docs: finalize release docs and add runtime blog

1 files changed, 62 insertions, 26 deletions

diff --git a/website/src/content/docs/agents.mdx b/website/src/content/docs/agents.mdx
index d224e37b..49f64881 100644
--- a/website/src/content/docs/agents.mdx
+++ b/website/src/content/docs/agents.mdx
@@ -7,39 +7,71 @@ Herdr is built for running more than one coding agent at a time. Each agent stay
 
 ## Supported agents
 
-Automatic detection works out of the box for common coding agents.
+Automatic detection works out of the box for common coding agents. The important difference is not whether Herdr can see an agent. It is which signal is allowed to author `idle`, `working`, and `blocked`.
 
-| Agent | Idle / done | Working | Blocked |
-| --- | --- | --- | --- |
-| Pi | yes | yes | partial |
-| Claude Code | yes | yes | yes |
-| Codex | yes | yes | yes |
-| Droid | yes | yes | yes |
-| Amp | yes | yes | yes |
-| OpenCode | yes | yes | yes |
-| Grok CLI | yes | yes | yes |
-| Hermes Agent | yes | yes | yes |
-| Kilo Code CLI | yes | yes | yes |
-| Cursor Agent | yes | yes | yes |
-| Antigravity CLI | yes | yes | yes |
-| Kimi Code CLI | yes | yes | yes |
-| Kiro CLI | yes | yes | no |
-| GitHub Copilot CLI | yes | yes | yes |
-| Qoder CLI | yes | yes | yes |
+| Agent | State authority | Integration role |
+| --- | --- | --- |
+| Pi | lifecycle hooks when installed; otherwise screen manifest | state and session |
+| OMP | lifecycle hooks when installed | state |
+| GitHub Copilot CLI | screen manifest | session |
+| Kimi Code CLI | lifecycle hooks when installed; otherwise screen manifest | state and session |
+| Hermes Agent | lifecycle hooks when installed; otherwise screen manifest | state and session |
+| Qoder CLI | screen manifest | session |
+| Droid | screen manifest | session |
+| OpenCode | lifecycle plugin when installed; otherwise screen manifest | state and session |
+| Kilo Code CLI | lifecycle plugin when installed; otherwise screen manifest | state and session |
+| Claude Code | screen manifest | session |
+| Codex | screen manifest | session |
+| Cursor Agent CLI | screen manifest | session |
+| Amp | screen manifest | none |
+| Grok CLI | screen manifest | none |
+| Antigravity CLI | screen manifest | none |
+| Kiro CLI | screen manifest | none |
 
-Detected but less thoroughly tested: Gemini CLI and Cline.
+Detected but less thoroughly tested: Gemini CLI and Cline. Unsupported agents still run normally as terminal processes. They just may not get rich state unless you add an integration or report state over the socket API.
 
-Unsupported agents still run normally as terminal processes. They just may not get rich state unless you add an integration or report state over the socket API.
+## Status authority
 
-## How detection works
+Herdr first detects the foreground process in each pane. After that, each pane has one status authority.
 
-Herdr combines three signals:
+For agents with complete lifecycle hooks, the integration is authoritative when it is installed and actively reporting for the running pane. Herdr uses those hook reports for `idle`, `working`, `blocked`, and session identity. It does not also run screen manifest fallback for that same lifecycle authority. This avoids two competing sources of truth.
 
-1. foreground process detection
-2. terminal output heuristics
-3. integration session identity or state reports
+For agents without complete lifecycle hooks, Herdr identifies the foreground process and reads the live bottom-buffer screen snapshot. It evaluates TOML manifests against that snapshot to classify `idle`, `working`, and `blocked`. For agents that emit them, manifests can also match terminal title and progress (OSC) sequences as detection evidence; when that evidence is absent, screen rules carry detection on their own.
 
-Process detection tells Herdr which pane owns an agent. Heuristics infer native agent state from terminal screen snapshots. Claude Code, Codex, and OpenCode integrations provide session identity for restore; Pi, OMP, GitHub Copilot CLI, Hermes Agent, Qoder CLI, and custom socket integrations can report state when they define state outside the native terminal UI.
+The screen snapshot comes from the recent bottom of the pane buffer, not the scrolled viewport. If you scroll back in Herdr, detection still follows the live agent UI at the bottom.
+
+Claude Code, Codex, GitHub Copilot CLI, Droid, Qoder CLI, and Cursor Agent CLI integrations are intentionally not lifecycle authorities. They provide native session identity for restore, but their hooks do not cover the whole lifecycle. They can miss permission approval results, escape interrupts, or other transitions. For those agents, Herdr still uses screen manifest detection.
+
+## Blocked state
+
+Blocked detection is deliberately strict for screen-manifest agents. Herdr only marks `blocked` when the live bottom-buffer snapshot matches known visible approval, question, or permission UI. If no manifest rule matches for a known agent, Herdr falls back to `idle` and labels that fallback as `default_known_agent_idle_fallback` in explain output.
+
+This means unusual new agent prompts may initially show as `idle` instead of `blocked` until Herdr learns that screen shape. Those interactions should not make Herdr send input or take destructive action; they only affect the visible status and waits.
+
+## Detection manifests
+
+Bundled manifests live inside Herdr. Herdr also checks herdr.dev for remote manifest updates and applies valid per-agent rule updates automatically without requiring a Herdr restart. Remote manifests are stored in Herdr's state directory.
+
+Local overrides can replace a remote or bundled manifest from the platform config directory:
+
+```text
+~/.config/herdr/agent-detection/<agent>.toml
+```
+
+Local overrides always win. Without a local override, Herdr uses the newer compatible manifest between the cached remote manifest and the bundled manifest in the running binary. On debug builds, the same config helper may use a development directory such as `herdr-dev`. Invalid override files are ignored with a warning and Herdr falls back to the cached remote or bundled manifest for that agent.
+
+Remote manifests patch detection rules for agents Herdr already knows how to identify. Adding a completely new agent still requires a Herdr binary update for process detection, labels, and integration behavior.
+
+The running server loads active manifests into memory on startup. Automatic remote manifest updates reload that in-memory cache after new rules are written. Run `herdr server update-agent-manifests` to fetch remote manifest updates immediately and reload the running server. After editing a local override manually, restart Herdr or run `herdr server reload-agent-manifests` to apply the file to the running server.
+
+Use `herdr agent explain` when a pane shows the wrong state:
+
+```bash
+herdr agent explain <target>
+herdr agent explain --file screen.txt --agent codex --json
+```
+
+Live explain is evaluated by the running server, so it reflects the active manifest cache. The explain output shows the agent, final state, whether screen detection was skipped by a full lifecycle authority, manifest source and version, cached remote version, local override shadowing, remote update status, matched rule, visible evidence flags, matcher and region evidence for evaluated rules, skipped-update reason for transcript viewers, and the idle fallback reason when no rule matched.
 
 Herdr can run inside tmux as the outer terminal environment. Agent detection does not inspect tmux sessions launched inside a Herdr pane. If a shell framework auto-enters tmux inside Herdr, Herdr sees `tmux` as the pane process instead of the agent behind it.
 
@@ -61,7 +93,11 @@ herdr integration install omp
 herdr integration install claude
 herdr integration install codex
 herdr integration install copilot
+herdr integration install cursor
+herdr integration install droid
+herdr integration install kimi
 herdr integration install opencode
+herdr integration install kilo
 herdr integration install hermes
 herdr integration install qodercli
 ```