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.2

booboosui634c6ee34ef1
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d78e54f..495c48f 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 **`10` / `"0.5.1"`**.
+- `versionCode` / `versionName` live in `app/build.gradle` and are currently **`11` / `"0.5.2"`**.
- 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,57 @@ hash into `versionName` at build time would close this hole; it is not implement
## [Unreleased]
+## [0.5.2] - 2026-10-19
+
+**Two fixes from watching it work on an app that hides its element tree, and a new hero image.** The
+fixes are the substance: commenting on a WeChat Moments post took **64 steps and 341 seconds**, and the
+same task now takes **20 steps and 58 seconds**, sent on the first tap. The version number is `0.5.2`
+rather than `0.6.0` because the one `feat` commit in this delta is the README's cover art, not a
+capability — nothing a user can do changed by it.
+
+### Fixed
+
+- **A swipe no longer coasts past what the model aimed at.** `swipe_by_coordinates` lifted the finger
+ while it was still moving, so the list flung several screens beyond the target and the model lost its
+ place — the largest single cost in the 64-step measurement. The stroke now **holds at its end point
+ before lifting** (`SWIPE_HOLD_MS`), and `ACTION_CANCEL` ends a scroll without a fling, so the list
+ moves about as far as the finger did and **the distance becomes the control**. A new `fling` parameter
+ (default `false`) keeps the old behaviour for long jumps, and its tool text says to take a fresh look
+ afterwards rather than assume where it stopped.
+- **The tap right after blind typing is refused unless it came from a zoom.** On an app that withholds
+ its tree, the reply box is a thin strip directly on top of the post below it, so a grid-cell tap aimed
+ at it landed on that post and opened it — **twice out of two** on the same Moments reply box. After a
+ `type_text` on such an app, only a tap carrying `on="zoom"` is accepted, with an error that says why;
+ leaving the box clears the rule. Zoom-then-tap is how the same comment now sends on the first attempt.
+- **`submit_input` no longer reports success on a box that cannot be submitted that way.** WeChat's
+ comment box declares `IME_FLAG_NO_ENTER_ACTION` and sends only from its own button; firing the IME
+ action there answered "done" while sending nothing. It now says it cannot, and names the app's own
+ send button. `type_text` and `submit_input` also work when the tree has no focus node but the input
+ connection is bound.
+- **The tap ring is drawn where the tap landed.** The marker window is positioned in display pixels, but
+ an API 30+ overlay fits the system-bar insets by default, so its frame began below the status bar and
+ **every ring sat that far under the real tap**. It now carries the same `FLAG_LAYOUT_IN_SCREEN` /
+ `fitInsetsTypes = 0` / cutout mode the ball window already had. The caption's 0-1000 numbers were
+ always right.
+
+### Changed
+
+- **The tool text now corrects three things models kept getting wrong.** `zoom_screen_region`'s `x/y/w/h`
+ are **0-1000 of the whole screen, never pixels of an image** — a screenshot arrives downscaled (often
+ ~576 px wide as the model sees it), and every zoom now reports the rectangle it actually showed so a
+ model can notice it was in the wrong space. `type_text`'s text states that a box which opened with the
+ keyboard is **already focused** and should be typed into without a preliminary tap. `take_screenshot`'s
+ text states that **the assistant's own ball is never in a capture** — the device hides its overlays for
+ the instant of capture — because a model that saw a round blue shape blamed it for covering a button
+ and tried to route around it.
+- **The README's first image is now a phone with the character sitting on it** rather than a floating
+ head. `images/brand/andee-device.png` is the new hero art and `tools/make_social_preview.py` places it
+ at 720 px wide, bottom-right, keeping 60 px of white padding with a 40 px analytic edge ramp; the mood
+ strip narrows to 512/88 so the phone's left corner clears the last cell, and the text-to-art gap check
+ now measures the character's left edge instead of a hard-coded offset. All four generated images were
+ regenerated; **the round avatar is byte-identical**, because it still uses the head-only asset. The
+ character in this render has a body; the app still draws a floating sphere.
+
## [0.5.1] - 2026-10-19
**Two ways the assistant could quietly lose the ability to keep working, both fixed.** One, its
diff --git a/CLAUDE.md b/CLAUDE.md
index af2b512..59338e2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -132,6 +132,9 @@ Ported from generic_bridge (phone.sh), whose finding is the founding rule here:
- `get_screen_element` returns an **element outline**, one line per element, in document order and indented by depth: ` e7*|Button|发送|[490,321]` — eid, `*` clickable marker, class, label, and the element's center in **0-1000 relative** coordinates computed by us from `getBoundsInScreen`. The indentation is the pruned tree rendered cheaply (~20% more characters than an unindented list, against ~170% for the nested JSON) and it is what makes "which one" answerable: on a 朋友圈 feed the `#comment_btn` under the line saying 好友3 *is* 好友3's comment button. Label falls back `text → desc → #<id tail>`; a `#` label is an internal resource name, never visible text. Ordering is document order, not useful-first — sorting scattered each post across the list and stacked twenty identical label-less `ImageView` lines at the bottom. Truncation is a safety valve (`MAX_ELEMENT_LINES = 300`, reported as `elements_dropped`) that drops decorative leaves from the tail first and never containers, so grouping survives it.
- `tap_screen_element` takes an **eid** (the old resource-id parameter is gone — WeChat nodes mostly have none, and e-numbers cover every listed element). `rebuildIndexAndList` rebuilds the eid→pixel-center index on every dump; `tapByEid` looks the number up and passes the **pixels straight to `tap()`** — no px→norm→px round-trip (an earlier lost version fed norm values into the pixel `tap()` and every e-tap landed in the top-left quadrant). Stale/unknown eids fail loudly with "re-dump, don't guess".
- `tap_by_coordinates` / `long_press_by_coordinates` / `swipe_by_coordinates` are the **last resort** for self-drawn panes (mini-program, WebView, game canvas) and take **0-1000 relative integers** — resolution-independent and immune to screenshot downscaling. Values outside 0-1000 are **rejected**, never clamped (a silent clamp to the edge is a mis-tap the model can't see). `ScreenController.tapNorm/longPressNorm/swipeNorm` convert to pixels against the local display.
+- 🔴 **`swipe_by_coordinates` does not coast by default, and that is the fix rather than a preference.** A plain `StrokeDescription` lifts while still moving, so the list flung several screens past the target and the model lost its place (measured on a tree-blind 朋友圈: 64 steps / 341 s for one comment). The stroke is now a **continued stroke that holds at the end point** for `SWIPE_HOLD_MS` before lifting — `ACTION_CANCEL` ends a scroll without a fling, so the list moves about as far as the finger did and the distance becomes the control. `fling=true` keeps the old single-stroke behaviour for long jumps, and its tool text says to take a fresh look afterwards rather than assume where it stopped. **A cancelled hold still leaves the list where the finger put it** — do not "fix" that by retrying the gesture.
+- 🔴 **The tap right after blind typing is refused unless it came from a zoom** (`requireAimedSend`). On an app that withholds its tree, the input strip above the keyboard is thin and sits on top of the post below it, so a grid-cell tap aimed at it lands on that content instead — twice out of two on the same 朋友圈 reply box. After a `type_text` on a tree-blind app, only a tap carrying `on="zoom"` is accepted, with an error that says why; leaving the box clears `typedBlindAt`. Related: `A11yIme.sendsOnlyFromButton` reads `IME_FLAG_NO_ENTER_ACTION` with no custom `actionId` — on such a field (WeChat's comment box) `submit_input` used to report success while sending nothing, so it now reports that it cannot and names the app's own send button.
+- **Screenshot pixels are never 0-1000 units, and `zoom_screen_region` reports the rectangle it actually showed** (`region`). A capture arrives downscaled (often ~576 px wide as the model sees it), so a position measured in those pixels is the wrong number for `zoom`'s `x/y/w/h`; every zoom echoing `region` back is what lets the model notice it was in the wrong space. The tool text also states that **our own ball is never in a capture** — the device hides its overlays for the instant of capture — because a model that saw a round blue shape blamed it for covering a button and routed around it.
- `take_screenshot` downscales to **1280 on the long side** before base64 — proportions are preserved and the 0-1000 protocol is scale-invariant, so this is free token savings.
- **Stuck-loop guard**: per-location counting, not consecutive-with-no-change (the real dead-loop interleaves menu opens, wrong pages and backs, and apps emit content events constantly — both naive conditions miss it). Gestures within 120 px of each other share a bucket; within 5 minutes, the 4th tap on the same bucket is refused with an error telling the brain to stop, re-observe, and ask the user. Swipes are exempt (list scrolling legitimately repeats); e-taps are exempt (re-tapping a confirmed element is normal operation).
- **NO_TREE policy** (empty-list hint): prefer `back`/`home` to exit and retry via a different route over blind coordinate taps — a wrong exit costs one tap, a wrong tap can cost the task.
diff --git a/DISCLAIMER.md b/DISCLAIMER.md
index 5dc83b3..c5c9184 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.1.
+- *"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.2.
- *"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 96f0533..714b921 100644
--- a/DISCLAIMER.zh-CN.md
+++ b/DISCLAIMER.zh-CN.md
@@ -45,7 +45,7 @@
**因此"本机模式"不等于"本地处理"** —— 本机模式只是把大脑从 hub 换成了你填的那个服务商。它没有让数据留在设备上,一个字都没有。
所以:
-- 「我们不会监控和存储您的数据」——**基本成立,但别把话说满**。不落库、不做行为分析、不看你发的内容;唯一的例外是版本自检,它让我们知道"某个 IP 上,有一台某个型号的设备在跑 0.5.1"。
+- 「我们不会监控和存储您的数据」——**基本成立,但别把话说满**。不落库、不做行为分析、不看你发的内容;唯一的例外是版本自检,它让我们知道"某个 IP 上,有一台某个型号的设备在跑 0.5.2"。
- 「您的数据不会离开设备」——**不成立,而且不要说**。
## 3. 它真的能做什么(以下都不是危言耸听,是代码里的现状)
diff --git a/README.md b/README.md
index 2db6c2b..21ebf1b 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 | 10 / 0.5.1 | see [CHANGELOG.md](CHANGELOG.md) for the policy |
+| versionCode / versionName | 11 / 0.5.2 | 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.1`** — pre-1.0 on purpose, because the wire contract and the build flags are still moving.
+**`v0.5.2`** — 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 566b711..9c27d82 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 | 10 / 0.5.1 | 策略见 [CHANGELOG.md](CHANGELOG.md) |
+| versionCode / versionName | 11 / 0.5.2 | 策略见 [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.1`**,故意停在
+改了什么、以及版本号策略见 [CHANGELOG.md](CHANGELOG.md) —— 当前版本是 **`v0.5.2`**,故意停在
pre-1.0:线上协议和构建开关都还在动。
## 相关文档
diff --git a/app/build.gradle b/app/build.gradle
index a0015d8..db89b03 100644
--- a/app/build.gradle
+++ b/app/build.gradle
@@ -34,8 +34,8 @@ android {
applicationId "net.kuafuai.andee"
minSdk 30
targetSdk 34
- versionCode 10
- versionName "0.5.1"
+ versionCode 11
+ versionName "0.5.2"
testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
diff --git a/docs/releases/v0.5.2.md b/docs/releases/v0.5.2.md
new file mode 100644
index 0000000..9f49e20
--- /dev/null
+++ b/docs/releases/v0.5.2.md
@@ -0,0 +1,194 @@
+# v0.5.2
+
+**Two fixes from watching it work on an app that hides its element tree, plus a new hero image.**
+Commenting on a WeChat Moments post took **64 steps and 341 seconds**; the same task now takes
+**20 steps and 58 seconds**, sent on the first tap. Neither fix is a new capability — they stop the
+assistant from wasting turns, and both were found by measuring rather than by reading code.
+
+> **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
+
+- **A swipe moves as far as the finger did, and stops there.** It used to lift mid-motion, so the list
+ flung several screens past the target and the model lost its place — the single largest cost in the
+ 64-step measurement. Distance is now the control: to bring something 300 units into view, swipe 300
+ units. A new `fling` option keeps the old behaviour for long jumps through a feed.
+- **The tap right after typing into a reply box now has to be aimed.** On an app that hides its tree,
+ the reply strip is a thin band lying on top of the post below it, so a grid-cell tap aimed at it
+ opened that post instead — twice out of two. After blind typing, only a tap that came from a zoom is
+ accepted, and the error says so.
+- **`submit_input` stops claiming success on a box that cannot be submitted that way.** WeChat's
+ comment box only sends from its own button; firing the IME action there answered "done" while
+ sending nothing.
+- **The tap ring is drawn where the tap landed.** It was sitting a status bar below, on every tap.
+- **The README's first image is a phone with the character sitting on it**, instead of a floating head.
+
+## What's Changed
+
+### Fixed
+
+- **A swipe no longer coasts past what the model aimed at.** `swipe_by_coordinates` lifted the finger
+ while it was still moving, so the list flung several screens beyond the target. The stroke now
+ **holds at its end point before lifting**, and `ACTION_CANCEL` ends a scroll without a fling — so the
+ list moves about as far as the finger did, and **the distance becomes the control**. A new `fling`
+ parameter (default `false`) keeps the old behaviour for long jumps, and its tool text says to take a
+ fresh look afterwards rather than assume where it stopped.
+- **The tap right after blind typing is refused unless it came from a zoom.** On an app that withholds
+ its tree, the reply box is a thin strip directly on top of the post below it, so a grid-cell tap
+ aimed at it landed on that post and opened it — **twice out of two** on the same Moments reply box.
+ After a `type_text` on such an app, only a tap carrying `on="zoom"` is accepted, with an error that
+ says why; leaving the box clears the rule. Zoom-then-tap is how the same comment now sends on the
+ first attempt.
+- **`submit_input` no longer reports success on a box that cannot be submitted that way.** WeChat's
+ comment box declares `IME_FLAG_NO_ENTER_ACTION` and sends only from its own button; firing the IME
+ action there answered "done" while sending nothing. It now says it cannot, and names the app's own
+ send button. `type_text` and `submit_input` also work when the tree has no focus node but our input
+ connection is bound to the field.
+- **The tap ring is drawn where the tap landed.** The marker window is positioned in display pixels, but
+ an API 30+ overlay fits the system-bar insets by default, so its frame began below the status bar and
+ **every ring sat that far under the real tap**. It now carries the same `FLAG_LAYOUT_IN_SCREEN` /
+ `fitInsetsTypes = 0` / cutout mode the ball window already had. The caption's 0-1000 numbers were
+ always right.
+
+### Changed
+
+- **The tool text now corrects three things models kept getting wrong.** `zoom_screen_region`'s
+ `x/y/w/h` are **0-1000 of the whole screen, never pixels of an image** — a screenshot arrives
+ downscaled (often ~576 px wide as the model sees it), and every zoom now reports the rectangle it
+ actually showed, so a model can notice it was in the wrong space. `type_text`'s text states that a
+ box which opened with the keyboard is **already focused** and should be typed into without a
+ preliminary tap. And the screenshot text states that **the assistant's own ball is never in a
+ capture** — the device blanks its overlays for the instant of capture — because a model that saw a
+ round blue shape blamed it for covering a button and tried to route around it.
+- **The README's first image is now a phone with the character sitting on it** rather than a floating
+ head. `images/brand/andee-device.png` is the new hero art, and the generator places it 720 px wide,
+ bottom-right, keeping 60 px of white padding with a 40 px analytic edge ramp; the mood strip narrows
+ to 512/88 so the phone's left corner clears the last cell, and the text-to-art gap check now measures
+ the character's left edge instead of a hard-coded offset. All four generated images were regenerated;
+ **the round avatar is byte-identical**, because it still uses the head-only asset. The character in
+ this render has a body — the app still draws a floating sphere.
+
+## 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.2-debug-arm64-v8a.apk` | anything bought in the last several years — **this is the one for almost everyone** |
+| `andee-0.5.2-debug-armeabi-v7a.apk` | an older 32-bit device |
+| `andee-0.5.2-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
+
+- **The zoom-then-tap rule is deliberately blunt, and it expires rather than persisting.** After blind
+ typing, *every* plain grid-cell tap is refused, including one aimed somewhere legitimate on the same
+ screen — the model has to zoom first. That costs a turn on an app that hides its tree, and it is the
+ trade taken: the alternative was landing on the post underneath, which cost several. The rule also
+ lifts by itself after two minutes, and clears as soon as the box goes away, so a task that typed and
+ moved on is not haunted by it.
+- **`fling=true` still coasts unpredictably.** The option exists for long jumps, and its text says so,
+ but nothing verifies where the list stopped — a model that flings and then assumes a position will
+ still be wrong.
+- **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.2
+./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.1:** `versionCode` moves `10 → 11`, so this installs over it normally. Nothing
+you configured is discarded. The two fixes change what the model does, not what the device stores, so
+there is nothing to migrate — a device that has been running v0.5.1 behaves the same at rest and
+differently the next time it swipes.
+
+**Full Changelog**: https://github.com/kuafuai/andee/compare/v0.5.1...v0.5.2