Add the native Hesychia Android client so the repo can build beyond the placeholder README.

README.md

@@ -1,2 +1,80 @@
-# chat_android
+# Hesychia Android (native)
 
+Kotlin + Jetpack Compose client for [Hesychia](https://hesychia.ai), reusing `chat_backend` APIs.
+
+Epic: [chat_web_app#111](https://git.aimloperations.com/ai_ml_operations/chat_web_app/issues/111)
+
+Capacitor WebView shell remains in `chat_web_app/llm-fe` as the interim Play track — see [docs/ADR-002-capacitor-coexistence.md](docs/ADR-002-capacitor-coexistence.md).
+
+## Stack
+
+- Kotlin, Jetpack Compose, Material 3
+- Hilt, Navigation Compose, DataStore
+- Retrofit + OkHttp (+ WebSocket next)
+- RevenueCat Android SDK (IAP Workstream E)
+- Min SDK 23 / target SDK 35
+- Application id: `ai.hesychia.chat`
+
+## Docs
+
+| Doc | Purpose |
+|-----|---------|
+| [ADR-001](docs/ADR-001-architecture.md) | Architecture choices |
+| [ADR-002](docs/ADR-002-capacitor-coexistence.md) | Play id + Capacitor sunset |
+| [SCREEN_INVENTORY](docs/SCREEN_INVENTORY.md) | Routes / flows to mirror |
+| [OPEN_QUESTIONS](docs/OPEN_QUESTIONS.md) | Spike leftovers |
+| [design-tokens/hesychia.tokens.json](design-tokens/hesychia.tokens.json) | Shared visual tokens |
+
+## Prerequisites
+
+- JDK 17+
+- Android SDK Platform 35 + build-tools
+- Android Studio (Ladybug+) recommended
+- Set `sdk.dir` in `local.properties` (gitignored), or open once in Android Studio
+
+```properties
+sdk.dir=/path/to/Android/Sdk
+```
+
+## Build
+
+```bash
+./gradlew :app:assembleProdDebug
+./gradlew :app:testProdDebugUnitTest
+# APK → app/build/outputs/apk/prod/debug/
+```
+
+Flavors:
+
+| Flavor | REST / WS | applicationId |
+|--------|-----------|---------------|
+| `prod` (default) | production `chatbackend.aimloperations.com` | `ai.hesychia.chat` (+ `.debug` for debug) |
+| `beta` | `beta.chatbackend.aimloperations.com` | `ai.hesychia.chat.beta` (+ `.debug`) |
+
+## Signing (release)
+
+Never commit keystores. Create `keystore.properties` (gitignored) at repo root:
+
+```properties
+storeFile=/absolute/path/to/aiml-chat-upload.jks
+storePassword=...
+keyAlias=aiml-chat-upload
+keyPassword=...
+```
+
+```bash
+./gradlew :app:bundleProdRelease
+```
+
+## Monetization
+
+Native Play uses **RevenueCat** only (no Stripe Checkout). Align with `chat_web_app/llm-fe/MONETIZATION.md`:
+
+- `appUserID` = Django user pk string
+- Provider badge: `revenuecat` + `PLAY_STORE`
+
+## Related repos
+
+- `chat_web_app` — product / Capacitor / design source
+- `chat_backend` — REST + WS + RevenueCat webhooks
+- Future: `chat_ios` (SwiftUI twin epic)