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

@@ -8,18 +8,36 @@ All tools accept an optional `socket_name` parameter for multi-server support. I
 
 **Reading terminal content?**
 - Know which pane? → {tool}`capture-pane`
+- Need text + cursor + mode in one call? → {tool}`snapshot-pane`
 - Don't know which pane? → {tool}`search-panes`
-- Need to wait for output? → {tool}`wait-for-text`
+- Need to wait for specific output? → {tool}`wait-for-text`
+- Need to wait for *any* change? → {tool}`wait-for-content-change`
 - Only need metadata (PID, path, size)? → {tool}`get-pane-info`
+- Need an arbitrary tmux variable? → {tool}`display-message`
 
 **Running a command?**
 - {tool}`send-keys` — then {tool}`wait-for-text` + {tool}`capture-pane`
+- Pasting multi-line text? → {tool}`paste-text`
 
 **Creating workspace structure?**
 - New session → {tool}`create-session`
 - New window → {tool}`create-window`
 - New pane → {tool}`split-window`
 
+**Navigating?**
+- Switch pane → {tool}`select-pane` (by ID or direction)
+- Switch window → {tool}`select-window` (by ID, index, or direction)
+
+**Rearranging layout?**
+- Swap two panes → {tool}`swap-pane`
+- Move window → {tool}`move-window`
+- Change layout → {tool}`select-layout`
+
+**Scrollback / copy mode?**
+- Enter copy mode → {tool}`enter-copy-mode`
+- Exit copy mode → {tool}`exit-copy-mode`
+- Log output to file → {tool}`pipe-pane`
+
 **Changing settings?**
 - tmux options → {tool}`show-option` / {tool}`set-option`
 - Environment vars → {tool}`show-environment` / {tool}`set-environment`
@@ -91,6 +109,24 @@ Query a tmux option value.
 Show tmux environment variables.
 :::
 
+:::{grid-item-card} snapshot_pane
+:link: snapshot-pane
+:link-type: ref
+Rich capture: content + cursor + mode + scroll.
+:::
+
+:::{grid-item-card} wait_for_content_change
+:link: wait-for-content-change
+:link-type: ref
+Wait for any screen change.
+:::
+
+:::{grid-item-card} display_message
+:link: display-message
+:link-type: ref
+Query arbitrary tmux format strings.
+:::
+
 ::::
 
 ## Act
@@ -178,6 +214,54 @@ Set a tmux option.
 Set a tmux environment variable.
 :::
 
+:::{grid-item-card} select_pane
+:link: select-pane
+:link-type: ref
+Focus a pane by ID or direction.
+:::
+
+:::{grid-item-card} select_window
+:link: select-window
+:link-type: ref
+Focus a window by ID, index, or direction.
+:::
+
+:::{grid-item-card} swap_pane
+:link: swap-pane
+:link-type: ref
+Exchange positions of two panes.
+:::
+
+:::{grid-item-card} move_window
+:link: move-window
+:link-type: ref
+Move window to another index or session.
+:::
+
+:::{grid-item-card} pipe_pane
+:link: pipe-pane
+:link-type: ref
+Stream pane output to a file.
+:::
+
+:::{grid-item-card} enter_copy_mode
+:link: enter-copy-mode
+:link-type: ref
+Enter copy mode for scrollback.
+:::
+
+:::{grid-item-card} exit_copy_mode
+:link: exit-copy-mode
+:link-type: ref
+Exit copy mode.
+:::
+
+:::{grid-item-card} paste_text
+:link: paste-text
+:link-type: ref
+Paste multi-line text via tmux buffer.
+:::
+
 ::::
 
 ## Destroy
@@ -216,8 +300,8 @@ Kill the entire tmux server.
 ```{toctree}
 :hidden:
 
-sessions
-windows
-panes
-options
+server/index
+session/index
+window/index
+pane/index
 ```