diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f640f38
--- /dev/null
+++ b/README.md
@@ -0,0 +1,71 @@
+# COLORCAST — tap the watch, paint the phone (Xiaomi Watch S4 + Android)
+
+Watch app + Android companion: tap the watch screen and the companion's screen
+changes color, over Bluetooth LE. Colors cycle RED → GREEN → BLUE → YELLOW.
+
+**Status: BUILT, UNTESTED ON HARDWARE.** The BLE code follows the official Vela
+docs exactly, but whether the S4 firmware exposes BLE to quick apps under
+AstroBox is unverified (same unknown class as the crown API).
+
+## How it works
+
+```text
+WATCH (GATT client)                     PHONE (GATT server, ColorCompanion)
+┌──────────────────────┐                ┌────────────────────────────┐
+│ createScanner        │  BLE advertise │ advertises ILIAS-COLOR     │
+│ subscribeBLEDeviceFind│ ◄──────────── │ service 0000fee7-…         │
+│ createGattClientDevice│                │ char 0000fee8-… (WRITE)    │
+│ connect              │                │                            │
+│ writeCharacteristic  │ ── 3B RGB ───► │ paint screen (r,g,b)       │
+└──────────────────────┘                └────────────────────────────┘
+```
+
+- Watch: `com.ilias.colorcast`, BLE flow in `src/pages/index/index.ux`
+  (scan → subscribe → connect → write), color cycle in `src/common/colorcast.js`
+- Phone: standard Android GATT server; no Xiaomi signature coupling (that's why
+  BLE instead of the official `@system.interconnect`, which requires matching
+  package names + re-signing with the Android app's key)
+- The S4 41mm has **no WiFi**, so the HTTP/fetch route was ruled out entirely
+
+## Watch app
+
+```text
+src/
+├── app.ux, manifest.json   # com.ilias.colorcast, feature system.bluetooth.ble
+├── common/colorcast.js     # color cycle + payload (3-byte RGB) + UUIDs
+└── pages/index/index.ux    # scan/connect UI, tap-to-cast, status text
+tests/colorcast.cjs         # cycle/payload/UUID tests (node tests/colorcast.cjs)
+```
+
+Build: `npm ci && npm run release` → `dist/com.ilias.colorcast.release.0.1.rpk`
+
+## Android companion (built on the Arch PC)
+
+Project: `~/android-build/colorcompanion` on `iliasmouhcine@192.168.1.30`
+(rsynced from `/tmp/colorcompanion`). Plain Java, no Android Studio needed.
+
+```bash
+cd ~/android-build/colorcompanion
+export JAVA_HOME=$HOME/android-build/jdk21        # system JDK 26 breaks AGP 8.5.2
+export ANDROID_HOME=$HOME/android-build/android-sdk
+~/android-build/gradle-8.9/bin/gradle assembleDebug --no-daemon
+# → app/build/outputs/apk/debug/app-debug.apk
+```
+
+On first launch it requests Bluetooth/Advertise/Connect + Location permissions,
+then advertises as **ILIAS-COLOR**. Tap the phone screen to hide the status text.
+Protocol: watch writes 3 bytes (R, G, B) to char `0000fee8-0000-1000-8000-00805f9b34fb`
+under service `0000fee7-0000-1000-8000-00805f9b34fb`.
+
+## Install & test
+
+1. Phone: install `ColorCompanion-0.1.apk`, open, grant permissions
+2. Watch: side-load the .rpk via AstroBox, open — it scans, auto-connects, and
+   casts RED on first contact
+3. Tap the watch disc to cycle colors
+
+If the watch shows "BLE unavailable" or never finds the phone, the firmware
+doesn't expose BLE to quick apps — report the on-screen status text.
+
+Releases: https://gitea.oimcloud.myaddr.tools/codex-bot/vela-colorcast
+(both the .rpk and the APK are attached to v0.1)