feat(docs[_ext]): Add safety badges to Inspect/Act/Destroy headings

why: Section headings grouping tools by tier should visually indicate
the safety level, matching the per-tool badges.
what:
- Add SECTION_BADGE_MAP constant mapping heading text to safety tiers
- Add _add_section_badges handler at doctree-resolved that appends
  colored badge nodes to matching titles
- Section IDs remain untouched (frozen before transform runs)
- Add 4 tests: map values, badge appended, ID preserved, non-match ignored

Author: tony

docs/_ext/fastmcp_autodoc.py

@@ -50,6 +50,12 @@
     "env_tools": "options",
 }
 
+SECTION_BADGE_MAP: dict[str, str] = {
+    "Inspect": "readonly",
+    "Act": "mutating",
+    "Destroy": "destructive",
+}
+
 TAG_READONLY = "readonly"
 TAG_MUTATING = "mutating"
 TAG_DESTRUCTIVE = "destructive"
@@ -739,6 +745,26 @@ def _register_tool_labels(app: Sphinx, doctree: nodes.document) -> None:
             domain.labels[section_id] = (docname, section_id, tool_name)
 
 
+def _add_section_badges(
+    app: Sphinx,
+    doctree: nodes.document,
+    fromdocname: str,
+) -> None:
+    """Append safety badges to Inspect/Act/Destroy section headings.
+
+    Runs at ``doctree-resolved`` — section IDs are already frozen, so
+    appending nodes to the title doesn't affect anchors or cross-refs.
+    """
+    for section in doctree.findall(nodes.section):
+        if not section.children or not isinstance(section[0], nodes.title):
+            continue
+        title_text = section[0].astext().strip()
+        safety = SECTION_BADGE_MAP.get(title_text)
+        if safety is not None:
+            section[0] += nodes.Text(" ")
+            section[0] += _safety_badge(safety)
+
+
 class _tool_ref_placeholder(nodes.General, nodes.Inline, nodes.Element):
     """Placeholder node for ``{tool}`` role, resolved at doctree-resolved."""
 
@@ -809,6 +835,7 @@ def setup(app: Sphinx) -> ExtensionMetadata:
     """Register the fastmcp_autodoc extension."""
     app.connect("builder-inited", _collect_tools)
     app.connect("doctree-read", _register_tool_labels)
+    app.connect("doctree-resolved", _add_section_badges)
     app.connect("doctree-resolved", _resolve_tool_refs)
     app.add_role("tool", _tool_role)
     app.add_directive("fastmcp-tool", FastMCPToolDirective)

tests/docs/_ext/test_fastmcp_autodoc.py

@@ -442,6 +442,84 @@ def test_safety_badge_classes() -> None:
     assert "sd-bg-danger" in badge["classes"]
 
 
+# ---------------------------------------------------------------------------
+# SECTION_BADGE_MAP + _add_section_badges
+# ---------------------------------------------------------------------------
+
+
+def test_section_badge_map_headings() -> None:
+    """SECTION_BADGE_MAP maps group headings to safety tiers."""
+    m = fastmcp_autodoc.SECTION_BADGE_MAP
+    assert m["Inspect"] == "readonly"
+    assert m["Act"] == "mutating"
+    assert m["Destroy"] == "destructive"
+
+
+def test_add_section_badges_appends_badge_to_title() -> None:
+    """_add_section_badges appends a safety badge to matching titles."""
+    from docutils import nodes
+    from docutils.frontend import OptionParser
+    from docutils.utils import new_document
+
+    settings = OptionParser(components=()).get_default_values()
+    doc = new_document("test", settings)
+
+    section = nodes.section(ids=["inspect"])
+    title = nodes.title("", "Inspect")
+    section += title
+    doc += section
+
+    # Simulate the handler — it expects (app, doctree, fromdocname)
+    # but only uses doctree, so pass None for the others.
+    fastmcp_autodoc._add_section_badges(None, doc, "")
+
+    # Title should now have 3 children: Text("Inspect"), Text(" "), inline(badge)
+    assert len(title.children) == 3
+    badge = title.children[2]
+    assert isinstance(badge, nodes.inline)
+    assert "sd-bg-success" in badge["classes"]
+    assert badge.astext() == "readonly"
+
+
+def test_add_section_badges_preserves_section_id() -> None:
+    """_add_section_badges does not change the section ID."""
+    from docutils import nodes
+    from docutils.frontend import OptionParser
+    from docutils.utils import new_document
+
+    settings = OptionParser(components=()).get_default_values()
+    doc = new_document("test", settings)
+
+    section = nodes.section(ids=["inspect"])
+    section += nodes.title("", "Inspect")
+    doc += section
+
+    fastmcp_autodoc._add_section_badges(None, doc, "")
+
+    assert section["ids"] == ["inspect"]
+
+
+def test_add_section_badges_ignores_non_matching() -> None:
+    """_add_section_badges leaves non-matching headings untouched."""
+    from docutils import nodes
+    from docutils.frontend import OptionParser
+    from docutils.utils import new_document
+
+    settings = OptionParser(components=()).get_default_values()
+    doc = new_document("test", settings)
+
+    section = nodes.section(ids=["overview"])
+    title = nodes.title("", "Overview")
+    section += title
+    doc += section
+
+    fastmcp_autodoc._add_section_badges(None, doc, "")
+
+    # Title should still have only the original text child
+    assert len(title.children) == 1
+    assert title.astext() == "Overview"
+
+
 # ---------------------------------------------------------------------------
 # Integration: collect real tools
 # ---------------------------------------------------------------------------