docs(tools): Use {tool} role for tool-to-tool cross-references

why: The {tool} role renders links with colored safety badges, which is
more informative in the tools section than plain {ref} links.
what:
- Replace {ref} with {tool} for 14 tool cross-references across
  panes.md (7), sessions.md (5), windows.md (2)
- Keep {ref} for non-tool refs (e.g. configuration)
- Cross-file links (panes→windows) render with correct badge colors

Author: tony

docs/tools/panes.md

@@ -9,8 +9,8 @@
 after running a command, checking output, or verifying state.
 
 **Avoid when** you need to search across multiple panes at once — use
-{ref}`search-panes`. If you only need pane metadata (not content), use
-{ref}`get-pane-info`.
+{tool}`search-panes`. If you only need pane metadata (not content), use
+{tool}`get-pane-info`.
 
 **Side effects:** None. Readonly.
 
@@ -51,7 +51,7 @@ $
 **Use when** you need pane dimensions, PID, current working directory, or
 other metadata without reading the terminal content.
 
-**Avoid when** you need the actual text — use {ref}`capture-pane`.
+**Avoid when** you need the actual text — use {tool}`capture-pane`.
 
 **Side effects:** None. Readonly.
 
@@ -67,7 +67,7 @@ other metadata without reading the terminal content.
 which pane has an error, finding a running process, or checking output
 without knowing which pane to look in.
 
-**Avoid when** you already know the target pane — use {ref}`capture-pane`
+**Avoid when** you already know the target pane — use {tool}`capture-pane`
 directly.
 
 **Side effects:** None. Readonly.
@@ -116,7 +116,7 @@ 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 {ref}`capture-pane` instead, or if the
+**Avoid when** you can poll with {tool}`capture-pane` instead, or if the
 expected text may never appear (set a timeout).
 
 **Side effects:** None. Readonly. Blocks until text appears or timeout.
@@ -160,7 +160,7 @@ Response:
 terminal. This is the primary way to execute commands in tmux panes.
 
 **Avoid when** you need to run something and immediately capture the result —
-send keys first, then use {ref}`capture-pane` or {ref}`wait-for-text`.
+send keys first, then use {tool}`capture-pane` or {tool}`wait-for-text`.
 
 **Side effects:** Sends keystrokes to the pane. If `enter` is true (default),
 the command executes.
@@ -230,7 +230,7 @@ Keys sent to pane %2
 **Use when** you're done with a specific terminal and want to remove it
 without affecting sibling panes.
 
-**Avoid when** you want to remove the entire window — use {ref}`kill-window`.
+**Avoid when** you want to remove the entire window — use {tool}`kill-window`.
 
 **Side effects:** Destroys the pane. Not reversible.
 

docs/tools/sessions.md

@@ -8,8 +8,8 @@
 **Use when** you need session names, IDs, or attached status before deciding
 which session to target.
 
-**Avoid when** you need window or pane details — use {ref}`list-windows` or
-{ref}`list-panes` instead.
+**Avoid when** you need window or pane details — use {tool}`list-windows` or
+{tool}`list-panes` instead.
 
 **Side effects:** None. Readonly.
 
@@ -47,7 +47,7 @@ Response:
 **Use when** you need to verify the tmux server is running, check its PID,
 or inspect server-level state before creating sessions.
 
-**Avoid when** you only need session names — use {ref}`list-sessions`.
+**Avoid when** you only need session names — use {tool}`list-sessions`.
 
 **Side effects:** None. Readonly.
 
@@ -63,7 +63,7 @@ or inspect server-level state before creating sessions.
 container — create one before creating windows or panes.
 
 **Avoid when** a session with the target name already exists — check with
-{ref}`list-sessions` first, or the command will fail.
+{tool}`list-sessions` first, or the command will fail.
 
 **Side effects:** Creates a new tmux session. Attaches if `attach` is true.
 
@@ -137,7 +137,7 @@ Response:
 **Use when** you're done with a workspace and want to clean up. Kills all
 windows and panes in the session.
 
-**Avoid when** you only want to close one window — use {ref}`kill-window`.
+**Avoid when** you only want to close one window — use {tool}`kill-window`.
 
 **Side effects:** Destroys the session and all its contents. Not reversible.
 
@@ -152,7 +152,7 @@ windows and panes in the session.
 **Use when** you need to tear down the entire tmux server. This kills every
 session, window, and pane.
 
-**Avoid when** you only need to remove one session — use {ref}`kill-session`.
+**Avoid when** you only need to remove one session — use {tool}`kill-session`.
 
 **Side effects:** Destroys everything. Not reversible.
 

docs/tools/windows.md

@@ -8,7 +8,7 @@
 **Use when** you need window names, indices, or layout metadata within a
 session before selecting a window to work with.
 
-**Avoid when** you need pane-level detail — use {ref}`list-panes`.
+**Avoid when** you need pane-level detail — use {tool}`list-panes`.
 
 **Side effects:** None. Readonly.
 
@@ -199,7 +199,7 @@ Response:
 
 **Use when** you're done with a window and all its panes.
 
-**Avoid when** you only want to remove one pane — use {ref}`kill-pane`.
+**Avoid when** you only want to remove one pane — use {tool}`kill-pane`.
 
 **Side effects:** Destroys the window and all its panes. Not reversible.