diff --git a/CLAUDE.md b/CLAUDE.md
index b55655d1..7199401f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -138,6 +138,45 @@ return <Text>{t('RoomSettings.some_key')}</Text>;
 - **@tanstack/react-query 5** — Data fetching
 - **@tanstack/react-virtual 3** — Virtual scrolling
 - **i18next 23 + react-i18next 15** — Localisation
+- **Capacitor 8.3** — Native Android wrapper
+- **@capacitor/browser 8.0** — External link handling in native
+
+## Android (Capacitor)
+
+**Requirements**: Node >=22, JDK 17+ (21 used), Android SDK with platform 36 + build-tools 36.0.0
+
+**Config**: `capacitor.config.ts` — `appId: chat.vojo.app`, `webDir: dist`
+
+**Android project**: `android/` — generated, `targetSdkVersion 36`, `compileSdkVersion 36`, `minSdkVersion 24`
+
+**Build scripts**:
+```bash
+npm run build:android:debug    # full chain: build → sync → debug APK
+npm run build:android:release  # full chain: build → sync → release APK
+npm run build:android:aab      # full chain: build → sync → release AAB
+npm run android:sync           # sync dist/ → android assets
+npm run android:apk:debug      # gradle debug build only
+```
+
+**APK output**: `android/app/build/outputs/apk/debug/app-debug.apk`
+
+**Version**: `versionCode` and `versionName` auto-derived from `package.json` version (major*1000000 + minor*1000 + patch)
+
+**Key architecture decisions**:
+- Bundled build (dist/ copied into APK), not remote WebView
+- Service Worker kept active — critical for authenticated Matrix media (MSC3916 / spec v1.11+). Do NOT disable. `resolveServiceWorkerRequests` default `true`.
+- Edge-to-edge via `EdgeToEdge.enable()` in `MainActivity.java` + `windowLayoutInDisplayCutoutMode: shortEdges`
+- External links opened via `@capacitor/browser` plugin (see `src/app/utils/capacitor.ts`)
+- `body` background-color bound to folds theme variable `var(--oq6d070)` for consistent safe-area coloring
+- Safe-area insets applied on `#root` (not `body`) so theme background extends behind system bars
+
+**VSCode tasks** (`.vscode/tasks.json`):
+- `Deploy to vojo.chat` (Ctrl+Shift+D) — web deploy
+- `Deploy to Android (ADB)` (Ctrl+Shift+A) — build + adb install
+
+**ADB wireless**: pair via `adb pair <ip>:<port> <code>`, connect via `adb connect <ip>:<port>`. Ports for pair and connect are different.
+
+**SDK location**: `/usr/lib/android-sdk`, also set in `android/local.properties`
 
 ## Matrix SDK Patterns