docs: align emulator setup with the verified host GPU

AGENTS.md

@@ -90,6 +90,6 @@ notifyListeners();
 - Immersive mode is reapplied on every `resumed` lifecycle event; Android may restore system bars after dialogs or role prompts.
 - The HOME role must be granted for the dashboard to replace the tablet home screen. On the emulator use `cmd role add-role-holder`; the in-app banner and Settings row use `RoleManager`.
 - Screen-space is deliberately finite: test at 1280×800 and 1024×600. Avoid unbounded `ListView`s inside `Column`s.
-- `tool/emulator.sh` starts a headless AVD; use `adb exec-out screencap -p` for screenshots. There may be multiple `adb` binaries on PATH; use the absolute one.
+- `tool/emulator.sh` starts a headless AVD with the **host GPU**; SwiftShader segfaulted on this machine's API 35 image. Use `CARDASH_GPU=swiftshader_indirect` only as a fallback. Use `adb exec-out screencap -p` for screenshots; there may be multiple `adb` binaries on PATH, so use the absolute one.
 - While CarDash is foreground, `MainActivity` consumes hardware volume keys and adjusts `STREAM_MUSIC` so they match the dashboard. Do not remove that override without providing another sync path; otherwise Android controls the ring stream when no media is playing.
 - Reinstalling the app can clear its HOME role; re-run `tool/install.sh` or use Settings > Home app.

README.md

@@ -55,6 +55,11 @@ Also: [All apps](docs/screenshots/all-apps.png) ·
 - **JDK 21** for Gradle (the machine default is JDK 27, which is not validated)
 - Android 10 (API 29) or newer device/emulator
 - A landscape tablet or an emulator; the app locks itself to landscape
+- The prepared tablet AVDs use the **host GPU**; a working GPU driver is recommended
+
+The Android application ID is `com.wasp.cardash_launcher`. Android package
+segments cannot contain hyphens, so the requested `com.wasp.cardash-launcher`
+spelling is normalized to an underscore.
 
 ```bash
 export JAVA_HOME=/usr/lib/jvm/java-21-openjdk
@@ -171,6 +176,21 @@ resolution and the shortcut tile widget. Native package enumeration, the HOME
 role, volume, app launching and PIN flows were verified on both API 35 and
 API 29 tablet emulators, including the release APK.
 
+## Troubleshooting the emulator
+
+The prepared AVDs use the host GPU (`-gpu host`), which is the verified setup on
+this machine. Software rendering with SwiftShader segfaulted on the API 35 image.
+If your machine has no usable GPU, you can try:
+
+```bash
+CARDASH_GPU=swiftshader_indirect ./tool/emulator.sh 35
+```
+
+The prepared AVD resolution is 1280×800. If the emulator is already running,
+`./tool/emulator.sh stop` shuts it down before starting a different one. The
+Android 15 AVD is left running headlessly after development; use
+`./tool/emulator.sh 35 window` for a visible window.
+
 ## Compatibility and limitations
 
 - **minSdk 29 (Android 10)**; compile/targetSdk 36. Nothing in the design
@@ -208,6 +228,7 @@ large numerals and quiet line icons. It is not a copy of that UI.
 
 ## License
 
-This repository is currently local-only; a project license has not been chosen.
+This repository is in local development and has not been pushed or published. A
+project license has not been chosen yet.
 Third-party asset licenses: Manrope (OFL) and Lucide (ISC). The design is
 inspired by TrailCurrent Godwit (MIT).

docs/IMPLEMENTATION_PLAN.md

@@ -108,7 +108,8 @@ Android (Kotlin)
 4. **Emulator stability**: software-rendered headless emulator can be killed by
    the host; scripts use managed background boot and `swiftshader_indirect`.
 5. **Flutter 3.47 / AGP 9.1 / JDK 21**: works on this machine; Java 27 is not the
-   validated toolchain.
+   validated toolchain. The emulator uses the host GPU; SwiftShader segfaulted
+   on the API 35 image, so the helper script defaults to `-gpu host`.
 6. **Uninstall/reinstall** may drop the HOME role; Settings and the installer
    script can restore it.
 

tool/emulator.sh

@@ -5,6 +5,7 @@ SDK="${ANDROID_HOME:-/opt/android-sdk}"
 ADB="$SDK/platform-tools/adb"
 EMULATOR="$SDK/emulator/emulator"
 API="${1:-35}"
+GPU_MODE="${CARDASH_GPU:-host}"
 
 if [[ "$API" == "stop" ]]; then
   if "$ADB" devices | grep -q "emulator-"; then
@@ -27,7 +28,7 @@ if ! "$ADB" devices | grep -q "emulator-"; then
     -avd "$AVD"
     -no-audio
     -no-boot-anim
-    -gpu swiftshader_indirect
+    -gpu "$GPU_MODE"
     -no-snapshot
     -no-metrics
     -camera-back none