For agents, on top of README.md, which they read first.

• The suite's invariants are one folder up, in tests/CLAUDE.md.
• Start instances only through TestPostgres. Its PDEATHSIG is what makes teardown leak-proof; never spawn postgres another way.
• Never give an instance a TCP port. It listens on a Unix socket in its own temp dir: a port picked by binding 0 and releasing it can be taken by another process before the server binds it.
• Several instances at once go through TestPostgres::start_all. Taking slots one at a time is hold-and-wait: three sidecar_cli tests on 3 cores each held one slot and waited for another until buck killed them at 10 minutes (2026-09-27). A second start on a thread that already holds a slot panics on purpose.
• The slot directory is fixed (/tmp/postjevsql-test-slots-<uid>), not temp_dir(), so every worktree's daemon and every test sandbox share one set of slots.
• gates.rs is the one copy of what the gates ask. A replay matches by exact request bytes, so changing its rows, question or SQL breaks every gate_* test until the fixtures are re-recorded.