diff --git a/CLAUDE.md b/CLAUDE.md
index cb898b3..62fd097 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,3 +1,19 @@
+## Build host (ARM64)
+
+The primary dev machine is ARM64 (aarch64) Linux, and Google ships no
+linux-aarch64 `aapt`/`aapt2` — both run under **box64** via wrappers that live
+outside the repo (`~/.gradle/box64-aapt2/aapt2` behind
+`android.aapt2FromMavenOverride`, and an `aapt` wrapper installed straight into
+`~/Android/Sdk/build-tools/*/` because AGP's test-APK installer hardcodes that
+path). Nothing in the project tree depends on this; x86-64 machines and CI are
+unaffected.
+
+The trap: without the `aapt` wrapper, `connectedDebugAndroidTest` **exits
+non-zero even when every test passes** — teardown fails, and Gradle reports it as
+"There were failing tests". If that shows up, read
+`app/build/outputs/androidTest-results/connected/debug/*.xml` for the real
+result before believing the exit code.
+
 ## On-device work (USB-connected phone)
 
 A physical phone is connected over USB. Rules: