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

[dem-extra1]

Issue #208 asks us to document https://herdr.dev/. This PR adds a chapters/ai-tools/herdr.qmd fragment (what it does, who makes it, install/use, supported agents, pricing/license, activity, and a "Useful to us?" verdict against the lab's existing parallel-session and worktree baseline), transcluded from chapters/coding-agents.qmd after the VS Code agent-sessions section.

Closes #208

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The new Herdr page introduces a style-guide inconsistency (long comma-separated list) and recommends running remote installer one-liners without a safety note.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

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.

File summaries

File	Description
references.bib	Adds Herdr-related citation entries used by the new documentation page.
inst/WORDLIST	Adds new terms/proper nouns to satisfy the repo’s spellcheck workflow.
chapters/coding-agents.qmd	Adds a new top-level “Herdr” section and includes the new AI tool page.
chapters/ai-tools/herdr.qmd	New documentation page describing Herdr’s purpose, usage, and fit vs lab baselines.

Review details

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

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

The bibliography update introduces a malformed BibTeX entry that will break parsing, and there are a few documentation/convention fixes needed before merge.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

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>

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://Morrison-Lab.github.io/wai/pr-preview/pr-218/
Built to branch gh-pages at 2026-09-10 08:36 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[github-actions]

Claude finished review — View run

---

No keys from main were dropped during the rebuild — all 36 of main's citation keys are present in the merged 50-entry file (36 from main + 14 new herdr*/etc. keys from this PR = 50, matches exactly).

Everything checks out. This round's fix is complete and correctly targeted.

Review: PR #218 — docs(agents): document Herdr (closes #208)

What changed since the last review round (266b7cca..f4b8062a): a single fix commit, 9f03034 ("fix(bib): rebuild references.bib as a clean union after the main sync"), rebuilds references.bib from scratch as a clean union of main's entries (in main's order/formatting) plus this branch's 14 new herdr* entries appended at the end. f4b8062 is the merge commit bringing that fix in. No other files changed in this range.

Verification of the previously-blocking finding

The prior round (commit 266b7cca) flagged a malformed BibTeX entry: a bad merge-conflict resolution had dropped flaviocopes_herdr's note field and closing }, causing it to swallow the entirety of oh_my_claudecode.

I verified the fix directly against the current references.bib:

• Parsed the file with a real BibTeX parser (bibtexparser 2.0.0): 50 entries, 0 parsing failures, 0 duplicate keys.
• flaviocopes_herdr (references.bib:444-452) is now a complete, independently-closed entry with its note = {Accessed 2026-09-09} field and closing } restored.
• oh_my_claudecode (references.bib:262-269) is now a separate, complete entry, no longer absorbed as spurious fields of flaviocopes_herdr.
• Ran a full brace-balance/entry-boundary scan across the whole file: all 50 @...{...} blocks close cleanly before the next @ begins — no other entries were damaged by the rebuild.
• Diffed key sets: every one of main's 36 citation keys is still present (none dropped by the "clean union" rebuild); 50 = 36 (main) + 14 (this branch's new herdr*/awesome_herdr/coles_herdr/flaviocopes_herdr keys), exactly as expected.
• No leftover <<<<<<</=======/>>>>>>> conflict markers anywhere in .qmd/.bib/WORDLIST.
• inst/WORDLIST still passes LC_ALL=C sort -c (alphabetical order intact).
• All @herdr*, @awesome_herdr, @coles_herdr, @flaviocopes_herdr, @oh_my_claudecode citation keys used in chapters/ai-tools/herdr.qmd and chapters/ai-tools/custom-harnesses.qmd resolve to entries in the rebuilt references.bib; the other apparent "missing" keys my grep initially flagged (claude, latest, opengsd, sec, tbl) are false positives from Quarto @sec-/@tbl- cross-refs and an npm package name (@opengsd/gsd-core@latest), not bibliography citations.
• chapters/ai-tools/herdr.qmd is byte-for-byte unchanged from the already-reviewed 1a99d572 commit (no diff). chapters/coding-agents.qmd and inst/WORDLIST only picked up unrelated content from the main merge (PR docs(agents): survey custom harnesses and how to build our own (closes #112) #212's custom-harnesses material), which is out of this PR's scope and was already reviewed/merged separately.
• No _site//_freeze/ changes, no new dependencies.

I could not run pandoc/quarto render directly (neither is installed in this sandbox) to positively confirm the citeproc render, but the independent Python BibTeX parser validation gives high confidence the file is now syntactically well-formed BibTeX, which was the entire substance of the prior blocking finding.

Other checks

All findings from the two prior review rounds (1a99d572 and 266b7cca) — fact-checking against herdr.dev/YC/HN/blog sources, cross-reference resolution, bullet-list formatting, heading levels, no raw HTML — still stand as verified; nothing in this round's diff touches that content.

No new issues found.

Verdict

Ready for merge — the prior blocking finding (malformed references.bib from a bad merge-conflict resolution) has been fixed and independently re-verified with a BibTeX parser; no new issues in this round's diff.

Structured Review Data (JSON)

{
  "schema_version": "1.1",
  "reviewer": "claude",
  "commit_sha": "f4b8062a10342c25b2171ae9cb7b650eaddc4e48",
  "verdict": "CLEAN",
  "findings": [],
  "detailed_assessment": "references.bib was rebuilt in commit 9f03034 as a clean union of main and branch entries; a bibtexparser pass over all 50 entries confirms zero parsing failures and both previously-broken keys (flaviocopes_herdr, oh_my_claudecode) are now complete and independent.",
  "holistic_assessment": "The bibliography regression from the prior review round is fully resolved without dropping any of main's 36 existing citation keys, so citation rendering integration for both herdr.qmd and custom-harnesses.qmd should build cleanly with no scope creep beyond the fix."
}

Reviewed commit: 9f03034

[github-actions]

💰 Cost: $0.4678 (review) — run

[Copilot]

🟡 Changes recommended

It introduces inconsistent references.bib metadata vs. established conventions and includes unsafe “pipe-to-shell” installer instructions without the repo’s usual cautions.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review 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