docs(autodoc[prompts,resources]): wire FastMCP autodoc for prompts and resources

Switch ``docs/tools/prompts.md`` and ``docs/reference/api/resources.md``
from hand-written signatures / ``automodule`` to the new
``{fastmcp-prompt}`` / ``{fastmcp-prompt-input}`` and
``{fastmcp-resource-template}`` directives from gp-sphinx. Each recipe
now has a live-introspected card (name, description, tags, type
badge) and an auto-generated arguments table, while the editorial
prose (``**Use when**``, ``**Why use this**``, ``**Sample render**``)
stays hand-written around the directive blocks.

``docs/conf.py`` now sets ``fastmcp_server_module = "libtmux_mcp.server:mcp"``
so the collector can enumerate the live FastMCP instance. Because
``server.py`` defers registration to ``run_server()``, the collector
invokes ``_register_all()`` internally to populate the component
registry before reading.

Also add three short ``docs/topics/`` pages for the MCP protocol
utilities that map conceptually rather than as first-class autodoc:

- ``completion.md`` — what FastMCP derives automatically from prompt
  args and resource-template parameters; notes that live tmux state
  is not yet wired in as a completion source.
- ``logging.md`` — the ``libtmux_mcp.*`` logger hierarchy and how
  FastMCP forwards records to clients via the MCP logging capability.
- ``pagination.md`` — contrasts MCP protocol-level cursors (automatic,
  server-owned) with tool-level ``offset`` / ``limit`` on
  ``search_panes`` (agent-controlled bounded cost).

Topics index grows a new "MCP protocol utilities" grid row linking
to them.

Author: tony

docs/conf.py

@@ -88,6 +88,7 @@
     "wait_for_tools": "waits",
     "hook_tools": "hooks",
 }
+conf["fastmcp_server_module"] = "libtmux_mcp.server:mcp"
 conf["fastmcp_model_module"] = "libtmux_mcp.models"
 conf["fastmcp_model_classes"] = (
     "SessionInfo",

docs/reference/api/resources.md

@@ -1,8 +1,40 @@
+(resources-overview)=
+
 # Resources
 
-```{eval-rst}
-.. automodule:: libtmux_mcp.resources.hierarchy
-   :members:
-   :undoc-members:
-   :show-inheritance:
+MCP resources are addressable documents the server exposes at
+``tmux://`` URIs. Clients read them via ``resources/read``. All
+libtmux-mcp resources are **resource templates** — each URI includes
+a ``{?socket_name}`` query parameter for socket isolation, plus
+structural path parameters (``{session_name}``, ``{pane_id}``, …) so
+a single template covers every session, window, or pane.
+
+Every resource delivers a snapshot of the tmux hierarchy at call
+time. Agents use them for read-only inspection; any write workflow
+goes through the corresponding {doc}`tools </tools/index>`.
+
+---
+
+## Sessions
+
+```{fastmcp-resource-template} get_sessions
+```
+
+```{fastmcp-resource-template} get_session
+```
+
+```{fastmcp-resource-template} get_session_windows
+```
+
+## Windows
+
+```{fastmcp-resource-template} get_window
+```
+
+## Panes
+
+```{fastmcp-resource-template} get_pane
+```
+
+```{fastmcp-resource-template} get_pane_content
 ```

docs/tools/prompts.md

@@ -29,10 +29,11 @@ tools instead.
 
 ---
 
-(run-and-wait)=
-
 ## `run_and_wait`
 
+```{fastmcp-prompt} run_and_wait
+```
+
 **Use when** the agent needs to execute a single shell command and
 must know whether it succeeded before deciding the next step.
 
@@ -43,11 +44,8 @@ never cross-signal each other. The server side blocks until the
 channel is signalled — strictly cheaper in agent turns than a
 ``capture_pane`` retry loop.
 
-**Parameters:**
-
-- ``command`` (str) — the shell command to run.
-- ``pane_id`` (str) — target pane (e.g. ``%1``).
-- ``timeout`` (float, default ``60.0``) — maximum seconds to wait.
+```{fastmcp-prompt-input} run_and_wait
+```
 
 **Sample render** (``command="pytest"``, ``pane_id="%1"``):
 
@@ -76,10 +74,11 @@ success or failure.
 
 ---
 
-(diagnose-failing-pane)=
-
 ## `diagnose_failing_pane`
 
+```{fastmcp-prompt} diagnose_failing_pane
+```
+
 **Use when** something visibly went wrong in a pane and the agent
 needs to investigate before deciding what to fix. Produces a plan,
 not an action.
@@ -91,9 +90,8 @@ follow-up ``get_pane_info`` round-trip. It also explicitly forbids
 the agent from acting before it has a hypothesis, which prevents
 "fix the symptom" anti-patterns.
 
-**Parameters:**
-
-- ``pane_id`` (str) — the pane to diagnose.
+```{fastmcp-prompt-input} diagnose_failing_pane
+```
 
 **Sample render** (``pane_id="%1"``):
 
@@ -111,10 +109,11 @@ Something went wrong in tmux pane %1. Diagnose it:
 
 ---
 
-(build-dev-workspace)=
-
 ## `build_dev_workspace`
 
+```{fastmcp-prompt} build_dev_workspace
+```
+
 **Use when** the operator wants a fresh 3-pane workspace with editor
 on top, terminal bottom-left, and a logs pane bottom-right — the
 most common shape for active development.
@@ -128,13 +127,12 @@ also explicitly avoids waiting for shell prompts after launching
 deadlock an agent following naïve "wait for the prompt between each
 step" advice.
 
-**Parameters:**
+```{fastmcp-prompt-input} build_dev_workspace
+```
 
-- ``session_name`` (str) — name for the new session.
-- ``log_command`` (str, default ``"watch -n 1 date"``) — command to
-  run in the logs pane. Pass e.g. ``"tail -f /var/log/syslog"`` on
-  Linux or ``"log stream --level info"`` on macOS to override the
-  OS-neutral default.
+Pass e.g. ``"tail -f /var/log/syslog"`` on Linux or
+``"log stream --level info"`` on macOS as the ``log_command`` to
+override the OS-neutral default.
 
 **Sample render** (``session_name="dev"``):
 
@@ -173,10 +171,11 @@ across layout changes; window renames are not.
 
 ---
 
-(interrupt-gracefully)=
-
 ## `interrupt_gracefully`
 
+```{fastmcp-prompt} interrupt_gracefully
+```
+
 **Use when** the agent needs to stop a running command and confirm
 control returned to the shell — without escalating beyond SIGINT.
 
@@ -187,9 +186,8 @@ times out. That prevents the most dangerous failure mode — an agent
 auto-escalating to ``C-\\`` (SIGQUIT, may core-dump) or ``kill``
 without operator consent — by drawing a clear escalation boundary.
 
-**Parameters:**
-
-- ``pane_id`` (str) — target pane.
+```{fastmcp-prompt-input} interrupt_gracefully
+```
 
 **Sample render** (``pane_id="%1"``):
 

docs/topics/completion.md

@@ -0,0 +1,51 @@
+(completion-overview)=
+
+# Completion
+
+libtmux-mcp inherits FastMCP's built-in
+[MCP completion](https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/completion)
+behaviour. We don't hand-author completion providers — the argument
+shapes on our prompts and resource templates are what the client
+sees.
+
+## What the spec does
+
+A client calls ``completion/complete`` with a partial argument for a
+prompt or resource URI template; the server replies with up to 100
+suggestions. Agents use this to offer auto-complete UX — e.g. a
+session picker popup when filling ``session_name=`` on
+``get_session``.
+
+## What libtmux-mcp currently exposes
+
+- **Prompt arguments** — the four recipes ({doc}`/tools/prompts`)
+  advertise their argument names and types. FastMCP derives a default
+  completion shape from the Python signatures:
+  ``str`` arguments accept free text, ``float`` arguments accept
+  numeric strings, no enum / list suggestions.
+- **Resource template parameters** —
+  {doc}`/reference/api/resources` URIs carry ``{session_name}``,
+  ``{window_index}``, ``{pane_id}``, and ``{?socket_name}``
+  placeholders. Completion suggestions are again derived from the
+  function signatures' types, not from live tmux state.
+
+```{warning}
+libtmux-mcp does **not** currently wire completion back to live
+tmux enumeration — i.e. the completion for ``session_name`` will not
+return the names of sessions that exist on the server right now.
+Adding that requires a dedicated FastMCP completion handler;
+tracked as a potential enhancement.
+```
+
+## Workarounds for clients that need live enumeration
+
+Agents that need to pick a real session / window / pane can call
+{tool}`list-sessions`, {tool}`list-windows`, or {tool}`list-panes`
+directly before rendering a prompt, then feed the chosen ID back
+into the prompt's arguments.
+
+## Further reading
+
+- [MCP completion spec](https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/completion)
+- {doc}`/tools/prompts` — the prompt argument surface
+- {doc}`/reference/api/resources` — the resource-template parameter surface

docs/topics/index.md

@@ -43,6 +43,37 @@ Write effective instructions for AI agents using tmux tools.
 
 ::::
 
+## MCP protocol utilities
+
+How libtmux-mcp maps to three optional utility capabilities from
+the Model Context Protocol specification.
+
+::::{grid} 1 1 3 3
+:gutter: 2 2 3 3
+
+:::{grid-item-card} Completion
+:link: completion
+:link-type: doc
+Argument auto-complete — what FastMCP derives automatically and
+what libtmux-mcp does not yet wire up.
+:::
+
+:::{grid-item-card} Logging
+:link: logging
+:link-type: doc
+Server-to-client log forwarding and the ``libtmux_mcp.*`` logger
+hierarchy.
+:::
+
+:::{grid-item-card} Pagination
+:link: pagination
+:link-type: doc
+Protocol-level cursors vs tool-level ``offset`` / ``limit`` (as in
+``search_panes``).
+:::
+
+::::
+
 ```{toctree}
 :hidden:
 
@@ -51,5 +82,8 @@ concepts
 safety
 gotchas
 prompting
+completion
+logging
+pagination
 troubleshooting
 ```

docs/topics/logging.md

@@ -0,0 +1,59 @@
+(logging-overview)=
+
+# Logging
+
+libtmux-mcp uses Python's standard ``logging`` module under the
+``libtmux_mcp.*`` namespace. FastMCP forwards server-side log
+records to connected MCP clients via the
+[MCP logging capability](https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/logging).
+No manual wiring needed.
+
+## Logger hierarchy
+
+All loggers are children of ``libtmux_mcp``. The primary streams
+are:
+
+- ``libtmux_mcp.audit`` — one structured line per tool call, emitted
+  by {class}`~libtmux_mcp.middleware.AuditMiddleware`. Includes
+  tool name, digest-redacted arguments, latency, outcome. See
+  {doc}`/topics/safety` for the argument-redaction rules.
+- ``libtmux_mcp.retry`` — warnings from
+  {class}`~libtmux_mcp.middleware.ReadonlyRetryMiddleware` when a
+  readonly tool retried after a transient
+  {exc}`libtmux.exc.LibTmuxException`.
+- ``libtmux_mcp.server`` / ``libtmux_mcp.tools.*`` / etc. — ad-hoc
+  warnings and debug messages from the codebase.
+
+## Level control
+
+Set the logger level via standard Python mechanisms — for local
+development, the simplest is an environment variable:
+
+```console
+$ FASTMCP_LOG_LEVEL=DEBUG libtmux-mcp
+```
+
+FastMCP reads ``FASTMCP_LOG_LEVEL`` at startup and applies it to
+every ``fastmcp.*`` and ``libtmux_mcp.*`` logger.
+
+## What clients see
+
+MCP clients render incoming ``notifications/message`` records in
+their log pane (e.g. Claude Desktop's "MCP server logs" panel, or
+``claude-cli``'s ``--verbose`` output). The records include the
+server name (``libtmux-mcp``), level, and the log message — but not
+the Python logger name, which the protocol doesn't model.
+
+```{tip}
+If a tool call fails silently (no user-visible error, no side
+effect), the ``libtmux_mcp.audit`` log will show the invocation and
+its return value. That's usually the fastest way to tell whether a
+tool ran at all.
+```
+
+## Further reading
+
+- [MCP logging spec](https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/logging)
+- {doc}`/topics/safety` — audit log redaction rules
+- {class}`~libtmux_mcp.middleware.AuditMiddleware` — the primary
+  audit emitter

docs/topics/pagination.md

@@ -0,0 +1,55 @@
+(pagination-overview)=
+
+# Pagination
+
+libtmux-mcp follows the
+[MCP pagination spec](https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/pagination):
+``tools/list``, ``prompts/list``, ``resources/list``, and
+``resources/templates/list`` all return an opaque ``nextCursor`` when
+a page is truncated, and accept ``cursor`` on the next call to
+resume.
+
+## Two places pagination shows up
+
+### Protocol-level list calls
+
+FastMCP handles ``tools/list`` / ``prompts/list`` / ``resources/list``
+/ ``resources/templates/list`` pagination automatically. Neither
+libtmux-mcp nor the agent needs to do anything: the server chooses
+a sensible page size, encodes the cursor in an opaque base64 blob,
+and replays state from it. Callers only need to thread through
+``nextCursor`` if they consume the raw MCP protocol.
+
+### Tool-level pagination on ``search_panes``
+
+One libtmux-mcp tool owns its own pagination surface because a
+single tmux server can carry tens of thousands of pane lines:
+
+- {tool}`search-panes` returns a
+  {class}`~libtmux_mcp.models.SearchPanesResult` wrapper with
+  ``matches``, ``truncated``, ``truncated_panes``,
+  ``total_panes_matched``, ``offset``, and ``limit``.
+- Agents detect ``truncated=True`` and re-call with a higher
+  ``offset`` to page through the match set.
+
+This is application-level pagination (not MCP-cursor pagination) —
+the agent decides how many matches it needs and when to stop.
+
+## Why separate paths
+
+Protocol-level cursors are for **collections the server owns
+end-to-end**: the tool / prompt / resource registries. The server
+knows what it has, so an opaque cursor is cheap.
+
+Tool-level pagination is for **collections derived from live tmux
+state**: capturing every pane's contents and running a regex is
+expensive, and the result set can change mid-scan (new panes open,
+old ones close). Exposing ``offset`` / ``limit`` lets the agent
+bound cost explicitly, without pretending the snapshot is stable.
+
+## Further reading
+
+- [MCP pagination spec](https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/pagination)
+- {class}`~libtmux_mcp.models.SearchPanesResult` — the structured
+  wrapper for ``search_panes``
+- {tool}`search-panes` — the tool itself