Improve AGENTS.md guidance

[timflannagan]

This looks like it was effectively scaffolded with any [codex, claude] /init command and doesn't provide a lot of value that the AI can't discover itself at runtime.

[Zandereins]

You're right that most of the current file is /init-scaffold an agent could rediscover at runtime. What it's missing is exactly the part an agent can't cheaply discover: the operational knowledge that isn't in the file tree.

I measured it — I maintain schliff, a deterministic (no-LLM) scorer for AGENTS.md files. Your current file at HEAD:

$ pip install schliff==8.4.0 && schliff score AGENTS.md

structure             80/100
operational_coverage  45/100   <- the gap
efficiency            74/100
composite             64.8/100 [D]

The operational_coverage breakdown is the actionable bit:

Category	Credited?	Why
test commands	✅	real test command found
PR / commit rules	✅	concrete section exists
code style	✅	concrete rules present
setup / install commands	❌	none found
build / run commands	❌	none found
gotchas / pitfalls	❌	no section with concrete, non-obvious warnings

It's also ~30% over the 3,000-token budget the format targets — which supports your scaffold diagnosis: there's prose an agent doesn't need, while the three things it can't infer (how to set up, how to build/run, what non-obviously breaks) are absent.

If useful, I'm happy to submit a PR per your CONTRIBUTING.md that (a) cuts the rediscoverable scaffold and (b) adds the missing setup/build commands + a gotchas section — should land well under budget and be verifiable with the command above. No worries if you'd rather keep it in-house; the breakdown above is reproducible either way.