Vendor OpenClaw source as Adolf fork baseline

Adolf is a fork/vendored clone of github.com/openclaw/openclaw (v2026.6.11),
free to diverge. Tree copied sans upstream .git; upstream remote added for
future syncs. Node pinned to 24 (.nvmrc); engines already require >=22.19.
Preserves docs/ARCHITECTURE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2

apps/android/README.md

@@ -0,0 +1,345 @@
+## OpenClaw Android App
+
+OpenClaw Android is the officially released Google Play app. It connects to an OpenClaw Gateway as a companion node for chat, voice, approvals, screen, and device-aware automation.
+
+### Current App Surface
+
+- [x] New 4-step onboarding flow
+- [x] Connect tab with `Setup Code` + `Manual` modes
+- [x] Encrypted persistence for gateway setup/auth state
+- [x] Chat UI restyled
+- [x] Settings UI restyled and de-duplicated (gateway controls moved to Connect)
+- [x] QR code scanning in onboarding
+- [x] Performance improvements
+- [x] Streaming support in chat UI
+- [x] Request camera/location and other permissions in onboarding/settings flow
+- [x] Push notifications for gateway/chat status updates
+- [x] Security hardening (biometric lock, token handling, safer defaults)
+- [x] Authenticated background presence beacons
+- [x] Voice tab full functionality
+- [x] Screen tab full functionality
+
+## Open in Android Studio
+
+- Open the folder `apps/android`.
+
+## Build / Run
+
+```bash
+cd apps/android
+./gradlew :app:assemblePlayDebug
+./gradlew :app:installPlayDebug
+./gradlew :app:testPlayDebugUnitTest
+cd ../..
+pnpm android:release:archive
+```
+
+Third-party debug flavor:
+
+```bash
+cd apps/android
+./gradlew :app:assembleThirdPartyDebug
+./gradlew :app:installThirdPartyDebug
+./gradlew :app:testThirdPartyDebugUnitTest
+```
+
+Android release archives use the pinned version in `apps/android/version.json`. Update it with:
+
+```bash
+pnpm android:version
+pnpm android:version:check
+pnpm android:version:pin -- --from-gateway
+pnpm android:version:pin -- --version 2026.6.5 --version-code 2026060501
+```
+
+Release-owner signing sync:
+
+```bash
+pnpm android:release:signing:plan
+MATCH_PASSWORD=<signing repo password> pnpm android:release:signing:sync:pull
+MATCH_PASSWORD=<signing repo password> pnpm android:release:signing:check
+```
+
+The signing sync pulls encrypted Android upload-key assets from the shared `apps-signing` repo and materializes decrypted files under `apps/android/build/release-signing/`.
+
+Generate raw Google Play screenshots:
+
+```bash
+pnpm android:screenshots
+```
+
+To make screenshot capture own emulator startup, pass a named AVD:
+
+```bash
+ANDROID_SCREENSHOT_AVD=OpenClaw_QA_API35 pnpm android:screenshots
+```
+
+The screenshot script uses one connected ADB device when available. If none is
+connected and `ANDROID_SCREENSHOT_AVD` is set, it boots that emulator
+headlessly, waits for Android to finish booting, disables animations, captures
+the screenshots, then shuts down the emulator it started.
+
+`pnpm android:release:archive` builds signed release artifacts into `apps/android/build/release-artifacts/` and writes `.sha256` checksum files:
+
+- Play build: `openclaw-<version>-play-release.aab`
+- Third-party build: `openclaw-<version>-third-party-release.apk`
+
+`pnpm android:bundle:release` is an alias for the same Fastlane archive lane.
+
+`pnpm android:release:archive` is for local archive validation only. It is not a
+fallback upload path after `pnpm android:release:upload` fails.
+
+Agent-driven Google Play uploads must use `pnpm android:release:upload` as the
+only release path. If that command fails, stop and fix the failing screenshot,
+metadata, signing, validation, archive, or upload step before trying again. Do
+not upload archived artifacts through direct Fastlane lanes, Gradle artifacts,
+Google Play API commands, or Play Console mutation commands.
+
+See `apps/android/VERSIONING.md` and `apps/android/fastlane/SETUP.md` for the release workflow.
+
+Flavor-specific direct Gradle tasks:
+
+```bash
+cd apps/android
+./gradlew :app:bundlePlayRelease
+./gradlew :app:bundleThirdPartyRelease
+```
+
+## Kotlin Lint + Format
+
+```bash
+pnpm android:lint
+pnpm android:format
+```
+
+Android framework/resource lint (separate pass):
+
+```bash
+pnpm android:lint:android
+```
+
+Direct Gradle tasks:
+
+```bash
+cd apps/android
+./gradlew :app:ktlintCheck :benchmark:ktlintCheck
+./gradlew :app:ktlintFormat :benchmark:ktlintFormat
+./gradlew :app:lintPlayDebug :app:lintThirdPartyDebug
+```
+
+`gradlew` auto-detects the Android SDK at `~/Library/Android/sdk` (macOS default) if `ANDROID_SDK_ROOT` / `ANDROID_HOME` are unset.
+
+## Macrobenchmark (Startup + Frame Timing)
+
+```bash
+cd apps/android
+./gradlew :benchmark:connectedDebugAndroidTest
+```
+
+Reports are written under:
+
+- `apps/android/benchmark/build/reports/androidTests/connected/`
+
+## Perf CLI (low-noise)
+
+Deterministic startup measurement + hotspot extraction with compact CLI output:
+
+```bash
+cd apps/android
+./scripts/perf-startup-benchmark.sh
+./scripts/perf-startup-hotspots.sh
+```
+
+Benchmark script behavior:
+
+- Runs only `StartupMacrobenchmark#coldStartup` (10 iterations).
+- Prints median/min/max/COV in one line.
+- Writes timestamped snapshot JSON to `apps/android/benchmark/results/`.
+- Auto-compares with previous local snapshot (or pass explicit baseline: `--baseline <old-benchmarkData.json>`).
+
+Hotspot script behavior:
+
+- Ensures debug app installed, captures startup `simpleperf` data for `.MainActivity`.
+- Prints top DSOs, top symbols, and key app-path clues (Compose/MainActivity/WebView).
+- Writes raw `perf.data` path for deeper follow-up if needed.
+
+## Run on a Real Android Phone (USB)
+
+1) On phone, enable **Developer options** + **USB debugging**.
+2) Connect by USB and accept the debugging trust prompt on phone.
+3) Verify ADB can see the device:
+
+```bash
+adb devices -l
+```
+
+4) Install + launch debug build:
+
+```bash
+pnpm android:install
+pnpm android:run
+```
+
+If `adb devices -l` shows `unauthorized`, re-plug and accept the trust prompt again.
+
+### USB-only gateway testing (no LAN dependency)
+
+Use `adb reverse` so Android `localhost:18789` tunnels to your laptop `localhost:18789`.
+
+Terminal A (gateway):
+
+```bash
+pnpm openclaw gateway --port 18789 --verbose
+```
+
+Terminal B (USB tunnel):
+
+```bash
+adb reverse tcp:18789 tcp:18789
+```
+
+Then in app **Connect → Manual**:
+
+- Host: `127.0.0.1`
+- Port: `18789`
+- TLS: off
+
+## Hot Reload / Fast Iteration
+
+This app is native Kotlin + Jetpack Compose.
+
+- For Compose UI edits: use Android Studio **Live Edit** on a debug build (works on physical devices; project `minSdk=31` already meets API requirement).
+- For many non-structural code/resource changes: use Android Studio **Apply Changes**.
+- For structural/native/manifest/Gradle changes: do full reinstall (`pnpm android:run`).
+- Canvas web content already supports live reload when loaded from Gateway `__openclaw__/canvas/` (see `docs/platforms/android.md`).
+
+## Connect / Pair
+
+1) Start the gateway (on your main machine):
+
+```bash
+pnpm openclaw gateway --port 18789 --verbose
+```
+
+2) In the Android app:
+
+- Open the **Connect** tab.
+- Use **Setup Code** or **Manual** mode to connect.
+
+3) Approve pairing (on the gateway machine):
+
+```bash
+openclaw devices list
+openclaw devices approve <requestId>
+```
+
+More details: `docs/platforms/android.md`.
+
+## Permissions
+
+- Discovery:
+  - Android 13+ (`API 33+`): `NEARBY_WIFI_DEVICES`
+  - Android 12 and below: `ACCESS_FINE_LOCATION` (required for NSD scanning)
+- Foreground service notification (Android 13+): `POST_NOTIFICATIONS`
+- Camera:
+  - `CAMERA` for `camera.snap` and `camera.clip`
+  - `RECORD_AUDIO` for `camera.clip` when `includeAudio=true`
+
+## Google Play Restricted Permissions
+
+As of March 19, 2026, these manifest permissions are the main Google Play policy risk for this app:
+
+- `READ_SMS`
+- `SEND_SMS`
+- `READ_CALL_LOG`
+
+Why these matter:
+
+- Google Play treats SMS and Call Log access as highly restricted. In most cases, Play only allows them for the default SMS app, default Phone app, default Assistant, or a narrow policy exception.
+- Review usually involves a `Permissions Declaration Form`, policy justification, and demo video evidence in Play Console.
+- The Play build removes these behind the `play` flavor.
+- Photo library access is also removed from the Play build. Use third-party builds for `photos.latest`.
+
+Current OpenClaw Android implication:
+
+- APK / sideload build can keep SMS, Call Log, and recent-photo features.
+- Google Play build excludes SMS send/search, Call Log search, and recent-photo access unless the product is intentionally positioned and approved under the relevant policy exception.
+- The repo now ships this split as Android product flavors:
+  - `play`: removes `READ_SMS`, `SEND_SMS`, `READ_CALL_LOG`, `READ_MEDIA_IMAGES`, `READ_MEDIA_VISUAL_USER_SELECTED`, and `READ_EXTERNAL_STORAGE`; hides SMS, Call Log, and Photos surfaces in onboarding, settings, and advertised node capabilities.
+  - Installed-app listing is user controlled. `device.apps` is advertised only after the user enables **Settings > Phone Capabilities > Installed Apps**. The command defaults to launcher-visible apps and does not require `QUERY_ALL_PACKAGES`.
+  - `thirdParty`: keeps the full permission set and the existing SMS / Call Log / Photos functionality.
+
+Policy links:
+
+- [Google Play SMS and Call Log policy](https://support.google.com/googleplay/android-developer/answer/10208820?hl=en)
+- [Google Play sensitive permissions policy hub](https://support.google.com/googleplay/android-developer/answer/16558241)
+- [Android default handlers guide](https://developer.android.com/guide/topics/permissions/default-handlers)
+
+Other Play-restricted surfaces to watch if added later:
+
+- `ACCESS_BACKGROUND_LOCATION`
+- `MANAGE_EXTERNAL_STORAGE`
+- `QUERY_ALL_PACKAGES`
+- `REQUEST_INSTALL_PACKAGES`
+- `AccessibilityService`
+
+Reference links:
+
+- [Background location policy](https://support.google.com/googleplay/android-developer/answer/9799150)
+- [AccessibilityService policy](https://support.google.com/googleplay/android-developer/answer/10964491?hl=en-GB)
+- [Photo and Video Permissions policy](https://support.google.com/googleplay/android-developer/answer/14594990)
+
+## Integration Capability Test (Preconditioned)
+
+This suite assumes setup is already done manually. It does **not** install/run/pair automatically.
+
+Pre-req checklist:
+
+1) Gateway is running and reachable from the Android app.
+2) Android app is connected to that gateway and `openclaw nodes status` shows it as paired + connected.
+3) App stays unlocked and in foreground for the whole run.
+4) Open the app **Screen** tab and keep it active during the run (canvas/A2UI commands require the canvas WebView attached there).
+5) Grant runtime permissions for capabilities you expect to pass (camera/mic/location/notification listener/location, etc.).
+6) No interactive system dialogs should be pending before test start.
+7) Canvas host is enabled and reachable from the device for remote Canvas checks (do not run gateway with `OPENCLAW_SKIP_CANVAS_HOST=1`; startup logs should include `canvas host mounted at .../__openclaw__/`).
+8) Local operator test client pairing is approved. If first run fails with `pairing required`, preview the latest pending request, approve the printed request ID, then rerun:
+9) For A2UI checks, keep the app on **Screen** tab; the node uses its bundled app-owned A2UI page for message application.
+
+```bash
+openclaw devices list
+openclaw devices approve --latest   # preview only; copy the requestId from output
+openclaw devices approve <requestId>
+```
+
+Run:
+
+```bash
+pnpm android:test:integration
+```
+
+Optional overrides:
+
+- `OPENCLAW_ANDROID_GATEWAY_URL=ws://...` (default: from your local OpenClaw config)
+- `OPENCLAW_ANDROID_GATEWAY_TOKEN=...`
+- `OPENCLAW_ANDROID_GATEWAY_PASSWORD=...`
+- `OPENCLAW_ANDROID_NODE_ID=...` or `OPENCLAW_ANDROID_NODE_NAME=...`
+
+What it does:
+
+- Reads `node.describe` command list from the selected Android node.
+- Invokes advertised non-interactive commands.
+- Skips `screen.record` in this suite (Android requires interactive per-invocation screen-capture consent).
+- Asserts command contracts (success or expected deterministic error for safe-invalid calls like `sms.send` and `notifications.actions`).
+
+Common failure quick-fixes:
+
+- `pairing required` before tests start:
+  - list pending requests (`openclaw devices list`), then approve with the exact ID (`openclaw devices approve <requestId>`) and rerun.
+- `A2UI host not reachable` / `A2UI_HOST_UNAVAILABLE`:
+  - keep the app foregrounded on the **Screen** tab and rerun. A2UI commands use the bundled app-owned A2UI page; the Gateway Canvas host is still needed for remote Canvas checks, but not for A2UI message application.
+- `NODE_BACKGROUND_UNAVAILABLE: canvas unavailable`:
+  - app is not effectively ready for canvas commands; keep app foregrounded and **Screen** tab active.
+
+## Contributions
+
+Maintainer: @obviyus. For issues/questions/contributions, please open an issue or reach out on Discord.