diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index 9a9051410e..da88da5f44 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -93,8 +93,10 @@ Two mechanical conventions, separate from voice:
   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`
-  is the reference.
+  charts don't scale on narrow viewports. Add `:alt:`, `:name:`, and
+  `:responsive: fit` to every diagram; use `:responsive: preserve` only
+  when the wide artifact is intentional and should scroll instead of
+  shrinking. `docs/configuration/workspace-builders.md` is the reference.
 - **Internal API pages** document a module with an `{eval-rst}` block
   wrapping `.. automodule:: <module>` (with `:members:`), the way the
   existing `docs/internals/api/**` pages do. A bare `.. py:module::`
diff --git a/docs/about_tmux.md b/docs/about_tmux.md
index 7f06817921..1eee7989e1 100644
--- a/docs/about_tmux.md
+++ b/docs/about_tmux.md
@@ -43,6 +43,9 @@ inside the text dimension. Inside tmux you can:
 
 :::{mermaid}
 :caption: A session holds windows; each window holds one or more panes.
+:alt: tmux session containing windows and panes
+:name: tmux-session-window-pane-tree
+:responsive: fit
 
 flowchart TD
     session["session"] --> w1["window"]
@@ -104,6 +107,9 @@ tmux supports as many terminals as you want.
 
 :::{mermaid}
 :caption: Switch between the windows in a session.
+:alt: switching from one active tmux window to another
+:name: tmux-window-switching
+:responsive: fit
 
 flowchart TD
     w1["window 1 · sys (active)"] -->|"switch-window 2"| w2["window 2 · vim (active)"]
@@ -118,6 +124,9 @@ a sandwich, and re-(attach), all applications are still running!
 
 :::{mermaid}
 :caption: Detach, leave everything running, and reattach later.
+:alt: detaching from and reattaching to a running tmux session
+:name: tmux-detach-reattach-cycle
+:responsive: fit
 
 flowchart TD
     running["session running"] -->|"detach · Prefix d"| detached["screen detached — apps keep running"]
diff --git a/docs/cli/load.md b/docs/cli/load.md
index c0cbfdb8ce..ce1ba88d5a 100644
--- a/docs/cli/load.md
+++ b/docs/cli/load.md
@@ -103,6 +103,9 @@ Or (a)ppend windows in the current active session?
 
 :::{mermaid}
 :caption: Loading from inside an existing tmux client.
+:alt: tmuxp load prompt choices inside an existing tmux client
+:name: tmuxp-load-inside-client
+:responsive: fit
 
 flowchart TD
     load["tmuxp load"]:::cmd --> q{"y / n / a ?"}
diff --git a/docs/conf.py b/docs/conf.py
index c0186c62f0..f48447201c 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -35,9 +35,12 @@
         "sphinx_autodoc_api_style",
         "aafig",
         "sphinx_gp_mermaid",
+        "sphinx_gp_highlighting",
         "tmux_layout",
         "sphinx_autodoc_argparse.exemplar",
     ],
+    gp_highlighting_inline_literals="safe",
+    gp_highlighting_inline_commands=["tmuxp"],
     # Route a plain ```mermaid fence to the mermaid directive (the colon and
     # brace forms route there already via colon_fence). Redundant once the
     # pinned gp-sphinx release auto-routes when sphinx_gp_mermaid is active;
diff --git a/docs/configuration/index.md b/docs/configuration/index.md
index 8cee308410..0cde232732 100644
--- a/docs/configuration/index.md
+++ b/docs/configuration/index.md
@@ -64,6 +64,9 @@ tmuxp will offer to assist when:
 
 :::{mermaid}
 :caption: A workspace file mirrors tmux's own hierarchy.
+:alt: tmuxp workspace file hierarchy from session to windows, panes, and shell commands
+:name: tmuxp-workspace-hierarchy
+:responsive: fit
 
 flowchart TD
     session["session_name"]:::cmd --> w1["window"]
diff --git a/docs/configuration/workspace-builders.md b/docs/configuration/workspace-builders.md
index 837338c0e2..0630477df7 100644
--- a/docs/configuration/workspace-builders.md
+++ b/docs/configuration/workspace-builders.md
@@ -16,6 +16,9 @@ fall back to the default.**
 
 :::{mermaid}
 :caption: How a workspace file becomes a live tmux session.
+:alt: tmuxp load reading workspace config through a workspace builder to attach a session
+:name: tmuxp-workspace-builder-flow
+:responsive: fit
 
 ---
 config:
diff --git a/docs/internals/architecture.md b/docs/internals/architecture.md
index 699f8249d0..0156f25eb5 100644
--- a/docs/internals/architecture.md
+++ b/docs/internals/architecture.md
@@ -7,17 +7,25 @@ modules:
 
 :::{mermaid}
 :caption: How each tmuxp subcommand reaches libtmux.
+:alt: tmuxp CLI subcommands reaching workspace modules and libtmux
+:name: tmuxp-command-architecture
+:responsive: fit
 
-flowchart LR
+flowchart TD
     cli["tmuxp CLI (argparse)"]
-    cli -->|load| loader["workspace.loader"]:::cmd
+    cli --> load["load"]:::cmd
+    load --> loader["workspace.loader"]:::cmd
     loader --> builder["workspace.builder"]:::cmd
     builder --> libtmux["libtmux"]:::cmd
-    cli -->|freeze| freezer["workspace.freezer"]:::cmd
+    cli --> freeze["freeze"]:::cmd
+    freeze --> freezer["workspace.freezer"]:::cmd
     freezer --> libtmux
-    cli -->|convert| reader["_internal.config_reader"]:::cmd
-    cli -->|shell| interactive["libtmux (interactive)"]
-    cli -->|"ls / search"| finders["workspace.finders"]:::cmd
+    cli --> convert["convert"]:::cmd
+    convert --> reader["_internal.config_reader"]:::cmd
+    cli --> shell["shell"]:::cmd
+    shell --> interactive["libtmux (interactive)"]
+    cli --> search["ls / search"]:::cmd
+    search --> finders["workspace.finders"]:::cmd
 :::
 
 ## Key Components
diff --git a/docs/topics/plugins.md b/docs/topics/plugins.md
index 027e2df44a..d664cb633f 100644
--- a/docs/topics/plugins.md
+++ b/docs/topics/plugins.md
@@ -40,6 +40,9 @@ nothing. {ref}`tmuxp load <cli-load>` drives the lifecycle in a fixed order:
 
 :::{mermaid}
 :caption: When each plugin hook fires.
+:alt: tmuxp plugin hook order during tmuxp load
+:name: tmuxp-plugin-hook-order
+:responsive: fit
 
 flowchart TD
     load["tmuxp load"]:::cmd --> bwb["before_workspace_builder"]:::cmd
@@ -71,7 +74,7 @@ interface tmuxp provides, {class}`~tmuxp.plugin.TmuxpPlugin`.
 works just as well. You need only one project file, for whichever packaging tool
 you choose.
 
-```console
+```tree
 python_module
 ├── tmuxp_plugin_my_plugin_module
 │   ├── __init__.py
diff --git a/docs/topics/workflows.md b/docs/topics/workflows.md
index 68a4e52739..2f8108d7cc 100644
--- a/docs/topics/workflows.md
+++ b/docs/topics/workflows.md
@@ -31,6 +31,9 @@ you like it, freeze it to capture the layout, then edit and replay it anywhere:
 
 :::{mermaid}
 :caption: Capture a session once, replay it anywhere.
+:alt: manual tmux session captured with tmuxp freeze and replayed with tmuxp load
+:name: tmuxp-freeze-load-workflow
+:responsive: fit
 
 flowchart TD
     arrange["arrange tmux by hand"] --> freeze["tmuxp freeze"]:::cmd