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

docs/ADR-001-architecture.md

@@ -0,0 +1,34 @@
+# ADR-001: Architecture for native Hesychia Android
+
+- **Status:** Accepted (spike default)
+- **Date:** 2026-08-05
+- **Context:** Epic [chat_web_app#111](https://git.aimloperations.com/ai_ml_operations/chat_web_app/issues/111)
+
+## Decision
+
+Ship a **Kotlin + Jetpack Compose + Material 3** client in `chat_android`, single `:app` module for v1.
+
+| Concern | Choice |
+|---------|--------|
+| UI | Jetpack Compose + Material 3 (`HesychiaTheme` from design tokens) |
+| DI | Hilt |
+| REST | Retrofit + OkHttp + kotlinx.serialization |
+| WebSocket | OkHttp WebSocket (parity with FE `WebSocketContext`) — Workstream D |
+| Session | DataStore Preferences (JWT access/refresh); migrate to EncryptedSharedPreferences if threat model requires |
+| Nav | Navigation Compose |
+| IAP | RevenueCat Android SDK (`com.revenuecat.purchases`) |
+| Flavors | `prod` / `beta` (env dimension); debug adds `.debug` applicationIdSuffix |
+| Min / target SDK | 23 / 35 (match Capacitor shell) |
+| Application id | **`ai.hesychia.chat`** (same as Capacitor) — see ADR-002 |
+
+## Alternatives considered
+
+1. **Keep Capacitor only** — lower eng cost short-term; WebView UX / IAP friction remain.
+2. **Flutter** — one codebase for Android+iOS, but new stack vs existing Kotlin skill + no shared UI with React web.
+3. **Multi-module now** — premature until chat + auth + billing vertical slices exist.
+
+## Consequences
+
+- Feature modules (`:feature:auth`, `:feature:chat`, `:core:network`) deferred until MVP vertical slice ships.
+- iOS twin is a **separate epic / repo** (SwiftUI), not Flutter.
+- Visual parity bar: **brand + layout rhythm**, not pixel-perfect MUI clones.

docs/ADR-002-capacitor-coexistence.md

@@ -0,0 +1,30 @@
+# ADR-002: Capacitor coexistence & Play application id
+
+- **Status:** Accepted (initial)
+- **Date:** 2026-08-05
+- **Context:** Epic chat_web_app#111 — package-name continuity matters for IAP + reviews.
+
+## Decision
+
+1. Native app **`applicationId` = `ai.hesychia.chat`** (same as Capacitor / `llm-fe/android`).
+2. Until native internal testing replaces Capacitor on Play:
+   - Capacitor remains interim Play track.
+   - Do **not** upload both Capacitor and native AABs under the same listing as competing “current” production binaries without a freeze plan.
+3. When native auth → chat → IAP path is green on internal testing:
+   - **Freeze** Capacitor Play uploads.
+   - Promote native AAB on the same listing (versionCode continues upward from Capacitor’s last upload).
+4. `beta` flavor uses `applicationIdSuffix = ".beta"` → `ai.hesychia.chat.beta` for side-by-side installs during development only (not the production listing).
+
+## Rationale
+
+Same application id preserves Play listing, reviews, and RevenueCat / Play Billing product bindings already tied to `ai.hesychia.chat`.
+
+## Rejected
+
+- New id (`ai.hesychia.chat.native`) then migrate users — splits listings, breaks IAP continuity, worse for reviews.
+
+## Open ops
+
+- Confirm last Capacitor `versionCode` before first native Play upload.
+- RevenueCat dashboard already includes package id `ai.hesychia.chat` (Capacitor path).
+- Capacitor shell in `llm-fe/android` stays for web mobile wrap until product sunsets it; document deprecation in `chat_web_app` when freeze date set.

docs/OPEN_QUESTIONS.md

@@ -0,0 +1,15 @@
+# Open questions
+
+1. **SSO redirect URIs** — which App Auth / Custom Tabs redirect URIs to register with Google / Microsoft + `chat_backend`?
+2. **Document storage on mobile** — still required for Play v1, or web-only?
+3. **Markdown strategy** — native Markwon/Coil vs small WebView islands for charts?
+4. **Analytics** — Tianji parity, Firebase, or none for native v1?
+5. **Push notifications** — defer confirmed?
+6. **Encrypted session storage** — DataStore OK for MVP, or EncryptedSharedPreferences required at launch?
+7. **Capacitor freeze date** — who owns Play Console cutover once native internal test passes?
+8. **JWT login field** — confirm backend `token/` expects `email` vs `username` (wire against live OpenAPI).
+9. **Cost estimate** — eng weeks for auth → chat → IAP after scaffolding (update epic AC #1).
+
+## Spike verdict (initial)
+
+**Proceed** with native Compose client. Capacitor remains interim Play track until native IAP path is proven (ADR-002). Rough order-of-magnitude after scaffold: **6–10 eng weeks** for auth + chat MVP + RevenueCat + store checklist (SSO + polish extra).

docs/SCREEN_INVENTORY.md

@@ -0,0 +1,36 @@
+# Screen inventory (mirror of llm-fe)
+
+Source: `chat_web_app/llm-fe/src/App.tsx` routes + key shells.
+
+| Web route | Native v1 | Priority | Notes |
+|-----------|-----------|----------|-------|
+| `/signin/` | SignIn | P0 | Email/password JWT (`POST token/`) |
+| `/signup/` | SignUp | P0 | After create → RevenueCat purchase (Workstream E) |
+| `/auth/callback/` | Deep link / Custom Tab return | P1 | Google / Microsoft SSO |
+| `/password_reset/` | Custom Tab + deep link | P1 | |
+| `/password_reset_confirmation/` | Deep link | P1 | |
+| `/set_password/` | Deep link | P2 | |
+| `/` (AsyncDashboard2) | Chat | P0 | Conversations list + detail + compose |
+| `/account/` | Account | P0 | Usage, theme, billing (RC), delete account |
+| `/billing/success` `/billing/cancel` | N/A on Play | — | Stripe web only |
+| `/document_storage` | Deferred | P2 | Confirm product need on mobile |
+| `/feedback/` | Deferred | P2 | |
+| `/analytics/` | Deferred / omit | P3 | Tianji subset TBD |
+| `/terms_of_service/` `/legal/terms-of-service` | Custom Tab to web | P1 | |
+| `/account-deletion/` | Custom Tab to public URL | P0 (store) | `https://hesychia.ai/account-deletion/` (#103) |
+| NotFound | System back / empty | — | |
+
+## Chat subflows (from AsyncDashboard2 / ConversationDetailCard)
+
+- Conversation list create / select / rename / delete
+- Message history load + pagination
+- Streaming tokens over WebSocket
+- Markdown / code / citations
+- Message actions (copy, regenerate, …) — product prune
+
+## Account subflows
+
+- Usage meters
+- Theme: dark mode + palette (`blue|green|purple|orange|red`)
+- Billing: subscribe / restore / manage (RevenueCat; badge `revenuecat` + `PLAY_STORE`)
+- Delete account → `DELETE /api/user/` + RC `logOut`