@oriro/orirocli 0.1.11 → 0.3.1

package/skills/craft/godmode/references/android-launch.md

@@ -1,680 +1,680 @@
-# Android Expert Reference — Build to Launch
-
-## Table of Contents
-
-1. [Android Project Fundamentals](#1-android-project-fundamentals)
-2. [Signing & Keystores](#2-signing--keystores)
-3. [Play App Signing](#3-play-app-signing)
-4. [SHA-1 Fingerprints & OAuth](#4-sha-1-fingerprints--oauth)
-5. [Play Console Deep Dive](#5-play-console-deep-dive)
-6. [Play Store Review & Policies](#6-play-store-review--policies)
-7. [App Bundle (AAB) vs APK](#7-app-bundle-aab-vs-apk)
-8. [FCM v1 API](#8-fcm-v1-api)
-9. [Google Sign-In Android](#9-google-sign-in-android)
-10. [Target SDK Requirements](#10-target-sdk-requirements)
-11. [Background Processing](#11-background-processing)
-12. [ProGuard / R8](#12-proguard--r8)
-13. [Firebase Android Integration](#13-firebase-android-integration)
-14. [Play Integrity API](#14-play-integrity-api)
-15. [Common Android Submission Failures](#15-common-android-submission-failures)
-
----
-
-## 1. Android Project Fundamentals
-
-**versionCode rules:**
-
-- Always an integer: 1, 2, 3...
-- Must STRICTLY increase with every upload to Play Console
-- Once uploaded, that versionCode can never be reused for that app
-- EAS manages this via `android.versionCode` in app.json
-
-**versionName rules:**
-
-- Human-readable string: "2.3.0", "2.3.1"
-- No strict requirement to increment (but should match marketing version)
-- Shown to users in Play Store
-
-**<project> Android current state:**
-
-- versionCode 14 / v2.3.0 — under Play Store review
-- versionCode 10 — currently active on devices
-- Next build: versionCode 15 / v2.4.0
-
-**Package name:** `com.<project>.shield` — permanent, never changes after first upload.
-Changing package name = entirely new app listing with zero install base.
-
-**Minimum SDK targets (2026):**
-
-- `minSdkVersion`: 21 (Android 5.0) — covers 99%+ of active devices
-- `targetSdkVersion`: 34 (Android 14) — **required by Google Play as of August 2024**
-- `compileSdkVersion`: 35 (Android 15) — use latest
-
-**Kotlin 2.0 highlights:**
-
-- K2 compiler: 2x faster compilation
-- `data class` copy with named arguments required
-- Smart casts improved across function boundaries
-- Compose: stable with Kotlin 2.0
-
----
-
-## 2. Signing & Keystores
-
-**Upload key vs App signing key:**
-With Play App Signing (mandatory for AAB):
-
-- **Upload key:** Used to sign AAB before uploading. Lives on your machine / EAS.
-- **App signing key:** Managed by Google. Applied to the final APK delivered to devices.
-- If you lose your upload key, you can register a new one in Play Console.
-- The SHA-1 that matters for Google Sign-In is the **App signing key** SHA-1 (Google manages this).
-
-**EAS manages signing automatically:**
-
-- EAS generates and stores your upload keystore
-- View keystore details: `eas credentials`
-- SHA-1 of upload key (dev): `D6:04:59:BE:DC:0C:BC:0E:85:00:23:CA:A4:2B:F7:BE:1C:5D:C1:E4`
-- SHA-1 of production key (Play App Signing): `41:35:AF:FE:B8:FE:BE:F9:DD:77:B4:61:05:BC:DA:7A:49:FC:F6:2B`
-
-**Generating a keystore manually (if needed):**
-
-```bash
-keytool -genkeypair -v \
-  -storetype PKCS12 \
-  -keystore <project>-upload-key.jks \
-  -alias <project> \
-  -keyalg RSA \
-  -keysize 2048 \
-  -validity 10000
-```
-
-**Getting SHA-1 from keystore:**
-
-```bash
-keytool -list -v \
-  -keystore <project>-upload-key.jks \
-  -alias <project>
-```
-
-**CRITICAL:** Back up your keystore file + password + alias + alias password.
-Without these you cannot update your app (you lose upload key recovery option).
-EAS stores keystores in their secure vault — managed builds are backed up.
-
----
-
-## 3. Play App Signing
-
-**Mandatory since August 2021** for new apps using AAB format.
-
-**Flow:**
-
-```
-You sign AAB with upload key
-→ Upload to Play Console
-→ Google verifies your signature
-→ Google re-signs with app signing key
-→ Distributed to users signed with Google's key
-```
-
-**Finding your App Signing Certificate SHA-1 (for OAuth):**
-
-1. Play Console → Release → Setup → App signing
-2. "App signing key certificate" section → SHA-1 certificate fingerprint
-3. This is the value that goes into Google Cloud Console / Firebase for production OAuth
-
-**<project> App Signing Key SHA-1:**
-`41:35:AF:FE:B8:FE:BE:F9:DD:77:B4:61:05:BC:DA:7A:49:FC:F6:2B`
-
-**Upload key reset (if lost):**
-
-1. Play Console → App → Setup → App signing
-2. Request upload key reset
-3. Generate new keystore, sign a new AAB
-4. Submit with new AAB — Google verifies identity via Play Developer account
-
----
-
-## 4. SHA-1 Fingerprints & OAuth
-
-**Two SHA-1 fingerprints for <project> Android:**
-
-1. **Dev SHA-1** (for debug builds and EAS development profile):
-   `D6:04:59:BE:DC:0C:BC:0E:85:00:23:CA:A4:2B:F7:BE:1C:5D:C1:E4`
-   → Add to Firebase Android app → google-services.json regenerated
-
-2. **Production SHA-1** (Play App Signing key — for Play Store builds):
-   `41:35:AF:FE:B8:FE:BE:F9:DD:77:B4:61:05:BC:DA:7A:49:FC:F6:2B`
-   → Add to Firebase Android app → google-services.json regenerated
-
-**Both SHA-1s must be registered in Firebase** for Google Sign-In to work across dev and production builds.
-
-**Firebase Console → Project Settings → Your apps → Android app:**
-
-- Add both SHA-1 fingerprints
-- Download updated google-services.json
-- Commit to repo root
-
-**OAuth flow with SHA-1:**
-Android Google Sign-In verifies the APK signing certificate at runtime.
-If the SHA-1 of the signing cert doesn't match what's registered in Firebase/OAuth Console,
-sign-in fails with `DEVELOPER_ERROR` (error code 10).
-
-**Error code 10 in Google Sign-In = SHA-1 mismatch.** Always the first thing to check.
-
-**Firebase OAuth client ID for Android:**
-`929418470411-ipdh7o4dp8fijjm7vbcmk43u03nnf1s7.apps.googleusercontent.com`
-
----
-
-## 5. Play Console Deep Dive
-
-**Account:** <email>
-**App:** <project> Shield · Package: com.<project>.shield
-**App ID:** 6099591004492585106
-
-**Track types:**
-| Track | Description | Review required |
-|-------|-------------|-----------------|
-| Internal testing | Up to 100 testers (by email) | No review, available in minutes |
-| Closed testing (Alpha) | Up to ~thousand testers | Brief review (~hours) |
-| Open testing (Beta) | Unlimited testers, opt-in | Brief review |
-| Production | All users | Full review (~days) |
-
-**Staged rollout:**
-
-- Roll out to 1%, 5%, 10%, 20%, 50%, 100% of users
-- Monitor crash rate and ANR rate before expanding
-- Can halt rollout if issues detected
-- <project>: start at 20% for new releases until stable
-
-**Play Console review timeline:**
-
-- Internal testing: minutes (no review)
-- Closed/Open testing: a few hours to 1 day
-- Production first release: 1-3 business days
-- Production updates for established apps: hours to 1 day
-- Post-rejection resubmission: same timeline
-
-**Policy dashboard:** Play Console → Policy status → Review violations
-**Pre-launch reports:** Automated Firebase Test Lab tests run on your AAB
-**Android vitals:** Crash rate, ANR rate, battery, permissions
-
-**AAB upload steps:**
-
-1. Play Console → App → Release → Closed testing (or Internal testing)
-2. Create new release
-3. Upload AAB file
-4. Fill "What's new in this release"
-5. Review release → Save → Start rollout
-
-**Version code error on upload:**
-
-> "Version code X has already been used. Try another version code."
-> Fix: increment versionCode in app.json and rebuild.
-
----
-
-## 6. Play Store Review & Policies
-
-**Critical policies for <project> (financial app):**
-
-- **Financial services policy:** Apps offering banking/financial services must comply with local laws, display required disclosures, and not mislead users about financial products.
-- **Personal data:** Declare all data collection in the Data Safety section.
-- **Sensitive permissions:** CAMERA, CONTACTS, LOCATION, READ_CALL_LOG require prominent disclosure at runtime before requesting.
-
-**Data Safety section (required since 2022):**
-
-- Must declare all data types collected, whether shared with third parties, whether data can be deleted by user
-- <project> data types: Name, Email, Phone number, Financial info (account numbers), Device identifiers
-- Fill in Play Console → App content → Data safety
-
-**Target audience:** If any content could appeal to children, must comply with Families Policy.
-<project> target: adults only → confirm in Play Console → App content → Target audience.
-
-**POST_NOTIFICATIONS permission (Android 13+):**
-Must request at runtime — cannot assume it's granted.
-
-```kotlin
-if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
-  ActivityCompat.requestPermissions(
-    this, arrayOf(Manifest.permission.POST_NOTIFICATIONS), 1)
-}
-```
-
-In Expo: `expo-notifications` handles this automatically.
-
-**Permission best practices:**
-
-- Request permissions at the moment they're needed (contextual)
-- Never request all permissions at app launch
-- Provide rationale before requesting (especially for sensitive permissions)
-- Handle denial gracefully
-
-**Common rejection reasons:**
-
-- Missing privacy policy (must be accessible in-app AND in store listing)
-- Missing data safety declaration
-- Misleading app description
-- Screenshot doesn't match actual app UI
-- App requests permissions not needed for stated functionality
-- Financial claims not substantiated (e.g., "guaranteed fraud protection")
-- App crashes during Play review testing
-
----
-
-## 7. App Bundle (AAB) vs APK
-
-**Always use AAB for Play Store.** APKs are no longer accepted for new apps.
-
-**AAB benefits:**
-
-- Google optimizes delivery per device (only relevant code/resources)
-- Smaller install size for users (20-50% reduction)
-- Required for Play App Signing
-
-**AAB structure:**
-
-- `base/` — main app module
-- `feature/` — optional dynamic feature modules
-- Resources split by density, ABI, language
-
-**EAS produces AAB** for the `production` profile automatically.
-EAS produces APK for `preview` profile (for direct installation without Play Store).
-
-**Local build (not EAS):**
-
-```bash
-cd android
-./gradlew bundleRelease
-# Output: app/build/outputs/bundle/release/app-release.aab
-```
-
----
-
-## 8. FCM v1 API
-
-**Legacy HTTP API deprecated July 2024 — use v1 API only.**
-
-**FCM v1 endpoint:**
-`POST https://fcm.googleapis.com/v1/projects/{project_id}/messages:send`
-
-**Auth:** OAuth 2.0 Bearer token using service account key (FIREBASE_SERVICE_ACCOUNT_KEY in GCP Secret Manager)
-
-**Message structure (v1):**
-
-```json
-{
-  "message": {
-    "token": "device_fcm_token",
-    "notification": {
-      "title": "ACH Transfer Challenge",
-      "body": "Tap the matching number"
-    },
-    "data": {
-      "type": "ach_challenge",
-      "challengeId": "uuid",
-      "options": "[\"3\",\"7\",\"9\"]"
-    },
-    "android": {
-      "priority": "high",
-      "notification": {
-        "channel_id": "ach_challenges",
-        "sound": "default"
-      }
-    },
-    "apns": {
-      "headers": { "apns-priority": "10" },
-      "payload": {
-        "aps": {
-          "sound": "default",
-          "badge": 1,
-          "content-available": 1
-        }
-      }
-    }
-  }
-}
-```
-
-**Android notification channels (required Android 8.0+):**
-Create channels at app startup:
-
-```kotlin
-val channel = NotificationChannel(
-  "ach_challenges",
-  "ACH Challenges",
-  NotificationManager.IMPORTANCE_HIGH
-).apply {
-  description = "ACH transfer challenge notifications"
-}
-val notificationManager = getSystemService(NotificationManager::class.java)
-notificationManager.createNotificationChannel(channel)
-```
-
-In Expo: configure in `app.json`:
-
-```json
-{
-  "expo": {
-    "android": {
-      "googleServicesFile": "./google-services.json"
-    },
-    "plugins": [
-      [
-        "expo-notifications",
-        {
-          "androidCollapsedTitle": "<project>",
-          "channels": [
-            {
-              "name": "ach_challenges",
-              "importance": "max",
-              "vibrationPattern": [0, 250, 250, 250]
-            }
-          ]
-        }
-      ]
-    ]
-  }
-}
-```
-
-**Sending FCM from Next.js backend:**
-
-```typescript
-import { GoogleAuth } from "google-auth-library";
-
-async function sendFCMNotification(token: string, data: object) {
-  const auth = new GoogleAuth({
-    scopes: ["https://www.googleapis.com/auth/firebase.messaging"],
-    credentials: JSON.parse(process.env.FIREBASE_SERVICE_ACCOUNT_KEY!),
-  });
-  const client = await auth.getClient();
-  const accessToken = await client.getAccessToken();
-
-  const response = await fetch(
-    `https://fcm.googleapis.com/v1/projects/<gcp-project>-a98aa/messages:send`,
-    {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${accessToken.token}`,
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({ message: { token, ...data } }),
-    },
-  );
-  return response.json();
-}
-```
-
----
-
-## 9. Google Sign-In Android
-
-**Error codes:**
-| Code | Meaning | Fix |
-|------|---------|-----|
-| 10 (DEVELOPER_ERROR) | SHA-1 mismatch | Add both dev + prod SHA-1 to Firebase; download new google-services.json |
-| 12500 | Sign-in failed | Check SHA-1 and OAuth client configuration |
-| 12501 | Sign-in cancelled | User dismissed |
-| 12502 | Sign-in currently in progress | Deduplicate calls |
-| 7 | NETWORK_ERROR | No internet connection |
-
-**SHA-1 is the #1 cause of DEVELOPER_ERROR (code 10).**
-
-Diagnosis: `adb logcat | grep "Google Sign-In"` — look for "SHA-1 not registered"
-
-**Expo/React Native Google Sign-In setup:**
-
-```json
-// app.json
-{
-  "expo": {
-    "plugins": [
-      [
-        "@react-native-google-signin/google-signin",
-        {
-          "iosUrlScheme": "com.googleusercontent.apps.929418470411-XXXXX"
-        }
-      ]
-    ]
-  }
-}
-```
-
-```typescript
-import { GoogleSignin } from "@react-native-google-signin/google-signin";
-
-GoogleSignin.configure({
-  webClientId: "WEB_CLIENT_ID.apps.googleusercontent.com", // from Firebase Console
-  offlineAccess: true,
-});
-```
-
-**webClientId = Web client OAuth client ID**, NOT Android client ID.
-Find in Firebase Console → Authentication → Sign-in method → Google → Web SDK configuration.
-
----
-
-## 10. Target SDK Requirements
-
-**Google Play enforcement schedule:**
-| Date | Requirement |
-|------|-------------|
-| August 2024 | New apps: targetSdkVersion ≥ 34 |
-| November 2024 | Existing apps updates: targetSdkVersion ≥ 34 |
-| 2025+ | ≥ 35 for new apps (Android 15) |
-
-**Android 14 (API 34) behavior changes affecting <project>:**
-
-- Foreground service types required (specify `android:foregroundServiceType`)
-- `ACTION_SCHEDULE_EXACT_ALARM` permission requires user opt-in
-- Photos/Media permissions split (partial access option)
-- Health Connect for health data
-
-**Android 15 (API 35) behavior changes:**
-
-- Edge-to-edge display enforcement
-- Health Connect permissions more granular
-- Predictive back gesture default on
-
-**In Expo (SDK 54), targetSdkVersion is set automatically.**
-Verify in `android/build.gradle` (ejected) or let EAS manage it.
-
----
-
-## 11. Background Processing
-
-**WorkManager (recommended for most background work):**
-
-```kotlin
-// Kotlin
-val workRequest = PeriodicWorkRequestBuilder<SyncWorker>(15, TimeUnit.MINUTES)
-  .setConstraints(Constraints.Builder()
-    .setRequiredNetworkType(NetworkType.CONNECTED)
-    .build())
-  .build()
-WorkManager.getInstance(context).enqueueUniquePeriodicWork(
-  "sync_guardian", ExistingPeriodicWorkPolicy.KEEP, workRequest)
-```
-
-In Expo/React Native: `expo-background-fetch` wraps this.
-
-**Doze mode and App Standby:**
-
-- Android 6+ throttles background processes when device is idle
-- FCM high-priority messages bypass Doze
-- WorkManager automatically handles Doze scheduling
-- Battery optimization exemption: can request user to exempt your app (not automatic)
-
-**Exact alarms (Android 12+):**
-
-- `SCHEDULE_EXACT_ALARM` permission required for exact alarms
-- Must show rationale and send user to settings if denied
-- For most use cases, use `setAndAllowWhileIdle` or WorkManager instead
-
----
-
-## 12. ProGuard / R8
-
-**R8 (default in modern Android) replaces ProGuard:**
-
-- Minification (removes unused code)
-- Obfuscation (renames classes/methods)
-- Optimization (inlines code, removes dead code)
-
-**Enable in build.gradle (enabled by default in release builds):**
-
-```groovy
-buildTypes {
-  release {
-    minifyEnabled true
-    shrinkResources true
-    proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
-  }
-}
-```
-
-**Critical keep rules for <project>:**
-
-```proguard
-# Keep Firebase classes
--keep class com.google.firebase.** { *; }
--keep class com.google.android.gms.** { *; }
-
-# Keep React Native
--keep class com.facebook.react.** { *; }
-
-# Keep Expo modules
--keep class expo.modules.** { *; }
-
-# Keep data classes used with JSON parsing
--keep class com.<project>.** { *; }
--keepclassmembers class ** {
-  @com.google.gson.annotations.SerializedName <fields>;
-}
-```
-
-**EAS handles ProGuard configuration** for managed workflow.
-For bare workflow: maintain `android/app/proguard-rules.pro`.
-
-**Debugging ProGuard issues:**
-
-- Use `mapping.txt` (generated with each release build) to de-obfuscate stack traces
-- Upload `mapping.txt` to Play Console for automatic de-obfuscation in Android Vitals
-- Firebase Crashlytics can also use mapping.txt for clear crash reports
-
----
-
-## 13. Firebase Android Integration
-
-**<project> Firebase:**
-
-- Project: <gcp-project>-a98aa
-- Android App ID: `1:929418470411:android:d88ddc48cf7656271d130e`
-- google-services.json: in repo root
-
-**google-services.json structure:**
-
-```json
-{
-  "project_info": {
-    "project_number": "929418470411",
-    "project_id": "<gcp-project>-a98aa"
-  },
-  "client": [{
-    "client_info": {
-      "mobilesdk_app_id": "1:929418470411:android:d88ddc48cf7656271d130e",
-      "android_client_info": {
-        "package_name": "com.<project>.shield"
-      }
-    },
-    "oauth_client": [{
-      "client_id": "929418470411-ipdh7o4dp8fijjm7vbcmk43u03nnf1s7.apps.googleusercontent.com",
-      "client_type": 1,
-      "android_info": {
-        "package_name": "com.<project>.shield",
-        "certificate_hash": "SHA-1 goes here"
-      }
-    }],
-    "services": {
-      "appinvite_service": { ... }
-    }
-  }]
-}
-```
-
-**After adding SHA-1 to Firebase → regenerate and re-download google-services.json.**
-The file must be in the root of the Expo project (not android/ — EAS copies it).
-
----
-
-## 14. Play Integrity API
-
-**Replaces SafetyNet (deprecated November 2024).**
-Use to verify: device integrity, app integrity, user license.
-
-**Verdict types:**
-
-- `MEETS_DEVICE_INTEGRITY` — device passes Android compatibility checks
-- `MEETS_BASIC_INTEGRITY` — passes basic Android security checks
-- `MEETS_STRONG_INTEGRITY` — certified hardware, bootloader locked
-
-**For <project> (fintech):** Check `MEETS_BASIC_INTEGRITY` minimum before allowing ACH transactions.
-
-**Implementation:**
-
-```kotlin
-val integrityManager = IntegrityManagerFactory.create(context)
-val nonce = generateSecureNonce() // backend-generated
-val integrityTokenResponse = integrityManager
-  .requestIntegrityToken(IntegrityTokenRequest.builder()
-    .setNonce(nonce)
-    .setCloudProjectNumber(929418470411L)
-    .build()).await()
-// Send token to backend for verification
-```
-
-**Backend verification:**
-POST to Google Play Integrity API → returns verdict.
-Server-to-server verification using service account.
-
----
-
-## 15. Common Android Submission Failures
-
-**"You uploaded an APK or Android App Bundle that is not zip aligned":**
-EAS handles this. If building locally: `zipalign -v -p 4 app.apk app-aligned.apk`
-
-**"Your app targets an old version of Android":**
-Increase `targetSdkVersion` to ≥ 34 in build.gradle or let EAS SDK 54 handle it.
-
-**"This release is not compliant with the EU User Choice Billing policy":**
-If operating in EU: must offer alternative billing options for subscriptions. <project>: not relevant for free app.
-
-**"You need to publish to a restricted track first":**
-For new accounts or apps: publish to internal testing first, then promote to production.
-
-**"Sensitive permissions not declared":**
-Add to Data Safety section in Play Console. Cannot just be in AndroidManifest.
-
-**"Multiple DEX files define the same class":**
-Dependency conflict in `build.gradle`. Use `exclude group:` to resolve.
-
-**"App crashes on launch during pre-launch testing":**
-Firebase Test Lab runs your app automatically. Common causes:
-
-- Missing network permissions
-- Missing google-services.json
-- Unhandled exception on main thread at startup
-- Native library not found
-
-**versionCode not incrementing:**
-Symptom: "Version code already uploaded"
-Fix: `android.versionCode: <current + 1>` in app.json → EAS rebuild
-
-**Google Sign-In fails in production but works in debug:**
-Production SHA-1 (`41:35:AF...`) not added to Firebase.
-Fix: Firebase Console → Android app → Add fingerprint → Download new google-services.json → commit → rebuild.
-
-**"This app has not been reviewed yet":**
-Normal for first closed testing release. Wait for review completion before promoting to production.
+# Android Expert Reference — Build to Launch
+
+## Table of Contents
+
+1. [Android Project Fundamentals](#1-android-project-fundamentals)
+2. [Signing & Keystores](#2-signing--keystores)
+3. [Play App Signing](#3-play-app-signing)
+4. [SHA-1 Fingerprints & OAuth](#4-sha-1-fingerprints--oauth)
+5. [Play Console Deep Dive](#5-play-console-deep-dive)
+6. [Play Store Review & Policies](#6-play-store-review--policies)
+7. [App Bundle (AAB) vs APK](#7-app-bundle-aab-vs-apk)
+8. [FCM v1 API](#8-fcm-v1-api)
+9. [Google Sign-In Android](#9-google-sign-in-android)
+10. [Target SDK Requirements](#10-target-sdk-requirements)
+11. [Background Processing](#11-background-processing)
+12. [ProGuard / R8](#12-proguard--r8)
+13. [Firebase Android Integration](#13-firebase-android-integration)
+14. [Play Integrity API](#14-play-integrity-api)
+15. [Common Android Submission Failures](#15-common-android-submission-failures)
+
+---
+
+## 1. Android Project Fundamentals
+
+**versionCode rules:**
+
+- Always an integer: 1, 2, 3...
+- Must STRICTLY increase with every upload to Play Console
+- Once uploaded, that versionCode can never be reused for that app
+- EAS manages this via `android.versionCode` in app.json
+
+**versionName rules:**
+
+- Human-readable string: "2.3.0", "2.3.1"
+- No strict requirement to increment (but should match marketing version)
+- Shown to users in Play Store
+
+**<project> Android current state:**
+
+- versionCode 14 / v2.3.0 — under Play Store review
+- versionCode 10 — currently active on devices
+- Next build: versionCode 15 / v2.4.0
+
+**Package name:** `com.<project>.shield` — permanent, never changes after first upload.
+Changing package name = entirely new app listing with zero install base.
+
+**Minimum SDK targets (2026):**
+
+- `minSdkVersion`: 21 (Android 5.0) — covers 99%+ of active devices
+- `targetSdkVersion`: 34 (Android 14) — **required by Google Play as of August 2024**
+- `compileSdkVersion`: 35 (Android 15) — use latest
+
+**Kotlin 2.0 highlights:**
+
+- K2 compiler: 2x faster compilation
+- `data class` copy with named arguments required
+- Smart casts improved across function boundaries
+- Compose: stable with Kotlin 2.0
+
+---
+
+## 2. Signing & Keystores
+
+**Upload key vs App signing key:**
+With Play App Signing (mandatory for AAB):
+
+- **Upload key:** Used to sign AAB before uploading. Lives on your machine / EAS.
+- **App signing key:** Managed by Google. Applied to the final APK delivered to devices.
+- If you lose your upload key, you can register a new one in Play Console.
+- The SHA-1 that matters for Google Sign-In is the **App signing key** SHA-1 (Google manages this).
+
+**EAS manages signing automatically:**
+
+- EAS generates and stores your upload keystore
+- View keystore details: `eas credentials`
+- SHA-1 of upload key (dev): `D6:04:59:BE:DC:0C:BC:0E:85:00:23:CA:A4:2B:F7:BE:1C:5D:C1:E4`
+- SHA-1 of production key (Play App Signing): `41:35:AF:FE:B8:FE:BE:F9:DD:77:B4:61:05:BC:DA:7A:49:FC:F6:2B`
+
+**Generating a keystore manually (if needed):**
+
+```bash
+keytool -genkeypair -v \
+  -storetype PKCS12 \
+  -keystore <project>-upload-key.jks \
+  -alias <project> \
+  -keyalg RSA \
+  -keysize 2048 \
+  -validity 10000
+```
+
+**Getting SHA-1 from keystore:**
+
+```bash
+keytool -list -v \
+  -keystore <project>-upload-key.jks \
+  -alias <project>
+```
+
+**CRITICAL:** Back up your keystore file + password + alias + alias password.
+Without these you cannot update your app (you lose upload key recovery option).
+EAS stores keystores in their secure vault — managed builds are backed up.
+
+---
+
+## 3. Play App Signing
+
+**Mandatory since August 2021** for new apps using AAB format.
+
+**Flow:**
+
+```
+You sign AAB with upload key
+→ Upload to Play Console
+→ Google verifies your signature
+→ Google re-signs with app signing key
+→ Distributed to users signed with Google's key
+```
+
+**Finding your App Signing Certificate SHA-1 (for OAuth):**
+
+1. Play Console → Release → Setup → App signing
+2. "App signing key certificate" section → SHA-1 certificate fingerprint
+3. This is the value that goes into Google Cloud Console / Firebase for production OAuth
+
+**<project> App Signing Key SHA-1:**
+`41:35:AF:FE:B8:FE:BE:F9:DD:77:B4:61:05:BC:DA:7A:49:FC:F6:2B`
+
+**Upload key reset (if lost):**
+
+1. Play Console → App → Setup → App signing
+2. Request upload key reset
+3. Generate new keystore, sign a new AAB
+4. Submit with new AAB — Google verifies identity via Play Developer account
+
+---
+
+## 4. SHA-1 Fingerprints & OAuth
+
+**Two SHA-1 fingerprints for <project> Android:**
+
+1. **Dev SHA-1** (for debug builds and EAS development profile):
+   `D6:04:59:BE:DC:0C:BC:0E:85:00:23:CA:A4:2B:F7:BE:1C:5D:C1:E4`
+   → Add to Firebase Android app → google-services.json regenerated
+
+2. **Production SHA-1** (Play App Signing key — for Play Store builds):
+   `41:35:AF:FE:B8:FE:BE:F9:DD:77:B4:61:05:BC:DA:7A:49:FC:F6:2B`
+   → Add to Firebase Android app → google-services.json regenerated
+
+**Both SHA-1s must be registered in Firebase** for Google Sign-In to work across dev and production builds.
+
+**Firebase Console → Project Settings → Your apps → Android app:**
+
+- Add both SHA-1 fingerprints
+- Download updated google-services.json
+- Commit to repo root
+
+**OAuth flow with SHA-1:**
+Android Google Sign-In verifies the APK signing certificate at runtime.
+If the SHA-1 of the signing cert doesn't match what's registered in Firebase/OAuth Console,
+sign-in fails with `DEVELOPER_ERROR` (error code 10).
+
+**Error code 10 in Google Sign-In = SHA-1 mismatch.** Always the first thing to check.
+
+**Firebase OAuth client ID for Android:**
+`929418470411-ipdh7o4dp8fijjm7vbcmk43u03nnf1s7.apps.googleusercontent.com`
+
+---
+
+## 5. Play Console Deep Dive
+
+**Account:** <email>
+**App:** <project> Shield · Package: com.<project>.shield
+**App ID:** 6099591004492585106
+
+**Track types:**
+| Track | Description | Review required |
+|-------|-------------|-----------------|
+| Internal testing | Up to 100 testers (by email) | No review, available in minutes |
+| Closed testing (Alpha) | Up to ~thousand testers | Brief review (~hours) |
+| Open testing (Beta) | Unlimited testers, opt-in | Brief review |
+| Production | All users | Full review (~days) |
+
+**Staged rollout:**
+
+- Roll out to 1%, 5%, 10%, 20%, 50%, 100% of users
+- Monitor crash rate and ANR rate before expanding
+- Can halt rollout if issues detected
+- <project>: start at 20% for new releases until stable
+
+**Play Console review timeline:**
+
+- Internal testing: minutes (no review)
+- Closed/Open testing: a few hours to 1 day
+- Production first release: 1-3 business days
+- Production updates for established apps: hours to 1 day
+- Post-rejection resubmission: same timeline
+
+**Policy dashboard:** Play Console → Policy status → Review violations
+**Pre-launch reports:** Automated Firebase Test Lab tests run on your AAB
+**Android vitals:** Crash rate, ANR rate, battery, permissions
+
+**AAB upload steps:**
+
+1. Play Console → App → Release → Closed testing (or Internal testing)
+2. Create new release
+3. Upload AAB file
+4. Fill "What's new in this release"
+5. Review release → Save → Start rollout
+
+**Version code error on upload:**
+
+> "Version code X has already been used. Try another version code."
+> Fix: increment versionCode in app.json and rebuild.
+
+---
+
+## 6. Play Store Review & Policies
+
+**Critical policies for <project> (financial app):**
+
+- **Financial services policy:** Apps offering banking/financial services must comply with local laws, display required disclosures, and not mislead users about financial products.
+- **Personal data:** Declare all data collection in the Data Safety section.
+- **Sensitive permissions:** CAMERA, CONTACTS, LOCATION, READ_CALL_LOG require prominent disclosure at runtime before requesting.
+
+**Data Safety section (required since 2022):**
+
+- Must declare all data types collected, whether shared with third parties, whether data can be deleted by user
+- <project> data types: Name, Email, Phone number, Financial info (account numbers), Device identifiers
+- Fill in Play Console → App content → Data safety
+
+**Target audience:** If any content could appeal to children, must comply with Families Policy.
+<project> target: adults only → confirm in Play Console → App content → Target audience.
+
+**POST_NOTIFICATIONS permission (Android 13+):**
+Must request at runtime — cannot assume it's granted.
+
+```kotlin
+if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+  ActivityCompat.requestPermissions(
+    this, arrayOf(Manifest.permission.POST_NOTIFICATIONS), 1)
+}
+```
+
+In Expo: `expo-notifications` handles this automatically.
+
+**Permission best practices:**
+
+- Request permissions at the moment they're needed (contextual)
+- Never request all permissions at app launch
+- Provide rationale before requesting (especially for sensitive permissions)
+- Handle denial gracefully
+
+**Common rejection reasons:**
+
+- Missing privacy policy (must be accessible in-app AND in store listing)
+- Missing data safety declaration
+- Misleading app description
+- Screenshot doesn't match actual app UI
+- App requests permissions not needed for stated functionality
+- Financial claims not substantiated (e.g., "guaranteed fraud protection")
+- App crashes during Play review testing
+
+---
+
+## 7. App Bundle (AAB) vs APK
+
+**Always use AAB for Play Store.** APKs are no longer accepted for new apps.
+
+**AAB benefits:**
+
+- Google optimizes delivery per device (only relevant code/resources)
+- Smaller install size for users (20-50% reduction)
+- Required for Play App Signing
+
+**AAB structure:**
+
+- `base/` — main app module
+- `feature/` — optional dynamic feature modules
+- Resources split by density, ABI, language
+
+**EAS produces AAB** for the `production` profile automatically.
+EAS produces APK for `preview` profile (for direct installation without Play Store).
+
+**Local build (not EAS):**
+
+```bash
+cd android
+./gradlew bundleRelease
+# Output: app/build/outputs/bundle/release/app-release.aab
+```
+
+---
+
+## 8. FCM v1 API
+
+**Legacy HTTP API deprecated July 2024 — use v1 API only.**
+
+**FCM v1 endpoint:**
+`POST https://fcm.googleapis.com/v1/projects/{project_id}/messages:send`
+
+**Auth:** OAuth 2.0 Bearer token using service account key (FIREBASE_SERVICE_ACCOUNT_KEY in GCP Secret Manager)
+
+**Message structure (v1):**
+
+```json
+{
+  "message": {
+    "token": "device_fcm_token",
+    "notification": {
+      "title": "ACH Transfer Challenge",
+      "body": "Tap the matching number"
+    },
+    "data": {
+      "type": "ach_challenge",
+      "challengeId": "uuid",
+      "options": "[\"3\",\"7\",\"9\"]"
+    },
+    "android": {
+      "priority": "high",
+      "notification": {
+        "channel_id": "ach_challenges",
+        "sound": "default"
+      }
+    },
+    "apns": {
+      "headers": { "apns-priority": "10" },
+      "payload": {
+        "aps": {
+          "sound": "default",
+          "badge": 1,
+          "content-available": 1
+        }
+      }
+    }
+  }
+}
+```
+
+**Android notification channels (required Android 8.0+):**
+Create channels at app startup:
+
+```kotlin
+val channel = NotificationChannel(
+  "ach_challenges",
+  "ACH Challenges",
+  NotificationManager.IMPORTANCE_HIGH
+).apply {
+  description = "ACH transfer challenge notifications"
+}
+val notificationManager = getSystemService(NotificationManager::class.java)
+notificationManager.createNotificationChannel(channel)
+```
+
+In Expo: configure in `app.json`:
+
+```json
+{
+  "expo": {
+    "android": {
+      "googleServicesFile": "./google-services.json"
+    },
+    "plugins": [
+      [
+        "expo-notifications",
+        {
+          "androidCollapsedTitle": "<project>",
+          "channels": [
+            {
+              "name": "ach_challenges",
+              "importance": "max",
+              "vibrationPattern": [0, 250, 250, 250]
+            }
+          ]
+        }
+      ]
+    ]
+  }
+}
+```
+
+**Sending FCM from Next.js backend:**
+
+```typescript
+import { GoogleAuth } from "google-auth-library";
+
+async function sendFCMNotification(token: string, data: object) {
+  const auth = new GoogleAuth({
+    scopes: ["https://www.googleapis.com/auth/firebase.messaging"],
+    credentials: JSON.parse(process.env.FIREBASE_SERVICE_ACCOUNT_KEY!),
+  });
+  const client = await auth.getClient();
+  const accessToken = await client.getAccessToken();
+
+  const response = await fetch(
+    `https://fcm.googleapis.com/v1/projects/<gcp-project>-a98aa/messages:send`,
+    {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${accessToken.token}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ message: { token, ...data } }),
+    },
+  );
+  return response.json();
+}
+```
+
+---
+
+## 9. Google Sign-In Android
+
+**Error codes:**
+| Code | Meaning | Fix |
+|------|---------|-----|
+| 10 (DEVELOPER_ERROR) | SHA-1 mismatch | Add both dev + prod SHA-1 to Firebase; download new google-services.json |
+| 12500 | Sign-in failed | Check SHA-1 and OAuth client configuration |
+| 12501 | Sign-in cancelled | User dismissed |
+| 12502 | Sign-in currently in progress | Deduplicate calls |
+| 7 | NETWORK_ERROR | No internet connection |
+
+**SHA-1 is the #1 cause of DEVELOPER_ERROR (code 10).**
+
+Diagnosis: `adb logcat | grep "Google Sign-In"` — look for "SHA-1 not registered"
+
+**Expo/React Native Google Sign-In setup:**
+
+```json
+// app.json
+{
+  "expo": {
+    "plugins": [
+      [
+        "@react-native-google-signin/google-signin",
+        {
+          "iosUrlScheme": "com.googleusercontent.apps.929418470411-XXXXX"
+        }
+      ]
+    ]
+  }
+}
+```
+
+```typescript
+import { GoogleSignin } from "@react-native-google-signin/google-signin";
+
+GoogleSignin.configure({
+  webClientId: "WEB_CLIENT_ID.apps.googleusercontent.com", // from Firebase Console
+  offlineAccess: true,
+});
+```
+
+**webClientId = Web client OAuth client ID**, NOT Android client ID.
+Find in Firebase Console → Authentication → Sign-in method → Google → Web SDK configuration.
+
+---
+
+## 10. Target SDK Requirements
+
+**Google Play enforcement schedule:**
+| Date | Requirement |
+|------|-------------|
+| August 2024 | New apps: targetSdkVersion ≥ 34 |
+| November 2024 | Existing apps updates: targetSdkVersion ≥ 34 |
+| 2025+ | ≥ 35 for new apps (Android 15) |
+
+**Android 14 (API 34) behavior changes affecting <project>:**
+
+- Foreground service types required (specify `android:foregroundServiceType`)
+- `ACTION_SCHEDULE_EXACT_ALARM` permission requires user opt-in
+- Photos/Media permissions split (partial access option)
+- Health Connect for health data
+
+**Android 15 (API 35) behavior changes:**
+
+- Edge-to-edge display enforcement
+- Health Connect permissions more granular
+- Predictive back gesture default on
+
+**In Expo (SDK 54), targetSdkVersion is set automatically.**
+Verify in `android/build.gradle` (ejected) or let EAS manage it.
+
+---
+
+## 11. Background Processing
+
+**WorkManager (recommended for most background work):**
+
+```kotlin
+// Kotlin
+val workRequest = PeriodicWorkRequestBuilder<SyncWorker>(15, TimeUnit.MINUTES)
+  .setConstraints(Constraints.Builder()
+    .setRequiredNetworkType(NetworkType.CONNECTED)
+    .build())
+  .build()
+WorkManager.getInstance(context).enqueueUniquePeriodicWork(
+  "sync_guardian", ExistingPeriodicWorkPolicy.KEEP, workRequest)
+```
+
+In Expo/React Native: `expo-background-fetch` wraps this.
+
+**Doze mode and App Standby:**
+
+- Android 6+ throttles background processes when device is idle
+- FCM high-priority messages bypass Doze
+- WorkManager automatically handles Doze scheduling
+- Battery optimization exemption: can request user to exempt your app (not automatic)
+
+**Exact alarms (Android 12+):**
+
+- `SCHEDULE_EXACT_ALARM` permission required for exact alarms
+- Must show rationale and send user to settings if denied
+- For most use cases, use `setAndAllowWhileIdle` or WorkManager instead
+
+---
+
+## 12. ProGuard / R8
+
+**R8 (default in modern Android) replaces ProGuard:**
+
+- Minification (removes unused code)
+- Obfuscation (renames classes/methods)
+- Optimization (inlines code, removes dead code)
+
+**Enable in build.gradle (enabled by default in release builds):**
+
+```groovy
+buildTypes {
+  release {
+    minifyEnabled true
+    shrinkResources true
+    proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+  }
+}
+```
+
+**Critical keep rules for <project>:**
+
+```proguard
+# Keep Firebase classes
+-keep class com.google.firebase.** { *; }
+-keep class com.google.android.gms.** { *; }
+
+# Keep React Native
+-keep class com.facebook.react.** { *; }
+
+# Keep Expo modules
+-keep class expo.modules.** { *; }
+
+# Keep data classes used with JSON parsing
+-keep class com.<project>.** { *; }
+-keepclassmembers class ** {
+  @com.google.gson.annotations.SerializedName <fields>;
+}
+```
+
+**EAS handles ProGuard configuration** for managed workflow.
+For bare workflow: maintain `android/app/proguard-rules.pro`.
+
+**Debugging ProGuard issues:**
+
+- Use `mapping.txt` (generated with each release build) to de-obfuscate stack traces
+- Upload `mapping.txt` to Play Console for automatic de-obfuscation in Android Vitals
+- Firebase Crashlytics can also use mapping.txt for clear crash reports
+
+---
+
+## 13. Firebase Android Integration
+
+**<project> Firebase:**
+
+- Project: <gcp-project>-a98aa
+- Android App ID: `1:929418470411:android:d88ddc48cf7656271d130e`
+- google-services.json: in repo root
+
+**google-services.json structure:**
+
+```json
+{
+  "project_info": {
+    "project_number": "929418470411",
+    "project_id": "<gcp-project>-a98aa"
+  },
+  "client": [{
+    "client_info": {
+      "mobilesdk_app_id": "1:929418470411:android:d88ddc48cf7656271d130e",
+      "android_client_info": {
+        "package_name": "com.<project>.shield"
+      }
+    },
+    "oauth_client": [{
+      "client_id": "929418470411-ipdh7o4dp8fijjm7vbcmk43u03nnf1s7.apps.googleusercontent.com",
+      "client_type": 1,
+      "android_info": {
+        "package_name": "com.<project>.shield",
+        "certificate_hash": "SHA-1 goes here"
+      }
+    }],
+    "services": {
+      "appinvite_service": { ... }
+    }
+  }]
+}
+```
+
+**After adding SHA-1 to Firebase → regenerate and re-download google-services.json.**
+The file must be in the root of the Expo project (not android/ — EAS copies it).
+
+---
+
+## 14. Play Integrity API
+
+**Replaces SafetyNet (deprecated November 2024).**
+Use to verify: device integrity, app integrity, user license.
+
+**Verdict types:**
+
+- `MEETS_DEVICE_INTEGRITY` — device passes Android compatibility checks
+- `MEETS_BASIC_INTEGRITY` — passes basic Android security checks
+- `MEETS_STRONG_INTEGRITY` — certified hardware, bootloader locked
+
+**For <project> (fintech):** Check `MEETS_BASIC_INTEGRITY` minimum before allowing ACH transactions.
+
+**Implementation:**
+
+```kotlin
+val integrityManager = IntegrityManagerFactory.create(context)
+val nonce = generateSecureNonce() // backend-generated
+val integrityTokenResponse = integrityManager
+  .requestIntegrityToken(IntegrityTokenRequest.builder()
+    .setNonce(nonce)
+    .setCloudProjectNumber(929418470411L)
+    .build()).await()
+// Send token to backend for verification
+```
+
+**Backend verification:**
+POST to Google Play Integrity API → returns verdict.
+Server-to-server verification using service account.
+
+---
+
+## 15. Common Android Submission Failures
+
+**"You uploaded an APK or Android App Bundle that is not zip aligned":**
+EAS handles this. If building locally: `zipalign -v -p 4 app.apk app-aligned.apk`
+
+**"Your app targets an old version of Android":**
+Increase `targetSdkVersion` to ≥ 34 in build.gradle or let EAS SDK 54 handle it.
+
+**"This release is not compliant with the EU User Choice Billing policy":**
+If operating in EU: must offer alternative billing options for subscriptions. <project>: not relevant for free app.
+
+**"You need to publish to a restricted track first":**
+For new accounts or apps: publish to internal testing first, then promote to production.
+
+**"Sensitive permissions not declared":**
+Add to Data Safety section in Play Console. Cannot just be in AndroidManifest.
+
+**"Multiple DEX files define the same class":**
+Dependency conflict in `build.gradle`. Use `exclude group:` to resolve.
+
+**"App crashes on launch during pre-launch testing":**
+Firebase Test Lab runs your app automatically. Common causes:
+
+- Missing network permissions
+- Missing google-services.json
+- Unhandled exception on main thread at startup
+- Native library not found
+
+**versionCode not incrementing:**
+Symptom: "Version code already uploaded"
+Fix: `android.versionCode: <current + 1>` in app.json → EAS rebuild
+
+**Google Sign-In fails in production but works in debug:**
+Production SHA-1 (`41:35:AF...`) not added to Firebase.
+Fix: Firebase Console → Android app → Add fingerprint → Download new google-services.json → commit → rebuild.
+
+**"This app has not been reviewed yet":**
+Normal for first closed testing release. Wait for review completion before promoting to production.