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

booboosui144c05b2657c
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 732b9c0..bd8f17d 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 **`7` / `"0.4.0"`**.
+- `versionCode` / `versionName` live in `app/build.gradle` and are currently **`8` / `"0.4.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,17 @@ hash into `versionName` at build time would close this hole; it is not implement
## [Unreleased]
+## [0.4.1] - 2026-10-15
+
+A day of fixes and one feature pair, and the version number is **a deliberate departure from the
+policy below**. The delta holds three `feat` commits — page versioning, the brain being able to see
+its own pages, and the default palette — and the policy says MINOR for a new capability, which would
+have made this `0.5.0`. It is `0.4.1` because the first two are two halves of repairing one
+incomplete feature rather than a new capability: `show_html` could already make a page and the panel
+could already list it, and what was missing was the model's knowledge of it and the device's
+willingness to treat a change as a change. Nothing in the wire contract or an existing configuration
+breaks either way, so neither number is wrong about compatibility — this one is about intent.
+
### Added
- **Revising a page makes a new *version* of it, not a second page.** Changing a page used to archive
@@ -41,17 +52,22 @@ hash into `versionName` at build time would close this hole; it is not implement
files its answer as the next version instead of rebuilding a lookalike beside it. `show_html`
gained an optional `revise` for naming the page explicitly; the device also infers it from the
`get_page` in the same turn, and from the panel row the user tapped. One artifact keeps at most 20
- revisions.
+ revisions. Which artifact a revision belongs to is decided on the device and never asked of the
+ model — and **the target is consumed rather than merely read**, a distinction found by hand on a
+ device, where a target left standing folded a second, unrelated page in as a later version of the
+ first.
- **The brain can see the pages it has made.** `show_html` draws a page and the device keeps it —
the *Made for you* panel lists them, so to the user they are a shelf — but nothing put that record into the
model's context, so a page built yesterday did not exist to the brain that built it. A request to
revise earlier work could come back as a fresh table that merely resembled the old one, or as a
flat "I have not made that". Two read-only tools close it: **`list_pages`** returns every page with
its id, title, date, size and whether the file is still there, and **`get_page`** reads one back by
- id so a revision is a revision rather than a new page wearing the old name. Alongside them the
- newest few ride on the per-turn user message as a short index — the same place and the same reason
+ id so a revision is a revision rather than a new page wearing the old name. Both are deliberately
+ **outside the `screen.` prefix**, so neither folds the card nor stops at the lock screen: reading a
+ file reaches neither. Alongside them the newest few ride on the per-turn user message as a short
+ index — the same place and the same reason
as the notebook index, since a tool only answers a question the model thought to ask. `available:
- false` on a page whose file the 100-page cap has taken is reported honestly rather than passed
+ false` on a page whose file the cap has taken is reported honestly rather than passed
over: the title and date are still true, the contents are not there to read.
### Changed
@@ -61,7 +77,24 @@ hash into `versionName` at build time would close this hole; it is not implement
`night`, so nothing here can overrule a user who picked dark, and the dark palette stays one tap
away in **Settings → Appearance**. Written this way round on purpose: the test is against the
*non-default* value, which is what makes changing the default later a one-line edit rather than a
- migration.
+ migration. **Dark is not the older palette and is not being corrected** — it is the look this app
+ was designed on, and light was derived from it as the inversion. `Theme.night`'s initial value
+ moves with the default, so the frame drawn before the saved setting is read is already the right
+ palette rather than flipping one frame in.
+- **Every face got its props, its idle life and its finishing touches.** Andee's mouth dropped twice
+ — `−0.185 → −0.235 → −0.285` — so there is a finger of sphere between its eyes and its smile
+ instead of the two crowding together. Sleep stopped being a flattening pose: the `sqx`/`sqy` that
+ squashed the resting and sleeping ball into a puddle are gone, and the floppy horns, the ⌣ eyes and
+ (while sleeping) the bubble carry it instead.
+
+### Fixed
+
+- **Changing the model, the thinking switch or the reasoning effort no longer wipes the
+ conversation.** Closing the settings card rebuilt the local brain on any `BrainConfig` difference,
+ and a rebuild is the loss of the whole conversation — flipping the thinking switch reset the
+ history mid-task, and the model then said it had no record of a page it had just built. Only a
+ change of **who answers** (mode, key, endpoint) rebuilds now; model, thinking and reasoning effort
+ are request parameters and are retuned in place, taking effect on the next request.
## [0.4.0] - 2026-10-14
diff --git a/CLAUDE.md b/CLAUDE.md
index d6adb63..74afcdf 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -86,6 +86,18 @@ The hub wire uses **LLM-facing tool names** (`get_screen_element`, `tap_screen_e
Consequence: **adding a tool means editing both `ToolSchemas.kt` and `CommandDispatcher.kt`.** A schema entry with no matching dispatcher branch fails at call time with `unknown method`; a dispatcher branch with no schema entry is invisible to the brain. The `description` strings in `ToolSchemas` are prompt text read by an LLM — they are behavioral documentation, not code comments, and are meant to stay in sync with the equivalent Python `body_tools/` files on the brain side.
+### 产物面板记的是「版本」,不是「条目」(`ui/ChatHistory.kt`)
+
+一轮 `show_html` 曾经就是一个新条目,所以「继续修改」两次会在货架上留下三个几乎一样的产物,且没有任何东西说明哪个是当前的。现在 `Entry` 多两个字段:**`groupId`**(属于哪个产物)与 **`version`**(第几版,**只增不减**)。面板 `ArtifactsUi` 用 `collapseToArtifacts` 折成 **一产物一行**(`ChatHistory.kt:158`),行上带 `v3`;旧版仍在磁盘上,**版本**打开列表、任何一版都能打开、**回到这版**把旧的一版改成当前版 —— 而这个动作本身**是追加一个新版本**,所以历史永远是 append-only,连回退都可回退。**单产物上限 `MAX_VERSIONS = 20`**(`artifacts()` 里 `dropLast`),全局页数上限仍是 `MAX_PAGES = 100`(数的是**带 page 的 entry 数**,版本化之后就是"最多一百个版本")。
+
+**归属判定全在设备侧,绝不问模型**,这是这一节最该记住的东西。三个入口:① `ui.get_page` 读完设目标;② 面板的「继续修改」把这个产物的 id 交给这一轮;③ `show_html` 可选参数 `revise` 显式点名。`show_html` 不带以上任何一个 ⇒ 新产物。
+
+🔴 **目标必须「消费」而不是只「读」**:`resolveRevisionTarget` 返回 `Pair(目标, null)`,调用方必须把返回的 null 存回去。真机抓到的 bug —— 一个回合里 `get_page` 之后再画两页,第二页被误并成第一页的 `v5`。**每个回合入口都要 `beginTurn`**(非编辑态传 null),否则上一轮的目标会漏进来。分组逻辑是纯函数、有 `ChatHistoryVersionsTest` 18 个用例,但**单测没覆盖到上面那个消费 bug** —— 真机走一遍四条路径(`get_page`→`show_html`、显式 `revise`、必须不被吞的新页面、回退)才算验过。
+
+**模型看得见自己的产物**靠两个**只读**工具:`list_pages`(一产物一行,带 version/versions)与 `get_page`(按 id 读回源码,**任何历史版本都可读**)。**故意不在 `screen.` 前缀下** —— 读文件既不折叠卡片也不受锁屏限制,那个前缀的守卫对它们没有意义。它们的新鲜几行还搭在**每轮 user message**的索引里,与 notebook 索引同一位置同一理由(工具只回答模型想得到的问题)。
+
+⚠️ 存档里新增了 `group`/`version` 两个键,**`load()` 遇到缺 `group` 的旧记录必须 fallback 成它自己的 id**(`ChatHistory.kt:608` 的 `if (o.has("group")) o.optLong("group") else id`),**绝不能是 0** —— 那会把所有旧页面并成一个产物。`Entry` 上 `groupId = id` 的默认值同时是「新条目自成一组」的表达。
+
### The overlay-vs-gesture conflict
This is the subtlest invariant in the codebase. `ScreenController.tap/swipe/longPress` use `dispatchGesture`, which injects events into the **real touch pipeline** — so the app's own floating overlay would intercept them first. Every gesture-based command is therefore wrapped in `passthroughForGesture` (`CommandDispatcher`) or the equivalent in `ScreenBodyService.swipe`, which flips the overlay to non-touchable, **sleeps ~50 ms** (because `updateViewLayout` is posted to the UI thread and needs a frame or two to actually apply), runs the gesture, then restores. The window stays visible throughout.
diff --git a/DISCLAIMER.md b/DISCLAIMER.md
index d649ca7..0730957 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.4.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.4.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 7286c20..c191fdc 100644
--- a/DISCLAIMER.zh-CN.md
+++ b/DISCLAIMER.zh-CN.md
@@ -45,7 +45,7 @@
**因此"本机模式"不等于"本地处理"** —— 本机模式只是把大脑从 hub 换成了你填的那个服务商。它没有让数据留在设备上,一个字都没有。
所以:
-- 「我们不会监控和存储您的数据」——**基本成立,但别把话说满**。不落库、不做行为分析、不看你发的内容;唯一的例外是版本自检,它让我们知道"某个 IP 上,有一台某个型号的设备在跑 0.4.0"。
+- 「我们不会监控和存储您的数据」——**基本成立,但别把话说满**。不落库、不做行为分析、不看你发的内容;唯一的例外是版本自检,它让我们知道"某个 IP 上,有一台某个型号的设备在跑 0.4.1"。
- 「您的数据不会离开设备」——**不成立,而且不要说**。
## 3. 它真的能做什么(以下都不是危言耸听,是代码里的现状)
diff --git a/README.md b/README.md
index c798e14..b2d2d28 100644
--- a/README.md
+++ b/README.md
@@ -212,8 +212,10 @@ up to six photos — from the camera or the gallery — with or without words.
**12. Answers you can keep.**
Anything structured — a comparison, a plan, meeting minutes — comes back as a page it writes and
-puts on screen. The **Made for you** panel keeps up to a hundred of them to reopen, delete, or
-revise by just saying what should change. Ask it to record a meeting and it holds the microphone
+puts on screen. The **Made for you** panel keeps one row per page and holds the revisions behind it —
+up to twenty of each — so you can reopen it, delete it, or have it revised by just saying what should
+change. **A revision is a new version of the same page, not a second page**, and any earlier version
+can be made current again. Ask it to record a meeting and it holds the microphone
for the hour, writing a verbatim transcript to disk as it goes, then turns it into minutes.
### Body
@@ -256,8 +258,8 @@ logged to `ChatHistory`, and is handed to whichever backend is in effect (`brain
out-of-box default).
The agent loop **is** `LocalBrain`. It holds the system prompt constant and inlines the volatile
-parts (clock, notebook index, scenes, photos) into the user message, so the provider's prefix cache
-still hits; it rebuilds the tool table every turn; and it calls the model in a **non-streaming**
+parts (clock, notebook index, scenes, pages, photos) into the user message, so the provider's prefix
+cache still hits; it rebuilds the tool table every turn; and it calls the model in a **non-streaming**
`for` loop of up to `maxSteps` steps. A reply carrying tool calls goes through `methodOf()` to the
one `CommandDispatcher`; a reply without any ends the turn. The result comes back out through six
channels — speech, text, a full-screen page, saved artifacts, long text, and physical motion.
@@ -561,7 +563,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 | 7 / 0.4.0 | see [CHANGELOG.md](CHANGELOG.md) for the policy |
+| versionCode / versionName | 8 / 0.4.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`):
@@ -990,7 +992,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.4.0`** — pre-1.0 on purpose, because the wire contract and the build flags are still moving.
+**`v0.4.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 9e6e6b7..d59531e 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -184,9 +184,10 @@ Android 13 及以上,它通过无障碍服务自带的输入通道打字 —
选,带不带文字都可以。
**12. 能留下来的答案。**
-凡是有结构的东西 —— 一份对比、一个计划、一份会议纪要 —— 它会写成一页放到屏幕上。**「产物」**面板最多
-留一百页,可以重新打开、删除,或者直接说"哪里要改"让它改。让它录会,它会占着麦克风录完一整场,边录
-边把逐字稿写到本机,结束后再整理成纪要。
+凡是有结构的东西 —— 一份对比、一个计划、一份会议纪要 —— 它会写成一页放到屏幕上。**「产物」**面板
+一个产物一行,改动记录都留在它后面(每个最多二十版),可以重新打开、删除,或者直接说"哪里要改"让它
+改。**改一次是同一个产物的新版本,不是又生出一个产物**,任何一版都能恢复成当前版。让它录会,它会
+占着麦克风录完一整场,边录边把逐字稿写到本机,结束后再整理成纪要。
### 身体
@@ -222,7 +223,7 @@ WebSocket hub 连到设备。两者之间只是一份普通的工具 schema 契
那个后端(`brain = local` 是开箱默认)。
agent loop **就是** `LocalBrain`。它让系统提示词保持不变,把会变的部分(时钟、notebook 索引、
-情景、照片)内联进 user 消息,这样服务商的前缀缓存仍然命中;工具表每轮重建;然后是一个
+情景、产物、照片)内联进 user 消息,这样服务商的前缀缓存仍然命中;工具表每轮重建;然后是一个
**非流式**的 `for` 循环,最多 `maxSteps` 步。带工具调用的回复经 `methodOf()` 送到唯一的
`CommandDispatcher`;不带工具调用的回复结束这一轮。结果从六个通道送出来 —— 语音、文字、
全屏网页、产物、长文、以及物理动作。
@@ -407,7 +408,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 | 7 / 0.4.0 | 策略见 [CHANGELOG.md](CHANGELOG.md) |
+| versionCode / versionName | 8 / 0.4.1 | 策略见 [CHANGELOG.md](CHANGELOG.md) |
| applicationId / namespace | `net.kuafuai.andee` | 从模板里没改,不影响功能 |
**运行库依赖**(`app/build.gradle`):
@@ -870,7 +871,7 @@ CLAUDE.md 给 AI 编码助手看的架构说明(英文)
随包分发的第三方组件清单在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。再分发之前请先看:
**ML Kit 扫码 SDK 和 `play-services-*` 不是开源许可**,而且扫码模型是运行时从 Google 拉的。
-改了什么、以及版本号策略见 [CHANGELOG.md](CHANGELOG.md) —— 当前版本是 **`v0.4.0`**,故意停在
+改了什么、以及版本号策略见 [CHANGELOG.md](CHANGELOG.md) —— 当前版本是 **`v0.4.1`**,故意停在
pre-1.0:线上协议和构建开关都还在动。
## 相关文档
diff --git a/app/build.gradle b/app/build.gradle
index 36243ee..a30a29b 100644
--- a/app/build.gradle
+++ b/app/build.gradle
@@ -34,8 +34,8 @@ android {
applicationId "net.kuafuai.andee"
minSdk 30
targetSdk 34
- versionCode 7
- versionName "0.4.0"
+ versionCode 8
+ versionName "0.4.1"
testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
diff --git a/docs/releases/v0.4.1.md b/docs/releases/v0.4.1.md
new file mode 100644
index 0000000..43f4d93
--- /dev/null
+++ b/docs/releases/v0.4.1.md
@@ -0,0 +1,189 @@
+# v0.4.1
+
+**Pages became versions, the brain learned to see its own work, and the default look is now the light
+one.** Three fixes ride along: the settings card no longer throws the conversation away, every face
+got its finishing touches, and a page can be revised without growing a second page beside it.
+
+> **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 revision is a new version of a page, not a second page.** Ask for a change and the panel keeps
+ one row for it with the old revisions behind it — **Versions** opens the list, and any of them can
+ be made current again, as a new version rather than by rewriting history.
+- **The brain can see the pages it made.** `list_pages` and `get_page` are two new read-only tools,
+ and the newest few also ride along on every turn — so "change the table from yesterday" reads
+ yesterday's table back instead of producing a lookalike or denying it exists.
+- **A fresh install comes up light.** A device that has chosen a theme keeps it; the dark palette is
+ one tap away in **Settings → Appearance**.
+- **Changing the model no longer wipes the conversation.** Flipping the thinking switch used to reset
+ the history mid-task, and the model would then say it had no record of a page it had just built.
+
+## What's Changed
+
+### Added
+
+- **Page revisions, kept as versions.** `ChatHistory.Entry` gained a `groupId` (which artifact it
+ belongs to) and a `version` (which revision — **only ever increasing**). The **Made for you** panel
+ collapses to one row per artifact with its version number (`v3`); older revisions stay on disk, and
+ **Go back to this** makes an old one current **as a new version**, so the history stays append-only
+ and a rollback can itself be rolled back. One artifact keeps at most 20 revisions.
+ **Which artifact a revision belongs to is decided on the device, never asked of the model** — reading
+ a page back arms the target, the panel's revise button hands it over, and `show_html` gained an
+ optional `revise` for naming one explicitly. The target is **consumed rather than merely read**:
+ found by hand on a device, where a target left standing folded a second, unrelated page in as a
+ later version of the first.
+- **`list_pages` and `get_page`.** A page drawn yesterday existed for the user (it is on the shelf)
+ and not for the model that drew it, so a request to revise earlier work could come back as a fresh
+ table that merely resembled the old one, or as a flat "I have not made that". `list_pages` returns
+ every page with its id, title, date, size and whether the file is still there; `get_page` reads one
+ back by id, **any revision of it**. Both are deliberately outside the `screen.` prefix, so neither
+ folds the card nor stops at the lock screen — reading a file reaches neither. Alongside them the
+ newest few ride on the per-turn user message as a short index, the same place and for the same
+ reason as the notebook index: a tool only answers a question the model thought to ask.
+
+### Changed
+
+- **The default appearance is light, not dark.** A fresh install now comes up on the light palette.
+ A device that has touched the setting keeps whatever it chose — the rule reads only an explicit
+ `night`, so nothing here can overrule a user who picked dark. Written against the *non-default*
+ value on purpose: it makes changing the default later a one-line edit rather than a migration, and
+ the dark palette stays one tap away in **Settings → Appearance**.
+ **Dark is not the older palette and nothing about it is being corrected** — it is the look this app
+ was designed on, and light was derived from it as the inversion. The frame drawn before the saved
+ setting is read moves with the default, so a fresh device does not flip palettes one frame in.
+- **Every face got its props, its idle life and its finishing touches.** Andee's mouth dropped twice
+ (`−0.185 → −0.235 → −0.285`) so there is a finger of sphere between its eyes and its smile instead
+ of the two crowding together. **Sleep stopped being a flattening pose**: the squash that melted the
+ resting and sleeping ball into a puddle is gone, and the floppy horns, the ⌣ eyes and (while
+ sleeping) the bubble carry it instead.
+
+### Fixed
+
+- **Changing the model, the thinking switch or the reasoning effort no longer wipes the
+ conversation.** Closing the settings card rebuilt the local brain on any config difference, and a
+ rebuild is the loss of the whole conversation — flipping the thinking switch reset the history
+ mid-task, and the model then said it had no record of a page it had just built. Only a change of
+ **who answers** (mode, key, endpoint) rebuilds now; model, thinking and reasoning effort are request
+ parameters and are retuned in place, taking effect on the next request.
+
+## 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.4.1-debug-arm64-v8a.apk` | anything bought in the last several years — **this is the one for almost everyone** |
+| `andee-0.4.1-debug-armeabi-v7a.apk` | an older 32-bit device |
+| `andee-0.4.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
+
+- **Twenty revisions is a per-artifact cap, and a global one sits behind it.** `MAX_VERSIONS` (20)
+ trims the oldest revisions of one artifact; the older `MAX_PAGES` (100) still governs how many
+ page-bearing entries exist at all — and since a revision is an entry, that global number now counts
+ versions rather than pages. Neither is surfaced anywhere in the UI.
+- **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`; **worth reading again in this release**, because the app's own default is
+ now light while those four surfaces are not.
+- **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.4.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.4.0:** `versionCode` moves `7 → 8`, so this installs over it normally. Nothing you
+configured is discarded: a device that picked a theme keeps it (only a device that never picked one
+changes, and it moves to light), and pages that already exist on the shelf keep their own row — an
+artifact that predates this release reads as a single version until you revise it.
+
+**Full Changelog**: https://github.com/kuafuai/andee/compare/v0.4.0...v0.4.1