docs: Overhaul documentation with autodoc directives and per-tool pages

docs/_static/css/fastmcp_autodoc.css

@@ -0,0 +1,37 @@
+/* fastmcp_autodoc.css — resource badge, model badge, URI template, table polish */
+
+/* Resource badge (blue) — additional ARIA styling */
+span.sd-badge[aria-label*="resource"] {
+    user-select: none;
+}
+
+/* Model badge (purple) — additional ARIA styling */
+span.sd-badge[aria-label*="model"] {
+    user-select: none;
+}
+
+/* URI template block — left-border accent, monospace */
+.fastmcp-uri-template {
+    border-left: 3px solid var(--sd-color-info, #0dcaf0);
+    padding: 0.5em 1em;
+    background: var(--sd-color-info-bg, #f0f9ff);
+    font-family: var(--sd-fontfamily-monospace, monospace);
+}
+
+/* Badge in section headings — medium size, not full h1 scale */
+h1 .sd-badge,
+h2 .sd-badge {
+    font-size: 0.5em;
+    vertical-align: middle;
+}
+
+/* Sidebar: strip background from inline code (tool/resource/model names) */
+.sidebar-tree code.literal {
+    background: none;
+}
+
+/* Field/param table polish — tighter padding */
+.fastmcp-autodoc-table td,
+.fastmcp-autodoc-table th {
+    padding: 0.35em 0.6em;
+}

docs/demo.md

@@ -72,6 +72,26 @@ Use {tooliconl}`search-panes` to find text across all panes. If you know which p
 
 The fundamental pattern: {toolref}`send-keys` → {toolref}`wait-for-text` → {toolref}`capture-pane`. For discovery: {toolref}`list-sessions` → {toolref}`list-panes` → {toolref}`get-pane-info`.
 
+## Resource references
+
+### `{resource}` — code-linked with badge
+
+{resource}`get-sessions` · {resource}`get-session` · {resource}`get-session-windows` · {resource}`get-window` · {resource}`get-pane` · {resource}`get-pane-content`
+
+### `{resourceref}` — code-linked, no badge
+
+{resourceref}`get-sessions` · {resourceref}`get-session` · {resourceref}`get-session-windows` · {resourceref}`get-window` · {resourceref}`get-pane` · {resourceref}`get-pane-content`
+
+## Model references
+
+### `{model}` — code-linked with badge
+
+{model}`SessionInfo` · {model}`WindowInfo` · {model}`PaneInfo` · {model}`PaneSnapshot` · {model}`ServerInfo` · {model}`WaitForTextResult`
+
+### `{modelref}` — code-linked, no badge
+
+{modelref}`SessionInfo` · {modelref}`WindowInfo` · {modelref}`PaneInfo` · {modelref}`PaneSnapshot` · {modelref}`ServerInfo` · {modelref}`WaitForTextResult`
+
 ## Environment variable references
 
 {envvar}`LIBTMUX_SOCKET` · {envvar}`LIBTMUX_SAFETY` · {envvar}`LIBTMUX_SOCKET_PATH` · {envvar}`LIBTMUX_TMUX_BIN`

docs/redirects.txt

@@ -12,3 +12,45 @@
 "concepts" "topics/concepts"
 "safety" "topics/safety"
 "guides/troubleshooting" "topics/troubleshooting"
+"tools/sessions" "tools/index"
+"tools/windows" "tools/index"
+"tools/panes" "tools/index"
+"tools/options" "tools/index"
+"tools/capture-pane" "tools/pane/capture-pane"
+"tools/clear-pane" "tools/pane/clear-pane"
+"tools/create-session" "tools/server/create-session"
+"tools/create-window" "tools/session/create-window"
+"tools/display-message" "tools/pane/display-message"
+"tools/enter-copy-mode" "tools/pane/enter-copy-mode"
+"tools/exit-copy-mode" "tools/pane/exit-copy-mode"
+"tools/get-pane-info" "tools/pane/get-pane-info"
+"tools/get-server-info" "tools/server/get-server-info"
+"tools/kill-pane" "tools/pane/kill-pane"
+"tools/kill-server" "tools/server/kill-server"
+"tools/kill-session" "tools/session/kill-session"
+"tools/kill-window" "tools/window/kill-window"
+"tools/list-panes" "tools/window/list-panes"
+"tools/list-sessions" "tools/server/list-sessions"
+"tools/list-windows" "tools/session/list-windows"
+"tools/move-window" "tools/window/move-window"
+"tools/paste-text" "tools/pane/paste-text"
+"tools/pipe-pane" "tools/pane/pipe-pane"
+"tools/rename-session" "tools/session/rename-session"
+"tools/rename-window" "tools/window/rename-window"
+"tools/resize-pane" "tools/pane/resize-pane"
+"tools/resize-window" "tools/window/resize-window"
+"tools/search-panes" "tools/pane/search-panes"
+"tools/select-layout" "tools/window/select-layout"
+"tools/select-pane" "tools/pane/select-pane"
+"tools/select-window" "tools/session/select-window"
+"tools/send-keys" "tools/pane/send-keys"
+"tools/set-environment" "tools/server/set-environment"
+"tools/set-option" "tools/server/set-option"
+"tools/set-pane-title" "tools/pane/set-pane-title"
+"tools/show-environment" "tools/server/show-environment"
+"tools/show-option" "tools/server/show-option"
+"tools/snapshot-pane" "tools/pane/snapshot-pane"
+"tools/split-window" "tools/window/split-window"
+"tools/swap-pane" "tools/pane/swap-pane"
+"tools/wait-for-content-change" "tools/pane/wait-for-content-change"
+"tools/wait-for-text" "tools/pane/wait-for-text"

docs/reference/api/models.md

@@ -1,8 +1,40 @@
 # Models
 
-```{eval-rst}
-.. automodule:: libtmux_mcp.models
-   :members:
-   :undoc-members:
-   :show-inheritance:
+```{fastmcp-modelsummary}
+```
+
+```{fastmcp-model} SessionInfo
+```
+
+```{fastmcp-model} WindowInfo
+```
+
+```{fastmcp-model} PaneInfo
+```
+
+```{fastmcp-model} PaneContentMatch
+```
+
+```{fastmcp-model} ServerInfo
+```
+
+```{fastmcp-model} OptionResult
+```
+
+```{fastmcp-model} OptionSetResult
+```
+
+```{fastmcp-model} EnvironmentResult
+```
+
+```{fastmcp-model} EnvironmentSetResult
+```
+
+```{fastmcp-model} WaitForTextResult
+```
+
+```{fastmcp-model} PaneSnapshot
+```
+
+```{fastmcp-model} ContentChangeResult
 ```

docs/reference/api/resources.md

@@ -1,8 +1,28 @@
 # Resources
 
-```{eval-rst}
-.. automodule:: libtmux_mcp.resources.hierarchy
-   :members:
-   :undoc-members:
-   :show-inheritance:
+```{fastmcp-resourcesummary}
+```
+
+## Session Resources
+
+```{fastmcp-resource} hierarchy.get_sessions
+```
+
+```{fastmcp-resource} hierarchy.get_session
+```
+
+```{fastmcp-resource} hierarchy.get_session_windows
+```
+
+## Window Resources
+
+```{fastmcp-resource} hierarchy.get_window
+```
+
+## Pane Resources
+
+```{fastmcp-resource} hierarchy.get_pane
+```
+
+```{fastmcp-resource} hierarchy.get_pane_content
 ```

docs/tools/index.md

@@ -300,8 +300,8 @@ Kill the entire tmux server.
 ```{toctree}
 :hidden:
 
-sessions
-windows
-panes
-options
+server/index
+session/index
+window/index
+pane/index
 ```

docs/tools/pane/capture-pane.md

@@ -0,0 +1,40 @@
+```{fastmcp-tool} pane_tools.capture_pane
+```
+
+**Use when** you need to read what's currently displayed in a terminal —
+after running a command, checking output, or verifying state.
+
+**Avoid when** you need to search across multiple panes at once — use
+{tooliconl}`search-panes`. If you only need pane metadata (not content), use
+{tooliconl}`get-pane-info`.
+
+**Side effects:** None. Readonly.
+
+**Example:**
+
+```json
+{
+  "tool": "capture_pane",
+  "arguments": {
+    "pane_id": "%0",
+    "start": -50
+  }
+}
+```
+
+Response (string):
+
+```text
+$ echo "Running tests..."
+Running tests...
+$ echo "PASS: test_auth (0.3s)"
+PASS: test_auth (0.3s)
+$ echo "FAIL: test_upload (AssertionError)"
+FAIL: test_upload (AssertionError)
+$ echo "3 tests: 2 passed, 1 failed"
+3 tests: 2 passed, 1 failed
+$
+```
+
+```{fastmcp-tool-input} pane_tools.capture_pane
+```