docs(tools): split area pages into per-tool pages by tmux scope (#26)

why: The 7 area pages under `docs/tools/` packed 47 tools into long
documents organized by safety tier (Inspect/Act/Destroy). Every
`{tool}`…`` reference in prose pointed into section anchors on
those pages, and agents navigating the site had to scroll an area
page to find a single tool's shape. Per-tool pages align with the
Server > Session > Window > Pane hierarchy agents already reason
about, give every tool a canonical citable URL, and let the
sidebar scope itself to the area the reader is currently in.

what:
- **47 per-tool pages** organized under six tmux-scope directories:
  `docs/tools/{server,session,window,pane,buffer,hook}/`. Each
  page carries the existing `{fastmcp-tool}` directive, its "Use
  when / Avoid when / Side effects / Example" prose, and the
  matching `{fastmcp-tool-input}` directive — extracted verbatim
  from the old area pages, no rewrites.
- **Six area `index.md` pages** with `grid-item-card` summaries +
  hidden `{toctree}` so the left sidebar populates per area. The
  top-level `tools/index.md` keeps its "Which tool do I want?"
  decision tree and gains a new scope-grouped toctree.
- **`docs/conf.py` `fastmcp_area_map`** remapped from flat area
  basenames (`"pane_tools": "panes"`) to scope-index paths
  (`"pane_tools": "pane/index"`). `option_tools` / `env_tools`
  now route to `server/`; `wait_for_tools` routes to `pane/`.
- **`sphinxext-rediraffe` redirects.** Seven entries in
  `docs/redirects.txt` map every deleted area page to its new
  scope index — `tools/panes → tools/pane/index`,
  `tools/sessions → tools/server/index`, `tools/windows →
  tools/window/index`, `tools/buffers → tools/buffer/index`,
  `tools/hooks → tools/hook/index`, `tools/options →
  tools/server/index`, `tools/waits → tools/pane/index`.
  Rediraffe's check-diff builder confirms each old URL still
  resolves.
- **Three area-level intros restored** to the corresponding scope
  `index.md` after code-review caught content the mechanical
  split dropped: `buffer/index.md` now documents UUID-namespacing
  and the deliberate absence of a `list_buffers` tool (OS-
  clipboard leak prevention); `hook/index.md` explains the
  "Why no `set_hook`?" design decision (FastMCP lifespan
  teardown bypassed on `kill -9` / OOM, leak risk for persistent
  user servers); `pane/wait-for-channel.md` restores the
  `send_keys → wait_for_channel` composition pattern and the
  `; status=$?; tmux wait-for -S NAME; exit $status`
  load-bearing safety contract for edge-triggered waits.
- **One stale relative link fixed.** `pane/search-panes.md` now
  points at `../../../CHANGES` (three directories up from the
  new nesting) instead of the old `../../CHANGES`.

Supersedes the earlier, stale `docs-overhaul-april-early-2026`
branch (PR #12, closed unmerged) — re-derived from current main
rather than rebased. Uses gp-sphinx's upstream
`sphinx-autodoc-fastmcp` directives, not the local autodoc the
earlier branch proposed.

Author: tony

docs/conf.py

@@ -80,15 +80,15 @@
     "libtmux_mcp.tools.hook_tools",
 ]
 conf["fastmcp_area_map"] = {
-    "server_tools": "sessions",
-    "session_tools": "sessions",
-    "window_tools": "windows",
-    "pane_tools": "panes",
-    "option_tools": "options",
-    "env_tools": "options",
-    "buffer_tools": "buffers",
-    "wait_for_tools": "waits",
-    "hook_tools": "hooks",
+    "server_tools": "server/index",
+    "session_tools": "session/index",
+    "window_tools": "window/index",
+    "pane_tools": "pane/index",
+    "option_tools": "server/index",
+    "env_tools": "server/index",
+    "buffer_tools": "buffer/index",
+    "wait_for_tools": "pane/index",
+    "hook_tools": "hook/index",
 }
 conf["fastmcp_server_module"] = "libtmux_mcp.server:mcp"
 conf["fastmcp_model_module"] = "libtmux_mcp.models"

docs/redirects.txt

@@ -15,3 +15,10 @@
 "concepts" "topics/concepts"
 "safety" "topics/safety"
 "guides/troubleshooting" "topics/troubleshooting"
+"tools/panes" "tools/pane/index"
+"tools/sessions" "tools/server/index"
+"tools/windows" "tools/window/index"
+"tools/buffers" "tools/buffer/index"
+"tools/hooks" "tools/hook/index"
+"tools/options" "tools/server/index"
+"tools/waits" "tools/pane/index"

docs/tools/buffer/delete-buffer.md

@@ -0,0 +1,16 @@
+# Delete buffer
+
+```{fastmcp-tool} buffer_tools.delete_buffer
+```
+
+**Use when** you're done with a buffer and want to free server-side
+state. Always call this when the buffer's purpose is complete —
+tmux servers outlive the MCP process, so leaked buffers persist
+across MCP restarts.
+
+**Side effects:** Removes the named buffer from the tmux server.
+Subsequent {tooliconl}`paste-buffer` calls against the deleted name
+return `ToolError`.
+
+```{fastmcp-tool-input} buffer_tools.delete_buffer
+```

docs/tools/buffer/index.md

@@ -0,0 +1,44 @@
+# Buffer tools
+
+tmux paste buffers are a server-global namespace shared by every client on the same socket. The buffer tools in libtmux-mcp expose a narrow, agent-namespaced subset: every allocation gets a UUID-scoped name like `libtmux_mcp_<32-hex>_<logical>`, so concurrent agents (or parallel tool calls from one agent) cannot collide on each other's payloads.
+
+There is **no** `list_buffers` tool. The user's OS clipboard often syncs into tmux paste buffers, so a generic enumeration would leak passwords, tokens, and other private content the agent has no business reading. Callers track the buffers they own via the {tool}`load-buffer` returns.
+
+::::{grid} 1 2 2 3
+:gutter: 2 2 3 3
+
+:::{grid-item-card} load_buffer
+:link: load-buffer
+:link-type: ref
+Stage content into a new tmux paste buffer.
+:::
+
+:::{grid-item-card} paste_buffer
+:link: paste-buffer
+:link-type: ref
+Push a staged buffer into a pane.
+:::
+
+:::{grid-item-card} show_buffer
+:link: show-buffer
+:link-type: ref
+Read a staged buffer's contents back.
+:::
+
+:::{grid-item-card} delete_buffer
+:link: delete-buffer
+:link-type: ref
+Free the server-side state of a staged buffer.
+:::
+
+::::
+
+```{toctree}
+:hidden:
+:maxdepth: 1
+
+load-buffer
+paste-buffer
+show-buffer
+delete-buffer
+```

docs/tools/buffer/load-buffer.md

@@ -0,0 +1,44 @@
+# Load buffer
+
+```{fastmcp-tool} buffer_tools.load_buffer
+```
+
+**Use when** you need to stage multi-line text for paste — sending a
+shell script, prepared input for an interactive prompt, or content
+that's too long for a clean {tooliconl}`send-keys` invocation.
+
+**Avoid when** the text is a single command line that {tooliconl}`send-keys`
+can deliver directly. `load_buffer` allocates server-side state that
+must be cleaned up via {tooliconl}`delete-buffer`.
+
+**Side effects:** Allocates a tmux paste buffer. Use the returned
+`buffer_name` for follow-up calls. The `content` argument is redacted
+in audit logs.
+
+**Example:**
+
+```json
+{
+  "tool": "load_buffer",
+  "arguments": {
+    "content": "for i in 1 2 3; do\n  echo line $i\ndone\n",
+    "logical_name": "loop"
+  }
+}
+```
+
+Response:
+
+```json
+{
+  "buffer_name": "libtmux_mcp_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6_loop",
+  "logical_name": "loop"
+}
+```
+
+```{fastmcp-tool-input} buffer_tools.load_buffer
+```
+
+---
+
+## Paste

docs/tools/buffer/paste-buffer.md

@@ -0,0 +1,24 @@
+# Paste buffer
+
+```{fastmcp-tool} buffer_tools.paste_buffer
+```
+
+**Use when** you've staged content via {tooliconl}`load-buffer` and
+need to push it into a target pane. Use bracketed paste mode
+(default `bracket=true`) for terminals that handle it; the wrapping
+escape sequences signal "this is pasted text, not typed input".
+
+**Avoid when** the buffer name doesn't match the MCP namespace —
+`paste_buffer` refuses non-`libtmux_mcp_*` names so it cannot be
+turned into an arbitrary-buffer paster.
+
+**Side effects:** Pastes content into the target pane (the pane's
+shell receives the bytes as input). Open-world: the resulting shell
+behavior is whatever the pasted bytes invoke.
+
+```{fastmcp-tool-input} buffer_tools.paste_buffer
+```
+
+---
+
+## Inspect

docs/tools/buffer/show-buffer.md

@@ -0,0 +1,17 @@
+# Show buffer
+
+```{fastmcp-tool} buffer_tools.show_buffer
+```
+
+**Use when** you need to confirm what was staged before pasting, or
+to read back a buffer between modifications. Restricted to
+MCP-namespaced buffers — non-agent buffers are rejected.
+
+**Side effects:** None. Readonly.
+
+```{fastmcp-tool-input} buffer_tools.show_buffer
+```
+
+---
+
+## Clean up

docs/tools/buffers.md

@@ -0,0 +1,36 @@
+# Hook tools
+
+tmux hooks let you attach commands to lifecycle events — `pane-exited`, `session-renamed`, `command-error`, and so on. libtmux-mcp exposes **read-only** hook introspection so agents can audit what hooks the human user has configured before running automation that might trigger them.
+
+## Why no `set_hook`?
+
+Write-hooks are deliberately not exposed. tmux servers outlive the MCP process, and FastMCP's `lifespan` teardown runs only on graceful SIGTERM/SIGINT — it's bypassed on `kill -9`, OOM-kill, and C-extension-fault crashes. Any cleanup registry in Python could be silently bypassed, leaking agent-installed shell hooks into the user's persistent tmux server where they would fire forever. Three plausible future paths exist (a tmux-side `client-detached` meta-hook for self-cleanup, requiring `LIBTMUX_SAFETY=destructive`, or exposing one-shot `run_hook` only); none is in scope.
+
+Until one of those paths is implemented, the surface here is visibility only.
+
+## Inspect
+
+::::{grid} 1 2 2 3
+:gutter: 2 2 3 3
+
+:::{grid-item-card} show_hooks
+:link: show-hooks
+:link-type: ref
+Enumerate bindings at a scope.
+:::
+
+:::{grid-item-card} show_hook
+:link: show-hook
+:link-type: ref
+Inspect a single binding.
+:::
+
+::::
+
+```{toctree}
+:hidden:
+:maxdepth: 1
+
+show-hooks
+show-hook
+```

docs/tools/hook/index.md

@@ -0,0 +1,14 @@
+# Show hook
+
+```{fastmcp-tool} hook_tools.show_hook
+```
+
+**Use when** you know which hook you want to inspect by name. Returns
+empty when the hook is unset; raises `ToolError` for unknown hook
+names (typos, wrong scope) so input mistakes don't masquerade as
+"nothing configured".
+
+**Side effects:** None. Readonly.
+
+```{fastmcp-tool-input} hook_tools.show_hook
+```