why: The topics pages opened in third person about generic "users"
instead of addressing the reader, and the plugin hook order and the
freeze->load loop are far easier to grasp as diagrams than as prose.

what:
- plugins: second-person, concept-first intro; mark plugins
  opt-in/advanced; add a hook-lifecycle mermaid (firing order
  verified against the builder and load CLI); fix a dict-literal
  syntax error and an invalid pyproject example (>=3.8 -> >=3.10,
  tmuxp^=1.7.0 -> tmuxp>=1.7.0, PEP 621 authors)
- workflows: second-person voice, sentence-case headings, a
  freeze->edit->load mermaid, {ref} the exit-codes page
- custom-workspace-builders: address the reader in the intro
- troubleshooting: tmux 3.2a -> 3.2; {ref} completion; bash/zsh/tcsh
- library-vs-cli: link quickstart and examples

why: The command pages opened straight into mechanics, shell
documented -c twice in non-adjacent sections, and the inside-tmux
load choice was described in prose only.

what:
- load: warmer concept-first open; a mermaid for the y/n/a
  switch/append/detached choice
- shell: consolidate the duplicated -c material into one
  "Running code directly" section after interactive usage
- completion: add a concept-first lead naming shtab vs click
- exit-codes: introduce each script example instead of stacking
  them bare
- freeze: Tmuxp -> tmuxp
- recipes: link the full CLI reference

why: The architecture request flow was ASCII art; the workspace
builder reference rendered as dead text because the package had no
module target; and the API index listed its pages as a bare toctree
instead of the grid every other index page uses.

what:
- architecture: ASCII request flow -> mermaid; link the classic
  builder class instead of a stale bare WorkspaceBuilder
- api/workspace/builder: register the package as a py:module so
  {mod}`tmuxp.workspace.builder` resolves and links
- api/index: concept-first lead + grid cards linking each module
  group, matching the other index pages

why: The quickstart still carried reStructuredText link syntax
([uv]_, [pip]\:) that renders broken under MyST, claimed python
>=3.9, and listed a .tmuxp.py config form that tmuxp does not load.

what:
- quickstart: concept-first lead; convert rST references to MyST
  markdown links; one command per console block; python >=3.9 ->
  >=3.10; drop the unsupported .tmuxp.py (only .tmuxp.{yaml,yml,json}
  load); fold the abstraction-layer table under Pythonics
- glossary: tidy the redundant Server definition; "a layouts" ->
  "layouts"

why: The tmux primer drew its session and pane diagrams as aafig
ASCII art. The repo now renders mermaid and tmux-layout to
theme-aware inline SVG, which reads better in light and dark themes.

what:
- session/window/pane hierarchy, window switching, and the
  detach/reattach flow -> mermaid
- the two terminal-split illustrations -> tmux-layout directives
- "stores it own screen" -> "its own screen"

why: contributing documented a make-based workflow, but the repo
uses just; its dev-config include paths and screenshot were one
directory too shallow and never resolved. releasing showed an
outdated rST changelog shape.

what:
- contributing: make -> just throughout (real recipe names); drop a
  duplicated clone block and an ownerless todo; fix the
  tests.yml/.tmuxp.yaml includes and the screenshot path (resolves
  3 build warnings); trim tab boilerplate to single commands
- releasing: active voice; changelog example uses the current
  Markdown "## tmuxp X.Y.Z" form and the fixed subheading order

why: GitHub renders code blocks without prompt-aware copy, so a
leading "$ " is copied along with the command and makes it
uncopyable. The README is the sole exception to the console
$-prefix convention used elsewhere in the docs.

what:
- drop the leading "$ " prompt from every command block
- tagline -> active second person
- "triage and code review and the tracker" -> "code-review on the
  tracker"

why: Left-to-right flowcharts overflow horizontally and do not
scale on narrow or mobile viewports; top-down charts wrap within
the doc column. The architecture request-flow stays LR, where the
fan-out reads better wide.

what:
- workflows freeze->edit->load loop: LR -> TD
- about_tmux window-switch and detach/reattach flows: LR -> TD

why: The architecture page named tmuxp.cli, tmuxp.cli.cli(),
tmuxp.cli._formatter, and the libtmux Server/Session/Window/Pane
objects in plain code, so none of them linked, and _formatter had
no API page to point at.

what:
- architecture: link the cli module and entry point, _formatter,
  and the libtmux objects via {mod}/{func}/{class} roles
- add an api/cli/formatter page (eval-rst automodule) and wire it
  into the toctree, giving {mod}`tmuxp.cli._formatter` a populated
  target

why: Command, symbol, and config-key labels read as code, so they
should render monospace the way inline code does, matching the
workspace-builders diagram's :::cmd nodes.

what:
- tag command/symbol/key nodes with :::cmd across the workflows,
  plugins, configuration, load, and architecture diagrams
- plugins: drop the inline per-hook timing from the nodes so the
  symbol nodes stay clean, and move it into the prose below

why: Review surfaced two conventions worth pinning so they are not
re-litigated: mermaid command nodes should be monospace and
vertical, and API pages need automodule (a bare py:module renders
an empty page).

what:
- add a "Diagrams and reference pages" section: :::cmd + flowchart
  TD for mermaid; {eval-rst} automodule for API reference pages
- add a matching before-you-commit checklist item