tmux-python · tony · Jun 30, 2026 · Jun 30, 2026 · Jun 30, 2026 · Jun 30, 2026
diff --git a/CHANGES b/CHANGES
@@ -54,6 +54,16 @@ site's light/dark palette and code styling, replacing the old static ASCII art.
 with a concept-first overview, and {ref}`examples` shows each pane example as a
 faithful tmux window layout.
 
+#### Concept-first documentation pass (#1072)
+
+The docs now open with what each feature *is* before its configuration, in a
+consistent second-person voice, with advanced and Python-only material marked
+opt-in. New diagrams trace the plugin hook lifecycle, the CLI request flow, the
+workspace hierarchy, and what `tmuxp load` does inside an existing session, and
+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.
+
 ## 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/README.md b/README.md
@@ -1,6 +1,6 @@
 # tmuxp
 
-Session manager for tmux, which allows users to save and load tmux sessions through simple configuration files. Powered by [libtmux](https://github.com/tmux-python/libtmux).
+Session manager for tmux. Save and load your tmux sessions through simple configuration files. Powered by [libtmux](https://github.com/tmux-python/libtmux).
 
 [![Python Package](https://img.shields.io/pypi/v/tmuxp.svg)](https://pypi.org/project/tmuxp/)
 [![Docs](https://github.com/tmux-python/tmuxp/workflows/docs/badge.svg)](https://tmuxp.git-pull.com/)
@@ -13,46 +13,46 @@ is available on Leanpub and [Amazon Kindle](http://amzn.to/2gPfRhC).
 Read and browse the book for free [on the
 web](https://leanpub.com/the-tao-of-tmux/read).
 
-**Have some spare time?** Help us triage and code review and the tracker. See [issue
+**Have some spare time?** Help us triage and code-review on the tracker. See [issue
 #290](https://github.com/tmux-python/tmuxp/discussions/290)!
 
 # Installation
 
 pip:
 
 ```console
-$ pip install --user tmuxp
+pip install --user tmuxp
 ```
 
 If you're managing the project with [uv](https://docs.astral.sh/uv/), add tmuxp as a dependency instead:
 
 ```console
-$ uv add tmuxp
+uv add tmuxp
 ```
 
 To run tmuxp without installing it globally, similar to `pipx`, invoke it with
 [uvx](https://docs.astral.sh/uv/guides/tools/):
 
 ```console
-$ uvx tmuxp
+uvx tmuxp
 ```
 
 Homebrew:
 
 ```console
-$ brew install tmuxp
+brew install tmuxp
 ```
 
 Debian / ubuntu:
 
 ```console
-$ sudo apt install tmuxp
+sudo apt install tmuxp
 ```
 
 Nix:
 
 ```console
-$ [[ -z $(which tmux) ]] && (nix-env -i tmux && nix-env -i tmuxp) || nix-env -i tmuxp
+[[ -z $(which tmux) ]] && (nix-env -i tmux && nix-env -i tmuxp) || nix-env -i tmuxp
 ```
 
 Find the package for your distro on repology: <https://repology.org/project/tmuxp/versions>
@@ -149,7 +149,7 @@ Load your tmuxp config from anywhere by using the filename, assuming
 _\~/.config/tmuxp/mysession.yaml_ (or _.json_):
 
 ```console
-$ tmuxp load mysession
+tmuxp load mysession
 ```
 
 See [author's tmuxp configs](https://github.com/tony/tmuxp-config) and
@@ -165,7 +165,7 @@ server, session, and window in
 [libtmux](https://github.com/tmux-python/libtmux) objects.
 
 ```console
-$ tmuxp shell
+tmuxp shell
 
 (Pdb) server
 <libtmux.server.Server object at 0x7f7dc8e69d10>
@@ -190,10 +190,10 @@ Supports [PEP
 (including `PYTHONBREAKPOINT`). Also supports direct commands via `-c`:
 
 ```console
-$ tmuxp shell -c 'print(window.name)'
+tmuxp shell -c 'print(window.name)'
 my_window
 
-$ tmuxp shell -c 'print(window.name.upper())'
+tmuxp shell -c 'print(window.name.upper())'
 MY_WINDOW
 ```
 
@@ -220,7 +220,7 @@ You can also load sessions in the background by passing `-d` flag
 Snapshot your tmux layout, pane paths, and window/session names.
 
 ```console
-$ tmuxp freeze session-name
+tmuxp freeze session-name
 ```
 
 See more about [freezing
@@ -231,7 +231,7 @@ tmux](https://tmuxp.git-pull.com/cli/freeze/) sessions.
 Convert a session file from yaml to json and vice versa.
 
 ```console
-$ tmuxp convert filename
+tmuxp convert filename
 ```
 
 This will prompt you for confirmation and shows you the new file that is
@@ -240,8 +240,8 @@ going to be written.
 You can auto confirm the prompt. In this case no preview will be shown.
 
 ```console
-$ tmuxp convert -y filename
-$ tmuxp convert --yes filename
+tmuxp convert -y filename
+tmuxp convert --yes filename
 ```
 
 # Plugin System
@@ -255,13 +255,13 @@ The `load` command provides a way to log output to a log file for
 debugging purposes.
 
 ```console
-$ tmuxp load --log-file <log-file-name> .
+tmuxp load --log-file <log-file-name> .
 ```
 
 Collect system info to submit with a Github issue:
 
 ```console
-$ tmuxp debug-info
+tmuxp debug-info
 ------------------
 environment:
     system: Linux

diff --git a/docs/AGENTS.md b/docs/AGENTS.md
@@ -68,6 +68,25 @@ by shrinking audience, an honest trade-off on the prompt wait, and
 precise reference tables left precise. Read it before reshaping another
 page.
 
+## Diagrams and reference pages
+
+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 —
+  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.
+- **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::`
+  registers a cross-reference target but renders an empty page — reach
+  for it only to add a *package* target to an index page that already
+  carries its own content (grids, prose), where `automodule` would
+  duplicate members documented on the leaf pages.
+
 ## Before you commit
 
 - Does the page open with what the feature *is*, or with how to
@@ -78,3 +97,5 @@ page.
   concept instead?
 - Are the advanced and Python-only parts clearly marked opt-in?
 - Did you leave every table, error string, and cross-reference exact?
+- Are diagram command/symbol nodes tagged `:::cmd`, and is the chart
+  vertical unless it has a reason to be wide?
diff --git a/docs/about_tmux.md b/docs/about_tmux.md
@@ -38,29 +38,23 @@ inside the text dimension. Inside tmux you can:
 | ----------- | ------------------------------- | ------------------------------------- |
 | Multiplexer | Multi-tasking                   | Multiple applications simultaneously. |
 | Session     | Desktop                         | Applications are visible here         |
-| Window      | Virtual Desktop or applications | A desktop that stores it own screen   |
+| Window      | Virtual Desktop or applications | A desktop that stores its own screen  |
 | Pane        | Application                     | Performs operations                   |
 
-```{eval-rst}
-.. aafig::
-    :textual:
-
-    +----------------------------------------------------------------+
-    |  +--------+--------+ +-----------------+ +-----------------+   |
-    |  | pane   | pane   | | pane            | | pane            |   |
-    |  |        |        | |                 | |                 |   |
-    |  |        |        | |                 | |                 |   |
-    |  +--------+--------+ |                 | +-----------------+   |
-    |  | pane   | pane   | |                 | | pane            |   |
-    |  |        |        | |                 | |                 |   |
-    |  |        |        | |                 | |                 |   |
-    |  +--------+--------+ +-----------------+ +-----------------+   |
-    |  | window          | | window          | | window          |   |
-    |  \--------+--------/ \-----------------/ \-----------------/   |
-    +----------------------------------------------------------------+
-    | session                                                        |
-    \----------------------------------------------------------------/
-```
+:::{mermaid}
+:caption: A session holds windows; each window holds one or more panes.
+
+flowchart TD
+    session["session"] --> w1["window"]
+    session --> w2["window"]
+    session --> w3["window"]
+    w1 --> p1["pane"]
+    w1 --> p2["pane"]
+    w1 --> p3["pane"]
+    w1 --> p4["pane"]
+    w3 --> p5["pane"]
+    w3 --> p6["pane"]
+:::
 
 - 1 {term}`Server`.
 
@@ -84,66 +78,36 @@ splitting up 1 terminal into multiple.
 One screen can be used to edit a file, and another may be used to
 `$ tail -F` a logfile.
 
-```{eval-rst}
-.. aafig::
-
-   +--------+--------+
-   | $ bash | $ bash |
-   |        |        |
-   |        |        |
-   |        |        |
-   |        |        |
-   |        |        |
-   |        |        |
-   +--------+--------+
-```
+:::{tmux-layout}
+:size: 40x10
+:layout: even-horizontal
 
-```{eval-rst}
-.. aafig::
-
-   +--------+--------+
-   | $ bash | $ bash |
-   |        |        |
-   |        |        |
-   +--------+--------+
-   | $ vim  | $ bash |
-   |        |        |
-   |        |        |
-   +--------+--------+
-```
+bash
+---
+bash
+:::
+
+:::{tmux-layout}
+:size: 40x12
+:layout: tiled
+
+bash
+---
+bash
+---
+vim
+---
+bash
+:::
 
 tmux supports as many terminals as you want.
 
-```{eval-rst}
-.. aafig::
-   :textual:
-
-   +---------+---------+
-   | $ bash  | $ bash  |
-   |         |         |
-   |         |         |     /-----------------\
-   +---------+---------+ --> |'switch-window 2'|
-   | $ bash  | $ bash  |     \-----------------/
-   |         |         |              |
-   |         |         |              |
-   +---------+---------+              |
-   | '1:sys*  2:vim'   |              |
-   +-------------------+              |
-             /------------------------/
-             |
-             v
-   +---------+---------+
-   | $ vim             |
-   |                   |
-   |                   |
-   +-------------------+
-   | $ bash  | $ bash  |
-   |         |         |
-   |         |         |
-   +-------------------+
-   | '1:sys  2:vim*'   |
-   +-------------------+
-```
+:::{mermaid}
+:caption: Switch between the windows in a session.
+
+flowchart TD
+    w1["window 1 · sys (active)"] -->|"switch-window 2"| w2["window 2 · vim (active)"]
+:::
 
 You can switch between the windows you create.
 
@@ -152,57 +116,13 @@ You can switch between the windows you create.
 You can leave tmux and all applications running (detach), log out, make
 a sandwich, and re-(attach), all applications are still running!
 
-```{eval-rst}
-.. aafig::
-   :textual:
-
-   +--------+--------+
-   | $ bash | $ bash |
-   |        |        |
-   |        |        |     /------------\
-   +--------+--------+ --> |   detach   |
-   | $ vim  | $ bash |     | 'Ctrl-b b' |
-   |        |        |     \------------/
-   |        |        |            |
-   +--------+--------+            |
-               /------------------/
-               |
-               v
-   +-----------------------+
-   | $ [screen detached]   |
-   |                       |
-   |                       |
-   |                       |
-   |                       |
-   |                       |
-   |                       |
-   +-----------------------+
-              v
-              |
-              v
-   +-----------------------+
-   | $ [screen detached]   |
-   | $ tmux attach         |
-   |                       |     /------------\
-   |                       | --> | attaching  |
-   |                       |     \------------/
-   |                       |            |
-   |                       |            |
-   +-----------------------+            |
-                                        |
-            /---------------------------/
-            |
-            v
-   +--------+--------+
-   | $ bash | $ bash |
-   |        |        |
-   |        |        |
-   +--------+--------+
-   | $ vim  | $ bash |
-   |        |        |
-   |        |        |
-   +--------+--------+
-```
+:::{mermaid}
+:caption: Detach, leave everything running, and reattach later.
+
+flowchart TD
+    running["session running"] -->|"detach · Prefix d"| detached["screen detached — apps keep running"]
+    detached -->|"tmux attach"| running
+:::
 
 ### Manage workflow