docs: finalize next release docs

1 files changed, 32 insertions, 12 deletions

diff --git a/INTEGRATIONS.md b/INTEGRATIONS.md
index ec4e4884..23b41ab8 100644
--- a/INTEGRATIONS.md
+++ b/INTEGRATIONS.md
@@ -55,6 +55,14 @@ this writes the bundled pi extension to:
 ~/.pi/agent/extensions/herdr-agent-state.ts
 ```
 
+if `PI_CODING_AGENT_DIR` is set, herdr uses that agent directory instead and writes to:
+
+```text
+$PI_CODING_AGENT_DIR/extensions/herdr-agent-state.ts
+```
+
+`~` is expanded in `PI_CODING_AGENT_DIR`.
+
 pi is the cleanest integration. it already has an authoritative hook model, so herdr can get direct state reports over the socket api without guessing as much from the terminal.
 
 bundled source: [`src/integration/assets/pi/herdr-agent-state.ts`](./src/integration/assets/pi/herdr-agent-state.ts)
@@ -65,11 +73,7 @@ uninstall:
 herdr integration uninstall pi
 ```
 
-this removes:
-
-```text
-~/.pi/agent/extensions/herdr-agent-state.ts
-```
+this removes the same extension path herdr would install, using `PI_CODING_AGENT_DIR` when it is set.
 
 ## claude code
 
@@ -84,6 +88,8 @@ this:
 - writes the hook script to `~/.claude/hooks/herdr-agent-state.sh`
 - updates `~/.claude/settings.json`
 
+if `CLAUDE_CONFIG_DIR` is set, herdr uses that directory instead, for example `$CLAUDE_CONFIG_DIR/hooks/herdr-agent-state.sh` and `$CLAUDE_CONFIG_DIR/settings.json`. `~` is expanded in `CLAUDE_CONFIG_DIR`.
+
 bundled source: [`src/integration/assets/claude/herdr-agent-state.sh`](./src/integration/assets/claude/herdr-agent-state.sh)
 
 current hook mapping:
@@ -102,6 +108,7 @@ notes:
 - claude code hooks also run inside subagents. herdr treats subagent `working` and `blocked` reports as real pane state.
 - subagent stop/release events are converted to `working` by the bundled hook script so a completed subagent does not make the parent claude pane look idle.
 - `PostToolUse` and `PostToolUseFailure` move the pane back to `working` after a permissioned tool call resolves.
+- some non-claude tools, including grok cli, may load claude settings or plugins. herdr ignores conflicting known-agent hook labels once native foreground-process detection identifies a different known agent.
 
 uninstall:
 
@@ -109,10 +116,7 @@ uninstall:
 herdr integration uninstall claude
 ```
 
-this:
-
-- removes `~/.claude/hooks/herdr-agent-state.sh`
-- removes herdr-owned hook entries from `~/.claude/settings.json`
+this removes the same hook path and settings entries herdr would install, using `CLAUDE_CONFIG_DIR` when it is set.
 
 ## codex
 
@@ -129,6 +133,8 @@ this:
 - ensures `hooks = true` under `[features]` in `~/.codex/config.toml`
 - migrates the deprecated top-level `[features] codex_hooks = true` setting to `hooks = true`
 
+if `CODEX_HOME` is set, herdr uses that directory instead, for example `$CODEX_HOME/herdr-agent-state.sh`, `$CODEX_HOME/hooks.json`, and `$CODEX_HOME/config.toml`. `~` is expanded in `CODEX_HOME`.
+
 bundled source: [`src/integration/assets/codex/herdr-agent-state.sh`](./src/integration/assets/codex/herdr-agent-state.sh)
 
 current hook mapping:
@@ -153,9 +159,9 @@ herdr integration uninstall codex
 
 this:
 
-- removes `~/.codex/herdr-agent-state.sh`
-- removes herdr-owned hook entries from `~/.codex/hooks.json`
-- intentionally leaves `~/.codex/config.toml` alone
+- removes the same hook path herdr would install, using `CODEX_HOME` when it is set
+- removes herdr-owned hook entries from the matching `hooks.json`
+- intentionally leaves the matching `config.toml` alone
 
 that last point is deliberate: herdr does **not** try to guess whether `hooks = true` is still needed for some other codex hook setup.
 
@@ -204,6 +210,20 @@ this removes:
 ~/.config/opencode/plugins/herdr-agent-state.js
 ```
 
+## grok cli
+
+herdr does not currently install a grok hook or plugin.
+
+grok is heuristic-only in herdr. herdr detects `grok` and `grok-build` from the foreground process and uses screen heuristics for `working`, `blocked`, and `idle` states.
+
+grok cli may load claude settings or plugins as a compatibility feature, including hooks from `~/.claude/settings.json`. if that causes the claude herdr hook to run in a grok pane, herdr ignores the conflicting `claude` hook label once native foreground-process detection identifies the pane as `grok`.
+
+## amp
+
+herdr does not currently install an Amp plugin.
+
+Amp's public plugin API exposes lifecycle and tool-call hooks, but not passive permission/request-blocked events. A Herdr Amp plugin that only reports `idle` and `working` would take hook authority for the pane and mask Herdr's existing screen heuristics for Amp `blocked` states. Until Amp exposes permission state as an observable plugin event, Amp remains heuristic-only in Herdr.
+
 ## known limitations
 
 - these integrations only activate inside herdr-managed panes.