diff --git a/README.md b/README.md
index 28519aa..b6caada 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,51 @@
 # Fabric.Android
+
+A **Capacitor** Android shell that bundles the `Fabric.Frontend` SPA — the
+same self-contained strategy as `Fabric.Desktop`, so there is no separate
+mobile UI to maintain. It talks to the Center/Guild **backends** over HTTP
+(the Center base is set on the login screen, so a phone points at the host's
+LAN IP or a deployed URL, not `localhost`).
+
+- `appId` `ai.hangman.fabric`, app name **Fabric**
+- `androidScheme: http` + `usesCleartextTraffic` (HTTP backends)
+- Launcher icons = the Fabric mark (adaptive: green mark on black; legacy +
+  round) at all densities
+
+## How it works
+
+- `scripts/build-web.mjs` builds `Fabric.Frontend` and copies its bundle into
+  `www/`. Capacitor serves `www/` from `http://localhost` with SPA index
+  fallback, so the standard build + `BrowserRouter` work as-is.
+- The native project lives in `android/` (generated by `cap add android`,
+  committed). Build outputs, `www/`, `node_modules`, and `local.properties`
+  are git-ignored.
+
+## Prerequisites
+
+- Node, Android SDK, and a **real JDK 17+** (the system `java` may be a JRE
+  with no `javac`; Android Studio's bundled JBR works — point `JAVA_HOME` at
+  it). `android/local.properties` must contain `sdk.dir=<Android SDK path>`.
+
+## Build
+
+```bash
+npm install
+# build SPA -> www, cap sync, then Gradle:
+JAVA_HOME=<jdk> npm run apk:debug      # -> android/app/build/outputs/apk/debug/app-debug.apk
+JAVA_HOME=<jdk> npm run apk:release
+npm run sync                            # build:web + cap sync (no APK)
+npm run open                            # open in Android Studio
+```
+
+Install on a device/emulator:
+
+```bash
+adb install -r android/app/build/outputs/apk/debug/app-debug.apk
+```
+
+## Roadmap
+
+Foreground realtime (socket.io) works today. Background **push for the
+`wakeup` signal** (FCM + `@capacitor/push-notifications` + a server-side
+push sender) is the natural follow-up — currently `wakeup` is
+OpenClaw-plugin-only.