diff --git a/AGENTS.md b/AGENTS.md
index 1eb9c36..1811c6a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -128,4 +128,6 @@ These features are product requirements, not “nice to have” ideas.
 - Track `gogio` as a Go tool and keep a reproducible `make apk` path for Android packaging.
 - When running tests or other automated validation that may touch persisted UI state, set `KEEPASSGO_STATE_DIR` to an isolated temporary directory so recent-vault history and other local state do not pollute the user’s real config.
 - Prefer commands shaped like `KEEPASSGO_STATE_DIR=\"$(mktemp -d)\" go test ./...` for ad hoc local validation unless a test already manages its own isolated state directory.
+- Do not assume the agent can decrypt SOPS-encrypted secrets in this repository.
+- If work requires plaintext from a SOPS-encrypted secret, stop and ask the user to decrypt it or otherwise provide the needed plaintext.
 - Do not commit generated binaries.
diff --git a/APK.md b/APK.md
index 1aa68ed..355a832 100644
--- a/APK.md
+++ b/APK.md
@@ -8,13 +8,23 @@ make apk
 
 Environment:
 
-- `ANDROID_SDK_ROOT` or `ANDROID_HOME` must point at an Android SDK install.
+- `ANDROID_SDK_ROOT` defaults to `/opt/android-sdk`.
+- `ANDROID_NDK_ROOT` defaults to `/opt/android-ndk`.
+- `JAVA_HOME` defaults to `/usr/lib/jvm/java-25-openjdk`.
 - `APP_ID` overrides the Android application id.
 - `APK_OUT` overrides the output path.
 - `APK_VERSION` overrides the packaged app version.
 - `ANDROID_MIN_SDK` overrides the minimum supported Android SDK.
 - `ANDROID_TARGET_SDK` overrides the target Android SDK.
 
+Installed machine prerequisites expected by this repo:
+
+- `android-sdk-cmdline-tools-latest`
+- `android-sdk-build-tools`
+- `android-platform-35`
+- `android-sdk-platform-tools`
+- JDK 17 or newer
+
 The repo tracks `gogio` as a Go tool, so the build runs through:
 
 ```sh
diff --git a/Makefile b/Makefile
index bf867c1..80647df 100644
--- a/Makefile
+++ b/Makefile
@@ -1,3 +1,7 @@
+ANDROID_SDK_ROOT ?= /opt/android-sdk
+ANDROID_NDK_ROOT ?= /opt/android-ndk
+JAVA_HOME ?= /usr/lib/jvm/java-25-openjdk
+PATH := $(JAVA_HOME)/bin:$(ANDROID_SDK_ROOT)/cmdline-tools/latest/bin:$(ANDROID_SDK_ROOT)/platform-tools:$(PATH)
 APP_ID ?= org.julianfamily.keepassgo
 APK_OUT ?= build/keepassgo.apk
 APK_VERSION ?= 0.1.0.1
@@ -6,7 +10,17 @@ ANDROID_TARGET_SDK ?= 35
 
 .PHONY: apk
 apk:
-	@test -n "$${ANDROID_SDK_ROOT:-$${ANDROID_HOME:-}}" || { echo "Set ANDROID_SDK_ROOT or ANDROID_HOME"; exit 1; }
+	@test -x "$(JAVA_HOME)/bin/java" || { echo "JAVA_HOME must point to a JDK 17+ install"; exit 1; }
+	@test -d "$(ANDROID_SDK_ROOT)" || { echo "ANDROID_SDK_ROOT must point to an Android SDK install"; exit 1; }
+	@test -d "$(ANDROID_NDK_ROOT)" || { echo "ANDROID_NDK_ROOT must point to an Android NDK install"; exit 1; }
+	@test -x "$(ANDROID_SDK_ROOT)/cmdline-tools/latest/bin/sdkmanager" || { echo "Android SDK cmdline-tools are missing"; exit 1; }
+	@test -d "$(ANDROID_SDK_ROOT)/platforms/android-$(ANDROID_TARGET_SDK)" || { echo "Android platform android-$(ANDROID_TARGET_SDK) is missing"; exit 1; }
+	@test -d "$(ANDROID_SDK_ROOT)/build-tools" || { echo "Android build-tools are missing"; exit 1; }
+	@mkdir -p "$(dir $(APK_OUT))"
+	ANDROID_HOME="$(ANDROID_SDK_ROOT)" \
+	ANDROID_SDK_ROOT="$(ANDROID_SDK_ROOT)" \
+	ANDROID_NDK_ROOT="$(ANDROID_NDK_ROOT)" \
+	JAVA_HOME="$(JAVA_HOME)" \
 	go tool gogio -target android \
 		-buildmode exe \
 		-appid $(APP_ID) \