docs: automate CLI demo recordings with virtui + embed across the docs

[Tombar]

Summary

Adds the recording half of the documentation flow — a sibling to the doc-validation harness in #2. That harness proves the copy-paste snippets in docs/ run against the real binary; this drives the same commands under virtui ("Playwright for the terminal"), records each session to asciicast v2, renders to embeddable SVG, and wires them into the docs — so prose, tests, and demos can't drift.

This is the "wire it up for real" follow-through on the earlier prototype: virtui v0.2.0 was installed and the pipeline run end-to-end, so the committed SVGs are recordings of the shipped binary, not mockups.

What's here

The recorder — scripts/record-docs.sh

• Builds failsafe into a throwaway bindir, sandboxes $HOME (failsafe reads all state from $HOME) so demos never touch your real ~/.config/failsafe — same isolation trick as the harness's helpers.bash.
• Starts the virtui daemon, spawns a recorded bash per scenario, types the documented command and --waits for expected screen text (deterministic, no fixed sleeps).
• Parses virtui's session_id: from run output (no jq dependency), kills the session to flush each cast.
• Fixed sandbox path so the explain cwd is readable and committed SVGs diff only when behaviour changes.
• Skips cleanly (exit 0) when virtui is absent — never fails a build. Optional --render turns .cast → .svg (svg-term) or .gif (agg).

The recordings — docs/assets/casts/

Cast	Command	Embedded in
explain-block	failsafe explain "kubectl … delete ns payments"	README hero, getting-started step 3, how-to/explain-a-command
mode-toggle	failsafe mode get / set rw / set ro	getting-started step 4, reference/modes
audit	failsafe audit	how-to/repo-policy

CI — .github/workflows/record-docs.yml: workflow_dispatch-only (same posture as docs.yml). Early-stage virtui is deliberately not wired into the required ci gate — a flaky upstream can never block main.

Docs — docs/demos/README.md: documents the flow and the honest split below.

What's NOT automated (honest split)

virtui is headless/VT100, so it records the CLI surface only. The GUI-only surfaces — WezTerm toasts & format-tab-title, iTerm2's Python-runtime keybinding — are not recordable here and remain manual, exactly the STATIC / LIVE-MANUAL surfaces #2 calls out in test/docs/REPORT.md. This automates the CLI documentation flow, not the full flow.

Test plan

• scripts/record-docs.sh --render — produces 3 casts + 3 SVGs against the real binary (virtui v0.2.0)
• All --wait strings verified against real binary output (Decision: BLOCK, read & write, block rule(s))
• Skips cleanly (exit 0) with virtui absent; bash -n clean
• All three SVGs well-formed XML and contain expected on-screen text
• mkdocs build --strict green; every embedded image path resolves in the built site
• go test ./... unaffected, all green

Depends on nothing in #2, but is designed to pair with it. Recommend landing both — together they give: snippets that work (#2) + demos that show them working (this).

🤖 Generated with Claude Code

---

Generated by Claude Code