1@README.md
2
3## For agents
4
5- **Run everything through the devshell** (`nix develop -c …`). A tool missing
6  from it is a line to add to `flake.nix`, not a `nix run nixpkgs#…`.
7- **Never launch the unwrapped Mesen** (`${pkgs.mesen}/bin/Mesen`, or a store
8  path) from outside the devshell. Without the devshell's GPU variables Mesa
9  is on llvmpipe and Mesen's GPU renderer shows a black game surface with
10  working audio, which reads as a broken ROM. `Mesen` on the devshell PATH is
11  the wrapper, which uses the software renderer and works either way.
12- **The GPU is reachable only because the devshell says how.**
13  `GALLIUM_DRIVER=d3d12` and `LD_LIBRARY_PATH=/run/opengl-driver/lib` are set
14  in `flake.nix`; without them GL, EGL and Vulkan all report llvmpipe
15  (measured 2026-09-20). Set `GALLIUM_DRIVER` alone and GL programs fail to
16  start at all (`failed to create drisw screen`). Check with
17  `vulkaninfo --summary` / `glxinfo -B` before blaming a renderer.
18- **`~/.config/Mesen2` is the user's live emulator config — leave it alone.**
19  Any experiment (fresh-install behaviour, settings changes, `--testRunner`
20  runs) gets its own `HOME` and `XDG_CONFIG_HOME` under a scratch directory.
21  Incident 2026-09-20: a research agent `mv`-ed the real directory aside while
22  the user's Mesen was running, and the directory was lost.
23- A new key Mesen must have set goes in the `enforce` attrset in `flake.nix`,
24  not into settings.json by hand — Mesen rewrites that file on exit.
25- **Rust comes from fenix, never from nixpkgs' `rustc`/`cargo`.** The
26  emulator core uses `float_algebraic`, which nixpkgs 26.05's rustc 1.95 does
27  not have (16 E0658 errors, measured 2026-09-20; clean on 1.98.1). `stable`
28  in `flake.nix` is the release CHANNEL — the newest released compiler — not
29  a request for an old one. Move it with `nix flake update fenix`.
30- **A crate that links `snes-core` for the browser needs two things or
31  `getrandom` refuses to compile:** the dependency
32  `getrandom = { version = "0.4", features = ["wasm_js"] }` under
33  `[target.'cfg(target_arch = "wasm32")'.dependencies]`, and the rustflag
34  `--cfg getrandom_backend="wasm_js"` for `wasm32-unknown-unknown`. Same pair
35  jgenesis' own `frontend/jgenesis-web` carries. Proven 2026-09-20 with a
36  probe crate: native `cargo check` and a wasm32 release build both clean.
37  No browser build exists in this repository yet; this is for the first one.
38- Flakes see only git-tracked files: `git add` a new file before `nix develop`
39  will notice it.
40- **The Jev key comes from `op-env-run -- <cmd>` and only from there.** Do not
41  add it to `.envrc`, export it in a shell, write it to a file, or echo it;
42  to check it arrived, print `${#TYPESAFE_API_KEY}`, never the value. Note
43  the `$TYPESAFE_API_KEY` in a command line must be expanded by the CHILD
44  (`op-env-run -- sh -c '…'`), not by the calling shell, where it is unset.
45- **ROMs never enter git**, and no doc names a personal path to them: a reader
46  is told to dump their own cartridge into the gitignored `roms/`.
47- **The folders are a guide, chapter by chapter**, in the style of lmjtfy's
48  (the owner, 2026-10-02: "read like the documentation subsite and like a
49  tutorial flow"). Every owned folder's README is `# Chapter N: <name>,
50  <subtitle>` with an opening that teaches, `> **Aside.**` detours, a `>
51  **Try it.**`, then "For the people who maintain it" with a file map, and a
52  last line `← Previous · Up · Next →`. The chain is a depth-first preorder
53  of the folders, in the order each parent's file table lists its children;
54  the prologue's table is the whole order. A new folder gets its chapter and
55  a CLAUDE.md, and the chapters after it are renumbered. Playful, never at
56  the expense of a true fact. Agent-only rules stay in CLAUDE.md files.