wherdr 1.3.3 → 2.0.0

package/docs/RELEASING.md

@@ -0,0 +1,174 @@
+# Releasing wherdr
+
+Publishing a version requires the user's explicit approval. Never republish a package held
+for npm review. No new secret is needed: GitHub uses `GITHUB_TOKEN`, npm uses OIDC Trusted
+Publishing (`npm.yml`), and the tap uses the existing optional `HOMEBREW_TAP_TOKEN`.
+
+1. Merge reviewed changes, including the release workflows, into `main`. The site workflow
+   deploys relevant changes on pushes to `main`, independently of tags and npm.
+2. Set the same version in `package.json`, `package-lock.json` and `herdr-plugin.toml`.
+   Move the Unreleased changelog into a dated version entry. Run tests, typecheck and leak
+   checks; review and merge this version commit before tagging it.
+3. Create the GitHub release as a **draft**, with reviewed English notes under one or more of New / Improved /
+   Fixed / Update. Write at least two readable sentences explaining what changed for users,
+   then link to the tagged CHANGELOG.md (see the example below). A link alone, including
+   "See CHANGELOG.md", is never sufficient. Push its version tag only after these notes are ready.
+   The workflow validates the draft before attaching the package and again immediately before
+   publication; missing or insufficient notes fail the job. It never generates stable release notes.
+4. The tag starts `release.yml` and `npm.yml` independently. `release.yml` runs `npm pack`
+   (prepack builds Nitro, includes `skills/wherdr`, resolves linked packages). It attaches
+   `wherdr-X.Y.Z.tgz` and `wherdr-X.Y.Z.tgz.sha256` to the draft. After the package job
+   succeeds, it publishes the release with `latest=false`. The public GitHub package is now
+   usable; native plugins compare the archive checksum. A failed package job leaves the
+   release draft; fix and rerun the failed job.
+5. The Homebrew job updates the formula URL and SHA from GitHub, without waiting for npm.
+   **The manual Homebrew step is MANDATORY while `HOMEBREW_TAP_TOKEN` is absent**. Wait for `release.yml` to finish successfully first, so its
+   archive is public; then run `scripts/bump-homebrew.sh`. Otherwise the legacy update channel
+   cannot advance even when npm is ready. A skipped Homebrew job does not complete this step.
+   Homebrew still uses npm to install the local archive and fetch its third-party dependency;
+   it does not need the new **wherdr version** to be available on npm.
+6. `npm.yml` waits for the attached archive (up to 30 minutes), verifies it, then publishes
+   that exact file with provenance. npm moderation may still delay registry availability.
+   If the assets were too slow to arrive, rerun the failed download job before any successful
+   publication; never retry a successful `npm publish` merely because moderation is pending.
+   To recover a workflow fix without moving a tag, run `gh workflow run npm.yml --ref main -f version=vX.Y.Z` after merging the fix; it checks out that tag and publishes its existing release archive.
+7. `release-ready.yml` checks hourly and after npm/release workflow completion. Once npm's
+   tarball and `latest` tag, and the Homebrew formula are ready, it marks the GitHub release
+   `latest`. Existing 1.3.x apps read this marker and can then safely use their npm updater.
+   New apps read published stable releases directly, checking npm or the formula for their
+   own installation mode. No update notice is offered while that channel is unavailable.
+
+An old plugin can get the release immediately via **U** in Herdr or the one-command installer;
+its old in-app Update button waits for the legacy channel. Plugin installation tries the exact
+version from GitHub, then npm, then compiles only when neither prebuilt source works. This
+includes older releases with no GitHub archive. Keep the previous npm version, GitHub assets,
+and Homebrew keg available for automatic health-check rollback.
+
+SHA-256 checks download integrity, not authenticity: the archive and checksum share an origin.
+Replacing both defeats this check. npm fallback compares the archive to the SHA-512 integrity
+in registry metadata, with the same limitation. There is no signature or build attestation check.
+
+npm provenance identifies the publishing workflow (`npm.yml`); the archive was built by
+`release.yml` in the same repository at the requested tagged commit. On a manual run from
+`main`, provenance identifies the workflow's `main` commit, while checkout and version checks
+use the requested tag. It does not independently attest that separate build workflow (M8);
+this limitation is intentionally retained.
+
+Readiness logs name each missing npm or Homebrew condition, and an already-current `latest`
+marker is left alone. GitHub disables scheduled workflows in public repositories after 60 days
+without repository activity. Check that `release-ready.yml` remains enabled; re-enable it and
+run it manually if needed. After re-enabling, workflow-completion and manual checks work too.
+
+## herdr-projects tested version
+
+wherdr installs one herdr-projects release, and offers an update to it on machines with an older
+one: `PROJECTS_TESTED` in `shared/projectsPlugin.ts`. `PROJECTS_MIN` (1.2.1) is the oldest
+release wherdr still reads; it moves only when wherdr drops one.
+
+To move to a newer herdr-projects release:
+
+1. Download its binary from GitHub (`gh release download vX.Y.Z -R eliasstravik/herdr-projects`)
+   and check it against its `.sha256`. Run it with `HOME` set to an empty temporary folder and
+   Herdr unreachable. Record `version`, `list --json`, `list --json --archived`,
+   `details --json -- <id>`, `show --json -- <id>` and `coordinator --machine --json status`
+   into `tests/recordings/herdr-projects-X.Y.Z/` (no personal paths or machine names).
+   Also check that `tell`, `approve`, `after`, `archive`, `restore` and `coordinator … tell`
+   still take the same arguments.
+2. Set `PROJECTS_TESTED` to `X.Y.Z`, and point the recordings test in
+   `tests/projectsTasks.test.ts` at the new folder.
+3. If the release adds a feature worth naming, add it to `FEATURES` in
+   `app/components/ProjectsPluginSettings.vue` (the update's one-line summary, FR + EN).
+4. Run `npx vitest related --run shared/projectsPlugin.ts`: `tests/projectsPlugin.test.ts`
+   fails until the install commands in `docs/board.md`, `docs/herdr-projects-1x.md` and
+   `website/public/agent.md` name the new release.
+
+## Release notes checklist
+
+- Summarize the changes in English under `## New`, `## Improved`, `## Fixed` or `## Update`;
+  omit categories with no relevant changes. Use complete sentences, at least two in total
+  (at least twelve words), describing the user-visible behavior and any required upgrade action.
+- Put the full changelog link after the summary, using the release tag rather than `main`.
+- Review the text against that version's changelog. The automated check enforces structure
+  and minimum content; the reviewer checks accuracy and clarity.
+- Validate the exact draft text locally before pushing the tag:
+  `GITHUB_REPOSITORY=example/wherdr GITHUB_REF_NAME=vX.Y.Z node scripts/check-release-notes.mjs < /tmp/wherdr-X.Y.Z.md`.
+  If the workflow refuses the notes, edit the draft and rerun the failed jobs.
+
+Example (replace `example/wherdr` and the version, and describe the actual release):
+
+```markdown
+## Improved
+File downloads now work with the supported Node versions. Temporary download links
+are released after the browser saves the file, keeping repeated downloads reliable.
+
+[Full changelog](https://github.com/example/wherdr/blob/vX.Y.Z/CHANGELOG.md)
+```
+
+## Rolling v2 prerelease
+
+`v2-prerelease.yml` rebuilds one prerelease on every push to the `v2` branch, so a machine
+can install v2 from a prebuilt package (the plugin's GitHub download) and never compile it.
+It publishes the version of `herdr-plugin.toml` (for example `2.0.0-dev`, before the stable version bump) as `v<version>`:
+
+- the tag moves to the pushed commit; the release is a prerelease, never `latest`. The update
+  checks of every version, the legacy channel and `release-ready.yml` only read stable
+  `vX.Y.Z` releases, so none of them offers it;
+- `wherdr-<version>.tgz` and `.tgz.sha256` are made as in `release.yml` (`npm pack`,
+  `sha256sum`) and replaced; the archive must hold the built server, `bin` with
+  `bin/lib/install-skill.sh`, `package.json` and `skills/wherdr/SKILL.md`, and no native code
+  (`.node`, `binding.gyp`, `prebuilds`, ELF or Mach-O files): the same file runs on
+  linux-arm64 and x64;
+- `COMMIT` holds the full SHA of the packaged commit, also written in the notes. It is removed
+  before the archive is replaced and attached last: when `COMMIT` is there and names the
+  branch head, the archive is that commit's.
+
+Once the version is stable, the workflow skips packaging and publication; it must not create a stable tag.
+
+The rolling notes start with an Update summary of the first three top-level Unreleased
+changelog entries and a link to the changelog at the packaged commit, followed by build
+metadata. Keep these entries readable and current; packaging fails if they are absent or fail the same minimum-content check.
+
+`scripts/prerelease.sh` does the checks and the publication. It refuses a version without a
+prerelease suffix (`X.Y.Z-something`) and a release of that tag that is not a published
+prerelease: stable versions keep going through the steps above. The tag is moved with
+`GITHUB_TOKEN`, which starts neither `release.yml` nor `npm.yml`. The workflow runs from the
+`v2` branch: it acts once this file is on `v2`.
+
+## Commands for 2.0.0
+
+Run in a release checkout after explicit approval. These commands are documentation, not a
+request to publish. The version commit must go through the usual reviewed PR process.
+
+```sh
+git switch main
+git pull --ff-only
+git switch -c release/2.0.0
+npm version 2.0.0 --no-git-tag-version
+sed -i.bak 's/^version = ".*"/version = "2.0.0"/' herdr-plugin.toml
+rm herdr-plugin.toml.bak
+# Move Unreleased notes to the dated 2.0.0 entry, run the project checks, then commit.
+git add package.json package-lock.json herdr-plugin.toml CHANGELOG.md
+git commit -m "Prepare release 2.0.0"
+git push -u origin release/2.0.0
+gh pr create --base main --head release/2.0.0 --title "Prepare release 2.0.0" --body "Prepare the reviewed 2.0.0 release versions and changelog."
+# Open, review and merge the version PR; refresh main before continuing.
+git switch main
+git pull --ff-only
+# Use the reviewed notes committed with the version preparation.
+GITHUB_REPOSITORY="$(gh repo view --json nameWithOwner -q .nameWithOwner)" GITHUB_REF_NAME=v2.0.0 node scripts/check-release-notes.mjs < docs/release-notes-2.0.0.md
+gh release create v2.0.0 --target "$(git rev-parse HEAD)" --draft --title "wherdr 2.0.0" --notes-file docs/release-notes-2.0.0.md
+git tag v2.0.0
+git push origin v2.0.0
+release_run=$(gh run list --workflow release.yml --commit "$(git rev-parse HEAD)" --json databaseId --jq '.[0].databaseId')
+# If no run appears yet, wait for GitHub to register the tag and repeat the lookup.
+gh run watch "$release_run" --exit-status
+gh run list --workflow npm.yml --limit 3
+# MANDATORY while the tap secret is absent. Run only after release.yml succeeds:
+sh scripts/bump-homebrew.sh 2.0.0 "$(gh repo view --json owner -q .owner.login)"
+# Inspect the readiness workflow; optionally request an immediate check:
+gh workflow run release-ready.yml --ref main
+```
+
+Use Node.js 22 for npm commands. Do not manually publish the draft or mark it latest ahead
+of these checks. A GitHub release created by `GITHUB_TOKEN` does not trigger other workflows;
+all publication work is driven by the pushed tag, not `release: published` events.

package/docs/board.md

@@ -0,0 +1,164 @@
+# Board and coordinators
+
+[Documentation](README.md) · [Project](../README.md)
+
+On desktop, drag the ticket panel’s divider to adjust its width. It uses the same
+handle as the navigation list: arrow keys (Shift for a larger step), double-click,
+Home or Enter to restore the default width. The width is saved on this device;
+the Board keeps at least 280 px when space permits. Phone panels stay full screen.
+
+## Works great with herdr-projects
+
+[herdr-projects](https://github.com/eliasstravik/herdr-projects) is a work board for Herdr: one
+list of tasks, each handed to an ordinary agent in its own space, reviewed when it finishes and
+merged on your yes. wherdr shows it on the **Board** (the button next to Settings, or `H`), for
+every machine at once. It needs **herdr-projects 1.2.1 or later**; the plugin is optional.
+
+**Install herdr-projects** in **Settings → Plugins → herdr-projects**, or on the machine. wherdr
+installs the release it was tested with (1.2.21):
+
+```sh
+herdr plugin install eliasstravik/herdr-projects --ref v1.2.21 --yes
+```
+
+A machine with an older 1.x (1.2.1 or later) still works. Settings says **Update available**
+there, with what the update adds, and **Update to 1.2.21** replaces Herdr's copy of the plugin;
+the tasks and settings stay. wherdr reads the program's own version (`herdr-projects version`),
+so a machine that ran `herdr-projects update` to a newer release is never taken back.
+
+> **Breaking change in wherdr 2.0: herdr-projects 0.2 is no longer read.** The Project panel,
+> the `TASKS.md` board, threads, thread limits and **New project** belonged to herdr-projects
+> 0.2 and are gone. With 0.2 (or a 1.x older than 1.2.1), Settings and the Board say
+> **Update herdr-projects to 1.2.1 or later, or downgrade wherdr to 1.3.4**, with the commands.
+> The step-by-step move, with a backup and the way back, is in
+> [docs/herdr-projects-1x.md](herdr-projects-1x.md). wherdr 1.3.4 is the last version
+> that reads herdr-projects 0.2.
+
+What the Board shows and does:
+
+- **The board's groups**: needs you, ready to approve, working, to do. **Done** is history, so it
+  is hidden by default: **Done · 9** at the end of the column heads (the last tab on a phone)
+  shows it, newest first, the latest five then **Show all**, and hides it again; the choice is
+  saved on the server and shared across devices. Headings still count done tasks. Side by side
+  on a computer, one at a time on a phone. A card shows
+  the task's key (`DEMO-12`), title, the line its agent reports, the agent program, progress, its
+  pull request and its review (pass or fail, with the findings by severity).
+- **A task** opens one compact side panel from the Board or its home row. The header names
+  the machine, repo, task and agent program, with the Board's one state: Needs you, Ready to
+  approve, Working, To do or Done. **Conversation**, **Terminal**, **Task** and **Settings** sit below it.
+  Task holds the description, closing note, report, pull request, review findings, limits,
+  token use and actions; a dot marks a new closing note or review. The agent's own Herdr state
+  is in a tooltip, separate from the task's state. The panel sits beside the Board on a
+  computer (with a full-screen button) and fills the screen on a phone.
+- **Settings** reads the effective task settings from `show --json` on its machine when
+  opened. Agent, review, plan and attempts, limits, merge and workspace settings show their
+  value and source: task, repository, you, repository file or default. Source details,
+  CLI notes and problems stay visible. This view is read-only; unavailable or missing data
+  is stated explicitly. Board refreshes do not reread the settings.
+- **Needs you** shows where the task stands now: the Board's failure or question, its command
+  output and next-step hint. A failure the task has moved on from (a later stage, or its agent
+  started again) is not the banner, and gets no buttons: it stays in Task as an earlier failure.
+  It offers **Retry**, **Send the error to the agent** (`fix`), **Open terminal** and, when
+  allowed, **Approve anyway** with confirmation. After a failed review, it lists the open
+  findings (severity and subject, worst first) and offers **Send the review back to the agent**
+  (`review`) first, as herdr-projects does, with **Approve anyway** after it. While the reviewer
+  shows a dialog (`reviewneeds`), a reply goes to the reviewer, and wherdr says so. **Finish** (`finish`, after a confirmation)
+  takes the work as it is, then runs its checks and review: offered when the agent stopped at
+  a limit (Retry gives it the same limit again) or without a summary, and when its agent is at
+  rest while the row stays on "Finishing". A setup failure offers **Start again**:
+  herdr-projects uses `delegate` before an agent has started. With no conversation, the panel
+  keeps the explanation visible instead of opening a bare shell; Terminal stays reachable
+  when a pane exists. Read-only and unreachable machines cannot run banner actions.
+- **A task's sheet**, from the panel's **…** button, has the same details and actions as
+  the Task tab. **Open the chat** closes it and opens the conversation. When the agent has
+  no pane, a field sends a reply through herdr-projects (`tell`; on a waiting plan, it sends
+  the plan back).
+  **Approve** merges finished work or says yes to a plan, after a confirmation; **Start**,
+  **Stop**, **Retry**, **Finish** and **Archive** where herdr-projects takes them. **Start** names the agent
+  the task starts with by default (its `worker.agent` and where that comes from) and offers the
+  other agents installed on its machine: one picked there is for this start only
+  (`delegate --worker.agent`). herdr-projects keeps that pick as the task's own setting while
+  its run lasts; wherdr puts back what the task had once the run is over (back in To do, or
+  done) and before its next Start, so its default, the repo's and your own settings stay as they
+  are (`data/start-agents.json` remembers what to put back). A default agent not installed on that
+  machine is shown but cannot be picked: Start then waits for an installed one. With every slot of
+  the board taken (`board.agents` tasks at work), **Start** says **Queue** and the place the task
+  would get (`delegate` queues it). **Start after…** picks tasks to wait for, by key, id or title, on
+  every machine the Board reads (another machine's as `machine:KEY-12`): `delegate --after`. A task
+  that waits names them, with **Stop waiting** (`after --clear`); one in the queue says its place.
+  herdr-projects' refusals (a circle, an unknown task, a machine that does not answer) are shown as
+  they are. After an action the sheet
+  shows the task's new state, or why it was refused. **Archive** closes the sheet and takes the
+  task off the Board, with **Restore** in a toast for a few seconds; **Archived** lists the
+  archived tasks, whose sheet is read-only with **Restore**, as in herdr-projects.
+- **Coordinators**, in the same panel: a machine's heading opens its Coordinator, the agent that
+  turns what you write into tasks; a repo's heading opens that repo's project coordinator. One
+  not started yet takes a first message (`coordinator tell`), which starts it. One that
+  herdr-projects could not start (an agent not installed there…) says why, with **Try again**
+  (`coordinator restart`) once it is fixed: the message still waiting then goes in.
+- **Autopilot** (herdr-projects 1.2.15 or later): each coordinator has a switch, under the Board's
+  bar for the main Coordinator, in each machine and repo heading, and at the top of its panel. It
+  shows whether the board wakes that coordinator to work toward its goal, and when next. Turning it
+  on asks for the goal (filled in with the saved one, required otherwise) and, optionally, how often
+  and how many tasks a day or at once, for this time only (`herdr-projects autopilot on --goal …
+  [--machine | --project <repo>]`); stopping asks first (`autopilot off`). The state shown is read
+  back from `herdr-projects autopilot --json` after each action; a refusal (no goal, older version)
+  is shown as the board says it.
+- **Task identity** stays with the worker on the home list, Board card and conversation header.
+  During a review, **Reviewed by** names the reviewer beside its own small logo. The conversation
+  explains that it belongs to the worker and the review runs separately; **Open reviewer terminal**
+  opens the reviewer's terminal when reachable, or a session switch is offered when it runs in
+  another open session. After a worker fallback, the main logo names the current worker and
+  **Took over from** names the previous one from the recorded handover.
+- **The agent list** groups the board's spaces under their repo, as Herdr's sidebar does: each
+  machine's Coordinator and machine coordinator first, each with its own icon and the Board's name (**Coordinator** with
+  the board's icon, **`<machine>` coordinator** with the machine's), then per repo a head row, its project
+  coordinator (named after the repo, the wherdr mark on the accent, **Coordinator**, its state; its
+  question and one-tap answers when it asks one), a bar under it (fold, the tasks' summary such as `4 TASKS · 1 YOUR TURN ·
+  1 LIMIT`, branch and commits behind its upstream, and the repo space's **…** menu, which opens
+  its terminal), and its tasks' spaces, indented and folding with the bar (key, title, state,
+  progress, time on it, the line the board reports; the Board icon opens the task there). One
+  row per task: its reviewer, planner and attempts, each in a tab of the task's space, are part
+  of it; in normal mode the row says the stage (**Under review · codex**), and both modes
+  open the task panel while a review runs. The counters count tasks, not tabs. A repo
+  coordinated from another machine shows **Coordinated from <machine>** above the bar instead
+  of a local coordinator. Without either coordinator, the bar is the first row; the repo's plain
+  terminal stays accessible through its **…** menu. wherdr reads this from
+  the board's files (`~/.herdr-projects/data`: tasks, attempts, reviewers, coordinators, repos)
+  and from Herdr's worktree groups, every 15 seconds while the list is shown, never through
+  herdr-projects' command line; the branch and behind count come from `git` in the repo's main
+  checkout, once a minute, without fetching.
+- **Scheduled** (FR **Programmé**), collapsed in every coordinator panel: its Autopilot
+  status, wake frequency, goal and daily limits; board automations for that project
+  (including events across all repos), their latest firings and links to created tasks;
+  and Claude Code session timers reconstructed from successful transcript tool calls.
+  Open the section to read it; refreshing the Board refreshes an open section. It is
+  read only. Dates use the coordinator machine's time zone. Session timers disappear
+  when deleted, after a one-shot fires, or after seven days; they are lost when the
+  Claude Code session closes. An unavailable source is shown explicitly rather than
+  presented as an empty schedule.
+- **Coordinator entry points**, named as herdr-projects names them, one name per level on the
+  Board, the home list, the conversation header and the menus: the top of the Board offers the
+  main **Coordinator** (FR **Coordinateur**), for all repos and machines it can reach. With
+  several hosts, its menu lists them by name; unavailable and read-only hosts stay listed with
+  their reason. Machine headings offer **`<machine> coordinator`** (FR **Coordinateur ·
+  `<machine>`**: the machine as a whole, its repos and folders, its tasks and agents), repo
+  headings offer **`<repo> coordinator`** (FR **Coordinateur · `<dépôt>`**: work in that repo). Hover or long-press an entry for its role;
+  the conversation header repeats that description.
+- **A machine is one board**, shared by its named sessions: one list, one queue, one card per
+  task. A machine whose read fails says why on the Board, and its last tasks stay, marked with
+  the time they were read.
+- What wherdr runs, on the task's machine and in its Herdr session (on an SSH machine, its own
+  session by name): `herdr-projects list --json`,
+  `details <id> --json`, `show <id> --json`, `set`/`unset worker.agent --task <id>` (to put back a pick), `tell <id> <text>`, `approve <id>`, `delegate` (with `--after`), `after <id> --clear`, `stop`, `retry`,
+  `archive` and `restore <id>`, `list --json --archived` (Archived), `coordinator tell <text>`,
+  `coordinator status --json` and `coordinator restart` (your
+  words always after `--`, so they are never read as options), through the plugin's own
+  launcher (`bin/run.sh`). Each command also runs herdr-projects' own upkeep, so wherdr calls it
+  sparingly: one command at a time per machine, a read every 15 seconds and only while the Board
+  is open (a list less than 5 seconds old is reused), and the last list kept when a machine is
+  slow or unreachable. Nothing runs where herdr-projects is missing or older than 1.2.1: its first
+  run would take over an older install's files.
+- **Agents in user folders**: wherdr runs herdr-projects with your [PATH](installation.md#agent-path), on this
+  machine and over SSH, so `claude is not installed here` does not come from a login service's
+  short `PATH`.

package/docs/command.md

@@ -0,0 +1,58 @@
+# The wherdr command
+
+[Documentation](README.md) · [Project](../README.md)
+
+### The `wherdr` command
+
+An alternative to [the one command](installation.md#the-one-command), from npm or Homebrew: the same app, without
+the Herdr plugin. npm can hold a new release for up to two days (moderation), so these get updates
+later than the installer, which downloads the GitHub release package. The npm package holds the
+built app: nothing is compiled on your machine. Try it with `npx wherdr` (or `bunx wherdr`,
+`pnpm dlx wherdr`); to keep it, install it once:
+
+```sh
+npm install -g wherdr       # or: pnpm add -g wherdr, bun add -g wherdr
+wherdr service install      # configures automatic startup; prints the address
+wherdr phone                # phone state, the app's phone setup page, QR code once it answers
+```
+
+| Command | What it does |
+| --- | --- |
+| `wherdr` (or `wherdr run`) | Runs in the foreground; Ctrl+C stops it. |
+| `wherdr start` · `stop` · `restart` | Background server, pid and log in `~/wherdr`. `start` says *started* only once the port answers; otherwise it prints the end of the log. With a login service installed, they drive the service. |
+| `wherdr status` | Address, process, service, data folder and log. |
+| `wherdr logs` (`-f` to follow, `-n 100`) | The log, `~/wherdr/wherdr.log`. |
+| `wherdr open` | Opens wherdr in the browser: its tailnet address when published and answering, else `localhost`. |
+| `wherdr phone` | Whether your phone can reach wherdr (Tailscale, `tailscale serve`, the address answering), the `tailscale serve` command to publish it when it is not (wherdr then enables the address by itself), the link to **Settings › Phone**, and the QR code once the address answers. |
+| `wherdr service install` · `uninstall` | Configure automatic startup: a LaunchAgent on macOS (`~/Library/LaunchAgents/dev.wherdr.plist`) starts at login; a `systemd --user` unit on Linux starts at boot with lingering enabled, otherwise at login. The command tries to enable lingering (`loginctl enable-linger`, without sudo; when your system refuses it, the command to run is printed) so it keeps running while you are logged out; without lingering it stops after logout. The service gets your [PATH](installation.md#agent-path). The one command and key **A** of the plugin's panel run it too. |
+| `wherdr doctor` | Checks Node/Bun, Herdr and its socket, the port, the service, the data folder and `APP_URL`. |
+
+Options: `--port` (default `7683`), `--host` (default `127.0.0.1`; loopback or this machine's
+tailnet address, anything else is [refused](security.md#network-access) unless `WHERDR_TRUSTED_NETWORKS` names it),
+`--data-dir` (passkeys, push keys and settings; default `~/wherdr/data`, the folder the Herdr
+plugin and the install script use), `--session` (a named Herdr session). Every
+[environment variable](configuration.md#configuration) works too, and so do `KEY=VALUE` lines in
+`~/wherdr/wherdr.env` (for example `APP_URL=…`, read at each start); options win, then the
+environment, then that file. `start` and `service install` remember the port and folders for
+the other commands.
+
+**Homebrew:** `brew install afloury/tap/wherdr` installs the same package; the first install also
+brings Homebrew's Node.js (heavier than the Herdr plugin when Node.js 22 is already there). Then:
+
+1. `brew services start wherdr`: runs `wherdr run` now and at every login, log in
+   `$(brew --prefix)/var/log/wherdr.log` (`wherdr logs` reads it).
+2. `wherdr open`: the setup guide in your browser.
+3. Its Phone step (or `wherdr phone`).
+
+On a Homebrew install, `wherdr start`, `stop`, `restart` and `service install` point to
+`brew services` (the installed path changes at each upgrade); `wherdr status` and `wherdr doctor`
+show the Homebrew service. Update: `brew upgrade wherdr && brew services restart wherdr`.
+
+The login service records the **absolute path** of the runtime (n, nvm, fnm, Volta or Homebrew
+node) and your [PATH](installation.md#agent-path), since launchd and systemd do not see your shell's. It refuses to point at a
+temporary `npx` / `pnpm dlx` / `bunx` folder: install the package globally first. To update:
+`npm install -g wherdr@latest && wherdr restart` (with `npx`: stop it, then `npx wherdr@latest`).
+
+Bun runs wherdr too (WebSockets, push, passkeys and Herdr's socket work); when Node.js 22 is
+also installed, `bunx wherdr` hands the server to Node, the reference runtime. Set
+`WHERDR_RUNTIME=bun` to keep Bun.

package/docs/configuration.md

@@ -0,0 +1,39 @@
+# Settings and configuration
+
+[Documentation](README.md) · [Project](../README.md)
+
+- **Themes**: wherdr Titanium (default), herdr.dev and Herdr's built-in themes, or follow your Herdr theme.
+  **English and French** interface.
+
+## Configuration
+
+All settings are environment variables: `KEY=VALUE` lines in `~/wherdr/wherdr.env` for the
+native service (read at each start: `wherdr restart`, or **R** in the panel).
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `PORT` | `7683` | Listening port. |
+| `HOST` | `127.0.0.1` (`npm start`) | Listening address: loopback, or this machine's tailnet address (`tailscale ip`, with Tailscale running). Any other address (`0.0.0.0`, a LAN address) stops wherdr at startup unless `WHERDR_TRUSTED_NETWORKS` covers it. |
+| `WHERDR_TRUSTED_NETWORKS` | *(empty)* | Other private networks wherdr accepts besides this computer and the tailnet, as comma-separated CIDR ranges or addresses (e.g. `10.147.17.0/24` for ZeroTier). `any` accepts every network, with a warning at startup and in the app: not recommended. See [Network access](security.md#network-access). |
+| `HOST_LABEL` | server hostname | Name of this machine in the app (can be renamed in the app). |
+| `APP_URL` | *(empty)* | App address and allowed host; a valid HTTPS URL enables Web Push. HTTP, empty or invalid values disable Web Push with a warning. With Tailscale, leave it empty: wherdr adopts the address `tailscale serve` publishes. |
+| `TAILNET_REFRESH_MS` | `30000` | How often wherdr reads again what `tailscale serve` publishes for its port. |
+| `HERDR_WEB_ALLOWED_HOSTS` | *(empty)* | Additional hostnames or IP addresses allowed to open the app, comma-separated. |
+| `PASSKEY_USER` | `wherdr` | User name stored with the passkeys. |
+| `DATA_DIR` | `./data` | VAPID keys, push subscriptions, passkeys, recent folders, and `settings.json`: the display settings that follow you across devices (theme, machine bar and groups, home list, Board and file browser preferences). Screen-dependent ones (content width, sidebar width, terminal size and rendering), the language, the last tab or filter and drafts stay in each browser. |
+| `HERDR_BIN` | `~/.local/bin/herdr`, else `herdr` in `PATH` | Herdr binary. |
+| `HERDR_WEB_SESSION` | *(default session)* | Named Herdr session to drive. Not `HERDR_SESSION`, which Herdr reads itself. |
+| `HERDR_PROJECTS_DATA_DIR` | `~/.herdr-projects/data` | herdr-projects' data folder, where wherdr reads the `PATH` it recorded ([Agent PATH](installation.md#agent-path)). |
+| `AGENT_KINDS` | all known agents | Agents offered in **New** (only installed ones are shown). |
+| `HERDR_WEB_MACHINES` | `on` | `off` to ignore the SSH machines registered in Herdr. |
+| `HERDR_WEB_SELF_HOSTS` | | Other names / IPs of this machine, comma-separated (profiles pointing to it are ignored). |
+| `HERDR_WEB_REMOTE_SESSION` | | Herdr session to use on every remote machine instead of the profile's. |
+| `HERDR_WEB_HERDR_NOTIFICATIONS` | `on` | `off` to stop relaying `herdr notification show` as push. |
+| `UPLOAD_DIR` | `~/.cache/herdr-web/uploads` | Where photos sent to agents are stored (deleted after 7 days). |
+| `ATTACH_DIR` | `~/.cache/herdr-web/files` | Where other files attached to messages are stored, on the agent's machine (mode 600, deleted after 7 days). |
+| `TZ` | `UTC` | Time zone. |
+
+In the app, **Settings** holds display preferences such as theme, typing effect and what the
+home screen shows; these follow you across devices through `settings.json`. Language,
+notifications, terminal text size and renderer remain device-specific. The passkey lock is
+managed under Settings › Security.

package/docs/conversation.md

@@ -0,0 +1,132 @@
+# Conversation and replies
+
+[Documentation](README.md) · [Project](../README.md)
+
+- **Conversation view**: the agent's real transcript (Claude Code, Codex and omp), rendered as
+  Markdown, with grouped tool calls, images (full-screen viewer with pinch / wheel zoom and pan), timestamps, search and infinite scroll back to the
+  first message. Reading a conversation never touches the terminal, so it never resizes a pane.
+  A command the agent proposes (shell code block, or inline `! command`) can be copied without
+  its prompt, or run in the agent's shell mode (`!`, Claude Code, Codex and omp) after you
+  confirm the full command.
+- **Interactive agent screens**: in a conversation, an uncertain menu or panel opens the
+  pane's real terminal in a modal window, with arrows, Enter, Escape, Tab, digits and y/n.
+  The rest of the app waits behind a scrim (the window fills the screen on a phone); in a
+  split, only the cell in use opens it. It closes after the agent's message field returns.
+  Close it yourself at any time with its button or a click on the scrim: that releases the
+  terminal without pressing Escape, which goes to the agent, and the same interaction stays
+  closed until you reopen it. Existing native questions, approvals, menus, waiting screens and
+  Claude settings cards keep their controls. The window is a fallback after those
+  recognizers, with two explicit exceptions: Codex's two-column `/usage` menu and
+  its Agent Command Center. The slash menu still lists and sends commands. On a phone, the window
+  temporarily fits the real pane to its width and restores its size on release, using
+  the same lease as Terminal view; it does not shrink 120 columns into unreadable text.
+  A pane already shown in Terminal keeps its existing live view. Try `/usage` on the
+  Codex agent in the browser demo (scripted, no account data).
+  In the compact list, native questions keep their preview and one-tap answers.
+  Unrecognized blocking screens offer an **Open interactive terminal** button.
+- **Composer**: send messages while the agent works (queued, cancellable: the agent's own
+  queue when it takes them, else held by wherdr and sent when the turn ends; never left
+  half-typed in its field; a message pulled back out of Claude's queue before it read it, or not seen after an hour, is
+  marked “Not sent” with Retry / Cancel, and “Not sent” clears once the message shows in its transcript), attach or paste
+  photos and the files the agent can read (Claude Code: PDFs, notebooks, text and code of any
+  extension; Codex: notebooks, text and code), run slash commands (`/compact`, `/clear`, `/context`, `/usage`…) and see the output
+  of local commands. Stop button while the agent works. When Claude Code suggests a reply
+  (grayed-out in the empty field), `Tab` takes it on a computer and **Use**, inside the field on
+  its right, on a phone: the field gets the text, to edit or send. A long pasted text (log, output) becomes
+  a "Pasted text · N lines" card, sent to the agent as it is and shown the same way in the
+  conversation, where it opens in full with Copy; long typed messages fold with Show more.
+  The draft (text, quotes, attachments) is kept per agent, across reloads: when Herdr closes a
+  pane and opens a new one for the same agent (the same conversation, or the same herdr-projects
+  coordinator or task, as after `coordinator restart`), the view moves to the new pane and the
+  draft comes along. A pane closed for good keeps it under its banner, with **Copy draft**.
+- **Model and effort pickers** for Claude Code, Codex and omp (omp: its
+  "Switch Model" selector, `/switch` or `/model`, and its thinking level, changed with its own
+  ⇧⇥ cycle). Changes apply **to the current session only**; wherdr never changes your default
+  model.
+**Settings › Conversation › Reply style** chooses how an agent's reply offers to be quoted in
+the field, question by question and point by point (a list item or a paragraph that asks
+nothing), so that one message answers them all:
+
+| Style | A question | A point |
+| --- | --- | --- |
+| **Icon** (default) | A small `↳` after it, in the middle or at the end of the message. | A grey `↳` at its end: on hover on a computer, always there and pale on a phone. |
+| **Tap the text** | No button: the question is underlined, tap or click it. | Click it on a computer. On a phone, tap it, then **↳ Discuss**: a single tap never quotes, so reading, scrolling and selecting text stay as they are. |
+| **List under the message** | A number after it, and the questions listed under the message. | **+ Quote a point** under the message, then the point. Offered when the reply has a list item to quote, or two points or more: not under one paragraph of prose. |
+
+Every one of these is a button reachable with the keyboard (`Tab`, then `Enter`), and selecting a
+passage still offers **Reply** on it. A quoted question or point shows `✓`.
+
+**One syntax for every reference.** Whatever you reply to, the field gets one line that names it,
+and your answer goes on the lines below:
+
+```
+↳ Quote message 11:37 ~k3f : I can merge the PR —
+Go ahead.
+↳ Quote point 11:37 ~k3f : Shall I tag the release today? —
+Yes
+↳ Quote decision 11:37 #3 ~k3f : Publish the release notes on the site? —
+No
+```
+
+| Line | Written by |
+| --- | --- |
+| `↳ Quote message <time> ~<code> : <start of the message> —` | **Reply** under an agent message. |
+| `↳ Quote point <time> ~<code> : <excerpt> —` | `↳` on a question or a point, **Reply** on a selected passage. |
+| `↳ Quote decision <time> #<n> ~<code> : <question> —` | **Yes**, **No** or `↳` on a row of a decision table. |
+| `↳ Quote decisions <time> #<rows> ~<code> : <questions> —` | **OK to all** on a decision table. |
+
+- The time is the one shown on the agent's message, so an answer to an earlier message is never
+  read as an answer to the last one. The types are the same words in every language.
+- The code after `~` is three characters wherdr derives from the message (and the rank of the
+  table, from the second table of a message on). It tells apart two messages of the same minute
+  and two tables of one message, whatever the excerpt shows. The field draws it dimmed, like
+  the words before the excerpt; the quote of a sent message leaves it out. The rows of **OK to
+  all** are the numbers the table really has: `#1-4`, or `#1,4` when rows 2 and 3 do not exist.
+- A reference is a whole line: it starts with `↳` in the first column and ends with ` —` at the
+  end of the line, and only there, so an excerpt may hold dashes of its own. The excerpt is plain
+  text on one line; a long one is cut with `…` (a message keeps its start, a passage its start
+  and its end).
+- Several references fit in one message, each followed by its answer.
+- Anything else is your own text: a `>` at the start of a line, a `↳` line of an unknown type or
+  with words after its dash. Text you paste never becomes a reference either: a pasted line that
+  reads like one gets a `\` before its `↳`. A long paste, shown as a **Pasted text** card, is
+  sent exactly as it was pasted.
+- In the conversation, each reference of a sent message shows as a quote; tap it to see the
+  message it names. Messages sent earlier with `> ` lines still show as quotes.
+
+**Settings › Conversation › Quoted replies** chooses how the field shows these lines: **Tokens,
+native field** (default) draws each one as a token in the usual field, **Plain text** shows the
+same lines as text, a fallback if the tokens misbehave. The message sent is the same.
+
+A **closed question**, one that yes or no answers in full, also gets **Yes** and **No** next to
+its `↳` (at the end of its row in the list style). A tap refers to the question and writes the
+answer under it, in the language of the interface, exactly as Reply and typing would; nothing is sent, so several questions can be
+answered in a row before sending. On a computer a click hands the field the focus, the caret
+right after the answer, so Enter sends it at once; the keyboard stays down on a phone, and a
+button pressed with the keyboard keeps the focus. Tapping the other answer
+replaces the first; words you typed under a quote are never replaced. The rule is cautious, and
+in doubt only Reply is offered: a single sentence that opens like a yes/no question (`Shall I…`,
+`Do you…`, `Is it…`, `Want me to…`, `Est-ce que…`, `Je lance… ?`, `On…`, `Dois-je…`) or ends
+with `, OK?` / `, d'accord ?`, with no alternative (`or`, `ou`), no interrogative word (`which`,
+`how`, `quel`, `comment`…) and no negation.
+
+A **decision table**, a Markdown table whose rows are numbered questions as a coordinator writes
+them, gets a panel right under it: **OK to all** refers to the whole table and writes `OK to all`
+under it (a second tap takes it back), and each row has **Yes**, **No** and `↳`, which refer to
+the row by its number and write `Yes` or `No` under it, or nothing for an answer in words; a row
+that asks an open question has `↳` alone. Every answer names the message and the row, even for
+the last message: the agent may write another one before you send. In French: `OK tout`, `Oui`,
+`Non`. Here too everything is composed in the field and you send; on a computer the field takes the focus
+after a click, so Enter sends. A table qualifies when it has a
+number column (a header `#`, `N°`, `No`, `Num`, `ID` or `Q` over short numbers, each once) and a
+question column, known by its header (`Question`, `Decision`, `Choix`…), by cells that all end
+with `?`, or by an advice column next to it (`Avis`, `Recommendation`, `Suggestion`…). Any other
+table is left as it is.
+
+Above the field, **N questions unanswered** counts the questions of the agent's last message
+(and the rows of its decision tables) that your draft does not answer yet; tap it to scroll to
+the first one. A question counts once it is quoted, a row once it is answered, quoted or covered
+by **OK to all**; when the message asks one thing only, any words you type answer it. The line
+goes when everything is answered and when you send, and it never shows for earlier messages,
+while the agent is working, or while it waits on a prompt. It hangs from the top edge of the
+field, so nothing moves when it comes or goes.

package/docs/development.md

@@ -0,0 +1,38 @@
+# Development and tests
+
+[Documentation](README.md) · [Project](../README.md)
+
+### From source
+
+For development, or to run a checkout of your own. With Herdr running, Git and Node.js 22 on the same machine:
+
+```sh
+git clone https://github.com/afloury/wherdr.git
+cd wherdr
+npm ci
+npm run build
+npm start                  # listens on 127.0.0.1:7683
+```
+
+Open `http://localhost:7683` in a browser on that computer: the desktop layout, passkeys and the
+installable app work there, since browsers treat `localhost` as secure. There is no phone access
+and no push notification in this setup; for that, use the [recommended setup](networks.md#recommended-always-on-server--tailscale) (or publish this
+instance with `tailscale serve` as described there and start it with
+`APP_URL=https://server.example.ts.net:7683/ npm start`).
+
+Run it as the user who runs Herdr. It uses `$HOME` and `$HOME/.local/bin/herdr`, or `herdr` from
+the `PATH` (Homebrew); set `HERDR_BIN` otherwise. `DATA_DIR` holds passkeys, push data and recent
+folders (default `./data`). `npm start` listens on `127.0.0.1` (`HOST`) and port `7683` (`PORT`).
+The first-passkey bootstrap token is printed in its output. Keep the process running with your
+usual service manager (systemd user unit, launchd, tmux…).
+
+With `APP_URL` empty or `http://localhost:7683/`, wherdr starts normally but disables Web Push
+and logs a warning.
+
+## Contributing
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md), including the [agent test rule](../CONTRIBUTING.md#agent-test-rule)
+and `npm run test:affected -- --base origin/v2 --dry-run`. Changes are listed in [CHANGELOG.md](../CHANGELOG.md).
+
+Every commit is public: a leak check (gitleaks plus your own forbidden patterns) covers the files
+and the commits about to be pushed; see [Leak check](../CONTRIBUTING.md#leak-check).