android-ai-skills 1.3.0 → 1.4.0

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

@@ -0,0 +1,36 @@
+# Play Store Deployment
+
+## Gradle Play Publisher
+- Plugin: com.github.triplet.play — automates Play Store uploads.
+- Configure: play { track.set("internal"); defaultToAppBundles.set(true) }.
+- Tasks: publishBundle (upload AAB), publishListing (update metadata), promoteArtifact (promote track).
+- Authenticate with service account JSON key from Google Cloud.
+- Store service account key as CI secret — never commit.
+
+## Service Account Setup
+- Create service account in Google Cloud Console.
+- Grant "Service Account User" role.
+- In Play Console: invite service account email with "Release manager" permissions.
+- Download JSON key — store as CI secret.
+- Key has no expiry — rotate periodically for security.
+
+## Deployment Strategy
+- Internal track: every merge to main — continuous delivery.
+- Closed testing: weekly or on-demand for QA team.
+- Production: manual trigger or tag-based release.
+- Staged rollout: start at 5-10%, monitor, expand to 100%.
+- Use GitHub Releases or tags to trigger production deployment.
+
+## Metadata Management
+- Store release notes in fastlane/metadata/android/ or play/ directory.
+- Per-locale directories: en-US/, es-ES/, etc.
+- Files: title.txt, short_description.txt, full_description.txt, changelogs/*.txt.
+- Automate metadata upload with publishListing task.
+- Version changelog in changelogs/{versionCode}.txt.
+
+## Rollback
+- Play Console: halt rollout to stop distribution of current version.
+- Re-promote previous version to resume old version distribution.
+- Alternatively: upload a hotfix with incremented versionCode.
+- Monitor Android Vitals during rollout — halt on crash rate regression.
+- Have a documented rollback procedure before every release.

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

@@ -0,0 +1,39 @@
+# Signing in CI
+
+## Keystore Management
+- Never commit keystore files to the repository.
+- Encode keystore as base64: base64 -i release.keystore | pbcopy.
+- Store base64 string as CI secret: KEYSTORE_BASE64.
+- Decode in CI: echo $KEYSTORE_BASE64 | base64 --decode > release.keystore.
+- Delete keystore after build completes — don't leave on CI runner.
+
+## Secret Configuration
+- Required secrets: KEYSTORE_BASE64, KEYSTORE_PASSWORD, KEY_ALIAS, KEY_PASSWORD.
+- Reference in build.gradle.kts via System.getenv().
+- signingConfigs.release { storeFile = file(keystorePath); storePassword = System.getenv("KEYSTORE_PASSWORD") }.
+- Never hardcode fallback values — fail the build if secrets are missing.
+
+## GitHub Actions Example
+```yaml
+- name: Decode keystore
+  run: echo "${{ secrets.KEYSTORE_BASE64 }}" | base64 --decode > app/release.keystore
+- name: Build release
+  env:
+    KEYSTORE_PASSWORD: ${{ secrets.KEYSTORE_PASSWORD }}
+    KEY_ALIAS: ${{ secrets.KEY_ALIAS }}
+    KEY_PASSWORD: ${{ secrets.KEY_PASSWORD }}
+  run: ./gradlew bundleRelease
+```
+
+## Play App Signing
+- Upload key (your key) signs the AAB before uploading.
+- Google re-signs with the app signing key for distribution.
+- If upload key is compromised: request reset in Play Console.
+- Upload key can be different from the app signing key.
+
+## Best Practices
+- Use separate upload key from app signing key.
+- Rotate upload key periodically (Play Console allows reset).
+- Audit CI secrets access — limit to deployment workflows only.
+- Use environment-specific signing: debug (auto), staging (shared), release (CI secret).
+- Test signed builds locally before relying on CI: ./gradlew bundleRelease.

package/android-dependency-injection/SKILL.md

@@ -0,0 +1,36 @@
+
+---
+name: android-dependency-injection
+description: Dependency injection with Hilt/Dagger — setup, scoping, multi-module, testing.
+---
+
+# Android Dependency Injection
+
+Cross-cutting skill — always activates alongside the project-type-specific skill.
+
+## Hard Rules
+- Use Hilt as the default DI framework for Android projects.
+- Annotate Application class with @HiltAndroidApp.
+- Annotate all Activities and Fragments that use injection with @AndroidEntryPoint.
+- Scope dependencies correctly — @Singleton for app-wide, @ViewModelScoped for ViewModel lifetime.
+- Never inject Activity or Fragment context into @Singleton-scoped objects — use @ApplicationContext.
+- Define bindings in @Module classes — use @Binds for interface-to-implementation, @Provides for construction.
+- Use @Qualifier annotations to distinguish same-type bindings — not named strings.
+- Keep modules focused — one module per feature boundary.
+- Use constructor injection over field injection wherever possible.
+- Never use Dagger directly when Hilt is available — Hilt reduces boilerplate.
+
+## Core Patterns
+- @InstallIn(SingletonComponent::class) for app-wide singletons.
+- @InstallIn(ViewModelComponent::class) for ViewModel-scoped dependencies.
+- Use @AssistedInject for WorkManager Workers and other assisted construction.
+- Define interface in feature-api, implementation binding in feature-impl module.
+- Use @EntryPoint for injecting into classes Hilt doesn't manage (ContentProvider, etc.).
+- Wrap third-party SDK initialization in @Provides methods for testability.
+
+## References
+- references/hilt_setup.md
+- references/scoping.md
+- references/multi_module_di.md
+- references/testing_di.md
+- references/common_mistakes.md

package/android-dependency-injection/references/common_mistakes.md

@@ -0,0 +1,37 @@
+# Common DI Mistakes
+
+## Scoping Leaks
+- Injecting Activity context into @Singleton scope — Activity leaks.
+- Fix: use @ApplicationContext for singleton-scoped dependencies.
+- Injecting ViewModel into @Singleton — ViewModel outlives its scope.
+- Fix: use @ViewModelScoped or don't scope the consuming class.
+
+## Missing Entry Points
+- Forgetting @AndroidEntryPoint on Activity that hosts injected Fragments.
+- Forgetting @HiltAndroidApp on Application class.
+- Forgetting to add hilt-android-compiler to KSP configuration.
+- Error: "Hilt Activity must be attached to an @AndroidEntryPoint Application."
+
+## Circular Dependencies
+- A depends on B, B depends on A — Dagger/Hilt fails at compile time.
+- Fix: introduce an interface to break the cycle.
+- Fix: use Provider<T> or Lazy<T> for deferred resolution.
+- Review dependency graph if cycles emerge — usually indicates design issue.
+
+## Field Injection Pitfalls
+- @Inject lateinit var in Fragments — must call inject before accessing.
+- Field injection not available in data classes or objects.
+- Prefer constructor injection — field injection hides dependencies.
+- Only use field injection where constructor injection is impossible (Activities, Fragments).
+
+## Module Mistakes
+- @Provides without @Module — binding is silently ignored.
+- @Module without @InstallIn — compile error (Hilt requires component).
+- @Binds with implementation class — must be abstract function in abstract module.
+- @Provides returning interface type but Hilt can't find the implementation.
+
+## Multi-Module Issues
+- Missing feature-impl dependency in :app module — binding not found at compile time.
+- Duplicate bindings across modules — use @Qualifier to disambiguate.
+- Installing test module in wrong component — bindings not visible to the test.
+- Feature module with @InstallIn(ActivityComponent::class) — consider if SingletonComponent is more appropriate.

package/android-dependency-injection/references/hilt_setup.md

@@ -0,0 +1,32 @@
+# Hilt Setup
+
+## Gradle Configuration
+- Add hilt-android and hilt-android-compiler (KSP) dependencies.
+- Apply com.google.dagger.hilt.android plugin.
+- Use KSP (not KAPT) for faster annotation processing.
+- Add hilt-navigation-compose for ViewModel injection in Navigation Compose.
+
+## Application
+- Annotate Application class with @HiltAndroidApp.
+- This generates the Hilt component hierarchy rooted at SingletonComponent.
+- Application class is required — Hilt cannot work without it.
+
+## Android Entry Points
+- @AndroidEntryPoint on Activities that use injection.
+- @AndroidEntryPoint on Fragments that use injection.
+- Activities must be @AndroidEntryPoint if their Fragments use injection.
+- Services, BroadcastReceivers, and Views can also be @AndroidEntryPoint.
+
+## Modules
+- @Module + @InstallIn(Component::class) for providing dependencies.
+- @Provides for creating instances with constructor logic.
+- @Binds for mapping interface to implementation (more efficient than @Provides).
+- companion object with @Provides for static factory methods.
+- Separate modules by concern: NetworkModule, DatabaseModule, RepositoryModule.
+
+## ViewModel
+- Annotate ViewModel with @HiltViewModel.
+- Use @Inject constructor for ViewModel dependencies.
+- Access in Compose: hiltViewModel() from hilt-navigation-compose.
+- Access in Fragment: by viewModels().
+- SavedStateHandle is automatically available in @HiltViewModel constructor.

package/android-dependency-injection/references/multi_module_di.md

@@ -0,0 +1,31 @@
+# Multi-Module DI
+
+## Pattern
+- feature-api module: defines interfaces (Repository, UseCase contracts).
+- feature-impl module: implements interfaces, provides Hilt bindings.
+- :app module: depends on all feature-impl modules, wires everything together.
+- Core modules: provide shared utilities (networking, database).
+
+## Binding in Feature Modules
+- Define @Module in feature-impl with @Binds mapping interface → implementation.
+- @InstallIn(SingletonComponent::class) for cross-feature shared instances.
+- @InstallIn(ViewModelComponent::class) for per-ViewModel instances.
+- Feature-impl module has implementation dependency on feature-api.
+
+## Cross-Feature Dependencies
+- Feature A needs Feature B's repository: depend on feature-b-api (interface only).
+- Hilt resolves the binding from feature-b-impl at compile time in :app.
+- Features never depend on other feature-impl modules directly.
+- This maintains loose coupling and parallel build.
+
+## Navigation DI
+- Feature-api exposes route classes — no DI needed for navigation contracts.
+- ViewModels in feature-impl use @HiltViewModel with injected dependencies.
+- Use hiltViewModel() in composable destinations for automatic scoping.
+- Shared data: pass via navigation arguments, not shared ViewModel instances.
+
+## Aggregation
+- :app module aggregates all @InstallIn modules automatically.
+- Hilt scans all transitive dependencies for @Module classes.
+- No manual component builder needed — Hilt handles aggregation.
+- Use @EntryPoint when injecting into non-Hilt-managed classes in feature modules.

package/android-dependency-injection/references/scoping.md

@@ -0,0 +1,34 @@
+# Scoping
+
+## Component Hierarchy
+- SingletonComponent: application lifetime — @Singleton scope.
+- ActivityRetainedComponent: survives configuration changes — @ActivityRetainedScoped.
+- ViewModelComponent: ViewModel lifetime — @ViewModelScoped.
+- ActivityComponent: Activity lifetime — @ActivityScoped.
+- FragmentComponent: Fragment lifetime — @FragmentScoped.
+- ServiceComponent: Service lifetime — @ServiceScoped.
+
+## Choosing Scope
+- @Singleton: app-wide singletons (Retrofit, OkHttpClient, Database, DataStore).
+- @ViewModelScoped: shared within a ViewModel's dependency graph.
+- Unscoped (no annotation): new instance every time — default and preferred for stateless objects.
+- Prefer unscoped — only add scope when sharing or lifecycle binding is needed.
+
+## Rules
+- Scoped bindings must be installed in a component that matches the scope.
+- @Singleton bindings must be in @InstallIn(SingletonComponent::class).
+- A scoped binding cannot depend on a narrower-scoped binding.
+- Unscoped bindings can be installed in any component.
+- Wider scope = longer lifetime = more memory usage — scope conservatively.
+
+## Common Mistakes
+- Over-scoping: making everything @Singleton wastes memory and hides lifecycle issues.
+- Under-scoping: creating expensive objects (database, HTTP client) repeatedly.
+- Injecting Activity/Fragment context into @Singleton — causes memory leaks.
+- Use @ApplicationContext for singletons that need Context.
+- Use @ActivityContext only in @ActivityScoped or narrower components.
+
+## Custom Scopes
+- Define custom scopes with @Scope annotation for domain-specific lifetimes.
+- Map to custom Hilt components with @DefineComponent.
+- Rarely needed — standard Hilt scopes cover most cases.

package/android-dependency-injection/references/testing_di.md

@@ -0,0 +1,36 @@
+# Testing with DI
+
+## Unit Tests
+- No Hilt needed — use constructor injection with fakes/mocks.
+- Create fakes of interfaces defined in feature-api modules.
+- Instantiate ViewModel/UseCase directly with fake dependencies.
+- This is the primary reason to use constructor injection everywhere.
+
+## Instrumented Tests
+- @HiltAndroidTest on test class.
+- Add HiltAndroidRule as a JUnit rule — must be ordered before other rules.
+- Use hiltRule.inject() in @Before to trigger injection.
+- Test Activity/Fragment with launchActivity or launchFragmentInHiltContainer.
+
+## Replacing Bindings
+- @UninstallModules(ProductionModule::class) removes production bindings.
+- Provide test bindings in a @Module @InstallIn @TestInstallIn annotated class.
+- Or use @BindValue to replace a single binding with a field in the test class.
+- @TestInstallIn replaces globally — @UninstallModules + local @Module for per-test replacement.
+
+## Custom Test Components
+- Use @CustomTestApplication for tests that need a custom Application class.
+- Combine with @HiltAndroidTest for full DI in custom app contexts.
+- Use HiltTestApplication as the application class in test runner config.
+
+## Robolectric
+- Hilt works with Robolectric — use @HiltAndroidTest + @Config(application = HiltTestApplication::class).
+- Combine with RobolectricTestRunner.
+- Faster than instrumented tests — runs on JVM.
+- Some Hilt features may require additional Robolectric configuration.
+
+## Best Practices
+- Test business logic without DI framework — pure unit tests.
+- Use DI in tests only when testing integration points (Activity, Fragment, Service).
+- Keep test modules simple — prefer @BindValue over full module replacement.
+- Verify DI graph compiles in CI — Hilt catches missing bindings at compile time.

package/android-local-storage/SKILL.md

@@ -0,0 +1,36 @@
+
+---
+name: android-local-storage
+description: Local storage — Room, DataStore, offline-first architecture, caching, encryption.
+---
+
+# Android Local Storage
+
+Cross-cutting skill — always activates alongside the project-type-specific skill.
+
+## Hard Rules
+- Use Room for structured relational data — not raw SQLite.
+- Use DataStore (Preferences or Proto) for key-value data — not SharedPreferences.
+- Export Room schemas (exportSchema = true) and test all migrations.
+- Never perform database operations on the main thread.
+- Use Flow or LiveData for reactive database queries — not one-shot reads for UI.
+- Define a single source of truth (database) — network responses update the database, UI observes the database.
+- Never store sensitive data (tokens, passwords) in Room or DataStore without encryption.
+- Use transactions for multi-table write operations.
+- Keep entities flat — avoid deeply nested objects in Room.
+- Use TypeConverters sparingly — prefer normalized relational design.
+
+## Core Patterns
+- Repository pattern: database as the source of truth, network as the updater.
+- Room DAOs return Flow<List<T>> for reactive UI updates.
+- Use @Upsert for insert-or-update operations (Room 2.5+).
+- DataStore with Proto for type-safe structured preferences.
+- Implement cache expiry with timestamps — stale-while-revalidate pattern.
+- Use database-backed pagination with RemoteMediator + Paging 3.
+
+## References
+- references/room_patterns.md
+- references/datastore.md
+- references/offline_first.md
+- references/cache_strategies.md
+- references/encryption.md

package/android-local-storage/references/cache_strategies.md

@@ -0,0 +1,33 @@
+# Cache Strategies
+
+## Time-Based Expiry
+- Store cachedAt timestamp alongside cached data.
+- Check freshness: if (now - cachedAt > maxAge) refresh from network.
+- Different TTLs for different data: user profile (1 hour), feed (5 minutes), config (24 hours).
+- Use stale-while-revalidate: show stale data immediately, refresh in background.
+
+## LRU Cache
+- In-memory LRU cache for frequently accessed data.
+- Use LruCache from android.util or custom implementation.
+- Size-based eviction — define max entries or max memory.
+- Use as L1 cache (memory) backed by L2 cache (database).
+
+## ETag / Conditional Requests
+- Store ETag from server response alongside cached data.
+- Send If-None-Match header on next request.
+- 304 Not Modified: cache is still valid, no data transfer.
+- Reduces bandwidth while keeping data fresh.
+
+## Cache Invalidation
+- User action: pull-to-refresh, data mutation, logout.
+- Push notification: server signals data change via FCM.
+- Time-based: automatic expiry after TTL.
+- Event-based: invalidate related caches when a mutation occurs.
+- Prefer explicit invalidation over time-based for user-facing data.
+
+## Multi-Layer Cache
+- L1: in-memory (fast, small, lost on process death).
+- L2: database/disk (slower, persistent across process restarts).
+- L3: network (slowest, always fresh).
+- Read: check L1 → L2 → L3. Write: update all layers.
+- Use for: image caching (Coil/Glide handle this), API response caching, computed results.

package/android-local-storage/references/datastore.md

@@ -0,0 +1,35 @@
+# DataStore
+
+## Preferences DataStore
+- Replacement for SharedPreferences — coroutine and Flow-based.
+- Create with preferencesDataStore(name = "settings") delegate.
+- Read: dataStore.data.map { prefs -> prefs[KEY] }.
+- Write: dataStore.edit { prefs -> prefs[KEY] = value }.
+- Keys: stringPreferencesKey, intPreferencesKey, booleanPreferencesKey, etc.
+
+## Proto DataStore
+- Type-safe structured data — define schema with Protocol Buffers.
+- Create .proto file in src/main/proto/.
+- Implement Serializer<T> for read/write.
+- Read/write are strongly typed — no string keys.
+- Prefer Proto DataStore for complex settings or data with multiple fields.
+
+## Migration from SharedPreferences
+- Use SharedPreferencesMigration in DataStore builder.
+- Migration runs once — old SharedPreferences deleted after migration.
+- Handle migration failures — provide default values.
+- Test migration with both old and new data formats.
+
+## Best Practices
+- Single DataStore instance per file — create at top level with delegate.
+- Never create DataStore inside Activity/Fragment — use singleton pattern.
+- Handle IOException in data.catch { } — file corruption is possible.
+- Emit default value on error: .catch { emit(emptyPreferences()) }.
+- DataStore writes are atomic — no partial writes.
+- Do not use DataStore for large datasets — use Room instead.
+
+## Thread Safety
+- DataStore is thread-safe — concurrent reads and writes are safe.
+- Writes are serialized — ordered by call sequence.
+- Reads are non-blocking — observe via Flow.
+- No need for synchronized blocks or mutexes.

package/android-local-storage/references/encryption.md

@@ -0,0 +1,35 @@
+# Storage Encryption
+
+## EncryptedSharedPreferences
+- Use for key-value secrets (tokens, API keys, small sensitive data).
+- Backed by AES256-SIV (keys) and AES256-GCM (values).
+- Create with MasterKey.Builder(context, MasterKey.DEFAULT_MASTER_KEY_ALIAS).
+- Thread-safe but slower than regular SharedPreferences.
+- Migrate from regular SharedPreferences when adding encryption.
+
+## EncryptedFile
+- Use for file-level encryption (documents, exported data).
+- Streaming encryption — suitable for large files.
+- Same MasterKey as EncryptedSharedPreferences.
+- Use for: database exports, log files, downloaded sensitive content.
+
+## SQLCipher for Room
+- SQLCipher encrypts the entire Room database file.
+- Use android-database-sqlcipher dependency + SupportFactory.
+- Pass encryption key via SupportFactory(passphrase).
+- Store passphrase in Android Keystore — not hardcoded.
+- Performance impact: ~5-15% slower than unencrypted Room.
+
+## Android Keystore
+- Hardware-backed key storage (TEE/StrongBox).
+- Generate keys with KeyGenParameterSpec.
+- Keys never leave the secure hardware.
+- Use for: encrypting local secrets, biometric-bound operations.
+- Keys are not exportable — use Keystore for crypto operations only.
+
+## Best Practices
+- Encrypt tokens, passwords, PII, health data, financial data.
+- Do not encrypt non-sensitive data — unnecessary performance cost.
+- Wipe decrypted data from memory after use (overwrite byte arrays).
+- Handle KeyPermanentlyInvalidatedException when biometric enrollment changes.
+- Test encryption on devices with and without hardware-backed Keystore.

package/android-local-storage/references/offline_first.md

@@ -0,0 +1,39 @@
+# Offline-First Architecture
+
+## Single Source of Truth
+- Database (Room) is the single source of truth — UI always reads from database.
+- Network responses update the database — never displayed directly to UI.
+- Flow: API → Repository → Database → UI observes database.
+- Benefits: offline access, consistent state, no stale UI.
+
+## Repository Pattern
+- Repository exposes Flow<List<T>> from Room DAO.
+- Repository has a refresh() suspend function that fetches from network and updates database.
+- UI calls refresh() on pull-to-refresh or initial load.
+- Database Flow automatically re-emits when data changes.
+
+## NetworkBoundResource Pattern
+- Observe database (cache).
+- If cache is stale or empty, fetch from network.
+- Save network response to database.
+- Re-emit updated data from database.
+- Handle loading, success, and error states.
+
+## Paging with RemoteMediator
+- Use Paging 3 + RemoteMediator for paginated offline-first lists.
+- RemoteMediator fetches pages from network, stores in Room.
+- PagingSource reads from Room for UI.
+- Room PagingSource auto-invalidates when data changes.
+- Handle PREPEND, APPEND, and REFRESH load types.
+
+## Conflict Resolution
+- Last-write-wins: server timestamp determines which version to keep.
+- Client-wins: local changes always override server data.
+- Server-wins: server data always overrides local changes.
+- Choose based on data type — user-generated content needs careful resolution.
+
+## Sync Strategy
+- Eager: sync immediately when network is available.
+- Lazy: sync on demand (user opens screen, pull-to-refresh).
+- Periodic: sync on schedule using WorkManager.
+- Push-triggered: sync when FCM notification arrives.

package/android-local-storage/references/room_patterns.md

@@ -0,0 +1,34 @@
+# Room Patterns
+
+## Database Setup
+- Annotate with @Database(entities = [...], version = N, exportSchema = true).
+- Use singleton pattern: companion object with @Volatile instance + synchronized.
+- Or provide via Hilt @Singleton @Provides.
+- Add fallbackToDestructiveMigration() only for cache databases — never for user data.
+- Configure WAL mode (default on API 16+) for better concurrent read/write.
+
+## Entities
+- @Entity with @PrimaryKey — prefer autoGenerate = true for local IDs.
+- Use @ColumnInfo for custom column names.
+- @Embedded for flattening nested objects into the same table.
+- @TypeConverter for complex types (Date, Enum, List) — register in @Database.
+- Keep entities flat — deeply nested objects should be separate entities with relations.
+
+## DAOs
+- Return Flow<List<T>> for reactive queries — Room re-emits on table changes.
+- Use suspend for write operations (insert, update, delete).
+- @Upsert (Room 2.5+) for insert-or-update in one operation.
+- @Transaction for multi-table operations.
+- @RawQuery for dynamic queries — use sparingly, prefer type-safe DAO methods.
+
+## Relations
+- @Relation for one-to-many and many-to-many relationships.
+- Use intermediary data classes with @Embedded parent + @Relation children.
+- @Junction for many-to-many with a junction table.
+- Always use @Transaction on queries with @Relation — ensures consistency.
+
+## Migrations
+- Provide Migration(oldVersion, newVersion) with SQL statements.
+- Test every migration path with MigrationTestHelper.
+- Use @AutoMigration for simple changes (add column, add table).
+- Never use fallbackToDestructiveMigration for databases with user data.

package/android-maps-location/SKILL.md

@@ -0,0 +1,35 @@
+
+---
+name: android-maps-location
+description: Maps & location — Google Maps SDK, FusedLocationProvider, geofencing, permissions.
+---
+
+# Android Maps & Location
+
+Cross-cutting skill — always activates alongside the project-type-specific skill.
+
+## Hard Rules
+- Use FusedLocationProviderClient — not LocationManager directly.
+- Request only the location accuracy you need (COARSE vs FINE).
+- Handle both approximate (COARSE) and precise (FINE) location grants (API 31+).
+- Remove location updates when not needed — do not leak location listeners.
+- Use foreground service with location type for background location access.
+- ACCESS_BACKGROUND_LOCATION requires separate permission request and justification.
+- Protect Google Maps API key with app restriction (SHA-1 + package name) in Cloud Console.
+- Do not hardcode API keys in source — use Secrets Gradle Plugin or local.properties.
+- Handle location permission denial gracefully — degrade to manual location entry.
+- Test with mock locations enabled and disabled.
+
+## Core Patterns
+- Request FINE + COARSE together — user can downgrade to approximate on API 31+.
+- Use LocationRequest.Builder with appropriate priority and interval.
+- Prefer geofencing over continuous polling for location-triggered actions.
+- Use Maps Compose library for Compose integration.
+- Cluster markers for dense map points — avoid rendering thousands of markers.
+- Cache geocoding results — avoid repeated API calls for the same coordinates.
+
+## References
+- references/google_maps.md
+- references/fused_location.md
+- references/geofencing.md
+- references/location_permissions.md

package/android-maps-location/references/fused_location.md

@@ -0,0 +1,40 @@
+# Fused Location Provider
+
+## Setup
+- Use com.google.android.gms:play-services-location dependency.
+- Get client: LocationServices.getFusedLocationProviderClient(context).
+- Requires ACCESS_FINE_LOCATION or ACCESS_COARSE_LOCATION permission.
+- Check permission before every location request.
+
+## Last Known Location
+- getLastLocation(): fast, no power cost, may return null.
+- Returns null if: location turned off, device just booted, Google Play Services data cleared.
+- Use as initial location while waiting for fresh updates.
+- Always handle null — don't assume location is available.
+
+## Location Updates
+- Build LocationRequest with Priority and interval.
+- PRIORITY_HIGH_ACCURACY: GPS + network (most power, ~1m accuracy).
+- PRIORITY_BALANCED_POWER_ACCURACY: network-based (~100m, lower power).
+- PRIORITY_LOW_POWER: passive, minimal power (~1km accuracy).
+- PRIORITY_PASSIVE: only receive locations from other apps' requests.
+
+## Request Configuration
+- setIntervalMillis: desired update interval.
+- setMinUpdateIntervalMillis: fastest acceptable interval.
+- setMaxUpdateDelayMillis: batch delivery delay for power saving.
+- setMinUpdateDistanceMeters: minimum displacement for update.
+- Use setWaitForAccurateLocation(true) for initial high-accuracy fix.
+
+## Receiving Updates
+- requestLocationUpdates(request, callback, looper) for callback-based.
+- requestLocationUpdates(request, pendingIntent) for background delivery.
+- Always call removeLocationUpdates() when done.
+- Use callbackFlow for coroutine/Flow integration.
+
+## Best Practices
+- Request lowest acceptable priority — save battery.
+- Remove updates in onPause/onStop — unless background location is needed.
+- Background location requires foreground service with location type (API 29+).
+- ACCESS_BACKGROUND_LOCATION is a separate permission request.
+- Handle location settings: use SettingsClient.checkLocationSettings() and prompt user.

package/android-maps-location/references/geofencing.md

@@ -0,0 +1,36 @@
+# Geofencing
+
+## Setup
+- Use GeofencingClient from play-services-location.
+- Requires ACCESS_FINE_LOCATION (and ACCESS_BACKGROUND_LOCATION for background).
+- Maximum 100 geofences per app per device.
+- Geofences are lost on reboot — re-register in BOOT_COMPLETED receiver.
+
+## Creating Geofences
+- Geofence.Builder() with requestId, circularRegion(lat, lng, radius), expirationDuration.
+- Transition types: GEOFENCE_TRANSITION_ENTER, EXIT, DWELL.
+- setLoiteringDelay() for DWELL transitions — how long user must stay.
+- Minimum reliable radius: ~100m (smaller radii are unreliable).
+- Use unique requestId for each geofence — needed for removal.
+
+## Registering
+- Build GeofencingRequest with addGeofences() and initial trigger.
+- INITIAL_TRIGGER_ENTER: trigger if already inside geofence.
+- INITIAL_TRIGGER_DWELL: trigger if already dwelling.
+- Register with addGeofences(request, pendingIntent).
+- PendingIntent delivers to BroadcastReceiver or Service.
+
+## Handling Transitions
+- Create a BroadcastReceiver to handle geofence events.
+- Extract GeofencingEvent from Intent: GeofencingEvent.fromIntent(intent).
+- Check for errors: geofencingEvent.hasError().
+- Get transition type and triggering geofences from the event.
+- Post notification or trigger WorkManager task on transition.
+
+## Best Practices
+- Use geofencing instead of continuous location polling — much lower power.
+- Keep radius ≥ 100m for reliable detection.
+- Handle Geofence expiration — re-register if long-lived.
+- Test with mock locations — real geofence testing is slow.
+- Handle permission denial — geofencing requires background location for useful behavior.
+- Re-register geofences on app update and device reboot.

package/android-maps-location/references/google_maps.md

@@ -0,0 +1,39 @@
+# Google Maps SDK
+
+## Setup
+- Add com.google.android.gms:play-services-maps dependency.
+- Add API key in AndroidManifest.xml: <meta-data android:name="com.google.android.geo.API_KEY" android:value="${MAPS_API_KEY}" />.
+- Inject API key from local.properties or CI secrets via Secrets Gradle Plugin.
+- Restrict API key in Google Cloud Console: Android app restriction + Maps SDK API restriction.
+
+## Maps Compose
+- Use maps-compose library for Compose integration.
+- GoogleMap composable with CameraPositionState.
+- Marker(state = MarkerState(position = latLng), title = "Label").
+- rememberCameraPositionState for controlling camera position.
+- Use MapProperties for map type, gestures, and controls.
+
+## Markers
+- Use Marker composable for individual points.
+- MarkerState for position — can be animated.
+- Custom marker icons: BitmapDescriptorFactory.fromResource or fromBitmap.
+- Use clustering for dense marker sets: maps-utils library + Clustering composable.
+- InfoWindow for tap-to-reveal details on markers.
+
+## Camera Control
+- CameraUpdateFactory.newLatLngZoom(position, zoom) for programmatic movement.
+- Animate: cameraPositionState.animate(cameraUpdate, durationMs).
+- Set bounds: CameraUpdateFactory.newLatLngBounds(bounds, padding) to fit all markers.
+- Handle camera move events: onCameraMove callback.
+
+## Styling
+- Use MapStyleOptions for custom map styling (JSON style).
+- Cloud-based map styling for dynamic style updates.
+- Dark mode: apply dark map style when app is in dark theme.
+- Hide/show map features: POIs, transit, roads, labels.
+
+## Best Practices
+- Load map lazily — don't initialize until the map screen is visible.
+- Handle Google Play Services unavailability gracefully.
+- Set initial camera position from user's last known location.
+- Test on devices without Google Play Services (Huawei, etc.) — provide fallback.