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

• Never edit anything under zbanks-alttp/: it is upstream's tree byte for byte. What the host needs goes in ../../packages/zbanks (shim/host.c for C, src/lib.rs for Rust) or in a compiler flag in BUCK, with a comment saying what forced it.
• A change the host genuinely cannot make from outside is a carried patch: a new patches/NNNN-what-it-does.patch (a git diff of the vendored file, applied with -p4), in its own commit named for what it does, with a comment in the patched code starting Carried patch (jev):, and a row in patches/README.md plus its notes in patches/CLAUDE.md. :patched in BUCK applies them in name order; one that stops applying fails the build. To make one: edit the vendored file, git diff --no-color <file> > patches/NNNN-....patch, git checkout <file>.
• BUCK globs patches/*.patch only, so patches/README.md and patches/CLAUDE.md are inert to the build. Keep any other file there out of that glob's reach.
• -Dap_goal_add=zb_goal_add applies to ap_map.c only (BUCK). That is what lets the host decline goals the save says are done while ap_plan.c keeps the real ap_goal_add. Adding the define to every source would rename the definition too and silently remove the host from the path.
• To refresh from upstream: git fetch ~/src/github.com/zbanks/alttp master, git rm -r third-party/c/zbanks-alttp, git read-tree --prefix=third-party/c/zbanks-alttp/ -u <commit>, build (every patch must still apply, or be dropped with its row in patches/ if upstream fixed the same thing), and update the commit hash in README.md, ../../packages/zbanks (src/lib.rs, shim/host.c) and ../../research/zbanks-alttp.md.
• The bot writes debug files with bare relative names; -Dfopen=zb_fopen and -Drename=zb_rename in BUCK send them to the host's chosen directory. A new libc file call in a future upstream (remove, open) needs the same treatment, or its file lands in the repo root.