gemstone-nexus · Phase 6
Capacitor Android — Practitioner Installation & Operation Playbook
Metadata
| id | doc_id | title | category | source_path | summary | content_hash | indexed_at |
|---|---|---|---|---|---|---|---|
| 1 | CAPACITOR-ANDROID-INSTALLATION-PLAYBOOK | Capacitor Android — Practitioner Installation & Operation Playbook | playbook | DevResources/docs/CAPACITOR-ANDROID-INSTALLATION-PLAYBOOK.md | This playbook is the end-to-end install and operate guide. It does **not** replace mobility specs or device UAT scripts — those live in the referenced docs below. | fc699e305a7e6547713ec6d4d3724259cf203254 | 2026-07-23 16:50:22 |
Content
# Capacitor Android — Practitioner Installation & Operation Playbook
**Audience:** Practitioners and QA standing up GemStone on a Windows 11 workstation
**App ID:** `com.nextech.gemstone` · **App name:** GemStone
**Date:** 2026-07-22 · **Capacitor:** 6.x · **Android:** minSdk 22 / compileSdk 34 / targetSdk 34 · **JDK:** 17+ (Studio JBR OK)
This playbook is the end-to-end install and operate guide. It does **not** replace mobility specs or device UAT scripts — those live in the referenced docs below.
### Fastest path — hosted debug APK (no Studio)
1. On an Android phone, open **[Install Android](https://gemstone.dataright.net/app/install-android)** (also linked from the Voice sidebar).
2. Tap **Download GemStone Android (debug APK)** and wait until the download **finishes** (notification / Downloads list).
3. **Android 13+:** Settings → Apps → Special app access → **Install unknown apps** → enable for **Chrome** and/or **Files** (the browser/file manager that opens the APK). **Do not look for GemStone in that list** — GemStone is not installed yet and will not appear under Apps until step 4 succeeds.
4. Open **Downloads** → tap `gemstone-debug.apk` → **Install**. Only then does GemStone appear in the launcher / Apps.
5. If the UI hangs on **Installing…**: force-stop **Package Installer** (system app), delete the old APK, re-download (`?v=` cache-bust), re-check Chrome/Files unknown-apps, or use USB `adb install -r` below (bypasses the on-device installer UI).
6. Launch **GemStone**. WebView loads `https://gemstone.dataright.net` (Voice console, Mode A).
**Direct download (cache-bust):** [`https://gemstone.dataright.net/downloads/gemstone-debug.apk?v=8edd700ae5e1`](https://gemstone.dataright.net/downloads/gemstone-debug.apk?v=8edd700ae5e1)
**USB fallback (Windows):**
```powershell
# After downloading gemstone-debug.apk to the PC
& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" devices
& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" install -r .\gemstone-debug.apk
```
This is a **debug-signed** sideload build for practitioners/QA — not a Play Store release. Package `com.nextech.gemstone`, minSdk 22 / targetSdk 34. Rebuild + redeploy when native code or Cap sync changes (`downloads/gemstone-debug.apk` is served by nginx with `Content-Disposition: attachment`).
## Related docs (do not duplicate)
| Doc | Use when |
| --- | --- |
| [`GS-MOB-01.md`](GS-MOB-01.md) | Field Mode / Extended Session / wake-word / interruption contract |
| [`DOC-Device-UAT-Checklist.md`](DOC-Device-UAT-Checklist.md) | Outdoor sun, call interruption 10-trial, wake 8/10 sign-off |
| [`DOC-Capacitor-Live-EC2.md`](DOC-Capacitor-Live-EC2.md) | Live EC2 `server.url`, debug TLS trust, env overrides |
| [`DOC-Auth0-Provisioning.md`](DOC-Auth0-Provisioning.md) | Auth0 tenant (deferred — **not** required to install) |
| [`DOC-Store-Submission-Checklist.md`](DOC-Store-Submission-Checklist.md) | Play Console / AAB assembly when accounts exist |
| [`frontend/CAPACITOR.md`](../../frontend/CAPACITOR.md) | Plugin surface, atomic concurrency, gate commands |
| [`DOC08-Playbook.md`](DOC08-Playbook.md) | Production session / Didymus / deploy runbooks |
---
## 1. Windows 11 workstation prerequisites
### 1.1 Node.js and npm
- **Node.js LTS** (20.x or 22.x recommended). Verify:
```powershell
node -v
npm -v
```
### 1.2 Android Studio, SDK, platform & build tools
1. Install [Android Studio](https://developer.android.com/studio) (current stable).
2. Open **Settings → Languages & Frameworks → Android SDK** and install:
- **Android SDK Platform** matching compile/target **34** (Android 14)
- **Android SDK Build-Tools** (latest 34.x)
- **Android SDK Platform-Tools** (`adb`)
- **Android Emulator** (if you will not use a physical device)
3. Note **Android SDK Location** (typical: `%LOCALAPPDATA%\Android\Sdk`).
Set user env vars (System Properties → Environment Variables), then open a **new** PowerShell:
```powershell
# Example — adjust to your SDK path
[System.Environment]::SetEnvironmentVariable("ANDROID_HOME", "$env:LOCALAPPDATA\Android\Sdk", "User")
# Add to User PATH: %ANDROID_HOME%\platform-tools and %ANDROID_HOME%\emulator
```
Verify:
```powershell
adb version
sdkmanager --list 2>$null | Select-Object -First 5 # if cmdline-tools installed
```
### 1.3 JDK 17+ and `JAVA_HOME`
Capacitor Android / Gradle in this repo compile with **Java 17** bytecode (`sourceCompatibility` / `targetCompatibility` = `VERSION_17` in `frontend/android`). The **Android Studio JBR (JDK 17 or 21)** is the preferred toolchain for `assembleDebug`.
- Prefer Studio JBR: `C:\Program Files\Android\Android Studio\jbr`, **or** Temurin/Oracle **JDK 17+**.
- Set `JAVA_HOME` to that JDK root (not JRE). Verify:
```powershell
$env:JAVA_HOME = "C:\Program Files\Android\Android Studio\jbr"
java -version # 17.x or Studio JBR 21.x is fine with AGP 8.2
echo $env:JAVA_HOME
```
**Do not** point `JAVA_HOME` at JDK 8/11 — those cause `Unsupported class file major version` / toolchain errors.
### 1.4 USB debugging / emulator / device
**Physical device**
1. Enable **Developer options** → **USB debugging**.
2. Connect USB; accept the RSA fingerprint prompt on the phone.
3. Verify:
```powershell
adb devices
# expect: <serial> device
```
**Emulator**
1. Android Studio → **Device Manager** → create a virtual device (API 34 recommended).
2. Start the AVD, then `adb devices` should list `emulator-5554` (or similar) as `device`.
---
## 2. Clone / update the repository and install frontend deps
```powershell
# First time
git clone https://github.com/<org>/GemStone-Nexus-StackOne.git
cd GemStone-Nexus-StackOne
# Ongoing
git pull origin main
cd frontend
npm ci
```
Use `npm ci` for a clean, lockfile-faithful install. If `package-lock.json` is missing or intentionally being refreshed, `npm install` is acceptable once, then prefer `npm ci` thereafter.
**Do not** commit `.env`, keystores, Auth0 secrets, or `DevResources/project.env` with credentials. Templates live in `.env.example` / `DevResources/project.env.example`.
---
## 3. Development modes
GemStone Android is a Capacitor shell around the React/Vite SPA. Two modes matter for practitioners.
### Mode A — Live EC2-hosted UI/API (default debug path)
**Intent:** Run Android in parallel with the web stack already deployed on EC2. The WebView loads the remote SPA so Vite `base: "/app/"` stays aligned with nginx.
| Item | Value |
| --- | --- |
| Public SPA | `https://gemstone.dataright.net/app/` (secondary; Field/Install) |
| Capacitor `server.url` | `https://gemstone.dataright.net` (Voice console — no trailing slash) |
| API / WS | Same origin as the loaded SPA (see `frontend/src/services/apiOrigin.js`) |
**TLS:** Live host uses **Let's Encrypt** for `gemstone.dataright.net`. System CAs
trust that hostname — no custom Android trust needed. Debug-only
`network_security_config` + `ec2_debug.crt` remain only for raw-IP / self-signed
fallback (`https://18.116.188.14`). Details: [`DOC-Capacitor-Live-EC2.md`](DOC-Capacitor-Live-EC2.md).
### Mode B — Bundled native assets + configurable API base
**Intent:** Ship `dist/` inside the APK; WebView origin is typically `https://localhost`. REST/WS then use `VITE_API_BASE` or the live default origin (`https://gemstone.dataright.net`).
```powershell
cd frontend
npm run build
$env:CAPACITOR_USE_BUNDLED = "1"
npm run cap:sync:android
```
| Knob | Effect |
| --- | --- |
| `CAPACITOR_SERVER_URL` | Override live SPA URL before sync (no trailing slash required) |
| `CAPACITOR_USE_BUNDLED=1` | Remove `server.url`; load bundled `dist/` |
| `VITE_API_BASE` | Force REST/WS origin at **build** time (no trailing slash), e.g. `https://gemstone.dataright.net` |
Apply knobs via `frontend/scripts/apply-capacitor-server.cjs` (invoked by `npm run cap:sync` / `cap:sync:android`).
> **Note on Vite `base`:** Keep `base: "/app/"` for web/nginx while Mode A (`server.url`) points at live. A future fully-offline bundled path may need `base: "./"` — do not change that casually without a deliberate web + Capacitor change set (atomic concurrency).
---
## 4. Exact build / sync / install commands
All commands assume PowerShell on Windows 11 from the repo root unless noted.
### 4.1 Web build + Capacitor sync (Mode A — recommended)
```powershell
cd frontend
npm ci
npm run build
npm run cap:sync:android
# equivalent: node scripts/apply-capacitor-server.cjs; npx cap sync android
```
### 4.2 Open Android Studio
```powershell
cd frontend
npm run cap:open:android
```
Then **Run ▶ app** using the **debug** variant on an emulator or USB device. First paint loads `https://gemstone.dataright.net/app/` (network must reach that host on TCP 443).
### 4.3 Gradle `assembleDebug` without Studio UI
```powershell
cd frontend\android
.\gradlew.bat assembleDebug
```
**APK location:**
```text
frontend\android\app\build\outputs\apk\debug\app-debug.apk
```
### 4.4 Install with adb
```powershell
adb devices
adb install -r "frontend\android\app\build\outputs\apk\debug\app-debug.apk"
# or from frontend\android after assemble:
adb install -r "app\build\outputs\apk\debug\app-debug.apk"
```
Launch from the device launcher (GemStone) or:
```powershell
adb shell am start -n com.nextech.gemstone/.MainActivity
```
### 4.5 Logcat diagnostics
```powershell
# Process-filtered (adjust after launch)
adb logcat -c
adb logcat | Select-String -Pattern "Capacitor|chromium|GemStone|ExtendedAudio|WakeWord|AndroidRuntime"
```
Useful filters:
| Tag / pattern | Why |
| --- | --- |
| `chromium` / `Console` | WebView JS / network errors |
| `Capacitor` | Bridge / plugin load |
| `AndroidRuntime` | Native crashes |
| `ExtendedAudio` / `WakeWord` | FG service / mobility plugin |
---
## 5. Parallel web/API operation and atomic concurrency
### How Android runs in parallel
1. EC2 continues to serve nginx → web (`/app/`) + API (`/api`, `/healthz`, `/mcp`, sessions WS).
2. Desktop browsers hit the same public URL.
3. Debug Cap Android WebView also hits that URL (Mode A), so SPA and API share origin and CORS stays simple.
4. Native mobility plugins (`GemStoneMobility`, Extended FG mic, wake-word scaffold) run **on device** and call the same REST/WS contracts as web.
You do **not** need a second API stack on the laptop for Mode A. Mode B still needs a reachable API origin (`VITE_API_BASE` or live default).
### Atomic concurrency — Capacitor fail = feature fail
From [`frontend/CAPACITOR.md`](../../frontend/CAPACITOR.md) and GS-MOB-01:
- Web build, `npx cap sync android`, and (when applicable) `npx cap sync ios` ship in the **same change set**.
- If Capacitor sync or the native project is broken, the mobility **feature** is failed — do not claim Phase 2B/2C complete from web-only green builds.
- Docker frontend gate runs `vitest` + `npm run build` + `npx cap sync android`.
Auth0 is **explicitly excluded** from this invariant for install: Auth0 deferred must not block Capacitor install or live-stack parallel operation (see §8).
---
## 6. Signing: debug vs release (no invented credentials)
### Debug signing
- Android Studio / Gradle use the local **debug keystore** automatically (`~/.android/debug.keystore` or the Studio-managed equivalent).
- Fine for emulator, USB sideload, and internal engineering. **Not** for Play upload.
### Release signing / Play Console
- Release signing requires an **upload keystore** owned by NEXTECH, stored in a secrets vault (AWS Secrets Manager / secure store) — **never** committed to git.
- This repo’s `frontend/android/app/build.gradle` does **not** ship release `signingConfigs` with passwords. That is intentional.
- When Google Play Console access and keystore material exist, follow [`DOC-Store-Submission-Checklist.md`](DOC-Store-Submission-Checklist.md):
1. Generate / retrieve upload keystore offline.
2. Configure release signing via local `keystore.properties` (gitignored) or CI secrets — do not paste passwords into docs or chat logs.
3. Build AAB: `.\gradlew.bat bundleRelease`.
4. Upload to an **internal testing** track first.
**Keystore safety**
- Treat `.jks` / `.keystore` and passwords as production secrets.
- Rotate only with a documented Play App Signing recovery plan.
- Never invent or check in placeholder keystore passwords “for completeness.”
---
## 7. Permissions and mobility behavior
Declared in `frontend/android/app/src/main/AndroidManifest.xml`:
- `INTERNET`
- `RECORD_AUDIO`
- `MODIFY_AUDIO_SETTINGS`
- `FOREGROUND_SERVICE` / `FOREGROUND_SERVICE_MICROPHONE`
- `POST_NOTIFICATIONS`
Runtime mic: `GemStoneMobility.checkMicrophonePermission()` then `ensureMicrophonePermission()` before WebView `getUserMedia` / Gemini Live / Field Mode. Cap warms the prompt once after the first touch so Conversation is ready. **Android persists** the grant across app restarts until the user revokes it in **Settings → Apps → GemStone → Permissions → Microphone**. On deny, toast + `openAppSettings()` deep-link.
| Permission / component | Behavior |
| --- | --- |
| `INTERNET` | SPA + API + WS |
| `RECORD_AUDIO` | Field Mode (`getUserMedia` / `MediaRecorder`) and Extended Session mic; OS-persisted after first Allow |
| `FOREGROUND_SERVICE` + `FOREGROUND_SERVICE_MICROPHONE` | Extended Session + wake-word FG services |
| `POST_NOTIFICATIONS` | Persistent FG notification (Android 13+) — user must allow |
| `ExtendedAudioService` | Extended Session background audio bridge (`FOREGROUND_SERVICE_TYPE_MICROPHONE`) |
| `WakeWordService` | Wake-word **scaffold** (notification + service); on-device model + 8/10 killed-state trials are device QA |
**OS limitation:** GemStone cannot force “always on” mic if the user (or OEM battery policy) revokes `RECORD_AUDIO`. After revoke, the next Conversation / Live / Field start shows the system prompt again (or permanently denied → Settings).
### Modes (summary — see GS-MOB-01)
| Mode | Route | Audio path |
| --- | --- | --- |
| Field Mode | `/app/field` | WebView mic + ascending dual-tone |
| Extended Session | `/app/extended` | Native plugin → FG mic service + cues |
| Domain Packs | `/app/packs` | REST install/uninstall |
| Didymus queue | `/app/didymus` | Approval queue UI |
### Interruption resume (identical for all three causes)
Causes: `audio_focus_loss` | `network_drop` | `app_background`
```text
ACTIVE → PAUSED (snapshot) → RESUMABLE (session-ready chime) → ACTIVE
```
REST surface: `/api/sessions` (create, list/recents, get, pause, resumable, resume, end). Full contract: GS-MOB-01 §6.
Device sign-off scripts: [`DOC-Device-UAT-Checklist.md`](DOC-Device-UAT-Checklist.md).
---
## 8. Auth0 deferred — guest / stub behavior (must not block install)
**Status:** Auth0 live tenant is **deferred** and punchlisted. See [`DOC-Auth0-Provisioning.md`](DOC-Auth0-Provisioning.md).
| Fact | Implication for install |
| --- | --- |
| `/healthz` may report `auth0.configured: false` | **Not** an install failure |
| `/app/login` is an Auth0-ready **stub** | Shows “tenant not provisioned” until `VITE_AUTH0_*` exist |
| HorizonORBIT login markup lives in HorizonCRM (not cloned) | Layout stub only |
| Field / Extended / Packs / Didymus UI | Usable for engineering and device UAT without Universal Login |
**Current practitioner behavior:** use the app as an unauthenticated / guest-style engineering client against the live stack. Do **not** wait for Auth0 to run `npm ci`, sync, assemble, or Field Mode mic checks. When secrets land in `DATARIGHT_DEV_SECRETS`, follow the Auth0 provisioning doc — that work is separate from this playbook’s install path.
---
## 9. Troubleshooting
| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Blank WebView / missing assets | Wrong Vite `base` vs load URL; stale sync; bundled mode without rebuild | Mode A: confirm `server.url` → `…/app`. Mode B: `npm run build` then `CAPACITOR_USE_BUNDLED=1` + sync. Hard-reload / reinstall APK. |
| API calls hit `localhost` / fail on device | Bundled shell using `https://localhost` without `VITE_API_BASE` / live default; or old client | Confirm Mode A live URL, or rebuild with `VITE_API_BASE=https://gemstone.dataright.net`. See `apiOrigin.js`. |
| TLS / `SSLHandshakeException` / net::ERR_CERT | Hitting raw EIP with self-signed leaf | Prefer `https://gemstone.dataright.net` (LE / system CAs). Raw IP still needs debug `ec2_debug.crt`. |
| CORS / mixed content | `http` API from `https` WebView; `allowMixedContent: false` | Keep SPA + API on `https://gemstone.dataright.net`. Do not point Cap at `http://` API. |
| JDK mismatch / Gradle toolchain errors | `JAVA_HOME` is JDK 8/11 or unset | Point `JAVA_HOME` at Studio JBR or JDK 17+; restart Studio/shell. |
| SDK / build-tools missing | Platform 34 or build-tools not installed | Android Studio SDK Manager → install API 34 + build-tools + platform-tools. |
| `adb devices` empty / `unauthorized` | USB debug off, bad cable, no RSA accept | Re-enable USB debugging; accept prompt; try another cable/port; `adb kill-server; adb start-server`. |
| Microphone denied | Runtime permission not granted | App settings → Permissions → Microphone. Android 13+: also allow Notifications for FG service. |
| Stale Capacitor sync | Native project out of date vs `dist` / plugins | `npm run build` → `npm run cap:sync:android` → clean rebuild (`.\gradlew.bat clean assembleDebug`). |
| Live UI loads but voice/session APIs 502 | EC2 compose unhealthy | Check `https://gemstone.dataright.net/healthz` from PC; fix host stack (DOC-Deploy-Pipeline) — not a Cap config issue. |
| Wake-word never fires from killed state | Scaffold only / model not onboarded | Expected until device QA completes GS-MOB-01 wake gates; do not treat as install failure. |
---
## 10. Verification checklist
Mark each row after a successful run on your workstation + device.
| # | Check | Command / action | Pass? |
| --- | --- | --- | --- |
| 0 | Hosted APK | Open `/app/install-android` → Download → install APK; or `curl -I https://gemstone.dataright.net/downloads/gemstone-debug.apk` | ☐ |
| 1 | Web build | `cd frontend; npm ci; npm run build` | ☐ |
| 2 | Cap sync Android | `npm run cap:sync:android` | ☐ |
| 3 | Assemble debug | `cd android; .\gradlew.bat assembleDebug` | ☐ |
| 4 | Install | `adb install -r app\build\outputs\apk\debug\app-debug.apk` | ☐ |
| 5 | Launch | Open GemStone; SPA paints (Mode A: live `/app/`) | ☐ |
| 6 | Health | Device or PC: `https://gemstone.dataright.net/healthz` reachable; Auth0 may be `configured:false` | ☐ |
| 7 | Voice capture (Field) | `/app/field` → grant mic → tap → dual-tone ≤ 1s | ☐ |
| 8 | Reconnect | Toggle airplane mode briefly during session → pause → resumable → resume | ☐ |
| 9 | Field Mode | Heads-Up UI usable indoors; outdoor sun → Device UAT Script A | ☐ |
| 10 | Extended Session | Start extended; hear mic-open cue; FG notification present | ☐ |
| 11 | Log collection | `adb logcat` capture during a failing step; archive for engineering | ☐ |
Formal outdoor / call / wake sign-off remains on [`DOC-Device-UAT-Checklist.md`](DOC-Device-UAT-Checklist.md).
---
## 11. Quick-reference command card
```powershell
# Fastest: hosted debug APK (no local build)
# https://gemstone.dataright.net/app/install-android
# https://gemstone.dataright.net/downloads/gemstone-debug.apk
# Prereq smoke (local build path)
node -v; npm -v; java -version; adb version; adb devices
# Install path (Mode A — live EC2)
cd <repo>\frontend
npm ci
npm run build
npm run cap:sync:android
npm run cap:open:android
# — or —
cd android
$env:JAVA_HOME = "C:\Program Files\Android\Android Studio\jbr"
.\gradlew.bat assembleDebug
adb install -r app\build\outputs\apk\debug\app-debug.apk
# Bundled assets mode
cd <repo>\frontend
npm run build
$env:CAPACITOR_USE_BUNDLED = "1"
npm run cap:sync:android
# Optional overrides
$env:CAPACITOR_SERVER_URL = "https://gemstone.dataright.net/app"
$env:VITE_API_BASE = "https://gemstone.dataright.net" # must rebuild after setting
```
---
## 12. Post-wiring revision notes
As of **2026-07-21**, live-stack Android wiring is recorded complete (`DOC-Capacitor-Live-EC2.md`, punchlist row **Capacitor Android ↔ live EC2**). Revise **this playbook** if any of the following change:
| Change | Sections to update |
| --- | --- |
| EC2 public IP or hostname | Mode A URLs, troubleshooting, verification, command card |
| TLS leaf rotation | Debug cert path note; PEM rebuild reminder |
| Vite `base` / bundled-only product path | Modes A/B; blank WebView troubleshooting |
| Auth0 goes live | §8 guest behavior → real Universal Login + callback URLs for Cap |
| Release signing checked into CI (via secrets) | §6 — still never put passwords in this doc |
| `appId` / versionCode bumps for store | Header metadata + store checklist cross-link |
---
NEXTECH Business Technology Management LLC · nex-tech.biz · (941) 499-5505