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

[tony]

Summary

Split the 7 area pages (tools/{panes,sessions,windows,buffers,hooks,options,waits}.md) into 47 per-tool pages organized by tmux scope: docs/tools/{server,session,window,pane,buffer,hook}/. Each scope has an index.md with a grid-item-card overview and a hidden {toctree} so the sidebar populates when that area is open.

Supersedes #12 (closed unmerged earlier today — audit showed most of its commits had already landed on main via different routes and the remainder conflicted with main's drift). This PR re-derives the per-tool structure from current main, uses gp-sphinx's upstream sphinx-autodoc-fastmcp directives rather than a vendored copy, and keeps existing {tool}\…`` cross-refs working because the ref labels are auto-created by the directive regardless of which page hosts it.

Navigation shape

• tools/index.md — overview + "Which tool do I want?" decision tree + grid cards + hidden toctree → 6 area indexes.
• tools/<area>/index.md — one per scope (server, session, window, pane, buffer, hook) with grid cards → per-tool pages + hidden toctree for sidebar.
• tools/<area>/<tool>.md — one per tool. Contains the existing {fastmcp-tool} directive + "Use when / Avoid when / Side effects / Example" prose + {fastmcp-tool-input} directive, copy-pasted unchanged from the old area pages.

Mapping (42 tools from old area pages → new scope)

Old area page	Tools	New location
sessions.md	list_sessions, list_servers, get_server_info, create_session, kill_server	server/
sessions.md	rename_session, select_window, kill_session	session/
windows.md	list_windows, create_window	session/
windows.md	list_panes, split_window, rename_window, select_layout, resize_window, move_window, kill_window	window/
panes.md	all 18 pane tools	pane/
waits.md	wait_for_channel, signal_channel	pane/
options.md	show_option, set_option, show_environment, set_environment	server/
buffers.md	all 4 buffer tools	buffer/
hooks.md	show_hooks, show_hook	hook/

Config + redirects

• docs/conf.py — fastmcp_area_map remapped from old area basenames to new area-index paths ("pane_tools": "pane/index", etc.). option_tools / env_tools now map to server/index; wait_for_tools maps to pane/index.
• docs/redirects.txt — 7 new sphinxext-rediraffe entries redirect every old URL:
  ```
  "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 every deletion has a redirect; build log shows (good) for each.

What did not change

• Tool prose, examples, input-field docs, safety-tier badges — all verbatim from the old area pages.
• The {tool}\…`role,{fastmcp-tool}directive,{fastmcp-tool-input}` directive — same usage, same rendering, same ref labels (auto-generated by the upstream autodoc).
• docs/tools/index.md body (the "Which tool do I want?" guide + grids) — unchanged; only the toctree at the bottom was updated.
• No code in src/libtmux_mcp/. No tests.

Test plan

• uv run ruff check . --fix --show-fixes — all checks passed
• uv run ruff format . — no changes
• uv run mypy — success, no issues
• uv run py.test --reruns 0 -vvv — 366 passed
• just build-docs — build succeeded, zero warnings (one stale ../../CHANGES relative link in search-panes.md fixed to ../../../CHANGES for the new depth)
• Rediraffe redirect check — every removed/renamed page has a matching entry; no build failure from the check-diff builder

Out of scope (deferred)

• The badge-strip monkey-patch from the closed docs: Overhaul documentation with autodoc directives and per-tool pages #12 (c729553 docs(style): Strip badges from sidebar) was not re-derived. Current build doesn't show leak; if sidebar badge leakage reappears in production, a follow-up PR can contribute the fix upstream to gp-sphinx rather than vendoring.
• Local autodoc directives proposed in closed docs: Overhaul documentation with autodoc directives and per-tool pages #12 (f0ee3d0) were not re-derived — already provided by gp-sphinx==0.0.1a9's sphinx-autodoc-fastmcp package.

Closes none (PR #12 was already closed unmerged with rationale).

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.91%. Comparing base (bd0ad2f) to head (ca17bbc).

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #26      +/-   ##
==========================================
+ Coverage   86.67%   86.91%   +0.23%     
==========================================
  Files          38       38              
  Lines        1719     1719              
  Branches      204      204              
==========================================
+ Hits         1490     1494       +4     
+ Misses        169      166       -3     
+ Partials       60       59       -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tony]

Code review

Ignoring the temp [do not merge] commit d17c648 per the review scope.

Found 1 issue:

1. docs/tools/buffer/index.md drops the page-level design rationale that old buffers.md carried — specifically the UUID-namespacing explanation (concurrent-agent safety) and the deliberate absence of a list_buffers tool (OS-clipboard leak prevention). Commit message claims "No content was rewritten; no prose lost" but grep for agent-namespaced / UUID / list_buffers under docs/tools/ post-split returns zero hits. Content not recoverable elsewhere in the user-facing docs (module docstrings have it, but they're not rendered user documentation at an area-index level).

libtmux-mcp/docs/tools/buffer/index.md

Lines 1 to 5 in d17c648

	# Buffer tools
	Paste-buffer tools — stage, push, inspect, and delete MCP-namespaced tmux buffers for multi-line input.
	::::{grid} 1 2 2 3

Recommend hoisting the old intro into buffer/index.md (under a ## Safety notes or similar heading) so the rationale stays visible to agents browsing the area index.

Two other content-loss concerns — the old hooks.md "Why no set_hook?" H2 (scored 72) and the waits.md ; status=$?; tmux wait-for -S NAME; exit $status safety idiom intro (scored 78) — fell below the 80-threshold for separate flagging. Both are substantive but preserved at the module-docstring level (hook_tools.py, wait_for_tools.wait_for_channel), so rendered per-tool pages likely still carry the core content via {fastmcp-tool} autodoc.

One soft UX note (score 58, not flagged): redirects.txt line 19 routes old tools/sessions to tools/server/index. Defensible given the new taxonomy (session-lifecycle tools now live under server), but a sibling tools/session/index exists — bookmark users may be surprised. Bidirectional "See also" cross-links in both area indexes would fully resolve.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}