# Android Beta Build and Install

This guide covers the native Kotlin/Compose direct-gateway client at version `v0.1.0-beta.1`. It does not build or require `apps/companion`, publish an APK, or complete the beta release criteria by itself.

## Package identity

- Application ID: `cloud.molberg.hermesmobile`
- Android `versionName`: `0.1.0-beta.1`
- Android `versionCode`: `10001`
- Debug APK: `apps/mobile/android/app/build/outputs/apk/debug/hermes-mobile-v0.1.0-beta.1-debug.apk`

`versionName` is the user-visible semantic version. `versionCode` is an internal monotonically increasing Android package revision and must increase for every later installable build.

## Prerequisites

- JDK 17 or newer supported by the checked-in Android Gradle Plugin.
- Android SDK platform 35, matching build tools, and platform tools.
- Network access for the first dependency resolution, or a complete compatible Gradle cache.
- For installation, a real Android device with USB debugging enabled or a running emulator visible to `adb`.
- For use, an HTTPS upstream Hermes Agent gateway/API server and its bearer token when authentication is enabled.

Do not run Capacitor synchronization for this client. The beta application source is the native project under `apps/mobile/android`.

## Build and test

From the repository root:

```bash
cd apps/mobile/android
GRADLE_USER_HOME="$PWD/../../../.gradle-user" ./gradlew \
  :app:testDebugUnitTest \
  :app:assembleDebug
```

The expected APK is:

```text
app/build/outputs/apk/debug/hermes-mobile-v0.1.0-beta.1-debug.apk
```

Confirm the package metadata before distributing the file:

```bash
aapt dump badging app/build/outputs/apk/debug/hermes-mobile-v0.1.0-beta.1-debug.apk \
  | sed -n '1p'
sha256sum app/build/outputs/apk/debug/hermes-mobile-v0.1.0-beta.1-debug.apk
```

Expected badging includes package `cloud.molberg.hermesmobile`, `versionCode='10001'`, and `versionName='0.1.0-beta.1'`.

The debug APK is signed with the local Android debug key. It is suitable for beta verification, not a production signing or store-release workflow. APKs and build output must remain untracked.

## Clean install and run

Confirm that exactly one intended target is attached:

```bash
adb devices -l
```

Remove any prior installation, then install the newly built APK. Uninstalling clears existing Hermes Mobile app data and stored gateway credentials.

```bash
adb uninstall cloud.molberg.hermesmobile || true
adb install app/build/outputs/apk/debug/hermes-mobile-v0.1.0-beta.1-debug.apk
adb shell monkey -p cloud.molberg.hermesmobile -c android.intent.category.LAUNCHER 1
```

On first launch, complete the required Setup Wizard to configure the upstream gateway directly:

1. Enter the required Remote HTTPS gateway base URL and, optionally, a Local HTTPS URL for the same trusted gateway.
2. Select no authentication, bearer authentication, or username/password authentication to match the gateway configuration, then enter the required credentials.
3. Test the connection. The client probes `/health`, validates compatibility through the authenticated gateway surface, and displays the active Local or Remote route; the wizard finishes only after a successful test.
4. Exercise chat/session behavior only where the gateway advertises the required capabilities.

After setup completes, Settings reopens the same connection profile for later edits and retesting.

Do not enter a legacy companion URL or companion access key. The beta path is the direct upstream Hermes gateway architecture described in `docs/DIRECT_GATEWAY_ARCHITECTURE.md`.

## Required install evidence

Record all of the following before claiming R2 installation verification or a beta release:

- The source commit used for the build.
- Passing Android unit tests and APK assembly.
- `aapt` package/version output and the APK SHA-256.
- A successful clean `adb install` on a named real device or emulator.
- App launch plus direct-gateway configuration and connection result.
- Any observed limitations or failures, without treating source-only checks as device evidence.

## Known limitations

- R1 adaptive/accessibility verification still requires the documented real-device/emulator matrix.
- B3 remains blocked on an official session-search contract and live upstream gateway compatibility evidence.
- Direct gateway chat, streaming, tools, artifacts, and recovery remain capability-gated; unsupported or unverified routes are not inferred.
- The debug APK is not a published release artifact. No beta release exists until all release criteria in `docs/ROADMAP.md` are genuinely satisfied.