# Direct Android Application

The direct Android application is for users who install the ZoneGaze Matrix APK and run the mobile shell. Users do not need to clone this repository or run npm commands. The default runtime uses the owned Zone Terminal backend through the reusable `:zone-terminal` Android library; the Matrix APK has no external terminal package dependency or external command permission. The native app guides the user through runtime setup, project folder selection, Git setup, SSH key generation, and launching Matrix runtime-backed surfaces. `MatrixAndroidTerminalRequirements` tracks the owned terminal path for Flow, Git, Cline SDK, Chat, Code, Research, Whispr, Joplin, Open Design, Exo, and Ollama.

Related docs:

- [Platform application guides](README.md)
- [Software manual](../manual/software-manual.md)
- [Core feature guide](../features/zonegaze-flow-core-features.md)
- [Feature coverage matrix](../features/feature-coverage-matrix.md)

## What The Android App Includes

The Android app has package id `com.zonegaze.matrix`, Android launcher label `Matrix`, minimum SDK 26, and target SDK 37. The Kotlin source namespace remains `com.zonegazeflow.app` for build compatibility, but the install package is Matrix-specific so older ZoneGaze Flow APKs can coexist without replacing it.

It provides:

- native setup/status dashboard;
- native plugin install/uninstall records for Android Matrix plugins, including source, APK version, readiness, and adapter metadata;
- terminal requirement summaries for plugins that need the owned Android terminal backend, open without terminal, need an endpoint, or are planned;
- native Android Chat and Whispr plugin surfaces for owned local-first workflows;
- APK install path with no repository checkout;
- ZoneGaze Matrix runtime detection on ports `3484` through `3489`;
- ZoneGaze Code detection on ports `3500` through `3505`;
- Matrix plugin runtime detection for Open Design (`5175`), Exo (`52415`), and ZoneGaze Research (`53320`) with clear Android availability diagnostics;
- Vite development and preview detection on ports `4217` and `4173`;
- embedded asset server for the bundled Android runtime package on ports `3490` through `3495`;
- automatic Zone Terminal setup with native progress, runtime install, runtime start/stop, and runtime logs;
- in-app WebView for ZoneGaze Matrix runtime-backed surfaces and ZoneGaze Code;
- Matrix WebView bridge for shared port snapshots, plugin runtime status, clipboard copy, section route opening, and custom `zonegaze-matrix:` / `zonegaze-flow:` deep links;
- Device Link Devices surface with Android identity, short-lived pairing sessions, NSD same-network peer discovery, route status, relay configuration, and bridge methods matching the Mac Matrix contract;
- Android Whispr dictation through Google Speech (`SpeechRecognizer`) with native transcript/status events;
- installed-plugin navigation syncing between the native Android drawer and the Matrix WebView shell;
- native Zone Terminal activity for process-backed app-owned command sessions with bounded output and stop support;
- project folder storage, Git identity setup, SSH key generation, public key copy, and Android storage setup.

Source of truth:

- [Android README](../../platforms/android/README.md)
- [Android Gradle config](../../platforms/android/app/build.gradle.kts)
- [Android manifest](../../platforms/android/app/src/main/AndroidManifest.xml)
- [Android main activity](../../platforms/android/app/src/main/java/com/zonegazeflow/app/MainActivity.kt)
- [Server controller](../../platforms/android/app/src/main/java/com/zonegazeflow/app/ServerController.kt)
- [Server models](../../platforms/android/app/src/main/java/com/zonegazeflow/app/ServerModels.kt)
- [Matrix Android bridge](../../platforms/android/app/src/main/java/com/zonegazeflow/app/MatrixAndroidBridge.kt)
- [Matrix Android deep links](../../platforms/android/app/src/main/java/com/zonegazeflow/app/MatrixAndroidDeepLinks.kt)
- [Android Google Speech service](../../platforms/android/app/src/main/java/com/zonegazeflow/app/MatrixGoogleSpeechService.kt)
- [Zone Terminal Android library](../../platforms/android/zone-terminal/build.gradle.kts)
- [Zone Terminal module bridge](../../platforms/android/app/src/main/java/com/zonegazeflow/app/ZoneTerminalModuleBridge.kt)
- [Matrix Android plugin catalog](../../platforms/android/app/src/main/java/com/zonegazeflow/app/MatrixAndroidPluginCatalog.kt)
- [Matrix Android plugin install store](../../platforms/android/app/src/main/java/com/zonegazeflow/app/MatrixAndroidPluginInstallStore.kt)
- [Device Link section](../../platforms/android/app/src/main/java/com/zonegazeflow/app/DeviceLinkSection.kt)
- [Device Link store](../../platforms/android/app/src/main/java/com/zonegazeflow/app/DeviceLinkStore.kt)
- [Device Link local discovery](../../platforms/android/app/src/main/java/com/zonegazeflow/app/DeviceLinkLocalDiscovery.kt)
- [WebActivity](../../platforms/android/app/src/main/java/com/zonegazeflow/app/WebActivity.kt)
- [Embedded web server](../../platforms/android/app/src/main/java/com/zonegazeflow/app/EmbeddedWebServer.kt)

## Download And Install

1. Download the latest ZoneGaze Matrix APK from the trusted project Android distribution channel.
2. The app source currently defines this APK endpoint: [latest Android APK](https://zonegaze.com/ZoneGaze-debug.apk).
3. Open the APK on the Android device.
4. Allow installation from the chosen browser or file manager if Android asks.
5. Open `ZoneGaze Matrix`.

Do not install random APK mirrors. Use the project distribution channel or the endpoint above when it is the active release channel.

## First Run

1. Open the app.
2. Keep the app open while the bundled Zone Terminal runtime is prepared automatically.
3. Watch setup progress on **Dashboard** or **Runtime**.
4. Choose and save a launch folder.
5. Configure Git name, email, host, and SSH key if you plan to commit or push.
6. Tap **Start**, then **Open**.

Screenshot: [open Android emulator dashboard](../assets/screenshots/android-emulator-dashboard.png)

![Android emulator showing the ZoneGaze Matrix native dashboard, app ports, and Zone Terminal runtime setup state](../assets/screenshots/android-emulator-dashboard.png)

Current emulator install/launch screenshot: [open current Android install/launch screenshot](../assets/screenshots/android-install-launch-current.png)

![Current Android emulator showing the installed ZoneGaze Matrix APK dashboard and Zone Terminal start state](../assets/screenshots/android-install-launch-current.png)

Current emulator install/launch video: [open current Android install/launch recording](../assets/videos/zonegaze-flow-android-install-launch-current.mp4)

![Current ZoneGaze Matrix Android emulator install and launch recording](../assets/videos/zonegaze-flow-android-install-launch-current.mp4)

## Fresh Emulator Capture Set

Fresh Android evidence was recaptured on `2026-07-09` from `emulator-5554` using the current debug
APK. This set complements the earlier install/launch media with current shell-state screenshots.

- [Dashboard after launch](../assets/screenshots/android-emulator-dashboard.png)
- [First launch dashboard state](../assets/screenshots/android-install-launch-current.png)
- [Plugin catalog](../assets/screenshots/android-plugin-catalog-current.png)
- [Runtime tab](../assets/screenshots/android-runtime-status-current.png)
- [Ports tab](../assets/screenshots/android-ports-status-current.png)
- [Embedded WebView first open](../assets/screenshots/android-webview-first-open-current.png)
- [Live shell navigation video](../assets/videos/zonegaze-flow-android-live-shell-navigation-current.mp4)

## Plugin Install And Launch

The Android Matrix shell owns plugin install state in native app storage. The **Plugins** tab lists every supported Matrix plugin and shows **Install** when a plugin is absent and **Uninstall** when it is installed. Installed records include plugin id, install time, Android APK version, install mode, launch mode, readiness, source label, setup detail, and declared host adapter. Older installs that only wrote the legacy `installed_plugins` id list are migrated into full records on first read.

The burger drawer always shows installed plugins only. Plugin order is controlled from the drawer drag handles; Dashboard, Ports, Devices, Plugin, and Settings remain shell surfaces.

Plugin launch is isolated by adapter:

- Chat and Whispr open native Android plugin screens.
- Flow starts only the Flow runtime payload when Flow is opened.
- Code starts only the ZoneGaze Code/code-server runtime when Code is opened.
- Joplin, Open Design, Exo, and Research open through their declared Matrix web/runtime adapter instead of starting unrelated services.
- Research has a typed Android runtime action and owned Zone Terminal adapter. The current runtime still serves live Research through the shared Flow CLI process, but UI and bridge callers no longer start it through the generic Matrix action.
- Exo installs as an endpoint adapter until an Android-supported local model runtime is available.

Installing a plugin does not start Flow, Code, Joplin, Open Design, Exo, Research, Zone Terminal, or any other runtime. Install only records the Android-native availability of that plugin surface. Runtime setup runs automatically when the owned terminal prerequisites are ready, and runtime start remains tied to the selected plugin.

Plugin summaries also include the Android terminal requirement. Flow, Git, Cline SDK, Code, and Research are marked as needing the owned Android terminal backend. Chat, Whispr, Joplin, and Open Design are marked as opening without a terminal for their current Android surfaces. Exo is marked as needing an endpoint, and Ollama remains planned until an owned Android runtime package is implemented.

When a Flow-hosted web plugin opens, Android syncs the native installed-plugin list into the WebView Matrix shell so the web surface sees the same install state as the native drawer.

## Navigation Tabs

The app has a bottom navigation bar with four tabs:

- **Dashboard** — the Matrix dashboard with recent work, plugin summaries, and quick actions.
- **Plugins** — installed Matrix plugin surfaces.
- **Runtime** — permissions, setup, and the replaceable Android terminal backend state.
- **Ports** — the Mac-style local port monitor for ZoneGaze-managed services, plugin runtimes, and optional external listeners.

The Matrix burger drawer carries Dashboard, installed plugin entries, Ports, Devices, Plugin, and Settings. The drawer owns plugin ordering; the bottom navigation stays compact for mobile.

## Dashboard States And Actions

The dashboard renders Matrix activity and runtime summaries, while the Ports tab owns the full port table. Android reads local listeners from `/proc/net/tcp*`, shows ZoneGaze-managed ports by default, and lets users opt into read-only external local listeners. It keeps useful dashboard state across rotation or process recreation.

Server statuses are:

- `STOPPED`
- `STARTING`
- `STOPPING`
- `RUNNING`
- `EXTERNAL`
- `BLOCKED`
- `FAILED`

Runtime actions include refresh, automatic owned backend setup progress, retry/repair after failed setup, runtime diagnostics, storage setup, save project path, save Git account, generate SSH key, copy public key, start, stop, open, and copy URL.

## Matrix Host Bridge

Android shares the same Matrix web contract used by the Mac app through `@zonegaze/flow-contracts/matrix-platform-bridge`. The WebView exposes one native object, `window.ZoneGazeAndroid`, with an async request/event protocol rather than product-specific globals.

The bridge currently covers clipboard copy, Matrix port snapshots, Flow/Code start and stop, Code open, Open Design/Exo/Research status diagnostics, Matrix section route opening, deep-link relay, Device Link identity/pairing/relay state, and Whispr dictation start/stop/events.

The current backend is intentionally hidden behind `AndroidTerminalBackend`. Flow/plugin web code depends on Matrix platform contracts, not backend-specific APIs.

## Device Link

Android Device Link matches the Mac Matrix bridge contract through `deviceLink.*` methods. The native app creates a local Android identity, starts short-lived pairing sessions for Mac pairing, stores paired-device records locally, stores relay settings locally, and reports route probes through the shared `DeviceLinkSnapshot`.

Same-network discovery uses Android NSD with service type `_zonegaze-device-link._tcp.`. The app starts a bounded discovery scan when pairing starts or when the user tests routes, resolves matching peers, exposes them as `localPeers`, and reflects the first resolved peer in the direct LAN route. Android also handles `zonegaze-matrix://device-link/pair` invite links natively: it records the invited device key, opens the Devices surface, and exposes capability/revoke changes through both native UI and the Matrix WebView bridge. Direct internet remains blocked until the native Iroh Android endpoint is packaged and physically verified. Remote access remains user-owned relay only; there is no ZoneGaze-hosted relay or device directory.

## Whispr Google Speech

Android Whispr uses Google Speech through the native `SpeechRecognizer` API. The app declares microphone and foreground microphone permissions, queries Android speech recognition services, and emits Matrix Whispr transcript events with provider id `google-speech`.

When Google recognition is unavailable, Android reports Whispr as not installed/available through the native bridge. It does not fall back to another shell runtime, Apple Speech, or a cloud API provider.

## Terminal Runtime

The default Android terminal backend is the owned Zone Terminal adapter behind `AndroidTerminalBackend`. Automatic setup extracts the bundled Matrix runtime package into app-owned storage, and runtime start can use the packaged native Node bridge when the device ABI is supported.

The native Node bridge vendors `nodejs-mobile` `v18.20.4` `libnode.so` for `arm64-v8a` and `x86_64`, with a small JNI bridge that starts the Flow CLI on a background thread. The debug APK is intentionally larger because it includes both phone and emulator ABIs. The first native bridge supports starting the Matrix runtime and the typed Research runtime adapter. Owned Git account configuration and SSH key generation run through packaged `git` and `ssh-keygen` binaries when the runtime package includes them. ZoneGaze Code has a separate owned package feature state and launcher for packaged `bin/code-server`.

The owned backend also exposes a native Zone Terminal activity. It starts process-backed app-owned command sessions in the selected workspace, can open a persistent shell session, sends input to the latest running session, keeps bounded output, shows running/exit state, and can stop the latest running session. This is the first native session lifecycle for the future Android terminal; true PTY emulation remains separate follow-up work.

Native Node stop/restart, full PTY emulation, physical Code QA, and bundling a real Android-compatible `code-server` binary remain separate follow-up work.

The owned Zone Terminal setup:

- downloads the bundled runtime archive from the app's embedded server;
- extracts it under app-owned `files/zone-terminal/runtime`;
- prepares `runtime`, `data`, `home`, `logs`, `workspace`, package-state, and package-cache directories through the reusable `:zone-terminal` bootstrap planner;
- verifies the Matrix CLI entry point before enabling runtime start;
- starts the Matrix runtime through packaged executable Node when present, or through the isolated native Node service and JNI bridge for supported ABIs.

The app blocks start when the runtime bundle is missing, setup has not installed the runtime, the Matrix CLI entry point is missing, or no compatible Node launch path is available.

## ZoneGaze Code

The Android app can start ZoneGaze Code from the owned Zone Terminal package when packaged `bin/code-server` is available. The native app detects or starts ports `3500` through `3505`, creates an IDE password, signs the WebView into code-server, applies ZoneGaze Code branding where code-server exposes product metadata, disables telemetry and update checks, and opens the project folder in the in-app WebView.

ZoneGaze Code is the ZoneGaze-owned Code-OSS-based IDE plugin. It must not use Microsoft Visual Studio Code names, logos, extension-store assumptions, or affiliation claims in ZoneGaze-owned UI.

IDE start is blocked until the owned Zone Terminal package is installed, includes executable `bin/code-server`, and automatic setup is not running.

## WebView Behavior

The WebView enables JavaScript, DOM storage, content access, file access, cookies, and a ZoneGaze Matrix Android user-agent suffix. Local URLs such as `127.0.0.1`, `localhost`, and `::1` stay in the app. External HTTP(S) links open in the operating system browser.

The WebView top bar provides Back navigation and keeps the native shell wordmark as ZoneGaze Matrix. Code-server login cookies are applied before opening the IDE URL when an IDE password is available. Custom `zonegaze-matrix:` and `zonegaze-flow:` URLs are translated into local Matrix/Flow routes and stay inside the app.

## Storage And Projects

The default Android workspace is:

```text
~/zonegaze-flow/workspace
```

To use shared Android storage such as `/sdcard`, choose the folder with Android's native folder picker and save it as the launch folder. The owned Zone Terminal path uses the persisted Android folder grant instead of requiring a pasted storage command.

After storage permission is granted, save the desired project folder in the dashboard and start the runtime.

## Git Setup

The Android dashboard can save Git identity and generate an SSH key through the selected Android terminal backend.

- In the owned Zone Terminal backend, name and email are written to the app-owned runtime home with packaged `git`.
- Host can be used to rewrite HTTPS remotes to SSH.
- SSH keys are generated under the selected backend's home directory.
- ZoneGaze Matrix does not store Git passwords or tokens.
- Add the generated public key to the Git provider before pushing.

## Input Process Output Result Evidence

Android dashboard recording: [open Android dashboard setup recording](../assets/videos/zonegaze-flow-android-dashboard-setup.mp4)

![ZoneGaze Matrix Android dashboard setup video](../assets/videos/zonegaze-flow-android-dashboard-setup.mp4)

Current Android install/launch recording: [open current Android install/launch recording](../assets/videos/zonegaze-flow-android-install-launch-current.mp4)

![Current ZoneGaze Matrix Android install and launch video](../assets/videos/zonegaze-flow-android-install-launch-current.mp4)

The current recording shows the Matrix APK installed as `com.zonegaze.matrix` on the dedicated Matrix emulator, the native dashboard launch, and navigation across the dashboard tabs. It is app/emulator-only and is not a screenshot slideshow. It verifies install and launch, not the full owned-runtime workflow.

Current Android install/launch screenshot: [open current Android install/launch screenshot](../assets/screenshots/android-install-launch-current.png)

![Current Android installed app dashboard screenshot](../assets/screenshots/android-install-launch-current.png)

Current live shell navigation video: [open current Android shell navigation recording](../assets/videos/zonegaze-flow-android-live-shell-navigation-current.mp4)

![Current ZoneGaze Matrix Android shell navigation video](../assets/videos/zonegaze-flow-android-live-shell-navigation-current.mp4)

Additional shell-state screenshots from the same live run:

- [Dashboard after launch](../assets/screenshots/android-emulator-dashboard.png)
- [Plugin catalog](../assets/screenshots/android-plugin-catalog-current.png)
- [Runtime tab](../assets/screenshots/android-runtime-status-current.png)
- [Ports tab](../assets/screenshots/android-ports-status-current.png)
- [Embedded WebView first open](../assets/screenshots/android-webview-first-open-current.png)

Shared runtime result evidence after the ZoneGaze Matrix runtime is running:

- [Core working demo video](../assets/videos/zonegaze-flow-core-working-demo.webm)
- [Produced website result](../assets/screenshots/core-produced-website-result-page.png)

## Recording Status

Full owned-runtime Android workflow video is not complete in this environment. Current evidence confirms that the Android SDK emulator is available, the dedicated Matrix AVD boots, and the `com.zonegaze.matrix` APK installs and launches successfully. The captured dashboard state shows Zone Terminal ready to start, but this recording does not prove runtime start, board WebView loading, or IDE WebView loading.

Because the full workflow needs runtime start and WebView result evidence, no placeholder full-workflow recording was created.

Required future Android full workflow capture:

1. APK dashboard input.
2. Automatic Zone Terminal setup progress.
3. Runtime start output.
4. ZoneGaze Matrix WebView result.
5. ZoneGaze Code output.
6. Final app-only/emulator-only result view.

## Update

1. Install the newer ZoneGaze Matrix APK over the existing app.
2. Open the app.
3. Keep the app open while automatic setup refreshes the bundled Zone Terminal runtime if the APK includes a newer runtime bundle.
4. Tap **Start**.

The Android app version is controlled by `versionCode` and `versionName` in the Gradle config. The bundled runtime archive remains version-gated by the Android runtime packaging code.

## Troubleshooting

- **Runtime is not installed**: keep the app open and watch **Dashboard** or **Runtime** setup progress.
- **Runtime package is missing `dist/cli.js`**: rebuild the bundled runtime archive and use **Retry runtime setup** or **Repair runtime setup**.
- **Android Node launch path is missing**: install an APK build that includes the owned native Node bridge for the device ABI, or a runtime package with executable `bin/node`.
- **Setup failed**: use **Retry runtime setup** and inspect the Runtime diagnostic shown by the app.
- **Start remains disabled**: wait for automatic setup to finish and confirm the Runtime card shows the Matrix runtime as ready.
- **IDE does not open**: wait for automatic setup to finish, ensure the runtime package contains executable `bin/code-server`, then start ZoneGaze Code again.
