wherdr 1.3.3 → 2.0.0

package/docs/devices.md

@@ -0,0 +1,58 @@
+# Computer, phone and iPad
+
+[Documentation](README.md) · [Project](../README.md)
+
+### 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. 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.
+  The sidebar can be resized, or collapsed to a narrow rail (search, new agent, settings and
+  state counters) with the button next to Settings; the choice is kept on the device.
+- **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, `H` the [Board](board.md#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.
+  - In an agent: `Mod+F` searches the conversation, ``Ctrl+` `` switches between conversation
+    and terminal, and `Esc` stops a working agent when the message field is empty.
+  - `Alt+Shift+arrows` swaps the current pane with its neighbour, `Ctrl/⌘+Alt+arrows` moves
+    focus to the neighbouring pane in a side-by-side tab, `Esc` closes dialogs, `Enter` sends
+    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.
+- **Board** for [herdr-projects](board.md#works-great-with-herdr-projects) 1.2.1 or later: every machine's
+  tasks in four columns (needs you, ready to approve, working, to do), done one tap away, each
+  task with its pull request, review, reply and approval.
+- **Settings** in a sidebar, with desktop-only options such as the content width.
+
+### On a phone
+
+- **Installable app (PWA)** on iPhone and Android, with safe-area and keyboard handling.
+- **Web Push notifications** when an agent finishes or needs you (with its question), and for
+  `herdr notification show` (plugins, scripts).
+- **Quick replies**: answer permissions and questions in one tap from the agent list.
+- **Split tabs on a small screen**: a plan of the tab's panes in Herdr's proportions, then each
+  pane full screen with a mini-map and swipe to its neighbours.
+- **Terminal key bar** (Esc, Enter, arrows, Shift+Tab, Ctrl+C…) and touch scrolling.
+- **Offline reading** of the last known state and of recently opened conversations.
+
+### On an iPad
+
+- **Computer layout in both orientations**: in portrait the agent list folds to a narrow column
+  and slides over the conversation; in landscape it stays docked. Buttons are 44 px, and the
+  layout does not change when the on-screen keyboard opens.
+- **Side by side by touch**: finger-sized pane buttons, grip and dividers; the active terminal
+  pane has the key bar; with the keyboard open the tab fits the visible area above it.
+- **Hardware keyboard**: Enter sends (Shift+Enter adds a line) once a key only a hardware
+  keyboard sends (arrows, Esc, a ⌘ chord) has been typed.

package/docs/files.md

@@ -0,0 +1,29 @@
+# Files and changes
+
+[Documentation](README.md) · [Project](../README.md)
+
+- **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.

package/docs/herdr-projects-1x.md

@@ -0,0 +1,278 @@
+# Moving from herdr-projects 0.2 to 1.x
+
+wherdr **2.0.0** reads herdr-projects **1.2.1 or later** only. wherdr 1.3.4 is the last version
+that reads herdr-projects 0.2 (its Project panel, `TASKS.md`, threads). This page moves one
+machine from 0.2 to 1.x, keeps a backup, and says how to go back. Do it on each machine that
+runs herdr-projects.
+
+wherdr 2.0 runs only **natively**, as a service of your user. A wherdr 1.x running in Docker
+moves first: [Migrate a 1.x Docker install](migrate-from-1.x-docker.md).
+
+herdr-projects 1.x is a different program, not a newer 0.2: one work board of tasks, each
+handed to an agent in its own space, reviewed when it finishes and merged on your yes. Your
+0.2 projects are **not converted**. 1.x sets them aside, whole, in `~/.herdr-projects-legacy`
+and never deletes them. Upstream describes what it does in
+[older installs](https://github.com/eliasstravik/herdr-projects/blob/main/docs/old-installs.md).
+
+## Before you start
+
+- Herdr 0.9.3 or later (`herdr --version`): the oldest Herdr herdr-projects 1.2.1 was checked on.
+- No 0.2 thread you still need running: finish or stop them first. 1.x asks the 0.2 ticker to
+  stop, and moves nothing while it still runs.
+- Note what each 0.2 project still had to do (its `TASKS.md`): you will tell the 1.x
+  Coordinator about it after the move.
+
+## 1. Back up
+
+1.x moves folders and edits a few files outside them (it backs those up itself, beside them,
+as `<file>.bak-herdr-projects`). Keep your own copy too:
+
+```sh
+cd ~ && if [ -s ~/herdr-projects-0.2-backup.path ]; then
+  echo "backup already made, kept: $(cat ~/herdr-projects-0.2-backup.path)"
+else
+  backup="$HOME/herdr-projects-0.2-backup-$(date +%Y%m%d-%H%M%S).tgz"
+  files=$(for p in .herdr-projects .config/herdr-projects .local/state/herdr/plugins/herdr-projects \
+    .config/herdr/config.toml .config/herdr/plugins.json; do [ -e "$p" ] && echo "$p"; done)
+  if ! printf '%s\n' "$files" | grep -q herdr-projects; then
+    echo "NO 0.2 FILES FOUND in $HOME: nothing backed up, check you are the user who runs Herdr"
+  elif [ ! -e "$backup" ] && printf '%s\n' "$files" | tar czf "$backup" -T - \
+    && tar tzf "$backup" > /dev/null; then
+    echo "$backup" > ~/herdr-projects-0.2-backup.path && echo "backup ok: $backup"
+    printf '%s\n' "$files" | grep -qx .config/herdr/config.toml \
+      || echo "no Herdr config.toml to keep: step 5 of Going back has nothing to restore"
+  else
+    echo "BACKUP FAILED: do not go on"
+  fi
+fi
+```
+
+Go on only after `backup ok` (or `backup already made`). The archive has a new name each time
+and is never overwritten. `~/herdr-projects-0.2-backup.path` keeps the path of the **first**
+one: running this again, for example after an install that stopped halfway, keeps that first
+backup instead of saving files 1.x has already changed. The steps of
+[Going back](#going-back-to-02) read the path from that file.
+
+The archive holds your whole projects (their libraries, uploads and thread records): expect
+hundreds of megabytes. Keep it, and its `.path` file, until you are sure you will not go back:
+it is the only full copy of Herdr's `config.toml` as it was (see
+[Going back](#going-back-to-02), step 5).
+
+## 2. Install herdr-projects 1.2.21
+
+```sh
+herdr plugin uninstall herdr-projects && herdr plugin install eliasstravik/herdr-projects --ref v1.2.21 --yes
+```
+
+Uninstalling removes only Herdr's copy of the plugin; your projects stay where they are.
+
+Then, in the Herdr terminal client, reload its config (`prefix` + `Shift` + `R`) and open the
+work board once (the plugin action **Open the work board**). Its first run sets the 0.2 files
+aside and says so in one line. Without an attached client, the same from a shell:
+
+```sh
+herdr server reload-config && herdr plugin action invoke open --plugin herdr-projects
+```
+
+Check where things stand:
+
+```sh
+~/.herdr-projects/data/bin/herdr-projects doctor
+```
+
+`doctor` lists what it took over and anything left to do (it exits with 1 when something needs
+you). Running it again changes nothing.
+
+What the first run changes, besides moving the 0.2 folders:
+
+- **`herdr-projects` leaves your PATH.** The link 0.2 had put there (`~/.local/bin/herdr-projects`)
+  is removed, and `doctor` reports it until you add 1.x's launcher folder to your PATH (in
+  `~/.profile` or your shell's start-up file):
+  `export PATH="$HOME/.herdr-projects/data/bin:$PATH"`.
+- **Herdr's config** loses 0.2's tab bar line, its key (`herdr-projects.open-popup`) and **both**
+  custom sidebar rows (agents and spaces): Herdr's own sidebar comes back. A
+  `[safety."~/.herdr-projects/<project>"]` section is left as it was, though that folder is now in
+  `~/.herdr-projects-legacy`: remove it or point it there.
+- **Agents' settings** (Claude, Codex…) lose only 0.2's `herdr-projects … hook --agent …` hooks.
+
+Do not run `herdr-projects update` on a machine that still had 0.2 before this step: install
+1.2.1 as above.
+
+## 3. Update wherdr
+
+Installing a new version does not change a wherdr that is already running: restart it too.
+
+- The installer (Herdr plugin, the recommended setup): `curl -fsSL https://wherdr.dev/install | sh`
+  again, or **U** in the **wherdr** panel. It fetches the GitHub release package directly, and
+  wherdr restarts on the new version.
+- npm: `npm install -g wherdr@latest && wherdr restart` (npm may hold a new release for up to two
+  days).
+- Homebrew: `brew upgrade wherdr && brew services restart wherdr`
+- A 1.x Docker install: there is no 2.0 image; move to the native service first
+  ([Migrate a 1.x Docker install](migrate-from-1.x-docker.md)).
+
+Check the version wherdr now serves in **Settings › About**: 2.0 or later. Still 1.3.4 means the
+old process is still running: restart it.
+
+Open **Settings › Plugins › herdr-projects**: each machine says **Installed · v1.2.21**. The
+**Board** (next to Settings) shows the tasks; write to the Coordinator in its box to add the
+work your 0.2 projects still had.
+
+## Push when a task needs you
+
+herdr-projects tells you when a task needs you, is ready to approve, or failed, through its
+`board.notify` setting: it can run a command for each event. Point it at Herdr's own
+notifications, which wherdr already sends to your phone. Run once on each machine with
+herdr-projects:
+
+```sh
+~/.herdr-projects/data/bin/herdr-projects set board.notify 'herdr notification show --body="$HERDR_PROJECTS_TITLE" --sound request -- "$HERDR_PROJECTS_ID · $HERDR_PROJECTS_EVENT"'
+```
+
+The push names the task and the event, and a tap opens the task on wherdr's Board. Back to
+none: `herdr-projects set board.notify none`. Settings › Plugins › herdr-projects shows the
+same command.
+
+## Going back to 0.2
+
+1. **Bring 1.x's agents to rest first**, so none keeps changing a repo while folders move.
+   Stopping the Coordinator is not enough: each task has its own agent (and its reviewer), and
+   machine and project coordinators are stopped apart. A Coordinator belongs to one Herdr
+   session while the plugin and its files are shared, so do this in each Herdr session where you
+   used 1.x's board.
+
+   ```sh
+   hp=~/.herdr-projects/data/bin/herdr-projects
+   $hp list --all --json      # every task, with its id and state
+   ```
+
+   Let each task that is working finish, or stop it with `$hp stop <id>`. Then stop the
+   coordinators you used:
+
+   ```sh
+   $hp coordinator stop                     # the Coordinator of this session
+   $hp coordinator --machine stop           # the machine coordinator
+   $hp coordinator --project <repo> stop    # each project coordinator (one per repo)
+   herdr agent list                         # every agent of this Herdr session and its status
+   ```
+
+   Go on when none of the agents 1.x started (its tasks' agents and reviewers, its coordinators)
+   is still working. Leave the agents you started yourself alone.
+
+2. **Take out 1.x's extras, then stop what still runs.** Herdr has no uninstall hook, so 1.x
+   cleans up outside its folders only when asked: its how-to files for agents, its blocks in
+   Herdr's config, and the herdr web UI's shared link if you pointed it at the board. Run this
+   while 1.x is still installed:
+
+   ```sh
+   ~/.herdr-projects/data/bin/herdr-projects remove-extras && echo "extras removed"
+   herdr plugin disable herdr-projects     # its hooks and its board key
+   ```
+
+   Go on only after `extras removed`. `disable` does not stop what already runs. Close the work
+   board's tab in Herdr: that ends the board, but its `keeper` and `keeper-work` keep running. List
+   your processes that name herdr-projects:
+
+   ```sh
+   ps -U "$(id -u)" -o pid=,args= | grep '[h]erdr-projects'
+   ```
+
+   This is a list to read, not a list to stop. Stop with `kill <pid>` only a line whose program
+   is 1.x's in **your** HOME: `~/.config/herdr/plugins/…/herdr-projects-…/bin/herdr-projects-<system>`
+   or `~/.herdr-projects/data/bin/herdr-projects`, such as its `keeper`, `keeper-work`, `board`
+   and page server. Leave any other line: another HOME or install, a 0.2 program
+   (`…/target/release/herdr-projects`), or a command that only mentions the name. Run the list
+   again: none of the processes you stopped may still be there.
+
+3. **Uninstall 1.x**: `herdr plugin uninstall herdr-projects`
+
+4. **Put the 0.2 folders back.** 1.x wrote down where it put each one in
+   `~/.herdr-projects/moved.json`: `~/.herdr-projects-legacy`, or `-legacy-2`, `-legacy-3`… when an
+   older one was already there. Do not guess the names: this lists them, then puts each folder back.
+   A folder already at the old place (1.x's own board, or a folder created since) is set aside
+   first, as `<name>.from-1x-1` (or the next free number), never moved inside it. Running it a
+   second time changes nothing.
+
+   ```sh
+   if [ ! -s ~/herdr-projects-restore.tsv ]; then
+   python3 - <<'PY' > ~/herdr-projects-restore.tsv.new && mv ~/herdr-projects-restore.tsv.new ~/herdr-projects-restore.tsv
+   import json, os
+   moved = json.load(open(os.path.expanduser('~/.herdr-projects/moved.json')))
+   for v in moved.get('legacy', {}).values():
+       print(v['from'] + '\t' + v['to'])
+   PY
+   fi
+   cat ~/herdr-projects-restore.tsv    # each line: old place <tab> where 1.x put it
+
+   restore() {
+     dest=$1 src=$2
+     [ -e "$src" ] || { echo "not found, skipped: $src"; return 0; }
+     if [ -e "$dest" ] || [ -L "$dest" ]; then
+       n=1; while [ -e "$dest.from-1x-$n" ] || [ -L "$dest.from-1x-$n" ]; do n=$((n + 1)); done
+       mv "$dest" "$dest.from-1x-$n" && echo "set aside: $dest -> $dest.from-1x-$n" || return 1
+     fi
+     mv "$src" "$dest" && echo "restored: $src -> $dest"
+   }
+   tab=$(printf '\t')
+   while IFS="$tab" read -r from to; do restore "$from" "$to" || break; done < ~/herdr-projects-restore.tsv
+   ```
+
+   1.x's own board is now in `~/.herdr-projects.from-1x-<n>`: keep it if you may come back to 1.x.
+
+5. Put back the files 1.x changed.
+   - **Herdr's config: restore it from your own backup** (step 1 of the move), not from
+     `config.toml.bak-herdr-projects`. 1.x rewrites that one file at each change it makes to
+     Herdr's config (adding its own key, then taking it out again on uninstall), so it only holds the
+     state before its last change, without 0.2's lines. If step 1 said there was no `config.toml`
+     to keep, skip this: 0.2 had none.
+
+     First take the file out of the archive, into a new private folder, and have Herdr check it.
+     Nothing is replaced yet:
+
+     ```sh
+     ok= && backup=$(cat ~/herdr-projects-0.2-backup.path) && tmp=$(mktemp -d) \
+       && tar xzf "$backup" -C "$tmp" .config/herdr/config.toml \
+       && [ -s "$tmp/.config/herdr/config.toml" ] \
+       && XDG_CONFIG_HOME="$tmp/.config" herdr config check \
+       && ok=1 && echo "checked: $tmp/.config/herdr/config.toml" || echo "STOP: nothing restored"
+     diff ~/.config/herdr/config.toml "$tmp/.config/herdr/config.toml"   # what the restore changes
+     ```
+
+     Only after `checked`, in the same shell, keep the current file beside it and restore:
+
+     ```sh
+     [ "$ok" = 1 ] && cp ~/.config/herdr/config.toml ~/.config/herdr/config.toml.before-0.2-restore \
+       && cp "$tmp/.config/herdr/config.toml" ~/.config/herdr/config.toml && herdr server reload-config
+     ```
+
+   - **Agents' settings** (Claude, Codex…): 1.x changes them once, so their
+     `<file>.bak-herdr-projects` is the file as it was before the move. Compare before restoring,
+     since the file may have changed since:
+     `diff ~/.claude/settings.json ~/.claude/settings.json.bak-herdr-projects`, then
+     `cp ~/.claude/settings.json.bak-herdr-projects ~/.claude/settings.json` (same for
+     `~/.codex/hooks.json` and the others `doctor` named).
+6. Reinstall 0.2 from the fork wherdr 1.3.4 installs, pinned to `v0.2.36`: the command is in
+   wherdr 1.3.4's README and in its **Settings › Plugins › herdr-projects**. `v0.2.36` exists only on
+   that fork: upstream's last 0.2 tag is `v0.2.35`, whose `herdr-projects update` would offer 1.x
+   again. The install puts the `herdr-projects` link back on your PATH.
+7. Go back to wherdr 1.3.4, and restart it:
+   - The installer (Herdr plugin): `curl -fsSL https://wherdr.dev/install | WHERDR_REF=v1.3.4 sh`
+     (wherdr restarts on that version).
+   - npm: `npm install -g wherdr@1.3.4 && wherdr restart`
+   - Homebrew installs only the newest version: for 1.3.4, `brew services stop wherdr && brew uninstall wherdr`,
+     then use npm as above.
+
+   **Settings › About** must say 1.3.4: 2.0 there means the old process still runs.
+
+If anything is missing, the backup from step 1 of the move has everything as it was:
+`cd ~ && tar xzf "$(cat ~/herdr-projects-0.2-backup.path)"` (with herdr-projects stopped).
+
+## Moving from Docker to the native service
+
+wherdr 2.0 has no Docker image: it runs only natively, as your user, where the Board can act.
+Published 1.x images stay on GHCR as they are, for those who stay on 1.x. The native service
+keeps the same port and the same data folder, so passkeys, notifications and the address your
+devices open keep working.
+
+Follow [Migrate a 1.x Docker install](migrate-from-1.x-docker.md): back up, stop the container,
+install the native service, check, and go back if needed. It is written so an AI agent can run it.

package/docs/home.md

@@ -0,0 +1,52 @@
+# Home and agent list
+
+[Documentation](README.md) · [Project](../README.md)
+
+## Features
+
+### Everywhere
+
+- **Home grouping**: Settings › Appearance › Home screen › **Group by** chooses **Machine**
+  (default, projects under their coordinator) or **State** (Needs you, Working, Ready merged
+  across online machines). State mode adds machine and project badges to flat cards; the
+  machine bar and its groups filter both modes. Compact/normal applies to both. In State mode,
+  a row of machine chips at the top opens each machine's menu (sessions, keep awake, board,
+  Claude quota setup), and offline or reconnecting machines stay on one line at the bottom.
+- **Live agent list**, one line per Herdr space, grouped by state (your turn, working, ready).
+  The list is normal by default; turn on Settings › Appearance › Home screen › **Compact list**
+  for one line per card (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. Board tasks use one line in
+  compact mode (agent, key, title, progress, duration, state and Your turn when needed); normal
+  mode adds the current activity and relevant limit or review labels on a second line. Task
+  details stay in the task sheet. A compact list turned on in 1.x goes back to normal once, on
+  the first 2.0 load; turning it on again is kept. Other agents
+  also use dense rows, with a last-answer preview in normal mode; waiting agents keep their
+  questions and one-tap answers in both modes.
+  With [herdr-projects](board.md#works-great-with-herdr-projects), the board's spaces follow Herdr's sidebar:
+  the Coordinators on top, then one group per repo, headed by its project coordinator (the repo's
+  name, the wherdr mark, **Coordinator** and its state), a bar that folds the group and sums up its
+  tasks (`4 TASKS · 1 YOUR TURN · 1 LIMIT`, the branch and `↓` commits behind its upstream, the
+  repo space's menu), then its tasks, indented (key, title, progress, time on it, the board's
+  current line). A remote coordinator link replaces the local coordinator above the bar.
+  Without a coordinator, the group starts with the bar; the repo terminal opens from its **…**
+  menu. Closing a space that holds task agents names the tasks it stops.
+- **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.
+- **Machine bar**: at the top of the list, “All”, then each machine with its state and count; a
+  tap shows one machine alone, without its header: its Claude and Codex quotas sit together at
+  the top, and an offline or reconnecting machine says so there. Right click (long press on a
+  phone) a machine's tab for its actions, those of its **…** menu; on a group's tab, for **Group
+  settings**. Settings › Appearance › Home screen › **Machine bar** orders its
+  items, takes some off it or hides it (saved on the server). A machine's **…** menu opens the
+  Board filtered on it (**Open the board**). In **Groups**, create a named selection of machines,
+  check its members and drag their handles to set their order. Groups appear after All by default,
+  with their combined task count and a group icon; order or hide them alongside the machines.
+  Choosing a group shows its members in the group's order. Groups follow you across devices.
+  Switching selections keeps the current conversation if it belongs there; otherwise the desktop
+  restores that selection's last conversation on this device, then its machine coordinator (a group's
+  first online machine), or the empty view. All always keeps the current conversation. Phones keep
+  the list first and check the same rule when reopening a conversation through browser history.
+  Explicit choices from search, cards or links open the chosen conversation. Unsent drafts stay saved.
+- **Named Herdr sessions**, **quotas** (remaining Claude and Codex usage limits), **Herdr plugin
+  actions** in the menus, **passkey lock** (Face ID, Touch ID, Windows Hello, Android…).

package/docs/installation.md

@@ -0,0 +1,174 @@
+# Installation and updates
+
+**Upgrading to 2.0.0?** Read the [release notes](release-notes-2.0.0.md) for breaking changes and the 1.x migration checklist.
+
+[Documentation](README.md) · [Project](../README.md)
+
+## Requirements
+
+- **Herdr ≥ 0.9.1** running on the server (`herdr` or `herdr server`), with its Claude Code /
+  Codex / omp integrations installed if you use them (`herdr integration install claude|codex|omp`).
+  omp's conversation is only found through its integration, which reports the session file.
+- **Linux or macOS** server with **Node.js 22** or newer (the installer offers to install it).
+  wherdr runs natively, as the user who runs Herdr.
+- **HTTPS** to use passkeys, push notifications and the installable app from another device.
+  Browsers only allow them on `https://` or `http://localhost`. The easiest way is
+  [`tailscale serve`](https://tailscale.com/kb/1312/serve); a reverse proxy **reachable only
+  from your private network** with a valid certificate also works (see
+  [Other private networks](networks.md#other-private-networks)).
+
+## Installation
+
+### 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:
+
+```sh
+curl -fsSL https://wherdr.dev/install | sh
+```
+
+The script ([read it first](https://wherdr.dev/install), source in
+[`website/public/install`](../website/public/install)) never uses sudo. It:
+
+1. checks **Herdr ≥ 0.9.1**; without it, it stops with the link to [herdr.dev](https://herdr.dev);
+2. leaves alone a wherdr that **already answers** on the port: a Herdr plugin install is offered
+   its update, anything else is left as it is;
+3. checks **Node.js 22** or newer (or Bun), in your `PATH` and in the folders of n, nvm, fnm,
+   Volta, asdf and Homebrew. Without it, it asks before installing it: `brew install node` on a
+   Mac with Homebrew, otherwise the official Node.js 22 build from nodejs.org, its checksum
+   checked, unpacked in `~/wherdr/node` (used by wherdr only: your `PATH` is not changed). With
+   musl libc (Alpine) it gives the install links instead;
+4. runs `herdr plugin install afloury/wherdr --yes`: the [Herdr plugin](plugins.md#install-as-a-herdr-plugin)
+   downloads the GitHub release package of its version (checksum checked, no wait for npm),
+   installs it in `~/wherdr/app`, starts it on `http://localhost:7683`, opens the setup guide in
+   your browser (first install) and binds **prefix+i** to its panel;
+5. configures automatic startup with `wherdr service install`: **at login on macOS** with a
+   LaunchAgent; **at boot on Linux when lingering is enabled**, otherwise **at login**, with a
+   `systemd --user` unit. It tries to enable lingering (`loginctl enable-linger`, allowed for
+   your own user without sudo on most systems), which also keeps wherdr running after logout.
+   Without lingering, wherdr stops after logout. The installer checks lingering after installation
+   and reports which case applies, or says when it cannot verify it. The service gets
+   your login shell's `PATH`, so the agents you installed in `~/.local/bin`, `~/.bun/bin`,
+   `~/.cargo/bin`, `~/.npm-global/bin` or Homebrew are found (see [Agent PATH](installation.md#agent-path)). Each
+   run installs it again, with the `PATH` of now. If this step fails (no systemd), nothing of it
+   is left, wherdr is started again and keeps starting with Herdr, and the script says how to
+   retry;
+6. on a computer **without a screen** (no `DISPLAY` on Linux, or an SSH session): opens nothing,
+   prints the local address, an `ssh -L` tunnel to reach it from your computer, and the phone
+   steps (`wherdr phone`: Tailscale state, the address, the QR code once it answers). Run the
+   command again at any time to check the phone address.
+
+Settings, as environment variables (`curl -fsSL https://wherdr.dev/install | WHERDR_PORT=7684 sh`):
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `WHERDR_DIR` | `~/wherdr` | Install folder (plugin settings, data, log). |
+| `WHERDR_PORT` | `7683` | Local port. |
+| `WHERDR_SERVICE` | — | `off`: no login service; wherdr then starts with Herdr only (the plugin's startup hook). |
+| `WHERDR_YES` | — | `1` answers yes to every question (non-interactive use), installing Node.js included. |
+| `WHERDR_NO_BROWSER` | — | `1` never opens a browser. |
+| `WHERDR_REF` | main | Git tag or branch of the plugin. |
+| `WHERDR_PLUGIN` | `afloury/wherdr` | A local checkout to link and build instead (development, tests). |
+
+Update: run the command again (it offers the update), **U** in the wherdr panel, or **Update** in
+the app: all three fetch the GitHub release package directly.
+
+#### Agent PATH
+
+systemd and launchd start services with a short system `PATH`, and herdr-projects, run by
+wherdr for the Board, then reports `claude is not installed here` for an agent installed in a
+user folder. wherdr gives it the `PATH` an interactive login shell would have, on the host and
+over SSH, in this order: the `PATH` your login shell gives (asked once by `wherdr service
+install`), the one herdr-projects records in `~/.herdr-projects/data/env.json`
+(`$HERDR_PROJECTS_DATA_DIR`, or `$HERDR_PROJECTS_HOME/data`), then `~/.local/bin`, `~/.bun/bin`,
+`~/.cargo/bin`, `~/.npm-global/bin`, `~/.deno/bin`, `~/.volta/bin`, `~/bin`, Homebrew's folders and
+`/usr/local/bin` when they exist, then the `PATH` it was started with and the system folders. Your
+own folders come before the system ones, as in your shell: an old system-wide copy of an agent
+never wins over yours. After installing
+an agent somewhere else, run `wherdr service install` again (or the one command).
+
+### Which setup?
+
+| | **Always-on server + Tailscale** (recommended) | **One computer** |
+| --- | --- | --- |
+| Runs on | A machine that never sleeps: Raspberry Pi, mini-PC, home server, private VPS (Linux) | The computer you work on (macOS or Linux) |
+| Reach it from | Your phone and every computer on your tailnet | That computer only (`http://localhost:7683`) |
+| Installable app, push notifications, passkeys | Yes (private HTTPS from `tailscale serve`) | Desktop browser only; no phone access |
+| Other machines (a Mac, a laptop…) | Added in Herdr over SSH, shown in wherdr | Also possible, but they are only reachable while this computer is awake |
+
+Both use [the one command](installation.md#the-one-command) and the same app. You can start with the second one
+and move to the first later.
+
+### Moving from Docker to the native service
+
+wherdr 2.0 runs only natively as your user. Published 1.x images remain on GHCR for users
+staying on 1.x. To keep your port, passkeys and settings when moving, follow the
+[Docker migration guide](migrate-from-1.x-docker.md): verifiable steps, with a way back,
+that you can also hand to an AI agent ("read this file and migrate me").
+
+## Updating
+
+wherdr checks the latest GitHub release at most once a day (an anonymous request to
+`api.github.com`, nothing is sent) and shows a small **“wherdr X.Y.Z is available”** banner on the
+home screen and in Settings › About, with the release notes and the exact command for your setup.
+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) 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](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, on every device that can
+open wherdr (this computer and your tailnet; unlocked, when a passkey is set). wherdr installs the new version in a
+process of its own, restarts, and checks that `/api/health` reports the new version within 60
+seconds; the app shows the progress and reloads on the new version. If the new version does not
+answer, wherdr goes back to the previous one by itself (the plugin keeps the previous copy in
+`~/wherdr/app.prev`, npm reinstalls the previous version, Homebrew points back to the previous keg)
+and the app says so. Every step is logged in `~/wherdr/update.log`.
+
+| Setup | What Update does |
+| --- | --- |
+| The one command / Herdr plugin, Node.js | Verifies and unpacks the GitHub release package of the new version into `~/wherdr/app`, keeps the old copy, restarts (the login service included) |
+| `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` |
+
+`npx wherdr` runs from a temporary folder: run `npx wherdr@latest` again.
+
+| Setup | Update command (in the wherdr folder) |
+| --- | --- |
+| The one command | Run `curl -fsSL https://wherdr.dev/install \| sh` again: it offers the update (GitHub release package) |
+| Herdr plugin, Node.js | **U** in the **wherdr** panel, or `herdr plugin install afloury/wherdr --yes` (wherdr restarts on the new version) |
+| `wherdr` command (npm) | `npm install -g wherdr@latest && wherdr restart` (npx: stop it, then `npx wherdr@latest`) |
+| `wherdr` command (Homebrew) | `brew upgrade wherdr`, then `brew services restart wherdr` |
+| From source | `git pull && npm ci && npm run build`, then restart wherdr |