Skip to content

armgit / andee

Public Imported from GitHub
0

Andee lives on your phone or Mac and uses any app like you do—no integrations, no root, any model; memory and passwords never leave your device | Andee 住进你的手机或 Mac,像你一样操作任何 App——无需集成、无需 Root、支持任意模型,记忆和密码绝不离开设备。

chore(release): v0.5.1

booboosuiefd06758df23
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6c2ed6f..d78e54f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,7 @@ Notable changes to Andee. The format follows [Keep a Changelog](https://keepacha
## Versioning policy
-- `versionCode` / `versionName` live in `app/build.gradle` and are currently **`9` / `"0.5.0"`**.
+- `versionCode` / `versionName` live in `app/build.gradle` and are currently **`10` / `"0.5.1"`**.
- Releases are tagged `vMAJOR.MINOR.PATCH`, `versionName` mirrors the tag without the leading `v`,
and `versionCode` increases by one per release. `versionCode` must increase **monotonically** or
Android refuses the upgrade; the same number must never be reused for two different builds.
@@ -28,6 +28,49 @@ hash into `versionName` at build time would close this hole; it is not implement
## [Unreleased]
+## [0.5.1] - 2026-10-19
+
+**Two ways the assistant could quietly lose the ability to keep working, both fixed.** One, its
+nightly review died with the process and never came back; the other, Xiaomi's power policy was
+reaping it in the background with no way for the user to see why. The version number is
+**a deliberate departure from the policy below**: both commits are `feat`, and the policy would have
+made this `0.6.0`, but neither adds a capability — they restore two things that were already supposed
+to happen, and a user who upgrades is not getting a new feature so much as getting the existing ones
+to survive a night. Nothing in the wire contract or an existing configuration breaks.
+
+### Fixed
+
+- **The quiet-hour review survives the process being killed, and is re-armed after a reboot.** The
+ sweep is an `AlarmManager` alarm, so it outlives the process — but when it landed there was often
+ no service left to run it, and a reboot did not re-arm it at all. Worse, the review reads the
+ conversation from memory, which dies with the process, so even a recovered sweep found **"0 messages
+ to review"** and did nothing. Two halves: `Notebook.last_sweep_at`, written only by the sweep itself,
+ is the one fact that separates *"already reviewed"* from *"died before it could"*; and
+ `rebuildHistoryFromScrollback` rebuilds the dialogue from the persisted scrollback — user and
+ assistant rows, each re-stamped with its own clock — when the in-memory history is empty. On start
+ the service catches up: it waits out a quiet window that has not finished, skips a stretch that was
+ already swept, and otherwise runs the review it missed. Measured on a device: a sweep after a restart
+ listed the four prior turns and completed.
+- **A Xiaomi-family device now has a self-check row for auto-start, which is what actually keeps it
+ alive there.** MIUI reaps background processes on a timer (measured at one kill every 40–60 minutes
+ on the maintainer's tablet), and without the auto-start grant `START_STICKY` cannot bring the process
+ back — the symptom a user reports is *"it closes by itself after a while"*, with nothing anywhere
+ saying why. The new row reads the vendor AppOps op (`OP_AUTO_START = 10008`, by reflection, since it
+ has a number but no name this app can spell) and offers a one-tap door to MIUI's auto-start manager,
+ probing the known components in order because MIUI has renamed that activity across versions. It is
+ **`WARN`, not `FAIL`**: with auto-start off the app is fully alive right now — it is the *future*
+ that degrades, which is exactly what `WARN` is for. The row **only exists on Xiaomi, Redmi and POCO**
+ (matched on brand words, since the MIUI build property would need a hidden API and the words are
+ free), because on every other ROM it would be a switch that does nothing. `Fix.Screen` gained an
+ optional `component` for the vendor screen that has no action to name.
+
+### Changed
+
+- **`CLAUDE.md`'s self-check section no longer claims a count.** It said "Seven things in the design
+ are load-bearing" and had listed fifteen for some releases; the sentence now says "a number of"
+ instead, on the same reasoning the versioning policy above records — a count written into prose goes
+ stale, and this one already had.
+
## [0.5.0] - 2026-10-16
**A finished conversation is now something the device puts away and can read back.** That is the new
diff --git a/CLAUDE.md b/CLAUDE.md
index 47d59ca..af2b512 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -476,10 +476,10 @@ Every failure this app has is silent by construction. A missing `SYSTEM_ALERT_WI
- **`ui/SelfCheckUi`** — the card, and the only code that draws a row. `✓` in the control bar opens it through `ScreenBodyService.openSelfCheck()`. Fix button per row, paints from `SelfCheck.local()` (no network, instant) then fills in the probes behind it, and offers 重新检查 because the user is being sent to *other* apps to change things and a two-tap fix should not become a round trip through the launcher.
- **`ui/SelfCheckActivity`** — the launcher icon, and the **only** surface in this app that runs while the assistant does not: everything else is an overlay owned by an accessibility service, so with accessibility off there is no ball, no card, no window and no way in at all. It is also the only place the `accessibility` row can be *red and read*. When the overlays are genuinely usable it draws nothing — it calls `dispatcher.expand()`, the same thing a long-press on the ball does, and finishes; otherwise (no service, no overlay grant, or an overlay not yet attached) it hosts the same `SelfCheckUi` card on its `stage` instead of in a window. See "The launcher icon opens two doors".
-Seven things in the design are load-bearing:
+A number of things in the design are load-bearing:
- **Levels, and only two of them may interrupt.** `FAIL` (dead now — the complaint will be "没反应"), `WARN` (works, but something degrades silently), `NOTE` (a fact worth being able to read — the wake phrase is not taught yet, a probe was skipped), `OK`. `needsAttention` is `FAIL || WARN`, and `NOTE` **never** raises a card. Without that split this is nagware and the user learns to dismiss it unread.
-- **`Fix` is a closed set of values, not a lambda.** `Screen(action, data)` / `Link(url)` / `Grant(permissions)` / `Adb(command)` / `OurSettings` / `Nothing`. `actionable` is defined from that set. Values rather than closures because the list is built off the main thread and consumed up to seconds later — an `Intent` described at 200 ms is still good at 3 s, where a captured `Context` would be a leak waiting to be filed as a bug. `Link` is its own member rather than `Screen(ACTION_VIEW, url)`: the button it produces is a different word (去下载 is not 去开启), and a Settings-labelled button that opens a browser is the small lie this list exists to avoid.
+- **`Fix` is a closed set of values, not a lambda.** `Screen(action, data, component)` / `Link(url)` / `Grant(permissions)` / `Adb(command)` / `OurSettings` / `Nothing`. `actionable` is defined from that set. Values rather than closures because the list is built off the main thread and consumed up to seconds later — an `Intent` described at 200 ms is still good at 3 s, where a captured `Context` would be a leak waiting to be filed as a bug. `Link` is its own member rather than `Screen(ACTION_VIEW, url)`: the button it produces is a different word (去下载 is not 去开启), and a Settings-labelled button that opens a browser is the small lie this list exists to avoid. **`component` exists for a vendor screen that has no action to name** (`package/package.Class`, and it wins over `action`) — see the auto-start row below, where MIUI exposes the switch as a bare component and renamed the activity across versions, so the row probes the known candidates in order and takes the first that resolves.
- **`Fix.Adb` deliberately has no button.** `WRITE_SECURE_SETTINGS` is `signature|privileged|development`, so `adb shell pm grant` is the only way and there is no switch in Settings to find. The row shows a **selectable** command and says it is an adb errand — a user hunting Settings for a switch that does not exist there is the failure mode being prevented.
- **`Fix.OurSettings` is the one door that can be missing, and the card omits it rather than drawing one that does nothing.** `SelfCheckUi.canOpenSettings` is `onOpenSettings != null` — a fact the *host* already knows, not an inference about the service. The service host always passes it (`openSettings()`); `SelfCheckActivity` passes it only when `Settings.canDrawOverlays()` is true, because its own `openOwnSettings()` raises a `SettingsUi` as an overlay and would have nowhere to draw without the grant. So the rows lose their button in exactly one case — the Activity host with the overlay grant missing — which is also the case where the red overlay row sitting right there carries the fix. Same rule as `Fix.Adb`: a button that does nothing is worse than no button. It used to be inferred instead: `serviceUp` asked "is the accessibility row green" and suppressed the button when it was not, which was true only while the service was the sole raiser of our sheet — and the two rows it gates (大脑, 语音密钥) are precisely the ones a user configures *before* the assistant works, so that inference suppressed the button in the case it exists for.
- **The keyboard row tests the exact component this app switches to.** `typeViaAdbKeyboard` is a broadcast to `com.android.adbkeyboard`, which has to be an *enabled* IME for the `commitText` to land — so "can the assistant type into other apps *this way*" is decided by two facts on the device that had no way of announcing themselves, and the symptom is an error that blames the app being driven. One row rather than two, because the three states are three steps of one errand and the button changes as they are completed: not there → 去下载, there but off → `INPUT_METHOD_SETTINGS` (the screen with the toggle, not `showInputMethodPicker`, which `ImeSwitch` refuses on purpose), enabled → OK. A permanent red "not installed" above a green "enabled" is what two rows would buy. Installed-ness is asked through `getInputMethodList()` — "is there a keyboard *in* that package", not "does the package exist", so a truncated APK does not send the user to a keyboard list that cannot contain it — and that only works because the manifest declares `QUERY_ALL_PACKAGES`; enabled-ness is the **exact** id, because a build with a renamed service is one this app cannot switch to and a green row beside a dead `type_text` is the lie this whole page exists to prevent. The download is the **v2.5-dev release asset**, not the `master/ADBKeyboard.apk` every blog post links to — upstream itself labels that one "[Old]", and v2.5-dev exists to fix it on android-36, which is what a newly bought tablet arrives on. Both APKs were read before choosing (`com.android.adbkeyboard.AdbIME`, `ADB_INPUT_TEXT`/`ADB_CLEAR_TEXT`/`ADB_EDITOR_CODE`, `commitText` — the same component and actions `ScreenController` names). It is **not** vendored into `assets/` and installed through a `FileProvider`, which would make it one tap instead of three: redistributing someone else's APK is a licensing decision rather than a build detail.
diff --git a/DISCLAIMER.md b/DISCLAIMER.md
index 29d7ab5..5dc83b3 100644
--- a/DISCLAIMER.md
+++ b/DISCLAIMER.md
@@ -46,7 +46,7 @@ The second row needs spelling out: **tool results are part of the conversation.*
**So "local mode" does not mean "processed locally."** Local mode swaps the hub for whichever provider you typed in. It does not keep a single byte on the device.
Therefore:
-- *"We do not monitor or store your data"* — **mostly true, but do not overclaim it.** No database, no behavioural analysis, and no reading of anything you send; the one exception is the version check, which tells us that some device of some model on some IP is running 0.5.0.
+- *"We do not monitor or store your data"* — **mostly true, but do not overclaim it.** No database, no behavioural analysis, and no reading of anything you send; the one exception is the version check, which tells us that some device of some model on some IP is running 0.5.1.
- *"Your data never leaves the device"* — **false. Do not claim it.**
## 3. What it can actually do (not hypotheticals — current state of the code)
diff --git a/DISCLAIMER.zh-CN.md b/DISCLAIMER.zh-CN.md
index b8dc994..96f0533 100644
--- a/DISCLAIMER.zh-CN.md
+++ b/DISCLAIMER.zh-CN.md
@@ -45,7 +45,7 @@
**因此"本机模式"不等于"本地处理"** —— 本机模式只是把大脑从 hub 换成了你填的那个服务商。它没有让数据留在设备上,一个字都没有。
所以:
-- 「我们不会监控和存储您的数据」——**基本成立,但别把话说满**。不落库、不做行为分析、不看你发的内容;唯一的例外是版本自检,它让我们知道"某个 IP 上,有一台某个型号的设备在跑 0.5.0"。
+- 「我们不会监控和存储您的数据」——**基本成立,但别把话说满**。不落库、不做行为分析、不看你发的内容;唯一的例外是版本自检,它让我们知道"某个 IP 上,有一台某个型号的设备在跑 0.5.1"。
- 「您的数据不会离开设备」——**不成立,而且不要说**。
## 3. 它真的能做什么(以下都不是危言耸听,是代码里的现状)
diff --git a/README.md b/README.md
index 1110145..2db6c2b 100644
--- a/README.md
+++ b/README.md
@@ -579,7 +579,7 @@ Pure Kotlin, no Compose; the whole thing hangs off two pillars, `WindowManager`
| minSdk | 30 | Android 11 — `AccessibilityAction.ACTION_IME_ENTER` and `takeScreenshot` are both API 30+ |
| Java / Kotlin JVM target | 1.8 | `sourceCompatibility` 1.8, `jvmTarget = '1.8'` |
| **Build JDK** | **17–20** | see [Which JDK](#which-jdk) — this is the step people get stuck on |
-| versionCode / versionName | 9 / 0.5.0 | see [CHANGELOG.md](CHANGELOG.md) for the policy |
+| versionCode / versionName | 10 / 0.5.1 | see [CHANGELOG.md](CHANGELOG.md) for the policy |
| applicationId / namespace | `net.kuafuai.andee` | never changed from the template. It affects nothing |
**Runtime dependencies** (`app/build.gradle`):
@@ -1008,7 +1008,7 @@ Read it before redistributing: **the ML Kit barcode SDK and the `play-services-*
open-source**, and the barcode model is fetched from Google at runtime.
See [CHANGELOG.md](CHANGELOG.md) for what changed and for the versioning policy. The latest release is
-**`v0.5.0`** — pre-1.0 on purpose, because the wire contract and the build flags are still moving.
+**`v0.5.1`** — pre-1.0 on purpose, because the wire contract and the build flags are still moving.
## Related documents
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 2d0e2e3..566b711 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -420,7 +420,7 @@ Google),再填该服务商的密钥。这是两个独立的服务,条款
| minSdk | 30 | Android 11 —— 因为要用 `AccessibilityAction.ACTION_IME_ENTER`(API 30+)和 `takeScreenshot`(API 30+) |
| Java / Kotlin JVM target | 1.8 | `sourceCompatibility` 1.8、`jvmTarget = '1.8'` |
| **构建用 JDK** | **17–20** | 见[配 JDK](#配-jdk),这是最容易卡住的一步 |
-| versionCode / versionName | 9 / 0.5.0 | 策略见 [CHANGELOG.md](CHANGELOG.md) |
+| versionCode / versionName | 10 / 0.5.1 | 策略见 [CHANGELOG.md](CHANGELOG.md) |
| applicationId / namespace | `net.kuafuai.andee` | 从模板里没改,不影响功能 |
**运行库依赖**(`app/build.gradle`):
@@ -883,7 +883,7 @@ CLAUDE.md 给 AI 编码助手看的架构说明(英文)
随包分发的第三方组件清单在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。再分发之前请先看:
**ML Kit 扫码 SDK 和 `play-services-*` 不是开源许可**,而且扫码模型是运行时从 Google 拉的。
-改了什么、以及版本号策略见 [CHANGELOG.md](CHANGELOG.md) —— 当前版本是 **`v0.5.0`**,故意停在
+改了什么、以及版本号策略见 [CHANGELOG.md](CHANGELOG.md) —— 当前版本是 **`v0.5.1`**,故意停在
pre-1.0:线上协议和构建开关都还在动。
## 相关文档
diff --git a/app/build.gradle b/app/build.gradle
index 34a5803..a0015d8 100644
--- a/app/build.gradle
+++ b/app/build.gradle
@@ -34,8 +34,8 @@ android {
applicationId "net.kuafuai.andee"
minSdk 30
targetSdk 34
- versionCode 9
- versionName "0.5.0"
+ versionCode 10
+ versionName "0.5.1"
testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
diff --git a/docs/releases/v0.5.1.md b/docs/releases/v0.5.1.md
new file mode 100644
index 0000000..1b22c52
--- /dev/null
+++ b/docs/releases/v0.5.1.md
@@ -0,0 +1,185 @@
+# v0.5.1
+
+**Two ways the assistant could quietly stop working, both fixed.** Its nightly review died with the
+process and never came back; and on a Xiaomi-family device, the power policy was reaping it in the
+background with nothing anywhere telling the user why. Neither is a new capability — they restore two
+things that were already supposed to happen.
+
+> **The attached APK is the `debug` build, as a stopgap.** The release build type has no
+> `signingConfig` and there is no keystore in this repository, so `assembleRelease` emits
+> `app-<abi>-release-unsigned.apk`, which will not install until you sign it. Rather than ship nothing
+> while that decision is still open, the attached APK is the debug variant: signed with the standard
+> Android debug certificate, and it installs as-is. It is `debuggable`, it is larger than a signed
+> release build, and it is **bare** — no keys, English, CodeFlying off. See **[Download](#download)**
+> for the two keys you will have to supply yourself before it can do anything.
+
+## Highlights
+
+- **The nightly review survives being killed, and comes back after a reboot.** The alarm outlived the
+ process but there was often nothing left to run it, and a reboot never re-armed it. Worse, the review
+ reads the conversation from memory — which dies with the process — so even a recovered sweep found
+ nothing to review and did nothing. Both halves are fixed: the review can now tell *"already done"*
+ from *"died before it could"*, and it can rebuild the dialogue it missed from the scrollback on disk.
+- **On Xiaomi, Redmi and POCO there is now a row for auto-start, which is what actually keeps it
+ alive.** MIUI reaps background processes on a timer and, without that grant, the process cannot bring
+ itself back — the symptom is *"it closes by itself after a while"*. The self-check now reads that
+ switch and offers a one-tap door to the MIUI screen that holds it. On any other device the row is
+ absent, because there it would be a control that does nothing.
+
+## What's Changed
+
+### Fixed
+
+- **The quiet-hour review survives the process being killed, and is re-armed after a reboot.** The
+ sweep is an `AlarmManager` alarm, so it outlives the process — but when it landed there was often no
+ service left to run it, and after a reboot it was not re-armed at all. And the review reads the
+ conversation from memory, which dies with the process, so a recovered sweep found **"0 messages to
+ review"** and did nothing. Two halves close it: the notebook now records when the sweep last actually
+ ran — the one fact that separates *"already reviewed"* from *"died before it could"* — and the
+ dialogue can be rebuilt from the persisted scrollback (user and assistant rows, each re-stamped with
+ its own clock) when the in-memory history is empty. On start the service catches up: it waits out a
+ quiet window that has not finished, skips a stretch already swept, and otherwise runs the review it
+ missed. Measured on a device: a sweep after a restart listed the four prior turns and completed.
+- **A Xiaomi-family device has a self-check row for auto-start.** MIUI's power policy reaps background
+ processes on a timer (measured at one kill every 40–60 minutes on the maintainer's tablet), and
+ without the auto-start grant `START_STICKY` cannot bring the process back — the symptom a user
+ reports is *"it closes by itself after a while"*, with nothing saying why. The new row reads the
+ vendor AppOps op (`OP_AUTO_START = 10008`, by reflection — it has a number but no name this app can
+ spell) and offers a one-tap door to MIUI's auto-start manager, probing the known components in order
+ because MIUI has renamed that activity across versions. It is **`WARN`, not `FAIL`**: with auto-start
+ off the app is fully alive right now, and it is the *future* that degrades. The row **only exists on
+ Xiaomi, Redmi and POCO** — matched on brand words, since the MIUI build property would need a hidden
+ API and the words are free.
+
+### Changed
+
+- **The version number is a deliberate departure from this project's own policy.** Both commits in this
+ release are `feat`, and the policy says MINOR for a new capability — which would have made this
+ `0.6.0`. It is `0.5.1` because neither adds a capability: they restore two things that were already
+ supposed to happen, and what a user gets by upgrading is the existing features surviving a night
+ rather than a new one arriving. Nothing in the wire contract or an existing configuration breaks
+ either way. The departure is recorded in the CHANGELOG entry as well, rather than left for a reader
+ to notice.
+- **`CLAUDE.md`'s self-check section no longer claims a count.** It said "Seven things in the design
+ are load-bearing" and had listed fifteen for some releases. The sentence now says "a number of",
+ which is the same reasoning the versioning policy records — a count written into prose goes stale.
+
+## Download
+
+Android 11+ (`minSdk 30`). The APK is **per-ABI** (`splits` in `app/build.gradle`), so pick the file
+that matches your device:
+
+| File | Take it if |
+|---|---|
+| `andee-0.5.1-debug-arm64-v8a.apk` | anything bought in the last several years — **this is the one for almost everyone** |
+| `andee-0.5.1-debug-armeabi-v7a.apk` | an older 32-bit device |
+| `andee-0.5.1-debug-x86_64.apk` | an emulator |
+
+### This build is deliberately bare
+
+It is built from source with nothing configured — **verified against the generated `BuildConfig`, not
+assumed**:
+
+- `CODEFLYING_ENABLED` is `false`, and both `CODEFLYING_KEY` and `CODEFLYING_DOMAIN` are empty, so
+ **CodeFlying is not available in this build** and nothing is pre-wired to a hosted backend.
+- **The Google voice settings are empty too**, so this build comes up on **Volcengine** and has no
+ provider key of any kind baked in.
+- `DEFAULT_LANG` is `en`: a device that has never picked a language comes up in **English**.
+- The thinking default is off.
+
+### The two keys you have to supply yourself
+
+**The assistant cannot do anything until you give it two keys.** Open **⚙ → Backend → On-device** and
+fill in:
+
+1. **The model key (LLM)** — an OpenAI-compatible endpoint plus a model name. On an English UI these
+ default to `https://api.openai.com/v1` and `gpt-4o-mini`; a Chinese UI defaults to
+ `https://api.deepseek.com` and `deepseek-flash`.
+2. **The voice key** — speech recognition and synthesis. Pick the provider first (**Voice provider** →
+ Volcengine or Google), then fill in that provider's key: a Volcengine Speech key, or a Google Vertex
+ Express key plus a GCP project *number* and a location. Optional: without it the assistant is silent
+ but still works on screen.
+
+Then, in this order: grant **Overlay** → enable **Accessibility** → tap the ball. Until the keys are
+in, the card the assistant puts up will name what is missing — that is the self-check working, not a
+fault.
+
+> **Would you rather not configure keys at all?** Then this APK is the wrong door. Use the one-click
+> page instead — **[codeflying.app/andee](https://www.codeflying.app/andee)**, or
+> **[codeflying.net/andee](https://www.codeflying.net/andee)** in mainland China. Describe what you
+> want, tap the build button, and you get a package with the **tokens already configured** plus a QR
+> code to scan. Starting is free and the free token allowance is **finite — once it runs out, tokens
+> must be bought.** It is a separate service with no direct relationship to this project, with its own
+> terms, pricing and data handling.
+
+### Why a debug build, when the README says not to hand one out
+
+Because the alternative, today, is no binary at all. The README's advice still stands for anything you
+*distribute*: a debug APK is `debuggable`, and its certificate is the **shared Android debug key** —
+so it cannot install over a release-signed build, which means moving from this to a signed release
+takes an uninstall, and an uninstall takes the notebook and the vault with it. Use this to try the
+thing, not to hand it to someone who will depend on it.
+
+## Known issues
+
+- **Auto-start is only checked on Xiaomi, Redmi and POCO.** Other vendors have the same kind of policy
+ under different names (Huawei and HONOR were both encountered during development), and there is no
+ row for them yet.
+- **The auto-start row reads a vendor op by reflection.** If a future MIUI version moves or renames it,
+ the read fails closed — it answers "not allowed" rather than crashing — but that also means a device
+ where auto-start *is* on could be told it is off. The row is `WARN`, so nothing breaks; it would just
+ be wrong.
+- **The recovered review reviews the scrollback, not the original turn boundaries.** A sweep that runs
+ after a restart sees the conversation rebuilt from persisted rows, which is enough to review but is
+ not the same object the live conversation was.
+- **The wake threshold's margin is thin**, carried from `v0.3.2` and unchanged here: the eight measured
+ judgements sit in 1.47–2.05 with the line landing in the gap between 1.69 and 1.77 — 0.08 wide. There
+ is still no quality gate on enrolment takes.
+- **A light generated page still fades in over a dark stage.** `TextPage`, `TracePage`,
+ `Theme.Body.Fullscreen`'s window background and `HtmlActivity`'s WebView backdrop are all still dark.
+ Carried over from `v0.3.1`; the app's own default has been light since `v0.4.1`.
+- **A build with CodeFlying compiled in but no API key can still raise the wrong complaint.** The
+ availability test looks at `CODEFLYING_ENABLED` and the domain rather than the key. Carried from
+ `v0.1.1` onward; not fixed by this release.
+- **`assets/andee_key.txt` is tracked by git and is not in `.gitignore`.** It ships empty, which is
+ correct — the per-user token is written in at package time. But a local build that fills it in would
+ be a key in a tracked file, and nothing currently stops that being committed.
+- The two issues `v0.1.0` listed are **unchanged and untouched in this release**:
+ `tools/verify_faces_lab.py` still reports 7/16 assertions passing against the committed
+ `reports/ball-faces-lab.html`, and the debug WebSocket server (`net/BodyWsServer`) still binds
+ `0.0.0.0:9008` with no authentication (documented in `SECURITY.md`).
+
+## Before you install
+
+Read **[DISCLAIMER.md](../../DISCLAIMER.md)** and
+**[docs/acceptable-use.md](../acceptable-use.md)** first. This app asks for accessibility, overlay,
+notification access, SMS and call log, and it can complete a payment by tapping. The only guardrail on
+that path is Android's `FLAG_SECURE`; the prompt-level checks on risky actions are instructions to the
+model, not enforcement.
+
+## Install from source
+
+If you would rather build it yourself — or need a *signed* release build, which is what you should
+actually distribute:
+
+```bash
+git clone https://github.com/kuafuai/andee
+cd andee
+git checkout v0.5.1
+./gradlew :app:assembleDebug # installs as-is, signed with the debug certificate
+```
+
+To reproduce the attached build exactly, leave `local.properties` with no `CODEFLYING_*` keys, no
+`GOOGLE_VOICE_*` keys, and `DEFAULT_LANG=en`; that is the whole configuration, and nothing is passed
+on the command line.
+
+`assembleRelease` needs your own keystore — the repo has none, so it produces an unsigned APK that
+will not install until you sign it. Full from-scratch setup, including the JDK traps, is in the
+README's **Provisioning** section.
+
+**Upgrading from v0.5.0:** `versionCode` moves `9 → 10`, so this installs over it normally. Nothing you
+configured is discarded, and nothing already on the device is re-processed — the notebook's
+`last_sweep_at` starts empty, which reads as "nothing has been swept yet", so the first catch-up after
+this build runs once and settles.
+
+**Full Changelog**: https://github.com/kuafuai/andee/compare/v0.5.0...v0.5.1