tmux-python
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -78,7 +78,7 @@ jobs:
           restore-keys: |
             puppeteer-${{ runner.os }}-
 
-      # Diagrams (docs/_ext/mermaid_inline.py) are rendered at build time by
+      # Diagrams (sphinx-gp-mermaid) are rendered at build time by
       # mmdc, which drives a headless Chrome. Without it the build still
       # succeeds but degrades diagrams to a text fallback, so provision both.
       - name: Install diagram toolchain (mermaid-cli + Chrome)

diff --git a/.gitignore b/.gitignore
@@ -59,7 +59,7 @@ coverage.xml
 # Sphinx documentation
 docs/_build/
 
-# Mermaid diagram tooling (docs/_ext/mermaid_inline.py)
+# Mermaid diagram tooling (sphinx-gp-mermaid)
 docs/node_modules/
 docs/_mermaid_cache/
 

diff --git a/CHANGES b/CHANGES
@@ -64,6 +64,14 @@ more internal API cross-references resolve to their pages. The {ref}`quickstart`
 and {ref}`about-tmux` primer also pick up corrected version requirements,
 tooling, and commands.
 
+### Development
+
+#### Docs adopt the upstream `sphinx-gp-mermaid` renderer (#1073)
+
+The build-time mermaid diagram renderer, previously bundled with the docs, now
+comes from the reusable `sphinx-gp-mermaid` package (a dev/docs dependency).
+Rendered output is unchanged.
+
 ## tmuxp 1.73.0 (2026-06-28)
 
 tmuxp 1.73.0 makes the workspace build step pluggable and tunable. A workspace can now build through a third-party builder selected by registered entry-point name or Python import path, and a new `workspace_builder_options` catalog controls the pane-readiness wait per workspace. The built-in builder stays the default, so existing workspaces keep working — though the new `pane_readiness: auto` default skips the prompt wait on non-zsh shells. See {ref}`custom-workspace-builders` for the guide.

diff --git a/docs/AGENTS.md b/docs/AGENTS.md
@@ -87,9 +87,10 @@ page.
 
 Two mechanical conventions, separate from voice:
 
-- **Mermaid diagrams** render to inline SVG at build time (see
-  `docs/_ext`). Tag any node whose label is a command, code identifier,
-  config key, or other symbol with `:::cmd` so it renders monospace —
+- **Mermaid diagrams** render to inline SVG at build time (via the
+  `sphinx-gp-mermaid` package). Tag any node whose label is a command,
+  code identifier, config key, or other symbol with `:::cmd` so it
+  renders monospace —
   the way that text reads as code inline; leave prose and concept nodes
   unstyled. Prefer top-to-bottom (`flowchart TD`); wide left-to-right
   charts don't scale on narrow viewports. `docs/configuration/workspace-builders.md`