feat(docs[_ext]): register tool sections as Sphinx labels for site-wide {ref} links

Add doctree-read hook to fastmcp_autodoc that registers all section
nodes with StandardDomain (labels + anonlabels), mirroring the pattern
used by sphinx.ext.autosectionlabel.

note_explicit_target() only registers with docutils — the Sphinx {ref}
role looks up targets in StandardDomain, which was never populated.
Now any section ID created by the fastmcp-tool directive (or any other
heading) is a valid cross-reference target from any page.

docs/index.md "What you can do" tool names are now inline code links
using MyST [`tool_name`](#label) syntax — renders as <a><code> elements
that resolve through Sphinx's label system across the dirhtml builder.

Author: tony

docs/_ext/fastmcp_autodoc.py

@@ -34,6 +34,7 @@
 from sphinx.util.docutils import SphinxDirective
 
 if t.TYPE_CHECKING:
+    from sphinx.domains.std import StandardDomain
     from sphinx.util.typing import ExtensionMetadata
 
 # ---------------------------------------------------------------------------
@@ -705,9 +706,30 @@ def run(self) -> list[nodes.Node]:
 # ---------------------------------------------------------------------------
 
 
+def _register_tool_labels(app: Sphinx, doctree: nodes.document) -> None:
+    """Register tool sections with StandardDomain for site-wide {ref} links.
+
+    ``note_explicit_target()`` only registers with docutils, not with Sphinx's
+    StandardDomain.  This hook mirrors the pattern used by
+    ``sphinx.ext.autosectionlabel`` so that ``{ref}`list-sessions``` works
+    from any page.
+    """
+    domain = t.cast("StandardDomain", app.env.get_domain("std"))
+    docname = app.env.docname
+    for section in doctree.findall(nodes.section):
+        if not section["ids"]:
+            continue
+        section_id = section["ids"][0]
+        if section.children and isinstance(section[0], nodes.title):
+            title = section[0].astext()
+            domain.anonlabels[section_id] = (docname, section_id)
+            domain.labels[section_id] = (docname, section_id, title)
+
+
 def setup(app: Sphinx) -> ExtensionMetadata:
     """Register the fastmcp_autodoc extension."""
     app.connect("builder-inited", _collect_tools)
+    app.connect("doctree-read", _register_tool_labels)
     app.add_directive("fastmcp-tool", FastMCPToolDirective)
     app.add_directive("fastmcp-tool-input", FastMCPToolInputDirective)
     app.add_directive("fastmcp-toolsummary", FastMCPToolSummaryDirective)

docs/index.md

@@ -53,19 +53,19 @@ Config blocks for Claude Desktop, Claude Code, Cursor, and others.
 
 Read tmux state without changing anything.
 
-`list_sessions` · `capture_pane` · `get_pane_info` · `search_panes` · `wait_for_text`
+[`list_sessions`](#list-sessions) · [`capture_pane`](#capture-pane) · [`get_pane_info`](#get-pane-info) · [`search_panes`](#search-panes) · [`wait_for_text`](#wait-for-text)
 
 ### Act (mutating)
 
 Create or modify tmux objects.
 
-`create_session` · `send_keys` · `create_window` · `split_window` · `resize_pane` · `set_option`
+[`create_session`](#create-session) · [`send_keys`](#send-keys) · [`create_window`](#create-window) · [`split_window`](#split-window) · [`resize_pane`](#resize-pane) · [`set_option`](#set-option)
 
 ### Destroy (destructive)
 
 Tear down tmux objects. Not reversible.
 
-`kill_session` · `kill_window` · `kill_pane` · `kill_server`
+[`kill_session`](#kill-session) · [`kill_window`](#kill-window) · [`kill_pane`](#kill-pane) · [`kill_server`](#kill-server)
 
 [Browse all tools →](tools/index)