feat(docs[_ext]): add fastmcp_autodoc Sphinx extension for MCP tool docs

why: MCP tool documentation was hand-maintained and prone to drift from
source code. Tool parameter tables, safety tiers, and descriptions need
to stay in sync with the actual function signatures and docstrings.

what:

Extension (docs/_ext/fastmcp_autodoc.py):
- fastmcp-tool directive: autodoc a single tool as a ToC-visible section
  with safety badge (floated top-right), one-line description from docstring
- fastmcp-tool-input directive: emit parameter table + return type,
  placed after hand-written judgment content (Use when / Avoid when)
- fastmcp-toolsummary directive: grouped summary tables by safety tier
  (Inspect / Act / Destroy) with cross-reference links
- Collects all 27 tools from source at build time via mock FastMCP collector
- Strips | None from optional parameter types
- Splits union types into comma-separated <code> elements for clean wrapping
- Cleans up t.Literal[...] and Literal[...] to bare quoted values
- Parses RST inline markup in docstring descriptions via state.inline_text()
- All output via docutils node API — tables, sections, badges are proper nodes

Tool area pages (docs/tools/):
- sessions.md: list_sessions, get_server_info, create_session, rename_session,
  kill_session, kill_server
- windows.md: list_windows, list_panes, create_window, split_window,
  rename_window, select_layout, resize_window, kill_window
- panes.md: capture_pane, get_pane_info, search_panes, wait_for_text,
  send_keys, set_pane_title, clear_pane, resize_pane, kill_pane
- options.md: show_option, show_environment, set_option, set_environment
- Each tool has: Use when / Avoid when, Side effects, JSON example,
  auto-generated Input table at section end

Scan layer (docs/tools/index.md):
- Hand-written card grid grouped by Inspect / Act / Destroy
- Links to area pages for each of the 27 tools

CSS (docs/_static/css/custom.css):
- .tool-safety-badge floats badge top-right, drops to own row on narrow screens

Tests (tests/docs/_ext/test_fastmcp_autodoc.py):
- 28 tests covering: docstring parsing, annotation formatting, Literal cleanup,
  union type splitting, table construction, badge classes, tool collection,
  parameter extraction, integration with real libtmux_mcp tools

Author: tony

docs/_ext/fastmcp_autodoc.py

@@ -232,3 +232,8 @@ img[src*="codecov.io"] {
 ::view-transition-new(root) {
   animation-duration: 150ms;
 }
+
+/* ── MCP Tool safety badges ──────────────────────────────
+ * Badge sits inline next to the tool name in the heading.
+ * Slight vertical offset for alignment with the code text.
+ * ────────────────────────────────────────────────────────── */

docs/_static/css/custom.css

@@ -43,6 +43,7 @@
     "sphinx_design",
     "myst_parser",
     "linkify_issues",
+    "fastmcp_autodoc",
 ]
 
 myst_heading_anchors = 4

docs/conf.py

@@ -4,114 +4,200 @@
 
 All tools accept an optional `socket_name` parameter for multi-server support. It defaults to the `LIBTMUX_SOCKET` env var. See {ref}`configuration`.
 
-::::{grid} 1 1 2 2
+## Inspect
+
+Read tmux state without changing anything.
+
+::::{grid} 1 2 3 3
 :gutter: 2 2 3 3
 
-:::{grid-item-card} Discovery
-Find and inspect tmux objects.
-^^^
-`list_sessions` `list_windows` `list_panes` `get_server_info` `get_pane_info`
+:::{grid-item-card} list_sessions
+:link: sessions
+:link-type: doc
+List all active sessions.
 :::
 
-:::{grid-item-card} Capture & Search
-Read and search terminal output.
-^^^
-`capture_pane` `search_panes` `wait_for_text`
+:::{grid-item-card} list_windows
+:link: windows
+:link-type: doc
+List windows in a session.
 :::
 
-:::{grid-item-card} Session Lifecycle
-Create and manage sessions.
-^^^
-`create_session` `rename_session` `kill_session`
+:::{grid-item-card} list_panes
+:link: windows
+:link-type: doc
+List panes in a window.
 :::
 
-:::{grid-item-card} Windows & Panes
-Create, split, and organize.
-^^^
-`create_window` `split_window` `rename_window` `select_layout` `resize_window` `resize_pane` `kill_window` `kill_pane`
+:::{grid-item-card} capture_pane
+:link: panes
+:link-type: doc
+Read visible content of a pane.
 :::
 
-:::{grid-item-card} Execution
-Send commands and interact with terminals.
-^^^
-`send_keys` `set_pane_title` `clear_pane`
+:::{grid-item-card} get_pane_info
+:link: panes
+:link-type: doc
+Get detailed pane metadata.
 :::
 
-:::{grid-item-card} Options & Environment
-Read and set tmux configuration.
-^^^
-`show_option` `set_option` `show_environment` `set_environment`
+:::{grid-item-card} search_panes
+:link: panes
+:link-type: doc
+Search text across panes.
 :::
 
-:::{grid-item-card} Server Management
-Destructive server operations.
-^^^
-`kill_server`
+:::{grid-item-card} wait_for_text
+:link: panes
+:link-type: doc
+Wait for text to appear in a pane.
+:::
+
+:::{grid-item-card} get_server_info
+:link: sessions
+:link-type: doc
+Get tmux server info.
+:::
+
+:::{grid-item-card} show_option
+:link: options
+:link-type: doc
+Query a tmux option value.
+:::
+
+:::{grid-item-card} show_environment
+:link: options
+:link-type: doc
+Show tmux environment variables.
 :::
 
 ::::
 
-## Discovery
+## Act
+
+Create or modify tmux objects.
+
+::::{grid} 1 2 3 3
+:gutter: 2 2 3 3
+
+:::{grid-item-card} create_session
+:link: sessions
+:link-type: doc
+Start a new tmux session.
+:::
+
+:::{grid-item-card} create_window
+:link: windows
+:link-type: doc
+Add a window to a session.
+:::
+
+:::{grid-item-card} split_window
+:link: windows
+:link-type: doc
+Split a window into panes.
+:::
 
-Find and inspect tmux objects.
+:::{grid-item-card} send_keys
+:link: panes
+:link-type: doc
+Send commands or keystrokes to a pane.
+:::
 
-- **`list_sessions`** — List all sessions (with optional filters)
-- **`list_windows`** — List windows in a session or across all sessions
-- **`list_panes`** — List panes in a window or across all windows
-- **`get_server_info`** — Server status: version, socket path, session count, alive status
-- **`get_pane_info`** — Pane metadata: size, title, current command, PID
+:::{grid-item-card} rename_session
+:link: sessions
+:link-type: doc
+Rename a session.
+:::
 
-## Capture and search
+:::{grid-item-card} rename_window
+:link: windows
+:link-type: doc
+Rename a window.
+:::
 
-Read and search terminal output.
+:::{grid-item-card} resize_pane
+:link: panes
+:link-type: doc
+Adjust pane dimensions.
+:::
 
-- **`capture_pane`** — Capture pane content as text (visible area or scrollback)
-- **`search_panes`** — Search across all pane contents for text or regex
-- **`wait_for_text`** — Wait for text to appear in a pane (polling with timeout)
+:::{grid-item-card} resize_window
+:link: windows
+:link-type: doc
+Adjust window dimensions.
+:::
 
-## Session lifecycle
+:::{grid-item-card} select_layout
+:link: windows
+:link-type: doc
+Set window layout.
+:::
 
-Create and manage sessions.
+:::{grid-item-card} set_pane_title
+:link: panes
+:link-type: doc
+Set pane title.
+:::
 
-- **`create_session`** — Create a new session with optional window name, size, and env vars
-- **`rename_session`** — Rename an existing session
-- **`kill_session`** — Kill a session (destructive)
+:::{grid-item-card} clear_pane
+:link: panes
+:link-type: doc
+Clear pane content.
+:::
 
-## Windows and panes
+:::{grid-item-card} set_option
+:link: options
+:link-type: doc
+Set a tmux option.
+:::
 
-Create, split, and organize.
+:::{grid-item-card} set_environment
+:link: options
+:link-type: doc
+Set a tmux environment variable.
+:::
 
-- **`create_window`** — Create a new window in a session
-- **`split_window`** — Split a window to create a new pane (horizontal or vertical)
-- **`rename_window`** — Rename a window
-- **`select_layout`** — Set layout: `even-horizontal`, `even-vertical`, `main-horizontal`, `main-vertical`, `tiled`
-- **`resize_window`** — Resize a window (width and/or height)
-- **`resize_pane`** — Resize a pane (width, height, or zoom toggle)
-- **`kill_window`** — Kill a window (destructive)
-- **`kill_pane`** — Kill a pane (destructive)
+::::
 
-## Execution
+## Destroy
 
-Send commands and interact with terminals.
+Tear down tmux objects. Not reversible.
 
-- **`send_keys`** — Send keys or text to a pane (with optional Enter, literal mode, history suppression)
-- **`set_pane_title`** — Set a pane's title
-- **`clear_pane`** — Clear pane content and scrollback history
+::::{grid} 1 2 3 3
+:gutter: 2 2 3 3
 
-## Options and environment
+:::{grid-item-card} kill_session
+:link: sessions
+:link-type: doc
+Destroy a session and all its windows.
+:::
 
-Read and set tmux configuration.
+:::{grid-item-card} kill_window
+:link: windows
+:link-type: doc
+Destroy a window and all its panes.
+:::
 
-- **`show_option`** — Query a tmux option value (server, session, window, or pane scope)
-- **`set_option`** — Set a tmux option
-- **`show_environment`** — Show tmux environment variables
-- **`set_environment`** — Set a tmux environment variable
+:::{grid-item-card} kill_pane
+:link: panes
+:link-type: doc
+Destroy a pane.
+:::
 
-## Server management
+:::{grid-item-card} kill_server
+:link: sessions
+:link-type: doc
+Kill the entire tmux server.
+:::
 
-- **`kill_server`** — Kill the tmux server (destructive)
+::::
 
-## Tool parameter reference
+```{toctree}
+:hidden:
 
-For full parameter documentation (types, defaults, descriptions), see the
-[API reference](../reference/api/index.md).
+sessions
+windows
+panes
+options
+```

docs/tools/index.md

@@ -0,0 +1,74 @@
+# Options & Environment
+
+## Inspect
+
+```{fastmcp-tool} option_tools.show_option
+```
+
+**Use when** you need to check a tmux configuration value — buffer limits,
+history size, status bar settings, etc.
+
+**Side effects:** None. Readonly.
+
+**Example:**
+
+```json
+{
+  "tool": "show_option",
+  "arguments": {
+    "option": "history-limit"
+  }
+}
+```
+
+```{fastmcp-tool-input} option_tools.show_option
+```
+
+---
+
+```{fastmcp-tool} env_tools.show_environment
+```
+
+**Use when** you need to inspect tmux environment variables.
+
+**Side effects:** None. Readonly.
+
+```{fastmcp-tool-input} env_tools.show_environment
+```
+
+## Act
+
+```{fastmcp-tool} option_tools.set_option
+```
+
+**Use when** you need to change tmux behavior — adjusting history limits,
+enabling mouse support, changing status bar format.
+
+**Side effects:** Changes the tmux option value.
+
+**Example:**
+
+```json
+{
+  "tool": "set_option",
+  "arguments": {
+    "option": "history-limit",
+    "value": "50000"
+  }
+}
+```
+
+```{fastmcp-tool-input} option_tools.set_option
+```
+
+---
+
+```{fastmcp-tool} env_tools.set_environment
+```
+
+**Use when** you need to set a tmux environment variable.
+
+**Side effects:** Sets the variable in the tmux server.
+
+```{fastmcp-tool-input} env_tools.set_environment
+```