diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 4420e38..eab6ce0 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "sidemux",
-  "description": "Delegate commands to tmux sidecar panes — token-efficient run/wait/read for AI coding agents.",
+  "description": "Delegate token-heavy commands to live tmux panes: an efficient run/wait/read loop for AI coding agents.",
   "owner": {
     "name": "Tom Ford",
     "email": "me@tomfordweb.net"
@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "sidemux",
-      "description": "Delegate long-running commands to tmux panes: blocking waits, incremental reads, exit-code detection.",
+      "description": "Delegate token-heavy commands to live tmux panes: an efficient run/wait/read loop for AI coding agents.",
       "source": "./",
       "category": "productivity"
     }
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index a329a24..db8d65a 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "sidemux",
-  "description": "Delegate commands to tmux sidecar panes. run/wait/read tools that replace token-burning polling loops with one blocking call and incremental output reads.",
+  "description": "Delegate token-heavy commands to live tmux panes: an efficient run/wait/read loop for AI coding agents.",
   "author": {
     "name": "Tom Ford",
     "email": "me@tomfordweb.net"
diff --git a/AGENTS.md b/AGENTS.md
index 178b933..cda49cd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,14 +4,16 @@
 
 Run these through the sidemux **`run`** MCP tool, not the Bash tool — long output stays in a tmux pane and you get an incremental tail:
 
-- `pnpm test` → `run { command: "pnpm test" }`
-- `pnpm lint` → `run { command: "pnpm lint" }`
-- `pnpm typecheck` → `run { command: "pnpm typecheck" }`
-- `pnpm build` → `run { command: "pnpm build" }`
-- `pnpm dev` → `run { command: "pnpm dev", background: true }` then `wait { until: "pattern", … }`
+- `pnpm test` → `run { command: "pnpm test", description: "<why>" }`
+- `pnpm lint` → `run { command: "pnpm lint", description: "<why>" }`
+- `pnpm typecheck` → `run { command: "pnpm typecheck", description: "<why>" }`
+- `pnpm build` → `run { command: "pnpm build", description: "<why>" }`
+- `pnpm dev` → `run { command: "pnpm dev", description: "<why>", background: true }` then `wait { until: "pattern", … }`
 
 Any other heavy or long-output command — full test suites, linters, type checkers, builds, e2e runs, dev servers — should also go through `run`, even when it isn't listed above (`background: true` for servers/watchers you keep alive).
 
-Prefer the current visible tmux session/window when one is available. If the tool can target an existing pane there, reuse it instead of creating a fresh pane. Panes are reused across runs — rerun a command and it lands back in the same pane (its header shows the command and pane id). `background: true` is for servers/watchers you keep alive and later `kill`; add `close: true` only when you truly want the pane gone afterward.
+Every `run` requires a `description` — one line of context for the human watching the panes: "<stage> due to <reason>" (e.g. "typecheck gate before release", "run scripts at user request"). It shows in the pane header and dashboard.
+
+Panes are reused across runs — rerun a command and it lands back in the same pane (its header shows the command and pane id). `background: true` is for servers/watchers you keep alive and later `kill`; add `close: true` only when you truly want the pane gone afterward.
 
 <!-- END sidemux-delegate -->