From 136bf7cfa342cc77e13e9fca531b77acaf9f9db3 Mon Sep 17 00:00:00 2001
From: intelligence <intelligence@debian.local>
Date: Sat, 29 Aug 2026 19:36:39 +0200
Subject: [PATCH] chore: README

---
 AGENTS.md | 26 ++++++++++++++++++++++++++
 README.md | 12 ++++++++++--
 2 files changed, 36 insertions(+), 2 deletions(-)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..030f64c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,26 @@
+# Transui design
+
+- Linux is a GTK3 desktop recorder. It supports hosted transcription with an optional local fallback and can type at the cursor or copy to the clipboard.
+- Android is remote-only. It provides an Android `RecognitionService`, a voice-only input method, and a floating recognition activity. Do not add a local llama.cpp path to Android.
+- Both clients call OpenAI-compatible `/v1/audio/transcriptions` endpoints and clean only the Qwen3-ASR `language …<astext>` or `language …<asr_text>` prefix.
+- The Android voice UI is an opaque, compact system surface. Teal is the recording signal. `PushToTalkButton` draws the Apps and Stop Circle glyphs with Canvas because the target device drops `ImageButton` image layers. Keep the glyphs drawn above the button background.
+
+## llama.cpp local endpoint
+
+The Linux local fallback begins with this multipart request. `response_format=json`
+is required; `prompt` is optional and may request transcription or translation.
+
+```sh
+curl -s -X POST -F response_format=json http://localhost:8080/v1/audio/transcriptions \
+  -F file="@test.mp3" \
+  -F 'prompt=Transcribe the following speech segment in English, and translate them into chinese.'
+```
+
+llama.cpp may return an event envelope instead of a bare OpenAI response:
+
+```json
+{"type":"transcript.text.done","text":"这是个测试。你能听到什么？我希望这很好。","usage":{"type":"tokens","input_tokens":241,"output_tokens":516,"total_tokens":757,"input_tokens_details":{"cached_tokens":0}}}
+```
+
+Use `text` as the transcript. Accept `transcript.text.done`; do not require a
+bare `{ "text": "…" }` response.
diff --git a/README.md b/README.md
index a5db33a..850528e 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,8 @@
 # Transui
 
 A compact GTK3 desktop transcription tool for OpenAI-compatible and llama.cpp
-`/v1/audio/transcriptions` endpoints.
+`/v1/audio/transcriptions` endpoints. It also includes a remote-only Android
+speech-recognition provider and voice input method.
 
 ## Dependencies
 
@@ -21,6 +22,14 @@ cmake --build build
 sudo cmake --install build
 ```
 
+Android release APKs build in Gitea CI. To run local Android checks, configure
+the Android SDK and run:
+
+```sh
+cd android
+./gradlew lintDebug lintRelease testDebugUnitTest
+```
+
 ## Commands
 
 ```sh
@@ -28,4 +37,3 @@ transui settings    # configure endpoints, prompt, and destination
 transui record      # open the record window
 transui             # same as record
 ```
-