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

• Never edit BUCK. Change Cargo.toml, reindeer.toml or a fixup and re-run buckify.
• A new crate with a build.rs makes buckify warn that its fixup "does not say what to do". Answer it in fixups/<crate>/fixups.toml with buildscript.run = true or false - read the build script to decide; most only probe rustc features and need true.
• cargo_env = true in reindeer.toml is load-bearing: serde_core and thiserror read CARGO_PKG_VERSION_PATCH via env!() and fail to compile without it. It must sit above [vendor]: TOML keys after a table header belong to that table.
• jgenesis/ is excluded from this manifest's workspace on purpose. Left in, cargo resolves jgenesis's workspace = true keys against THIS manifest and fails with "workspace.package.version was not defined".
• jgenesis/ carries two patches over upstream d19ee94f: SnesEmulator::wram() (commit "jgenesis: expose work RAM from snes-core") and SnesEmulator::wram_mut() (commit "jgenesis: let a host write work RAM", for the zbanks bot, which writes its cheats into RAM each frame). After git subtree pull --prefix=third-party/rust/jgenesis, confirm both survived: grep -n "pub fn wram" third-party/rust/jgenesis/backend/snes-core/src/api.rs (two hits).
• jgenesis needs a Rust newer than nixpkgs 26.05 ships (it uses float_algebraic); the devshell's fenix toolchain is why it builds.
• Build scripts run inside the buck2 DAEMON's environment, not the calling shell's. After adding something a build script needs to the devshell (pkg-config, a library), run buck2 kill from the new shell first; until then the script fails as if the package were missing (measured 2026-09-20: alsa-sys could not find pkg-config that the shell itself could run).
• alsa-sys is the one crate here that links a system library at build time. Everything the window needs (wayland, xkbcommon, X11, Vulkan, GL) is dlopened at startup instead, which is what LD_LIBRARY_PATH in flake.nix is for.
• jevcrates/ is a git submodule of ~/jevcrates (jev-protocol, jev-client, jev-http), path dependencies in Cargo.toml; they were packages/jev and packages/jev-http until 2026-10-01. Never edit inside it here: change ~/jevcrates, then move the gitlink. Its URL in .gitmodules is relative (../jevcrates.git) so a clone from the lmjtfy site finds it beside this one; do not make it absolute, or a clone from the site points at private GitHub and fails. git submodule update --init checks it out.