wherdr 1.3.4 → 2.0.1

package/docs/machines.md

@@ -0,0 +1,74 @@
+# Machines and SSH
+
+[Documentation](README.md) · [Project](../README.md)
+
+- **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.
+## Several machines (SSH)
+
+wherdr also shows the agents of the **SSH machines registered in Herdr** — the ones the Herdr
+terminal client shows in its sidebar. It opens one SSH master connection per machine, forwards
+the remote Herdr socket through it, and reads transcripts and files over the same connection.
+
+Requirements on the remote machine: the **same Herdr version** (`herdr --version`), its server
+running, and key-based SSH access from the server. Example, on the server:
+
+```sh
+ssh-keygen -t ed25519 -f ~/.ssh/wherdr_ed25519 -N ''
+cat >> ~/.ssh/config <<'CFG'
+Host laptop
+  HostName laptop
+  User alice
+  IdentityFile ~/.ssh/wherdr_ed25519
+  IdentitiesOnly yes
+CFG
+ssh-copy-id -i ~/.ssh/wherdr_ed25519 laptop
+ssh laptop true                            # accept the host key once
+herdr machine add laptop --label Laptop    # see `herdr machine --help`
+```
+
+wherdr picks it up within 30 seconds; `herdr machine rename|disable|remove` work the same way.
+Machines can also be renamed from the app (machine menu → Options).
+With Herdr 0.9.2 or later, **Options → Connection status** checks the saved profile
+with `herdr machine status --json`: reachable, authentication required, error or disabled.
+It also gives a `herdr machine reconnect <profile-id>` command to run interactively
+on the wherdr host. **Retry connection** restarts wherdr's own SSH connection;
+Herdr's approved SSH connection and wherdr's connection are separate, so key-based
+SSH access is still required for wherdr. Older Herdr keeps automatic retries and
+manual **Retry connection**, without the native diagnostic.
+
+The terminal view uses `terminal.mouse` on Herdr 0.9.2+ (both CLI and server): clicks,
+touch taps, drags and movement are encoded by Herdr for the application's mouse mode.
+Use **Shift + drag** to select text, and Ctrl/⌘+click to open links. Older or unknown
+versions keep the existing terminal keyboard, selection and scrolling behavior.
+
+### Windows remote machines
+
+The wherdr host must support Unix sockets and OpenSSH multiplexing (for example,
+Linux/WSL or macOS). On the **remote Windows machine**, install Git Bash and set
+it as the OpenSSH server's default shell. In an elevated PowerShell:
+
+```powershell
+New-ItemProperty -Path 'HKLM:\SOFTWARE\OpenSSH' -Name DefaultShell -Value 'C:\Program Files\Git\bin\bash.exe' -PropertyType String -Force
+Restart-Service sshd
+```
+
+Reconnect SSH after changing the shell. Adjust the path if Git is installed
+elsewhere. wherdr's bootstrap and file commands require a POSIX shell; with
+cmd.exe or PowerShell as the default, they fail before Herdr is discovered.
+With `cmd.exe` as the default shell, the error comes back localized and can be
+unreadable (for example GBK-encoded Chinese). When the probe does not answer
+as a POSIX shell, wherdr shows “Remote SSH shell must support POSIX commands”
+and points to this section; the same hint covers other failures before the
+probe runs.
+
+Herdr must be available in this non-interactive shell (`ssh laptop 'command -v herdr'`) and its server must already be running. Windows remotes require Herdr
+0.9.3 or later with `remote-api-bridge` support.
+
+Since 2.0.0 (#144), wherdr reaches a Windows machine through a relay instead of
+`ssh -L` to the socket path, so Herdr sockets under `C:\…` work. It selects a stdio relay for
+socket paths containing a drive letter or backslashes, rather than putting the
+Windows path into `ssh -L`. It uses Herdr's native `remote-api-bridge` for API
+requests and `remote-client-bridge` for notifications, over the same SSH master.
+No additional relay program or TCP listening port is needed. Linux and macOS
+POSIX socket paths continue to use `ssh -L`.

package/docs/migrate-from-1.x-docker.md

@@ -0,0 +1,160 @@
+# Migrate a wherdr 1.x Docker install to wherdr 2.0
+
+wherdr 2.0.0 has no Docker image: it runs natively, as your user, so the herdr-projects Board can act.
+This guide moves a wherdr 1.x container to the native service. It keeps the port, the data
+folder (passkeys, push subscriptions, phone address, settings) and therefore the address your
+devices open.
+
+**For an AI agent.** The user can say "read this file and migrate me". Run the steps in order,
+on the machine where the `wherdr` container runs, as the user who runs Herdr (never with `sudo`
+unless a step says so). Every step ends with a **Check**. When a check fails, stop, do not run
+the next step, and report the output to the user. Run [Roll back](#roll-back) if the user asks,
+or if wherdr no longer answers after step 4. Ask the user before deleting anything; this guide never deletes.
+
+The 1.x in-app banner shows `docker compose pull && docker compose up -d` for 2.0. That
+command cannot reach 2.0: the `wherdr:latest` image on GHCR stays on the last 1.x release.
+Running it changes nothing. This guide is the way to 2.0.
+
+## 0. Collect the facts
+
+```sh
+docker inspect wherdr --format '{{.State.Status}} {{.Config.Image}}'
+OLD="$(docker inspect wherdr --format '{{ index .Config.Labels "com.docker.compose.project.working_dir" }}')"
+DATA_SRC="$(docker inspect wherdr --format '{{ range .Mounts }}{{ if eq .Destination "/data" }}{{ .Source }}{{ end }}{{ end }}')"
+PORT="$(docker inspect wherdr --format '{{ range .Config.Env }}{{ println . }}{{ end }}' | sed -n 's/^PORT=//p')"
+echo "OLD=$OLD DATA_SRC=$DATA_SRC PORT=${PORT:-7683}"
+curl -fsS "http://127.0.0.1:${PORT:-7683}/api/health"
+herdr --version
+grep -s WHERDR_MODE ~/wherdr/plugin.env
+```
+
+**Check:** the container exists (`running`), `OLD` and `DATA_SRC` are absolute paths, `DATA_SRC`
+holds files (`ls -la "$DATA_SRC"`), and the health answer says `"name":"wherdr"` with a `1.x`
+version. Herdr must be 0.9.1 or newer. Linux or macOS only.
+
+If the container has another name, use that name in every command. Keep `OLD`, `DATA_SRC` and
+`PORT` for the next steps; in a new shell, set them again with the same commands.
+If `~/wherdr/plugin.env` says `WHERDR_MODE=docker`, the Herdr plugin started this container: that is
+expected, the plugin switches to native at step 4.
+
+If the user also runs herdr-projects 0.2 (the Project panel, `TASKS.md`, threads), stop here
+and tell them. wherdr 2.0's Board needs herdr-projects 1.2.1 or later; they must follow
+[the herdr-projects migration guide](herdr-projects-1x.md) as well, or stay on wherdr 1.3.4.
+
+## 1. Back up
+
+```sh
+BACKUP=~/wherdr-docker-backup-$(date +%F-%H%M).tgz
+tar czf "$BACKUP" -C "$DATA_SRC" . && tar czf "$BACKUP.compose.tgz" -C "$OLD" $(cd "$OLD" && ls -A | grep -E '^(\.env|docker-compose.*\.ya?ml)$')
+docker inspect wherdr --format '{{.Image}}' > "$BACKUP.image"
+tar tzf "$BACKUP" | head; tar tzf "$BACKUP.compose.tgz"; cat "$BACKUP.image"
+```
+
+**Check:** the first archive lists the data files (for example `./auth.json`, `./push.json`), the
+second one lists `docker-compose.yml` (and `.env` when there is one), and the image file holds a
+`sha256:` id. That image stays on the machine for the way back: do not prune it.
+
+## 2. Keep the settings
+
+```sh
+cat "$OLD/.env" 2>/dev/null
+```
+
+Keep the lines the user set, which the native service reads too: `APP_URL`, `HOST_LABEL`,
+`HERDR_WEB_SESSION`, `HERDR_WEB_MACHINES`, `HERDR_WEB_SELF_HOSTS`, `HERDR_WEB_ALLOWED_HOSTS`,
+`WHERDR_TRUSTED_NETWORKS`, `WHERDR_UPDATE_CHECK`, `PASSKEY_USER`,
+`AGENT_KINDS`, `TZ`. Drop the container's own: `PORT` (it becomes `WHERDR_PORT` at step 4),
+`HOST_HOME`, `HOME`, `PUID`, `PGID`, `DATA_DIR`, `HERDR_BIN`, `WHERDR_IMAGE`,
+`WHERDR_DOCKER_LOOPBACK_ONLY`, `WHERDR_TASKS_FROM_FILES`, `HERDR_WEB_HOST_OPEN_*`.
+Show the user the kept lines before writing them at step 3.
+
+**Check:** the user agrees with the list (it may be empty).
+
+## 3. Stop the container and put the data in place
+
+```sh
+(cd "$OLD" && docker compose down)
+docker ps -a --filter name='^wherdr$' --format '{{.Names}}'
+curl -fsS --max-time 3 "http://127.0.0.1:${PORT:-7683}/api/health" || echo "port free"
+```
+
+**Check:** no container is listed and the last line says `port free`. `docker compose down`
+removes the container only; its folder, data and image stay.
+
+The native service reads `~/wherdr/data`. When `DATA_SRC` is already `~/wherdr/data` (installs
+made by the 1.x installer or plugin), leave it. Otherwise copy it; the command refuses when the
+target exists (then show the user what `~/wherdr/data` holds and ask):
+
+```sh
+mkdir -p ~/wherdr
+[ "$(cd "$DATA_SRC" && pwd -P)" = "$(cd ~/wherdr 2>/dev/null && pwd -P)/data" ] || { [ ! -e ~/wherdr/data ] && cp -a "$DATA_SRC" ~/wherdr/data; }
+find ~/wherdr/data ! -user "$(id -u)" | head
+```
+
+**Check:** `ls ~/wherdr/data` shows the same files as `DATA_SRC`, and `find` prints nothing. If it
+lists files owned by someone else (the container ran with another `PUID`), ask the user to run
+`sudo chown -R "$(id -un)" ~/wherdr/data`.
+
+Write the settings kept at step 2, one `KEY=VALUE` per line, in `~/wherdr/wherdr.env` (add them
+to the file if it exists; never overwrite other lines).
+
+## 4. Install the native service
+
+```sh
+curl -fsSL https://wherdr.dev/install | WHERDR_PORT="${PORT:-7683}" sh
+```
+
+The installer asks before installing Node.js 22 when it is missing; let the user answer
+(`WHERDR_YES=1` answers yes to everything). It installs the Herdr plugin into `~/wherdr`, starts
+wherdr on that port and installs its login service: `systemd --user` (`wherdr.service`) on Linux,
+a LaunchAgent (`dev.wherdr.plist`) on macOS. A plugin left in Docker mode says
+`switching this plugin to the native service`.
+
+**Check:** the installer ends without an error and prints the wherdr address.
+
+## 5. Verify
+
+```sh
+curl -fsS "http://127.0.0.1:${PORT:-7683}/api/health"
+grep -s WHERDR_MODE ~/wherdr/plugin.env || echo "no Docker mode"
+systemctl --user is-active wherdr 2>/dev/null || launchctl list 2>/dev/null | grep dev.wherdr
+docker ps -a --filter name='^wherdr$' --format '{{.Names}}'
+```
+
+**Check:** health says `"name":"wherdr"` with a `2.x` version; `no Docker mode`; the service is
+`active` (Linux) or listed (macOS); no container came back. If wherdr was reached over Tailscale,
+`tailscale serve status` still points to the same port.
+
+Then ask the user to open wherdr at the address they used before, on the phone and on each
+browser. It must unlock with the same passkey, and notifications must still arrive. Each browser
+copies its display settings to the server once, at its first visit (they are then shared).
+If something fails here, go to [Roll back](#roll-back).
+
+Leave the backup, the old compose folder and the image in place for a few days. Remove them later
+only when the user asks (`docker image rm <id from $BACKUP.image>`).
+
+## Roll back
+
+Back to the 1.x container, with the data as it is now:
+
+```sh
+herdr plugin disable afloury.wherdr
+systemctl --user disable --now wherdr 2>/dev/null || launchctl bootout "gui/$(id -u)/dev.wherdr" 2>/dev/null
+curl -fsS --max-time 3 "http://127.0.0.1:${PORT:-7683}/api/health" || echo "port free"
+```
+
+When the data was copied at step 3, copy back what changed since (skip this when `DATA_SRC` is
+`~/wherdr/data`): `cp -a ~/wherdr/data/. "$DATA_SRC/"`. To return to the data as it was before
+the migration instead, restore the backup: `tar xzf "$BACKUP" -C "$DATA_SRC"`.
+
+```sh
+(cd "$OLD" && docker compose up -d)
+curl -fsS "http://127.0.0.1:${PORT:-7683}/api/health"
+```
+
+**Check:** `port free` before starting, then health answers with the `1.x` version. If
+`docker compose up` pulls a different image, pin the saved one: `WHERDR_IMAGE=<id from $BACKUP.image>`
+in `"$OLD/.env"`, then run it again.
+
+To stop the 1.x banner from offering 2.0, set `WHERDR_UPDATE_CHECK=off` in `"$OLD/.env"` and run
+`docker compose up -d` again.

package/docs/networks.md

@@ -0,0 +1,154 @@
+# Phone access and private networks
+
+[Documentation](README.md) · [Project](../README.md)
+
+### Recommended: always-on server + Tailscale
+
+Your agents keep running when your laptop is closed, and you follow them from your phone.
+wherdr stays on your private network: it is **never published on the Internet**.
+
+**1. Herdr on the server.** Install [Herdr](https://herdr.dev) (≥ 0.9.1) and start it
+(`herdr` or `herdr server`), with the integrations of the agents you use
+(`herdr integration install claude|codex`).
+
+**2. wherdr.** Run [the one command](installation.md#the-one-command) on the server, as your user (over SSH, it
+prints the address and the phone steps instead of opening a browser). wherdr runs as a service
+that starts with the machine and keeps running when you log out.
+
+**3. Private HTTPS with Tailscale.** Install [Tailscale](https://tailscale.com) on the server,
+your phone and your computers, on the same tailnet, with
+[MagicDNS and HTTPS certificates](https://tailscale.com/kb/1153/enabling-https) enabled. Then,
+on the server:
+
+```sh
+tailscale serve --bg --https=7683 http://127.0.0.1:7683
+# → https://<machine>.<tailnet>.ts.net:7683/   (e.g. https://server.example.ts.net:7683/)
+```
+
+Tailscale Serve listens on HTTPS port 7683 of your tailnet name, with a valid certificate, and
+forwards to wherdr's local HTTP port. Only devices of your tailnet can reach it.
+
+**wherdr enables that address by itself**, on a server without a screen too: at startup, every
+30 seconds, and when an address it does not know yet is opened, it reads what `tailscale serve`
+publishes on this machine (the `tailscale` command) and adopts the HTTPS address that points to
+its own port (allowed host and `APP_URL`, saved in `data/app-url.json`; an HTTPS `APP_URL` in the
+environment or `~/wherdr/wherdr.env` wins). An address removed from `tailscale serve` is refused
+again. Nothing a request says can enable an address: only Tailscale's own state on the machine
+does, and an address that `tailscale funnel` opens to the Internet is never adopted.
+
+**Settings › Phone** on the server (`http://localhost:7683/#/settings?section=phone`) shows the
+state and the QR code and publishes wherdr itself: one button, asked first. From a terminal,
+**P** in the wherdr panel, `wherdr phone` (npm, Homebrew) or the [one command](installation.md#the-one-command)
+run again checks the same thing, and `curl -fsS http://127.0.0.1:7683/api/phone` prints the state
+as JSON.
+
+If the phone shows **"This address isn't enabled yet"** (403), the address it opened is not one
+`tailscale serve` publishes for wherdr's port on that machine: the page gives the command to run
+there.
+
+**Why HTTPS matters.** Browsers only allow three things on `https://` (or on `localhost` itself):
+
+- **installing the app** on the home screen (PWA) on iPhone and Android;
+- **push notifications** (on iOS, only in the installed app);
+- **passkeys** for the lock screen (Face ID, Touch ID, Windows Hello, Android).
+
+**4. On the phone:** open the address, [install the app](phone.md#install-it-as-an-app), then
+Settings → **Enable notifications**. **On the computer:** use the same address in a browser; the
+desktop layout can replace the Herdr terminal client for daily work.
+
+**5. Passkey lock** (optional): Settings → Security → **Enable passkey lock**. The
+first passkey asks for a bootstrap token, printed in the server log (`~/wherdr/wherdr.log`,
+**L** in the wherdr panel); it changes on each restart and is only needed for that first passkey. Add a passkey on each of
+your devices after that (see [New device](security.md#new-device)). Without one, every device of your
+tailnet can control your agents: enough when the tailnet is yours alone, a passkey adds a lock
+on each device when someone else shares the tailnet or your devices.
+
+**6. More machines** (optional): register your other computers in Herdr over SSH
+(`herdr machine add`, see [Several machines (SSH)](machines.md#several-machines-ssh)). Their agents show
+in wherdr in their own section, and everything works the same on them. The machine menu also has
+**Keep awake**, which stops a Mac (`caffeinate`) or a Linux machine (`systemd-inhibit`) from
+sleeping for an hour, four hours, the evening or until turned off.
+
+> [!CAUTION]
+> Never publish wherdr on the Internet: no port forwarding on your router, no public reverse
+> proxy, no ngrok, no `tailscale funnel`, no Cloudflare Tunnel without Cloudflare Access. Use
+> `tailscale serve`, which stays inside your tailnet. See [Security](security.md#security).
+
+### Other private networks
+
+Tailscale is the built-in path (one click in **Settings › Phone**), not a requirement. wherdr
+works with any private network that gives it an **HTTPS address with a valid certificate**:
+
+- **HTTPS with a certificate your phone trusts.** The installed app (PWA), push notifications
+  and passkeys only work on `https://`. A self-signed certificate or plain `http://` on your
+  LAN is not enough, and is never a supported way to reach wherdr.
+- **`APP_URL` set to that address** (the environment of `wherdr` / `npm start`), then restart wherdr. Its hostname is allowed automatically and it enables Web
+  Push. Add `HERDR_WEB_ALLOWED_HOSTS` only if you also open wherdr under another name. The
+  automatic adoption and the address check in **Settings › Phone** only know the `*.ts.net`
+  addresses of `tailscale serve`; an HTTPS `APP_URL` in the environment always wins.
+- **Never exposed without authentication.** wherdr keeps listening on `127.0.0.1`; only the
+  proxy listens on the private network. Turn on the passkey lock as soon as another device can
+  reach it.
+
+**Headscale, NetBird, ZeroTier, WireGuard: the same recipe.** Join the server and the phone to
+the network, give the server a DNS name that points to its **private** address, and put a reverse
+proxy in front of wherdr that listens on that private address only. Let's Encrypt cannot reach a
+private address, so the certificate comes from the
+[DNS challenge](https://caddyserver.com/docs/automatic-https#dns-challenge). With
+[Caddy](https://caddyserver.com) built with your DNS provider's
+[module](https://github.com/caddy-dns) (here [Cloudflare DNS](https://github.com/caddy-dns/cloudflare)),
+a `Caddyfile` like this ([`bind`](https://caddyserver.com/docs/caddyfile/directives/bind),
+[`tls`](https://caddyserver.com/docs/caddyfile/directives/tls)):
+
+```caddy
+wherdr.example.com {
+	bind 100.64.0.10                 # the server's address on the private network only
+	tls {
+		dns cloudflare {env.CF_API_TOKEN}
+	}
+	reverse_proxy 127.0.0.1:7683
+}
+```
+
+Point `wherdr.example.com` (an `A` record in your DNS zone) to that private address: from
+anywhere else it leads nowhere. Then set `APP_URL=https://wherdr.example.com/` and restart
+wherdr. Caddy is a relay on this computer ([Network access](security.md#network-access)): keep it bound to
+the private address and turn the passkey lock on. Caddy passes each client's address on: with
+Headscale or NetBird (`100.64.0.0/10`) wherdr accepts it as is; for another range (ZeroTier,
+WireGuard), also set `WHERDR_TRUSTED_NETWORKS` to it, such as `10.147.17.0/24`. To join each
+device:
+
+| Network | Join a device (official docs) | Server's private address |
+| --- | --- | --- |
+| [Headscale](https://headscale.net/stable/usage/getting-started/) | Tailscale clients: `tailscale up --login-server <YOUR_HEADSCALE_URL>` | `tailscale ip -4` |
+| [NetBird](https://docs.netbird.io/get-started/cli) | `netbird up` (`--management-url` when self-hosted) | `netbird status` |
+| [ZeroTier](https://docs.zerotier.com/start) | `zerotier-cli join <network ID>`, then authorize the device in the network's members | The members list of your network |
+| [WireGuard](https://www.wireguard.com/quickstart/) | `wg-quick up wg0` with a peer per device | The `Address` of the server's interface |
+
+Headscale does not support `tailscale serve` with HTTPS yet
+([features](https://headscale.net/stable/about/features/),
+[#1921](https://github.com/juanfont/headscale/issues/1921)): `tailscale cert` and Serve need
+certificates that only Tailscale's own control server provisions. Use the reverse proxy above
+instead of step 3.
+
+**Cloudflare Tunnel + Cloudflare Access: only with Access.**
+
+> [!WARNING]
+> A Cloudflare Tunnel puts wherdr **on the Internet**: anyone can reach its address, and
+> Cloudflare terminates TLS, so it sees all traffic. **Cloudflare Access is mandatory**, created
+> *before* the route: without it, whoever finds the address controls your agents. Keep the
+> passkey lock on as well. Prefer a private network when you can.
+
+1. In Cloudflare One, create the Access application first:
+   [Self-hosted and private › Add public hostname](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/self-hosted-public-app/)
+   `wherdr.example.com`, with an **Allow** policy for your own e-mail only (Access applications
+   deny everyone else by default).
+2. [Create a tunnel](https://developers.cloudflare.com/tunnel/setup/) and run `cloudflared` on the
+   server, then add a **published application** route: hostname `wherdr.example.com`, service
+   `http://localhost:7683`.
+3. Set `APP_URL=https://wherdr.example.com/` and `WHERDR_TRUSTED_NETWORKS=any` (the tunnel brings
+   clients from the Internet, which wherdr refuses otherwise; it then shows a warning), and
+   restart wherdr.
+
+Installing the app and notifications behind Access are not tested by the project: the phone must
+first sign in to Access in the browser.

package/docs/notifications.md

@@ -0,0 +1,83 @@
+# Notifications
+
+[Documentation](README.md) · [Project](../README.md)
+
+## Notifications
+
+With notifications enabled on a device, wherdr sends a Web Push when an agent goes from working
+to **blocked** (with its question and options) or to **done** (with the start of its answer).
+There is no push for the agent currently on screen.
+
+**Do not disturb** (top of Settings → Notifications) stops every push, for this device or for all
+devices, for 1 hour, until 8 am or until turned back on. The server applies it before sending and
+keeps it across restarts (`data/quiet.json` for all devices). While it is on, the agent list
+shows one line, “Notifications silenced until 08:00”, that opens these settings (a crossed-out bell
+under the counters when the list is collapsed); the header keeps its buttons as they are.
+
+wherdr also relays custom notifications sent with `herdr notification show` (plugins, scripts).
+To receive them it connects to Herdr's client socket as a **passive** client: it never becomes
+the foreground client and never resizes anything. Side effects: with wherdr connected,
+`notification show` reports `shown: true` even with no terminal attached, and an empty session
+gets a default workspace, as with any attached client.
+
+## A default and exceptions
+
+Settings → Notifications stores one policy, synchronized across devices
+(`notificationRules` in `settings.json`): **a default for everything, and
+exceptions to that default**. Every setting uses the same scale:
+
+| Level | Notifies for |
+|---|---|
+| **Muted** | nothing |
+| **Needs you** | a task or a coordinator waiting for you (questions, permission requests, board approvals) |
+| **Needs you + finished** | also a finished task, or a coordinator that finished answering you |
+| **All activity** | also every intermediate message and scheduled tasks |
+
+Under each level, **Customize** keeps the individual events (needs you, finished,
+new message, scheduled task) for edge cases.
+
+The screen reads top to bottom:
+
+1. **Do not disturb** turns off every notification, no exceptions: the default and
+   the exceptions are ignored while it is on.
+2. **Default (applies to everything)**: a level (needs you + finished at first)
+   and a **Sub-agents** switch. Off, only coordinators, standalone agents and board
+   events notify; on, task agents (workers, reviewers, planners, attempts) notify
+   too, at the same level. Sub-agents are all on or all off, never task by task.
+3. **Exceptions**: **Add an exception** picks a coordinator (main, machine or project
+   coordinator, grouped by machine) or a standalone agent conversation. Each one has
+   its own level, Customize and, for a coordinator, a Sub-agents switch: on, the task
+   agents of its board follow the exception instead of the default (a project
+   coordinator covers its project's tasks; the main and machine coordinators cover the
+   others). Each says how it differs from the default; removing one goes back to it.
+4. **This device's notifications** only asks this browser or phone for permission to
+   show push notifications, and shows whether it is allowed, blocked or not asked yet.
+
+A coordinator's exception is kept by its identity (machine, Herdr session, level and
+repo), not its pane: it still applies after `coordinator new` or a restart.
+
+Right-click → **Notifications** on a coordinator or a standalone agent sets that
+conversation's exception: the four levels (with a check mark on the current one, and
+whether it is an exception or the default), **Mute for 1 hour / 8 hours** (then back
+to what it was), and **Follow the default** to remove the exception. On a task agent,
+the menu points to the Sub-agents switch instead.
+
+Board events (`herdr-projects` approvals and failures) follow the default even with
+Sub-agents off, or their project coordinator's exception in the task's own Herdr
+session (the default when that session is not known: a task with no pane or space linked). Custom `herdr notification
+show` notices with a pane follow that conversation; others follow the default. Scripts
+can mark a scheduled notice with a `[scheduled]` title prefix. New assistant messages
+are identified by their transcript position, so streaming updates do not ring
+repeatedly.
+
+Settings saved by the earlier machine → project → conversation rules are converted
+once: a permanent machine rule becomes the default (so "Only main coordinators"
+becomes default Muted plus one exception), project rules are dropped, and
+conversation rules become exceptions (moved to the coordinator's identity when the
+conversation is a coordinator).
+
+An open conversation suppresses push to **every** device while the page is visible,
+focused and recently used (within two minutes). A WebSocket heartbeat renews a
+30-second lease every 10 seconds. Hiding, closing, losing the connection or leaving
+an idle tab stops renewing it; push resumes when the last lease expires. The global
+Do not disturb setting and notification deduplication still apply.

package/docs/overview.md

@@ -0,0 +1,71 @@
+# Overview and architecture
+
+[Documentation](README.md) · [Project](../README.md)
+
+<p align="center">
+  <img src="../server/assets/branding/icons/icon-512.png" alt="wherdr logo" width="120">
+</p>
+
+<h1 align="center">wherdr</h1>
+
+<p align="center"><b>Start your <a href="https://herdr.dev">Herdr</a> agents on your computer.
+Follow their work and answer from your phone.</b></p>
+
+<p align="center">Add it to your home screen like an app — no App Store needed.</p>
+
+<p align="center">
+  <a href="../assets/wherdr-launch.mp4"><img src="../assets/wherdr-launch.webp" width="720" alt="Animated wherdr launch film with real app captures: launch a Claude agent on desktop, continue the same conversation on a phone, approve its test request, then open project tasks and the Board."></a>
+</p>
+<p align="center"><sub>Start on PC. Stay in control from your phone. Real app, demo data. <a href="../assets/wherdr-launch.mp4">Watch the 15-second video</a>.</sub></p>
+
+<p align="center"><a href="https://wherdr.dev"><b>wherdr.dev</b></a> · <a href="quick-start.md#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>
+
+<p align="center"><a href="https://github.com/afloury/wherdr/actions/workflows/ci.yml"><img src="https://github.com/afloury/wherdr/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a></p>
+
+## Why wherdr
+
+- **Herdr's splits, live.** A tab with several panes is drawn in Herdr's real layout, every pane
+  live; drag a pane to move it or a divider to resize, and the change goes to Herdr itself.
+- **Private by default, passkey lock optional.** wherdr answers only its own computer and your
+  tailnet. Add a passkey if you like: Face ID, Touch ID, Windows Hello or Android unlock the app,
+  and nothing about your agents is served to a locked session.
+- **The agent's diff.** Git status and diff of each agent's working folder, one click away from
+  its conversation.
+- **The herdr-projects board.** Every machine's herdr-projects tasks in the board's own groups,
+  with replies to their agents, approval of finished work and a box for the Coordinator.
+- **Keyboard and global search.** One shortcut searches every agent and conversation; next
+  agent, new tab, pane swaps and `1`–`9` answers never need the mouse.
+- **Real time, and private.** The real terminal over a WebSocket, a push when an agent needs
+  you, and your phone through Tailscale: nothing is on the Internet.
+
+Details in [Features](home.md#features) and [Security](security.md#security).
+
+## How it works
+
+```
+phone / laptop ──private network──> HTTPS (tailscale serve, private proxy)
+                                        │
+                                        ▼
+                             wherdr (Nitro server, 127.0.0.1:7683)
+                               ├─ Herdr API socket     ~/.config/herdr/herdr.sock
+                               ├─ Herdr client socket  (notifications, passive client)
+                               ├─ herdr terminal session control <pane>   (terminal view)
+                               ├─ transcripts          ~/.claude, ~/.codex, ~/.omp (read only)
+                               └─ ssh -M <machine>     (other machines, optional)
+```
+
+wherdr runs on the same machine as the Herdr server (the "server" in these guides). 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/`. 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.
+
+## License
+
+[MIT](../LICENSE). The embedded font subsets keep their own licenses (`app/assets/fonts/`).

package/docs/phone.md

@@ -0,0 +1,26 @@
+# Install as an app
+
+[Documentation](README.md) · [Project](../README.md)
+
+## Install it as an app
+
+For phone access, first configure [private HTTPS](networks.md). For UI development, see the
+[iOS conventions](../CONTRIBUTING.md#conventions), including the iOS 26 status-bar pitfall.
+
+The app must be served over HTTPS (see [Requirements](installation.md#requirements)). Installed, wherdr opens
+in its own window, without the browser's bars.
+
+- **iPhone / iPad** (iOS 16.4 or later): open the address in **Safari** → Share →
+  **Add to Home Screen**. Open wherdr from the home screen, then Settings → **Enable
+  notifications**. On iOS, push notifications only work in the installed app.
+- **Android**: open the address in **Chrome** → menu → **Install app** (or Add to Home
+  screen), then Settings → **Enable notifications**.
+- **Mac, Safari** (macOS 14 Sonoma or later): File → **Add to Dock**.
+- **Chrome, Edge, Brave** (macOS, Windows, Linux): the install icon at the right of the address
+  bar, or menu → **Cast, save and share** → **Install page as app** (Edge: Apps → **Install
+  this site as an app**).
+- **Arc** cannot install web apps
+  ([Arc Help Center](https://resources.arc.net/hc/en-us/articles/25678978728983-Does-Arc-for-Desktop-Support-Progressive-Web-Apps)):
+  open the address in Safari or Chrome for that, or keep wherdr as an Arc favorite.
+
+Then Settings → Security → **Enable passkey lock** on each device.