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

For agents

• The design rationale for mesen.nix lives in its header comment, with file:line citations into the Mesen 2 source (tag 2.1.1, reference clone at ~/src/github.com/SourMesen/Mesen2). Re-check those citations when the nixpkgs pin moves Mesen to a new version.
• Test wrapper changes with an isolated HOME/XDG_CONFIG_HOME and --testRunner, against a copy of a real Mesen-written settings.json — that file carries a UTF-8 BOM, a bare seed does not, and both paths must work.
• Running the wrapper merges keys into ${XDG_CONFIG_HOME:-$HOME/.config}/Mesen2/settings.json. Under your real HOME that is the user's live config; see the repo CLAUDE.md before running it anywhere but a scratch HOME.