android-ai-skills 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.4.0](https://github.com/noloman/Android-AI-skills/compare/v1.3.0...v1.4.0) (2026-02-12)
+
+
+### Features
+
+* add 10 more cross-cutting skills (billing, Firebase, DI, networking, storage, auth, media, CI/CD, maps, ML) ([bb2990e](https://github.com/noloman/Android-AI-skills/commit/bb2990ebd9929d0c725c99c9cfcc94c88593b702))
+
 # [1.3.0](https://github.com/noloman/Android-AI-skills/compare/v1.2.0...v1.3.0) (2026-02-12)
 
 

package/README.md

@@ -55,6 +55,16 @@ These AI skills:
 - Standardize **build infrastructure** (version catalogs, convention plugins, modularization)
 - Govern **background work** (WorkManager, foreground services, notifications)
 - Guide **navigation** (type-safe routes, deep links, App Links)
+- Enforce **Play Billing** (subscriptions, server verification, purchase lifecycle)
+- Integrate **Firebase** (Auth, Firestore, Crashlytics, FCM, Remote Config)
+- Standardize **dependency injection** (Hilt scoping, multi-module DI, testing)
+- Govern **networking** (Retrofit, OkHttp, Ktor, caching, error handling)
+- Manage **local storage** (Room, DataStore, offline-first, encryption)
+- Secure **authentication** (Credential Manager, biometrics, token management)
+- Handle **media** (Media3, CameraX, image loading, audio focus)
+- Automate **CI/CD** (GitHub Actions, Fastlane, signing, Play Store deployment)
+- Guide **maps & location** (FusedLocationProvider, geofencing, permissions)
+- Enable **on-device ML** (ML Kit, TFLite, Gemini Nano, model management)
 - Scale from indie to enterprise
 - Adapt automatically (Enterprise Mode auto-detection)
 
@@ -124,6 +134,56 @@ flowchart LR
     C --- U
     D --- U
     E --- U
+
+    V[play-billing-best-practices]
+    C --- V
+    D --- V
+    E --- V
+
+    W[firebase-best-practices]
+    C --- W
+    D --- W
+    E --- W
+
+    X[android-dependency-injection]
+    C --- X
+    D --- X
+    E --- X
+
+    Y[android-networking]
+    C --- Y
+    D --- Y
+    E --- Y
+
+    Z[android-local-storage]
+    C --- Z
+    D --- Z
+    E --- Z
+
+    AA[android-auth-identity]
+    C --- AA
+    D --- AA
+    E --- AA
+
+    AB[android-media]
+    C --- AB
+    D --- AB
+    E --- AB
+
+    AC[android-ci-cd]
+    C --- AC
+    D --- AC
+    E --- AC
+
+    AD[android-maps-location]
+    C --- AD
+    D --- AD
+    E --- AD
+
+    AE[android-ml-ondevice]
+    C --- AE
+    D --- AE
+    E --- AE
 ```
 
 ---
@@ -304,6 +364,146 @@ Cross-cutting skill — type-safe routes, deep links, App Links, navigation patt
 
 ---
 
+### 13. play-billing-best-practices
+
+Cross-cutting skill — in-app purchases, subscriptions, server verification, testing.
+
+**Enforces:**
+- Server-side purchase verification — never trust client
+- Acknowledge all purchases within 3 days
+- Consume consumable purchases after delivery
+- Handle all BillingResponseCode values
+- Test with license testers on real devices
+- Handle pending purchases for slow payment methods
+
+---
+
+### 14. firebase-best-practices
+
+Cross-cutting skill — Auth, Firestore, Crashlytics, Remote Config, FCM, Analytics.
+
+**Enforces:**
+- Firebase BoM for consistent versions
+- Firestore security rules before production
+- No PII in Crashlytics logs
+- Respect user consent before Analytics collection
+- Handle FCM token rotation
+- Rate-limit Remote Config fetches
+
+---
+
+### 15. android-dependency-injection
+
+Cross-cutting skill — Hilt/Dagger setup, scoping, multi-module DI, testing.
+
+**Enforces:**
+- Hilt as default DI framework
+- Correct scoping (@Singleton, @ViewModelScoped)
+- Never inject Activity context into singletons
+- Constructor injection over field injection
+- @Binds for interface-to-implementation mapping
+- Focused modules per feature boundary
+
+---
+
+### 16. android-networking
+
+Cross-cutting skill — Retrofit, OkHttp, Ktor, caching, error handling, resilience.
+
+**Enforces:**
+- Suspend functions for all API calls
+- Explicit error handling for all HTTP codes
+- OkHttp interceptors for cross-cutting concerns
+- No request/response body logging in production
+- Token refresh in Authenticator
+- kotlinx.serialization or Moshi (not Gson)
+
+---
+
+### 17. android-local-storage
+
+Cross-cutting skill — Room, DataStore, offline-first architecture, caching, encryption.
+
+**Enforces:**
+- Room for relational data, DataStore for key-value
+- Export Room schemas and test all migrations
+- No database operations on main thread
+- Database as single source of truth
+- No sensitive data in unencrypted storage
+- Transactions for multi-table writes
+
+---
+
+### 18. android-auth-identity
+
+Cross-cutting skill — Credential Manager, biometrics, token management, session security.
+
+**Enforces:**
+- Credential Manager API for sign-in flows
+- Tokens in EncryptedSharedPreferences or Keystore
+- Transparent token refresh
+- BiometricPrompt (not FingerprintManager)
+- BIOMETRIC_STRONG for sensitive operations
+- Clear all credentials on logout
+
+---
+
+### 19. android-media
+
+Cross-cutting skill — Media3/ExoPlayer, CameraX, image loading, audio focus, PiP.
+
+**Enforces:**
+- Media3 for playback (not legacy ExoPlayer)
+- CameraX for camera (not Camera2 directly)
+- Coil or Glide for image loading
+- Audio focus management before playback
+- MediaSession for background playback
+- Lifecycle-aware resource release
+
+---
+
+### 20. android-ci-cd
+
+Cross-cutting skill — GitHub Actions, Fastlane, signing, Play Store deployment, build optimization.
+
+**Enforces:**
+- Never store signing keys in repository
+- Unit tests on every PR
+- Release AAB built in CI
+- Pin CI action versions to SHA hashes
+- Gradle build cache and configuration cache
+- Separate CI stages (lint → test → build → deploy)
+
+---
+
+### 21. android-maps-location
+
+Cross-cutting skill — Google Maps SDK, FusedLocationProvider, geofencing, permissions.
+
+**Enforces:**
+- FusedLocationProviderClient (not LocationManager)
+- Request only needed location accuracy
+- Remove location updates when not needed
+- Protect API keys with app restrictions
+- Foreground service for background location
+- Handle approximate vs precise location (API 31+)
+
+---
+
+### 22. android-ml-ondevice
+
+Cross-cutting skill — ML Kit, TensorFlow Lite, Gemini Nano, model management.
+
+**Enforces:**
+- ML Kit for common vision/NLP tasks
+- Run inference off main thread
+- Play Services-based models to reduce APK size
+- Validate model input/output shapes
+- Graceful fallback when models unavailable
+- Quantize models for size and performance
+
+---
+
 ## Enterprise Mode (Auto-Detection)
 
 Enterprise Mode activates automatically if the repository contains:
@@ -429,6 +629,16 @@ CLAUDE.md                                            # Claude Code
 .cursor/rules/android-build-infra.mdc
 .cursor/rules/android-background-work.mdc
 .cursor/rules/android-navigation-best-practices.mdc
+.cursor/rules/play-billing-best-practices.mdc
+.cursor/rules/firebase-best-practices.mdc
+.cursor/rules/android-dependency-injection.mdc
+.cursor/rules/android-networking.mdc
+.cursor/rules/android-local-storage.mdc
+.cursor/rules/android-auth-identity.mdc
+.cursor/rules/android-media.mdc
+.cursor/rules/android-ci-cd.mdc
+.cursor/rules/android-maps-location.mdc
+.cursor/rules/android-ml-ondevice.mdc
 .windsurfrules                                       # Windsurf
 .clinerules/compose-best-practices.md                # Cline (per skill)
 .clinerules/kmp-architecture-best-practices.md
@@ -442,6 +652,16 @@ CLAUDE.md                                            # Claude Code
 .clinerules/android-build-infra.md
 .clinerules/android-background-work.md
 .clinerules/android-navigation-best-practices.md
+.clinerules/play-billing-best-practices.md
+.clinerules/firebase-best-practices.md
+.clinerules/android-dependency-injection.md
+.clinerules/android-networking.md
+.clinerules/android-local-storage.md
+.clinerules/android-auth-identity.md
+.clinerules/android-media.md
+.clinerules/android-ci-cd.md
+.clinerules/android-maps-location.md
+.clinerules/android-ml-ondevice.md
 .aiassistant/rules/compose-best-practices.md         # JetBrains AI (per skill)
 .aiassistant/rules/kmp-architecture-best-practices.md
 .aiassistant/rules/compose-multiplatform-best-practices.md
@@ -454,6 +674,16 @@ CLAUDE.md                                            # Claude Code
 .aiassistant/rules/android-build-infra.md
 .aiassistant/rules/android-background-work.md
 .aiassistant/rules/android-navigation-best-practices.md
+.aiassistant/rules/play-billing-best-practices.md
+.aiassistant/rules/firebase-best-practices.md
+.aiassistant/rules/android-dependency-injection.md
+.aiassistant/rules/android-networking.md
+.aiassistant/rules/android-local-storage.md
+.aiassistant/rules/android-auth-identity.md
+.aiassistant/rules/android-media.md
+.aiassistant/rules/android-ci-cd.md
+.aiassistant/rules/android-maps-location.md
+.aiassistant/rules/android-ml-ondevice.md
 .amazonq/rules/compose-best-practices.md             # Amazon Q (per skill)
 .amazonq/rules/kmp-architecture-best-practices.md
 .amazonq/rules/compose-multiplatform-best-practices.md
@@ -466,6 +696,16 @@ CLAUDE.md                                            # Claude Code
 .amazonq/rules/android-build-infra.md
 .amazonq/rules/android-background-work.md
 .amazonq/rules/android-navigation-best-practices.md
+.amazonq/rules/play-billing-best-practices.md
+.amazonq/rules/firebase-best-practices.md
+.amazonq/rules/android-dependency-injection.md
+.amazonq/rules/android-networking.md
+.amazonq/rules/android-local-storage.md
+.amazonq/rules/android-auth-identity.md
+.amazonq/rules/android-media.md
+.amazonq/rules/android-ci-cd.md
+.amazonq/rules/android-maps-location.md
+.amazonq/rules/android-ml-ondevice.md
 CONVENTIONS.md                                       # Aider
 .aider.conf.yml
 ```
@@ -547,6 +787,16 @@ android-accessibility-best-practices/
 android-build-infra/
 android-background-work/
 android-navigation-best-practices/
+play-billing-best-practices/
+firebase-best-practices/
+android-dependency-injection/
+android-networking/
+android-local-storage/
+android-auth-identity/
+android-media/
+android-ci-cd/
+android-maps-location/
+android-ml-ondevice/
 README.md
 ```
 

package/android-auth-identity/SKILL.md

@@ -0,0 +1,36 @@
+
+---
+name: android-auth-identity
+description: Authentication & identity — Credential Manager, biometrics, token management, session security.
+---
+
+# Android Authentication & Identity
+
+Cross-cutting skill — always activates alongside the project-type-specific skill.
+
+## Hard Rules
+- Use Credential Manager API for sign-in flows — replaces legacy Smart Lock and FIDO2 APIs.
+- Store tokens in EncryptedSharedPreferences or Android Keystore — never in plain SharedPreferences.
+- Implement token refresh transparently — user should not see expired-token errors.
+- Use BiometricPrompt from androidx.biometric — not deprecated FingerprintManager.
+- Require BIOMETRIC_STRONG for sensitive operations (payments, account changes).
+- Never store raw passwords on device — use credential management APIs.
+- Validate all tokens server-side — client-side validation alone is insufficient.
+- Handle account linking carefully — merge conflicts can lose user data.
+- Clear all credentials on logout — tokens, cookies, cached user data.
+- Support passkeys (WebAuthn) as the primary passwordless credential.
+
+## Core Patterns
+- Single AuthRepository abstraction over Credential Manager + token storage.
+- Refresh tokens in OkHttp Authenticator — seamless for all API calls.
+- Biometric-bound keys for sensitive operations (CryptoObject in BiometricPrompt).
+- Use ID tokens (JWT) for user identity, access tokens for API authorization.
+- Implement session timeout — re-authenticate after inactivity period.
+- Wrap auth state in StateFlow for reactive UI updates.
+
+## References
+- references/credential_manager.md
+- references/biometric_auth.md
+- references/token_management.md
+- references/google_sign_in.md
+- references/session_security.md

package/android-auth-identity/references/biometric_auth.md

@@ -0,0 +1,36 @@
+# Biometric Authentication
+
+## BiometricPrompt
+- Use androidx.biometric.BiometricPrompt — not deprecated FingerprintManager.
+- Create with BiometricPrompt(activity/fragment, executor, callback).
+- Configure with BiometricPrompt.PromptInfo.Builder().
+- setTitle(), setSubtitle(), setDescription() for user-facing text.
+- setNegativeButtonText() for cancel action (required unless using device credential).
+
+## Authenticator Types
+- BIOMETRIC_STRONG: fingerprint, face (Class 3) — required for crypto operations.
+- BIOMETRIC_WEAK: less secure biometrics (Class 2) — no crypto support.
+- DEVICE_CREDENTIAL: PIN, pattern, password fallback.
+- setAllowedAuthenticators(BIOMETRIC_STRONG or DEVICE_CREDENTIAL) for flexible auth.
+- Check availability: BiometricManager.canAuthenticate(authenticators).
+
+## Crypto Integration
+- CryptoObject: wraps Cipher, Signature, or Mac bound to biometric auth.
+- Key generated with setUserAuthenticationRequired(true) in KeyGenParameterSpec.
+- After successful auth, use CryptoObject to perform crypto operation.
+- Use for: decrypting tokens, signing transactions, accessing secure data.
+- Key invalidated if biometric enrollment changes (setInvalidatedByBiometricEnrollment).
+
+## Authentication Flow
+1. Check BiometricManager.canAuthenticate() — handle BIOMETRIC_ERROR_*.
+2. Build PromptInfo with title and allowed authenticators.
+3. Create CryptoObject if needed (for sensitive operations).
+4. Call authenticate(promptInfo) or authenticate(promptInfo, cryptoObject).
+5. Handle callback: onAuthenticationSucceeded, onAuthenticationError, onAuthenticationFailed.
+
+## Best Practices
+- Use BIOMETRIC_STRONG for payments and sensitive data access.
+- Allow DEVICE_CREDENTIAL as fallback for convenience features.
+- Never use biometrics as the sole authentication — combine with server-side auth.
+- Handle all error codes: ERROR_LOCKOUT (too many attempts), ERROR_NO_BIOMETRICS, etc.
+- Test on devices with and without biometric hardware.

package/android-auth-identity/references/credential_manager.md

@@ -0,0 +1,32 @@
+# Credential Manager
+
+## Overview
+- Credential Manager is the unified API for sign-in (replaces Smart Lock, FIDO2 APIs).
+- Supports: passkeys (WebAuthn), passwords, federated sign-in (Google, etc.).
+- Single API: getCredential() presents all available credentials.
+- Available on API 28+ via Google Play Services, API 34+ natively.
+
+## Passkeys (WebAuthn)
+- Passkeys are FIDO2 credentials — phishing-resistant, no password needed.
+- Create: createCredential(CreatePublicKeyCredentialRequest(requestJson)).
+- Authenticate: getCredential(GetCredentialRequest(listOf(GetPublicKeyCredentialOption(requestJson)))).
+- requestJson comes from your server (WebAuthn challenge).
+- Passkeys sync across devices via Google Password Manager.
+
+## Password Credentials
+- GetPasswordOption() in GetCredentialRequest to offer saved passwords.
+- CreatePasswordRequest(id, password) to save new passwords.
+- Credential Manager auto-fills saved passwords.
+- Encourage passkey adoption — offer passkey creation after password sign-in.
+
+## Federated Sign-In
+- Google Sign-In: GetGoogleIdOption with serverClientId.
+- Returns GoogleIdTokenCredential — send ID token to your server.
+- Configure in Google Cloud Console: OAuth 2.0 client ID.
+- Filter by authorized accounts or allow any Google account.
+
+## Implementation Pattern
+- Call getCredential() on sign-in screen — shows bottom sheet with all options.
+- Handle GetCredentialResponse — check credential type and extract data.
+- Handle exceptions: NoCredentialException (no saved credentials), GetCredentialCancellationException (user dismissed).
+- Call clearCredentialState() on logout — clears Credential Manager state.

package/android-auth-identity/references/google_sign_in.md

@@ -0,0 +1,39 @@
+# Google Sign-In
+
+## Credential Manager Approach (Modern)
+- Use GetGoogleIdOption in Credential Manager — replaces legacy GoogleSignInClient.
+- Set serverClientId to your OAuth 2.0 Web client ID (from Google Cloud Console).
+- Set filterByAuthorizedAccounts(true) for returning users, false for new sign-up.
+- Returns GoogleIdTokenCredential with ID token and basic profile info.
+
+## OAuth Configuration
+- Create OAuth 2.0 client IDs in Google Cloud Console.
+- Web client ID: used as serverClientId in Android app.
+- Android client ID: configured with package name + SHA-1 fingerprint.
+- Add both debug and release SHA-1 fingerprints.
+- Update fingerprints when signing keys rotate.
+
+## Sign-In Flow
+1. Create GetGoogleIdOption with serverClientId.
+2. Build GetCredentialRequest with the option.
+3. Call credentialManager.getCredential(context, request).
+4. Extract GoogleIdTokenCredential from response.
+5. Send ID token to your server for verification.
+6. Server verifies token and creates/updates user account.
+
+## Server Verification
+- Verify ID token using Google's tokeninfo endpoint or client library.
+- Check: aud matches your client ID, iss is accounts.google.com, exp is not past.
+- Extract: sub (unique Google user ID), email, name, picture.
+- Use sub as the stable identifier — email can change.
+
+## One Tap Sign-In
+- Credential Manager shows One Tap UI automatically.
+- Returns user selection without full-screen flow.
+- Falls back to full sign-in if One Tap is dismissed.
+- Rate-limited: Google may suppress One Tap if dismissed repeatedly.
+
+## Sign-Out
+- Call credentialManager.clearCredentialState(ClearCredentialStateRequest()).
+- Also sign out from your backend (revoke tokens).
+- Clear local user data and cached credentials.

package/android-auth-identity/references/session_security.md

@@ -0,0 +1,33 @@
+# Session Security
+
+## Session Management
+- Define session lifetime based on app sensitivity (banking: 15 min, social: 30 days).
+- Track last-active timestamp — expire session after inactivity period.
+- Store session state in EncryptedSharedPreferences.
+- Clear session on logout: tokens, cached data, navigation state.
+
+## Re-Authentication
+- Require re-auth for sensitive operations: password change, payment, account deletion.
+- Use BiometricPrompt for seamless re-auth (if biometrics enrolled).
+- Fall back to full credential entry if biometrics fail.
+- Server should enforce re-auth — don't rely solely on client-side checks.
+
+## Device Binding
+- Use Android Keystore to generate device-bound keys.
+- Include device attestation in auth flow for high-security apps.
+- Detect device change: invalidate sessions when device fingerprint changes.
+- Use Play Integrity API for device integrity verification.
+
+## Secure Logout
+- Clear all tokens (access, refresh, ID) from secure storage.
+- Clear Credential Manager state: clearCredentialState().
+- Revoke tokens server-side — prevent reuse.
+- Clear WebView cookies if using web-based auth.
+- Navigate to login screen and clear back stack.
+
+## Attack Mitigation
+- Token fixation: always issue new tokens on successful auth.
+- Session hijacking: bind sessions to device/IP when feasible.
+- Brute force: implement account lockout after N failed attempts (server-side).
+- Replay attacks: use nonces in authentication challenges.
+- Man-in-the-middle: enforce certificate pinning for auth endpoints.

package/android-auth-identity/references/token_management.md

@@ -0,0 +1,33 @@
+# Token Management
+
+## Token Types
+- Access token: short-lived (15-60 minutes), authorizes API requests.
+- Refresh token: long-lived (days-months), used to obtain new access tokens.
+- ID token (JWT): contains user identity claims, used for user info.
+- Never use refresh tokens for API authorization — only for token renewal.
+
+## Storage
+- Store tokens in EncryptedSharedPreferences — not plain SharedPreferences.
+- Never store tokens in: Room database, DataStore, files, or logs.
+- Clear all tokens on logout.
+- Handle storage errors gracefully — force re-authentication if token storage fails.
+
+## Refresh Flow
+- Implement in OkHttp Authenticator for transparent refresh.
+- On 401: use refresh token to get new access token → retry original request.
+- Synchronize refresh: multiple concurrent 401s should trigger only one refresh.
+- If refresh fails (refresh token expired): clear tokens, navigate to login.
+- Use mutex or synchronized block to prevent concurrent refresh requests.
+
+## JWT Validation
+- Validate ID tokens on your server — not just on the client.
+- Check: issuer (iss), audience (aud), expiration (exp), signature.
+- Client-side: only check expiration for UX purposes (show login screen).
+- Never trust client-side JWT validation as the sole security measure.
+
+## Security
+- Rotate refresh tokens on each use (refresh token rotation).
+- Detect token theft: if a used refresh token is reused, revoke all tokens.
+- Set reasonable token lifetimes: access (15 min), refresh (7-30 days).
+- Bind tokens to device if possible (device attestation).
+- Handle token revocation from server (user changed password, admin action).

package/android-ci-cd/SKILL.md

@@ -0,0 +1,36 @@
+
+---
+name: android-ci-cd
+description: Android CI/CD — GitHub Actions, Fastlane, signing, Play Store deployment, build optimization.
+---
+
+# Android CI/CD
+
+Cross-cutting skill — always activates alongside the project-type-specific skill.
+
+## Hard Rules
+- Never store signing keys or passwords in the repository — use CI secrets.
+- Run unit tests on every pull request — block merge on failure.
+- Build release AAB in CI — not on developer machines.
+- Upload mapping.txt and native symbols with every release build.
+- Use Gradle build cache and configuration cache in CI.
+- Pin all CI action versions to SHA hashes — not tags (supply chain security).
+- Separate CI stages: lint → unit test → build → instrumented test → deploy.
+- Never skip CI checks for hotfixes — no --no-verify equivalent.
+- Cache Gradle dependencies and build outputs between runs.
+- Use Gradle Managed Devices or Firebase Test Lab for instrumented tests in CI.
+
+## Core Patterns
+- GitHub Actions with matrix strategy for testing on multiple API levels.
+- Fastlane for automated screenshots, metadata management, and deployment.
+- Decode signing keystore from base64 CI secret at build time.
+- Use semantic-release or Gradle Play Publisher for automated releases.
+- Run lint checks (detekt, ktlint, Android Lint) as CI gates.
+- Separate pipelines: PR validation (fast) vs release (thorough).
+
+## References
+- references/github_actions.md
+- references/fastlane.md
+- references/signing_ci.md
+- references/play_store_deployment.md
+- references/build_optimization.md

package/android-ci-cd/references/build_optimization.md

@@ -0,0 +1,39 @@
+# Build Optimization for CI
+
+## Gradle Caching
+- Enable build cache: org.gradle.caching=true in gradle.properties.
+- Enable configuration cache: org.gradle.configuration-cache=true.
+- Cache Gradle wrapper, dependencies, and build outputs in CI.
+- GitHub Actions: use gradle/actions/setup-gradle for automatic caching.
+- Cache key should include: gradle-wrapper.properties, libs.versions.toml, build files.
+
+## Parallel Execution
+- Enable parallel builds: org.gradle.parallel=true.
+- Set workers: org.gradle.workers.max=4 (match CI runner cores).
+- Modularized projects benefit most — independent modules build concurrently.
+- CI runners typically have 2-4 cores — adjust workers accordingly.
+
+## Daemon & Memory
+- Disable Gradle daemon in CI: org.gradle.daemon=false (CI runners are ephemeral).
+- Or keep daemon with warm-start for multi-step workflows.
+- Set JVM heap: org.gradle.jvmargs=-Xmx4g -XX:+UseParallelGC.
+- Match to CI runner memory — OOM kills are silent and confusing.
+- Use metaspace limit: -XX:MaxMetaspaceSize=512m.
+
+## Incremental Builds
+- Avoid clean builds in CI — leverage incremental compilation.
+- Only clean when: Gradle version changes, build scripts change significantly.
+- KSP/KAPT: incremental processing reduces annotation processing time.
+- Use --no-rebuild to skip up-to-date tasks.
+
+## Build Scans
+- Enable Gradle build scans for CI debugging: --scan flag.
+- Build scans show: task execution times, dependency resolution, cache hit rates.
+- Identify slow tasks and optimize them.
+- Use Develocity (Gradle Enterprise) for team-wide build analytics.
+
+## CI-Specific Tips
+- Use --stacktrace for debugging but --quiet for production CI (less log noise).
+- Upload build reports (lint, test, scan) as CI artifacts.
+- Set timeout on build steps — prevent hung builds from consuming runner time.
+- Use self-hosted runners for faster builds with persistent caches.

package/android-ci-cd/references/fastlane.md

@@ -0,0 +1,34 @@
+# Fastlane for Android
+
+## Setup
+- Install: gem install fastlane or add to Gemfile.
+- Initialize: fastlane init in project root.
+- Configure in fastlane/Fastfile with lanes.
+- Use .env files for environment-specific config (never commit secrets).
+
+## Common Lanes
+- lane :test — run unit tests: gradle(task: "testDebugUnitTest").
+- lane :build — build release: gradle(task: "bundleRelease").
+- lane :deploy — upload to Play Store: upload_to_play_store.
+- lane :screenshots — automated screenshots: capture_android_screenshots.
+- Chain lanes: before_all, after_all, error blocks.
+
+## Play Store Upload
+- upload_to_play_store: uploads AAB to specified track.
+- Tracks: internal, alpha, beta, production.
+- Set rollout_percentage for staged rollout: rollout_percentage: "10".
+- Include mapping.txt: mapping_paths: ["app/build/outputs/mapping/release/mapping.txt"].
+- Manage metadata: supply action for descriptions, screenshots, changelogs.
+
+## Screenshots
+- Use screengrab for automated screenshot capture.
+- Configure devices and locales in Screengrabfile.
+- Requires instrumented test that navigates through screens.
+- Upload screenshots to Play Store with supply.
+
+## Best Practices
+- Version lock fastlane in Gemfile — avoid CI surprises.
+- Use fastlane match or manual key management for signing.
+- Store Play Store JSON key in CI secrets — not in repo.
+- Use --verbose flag for debugging CI failures.
+- Run fastlane locally before pushing to CI.

package/android-ci-cd/references/github_actions.md

@@ -0,0 +1,35 @@
+# GitHub Actions for Android
+
+## Basic Workflow
+- Trigger on: push to main, pull_request.
+- Runner: ubuntu-latest (Linux — fastest for Android builds).
+- Set up JDK: actions/setup-java with distribution: 'temurin' and java-version: '17'.
+- Cache Gradle: actions/cache with ~/.gradle/caches and ~/.gradle/wrapper.
+- Or use gradle/actions/setup-gradle for automatic caching.
+
+## Build Steps
+- Make gradlew executable: chmod +x gradlew.
+- Lint: ./gradlew lint detekt ktlintCheck.
+- Unit tests: ./gradlew testDebugUnitTest.
+- Build: ./gradlew assembleRelease or bundleRelease.
+- Upload artifacts: actions/upload-artifact for APK/AAB.
+
+## Matrix Testing
+- Use strategy.matrix for multiple API levels or configurations.
+- Matrix dimensions: api-level [29, 33, 34], target [default, google_apis].
+- Use reactivecircus/android-emulator-runner for instrumented tests.
+- Cache AVD snapshots: force-avd-creation: false + avd-cache key.
+
+## Instrumented Tests
+- Use reactivecircus/android-emulator-runner action.
+- Or use Firebase Test Lab via gcloud CLI.
+- Set emulator-options: -no-snapshot-save -no-window -gpu swiftshader_indirect.
+- Run with script: ./gradlew connectedCheck.
+- Upload test reports as artifacts on failure.
+
+## Security
+- Pin action versions to SHA hashes: actions/checkout@<sha> (not @v4).
+- Store secrets in GitHub Settings > Secrets: KEYSTORE_BASE64, KEY_PASSWORD, etc.
+- Never echo secrets in workflow logs.
+- Use OIDC for trusted publishing (npm, PyPI) — no long-lived tokens.
+- Review third-party actions before adoption.