diff --git a/ui-tui/README.md b/ui-tui/README.md
index 7ac186c131..bd1961dae8 100644
--- a/ui-tui/README.md
+++ b/ui-tui/README.md
@@ -66,6 +66,26 @@ npm test         # single run
 npm run test:watch
 ```
 
+## Live agents
+
+The dock above the composer appears automatically while children are running. It shows
+actual live-child counts, task names, elapsed time, and the latest activity. Its row budget
+shrinks on short terminals; finished work remains in the existing `/agents` / `/replay` history
+rather than permanently occupying composer space. Async completion units are not counted
+as extra agents.
+
+- **Ctrl+T** expands the roster without clearing your draft; **Esc** returns.
+- **↑/↓** selects an agent, **Enter** opens its details (tools, output, files, usage).
+- **t** opens its bounded live transcript tail; **g/G** moves to top/bottom.
+- **e** opens a separate steering form. **Enter** queues guidance and **Esc** returns.
+  “Queued” means accepted for the next tool boundary, not confirmed delivery.
+- **x** requests that the selected child stop; **X** requests a subtree stop.
+- Existing sort/filter, spawn-pause, timeline, and replay controls remain available.
+
+The roster hydrates from the session-scoped `subagent.list` RPC alongside streamed events.
+Only an open tail view polls `subagent.tail`; steering uses the existing `subagent.steer` RPC.
+No model tool schema or prompt-caching behavior changes.
+
 ## App model
 
 `src/app.tsx` is the center of the UI. Heavy logic is split into `src/app/`: