Document update release policy

README.md

@@ -16,14 +16,17 @@ APIs directly:
   and kill session through HTTP API
 - open one live terminal viewer through `/ws/terminal`
 - native `/ws/events` listener for session invalidation and hook notifications
-- GitHub and Gitea update manifest mirrors with fallback
+- selectable GitHub or Gitea update manifest source
 - native API action center for health, server status, timeline, preferences,
   kanban projects, group messages, hook events, image file/URL upload, image
   preview info, and native image preview display
 - mobile soft-key row for tmux-oriented input, including tmux prefix, detach,
   new window, previous/next window, Ctrl keys, arrows, page keys, and paste
-- automatic update checks against a GitHub Release manifest
+- automatic update checks against the selected release manifest
-- APK download, SHA-256 verification, and installer handoff
+- one-download-per-version APK cache, SHA-256 verification, and installer
+  handoff
+- native Update and About pages for version, protocol, permission, and release
+  information
 
 ## Server URL
 
@@ -75,7 +78,12 @@ Create the base64 value from your release keystore:
 base64 -w 0 tmux-android-release.jks
 ```
 
-Publish a test build by pushing a `v*` tag. That creates a GitHub Release with:
+Branch builds create Actions artifacts only. Use them to verify grouped changes
+before publishing.
+
+Publish a release build by pushing a `v*` tag. A tag should be reserved for a
+coherent feature/test batch, not every small UI or text change. Tag publishing
+creates a GitHub Release with:
 
 ```text
 https://github.com/neatstudio/tmux-browser-android/releases/latest/download/tmux-android.apk
@@ -143,8 +151,11 @@ The public manual APK download is:
 https://github.com/neatstudio/tmux-browser-android/releases/latest/download/tmux-android.apk
 ```
 
-The app tries the selected update source first, then falls back to the GitHub
+The app checks only the selected update source. It does not probe GitHub and
-manifest and the Gitea release API. The Gitea API endpoint is:
+Gitea during the same update check. Choose the source in the app's `Update`
+page, or use a custom manifest/API URL.
+
+The built-in Gitea API endpoint is:
 
 ```text
 https://gitea.neatcn.com/api/v1/repos/tmux/tmux-browser-android/releases/latest
@@ -159,10 +170,14 @@ https://gitea.neatcn.com/tmux/tmux-browser-android/releases/download/v0.1.7/tmux
 
 In the app:
 
-- Tap `Update` on the main screen to check `latest.json`, download the APK,
+- Open the `Update` page to check `latest.json`, download the APK, verify
-  verify SHA-256, and open Android's installer.
+  SHA-256, and open Android's installer.
+- If the same version APK was already downloaded and its SHA-256 still matches,
+  the app reuses that file instead of downloading it again.
 - Open `More` -> `Open APK download` to download the current public APK in a
   browser.
-- Open `More` -> `Permissions / update status` to see the installed version,
+- Open the `Update` page or `More` -> `Permissions / update status` to see the
-  update manifest, APK URL, install permission state, and a `Check update`
+  installed version, selected update source, APK URL, install permission state,
-  button.
+  and a `Check update` button.
+- Open the `About` page to see the app version, package name, API/protocol
+  summary, and update policy.

docs/android-client-notes.md

@@ -70,6 +70,7 @@ Implemented now:
 
 - configurable base URL, defaulting to `http://100.89.0.116:3000`
 - support for Tailscale URLs such as `http://100.x.y.z:3000`
+- native multi-page shell with `Sessions`, `Tools`, `Update`, and `About`
 - native session list from `GET /api/sessions`
 - create, rename, command send, split, pane select, pane kill, pin, mute, and
   kill session through documented session/preference endpoints
@@ -83,7 +84,34 @@ Implemented now:
   metadata, and native image preview display
 - GitHub Actions APK build
 - release manifest `latest.json`
-- APK download, SHA-256 verification, and installer handoff
+- selected-source update checks; GitHub and Gitea are not probed in the same
+  update check
+- one-download-per-version APK cache, SHA-256 verification, and installer
+  handoff
+- permission/about surfaces for unknown-app install status, notification status,
+  app version, package name, and API/protocol summary
+
+## Update And Release Policy
+
+The Android app cannot silently replace itself. It may download a newer APK and
+open Android's package installer, but the user must approve the install. On
+Android 8+, the user may also need to allow this app to install unknown apps.
+
+The app checks exactly one update source per run: the selected manifest/API URL.
+GitHub is the default public source. Gitea is available as a public mirror, but
+the app does not fall back across both providers during a normal check. This
+keeps update behavior predictable on mobile networks and avoids duplicate
+provider checks.
+
+Downloaded APKs are cached by `versionCode`. If a cached APK exists and its
+SHA-256 matches the manifest, the app reuses it instead of downloading the same
+version again. This matters when Android redirects the user to unknown-app
+install settings before the installer can run.
+
+Only `v*` tags publish GitHub Releases. Main branch builds are for CI artifacts
+and should be used to validate grouped changes. Do not publish a new tag for
+every small UI copy or layout change; publish when there is a useful feature or
+test batch for phone-side validation.
 
 ## Native Roadmap