diff --git a/docs/web-ui/agent.md b/docs/web-ui/agent.md
index 0d0cb11c..d0b35e3c 100644
--- a/docs/web-ui/agent.md
+++ b/docs/web-ui/agent.md
@@ -372,6 +372,15 @@ cost chart), doughnuts for tool / wake-source / result mix, and a
 **result-trend** stacked bar — per-bucket `result_counts` so
 error / rate-limit / compaction outcomes are visible over time
 (the doughnut shows only the window total).
+A **favorite tools** doughnut shows the most-run shell commands —
+normalised `bash_commands` heads written per bash task by the
+hive-bash-mcp capture: the basename of the *first real command*,
+looking past `cd repo &&` prefixes, env-assignments, and
+prefix-runners like `sudo` / `env` (so `cd /repo && cargo build`
+records `cargo`, not `cd`). Read via `bash_breakdown`; the card
+stays hidden until the agent has run a bash command (a missing
+`bash_commands` table degrades to an empty list), so it never
+renders an empty chart.
 A summary chip row carries window totals, plus two
 token-efficiency chips derived from the bucket sums: **cache
 hit-rate** (`cache_read` over all input-side tokens) and