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

• Build and run through the devshell: nix develop -c buck2 run //apps/<name>:<name> -- <args>.
• The toolchain builds at opt-level 3 for every target (../toolchains/BUCK says why). Do not add a per-app debug variant to "speed up the build": the core runs below real time unoptimised.
• Everything an app writes goes under run/ (gitignored), never anywhere tracked and never the repo root.