docs(agents): document Herdr (closes #208) - #218

Adds a new “Herdr” documentation section to the site’s coding-agents chapter, including citations and spellcheck wordlist updates, to address issue #208.

Changes:

• Add a new tool page at chapters/ai-tools/herdr.qmd and include it from chapters/coding-agents.qmd.
• Add Herdr-related bibliography entries to references.bib.
• Extend inst/WORDLIST with new proper nouns/terms used in the Herdr write-up.

• Files reviewed: 4/4 changed files
• Comments generated: 2
• Review effort level: Lite

Suppressed comments (4)

references.bib:345

• The flaviocopes_herdr BibTeX entry is missing its note field and closing }; as written, the next @misc{oh_my_claudecode,...} starts before the previous entry closes, which will break bibliography parsing.

  howpublished = {Blog post},
  url = {https://flaviocopes.com/herdr/},
@misc{oh_my_claudecode,

references.bib:325

• For consistency with the rest of references.bib, GitHub repository citations use howpublished = {Software} (e.g., rakazo, openclaw).

  howpublished = {GitHub repository},

chapters/ai-tools/herdr.qmd:89

• Similarly, irm ... | iex executes remote content directly. Consider switching to a download-then-run pattern for the PowerShell installer as well.

```powershell
powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"

**chapters/ai-tools/herdr.qmd:85**
* The install instructions currently use a pipe-to-shell pattern (`curl ... | sh`). Since this is a docs page, it’s safer to download the script to a file (so readers can inspect it) and then run it.

The one-line installers are:

curl -fsSL https://herdr.dev/install.sh | sh

- **Files reviewed:** 4/4 changed files
- **Comments generated:** 2
- **Review effort level:** Lite
</details>

Suppressed comments (5)

references.bib:339

• howpublished is inconsistent with the rest of references.bib: GitHub repository citations use howpublished = {Software} (e.g., inflexa at references.bib:105-112).

  howpublished = {GitHub repository},

references.bib:384

• Same howpublished = {Herdr documentation} issue here: these are documentation pages and should use the existing Documentation tag used elsewhere in references.bib.

@misc{herdr_session_state,
  title = {Session state},
  author = {{herdrdev}},
  year = {2026},
  howpublished = {Herdr documentation},

references.bib:357

• These entries represent documentation pages; elsewhere in references.bib documentation is consistently tagged with howpublished = {Documentation} (e.g., references.bib:96-103). Using a custom howpublished = {Herdr documentation} breaks that convention.

@misc{herdr_agents,
  title = {Agents},
  author = {{herdrdev}},
  year = {2026},
  howpublished = {Herdr documentation},

references.bib:411

• howpublished should be consistent with other documentation citations in references.bib (use Documentation rather than Herdr documentation).

  howpublished = {Herdr documentation},

chapters/ai-tools/herdr.qmd:84

• This section suggests running remote install scripts via curl | sh and irm | iex, which executes unreviewed code. Elsewhere the docs explicitly warn against this pattern (see chapters/ai-tools/running-agents-offline.qmd:31-40). Consider switching to “download, inspect, then run” commands (and/or a caution callout) while still mentioning package-manager installs.

Herdr ships stable binaries for Linux, macOS, and Windows x86_64 [@herdr_install].
The one-line installers are:

```bash
curl -fsSL https://herdr.dev/install.sh | sh

• Files reviewed: 4/4 changed files
• Comments generated: 1
• Review effort level: Lite

Suppressed comments (5)

chapters/ai-tools/herdr.qmd:88

• These examples execute downloaded code directly (curl | sh / irm | iex), but the repository's security guidance explicitly warns readers not to do this and to save/review the script first (chapters/ai-tools/running-agents-offline.qmd:31-40). As written, this page bypasses that guardrail; show the reviewed-download flow or add the same caution before publishing these commands.

curl -fsSL https://herdr.dev/install.sh | sh

powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"

chapters/ai-tools/herdr.qmd:95

• Because the paragraph has just listed Homebrew, mise, and Nix as installation methods, this currently tells users of those package managers to run herdr update. Herdr's install documentation says herdr update is only for Herdr-managed installs; package-manager installations must be upgraded through their respective managers. Qualify this command so users do not bypass or desynchronize the package manager.

and `herdr update` to upgrade.

chapters/ai-tools/herdr.qmd:58

• The socket location is written as ~/.config/herdr/herdr.sock for both Unix and Windows, but Windows clients must address the named-pipe endpoint as \\.\pipe\herdr.sock (the platform-specific form is required by the socket API). As written, a Windows reader following this API description will try to connect to a Unix-style path; state both forms explicitly.

  speaking newline-delimited JSON over a Unix socket
  (a named pipe on Windows) at `~/.config/herdr/herdr.sock`.

chapters/ai-tools/herdr.qmd:18

• This is a factual statement without a citation, unlike the surrounding project facts. Add the repository citation to this sentence so readers can verify the language and license.

The project is written in Rust and licensed under Apache 2.0.

chapters/ai-tools/herdr.qmd:76

• This separate compatibility claim is not covered by the citation on the preceding sentence. Add the machines-documentation citation here so the Linux/macOS-only remote-server limitation is verifiable.

  Remote servers must run Linux or macOS;
  a native Windows server is not supported as an SSH target.

• Files reviewed: 4/4 changed files
• Comments generated: 2
• Review effort level: Lite