Docs: build-time mermaid + tmux-layout diagram rendering

[tony]

Summary

• Add a build-time mermaid pipeline: a mermaid directive renders fenced diagrams to inline SVG during the Sphinx build (via mmdc), so diagrams paint with the page — no client-side mermaid runtime, no layout shift, no staggered pop-in, and they survive gp-sphinx's SPA navigation as live DOM.
• Add a tmux-layout directive that draws real tmux pane layouts as inline SVG in pure Python — the aafig successor, tmux-aware. Authors declare a screen size and a named layout; panes tile the screen with single dividers, top-left shell commands, pygments-highlighted in the site's code font and colours.
• Theme-match both: diagrams adapt to light/dark from furo's own tokens and .highlight rules, so they look native in either theme.
• Add docs/AGENTS.md (a docs-prose voice guide, symlinked from docs/CLAUDE.md) and rewrite the workspace-builders intro to lead with the concept rather than the config keys.
• Provision the docs CI to render diagrams (mmdc + headless Chrome); without it the build still succeeds but degrades a diagram to its source text with a single warning.

Changes by area

Diagram extensions

• docs/_ext/mermaid_inline.py: mermaid directive → HTML write-phase visitor that shells to mmdc, content-hash-caches per theme, normalizes the SVG (unique id, explicit width/height from the viewBox, stripped max-width), and inlines light+dark variants toggled by CSS. Falls back to a <pre> with a one-time warning when the renderer is absent.
• docs/_ext/tmux_layout.py: tmux-layout directive. Computes filling geometry for tmux's named layouts (even-vertical/horizontal, main-vertical/horizontal, tiled) and emits one inline SVG — panes tile with single dividers, text top-left, pygments shell highlighting reusing furo's .highlight rules via fill: currentColor. Pure Python, no headless browser.
• docs/_static/css/gp-diagram.css, gp-tmux-layout.css: theme-adaptive styling (light/dark), code-block-matched fonts and backgrounds.

Docs content & voice

• docs/configuration/workspace-builders.md: concept-first intro, a tmuxp load → Workspace Builder → Attach tmux session flow diagram, libtmux linked.
• docs/configuration/examples.md: the pane-layout examples now use tmux-layout (faithful tmux geometry) instead of ASCII art.
• docs/AGENTS.md + docs/CLAUDE.md (symlink): the docs prose voice guide.

Toolchain & CI

• .github/workflows/docs.yml: Node/pnpm setup, a Puppeteer-browser cache, and a version-matched Chrome install before the docs build.
• docs/package.json + pnpm lock/workspace: pin @mermaid-js/mermaid-cli. docs/node_modules and the render cache are gitignored.

Design decisions

• Build-time SVG, not client-side mermaid: client mermaid.run() renders after paint (layout shift + flash + per-diagram stagger) and, with gp-sphinx's synchronous View-Transition swap, the diagram would flash in after the crossfade. Build-time inline SVG paints with the page and rides SPA swaps untouched. The cost — owned explicitly — is a headless-Chrome build dependency (mmdc); there is no pure-Node path, since mermaid needs real browser text metrics.
• tmux-layout is a Python directive, not a mermaid extension: tmux layouts are pure geometry, where mermaid's browser-based layout engine is all cost and no benefit. A Python renderer needs no browser, and reusing furo's .highlight CSS makes the panes pixel-identical to the site's code blocks in both themes — which baked-in mermaid colours can't do.
• Cache keyed on the full render config: the on-disk render cache digest includes the theme variables and themeCSS, so a styling change busts the cache instead of serving a stale SVG.

Test plan

• uv run ruff check . --fix && uv run ruff format . — clean
• uv run mypy . — clean
• uv run py.test --reruns 0 — green, including new tests/test_docs_mermaid.py and tests/test_docs_tmux_layout.py (NamedTuple-parametrized: SVG normalization, render cache idempotency, missing-renderer fallback, tmux geometry fills the screen, shell highlighting, the setup() contracts)
• just build-docs — succeeds with no new warnings against the existing baseline; diagrams render as inline themed SVG on the workspace-builders and examples pages

Setup required

The docs build environment must provide the diagram renderer, or mermaid diagrams degrade to text:

1. pnpm -C docs install
2. pnpm -C docs rebuild puppeteer (installs the version-matched headless Chrome)

The docs.yml workflow already does this for CI.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.56%. Comparing base (812dcca) to head (88b115d).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1071   +/-   ##
=======================================
  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.