docs: voice-guide compliance pass, diagrams, and fixes

[tony]

Summary

• Align every prose page under docs/ and the README with the docs/AGENTS.md voice guide — concept-first leads, second-person voice, "you can stop here" reassurance, advanced/Python material marked opt-in — while preserving every link, cross-reference, table, and error string.
• Add build-time mermaid and tmux-layout diagrams where prose was carrying structural information: the plugin hook lifecycle, the CLI request flow, the workspace hierarchy, the load attach/append decision, and the freeze→edit→load loop. Diagrams are vertical and tag command/symbol nodes monospace.
• Modernize the tmux primer (about_tmux) by replacing its aafig ASCII art with mermaid and tmux-layout directives that render to theme-aware inline SVG.
• Fix cross-references so internal symbols link: tmuxp.workspace.builder, tmuxp.cli, tmuxp.cli.cli(), tmuxp.cli._formatter, and the libtmux Server/Session/Window/Pane objects. The API index gains the same grid-card navigation as every other index page.
• Fix correctness drift surfaced during the pass: the Python floor (3.9→3.10), make→just throughout the contributor guide, broken include/image paths, leftover reStructuredText link syntax in the quickstart, an unsupported .tmuxp.py claim, and two broken code samples in the plugin guide.
• Record the diagram and API-page conventions in the docs voice guide so they aren't re-litigated.

Changes by area

Configuration

• top-level, environmental-variables, examples, index: concept-first leads; a session→window→pane hierarchy diagram; grammar and word fixes.

Topics

• plugins: rewritten concept-first and marked opt-in; a hook-lifecycle diagram whose firing order is verified against the builder and the load CLI; fixed a Python dict syntax error and an invalid pyproject.toml example.
• workflows: second-person voice, a freeze→edit→load diagram, a {ref} to the exit-codes page.
• library-vs-cli, troubleshooting, custom-workspace-builders: internal cross-references, tmux 3.2a→3.2, reader-addressed intros.

CLI

• load: warmer open; an attach/append/detached decision diagram.
• shell: consolidated the -c material that previously appeared in two non-adjacent sections.
• completion, exit-codes, freeze, recipes: leads, per-example intros, and cross-references.

Internals

• architecture: ASCII request flow → mermaid; link the cli module and entry point, _formatter, the classic builder class, and the libtmux objects.
• api/cli/formatter: new page documenting tmuxp.cli._formatter via automodule, so the module reference resolves to a populated target.
• api/workspace/builder: register the package as a module target so tmuxp.workspace.builder resolves and links.
• api/index: grid cards matching the other index pages.

Guides & front matter

• quickstart: clean MyST (reStructuredText link artifacts removed), Python ≥3.10, dropped the unsupported .tmuxp.py.
• about_tmux: aafig → mermaid + tmux-layout.
• glossary: tidied the Server definition.
• project/contributing: make→just, fixed include/image paths, removed a duplicate clone block and an ownerless TODO.
• project/releasing: active voice; current Markdown changelog format.
• README: active tagline; omit the $ prompt from command blocks.

Conventions

• docs/AGENTS.md: a "Diagrams and reference pages" section — :::cmd monospace nodes and vertical flowchart TD for mermaid, and {eval-rst} automodule for API pages.

Design decisions

• Audit before rewrite: a read-only pass scored each page against the guide, so already-compliant pages were left untouched, avoiding needless churn.
• Preserve the precise blocks: the guide separates framing (warm) from facts (exact). Resolution-order lists, value tables, error strings, and {ref}/{class} roles were kept verbatim; only the prose around them changed.
• Diagrams encode verified facts: the hook-lifecycle and request-flow diagrams assert ordering, so each node and edge was checked against source.
• Diagram ergonomics: vertical charts scale on narrow viewports, so diagrams are flowchart TD (the architecture fan-out stays wide on purpose); command, symbol, and config-key nodes render monospace via :::cmd.
• The README omits $ prompts: GitHub renders code blocks without prompt-aware copy, so a leading $ is copied with the command. The README is the sole exception to the console $-prefix convention used in the Sphinx docs.
• Each commit rebuilds clean: the docs were rebuilt in full before every commit; no new broken references were introduced, and pre-existing broken references in the contributor guide now resolve.

Verification

No reStructuredText reference artifacts remain in the quickstart:

rg -n '\]\_|\]\\:' docs/quickstart.md

No make invocations remain in the contributor guide:

rg -n '\bmake ' docs/project/contributing.md

No aafig blocks remain in the primer:

rg -n 'aafig' docs/about_tmux.md

No leading $ prompts remain in the README:

rg -n '^\s*\$ ' README.md

The builder package is registered as a module target:

rg -n 'py:module:: tmuxp.workspace.builder' docs/internals/api/workspace/builder/index.md

Test plan

• uv run ruff check . — lint clean
• uv run ruff format . — no formatting changes
• uv run mypy — type-check clean
• uv run py.test — suite green (doctests unaffected)
• just build-docs — full rebuild succeeds; no new broken references; contributor-guide include/image references now resolve
• mermaid and tmux-layout directives render to inline SVG; command nodes render monospace
• cross-references resolve in the rendered HTML: tmuxp.workspace.builder, tmuxp.cli, tmuxp.cli.cli(), tmuxp.cli._formatter, and the libtmux Server/Session/Window/Pane objects

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.56%. Comparing base (9c6bd26) to head (e9b2ef7).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1072   +/-   ##
=======================================
  Coverage   82.56%   82.56%           
=======================================
  Files          31       31           
  Lines        2770     2770           
  Branches      518      518           
=======================================
  Hits         2287     2287           
  Misses        346      346           
  Partials      137      137           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.