docs(fix[panes]): Fix wait_for_text guidance that contradicts core teaching

why: "Avoid when you can poll with capture-pane" contradicted prompting.md,
gotchas.md, and recipes.md which all identify polling as the anti-pattern.
For MCP agents, polling also exhausts the LLM context window.
what:
- Reframe "Avoid when" around timeout/never-appearing text risk
- Preserve capture_pane as fallback for known-delay scenarios

Author: tony

docs/tools/panes.md

@@ -146,8 +146,10 @@ Response:
 **Use when** you need to block until specific output appears — waiting for a
 server to start, a build to complete, or a prompt to return.
 
-**Avoid when** you can poll with {tooliconl}`capture-pane` instead, or if the
-expected text may never appear (set a timeout).
+**Avoid when** the expected text may never appear — always set a reasonable
+`timeout`. For known output, {tooliconl}`capture-pane` after a known delay
+may suffice, but `wait_for_text` is preferred because it adapts to variable
+timing.
 
 **Side effects:** None. Readonly. Blocks until text appears or timeout.