Herdr

• Every herdr command takes its syntax from the installed binary (herdr --skill, the command group's own help, herdr api schema), never from memory or this skill.
• Control commands run only from inside a herdr pane, against an explicit target, without moving the principal's focus; anything that would stop the server, close what I did not open or answer another agent's dialog waits for an explicit yes.
• A question about local behaviour is answered from the live file that causes it, and a change lands in the file that owns it.
• Drift between the install, our config and herdr's own agent instructions is caught by Tools/Freshness.ts, not by editing this skill on every release.

Read these at use time. The installed binary outranks the website when they disagree, because the site describes the newest release.

The config reference is one large JSON file. Filter it by key:

curl -fsSL "<config reference URL from the index>" | jq --arg key 'ui.sidebar_width' '.sections[].keys[] | select(.key == $key)'

Optional: if LIFEOS/USER/CUSTOMIZATIONS/SKILLS/Herdr/ThisInstall.md exists, read it for the local pieces around herdr (config mirror, shell wrapper, passthrough maps, sidebar naming, hooks); without it, rely on the sources above.

Freshness baseline and the last accepted copy of herdr's skill text: LIFEOS/USER/CUSTOMIZATIONS/SKILLS/Herdr/ (freshness.json, upstream-skill.md). The snapshot exists only so a changed skill can be diffed; it is never the instruction source. Both files are created by Tools/Freshness.ts --accept; with no baseline the skill_hash check reports stale and says to run it. First-time setup and the commands that prove the install: Setup.md.

• Bare herdr launches or attaches the TUI. Never run it for discovery. A mutating subcommand with its arguments omitted still executes with defaults (herdr workspace create creates one). (upstream skill text)
• Control commands need HERDR_ENV=1. Outside a herdr pane the CLI still reaches the socket, and it would act on whichever pane the principal has focused. Status, config and docs work is fine from anywhere.
• herdr update, herdr server stop and a server restart take down every pane the server owns, this session included when it runs inside herdr. Check herdr agent list first and get a yes.
• The upstream repo has moved owners more than once. Take URLs from the docs index, never from memory or an old note.
• The docs index describes the newest stable release. When it names a command the installed binary lacks, the binary is behind; do not guess the syntax.
• cmd chords only reach herdr through the kitty keyboard protocol (herdr 0.8+), and a chord left unbound because another tool claims it system-wide. A "broken" key is usually one of those two.
• Workspace rows are named after the launch directory, so sessions started from home all read ~ until something renames them.
• A second agent started in a pane works in the same checkout unless a worktree was asked for.
• herdr --default-config is an incomplete key list: it shows only example theme.custom colour tokens, and it lists ui.accent after the commented [ui.sidebar.spaces] header. The exact list is the config reference JSON at the installed version tag, which Tools/Freshness.ts uses when online. herdr server reload-config can return zero diagnostics for a config the default-config check flagged.
• Theme and sidebar-layout keys are read from the client's config.toml, never from the server's. When a client attaches from another machine (a herdr remote-client-bridge process whose parent is an sshd-session), edits on this machine and herdr server reload-config change nothing on that client's screen, even though the reload reports applied. Identify the client machine before changing a colour.
• No key or mouse gesture resizes the sidebar; toggle_sidebar only collapses it (per the config reference). Width is ui.sidebar_width and ui.sidebar_max_width plus herdr server reload-config.
• The Helm rows in the Configure and Update intents (the kitty passthrough map and the shell wrapper) apply only when the Helm terminal is installed (LIFEOS/DOCUMENTATION/Terminal/Helm.md); without it, skip them.
• Herdr is AGPL. Use it as an unmodified installed binary; never vendor or fork its source into this tree.

Example 1: Hand a review to a second agent

User: "spin up codex next to me and have it review the diff"
→ Delegate
→ Codex's review, read from its settled pane and checked, is in my reply; the principal's focus never moved and the pane is closed

Example 2: A key does the wrong thing inside herdr

User: "cmd+t opens a kitty tab instead of a herdr workspace"
→ Configure
→ The answer names the cause (a missing empty kitty map or a missing user var, per Helm.md § Herdr inside Helm) and the fix lands in that file; `herdr server reload-config` ran only if config.toml changed

Example 3: After an update

User: "is herdr current?"
→ Freshness
→ Each stale check from `bun Tools/Freshness.ts` is reported with its meaning and response; a changed `herdr --skill` was diffed against the snapshot before --accept