[apiad]

Fixes #68. Fixes #69.

What changed

• AGENTS.md replaces CLAUDE.md: what auditorium is, who it is for, what done means, where things live, the gates, the know-how menu, and how work lands.
• DESIGN.md at the root describes the 4.0 architecture top-down (compile → timeline → seek(t) → surfaces). It keeps the scene-engine spec's D1–D9 labels because code comments cite them, adds the rules decided after the spec, and routes to docs/design/ for the measurements. The 2.0 design.md moves to docs/design/2026-04-17-auditorium-2-rewrite.md as history.
• CLAUDE.md's module tour: most of it was already in docstrings and file-head comments with its reasons. Facts the code lacked became module docstrings in server.py, deck.py, slide.py, layout.py and cli.py. Two were wrong and are corrected: a top-level layout adds aud-layout-mode (it does not remove justify-center), and the exporter docstring still offered PDF.
• know-how/: releasing, adding an animation primitive, running the tests.
• Makefile: test, lint, docs (rift, pinned from GitHub because the PyPI package named rift is unrelated), know-how.
• .rift.yaml: the workspace agent-docs block. All four rules were mutation-tested on a scratch copy, with cmp confirming each mutation changed the file, and each named rule fired. The path rule caught two real broken paths in the first draft of DESIGN.md.
• .github/workflows/tests.yml: lint, docs gate and the suite on every PR, 15-minute cap. It installs ffmpeg and the examples extra and checks for them before testing, because the 12 encode/audio tests and the tesserax deck skip rather than fail without them.

The test hang (#69)

Before the fix the full suite hung in 2 of 3 runs on the VPS. tests/test_server.py alone hung in 8 of 20 runs on this branch and 2 of 12 on a clean origin/main. Every bare TestClient ran each socket on its own event loop. Entered with with, it hung 0 times in 40.

Measured locally

make lint 0, make docs 0 (4 rules pass), make test 190 passed and 13 skipped in 73 s. The skips are ffmpeg and tesserax, which the VPS lacks and CI installs. One full run failed test_a_late_audience_tab_catches_up_to_the_presenter, which is filed as #70 with a hypothesis. It failed 1 in 10 here and 0 in 10 on main, which is within noise, and nothing on its path changed.

Left out on purpose

• The seven open issues from 2019–2021 refer to the 1.x/2.x API. Triage is a separate decision.
• No CHANGELOG entry: nothing here changes what a user of the package sees.

🤖 Generated with Claude Code

[mergify]

This pull request does not currently match the merge queue conditions, so it cannot be queued from here. The box comes back if it matches again.

[apiad]

The first CI run failed test_render_command_exists_and_documents_itself. Rich colours typer's help when it detects CI, and the escape codes split --fps. Reproduced locally with GITHUB_ACTIONS=true, fixed in a3cc01c by matching on the help text with the ANSI codes stripped, and break-checked against a flag that does not exist. Second run: 203 passed, 0 skipped, in 82 s.