diff --git a/README.md b/README.md
index 0da0b46..8c2510b 100644
--- a/README.md
+++ b/README.md
@@ -141,16 +141,39 @@ prints the three environment variables to export (`ANDROID_HOME`, `NDK_HOME`,
 
 ### Build and run
 
+Every Android command needs `ANDROID_HOME` / `NDK_HOME` / `JAVA_HOME`. Source
+the helper once per shell — it auto-detects all three:
+
 ```bash
-cargo tauri android init      # once — scaffolds src-tauri/gen/android
-cargo tauri android dev       # run on an emulator or adb-connected device
-cargo tauri android build --apk
+source scripts/android-env.sh
+```
+
+Then, from the project root:
+
+```bash
+cargo tauri android dev --open   # dev server + open in Android Studio
+cargo tauri android build --apk  # standalone release APK
 ```
 
 `src-tauri/gen/android` is committed (unlike the rest of `gen/`) because
 `AndroidManifest.xml` is hand-edited — Android permissions have no
 `tauri.conf.json` equivalent.
 
+### Working in Android Studio
+
+Use **`cargo tauri android dev --open`** rather than opening
+`src-tauri/gen/android` directly. Studio's Run button delegates the Rust build
+to `cargo tauri android android-studio-script`, which expects a running Tauri
+dev session — it reads the dev-server address from
+`/tmp/<identifier>-server-addr`. Open the Gradle project on its own and the
+build fails with `failed to read missing addr file`.
+
+With the dev session running, Studio's device dropdown, Device Manager
+(emulator), and debugger all work normally.
+
+To build without Studio and without a dev server, use `cargo tauri android
+build` — that path needs no addr file.
+
 ### Card data on a phone
 
 Downloading card data streams ~740MB of JSON to build a ~73MB database, which
diff --git a/scripts/android-env.sh b/scripts/android-env.sh
new file mode 100755
index 0000000..89415d7
--- /dev/null
+++ b/scripts/android-env.sh
@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+#
+# android-env.sh — export the environment the Android build needs.
+#
+# SOURCE this, don't execute it:
+#
+#   source scripts/android-env.sh
+#   cargo tauri android dev --open
+#
+# Everything is auto-detected, so there are no machine-specific paths to keep in
+# sync. Run ./scripts/android-setup.sh first to install the pieces.
+
+_mtgc_android_env() {
+    local sdk ndk jdk
+
+    # --- SDK ---
+    sdk="${ANDROID_HOME:-$HOME/Android/Sdk}"
+    if [ ! -d "$sdk" ]; then
+        echo "android-env: no Android SDK at $sdk (run ./scripts/android-setup.sh)" >&2
+        return 1
+    fi
+
+    # --- NDK: newest *stable* installed (skip beta/rc/canary) ---
+    local best=""
+    for d in "$sdk"/ndk/*; do
+        [ -d "$d" ] || continue
+        case "$(sed -n 's/^Pkg.Revision *= *//p' "$d/source.properties" 2>/dev/null)" in
+            *beta*|*rc*|*canary*) continue ;;
+        esac
+        best="$d"
+    done
+    ndk="$best"
+    if [ -z "$ndk" ]; then
+        echo "android-env: no stable NDK under $sdk/ndk (run ./scripts/android-setup.sh)" >&2
+        return 1
+    fi
+
+    # --- JDK: Gradle/AGP reject very new JDKs; prefer Studio's bundled JBR 21 ---
+    for d in \
+        "$HOME/.local/share/JetBrains/Toolbox/apps/android-studio/jbr" \
+        "$HOME/.local/share/JetBrains/Toolbox/apps/android-studio"/*/jbr \
+        "$HOME/android-studio/jbr" \
+        /opt/android-studio/jbr \
+        /usr/lib/jvm/java-21-openjdk /usr/lib/jvm/java-21-openjdk-* \
+        /usr/lib/jvm/java-17-openjdk /usr/lib/jvm/java-17-openjdk-*
+    do
+        if [ -x "$d/bin/javac" ]; then jdk="$d"; break; fi
+    done
+    if [ -z "$jdk" ]; then
+        echo "android-env: no JDK 21/17 found (Gradle rejects the system default)" >&2
+        return 1
+    fi
+
+    export ANDROID_HOME="$sdk"
+    export NDK_HOME="$ndk"
+    export JAVA_HOME="$jdk"
+    # adb/emulator live here; harmless if already present.
+    case ":$PATH:" in
+        *":$sdk/platform-tools:"*) ;;
+        *) export PATH="$sdk/platform-tools:$PATH" ;;
+    esac
+
+    echo "ANDROID_HOME=$ANDROID_HOME"
+    echo "NDK_HOME=$NDK_HOME"
+    echo "JAVA_HOME=$JAVA_HOME"
+}
+
+_mtgc_android_env
+unset -f _mtgc_android_env