wherdr 1.3.3 → 2.0.0

package/docs/plugins.md

@@ -0,0 +1,109 @@
+# Herdr plugins
+
+[Documentation](README.md) · [Project](../README.md)
+
+### Install as a Herdr plugin
+
+This is what [the one command](installation.md#the-one-command) installs; you can also run it yourself, on Linux
+and macOS, with Herdr ≥ 0.9.1 (no checks for Herdr or Node.js first). In three lines:
+
+1. Run `herdr plugin install afloury/wherdr`: it installs wherdr, starts it
+   (`✓ wherdr is running → http://localhost:7683`) and, at the first install on a computer with a
+   screen, opens the setup guide in your browser (`open` on macOS, `xdg-open` on Linux with a
+   display; a headless server, or `WHERDR_NO_BROWSER=1` in the environment of the install, just
+   prints `http://localhost:7683/#/setup`). Updates open nothing.
+2. In Herdr, press **prefix+i** (`ctrl+b` then `i` with the default prefix): the **wherdr** panel,
+   with the state, **O** Open wherdr and **P** Set up my phone. The install prints the key it
+   chose (see [Panel key](plugins.md#panel-key)).
+3. **P** opens Settings › Phone in the browser: **Make wherdr reachable from my phone** publishes
+   it on your tailnet, then the QR code shows once the address answers. Scan it with the iPhone,
+   then Share → Add to Home Screen.
+
+Herdr shows the manifest and the commands it will run, then the plugin installs wherdr in
+`~/wherdr` and starts it, unless something already answers on the port. If wherdr cannot start,
+the install still succeeds and says why; press **S** in the panel once it is fixed. It runs
+wherdr natively:
+
+- **Node.js 22**, on Linux and macOS: 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
+  from there (detached, or by the login service), 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 ([the one command](installation.md#the-one-command) offers to install Node.js).
+The **wherdr** panel (a Herdr popup) shows ● running / ○ stopped, the local address, the phone
+address (with its QR code once it answers), and two main keys: **O** Open wherdr, **P** Set up my
+phone (Settings › Phone in the browser). The other keys stay as a fallback: **S** start, **X**
+stop, **R** restart, **L** log (Ctrl+C to go back), **U** update (reinstalls the plugin), **A** auto-start at login on/off, **Q** quit.
+
+#### Panel key
+
+Herdr plugins have no menu of their own: an action runs from a key or from the command line. The
+install therefore appends one marked block to Herdr's `config.toml` (`HERDR_CONFIG_PATH`, or
+`~/.config/herdr/config.toml`):
+
+```toml
+# wherdr: key that opens the wherdr panel (remove this block to unbind it)
+[[keys.command]]
+key = "prefix+i"
+type = "plugin_action"
+command = "afloury.wherdr.panel"
+description = "wherdr"
+# end wherdr
+```
+
+It takes the first key of `prefix+i`, `prefix+u`, `prefix+y`, `prefix+m`, `prefix+alt+w` that
+neither Herdr's default keymap nor your config already binds, and prints
+`Press prefix+i in Herdr to open the wherdr panel.` Your own lines are never changed. Nothing is
+added when a key already runs the panel, when every candidate is taken, or when
+`herdr config check` would reject the result. The install then runs `herdr server reload-config`:
+keys apply without restarting Herdr. Pick another key by editing the block, or bind the panel
+yourself (`command = "afloury.wherdr.panel"`) before installing.
+
+Without a key: `herdr plugin action invoke panel --plugin afloury.wherdr`. The plugin's actions:
+
+| Action | What it does |
+|---|---|
+| `panel` | The **wherdr** panel (a popup) |
+| `open` | Opens wherdr in the browser (its tailnet address when published and answering) |
+
+Up to 1.2.0 the panel action was called `wherdr`: change a key bound to `afloury.wherdr.wherdr` to
+`afloury.wherdr.panel` (Herdr has no action aliases; the install warns about such a key and
+leaves it alone). Remove the block with `sh scripts/herdr-plugin.sh key uninstall` in the plugin
+folder (`~/.config/herdr/plugins/github/wherdr-…`), or delete the lines from `# wherdr:` to `# end wherdr`.
+
+Auto-start: the plugin's startup hook starts wherdr each time the Herdr server starts, when
+nothing answers on the port yet. [The one command](installation.md#the-one-command) also installs a login
+service (a LaunchAgent on macOS, a `systemd --user` unit with lingering on Linux, pointing at
+`~/wherdr/app` with the absolute path of the runtime and your [PATH](installation.md#agent-path)): wherdr then
+runs from boot and is restarted if it crashes. Key **A** in the panel turns it on or off;
+`herdr plugin install` alone does not add it, since it changes your login session.
+
+Herdr runs the plugin's commands with the environment of its server, whose `PATH` often lacks the
+folders of version managers (n, nvm, fnm, Volta, asdf). The install therefore saves the absolute
+path of the runtime in `~/wherdr/plugin.env` (`WHERDR_RUNTIME=/path/to/node`); if that binary
+disappears, **Start** looks in the usual places (`~/.n/bin`, `~/.nvm`, `~/.volta/bin`, fnm,
+`~/.asdf/shims`, Homebrew, `/usr/local/bin`, `~/.bun/bin`) and saves what it finds. Set
+`WHERDR_RUNTIME` there by hand for anything else. **Start** only reports success once the
+process is alive and the port answers; otherwise it prints the last lines of `wherdr.log`.
+
+When something already answers on the port (a wherdr started with systemd or by hand),
+the plugin starts nothing and never stops it: **Stop** only stops what the plugin started. The
+output of the install and of the startup hook is in the plugin logs:
+`herdr plugin log list --plugin afloury.wherdr`.
+
+**Uninstall.** Herdr has no uninstall hook, so remove wherdr in this order: in the panel, **A**
+(if the login service is on) and **X**; in the plugin folder, `sh scripts/herdr-plugin.sh key
+uninstall` (the panel key) and `sh scripts/herdr-plugin.sh skill uninstall`; then
+`herdr plugin uninstall afloury.wherdr && rm -rf ~/wherdr` (`~/wherdr/data` holds your passkeys
+and push keys).
+
+## Herdr plugins
+
+Actions declared by the plugins installed on a machine (`herdr plugin install|link`) appear in
+the menus: workspace / tab / pane actions in the agent menu, global actions in the machine menu.
+wherdr always passes the agent's pane explicitly. It asks for confirmation before running an
+action, except for actions that only show or check something (list, show, status, doctor…).
+Actions that open a plugin pane or popup open it in the attached Herdr terminal client, not on the
+phone: the menu marks them **Opens in Herdr**. wherdr's own plugin actions (its panel, open in the
+browser) are not listed. With a single machine, the machine's actions are in the **…** menu of
+its session row, under the agent list header.

package/docs/quick-start.md

@@ -0,0 +1,89 @@
+# First launch
+
+[Documentation](README.md) · [Project](../README.md)
+
+## Quick start
+
+### 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
+```
+
+It installs the wherdr [Herdr plugin](plugins.md#install-as-a-herdr-plugin) with the verified package of the
+GitHub release, runs wherdr natively as your user on `http://localhost:7683`, starts it at every
+boot (a `systemd --user` service with lingering on Linux, a LaunchAgent on macOS) and opens its
+setup guide in your browser; then **prefix+i** in Herdr opens the wherdr panel. Without Herdr, it
+says where to get it; without Node.js 22, it offers to install it (Homebrew, or the official
+build in `~/wherdr/node`, no sudo). On a server without a screen (or over SSH), it prints the
+address and the phone steps instead. See [The one command](installation.md#the-one-command).
+
+**wherdr 2.0 runs only natively**, as your user, so it can act on the
+[herdr-projects Board](board.md#works-great-with-herdr-projects) (Coordinator, reply, start, stop,
+approve). Other ways, after it: `herdr plugin install afloury/wherdr` (the same plugin, without
+the checks), and [the `wherdr` command](command.md#the-wherdr-command) from npm or Homebrew (npm can hold a
+new release for up to two days; the installer gets it from GitHub at once).
+
+At first launch, wherdr opens a **setup guide**: the Herdr agents it found, your phone
+(Tailscale), then the passkey lock and notifications. Skip it any time; finishing or skipping is
+saved on the server (`data/onboarding.json`), so your other devices do not show it again. Reopen
+it from Settings › About › **Setup guide**. On a phone that already opens wherdr through its
+tailnet address, the phone step becomes Add to Home Screen.
+
+**Passkeys are tied to the address they are created on.** Once wherdr's tailnet address is
+published and answers, the guide opened on `localhost` shows **Continue on
+<machine>.<tailnet>.ts.net**, which reopens it at the same step on that address, and its Security
+step (like Settings › Security) sends the passkey lock there. Nothing redirects on its own:
+`localhost` stays valid on the computer. The installer, the Herdr plugin and `wherdr open` open
+that address too when it is already published.
+
+wherdr is a small self-hosted web app that talks to the Herdr server on your machine. **On a
+computer**, it can replace the Herdr terminal client day to day: your spaces, tabs and split panes
+side by side, live conversations and real terminals, drag-and-drop layout, keyboard shortcuts
+and a task board for herdr-projects. **On a phone**, installed as a PWA, it is the companion
+that follows your agents when you are away: push notifications when an agent finishes or needs
+you, one-tap answers, quick replies and offline reading.
+
+It lists your agents live — Claude Code, Codex and the other agents Herdr recognizes — and works
+on the same Herdr session `herdr` attaches to: nothing is copied, nothing runs in the cloud. Use
+it on `localhost`, or from your other devices over Tailscale.
+
+> [!WARNING]
+> **wherdr is a remote shell on your machine.** Anyone who can reach it can start agents and
+> run commands as your user. **Never expose it on the public Internet** (no port forwarding, no
+> public reverse proxy, no tunnel). Use it on `localhost`, or from your other devices through a
+> private network such as [Tailscale](https://tailscale.com). wherdr refuses any other network
+> by itself; the passkey lock is an optional extra. See [Security](security.md#security).
+
+<p align="center">
+  <img src="screenshots/desktop.png" alt="wherdr on a computer: compact agent list with a project and its tasks, and a task's conversation waiting for an approval" width="900">
+</p>
+<p align="center"><sub>On a computer</sub></p>
+<br>
+<p align="center">
+  <img src="screenshots/board.png" alt="The Board: tasks of each project in Needs you, Ready to approve, Working and To do columns" width="900">
+</p>
+<p align="center"><sub>The Board: every task of every project, with <a href="board.md#works-great-with-herdr-projects">herdr-projects</a></sub></p>
+<br>
+<p align="center">
+  <img src="screenshots/home-phone.png" alt="Compact agent list on a phone: a project coordinator and its tasks" width="340">
+  &nbsp;&nbsp;&nbsp;&nbsp;
+  <img src="screenshots/chat-phone.png" alt="A task's conversation on a phone, waiting for an approval" width="340">
+</p>
+<p align="center"><sub>On a phone: the same agents, the same session.</sub></p>
+
+*Unofficial project. Not affiliated with or endorsed by Herdr, Anthropic or OpenAI. Claude,
+Claude Code, Codex and other product names are trademarks of their respective owners.*

package/docs/quotas.md

@@ -0,0 +1,65 @@
+# Claude and Codex quotas
+
+[Documentation](README.md) · [Project](../README.md)
+
+- **Codex updates and limits**: in a Codex conversation, a new Codex version shows above the
+  field with an **Update** button (runs Codex's official update command on that machine, after
+  confirmation), then **Restart to update** on the same conversation. When wherdr cannot run it
+  (read-only home), Update exits Codex, runs the command in the agent's own terminal and
+  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.
+  Messages sent meanwhile 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.
+## Claude and Codex quotas
+
+The home screen shows what is left of the Claude and Codex usage limits (5-hour window and
+week, with reset times), for every online machine.
+
+- **Codex**: nothing to do, Codex writes its limits in its session files. Machines on different
+  Codex accounts get one block each (told apart by a short hash of the account ID found in the
+  session files; `~/.codex/auth.json` is never read).
+- **Claude Code** only gives them to its status line. On each machine, install wherdr's
+  invisible status line (it displays nothing, and chains to your existing status line if you
+  have one):
+
+  ```sh
+  sh scripts/install-claude-statusline.sh
+  ```
+
+  The app offers the same thing in **Settings › Agents › Claude quotas**: each machine with
+  Claude, its state (set up, installed, update available, not set up), **Install** or **Update**
+  (runs it over SSH on a remote machine) and **Copy command**. The setup guide has it as an
+  optional **Quotas** step, and the home list only adds **Set up Claude quotas** and **Don’t
+  suggest again** to the machine's **…** menu, never a banner. Skipped or declined, it is no
+  longer suggested on any device (`data/claude-quotas.json`); Settings still offers it. A machine
+  whose quotas show from an older status line reads **Update available**, never "not set up".
+  Quotas show after the next exchange with a Claude agent. The status line stores the limits in `~/.cache/herdr-web/claude-status.json`
+  and a short hash of the account ID (never a token or email) to tell accounts apart. The hash
+  and observation time are stored together with the limits in one atomic snapshot, so a
+  new login takes effect on the next status-line update. Machines sharing a known account
+  use its newest snapshot; an unknown identity never overrides a known account. A failed
+  Claude read is retried once;
+  if both attempts fail, its previous identity is not reused. This prevents an old
+  successful reading from masking a newer file indefinitely during SSH failures.
+  Failed attempts are logged with the machine key and error code, without account data.
+  After upgrading from the older status
+  line, rerun the install command on each machine (or use **Install**) and exchange a message
+  with Claude to produce the new snapshot. The status line also requires `python3` in Claude’s
+  `PATH` at runtime.
+
+  **New machine**: run `sh scripts/install-claude-statusline.sh` on it once (or **Install** in
+  Settings › Agents › Claude quotas), then send a message to any Claude agent there; its quotas
+  appear on the home screen.

package/docs/release-notes-2.0.0.md

@@ -0,0 +1,84 @@
+# wherdr 2.0.0
+
+A major upgrade from **1.3.4**, with the new work board and a native service.
+
+> **Upgrading from 1.x? Back up first and read the Update section below.**
+> wherdr 2.0 has no Docker image: on a 1.x Docker install, the suggested `docker compose pull`
+> keeps 1.3.4. Follow the [Docker migration guide](https://github.com/afloury/wherdr/blob/v2.0.0/docs/migrate-from-1.x-docker.md) instead.
+
+## New
+
+Notifications use one default level and coordinator or agent exceptions, with a separate
+sub-agent switch (#157). Task panels include read-only effective settings and their
+provenance (#163). Start offers a model and effort for this run (#165); task keys can
+be copied with a click or tap (#168). Tasks stopped at a limit offer Continue or a
+higher limit (#167). Remote coordinator links select their machine (#169), and
+restarting an agent keeps its terminal closed (#164).
+
+The new Board works with herdr-projects 1.2.1 or later across your machines: create,
+start, queue, stop, retry, approve and archive tasks, set dependencies, and talk to
+project coordinators. Task panels bring together the conversation, terminal, review,
+progress and actionable failures. Done is hidden by default and can be shown again.
+
+Display settings follow you across devices through the server's `settings.json`,
+including themes, machine groups, home list options, Board grouping and file browser
+preferences. Changes reach connected devices immediately; offline changes are retried.
+
+## Improved
+
+The home screen starts with the normal, two-line task list. Machine groups and grouping
+by state help you follow work across machines. The one-line Needs you banner offers
+answers or permission actions and takes you to the question in the conversation.
+The iPad layout stays stable with the keyboard open and has larger touch controls.
+Files support formatted Markdown and video previews, and terminal mouse input uses
+Herdr's structured events on supported versions. Slash commands include plugin skills
+and MCP prompts. New can open or create a project coordinator.
+
+Task logos distinguish workers, reviewers and fallbacks. Machine and group tabs restore
+their last conversation, and task banners can send failed reviews back to the agent.
+The bundled herdr-projects installer targets 1.2.21, while the Board still reads 1.2.1 or later.
+
+The shorter README links to focused documentation pages. Startup instructions now
+state the actual behavior: at login on macOS, at boot on Linux with lingering enabled,
+otherwise at login. The installer reports which applies.
+
+## Fixed
+
+Messages removed from Claude's queue are reported as not sent with Retry. Messages
+waiting behind a terminal menu explain why and offer Close menu or Send anyway.
+Drafts follow an agent when its pane is replaced, rewritten transcripts reload correctly,
+and Claude quota snapshots keep the account and observation together. Remote SSH
+connections recover when an old connection leaves its control socket unusable.
+Agent terminal copies (OSC 52) reach the browser clipboard when Herdr forwards them,
+with a tap-to-copy fallback when a browser requires a gesture.
+
+## Update
+
+**This is a major upgrade from 1.x. Back up before updating.**
+
+1. Back up wherdr's data directory and any herdr-projects 0.2 projects. Follow the
+   [herdr-projects migration guide](https://github.com/afloury/wherdr/blob/v2.0.0/docs/herdr-projects-1x.md) (#152) before running upstream 1.x:
+   it is a different program, and its first run moves the old directory aside.
+   wherdr 2.0.0 requires herdr-projects **1.2.1 or later** for the Board. The old Project
+   panel, TASKS.md, threads, inbox and routines integration are removed. Stay on
+   wherdr **1.3.4** if you still need herdr-projects 0.2.
+2. **Docker is removed.** Move to the native service with the
+   [Docker migration guide](https://github.com/afloury/wherdr/blob/v2.0.0/docs/migrate-from-1.x-docker.md), keeping your port and data. You can hand that
+   guide to an AI agent: it lists checkable steps and the way back. The plugin switches its old Docker mode to native on
+   update and points to that guide. Existing 1.x images remain on GHCR for 1.x users.
+3. Once 2.0.0 is published, update the native Herdr plugin with **U** in its panel or
+   rerun the installer. For npm, run `npm install -g wherdr@2.0.0 && wherdr restart`;
+   for Homebrew, run `brew upgrade wherdr && brew services restart wherdr`.
+   Requirements remain Linux or macOS, Node.js 22 or newer, and Herdr 0.9.1 or newer
+   (the herdr-projects migration guide uses Herdr 0.9.3 or newer).
+4. Open each browser once. Its display settings fill only missing server keys; existing
+   server values win. After that, shared settings belong to the server. Keep
+   `DATA_DIR/settings.json` in your backups. Language, screen and terminal sizing,
+   drafts, notifications and authentication remain device-specific.
+5. Compact list from 1.x resets to Normal once. If you prefer Compact, turn it on again
+   in Settings; that choice follows you to other devices. Check Settings and the Board
+   after updating. The migration guide also documents rollback.
+
+PRs #153, #154, #155 and #71 are deferred to 2.0.1.
+
+[Full changelog](https://github.com/afloury/wherdr/blob/v2.0.0/CHANGELOG.md)

package/docs/security.md

@@ -0,0 +1,117 @@
+# Security
+
+[Documentation](README.md) · [Project](../README.md)
+
+## Security
+
+wherdr drives Herdr, so **it can run anything as your user**.
+
+- It listens on `127.0.0.1` only. Reach it from other devices **only through a private
+  network** (Tailscale or [equivalent](networks.md#other-private-networks)). Never add a public route
+  (port forwarding, public reverse proxy, ngrok…); the only exception is a Cloudflare Tunnel
+  behind Cloudflare Access, with its risks (it needs `WHERDR_TRUSTED_NETWORKS=any`).
+- It answers only this computer and the tailnet: see [Network access](security.md#network-access).
+- Requests are accepted only for `localhost`, loopback addresses, the runtime's hostname, the
+  hostname in `APP_URL`, the tailnet name `tailscale serve` publishes for wherdr's own port
+  (read from Tailscale on the machine, never from a request, and only while it is published),
+  and the runtime's network interface addresses. Add other private names or IP addresses to `HERDR_WEB_ALLOWED_HOSTS`
+  (comma-separated) before using them. An unlisted name returns HTTP 403 (`host` / "Host not
+  allowed"); add it to `HERDR_WEB_ALLOWED_HOSTS`, then restart wherdr. This host check also
+  applies to WebSockets.
+- **Passkey lock** (Settings → Security, optional): once a passkey is registered, the API,
+  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
+  passkeys: each device unlocks again with its own. Turning the lock off removes the passkeys and
+  invalidates every session. Lost passkey: delete `data/auth.json` on the server; the app is open
+  again to whoever can reach it.
+- <a id="new-device"></a>**New device**: it can only get in with an existing passkey. Unlock it
+  with a passkey synced by your password manager (iCloud Keychain, Google Password Manager,
+  1Password…), or with the passkey of another device through the browser's "use a phone or
+  tablet" QR code, then Settings → Security → **Add this device** to give it its own passkey.
+- Without a passkey, **anyone who can reach the address can control your agents**: every device
+  on your tailnet, and every user of your tailnet if you share it.
+- Writes require `Content-Type: application/json` (or `image/*` for photos, `application/octet-stream` for attached files) and an `Origin`
+  matching the host, WebSockets included. API reads sent from another site (links, images,
+  `no-cors` fetches, reported by the browser's `Sec-Fetch-Site`) are refused too.
+- A strict Content Security Policy limits scripts to the app's own origin and hashed inline
+  scripts, and connections to that origin and its WebSockets. It also blocks embedded objects
+  and framing.
+- wherdr never changes your agents' global settings: model and effort changes are for the
+  current session only.
+
+See [SECURITY.md](../SECURITY.md) to report a vulnerability.
+
+### Network access
+
+wherdr answers **this computer and your tailnet only**. A device on any other network (a coffee shop
+Wi-Fi, an office LAN, the Internet) gets HTTP 403 (`network`), with a page that says why, even
+when it knows the address and the port. The passkey lock is never required, on any network: it
+is an extra lock on top, and it needs HTTPS (or `localhost`).
+
+**Good practices**
+
+- Prefer **Tailscale** (`tailscale serve`): a private HTTPS address, only for your devices.
+- A network you add **without HTTPS** gets no passkey, no installed app and no notifications, and
+  any device on that network can control your agents.
+- **Create a passkey** as soon as wherdr is reached over HTTPS.
+
+How a request is judged, before anything else (WebSockets included):
+
+- **Its TCP peer** (the address the connection comes from, not a header). A client cannot pick
+  it: a connection only opens once the client has received wherdr's reply at that address.
+  - *Loopback* (`127.0.0.0/8`, `::1`): this computer. The kernel drops packets that arrive from a
+    network with a loopback source.
+  - *Tailnet*: an address of `100.64.0.0/10` or `fd7a:115c:a1e0::/48` counts only when
+    Tailscale, running on this machine, lists it as one of its peers (or its own address). wherdr
+    reads that from Tailscale every 10 seconds (the CLI or Tailscale's socket); an
+    interface address in that range proves nothing, since a LAN may use it too. When Tailscale is
+    stopped, missing or unreadable for 30 seconds, no direct connection counts as tailnet.
+- **Proxy headers**, only when the peer is this computer (a proxy on the machine, such as
+  `tailscale serve`): every address in `X-Forwarded-For`, `Forwarded`, `X-Real-IP`,
+  `CF-Connecting-IP` must be loopback, the tailnet or a trusted range too. They can only refuse
+  more: a client that writes its own headers directly only gets itself refused. A proxy that
+  adds the client's address (Caddy, nginx with `proxy_add_x_forwarded_for`, Cloudflare Tunnel)
+  therefore has its outside clients refused.
+- **Tailscale Funnel**: wherdr reads Tailscale's serve configuration every 10 seconds, at most
+  2 seconds before an HTTP request, and again for every WebSocket it opens. Connections from this
+  computer stay local only while the latest reading **proves** that Funnel does not expose
+  wherdr's port, in any form (HTTPS, TCP, or TCP with TLS termination, which carry no client
+  address). A Funnel route counts unless its target clearly leads to another port: the host is
+  never compared (`0.0.0.0:7683`, `127.1:7683` or a LAN address reach wherdr too), and a target
+  wherdr cannot parse counts. Funnel routes to other ports do not count (Funnel for another
+  service is fine). While Funnel exposes wherdr, **every connection from this computer is
+  refused**, with a page that says how to turn it off: Funnel puts wherdr on the Internet. Once
+  seen, the exposure stays until a valid reading shows it gone: a failed, garbled or late reading
+  does not reopen wherdr. Open WebSockets are judged again after every reading and closed when no
+  longer allowed; between two readings (10 seconds at most), a connection opened before Funnel was
+  turned on can last that long. When Funnel was never seen, a failed or garbled reading proves
+  nothing: connections are served and the server log says that Funnel cannot be checked. A Funnel request with Tailscale's
+  `Tailscale-Funnel-Request` header is always refused.
+- **The listening address**: wherdr refuses to start on anything else than
+  loopback or this machine's tailnet address as Tailscale reports it, with Tailscale running
+  (`HOST=0.0.0.0`, a LAN address), and says how to fix it.
+
+> [!IMPORTANT]
+> **A relay on this computer counts as this computer.** A reverse proxy or TCP forward you run
+> on the machine (nginx without forwarded headers, `socat`, an SSH tunnel, a tunnel client) opens
+> its connections from loopback, like your own browser, and may pass on headers its clients
+> wrote. wherdr cannot tell them apart. If you run one, make sure it only listens on a private
+> address, serve it over HTTPS and **create a passkey**.
+
+`tailscale serve` (npm, Homebrew, the Herdr plugin) forwards to `127.0.0.1` with the
+tailnet client's address in `X-Forwarded-For`: accepted, nothing to set up.
+
+**Another private network** (ZeroTier, WireGuard, NetBird outside `100.64.0.0/10`): name its
+range, `WHERDR_TRUSTED_NETWORKS=10.147.17.0/24` (comma-separated CIDR ranges or addresses), then
+restart wherdr. Such devices get the whole app, Settings › Phone and the one-tap update
+included, like the tailnet. `WHERDR_TRUSTED_NETWORKS=any` accepts every network: wherdr then
+warns at startup and shows a warning that cannot be hidden in the app. Use it only when
+something else protects the network (Cloudflare Access), and set up a passkey there too.

package/docs/terminal.md

@@ -0,0 +1,15 @@
+# Terminal
+
+[Documentation](README.md) · [Project](../README.md)
+
+- **Terminal view**: the real terminal (xterm.js, WebGL or DOM renderer) with take-over. Opening
+  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
+  `⌘C` / `Ctrl+Shift+C`. The history is browsed with the wheel, not by dragging past the edge.
+  Links (OSC 8 hyperlinks and plain `http(s)://` URLs, even wrapped over several rows) open in a
+  new tab with `⌘`+click / `Ctrl`+click, or a tap on a phone; only http and https open. A long
+  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.

package/docs/troubleshooting.md

@@ -0,0 +1,45 @@
+# Troubleshooting
+
+[Documentation](README.md) · [Project](../README.md)
+
+## Troubleshooting
+
+- **"The Herdr server is not responding"**: start Herdr on the server (`herdr` or
+  `herdr server`).
+- **wherdr stops when you log out** (Linux): lingering is off. `wherdr doctor` says so; run
+  `sudo loginctl enable-linger $USER` once.
+- **The Board says `claude is not installed here`**: the agent is in a folder your login shell
+  does not add to its `PATH`. Add it there, then run `wherdr service install` again
+  ([Agent PATH](installation.md#agent-path)).
+- **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. 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 "wherdr only answers this computer and your tailnet"**: the device is on another
+  network (Wi-Fi, LAN). Open wherdr through Tailscale, or name that private network in
+  `WHERDR_TRUSTED_NETWORKS` ([Network access](security.md#network-access)).
+- **HTTP 403 "Tailscale Funnel opens wherdr to the Internet"**: turn Funnel off for wherdr’s port (`tailscale funnel status`).
+- **wherdr stops at startup with "Refusing to listen on …"**: `HOST` is not loopback nor this
+  machine's tailnet address. Set `HOST=127.0.0.1` and use `tailscale serve`, or see
+  [Network access](security.md#network-access).
+- **HTTP 403 "This address isn't enabled yet"**: for a tailnet address, run the command the
+  page gives on the machine: it tells whether `tailscale serve` publishes wherdr's port there.
+  For another private name, add the hostname or IP address to `HERDR_WEB_ALLOWED_HOSTS`, or use
+  the hostname in `APP_URL`, then restart wherdr.
+- **Remote machine offline**: `grep machine ~/wherdr/wherdr.log` shows its state. Test SSH:
+  `ssh -o BatchMode=yes laptop '~/.local/bin/herdr status server'`.
+  - `Could not resolve hostname`: check the full name in `HostName`;
+  - `Permission denied (publickey)` / `Host key verification failed`: key or `known_hosts`
+    (run `ssh laptop true` once on the server);
+  - `Bad owner or permissions`: `~/.ssh/config` must belong to you and not be group-writable.
+- **Claude says "Not logged in" on a Mac** whose Herdr server was started over SSH: the macOS
+  keychain is locked in SSH sessions. Start the Herdr server from a terminal on the Mac.
+- **`Session open refused by peer` / `Connection closed by UNKNOWN port 65535`** in the logs: the
+  shared SSH connection to a remote machine reached sshd's session limit (`MaxSessions`, 10 by
+  default). wherdr stays under it and retries, so this is rare; if it persists (many terminals
+  open at once), raise `MaxSessions` in the remote machine's `sshd_config`.
+- **Quotas missing**: see [Claude and Codex quotas](quotas.md#claude-and-codex-quotas).
+- **iPhone layout cut at the bottom** after changing the status bar style: reinstall the home
+  screen icon (iOS reads this setting at install time).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wherdr",
-  "version": "1.3.3",
+  "version": "2.0.0",
   "license": "MIT",
   "type": "module",
   "description": "Unofficial mobile web client (PWA) to drive the coding agents running in Herdr",
@@ -26,7 +26,8 @@
     ".output",
     "!.output/**/*.map",
     "bin",
-    "skills/wherdr"
+    "skills/wherdr",
+    "docs/*.md"
   ],
   "engines": {
     "node": ">=22"
@@ -39,10 +40,15 @@
     "typecheck": "nuxt typecheck",
     "test": "vitest run",
     "test:e2e": "playwright test",
+    "shots:readme": "node tools/readme-shots/capture.mjs",
+    "test:e2e:shots": "SHOTS=${SHOTS:-.shots} playwright test tests/e2e/question-reply.spec.ts --grep screenshot:",
+    "test:e2e:stability": "playwright test menu-responsiveness codex-self-update quote-mode onboarding-tailnet --grep \"MCP arrow paints|a new Codex restarts|the former per-device values|a quoted question keeps|#/setup[?]step=security opens|a direct Security link\"",
     "prepare": "nuxt prepare",
     "prepack": "nuxt build && node scripts/pack-output.mjs",
+    "check:docs": "node scripts/check-doc-links.mjs",
     "check:leaks": "node scripts/check-leaks.mjs",
-    "hooks:install": "git config core.hooksPath .githooks"
+    "hooks:install": "git config core.hooksPath .githooks",
+    "test:affected": "node scripts/test-affected.mjs"
   },
   "dependencies": {
     "qrcode-terminal": "^0.12.0"
@@ -60,6 +66,7 @@
     "@types/node": "^22.0.0",
     "@types/web-push": "^3.6.4",
     "@vite-pwa/nuxt": "^1.1.1",
+    "@vue/reactivity": "^3.5.43",
     "@vue/test-utils": "^2.5.1",
     "@xterm/addon-fit": "^0.10.0",
     "@xterm/addon-webgl": "^0.18.0",
@@ -68,6 +75,7 @@
     "happy-dom": "^20.14.5",
     "marked": "^15.0.12",
     "nuxt": "^4.5.2",
+    "pdfjs-dist": "5.4.624",
     "tailwindcss": "^4.3.3",
     "typescript": "~5.9.3",
     "vitest": "^4.1.11",