docs(autonomous-agents): add the agent multiplexer page

[JacobPEvans-personal]

Adds autonomous-agents/herdr.mdx — the reader-facing page for herdr, the agent multiplexer now running on the fleet. Completes the set with dryvist/nix-ai#1836, dryvist/tofu-proxmox#1038 and dryvist/ansible-proxmox-ai#599.

What the page covers

• Why it exists — running 3–10 coding agents in plain tmux gives no visibility into which one is blocked, no way to drive them from a script, and ends the work when the laptop closes.
• Three containers, and why — a crash in the Slack bridge must not touch the runtime holding live agent panes. Table of what each does and whether it is reachable from outside.
• Talking to it from Slack — framed against the existing self-hosted agent page, since it is the same interaction model. Includes why herdr needs its own Slack app rather than a shared one.
• One config, two places — the same flake produces the workstation and server configs from the same binaries.
• Why the CLIs moved to Nix — Homebrew is macOS-only, which is what tied the whole stack to one laptop.
• Exposure — why the upstream project's free hosted tunnel is deliberately unused: that dashboard can approve a running agent's actions, so it goes through the estate's own gate.
• Two sharp edges — herdr's integration install writes into Nix-generated read-only config, and herdr fetches detection updates from the internet at runtime and applies them without a restart.

Conventions

• Public information only. No addresses, no internal names, no ports, no private-repo references — checked with a grep before commit. Services are described by role ("the SSO gate", "an internal name") rather than named.
• Inline Mermaid with the byte-for-byte theme directive from conventions/mermaid-style, classDef palette, and 7 nodes — well inside the density cap.
• Active voice, second person, sentence-case headings, one idea per sentence, aimed at the 8th-grade target. Plain words over Latinate ones throughout.
• page_type: explanation, registered in docs.json under Autonomous agents (a one-line nav insert — no reformatting of the file).
• Cross-links to hermes-agent, runtime and secrets.

Validation — not run here

This session had no mint binary. docs.json is verified to still parse as JSON, and the nav diff is a single line. Before merge:

mint broken-links
mint dev          # eyeball the Mermaid render

The four cross-links (/autonomous-agents/hermes-agent, /autonomous-agents/runtime, /autonomous-agents/secrets, /local-llm/overview) all correspond to pages present in the repo, but mint broken-links is the real check.

---

Generated by Claude Code

---

Note

Low Risk
Documentation-only change (new MDX + one nav line); no application or infrastructure code paths are modified.

Overview
Adds a new Autonomous agents doc page for herdr — how the fleet runs it as a homelab service (runtime, Slack bridge, SSO-gated dashboard), why it is split across three LXCs, Nix-backed workstation/server config, and operational caveats (integration install, runtime detection updates).

The page includes a themed Mermaid architecture diagram, a container table, Slack interaction notes (separate Slack app vs Hermes), and links to hermes-agent, runtime, and secrets. docs.json registers autonomous-agents/herdr in the nav immediately after runtime.

^{Reviewed by Cursor Bugbot for commit cd4dee3. Bugbot is set up for automated code reviews on this repo. Configure here.}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_4781d044-4106-4148-985a-527a86cebbd0)

[gemini-code-assist]

Code Review

This pull request adds a new documentation page for the herdr agent multiplexer, explaining its architecture, Slack integration, and Nix configuration, as well as updating the documentation index. The reviewer suggests updating the section on herdr's runtime updates to explicitly recommend disabling this behavior to align with declarative infrastructure-as-code principles.

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_d08370f2-3b80-4501-bf3b-c3bf6b2e6ca2)