# Reference index - section anchors

Required: open only when [INDEX.md](INDEX.md) summary or a `-quick.md` file does not list the section you need.

Forbidden: load this file on every task; it is large by design.

## Sections by file

### android-accessibility.md (1571 lines)

Open when: TalkBack, semantics, touch targets, contrast, WCAG, Espresso a11y checks
Quick routing: [android-accessibility-quick.md](android-accessibility-quick.md)

- [Table of Contents](android-accessibility.md#table-of-contents)
- [WCAG 2.2 Criteria That Apply Here](android-accessibility.md#wcag-22-criteria-that-apply-here)
- [Semantic Properties](android-accessibility.md#semantic-properties)
  - [Content Description](android-accessibility.md#content-description)
  - [Label copy (TalkBack)](android-accessibility.md#label-copy-talkback)
  - [State Description](android-accessibility.md#state-description)
  - [Role Property](android-accessibility.md#role-property)
  - [Custom Actions](android-accessibility.md#custom-actions)
  - [Merge Descendants vs ClearAndSetSemantics](android-accessibility.md#merge-descendants-vs-clearandsetsemantics)
  - [Clear Semantics](android-accessibility.md#clear-semantics)
  - [Semantic Keys](android-accessibility.md#semantic-keys)
- [Touch Target Sizes](android-accessibility.md#touch-target-sizes)
  - [Minimum Touch Targets](android-accessibility.md#minimum-touch-targets)
  - [Spacing Between Targets](android-accessibility.md#spacing-between-targets)
  - [Testing Touch Targets](android-accessibility.md#testing-touch-targets)
- [Screen Reader Navigation](android-accessibility.md#screen-reader-navigation)
  - [Traversal Order](android-accessibility.md#traversal-order)
  - [Hiding sensitive fields from accessibility services](android-accessibility.md#hiding-sensitive-fields-from-accessibility-services)
  - [Heading Structure](android-accessibility.md#heading-structure)
  - [Live Region Announcements](android-accessibility.md#live-region-announcements)
  - [Skip to Content](android-accessibility.md#skip-to-content)
- [Color & Visual Accessibility](android-accessibility.md#color--visual-accessibility)
  - [Color Contrast Requirements](android-accessibility.md#color-contrast-requirements)
  - [Don't Rely on Color Alone](android-accessibility.md#dont-rely-on-color-alone)
  - [Dark Mode & High Contrast](android-accessibility.md#dark-mode--high-contrast)
- [Focus Management](android-accessibility.md#focus-management)
  - [Focus Order](android-accessibility.md#focus-order)
  - [Request Focus](android-accessibility.md#request-focus)
  - [Focus Indicators](android-accessibility.md#focus-indicators)
- [Common Patterns](android-accessibility.md#common-patterns)
  - [Lists](android-accessibility.md#lists)
  - [Dialogs](android-accessibility.md#dialogs)
  - [Bottom Navigation](android-accessibility.md#bottom-navigation)
  - [Forms with Validation](android-accessibility.md#forms-with-validation)
- [Testing Accessibility](android-accessibility.md#testing-accessibility)
  - [Compose Testing](android-accessibility.md#compose-testing)
  - [Espresso accessibility checks (instrumented)](android-accessibility.md#espresso-accessibility-checks-instrumented)
  - [Accessibility Scanner](android-accessibility.md#accessibility-scanner)
  - [Manual Testing Checklist](android-accessibility.md#manual-testing-checklist)
  - [Integration with CI/CD](android-accessibility.md#integration-with-cicd)
- [Rules](android-accessibility.md#rules)
- [References](android-accessibility.md#references)

### android-ci-cd.md (129 lines)

Open when: Play AAB, tracks, signing boundaries, rollout; agent vs Console work

- [Agent vs outside-repo work](android-ci-cd.md#agent-vs-outside-repo-work)
- [Table of Contents](android-ci-cd.md#table-of-contents)
- [Ship artifact format](android-ci-cd.md#ship-artifact-format)
- [versionCode and versionName](android-ci-cd.md#versioncode-and-versionname)
- [Release signing boundaries](android-ci-cd.md#release-signing-boundaries)
- [Play Console tracks](android-ci-cd.md#play-console-tracks)
- [Staged rollout on production](android-ci-cd.md#staged-rollout-on-production)
- [Upload automation routing](android-ci-cd.md#upload-automation-routing)
- [CI job composition (release lane)](android-ci-cd.md#ci-job-composition-release-lane)
- [Internal sharing without Play Console](android-ci-cd.md#internal-sharing-without-play-console)
- [Play developer verification](android-ci-cd.md#play-developer-verification)
- [Release notes and policy surfaces](android-ci-cd.md#release-notes-and-policy-surfaces)

### android-code-coverage.md (192 lines)

Open when: JaCoCo unit + instrumented coverage, CI, ScopedArtifacts pitfalls

- [Table of Contents](android-code-coverage.md#table-of-contents)
- [Coverage tiers](android-code-coverage.md#coverage-tiers)
  - [Optional: AGP aggregated reports (AGP 9.2+)](android-code-coverage.md#optional-agp-aggregated-reports-agp-92)
- [Setup](android-code-coverage.md#setup)
  - [Apply Convention Plugins](android-code-coverage.md#apply-convention-plugins)
- [Generating Coverage Reports](android-code-coverage.md#generating-coverage-reports)
- [Coverage Exclusions](android-code-coverage.md#coverage-exclusions)
- [CI Integration](android-code-coverage.md#ci-integration)
  - [GitHub Actions Example](android-code-coverage.md#github-actions-example)
  - [Enforcing Minimum Coverage](android-code-coverage.md#enforcing-minimum-coverage)
- [Rules](android-code-coverage.md#rules)
- [Troubleshooting](android-code-coverage.md#troubleshooting)
- [References](android-code-coverage.md#references)

### android-data-sync.md (2415 lines)

Open when: Offline-first, WorkManager sync, conflict resolution, cache invalidation
Quick routing: [android-data-sync-quick.md](android-data-sync-quick.md)

- [Table of Contents](android-data-sync.md#table-of-contents)
- [Offline-First Architecture](android-data-sync.md#offline-first-architecture)
  - [Core Principles](android-data-sync.md#core-principles)
  - [Architecture Flow](android-data-sync.md#architecture-flow)
  - [Repository with Offline-First](android-data-sync.md#repository-with-offline-first)
  - [Room Entity with Sync Metadata](android-data-sync.md#room-entity-with-sync-metadata)
- [Database Optimization (Room/SQLite)](android-data-sync.md#database-optimization-roomsqlite)
  - [Room](android-data-sync.md#room)
  - [SQLite](android-data-sync.md#sqlite)
- [Network State Monitoring](android-data-sync.md#network-state-monitoring)
  - [Network Monitor Interface](android-data-sync.md#network-monitor-interface)
  - [Implementation with ConnectivityManager](android-data-sync.md#implementation-with-connectivitymanager)
  - [Hilt Module](android-data-sync.md#hilt-module)
  - [Manifest Permission](android-data-sync.md#manifest-permission)
- [Sync Strategies](android-data-sync.md#sync-strategies)
  - [1. One-Way Sync (Server → Local)](android-data-sync.md#1-one-way-sync-server--local)
  - [2. Two-Way Sync (Bidirectional)](android-data-sync.md#2-two-way-sync-bidirectional)
  - [3. Periodic Sync](android-data-sync.md#3-periodic-sync)
  - [4. Event-Driven Sync (Real-Time)](android-data-sync.md#4-event-driven-sync-real-time)
- [Conflict Resolution](android-data-sync.md#conflict-resolution)
  - [Conflict Resolution Strategies](android-data-sync.md#conflict-resolution-strategies)
- [Cache Invalidation](android-data-sync.md#cache-invalidation)
  - [Time-Based Invalidation](android-data-sync.md#time-based-invalidation)
  - [Event-Based Invalidation](android-data-sync.md#event-based-invalidation)
  - [Size-Based Invalidation (LRU Cache)](android-data-sync.md#size-based-invalidation-lru-cache)
- [Retry Mechanisms](android-data-sync.md#retry-mechanisms)
  - [Retry with Exponential Backoff](android-data-sync.md#retry-with-exponential-backoff)
  - [Configurable Retry Policy](android-data-sync.md#configurable-retry-policy)
  - [Retry with Jitter](android-data-sync.md#retry-with-jitter)
- [WorkManager Integration](android-data-sync.md#workmanager-integration)
  - [`@HiltWorker` prerequisites](android-data-sync.md#hiltworker-prerequisites)
  - [Sync Coordinator](android-data-sync.md#sync-coordinator)
  - [Initialize Periodic Sync in Application](android-data-sync.md#initialize-periodic-sync-in-application)
  - [Work Constraints](android-data-sync.md#work-constraints)
  - [Work Chaining](android-data-sync.md#work-chaining)
  - [Passing Data Between Workers](android-data-sync.md#passing-data-between-workers)
  - [Progress Updates](android-data-sync.md#progress-updates)
  - [Observing Work Status](android-data-sync.md#observing-work-status)
  - [Expedited Work (API 31+)](android-data-sync.md#expedited-work-api-31)
  - [Testing WorkManager](android-data-sync.md#testing-workmanager)
  - [WorkManager Rules](android-data-sync.md#workmanager-rules)
  - [Work Constraints Comparison](android-data-sync.md#work-constraints-comparison)
- [Repository Pattern for Sync](android-data-sync.md#repository-pattern-for-sync)
- [Architecture Integration](android-data-sync.md#architecture-integration)
  - [ViewModel Observing Sync State](android-data-sync.md#viewmodel-observing-sync-state)
  - [UI Displaying Sync Status](android-data-sync.md#ui-displaying-sync-status)
- [Testing](android-data-sync.md#testing)
  - [Fake Repository](android-data-sync.md#fake-repository)
  - [Fake Network Monitor](android-data-sync.md#fake-network-monitor)
  - [Testing Sync Logic](android-data-sync.md#testing-sync-logic)
  - [Testing ViewModel with Sync](android-data-sync.md#testing-viewmodel-with-sync)
- [Rules](android-data-sync.md#rules)
  - [Sync Frequency Guidelines](android-data-sync.md#sync-frequency-guidelines)
  - [Conflict Resolution Strategy Selection](android-data-sync.md#conflict-resolution-strategy-selection)
  - [Performance Considerations](android-data-sync.md#performance-considerations)
- [References](android-data-sync.md#references)

### android-debugging.md (396 lines)

Open when: Logcat, ANR, R8 mapping, release crashes, memory-limiter repro

- [Table of Contents](android-debugging.md#table-of-contents)
- [Logcat](android-debugging.md#logcat)
  - [Filtering by App](android-debugging.md#filtering-by-app)
  - [When to use each level (operational discipline)](android-debugging.md#when-to-use-each-level-operational-discipline)
  - [Reading Crash Logs](android-debugging.md#reading-crash-logs)
- [ANR Debugging](android-debugging.md#anr-debugging)
  - [Gathering Evidence](android-debugging.md#gathering-evidence)
  - [What to Look For](android-debugging.md#what-to-look-for)
  - [Common Causes](android-debugging.md#common-causes)
- [Memory Leaks](android-debugging.md#memory-leaks)
  - [Common Causes](android-debugging.md#common-causes)
  - [LeakCanary](android-debugging.md#leakcanary)
  - [Manual Heap Dump](android-debugging.md#manual-heap-dump)
  - [Process kill under memory caps](android-debugging.md#process-kill-under-memory-caps)
- [R8 Stack Trace De-obfuscation](android-debugging.md#r8-stack-trace-de-obfuscation)
  - [R8 keep-rules troubleshooting](android-debugging.md#r8-keep-rules-troubleshooting)
  - [R8 Output Files](android-debugging.md#r8-output-files)
  - [Matching a trace to its mapping file](android-debugging.md#matching-a-trace-to-its-mapping-file)
  - [Using retrace (Automated)](android-debugging.md#using-retrace-automated)
  - [Manual De-obfuscation](android-debugging.md#manual-de-obfuscation)
  - [Debugging Unexpected Removal](android-debugging.md#debugging-unexpected-removal)
- [Gradle Build Failures](android-debugging.md#gradle-build-failures)
  - [Common Error Patterns](android-debugging.md#common-error-patterns)
  - [Dependency Investigation](android-debugging.md#dependency-investigation)
- [Compose Recomposition Debugging](android-debugging.md#compose-recomposition-debugging)
  - [Identifying Excessive Recomposition](android-debugging.md#identifying-excessive-recomposition)
  - [Common Causes](android-debugging.md#common-causes)
- [Multi-Layer Boundary Debugging](android-debugging.md#multi-layer-boundary-debugging)
- [ADB Quick Reference](android-debugging.md#adb-quick-reference)
- [Red Flags](android-debugging.md#red-flags)

### android-graphics.md (1216 lines)

Open when: Material Symbols, Coil3, Canvas, Palette, launcher icons

- [Table of Contents](android-graphics.md#table-of-contents)
- [Material Symbols Icons](android-graphics.md#material-symbols-icons)
  - [Downloading Icons](android-graphics.md#downloading-icons)
  - [Usage in Compose](android-graphics.md#usage-in-compose)
  - [Icon Organization](android-graphics.md#icon-organization)
- [Adaptive Launcher Icons](android-graphics.md#adaptive-launcher-icons)
- [ImageVector Patterns](android-graphics.md#imagevector-patterns)
  - [Basic ImageVector Creation](android-graphics.md#basic-imagevector-creation)
  - [PathData DSL](android-graphics.md#pathdata-dsl)
  - [PathData Commands Reference](android-graphics.md#pathdata-commands-reference)
  - [Dynamic Icon Generation](android-graphics.md#dynamic-icon-generation)
  - [Icon Collections](android-graphics.md#icon-collections)
  - [Themed Icons](android-graphics.md#themed-icons)
  - [Layered Icons with Alpha](android-graphics.md#layered-icons-with-alpha)
- [Custom Drawing with Canvas](android-graphics.md#custom-drawing-with-canvas)
  - [Drawing Modifiers](android-graphics.md#drawing-modifiers)
  - [Canvas Composable](android-graphics.md#canvas-composable)
  - [Advanced Canvas Techniques](android-graphics.md#advanced-canvas-techniques)
  - [Glow Effects with Radial Gradients](android-graphics.md#glow-effects-with-radial-gradients)
  - [Animated Pulsing Glow](android-graphics.md#animated-pulsing-glow)
  - [Multi-Color Glow Pattern](android-graphics.md#multi-color-glow-pattern)
  - [Color Extraction from Images](android-graphics.md#color-extraction-from-images)
  - [Dynamic Size Tracking](android-graphics.md#dynamic-size-tracking)
  - [Image Loading with Coil3](android-graphics.md#image-loading-with-coil3)
  - [Blend Modes](android-graphics.md#blend-modes)
  - [Performance: drawWithCache vs drawBehind](android-graphics.md#performance-drawwithcache-vs-drawbehind)
- [Performance Optimizations](android-graphics.md#performance-optimizations)
  - [Icon Caching](android-graphics.md#icon-caching)
  - [Avoid Recomposition](android-graphics.md#avoid-recomposition)
  - [Lazy Icon Loading](android-graphics.md#lazy-icon-loading)
- [Rules](android-graphics.md#rules)
- [Additional Resources](android-graphics.md#additional-resources)

### android-i18n.md (1063 lines)

Open when: strings.xml, plurals, RTL, locale formatting, translation CI

- [String Resources](android-i18n.md#string-resources)
  - [Basic String Resources](android-i18n.md#basic-string-resources)
  - [Using String Resources in Compose](android-i18n.md#using-string-resources-in-compose)
  - [Parameterized Strings](android-i18n.md#parameterized-strings)
- [Plurals (Quantity Strings)](android-i18n.md#plurals-quantity-strings)
  - [Defining Plurals](android-i18n.md#defining-plurals)
  - [Using Plurals in Compose](android-i18n.md#using-plurals-in-compose)
- [RTL (Right-to-Left) Support](android-i18n.md#rtl-right-to-left-support)
  - [Automatic RTL in Compose](android-i18n.md#automatic-rtl-in-compose)
  - [Layout Direction Awareness](android-i18n.md#layout-direction-awareness)
  - [RTL-Friendly Modifiers](android-i18n.md#rtl-friendly-modifiers)
  - [Force RTL for Testing](android-i18n.md#force-rtl-for-testing)
  - [Custom Mirroring for Icons](android-i18n.md#custom-mirroring-for-icons)
- [Date & Time Formatting](android-i18n.md#date--time-formatting)
  - [Dependencies](android-i18n.md#dependencies)
  - [Formatting with kotlinx-datetime](android-i18n.md#formatting-with-kotlinx-datetime)
  - [Using in Compose](android-i18n.md#using-in-compose)
  - [Relative Time with Plurals](android-i18n.md#relative-time-with-plurals)
- [Currency Formatting](android-i18n.md#currency-formatting)
- [Locale-Specific Resource Qualifiers](android-i18n.md#locale-specific-resource-qualifiers)
  - [Common Qualifiers](android-i18n.md#common-qualifiers)
  - [Combining Qualifiers](android-i18n.md#combining-qualifiers)
  - [String Arrays](android-i18n.md#string-arrays)
- [String Resource Ownership](android-i18n.md#string-resource-ownership)
  - [Module Organization](android-i18n.md#module-organization)
  - [Cross-Module Resource Access](android-i18n.md#cross-module-resource-access)
- [Architecture Integration](android-i18n.md#architecture-integration)
  - [Repository Layer](android-i18n.md#repository-layer)
  - [ViewModel Layer](android-i18n.md#viewmodel-layer)
  - [UI Layer](android-i18n.md#ui-layer)
- [Testing Localization](android-i18n.md#testing-localization)
  - [Testing Different Locales](android-i18n.md#testing-different-locales)
  - [Testing Plurals](android-i18n.md#testing-plurals)
  - [Parameterized Tests for Multiple Locales](android-i18n.md#parameterized-tests-for-multiple-locales)
  - [Screenshot Testing for RTL](android-i18n.md#screenshot-testing-for-rtl)
- [Rules](android-i18n.md#rules)
  - [String resources](android-i18n.md#string-resources)
  - [Plurals for quantities](android-i18n.md#plurals-for-quantities)
  - [No string concatenation](android-i18n.md#no-string-concatenation)
  - [Start/end layout](android-i18n.md#startend-layout)
  - [RTL testing](android-i18n.md#rtl-testing)
  - [Locale-aware formatting](android-i18n.md#locale-aware-formatting)
  - [Text expansion](android-i18n.md#text-expansion)
  - [Translator context comments](android-i18n.md#translator-context-comments)
  - [ICU MessageFormat](android-i18n.md#icu-messageformat)
  - [Relative measurements](android-i18n.md#relative-measurements)
- [CI/CD Integration](android-i18n.md#cicd-integration)
  - [Automated String Checks](android-i18n.md#automated-string-checks)
- [Common Pitfalls](android-i18n.md#common-pitfalls)
  - [Pitfall: RTL skipped](android-i18n.md#pitfall-rtl-skipped)
  - [Pitfall: string concatenation](android-i18n.md#pitfall-string-concatenation)
  - [Pitfall: hardcoded dates/times](android-i18n.md#pitfall-hardcoded-datestimes)
  - [Pitfall: English-only word order](android-i18n.md#pitfall-english-only-word-order)
  - [Pitfall: no expansion testing](android-i18n.md#pitfall-no-expansion-testing)
- [External Resources](android-i18n.md#external-resources)

### android-media.md (176 lines)

Open when: Media3 background playback API 37, picking, sharing, preloading

- [Table of Contents](android-media.md#table-of-contents)
- [Picking media and documents](android-media.md#picking-media-and-documents)
- [Sharing media and files](android-media.md#sharing-media-and-files)
- [Scoped storage and permissions](android-media.md#scoped-storage-and-permissions)
- [Media3 version and artifacts](android-media.md#media3-version-and-artifacts)
  - [Compose player UI (`media3-ui-compose`)](android-media.md#compose-player-ui-media3-ui-compose)
- [Playback preloading (Media3)](android-media.md#playback-preloading-media3)
- [Background media playback hardening (API 37)](android-media.md#background-media-playback-hardening-api-37)
  - [Diagnosing silent audio failures](android-media.md#diagnosing-silent-audio-failures)
  - [Manifest](android-media.md#manifest)
  - [Service skeleton](android-media.md#service-skeleton)

### android-navigation.md (2251 lines)

Open when: Navigation3, deep links, App Links, adaptive layouts, large screens
Quick routing: [android-navigation-quick.md](android-navigation-quick.md)

- [Table of Contents](android-navigation.md#table-of-contents)
- [Navigation3 Architecture](android-navigation.md#navigation3-architecture)
- [Adaptive Quality and Large Screens](android-navigation.md#adaptive-quality-and-large-screens)
  - [Quality tiers](android-navigation.md#quality-tiers)
  - [Width and layout (with Navigation3)](android-navigation.md#width-and-layout-with-navigation3)
  - [Configuration and state](android-navigation.md#configuration-and-state)
  - [Foldables](android-navigation.md#foldables)
  - [Pointer, keyboard, and desktop expectations](android-navigation.md#pointer-keyboard-and-desktop-expectations)
  - [Multi-window](android-navigation.md#multi-window)
  - [Testing matrix (manual)](android-navigation.md#testing-matrix-manual)
- [Navigation 3 Quick Start](android-navigation.md#navigation-3-quick-start)
- [App Navigation Setup](android-navigation.md#app-navigation-setup)
- [Navigation 3 State Management](android-navigation.md#navigation-3-state-management)
- [Navigation invariants](android-navigation.md#navigation-invariants)
- [Navigation Flow](android-navigation.md#navigation-flow)
- [Migration](android-navigation.md#migration)
- [Animations](android-navigation.md#animations)
  - [Global Transitions](android-navigation.md#global-transitions)
  - [Per-Entry Overrides](android-navigation.md#per-entry-overrides)
  - [Common Animation Patterns](android-navigation.md#common-animation-patterns)
- [Scenes & Custom Layouts](android-navigation.md#scenes--custom-layouts)
  - [Scene Interface](android-navigation.md#scene-interface)
  - [SceneStrategy](android-navigation.md#scenestrategy)
    - [Pass a list, not a chain](android-navigation.md#pass-a-list-not-a-chain)
    - [Implementing a custom Scene](android-navigation.md#implementing-a-custom-scene)
    - [Scene decorators](android-navigation.md#scene-decorators)
    - [NavMetadata DSL](android-navigation.md#navmetadata-dsl)
  - [Dialog Navigation](android-navigation.md#dialog-navigation)
  - [Bottom Sheet Navigation](android-navigation.md#bottom-sheet-navigation)
  - [Custom Scene: List-Detail Layout](android-navigation.md#custom-scene-list-detail-layout)
  - [Material3 Adaptive Scenes](android-navigation.md#material3-adaptive-scenes)
- [Deep Links](android-navigation.md#deep-links)
  - [Parsing an Intent into a NavKey](android-navigation.md#parsing-an-intent-into-a-navkey)
  - [Synthetic Back Stack](android-navigation.md#synthetic-back-stack)
  - [Task Management](android-navigation.md#task-management)
  - [AndroidManifest Setup](android-navigation.md#androidmanifest-setup)
  - [onNewIntent for singleTask](android-navigation.md#onnewintent-for-singletask)
  - [Broad manifest scope with server-side path routing (Android 15+)](android-navigation.md#broad-manifest-scope-with-server-side-path-routing-android-15)
  - [App Links Verification](android-navigation.md#app-links-verification)
  - [Dynamic App Links (Android 15+, API 35)](android-navigation.md#dynamic-app-links-android-15-api-35)
  - [DomainVerificationManager Runtime Check](android-navigation.md#domainverificationmanager-runtime-check)
  - [URI Pattern Matching](android-navigation.md#uri-pattern-matching)
  - [Deep Link Security](android-navigation.md#deep-link-security)
  - [Custom-Scheme Deep Linking](android-navigation.md#custom-scheme-deep-linking)
  - [Testing Deep Links](android-navigation.md#testing-deep-links)
  - [Troubleshooting Deep Links](android-navigation.md#troubleshooting-deep-links)
- [Conditional Navigation](android-navigation.md#conditional-navigation)
  - [Define Auth-Gated Keys](android-navigation.md#define-auth-gated-keys)
  - [Navigator with Auth Check](android-navigation.md#navigator-with-auth-check)
  - [Wire Up in Composable](android-navigation.md#wire-up-in-composable)
- [Returning Results](android-navigation.md#returning-results)
  - [Callback-Based Results](android-navigation.md#callback-based-results)
  - [Event-Based Results](android-navigation.md#event-based-results)
  - [State-Based Results (CompositionLocal)](android-navigation.md#state-based-results-compositionlocal)
  - [Choosing a pattern](android-navigation.md#choosing-a-pattern)
- [ViewModel Scoping](android-navigation.md#viewmodel-scoping)
  - [NavEntryDecorators](android-navigation.md#naventrydecorators)
  - [Scoping to a non-screen composable](android-navigation.md#scoping-to-a-non-screen-composable)
  - [Passing NavKey Arguments to Hilt ViewModels](android-navigation.md#passing-navkey-arguments-to-hilt-viewmodels)
  - [Shared ViewModel Between Screens](android-navigation.md#shared-viewmodel-between-screens)
- [Navigation Anti-Patterns](android-navigation.md#navigation-anti-patterns)
  - [`hiltViewModel()` Scope Mistakes](android-navigation.md#hiltviewmodel-scope-mistakes)
  - [ViewModel Navigation](android-navigation.md#viewmodel-navigation)
  - [Passing Complex Objects in NavKeys](android-navigation.md#passing-complex-objects-in-navkeys)

### android-notifications.md (1322 lines)

Open when: Channels, FGS, MediaStyle, PiP, sharesheet from notification taps

- [Table of Contents](android-notifications.md#table-of-contents)
- [Notification Channels (API 26+)](android-notifications.md#notification-channels-api-26)
  - [Channel Creation](android-notifications.md#channel-creation)
  - [Initialize in Application](android-notifications.md#initialize-in-application)
- [Basic Notifications](android-notifications.md#basic-notifications)
  - [Simple Notification](android-notifications.md#simple-notification)
  - [Notification with Tap Action](android-notifications.md#notification-with-tap-action)
- [Notification Styles](android-notifications.md#notification-styles)
  - [BigTextStyle](android-notifications.md#bigtextstyle)
  - [BigPictureStyle](android-notifications.md#bigpicturestyle)
  - [InboxStyle](android-notifications.md#inboxstyle)
  - [MessagingStyle](android-notifications.md#messagingstyle)
- [Action Buttons](android-notifications.md#action-buttons)
  - [Basic Actions](android-notifications.md#basic-actions)
  - [Notification Action Receiver](android-notifications.md#notification-action-receiver)
- [Progress Notifications](android-notifications.md#progress-notifications)
  - [Determinate Progress](android-notifications.md#determinate-progress)
  - [Indeterminate Progress](android-notifications.md#indeterminate-progress)
- [Progress-Centric Notifications (API 36+)](android-notifications.md#progress-centric-notifications-api-36)
  - [ProgressStyle Notification](android-notifications.md#progressstyle-notification)
- [Metric Notifications (API 37+)](android-notifications.md#metric-notifications-api-37)
- [Live Updates (API 36+)](android-notifications.md#live-updates-api-36)
  - [Semantic coloring (API 37+)](android-notifications.md#semantic-coloring-api-37)
- [Foreground Service Notifications](android-notifications.md#foreground-service-notifications)
  - [Foreground Service Setup](android-notifications.md#foreground-service-setup)
  - [Foreground Service in Android Service](android-notifications.md#foreground-service-in-android-service)
- [Media, PiP, Sharing, and Background Work](android-notifications.md#media-pip-sharing-and-background-work)
  - [Audio focus](android-notifications.md#audio-focus)
  - [Picture-in-picture (video)](android-notifications.md#picture-in-picture-video)
  - [System sharesheet](android-notifications.md#system-sharesheet)
  - [Background work vs long-running services](android-notifications.md#background-work-vs-long-running-services)
- [Navigation State (Navigation3)](android-notifications.md#navigation-state-navigation3)
- [Notification Manager Interface](android-notifications.md#notification-manager-interface)
  - [Implementation](android-notifications.md#implementation)
  - [Hilt Module](android-notifications.md#hilt-module)
- [Architecture Integration](android-notifications.md#architecture-integration)
  - [Repository Layer](android-notifications.md#repository-layer)
  - [ViewModel Layer](android-notifications.md#viewmodel-layer)
- [Testing](android-notifications.md#testing)
  - [Fake NotificationManager](android-notifications.md#fake-notificationmanager)
  - [Testing Repository](android-notifications.md#testing-repository)
  - [Testing ViewModel](android-notifications.md#testing-viewmodel)
- [Notification routing](android-notifications.md#notification-routing)
  - [Required](android-notifications.md#required)
  - [Forbidden](android-notifications.md#forbidden)
  - [Notification ID Strategy](android-notifications.md#notification-id-strategy)
  - [Channel Importance Levels](android-notifications.md#channel-importance-levels)
  - [PendingIntent Flags](android-notifications.md#pendingintent-flags)
- [References](android-notifications.md#references)

### android-performance.md (1417 lines)

Open when: Macrobenchmark, baseline profiles, vitals, recomposition, startup, APA/Perfetto

- [Table of Contents](android-performance.md#table-of-contents)
- [Google Play Vitals and production targets](android-performance.md#google-play-vitals-and-production-targets)
  - [Core thresholds (Play Console)](android-performance.md#core-thresholds-play-console)
  - [Optional: Play Vitals observability (Play Developer Reporting API)](android-performance.md#optional-play-vitals-observability-play-developer-reporting-api)
  - [Startup time (user experience)](android-performance.md#startup-time-user-experience)
  - [Frame time and jank](android-performance.md#frame-time-and-jank)
  - [Background work and battery](android-performance.md#background-work-and-battery)
- [Benchmark](android-performance.md#benchmark)
  - [Macrobenchmark (Compose)](android-performance.md#macrobenchmark-compose)
  - [Android Performance Analyzer (APA)](android-performance.md#android-performance-analyzer-apa)
  - [Perfetto (system traces)](android-performance.md#perfetto-system-traces)
  - [Startup Performance Metrics (TTID & TTFD)](android-performance.md#startup-performance-metrics-ttid--ttfd)
  - [Baseline Profiles](android-performance.md#baseline-profiles)
- [Compose Stability Validation (Optional)](android-performance.md#compose-stability-validation-optional)
  - [IDE Plugin (Optional)](android-performance.md#ide-plugin-optional)
  - [Gradle Plugin for CI/CD](android-performance.md#gradle-plugin-for-cicd)
- [CPU Optimization](android-performance.md#cpu-optimization)
- [Battery Optimization](android-performance.md#battery-optimization)
  - [Excessive partial wake locks (Play Vitals core metric)](android-performance.md#excessive-partial-wake-locks-play-vitals-core-metric)
- [Network Performance Optimization](android-performance.md#network-performance-optimization)
- [Image Optimization](android-performance.md#image-optimization)
- [APK Size Optimization](android-performance.md#apk-size-optimization)
- [App Startup & Initialization](android-performance.md#app-startup--initialization)
  - [ContentProvider Anti-Pattern](android-performance.md#contentprovider-anti-pattern)
  - [App Startup Library](android-performance.md#app-startup-library)
  - [Lazy Initialization Strategies](android-performance.md#lazy-initialization-strategies)
  - [Splash Screen](android-performance.md#splash-screen)
  - [Startup Optimization Checklist](android-performance.md#startup-optimization-checklist)
- [Compose Recomposition Performance](android-performance.md#compose-recomposition-performance)
  - [Three Phases of Compose](android-performance.md#three-phases-of-compose)
  - [Deferred State Reads](android-performance.md#deferred-state-reads)
  - [Strong Skipping Mode](android-performance.md#strong-skipping-mode)
  - [derivedStateOf - Reducing Recomposition Frequency](android-performance.md#derivedstateof---reducing-recomposition-frequency)
  - [remember with Keys](android-performance.md#remember-with-keys)
  - [R8/ProGuard Compose Rules](android-performance.md#r8proguard-compose-rules)
  - [Layout Inspector - Recomposition Counts](android-performance.md#layout-inspector---recomposition-counts)
  - [Common Hot Paths](android-performance.md#common-hot-paths)
  - [Text Input Performance](android-performance.md#text-input-performance)
  - [Performance Checklist](android-performance.md#performance-checklist)
- [References](android-performance.md#references)

### android-permissions.md (921 lines)

Open when: Runtime permissions, Photo Picker, contacts, API 37 location privacy

- [Table of Contents](android-permissions.md#table-of-contents)
- [Where Permissions Live](android-permissions.md#where-permissions-live)
- [Common Permission Sets](android-permissions.md#common-permission-sets)
  - [Network (Normal)](android-permissions.md#network-normal)
  - [Camera (Runtime)](android-permissions.md#camera-runtime)
  - [Media Access (Runtime, Android 13+)](android-permissions.md#media-access-runtime-android-13)
  - [Notifications (Runtime, Android 13+)](android-permissions.md#notifications-runtime-android-13)
  - [Location (Runtime)](android-permissions.md#location-runtime)
  - [Contact picker (privacy-first)](android-permissions.md#contact-picker-privacy-first)
- [Requesting Runtime Permissions in Compose](android-permissions.md#requesting-runtime-permissions-in-compose)
  - [Single Permission (Camera)](android-permissions.md#single-permission-camera)
  - [Multiple Permissions (Media Access)](android-permissions.md#multiple-permissions-media-access)
  - [Notifications Permission (Android 13+)](android-permissions.md#notifications-permission-android-13)
  - [Photo Picker (Android 13+)](android-permissions.md#photo-picker-android-13)
  - [Embedded Photo Picker](android-permissions.md#embedded-photo-picker)
- [Requesting Special Permissions](android-permissions.md#requesting-special-permissions)
  - [Exact Alarms (Special Permission)](android-permissions.md#exact-alarms-special-permission)
  - [All Files Access (Special Permission)](android-permissions.md#all-files-access-special-permission)
- [Rationale and Don't Ask Again](android-permissions.md#rationale-and-dont-ask-again)
  - [Rules](android-permissions.md#rules)
  - [Open App Settings](android-permissions.md#open-app-settings)
  - [Rationale Dialog Component](android-permissions.md#rationale-dialog-component)
  - [Track Denial Count (Proper Pattern)](android-permissions.md#track-denial-count-proper-pattern)
- [Version-Specific Handling](android-permissions.md#version-specific-handling)
  - [Media Permissions (Android 14+ Partial Access)](android-permissions.md#media-permissions-android-14-partial-access)
  - [Notification Permissions (Android 13+)](android-permissions.md#notification-permissions-android-13)
- [Android 16 (API 36) Permission Changes](android-permissions.md#android-16-api-36-permission-changes)
  - [Health & Fitness Permissions](android-permissions.md#health--fitness-permissions)
  - [App-Owned Photos Pre-Selection](android-permissions.md#app-owned-photos-pre-selection)
- [Android 17 (API 37) Permission Changes](android-permissions.md#android-17-api-37-permission-changes)
  - [Local network access (API 37)](android-permissions.md#local-network-access-api-37)
  - [Android 17 location privacy](android-permissions.md#android-17-location-privacy)
  - [Coarse location is no longer a fixed grid](android-permissions.md#coarse-location-is-no-longer-a-fixed-grid)
  - [System location button (one-time precise access, no permission)](android-permissions.md#system-location-button-one-time-precise-access-no-permission)
  - [Location access transparency (Android 17)](android-permissions.md#location-access-transparency-android-17)
- [Testing](android-permissions.md#testing)
  - [Grant Permission in Tests](android-permissions.md#grant-permission-in-tests)
  - [Test Permission Denial Flow](android-permissions.md#test-permission-denial-flow)
  - [Performance Checks (Macrobenchmark)](android-permissions.md#performance-checks-macrobenchmark)
- [References](android-permissions.md#references)

### android-security.md (1849 lines)

Open when: Pinning, encryption, biometrics, Play Integrity, Credential Manager, URI grants
Quick routing: [android-security-quick.md](android-security-quick.md)

- [Table of Contents](android-security.md#table-of-contents)
- [Dependencies](android-security.md#dependencies)
- [Device trust and abuse resistance](android-security.md#device-trust-and-abuse-resistance)
  - [Client-only heuristics are insufficient](android-security.md#client-only-heuristics-are-insufficient)
  - [Trust inputs (server-verifiable)](android-security.md#trust-inputs-server-verifiable)
  - [Implementation order](android-security.md#implementation-order)
- [Network Security](android-security.md#network-security)
  - [Network Security Configuration](android-security.md#network-security-configuration)
  - [Certificate Transparency (API 37)](android-security.md#certificate-transparency-api-37)
  - [Cross-profile loopback (Android 17)](android-security.md#cross-profile-loopback-android-17)
  - [OkHttp Security Configuration](android-security.md#okhttp-security-configuration)
  - [Preventing Man-in-the-Middle Attacks](android-security.md#preventing-man-in-the-middle-attacks)
- [Certificate Pinning](android-security.md#certificate-pinning)
  - [Network Security Config](android-security.md#network-security-config)
  - [OkHttp CertificatePinner (programmatic)](android-security.md#okhttp-certificatepinner-programmatic)
  - [Extracting Pin Hashes](android-security.md#extracting-pin-hashes)
  - [Pin rotation and monitoring](android-security.md#pin-rotation-and-monitoring)
- [Data Encryption at Rest](android-security.md#data-encryption-at-rest)
  - [EncryptedSharedPreferences](android-security.md#encryptedsharedpreferences)
  - [EncryptedFile](android-security.md#encryptedfile)
  - [Bank-Level Encryption (AES-256-GCM)](android-security.md#bank-level-encryption-aes-256-gcm)
  - [Software Fallback (No Hardware Security Module)](android-security.md#software-fallback-no-hardware-security-module)
- [Android Keystore, TEE & StrongBox](android-security.md#android-keystore-tee--strongbox)
  - [What They Are](android-security.md#what-they-are)
  - [How They Protect](android-security.md#how-they-protect)
  - [Using Hardware-Backed Keys](android-security.md#using-hardware-backed-keys)
  - [DI Integration](android-security.md#di-integration)
- [Biometric Authentication](android-security.md#biometric-authentication)
  - [BiometricPrompt Setup](android-security.md#biometricprompt-setup)
  - [Using Biometrics in Compose](android-security.md#using-biometrics-in-compose)
  - [Biometric + Keystore (Bank-Level Security)](android-security.md#biometric--keystore-bank-level-security)
- [Credential Manager and Sign-In](android-security.md#credential-manager-and-sign-in)
- [Device Identifiers and Privacy](android-security.md#device-identifiers-and-privacy)
- [Android 15+ Platform Privacy](android-security.md#android-15-platform-privacy)
  - [Partial photo/media access (API 34+, enforced broadly on API 35+)](android-security.md#partial-photomedia-access-api-34-enforced-broadly-on-api-35)
  - [Screen recording detection (API 35+)](android-security.md#screen-recording-detection-api-35)
  - [Private Space awareness (API 35+)](android-security.md#private-space-awareness-api-35)
  - [Partial screen sharing (API 34+)](android-security.md#partial-screen-sharing-api-34)
  - [Official references](android-security.md#official-references)
- [Play Console Data Safety](android-security.md#play-console-data-safety)
- [Play Integrity API](android-security.md#play-integrity-api)
  - [Prerequisites and project setup](android-security.md#prerequisites-and-project-setup)
  - [Standard API vs Classic API](android-security.md#standard-api-vs-classic-api)
  - [Standard API client flow](android-security.md#standard-api-client-flow)
  - [Classic API client flow](android-security.md#classic-api-client-flow)
  - [Policy (enforcement)](android-security.md#policy-enforcement)
  - [Setup](android-security.md#setup)
  - [Server-Side Verification](android-security.md#server-side-verification)
  - [Server decode and verify checklist](android-security.md#server-decode-and-verify-checklist)
  - [Standard API sequence (reference)](android-security.md#standard-api-sequence-reference)
  - [Client errors and retries](android-security.md#client-errors-and-retries)
  - [Remediation dialogs](android-security.md#remediation-dialogs)
  - [Integrity Verdicts](android-security.md#integrity-verdicts)
- [Root & Emulator Detection](android-security.md#root--emulator-detection)
  - [Relationship to Play Integrity](android-security.md#relationship-to-play-integrity)
  - [Root Detection](android-security.md#root-detection)
  - [Emulator Detection](android-security.md#emulator-detection)
  - [Architecture Integration](android-security.md#architecture-integration)
  - [Handling Detection Results](android-security.md#handling-detection-results)
- [Screenshot & Screen Recording Prevention](android-security.md#screenshot--screen-recording-prevention)
  - [Prevent Screenshots (FLAG_SECURE)](android-security.md#prevent-screenshots-flag_secure)
  - [Per-Screen Screenshot Prevention in Compose](android-security.md#per-screen-screenshot-prevention-in-compose)
  - [Preventing Recent Apps Thumbnail](android-security.md#preventing-recent-apps-thumbnail)
  - [Hiding sensitive content from accessibility services](android-security.md#hiding-sensitive-content-from-accessibility-services)
- [Secure Database (Room 3)](android-security.md#secure-database-room-3)
  - [Building the database (driver required)](android-security.md#building-the-database-driver-required)
  - [SQLCipher / full-database encryption](android-security.md#sqlcipher--full-database-encryption)
  - [Sensitive Field Encryption](android-security.md#sensitive-field-encryption)
- [Secure Clipboard](android-security.md#secure-clipboard)
  - [Prevent Clipboard Leaks](android-security.md#prevent-clipboard-leaks)
  - [Android 13+ Clipboard Auto-Clear](android-security.md#android-13-clipboard-auto-clear)
- [WebView Security](android-security.md#webview-security)
  - [Secure WebView Configuration](android-security.md#secure-webview-configuration)
  - [Avoid `addJavascriptInterface` Attack Surface](android-security.md#avoid-addjavascriptinterface-attack-surface)
- [Content Provider Security](android-security.md#content-provider-security)
  - [Restrict Content Provider Access](android-security.md#restrict-content-provider-access)
  - [FileProvider for Secure File Sharing](android-security.md#fileprovider-for-secure-file-sharing)
  - [URI grants on outbound intents](android-security.md#uri-grants-on-outbound-intents)
- [ProGuard / R8 Hardening](android-security.md#proguard--r8-hardening)
  - [Manifest Security](android-security.md#manifest-security)
  - [Data Extraction Rules (API 31+)](android-security.md#data-extraction-rules-api-31)
- [CI/CD Security](android-security.md#cicd-security)
  - [Secrets Management](android-security.md#secrets-management)
  - [.gitignore Entries](android-security.md#gitignore-entries)
  - [Static Analysis in CI](android-security.md#static-analysis-in-ci)
- [Security Checklist](android-security.md#security-checklist)
  - [Network](android-security.md#network)
  - [Data at Rest](android-security.md#data-at-rest)
  - [Authentication](android-security.md#authentication)
  - [Privacy and Play policy](android-security.md#privacy-and-play-policy)
  - [App Hardening](android-security.md#app-hardening)
  - [Build & Deploy](android-security.md#build--deploy)
  - [Device Security](android-security.md#device-security)
- [Rules](android-security.md#rules)

### android-strictmode.md (235 lines)

Open when: StrictMode, cleartext detection, Compose stability diagnostics

- [Table of Contents](android-strictmode.md#table-of-contents)
- [1) Classic StrictMode (Thread + VM)](android-strictmode.md#1-classic-strictmode-thread--vm)
  - [ThreadPolicy Options](android-strictmode.md#threadpolicy-options)
  - [VmPolicy Options](android-strictmode.md#vmpolicy-options)
  - [Penalty Options](android-strictmode.md#penalty-options)
- [2) Compose Stability Guardrails](android-strictmode.md#2-compose-stability-guardrails)
  - [Stability Configuration File](android-strictmode.md#stability-configuration-file)
  - [Analyzing Compose Metrics](android-strictmode.md#analyzing-compose-metrics)
- [3) CI Guardrails (Optional)](android-strictmode.md#3-ci-guardrails-optional)
- [Uploading StrictMode Signals to Crash Reporters](android-strictmode.md#uploading-strictmode-signals-to-crash-reporters)
- [References](android-strictmode.md#references)

### android-theming.md (2139 lines)

Open when: Material 3 color roles, dynamic color, contrast, typography, shapes
Quick routing: [android-theming-quick.md](android-theming-quick.md)

- [Table of Contents](android-theming.md#table-of-contents)
- [Material 3 Theme System](android-theming.md#material-3-theme-system)
  - [Basic Theme Setup](android-theming.md#basic-theme-setup)
  - [Using in MainActivity](android-theming.md#using-in-mainactivity)
- [Color Schemes](android-theming.md#color-schemes)
  - [Full Color Role Reference (M3)](android-theming.md#full-color-role-reference-m3)
  - [Default Light and Dark Schemes](android-theming.md#default-light-and-dark-schemes)
  - [Generating Custom Color Schemes](android-theming.md#generating-custom-color-schemes)
  - [Using Colors in Composables](android-theming.md#using-colors-in-composables)
- [Color Pairing Rules](android-theming.md#color-pairing-rules)
  - [The pairing table](android-theming.md#the-pairing-table)
  - [Compose: pair containers and content explicitly](android-theming.md#compose-pair-containers-and-content-explicitly)
  - [Title vs supporting text on surfaces](android-theming.md#title-vs-supporting-text-on-surfaces)
  - [`*Fixed` / `*FixedDim`: keep tone constant across modes](android-theming.md#fixed--fixeddim-keep-tone-constant-across-modes)
  - [Cross-references](android-theming.md#cross-references)
- [`outline` vs `outlineVariant`](android-theming.md#outline-vs-outlinevariant)
  - [Compose: pick the role that matches the job](android-theming.md#compose-pick-the-role-that-matches-the-job)
  - [Cross-references](android-theming.md#cross-references)
- [Surface Container Hierarchy](android-theming.md#surface-container-hierarchy)
  - [Which level for what](android-theming.md#which-level-for-what)
  - [Compose nesting example](android-theming.md#compose-nesting-example)
  - [Avoid `surfaceVariant` for new containers](android-theming.md#avoid-surfacevariant-for-new-containers)
- [Tonal Elevation vs Shadows](android-theming.md#tonal-elevation-vs-shadows)
  - [Map elevation level to surface role](android-theming.md#map-elevation-level-to-surface-role)
  - [Compose: prefer container role, add shadow only when needed](android-theming.md#compose-prefer-container-role-add-shadow-only-when-needed)
  - [Hover/focus, not resting](android-theming.md#hoverfocus-not-resting)
  - [Cross-references](android-theming.md#cross-references)
- [Dynamic Color (Material You)](android-theming.md#dynamic-color-material-you)
  - [Enabling Dynamic Color](android-theming.md#enabling-dynamic-color)
  - [User Preference for Dynamic Color](android-theming.md#user-preference-for-dynamic-color)
  - [Conditional Dynamic Color Support](android-theming.md#conditional-dynamic-color-support)
- [User Contrast Preference (Android 14+)](android-theming.md#user-contrast-preference-android-14)
  - [Generate the contrast scheme variants](android-theming.md#generate-the-contrast-scheme-variants)
  - [Compose helper: read contrast reactively](android-theming.md#compose-helper-read-contrast-reactively)
  - [Plug into `AppTheme`](android-theming.md#plug-into-apptheme)
  - [What this does **not** replace](android-theming.md#what-this-does-not-replace)
  - [Testing](android-theming.md#testing)
- [Typography Scales](android-theming.md#typography-scales)
  - [Default Typography](android-theming.md#default-typography)
  - [Using Typography](android-theming.md#using-typography)
  - [Android 16 (API 36) Font Changes](android-theming.md#android-16-api-36-font-changes)
  - [Adding Custom Fonts](android-theming.md#adding-custom-fonts)
- [Shape Theming](android-theming.md#shape-theming)
  - [Default Shapes](android-theming.md#default-shapes)
  - [Custom Shape Scales](android-theming.md#custom-shape-scales)
  - [Using Shapes](android-theming.md#using-shapes)
- [Material 3 Expressive](android-theming.md#material-3-expressive)
  - [Status](android-theming.md#status)
  - [Opt-in](android-theming.md#opt-in)
  - [Wiring](android-theming.md#wiring)
  - [What changes vs `MaterialTheme`](android-theming.md#what-changes-vs-materialtheme)
  - [When to adopt](android-theming.md#when-to-adopt)
- [Dark/Light Mode Switching](android-theming.md#darklight-mode-switching)
  - [System Default](android-theming.md#system-default)
  - [User-Controlled Theme](android-theming.md#user-controlled-theme)
  - [Theme Switcher UI](android-theming.md#theme-switcher-ui)
  - [WebView content follows the app theme](android-theming.md#webview-content-follows-the-app-theme)
- [Theme Preferences](android-theming.md#theme-preferences)
  - [DataStore Implementation](android-theming.md#datastore-implementation)
  - [Repository](android-theming.md#repository)
  - [Hilt Module](android-theming.md#hilt-module)
- [Custom Theme Attributes](android-theming.md#custom-theme-attributes)
  - [Extended Color Scheme](android-theming.md#extended-color-scheme)
  - [Providing Extended Colors](android-theming.md#providing-extended-colors)
  - [Using Extended Colors](android-theming.md#using-extended-colors)
  - [Brand Color Harmonization](android-theming.md#brand-color-harmonization)
- [Scoped Themes](android-theming.md#scoped-themes)
  - [Rule: `copy()` from the outer scheme, never rebuild](android-theming.md#rule-copy-from-the-outer-scheme-never-rebuild)
  - [Common scoped-theme patterns](android-theming.md#common-scoped-theme-patterns)
  - [Don'ts](android-theming.md#donts)
- [Architecture Integration](android-theming.md#architecture-integration)
  - [ViewModel Integration](android-theming.md#viewmodel-integration)
  - [App-Level Theme State](android-theming.md#app-level-theme-state)
- [Testing](android-theming.md#testing)
  - [Fake Theme Repository](android-theming.md#fake-theme-repository)
  - [Testing Theme Changes](android-theming.md#testing-theme-changes)
  - [UI Testing with Theme](android-theming.md#ui-testing-with-theme)
- [Layout Spacing and Component Dimensions](android-theming.md#layout-spacing-and-component-dimensions)
- [Reserved Resource Names](android-theming.md#reserved-resource-names)
- [Visual Style by App Category](android-theming.md#visual-style-by-app-category)
- [Theme routing](android-theming.md#theme-routing)
  - [Required](android-theming.md#required)
  - [Forbidden](android-theming.md#forbidden)
  - [Color Naming Convention](android-theming.md#color-naming-convention)
  - [Theme Transitions](android-theming.md#theme-transitions)
  - [Preview with Themes](android-theming.md#preview-with-themes)
  - [Material Theme Builder](android-theming.md#material-theme-builder)
  - [Dynamic Color Considerations](android-theming.md#dynamic-color-considerations)
- [References](android-theming.md#references)

### architecture.md (975 lines)

Open when: MVVM layers, repositories, DI, network, DataStore vs Room

- [Table of Contents](architecture.md#table-of-contents)
- [Architecture Overview](architecture.md#architecture-overview)
- [Architecture Principles](architecture.md#architecture-principles)
  - [Stack defaults (greenfield)](architecture.md#stack-defaults-greenfield)
- [Cross-cutting anti-patterns (quick reference)](architecture.md#cross-cutting-anti-patterns-quick-reference)
- [Module Structure](architecture.md#module-structure)
- [Data Layer](architecture.md#data-layer)
  - [Principles](architecture.md#principles)
  - [Repository Pattern](architecture.md#repository-pattern)
  - [Data Sources](architecture.md#data-sources)
  - [DataStore (Preferences & Typed)](architecture.md#datastore-preferences--typed)
  - [Network Layer Setup (core/network)](architecture.md#network-layer-setup-corenetwork)
  - [Model Mapping Strategy](architecture.md#model-mapping-strategy)
  - [Domain-Specific Error Types](architecture.md#domain-specific-error-types)
  - [Data Synchronization](architecture.md#data-synchronization)
- [Domain Layer](architecture.md#domain-layer)
  - [Purpose](architecture.md#purpose)
  - [Module Setup](architecture.md#module-setup)
  - [Dependency Injection Setup](architecture.md#dependency-injection-setup)
    - [`hiltViewModel()` artifact and import](architecture.md#hiltviewmodel-artifact-and-import)
  - [Use Case Pattern](architecture.md#use-case-pattern)
  - [Repository Interface Pattern](architecture.md#repository-interface-pattern)
  - [Domain Models](architecture.md#domain-models)
- [Presentation Layer](architecture.md#presentation-layer)
  - [Location: Feature modules (`feature/*`)](architecture.md#location-feature-modules-feature)
  - [Components](architecture.md#components)
  - [ViewModel placement](architecture.md#viewmodel-placement)
  - [UiState, Actions, and ViewModel Patterns](architecture.md#uistate-actions-and-viewmodel-patterns)
- [UI Layer](architecture.md#ui-layer)
  - [Location: `core/ui` (shared) and feature modules (specific)](architecture.md#location-coreui-shared-and-feature-modules-specific)
  - [Screen Composition and Shared UI Components](architecture.md#screen-composition-and-shared-ui-components)
- [Navigation](architecture.md#navigation)
- [Complete Architecture Flow](architecture.md#complete-architecture-flow)
  - [User Interaction Flow (UI → Data):](architecture.md#user-interaction-flow-ui--data)
  - [Data Response Flow (Data → UI):](architecture.md#data-response-flow-data--ui)
  - [Navigation Flow (Feature Coordination):](architecture.md#navigation-flow-feature-coordination)
- [Combined Complete Flow Diagram:](architecture.md#combined-complete-flow-diagram)
- [Key Flow Rules:](architecture.md#key-flow-rules)
  - [1. **Unidirectional Event Flow (DOWN):**](architecture.md#1-unidirectional-event-flow-down)
  - [2. **Unidirectional Data Flow (UP):**](architecture.md#2-unidirectional-data-flow-up)
  - [3. **Unidirectional Navigation Flow:**](architecture.md#3-unidirectional-navigation-flow)
- [Concrete Example Flow: Resetting a Password](architecture.md#concrete-example-flow-resetting-a-password)
  - [Phase 1: User Interaction (Event Flow DOWN)](architecture.md#phase-1-user-interaction-event-flow-down)
  - [Phase 2: Data Response (Data Flow UP)](architecture.md#phase-2-data-response-data-flow-up)
  - [Phase 3: Navigation Example (Separate Flow)](architecture.md#phase-3-navigation-example-separate-flow)
- [Cross-references](architecture.md#cross-references)

### code-quality.md (349 lines)

Open when: Detekt convention plugin, custom rules, CI

- [Table of Contents](code-quality.md#table-of-contents)
- [Version Catalog](code-quality.md#version-catalog)
  - [Detekt 2.x coordinates and pairing](code-quality.md#detekt-2x-coordinates-and-pairing)
- [Detekt Convention Plugin (Build Logic)](code-quality.md#detekt-convention-plugin-build-logic)
  - [Build Logic Registration](code-quality.md#build-logic-registration)
- [Apply in Modules](code-quality.md#apply-in-modules)
- [Running Detekt](code-quality.md#running-detekt)
  - [Local Development](code-quality.md#local-development)
  - [Excluding Generated Code](code-quality.md#excluding-generated-code)
- [Baselines & CI](code-quality.md#baselines--ci)
  - [Detekt baseline routing](code-quality.md#detekt-baseline-routing)
  - [Creating Per-Module Baselines](code-quality.md#creating-per-module-baselines)
  - [CI Integration](code-quality.md#ci-integration)
- [Compose Rules](code-quality.md#compose-rules)
- [Suppressing Violations](code-quality.md#suppressing-violations)
  - [Acceptable Suppressions for Compose](code-quality.md#acceptable-suppressions-for-compose)
  - [Targeted Suppressions](code-quality.md#targeted-suppressions)
  - [Forbidden suppressions](code-quality.md#forbidden-suppressions)
- [Suppression rules](code-quality.md#suppression-rules)

### compose-patterns.md (4202 lines)

Open when: Screens, state, side effects, lists, edge-to-edge, forms, animation
Quick routing: [compose-patterns-quick.md](compose-patterns-quick.md)

- [Table of Contents](compose-patterns.md#table-of-contents)
- [Screen Architecture](compose-patterns.md#screen-architecture)
  - [Feature Screen Pattern](compose-patterns.md#feature-screen-pattern)
- [Naming Conventions](compose-patterns.md#naming-conventions)
  - [Components](compose-patterns.md#components)
  - [Factory Functions](compose-patterns.md#factory-functions)
- [State Management](compose-patterns.md#state-management)
  - [Loading and refresh UX](compose-patterns.md#loading-and-refresh-ux)
  - [Sealed Interface for UI State](compose-patterns.md#sealed-interface-for-ui-state)
  - [Actions Pattern for User Interactions](compose-patterns.md#actions-pattern-for-user-interactions)
  - [ViewModel with Form State](compose-patterns.md#viewmodel-with-form-state)
  - [Initial Data Load Strategies](compose-patterns.md#initial-data-load-strategies)
  - [State Collection with Lifecycle](compose-patterns.md#state-collection-with-lifecycle)
  - [Lifecycle-Aware Flow Collection for Side Effects](compose-patterns.md#lifecycle-aware-flow-collection-for-side-effects)
  - [Primitive State Specializations](compose-patterns.md#primitive-state-specializations)
  - [snapshotFlow - Compose State to Flow](compose-patterns.md#snapshotflow---compose-state-to-flow)
  - [SnapshotStateList and SnapshotStateMap](compose-patterns.md#snapshotstatelist-and-snapshotstatemap)
  - [remember, retain, rememberSaveable, and rememberSerializable](compose-patterns.md#remember-retain-remembersaveable-and-rememberserializable)
  - [Edge-to-Edge (Mandatory on API 36)](compose-patterns.md#edge-to-edge-mandatory-on-api-36)
  - [Predictive Back (Mandatory on API 36)](compose-patterns.md#predictive-back-mandatory-on-api-36)
  - [Adaptive Layouts (Mandatory on API 36+ for Large Screens)](compose-patterns.md#adaptive-layouts-mandatory-on-api-36-for-large-screens)
  - [Handling System Back Button](compose-patterns.md#handling-system-back-button)
- [Component Patterns](compose-patterns.md#component-patterns)
  - [Stateless, Reusable Components](compose-patterns.md#stateless-reusable-components)
  - [Adaptive List Components](compose-patterns.md#adaptive-list-components)
  - [Shared Loading & Error States](compose-patterns.md#shared-loading--error-states)
  - [Card Variants (Filled / Outlined / Elevated)](compose-patterns.md#card-variants-filled--outlined--elevated)
  - [Touch Targets](compose-patterns.md#touch-targets)
  - [Haptic Feedback](compose-patterns.md#haptic-feedback)
- [Adaptive UI](compose-patterns.md#adaptive-ui)
  - [Large and extra-large widths (WindowManager 1.5)](compose-patterns.md#large-and-extra-large-widths-windowmanager-15)
  - [Adaptive Navigation with NavigationSuiteScaffold](compose-patterns.md#adaptive-navigation-with-navigationsuitescaffold)
  - [List-Detail Layout (NavigableListDetailPaneScaffold)](compose-patterns.md#list-detail-layout-navigablelistdetailpanescaffold)
    - [Pane adapt strategies (Material 3 Adaptive 1.2+)](compose-patterns.md#pane-adapt-strategies-material-3-adaptive-12)
  - [Supporting Pane Layout (NavigableSupportingPaneScaffold)](compose-patterns.md#supporting-pane-layout-navigablesupportingpanescaffold)
  - [Extracting Pane Composables](compose-patterns.md#extracting-pane-composables)
- [Theming & Design System](compose-patterns.md#theming--design-system)
  - [Material 3 Theme](compose-patterns.md#material-3-theme)
  - [Custom Design Tokens](compose-patterns.md#custom-design-tokens)
  - [Component Shape Defaults](compose-patterns.md#component-shape-defaults)
  - [Component-Specific Themes](compose-patterns.md#component-specific-themes)
- [Previews & Testing](compose-patterns.md#previews--testing)
  - [Comprehensive Preview Setup](compose-patterns.md#comprehensive-preview-setup)
  - [Preview with Realistic Data](compose-patterns.md#preview-with-realistic-data)
  - [Preview Parameter Providers](compose-patterns.md#preview-parameter-providers)
  - [Preview wrappers (Compose 1.11+)](compose-patterns.md#preview-wrappers-compose-111)
  - [Stability Annotations: `@Immutable` vs `@Stable`](compose-patterns.md#stability-annotations-immutable-vs-stable)
  - [Lazy Composition](compose-patterns.md#lazy-composition)
  - [State Hoisting for Performance](compose-patterns.md#state-hoisting-for-performance)
  - [Hoistable Stable State Pattern](compose-patterns.md#hoistable-stable-state-pattern)
  - [`remember` and lambda routing](compose-patterns.md#remember-and-lambda-routing)
- [Animation](compose-patterns.md#animation)
  - [State-Based Animations](compose-patterns.md#state-based-animations)
  - [Coordinated Animations](compose-patterns.md#coordinated-animations)
  - [Imperative Animation Control](compose-patterns.md#imperative-animation-control)
  - [Animation Specifications](compose-patterns.md#animation-specifications)
  - [Material Design motion (duration and easing)](compose-patterns.md#material-design-motion-duration-and-easing)
  - [Layout Animations](compose-patterns.md#layout-animations)
  - [Shared Element Transitions](compose-patterns.md#shared-element-transitions)
  - [graphicsLayer for Animation Performance](compose-patterns.md#graphicslayer-for-animation-performance)
  - [Animation Anti-Patterns](compose-patterns.md#animation-anti-patterns)
- [Side Effects](compose-patterns.md#side-effects)
  - [LaunchedEffect - Coroutines Scoped to Composition](compose-patterns.md#launchedeffect---coroutines-scoped-to-composition)
  - [DisposableEffect - Resource Cleanup](compose-patterns.md#disposableeffect---resource-cleanup)
  - [SideEffect - After Every Composition](compose-patterns.md#sideeffect---after-every-composition)
  - [rememberCoroutineScope - Launching from Event Handlers](compose-patterns.md#remembercoroutinescope---launching-from-event-handlers)
  - [rememberUpdatedState - Capturing Latest Values](compose-patterns.md#rememberupdatedstate---capturing-latest-values)
  - [produceState - Converting External State to Compose State](compose-patterns.md#producestate---converting-external-state-to-compose-state)
  - [LifecycleResumeEffect - onResume / onPause](compose-patterns.md#lifecycleresumeeffect---onresume--onpause)
  - [LifecycleStartEffect - onStart / onStop](compose-patterns.md#lifecyclestarteffect---onstart--onstop)
  - [Effect Decision Guide](compose-patterns.md#effect-decision-guide)
  - [Side Effect Anti-Patterns](compose-patterns.md#side-effect-anti-patterns)
- [Modifiers](compose-patterns.md#modifiers)
  - [Modifier Chain Ordering](compose-patterns.md#modifier-chain-ordering)
  - [Common Modifier Patterns](compose-patterns.md#common-modifier-patterns)
  - [Clickable and CombinedClickable](compose-patterns.md#clickable-and-combinedclickable)
  - [Conditional Modifiers](compose-patterns.md#conditional-modifiers)
  - [Custom Modifiers with Modifier.Node](compose-patterns.md#custom-modifiers-with-modifiernode)
  - [Layout vs Drawing vs Pointer Input](compose-patterns.md#layout-vs-drawing-vs-pointer-input)
  - [Trackpad and mouse input (Compose 1.11+)](compose-patterns.md#trackpad-and-mouse-input-compose-111)
  - [graphicsLayer - GPU Transforms](compose-patterns.md#graphicslayer---gpu-transforms)
  - [Semantics and TestTag](compose-patterns.md#semantics-and-testtag)
  - [Always Accept Modifier Parameter](compose-patterns.md#always-accept-modifier-parameter)
  - [Modifier Anti-Patterns](compose-patterns.md#modifier-anti-patterns)
- [CompositionLocal](compose-patterns.md#compositionlocal)
  - [compositionLocalOf vs staticCompositionLocalOf](compose-patterns.md#compositionlocalof-vs-staticcompositionlocalof)
  - [Providing and Reading Values](compose-patterns.md#providing-and-reading-values)
  - [Built-In CompositionLocals](compose-patterns.md#built-in-compositionlocals)
  - [CompositionLocal routing](compose-patterns.md#compositionlocal-routing)
  - [CompositionLocal Anti-Patterns](compose-patterns.md#compositionlocal-anti-patterns)
- [Lists & Scrolling](compose-patterns.md#lists--scrolling)
  - [Paging 3](compose-patterns.md#paging-3)
  - [Flow Layouts](compose-patterns.md#flow-layouts)
  - [contentType for Recycling Optimization](compose-patterns.md#contenttype-for-recycling-optimization)
  - [LazyListState - Programmatic Scrolling](compose-patterns.md#lazyliststate---programmatic-scrolling)
  - [Sticky Headers](compose-patterns.md#sticky-headers)
  - [Grids](compose-patterns.md#grids)
  - [Staggered Grid](compose-patterns.md#staggered-grid)
  - [Pager](compose-patterns.md#pager)
  - [Nested Scrolling Pitfalls](compose-patterns.md#nested-scrolling-pitfalls)
  - [Trackpad and mouse input (Compose 1.11)](compose-patterns.md#trackpad-and-mouse-input-compose-111)
  - [Lists Rules](compose-patterns.md#lists-rules)
- [View Composition Rules](compose-patterns.md#view-composition-rules)
  - [Composable Naming](compose-patterns.md#composable-naming)
  - [Slot Pattern](compose-patterns.md#slot-pattern)
  - [Never Return Values from Composables](compose-patterns.md#never-return-values-from-composables)
  - [Screen-Level Composable Structure](compose-patterns.md#screen-level-composable-structure)
  - [Extraction Guidelines](compose-patterns.md#extraction-guidelines)
- [Deprecated Patterns & Migrations](compose-patterns.md#deprecated-patterns--migrations)
  - [Material 3 API replacements](compose-patterns.md#material-3-api-replacements)
  - [Compose 1.11 additions worth adopting](compose-patterns.md#compose-111-additions-worth-adopting)
  - [Experimental in Compose 1.11 - evaluation only](compose-patterns.md#experimental-in-compose-111---evaluation-only)
- [Forms & Input](compose-patterns.md#forms--input)
  - [Keyboard Configuration](compose-patterns.md#keyboard-configuration)
  - [Autofill](compose-patterns.md#autofill)
  - [Password Visibility Toggle](compose-patterns.md#password-visibility-toggle)
  - [Validation Timing](compose-patterns.md#validation-timing)
- [Cross-references](compose-patterns.md#cross-references)

### coroutines-patterns.md (1633 lines)

Open when: Dispatchers, Flow, StateFlow, testing coroutines, callbackFlow
Quick routing: [coroutines-patterns-quick.md](coroutines-patterns-quick.md)

- [Table of Contents](coroutines-patterns.md#table-of-contents)
- [Android coroutine rules](coroutines-patterns.md#android-coroutine-rules)
  - [Inject Dispatchers (Avoid Hardcoding)](coroutines-patterns.md#inject-dispatchers-avoid-hardcoding)
  - [Use `limitedParallelism` for Custom Dispatcher Pools](coroutines-patterns.md#use-limitedparallelism-for-custom-dispatcher-pools)
  - [Structured concurrency (not `GlobalScope`)](coroutines-patterns.md#structured-concurrency-not-globalscope)
  - [Make Coroutines Cancellable](coroutines-patterns.md#make-coroutines-cancellable)
  - [Handle Exceptions Carefully](coroutines-patterns.md#handle-exceptions-carefully)
  - [Do Not Catch `Throwable`](coroutines-patterns.md#do-not-catch-throwable)
  - [StateFlow for new code (not LiveData)](coroutines-patterns.md#stateflow-for-new-code-not-livedata)
  - [Convert Cold Flows to Hot StateFlows with `stateIn`](coroutines-patterns.md#convert-cold-flows-to-hot-stateflows-with-statein)
  - [Share Expensive Upstream with `shareIn`](coroutines-patterns.md#share-expensive-upstream-with-sharein)
  - [Combine Multiple Flows with `combine`](coroutines-patterns.md#combine-multiple-flows-with-combine)
  - [Avoid `async` with Immediate `await`](coroutines-patterns.md#avoid-async-with-immediate-await)
  - [`launch` vs `async` vs `withContext`](coroutines-patterns.md#launch-vs-async-vs-withcontext)
  - [Use `awaitAll` for Parallel Work](coroutines-patterns.md#use-awaitall-for-parallel-work)
  - [Keep Suspend/Flow Thread-Safe](coroutines-patterns.md#keep-suspendflow-thread-safe)
  - [Avoid Nested `withContext` Chains](coroutines-patterns.md#avoid-nested-withcontext-chains)
  - [Avoid Blocking Calls in Coroutines](coroutines-patterns.md#avoid-blocking-calls-in-coroutines)
  - [`coroutineScope` vs `supervisorScope` - Failure Propagation](coroutines-patterns.md#coroutinescope-vs-supervisorscope---failure-propagation)
  - [`supervisorScope` vs `SupervisorJob` - Independent Child Failures](coroutines-patterns.md#supervisorscope-vs-supervisorjob---independent-child-failures)
  - [Functions Returning `Flow` Should Not Be `suspend`](coroutines-patterns.md#functions-returning-flow-should-not-be-suspend)
  - [Use `flatMapLatest` for Sequential Flow Switching, `flatMapMerge` for Concurrent](coroutines-patterns.md#use-flatmaplatest-for-sequential-flow-switching-flatmapmerge-for-concurrent)
  - [Backpressure & Rate Limiting](coroutines-patterns.md#backpressure--rate-limiting)
  - [`suspend` for one-off values](coroutines-patterns.md#suspend-for-one-off-values)
  - [Coroutine names for long-lived work](coroutines-patterns.md#coroutine-names-for-long-lived-work)
  - [Avoid `Job` in `withContext` or Ad-Hoc `Job()` Usage](coroutines-patterns.md#avoid-job-in-withcontext-or-ad-hoc-job-usage)
  - [Yield During Heavy Work](coroutines-patterns.md#yield-during-heavy-work)
  - [ViewModels Should Launch Coroutines (Not Expose `suspend`)](coroutines-patterns.md#viewmodels-should-launch-coroutines-not-expose-suspend)
  - [Repositories/Use Cases Should Not Launch Coroutines](coroutines-patterns.md#repositoriesuse-cases-should-not-launch-coroutines)
  - [Treat NonCancellable as a Last Resort](coroutines-patterns.md#treat-noncancellable-as-a-last-resort)
  - [Timeouts for hardware and uncontrolled APIs](coroutines-patterns.md#timeouts-for-hardware-and-uncontrolled-apis)
- [Bridging Imperative Callbacks to Coroutines](coroutines-patterns.md#bridging-imperative-callbacks-to-coroutines)
  - [`callbackFlow` - Callback Stream to Flow](coroutines-patterns.md#callbackflow---callback-stream-to-flow)
  - [Core Pattern](coroutines-patterns.md#core-pattern)
  - [`suspendCancellableCoroutine` - One-Shot Callback to Suspend](coroutines-patterns.md#suspendcancellablecoroutine---one-shot-callback-to-suspend)
  - [Preserve Error Shape in Bridge APIs](coroutines-patterns.md#preserve-error-shape-in-bridge-apis)
- [Common Pitfalls](coroutines-patterns.md#common-pitfalls)
  - [Redundant SupervisorJob in ViewModel](coroutines-patterns.md#redundant-supervisorjob-in-viewmodel)
  - [Unawaited async in supervisorScope](coroutines-patterns.md#unawaited-async-in-supervisorscope)
  - [Side Effects Inside combine/map Transforms](coroutines-patterns.md#side-effects-inside-combinemap-transforms)
  - [Collecting a Flow Inside a Transform](coroutines-patterns.md#collecting-a-flow-inside-a-transform)
  - [Manual Job Cancellation Instead of flatMapLatest](coroutines-patterns.md#manual-job-cancellation-instead-of-flatmaplatest)
  - [`emit` vs `tryEmit`](coroutines-patterns.md#emit-vs-tryemit)
  - [Using emit() on MutableStateFlow](coroutines-patterns.md#using-emit-on-mutablestateflow)
- [Coexisting with RxJava (Legacy Code)](coroutines-patterns.md#coexisting-with-rxjava-legacy-code)

### crashlytics.md (726 lines)

Open when: Firebase/Sentry interfaces, breadcrumbs, PII scrubbing

- [Table of Contents](crashlytics.md#table-of-contents)
- [Architecture Placement](crashlytics.md#architecture-placement)
- [Provider-Agnostic Interface](crashlytics.md#provider-agnostic-interface)
- [Implementation Examples](crashlytics.md#implementation-examples)
  - [Firebase Crashlytics](crashlytics.md#firebase-crashlytics)
  - [Sentry](crashlytics.md#sentry)
- [Sentry Setup (Convention Plugin + Compose)](crashlytics.md#sentry-setup-convention-plugin--compose)
  - [Manifest Configuration](crashlytics.md#manifest-configuration)
  - [Application Initialization (Sentry)](crashlytics.md#application-initialization-sentry)
  - [Jetpack Compose Specifics](crashlytics.md#jetpack-compose-specifics)
- [Firebase Crashlytics Setup (Convention Plugin + Compose)](crashlytics.md#firebase-crashlytics-setup-convention-plugin--compose)
  - [Application Initialization (Firebase)](crashlytics.md#application-initialization-firebase)
  - [Compose Screen Tracking (Navigation3)](crashlytics.md#compose-screen-tracking-navigation3)
  - [Capturing UI State (Delegation)](crashlytics.md#capturing-ui-state-delegation)
  - [Non-fatal Exceptions in Coroutines](crashlytics.md#non-fatal-exceptions-in-coroutines)
- [Wiring in the App Module](crashlytics.md#wiring-in-the-app-module)
  - [Using Firebase Crashlytics](crashlytics.md#using-firebase-crashlytics)
  - [Using Sentry](crashlytics.md#using-sentry)
- [Rules](crashlytics.md#rules)
- [ProGuard/R8 Mapping Upload](crashlytics.md#proguardr8-mapping-upload)
  - [Firebase Crashlytics](crashlytics.md#firebase-crashlytics)
  - [Sentry](crashlytics.md#sentry)
- [Breadcrumbs](crashlytics.md#breadcrumbs)
- [Network Request Tracking](crashlytics.md#network-request-tracking)
  - [Failed Network Requests](crashlytics.md#failed-network-requests)
- [Testing Crash Reporting](crashlytics.md#testing-crash-reporting)
  - [Test Crashes in Development](crashlytics.md#test-crashes-in-development)
  - [Disable Crash Reporting in Debug (Optional)](crashlytics.md#disable-crash-reporting-in-debug-optional)
- [Data Scrubbing (Privacy/GDPR)](crashlytics.md#data-scrubbing-privacygdpr)
  - [Built-in Scrubbing (Sentry)](crashlytics.md#built-in-scrubbing-sentry)
  - [Custom Scrubbing for Both Providers](crashlytics.md#custom-scrubbing-for-both-providers)
- [Gradle & Setup Guidance](crashlytics.md#gradle--setup-guidance)

### dependencies.md (382 lines)

Open when: Version catalog, BOMs, pins, brownfield alignment, adding dependencies

- [Table of Contents](dependencies.md#table-of-contents)
- [Version Catalog Source of Truth](dependencies.md#version-catalog-source-of-truth)
  - [Rules](dependencies.md#rules)
- [Dependency Selection](dependencies.md#dependency-selection)
  - [Room 3](dependencies.md#room-3)
  - [Merged KTX artifacts (do not add the `-ktx` coordinate)](dependencies.md#merged-ktx-artifacts-do-not-add-the--ktx-coordinate)
  - [androidx.hilt artifacts](dependencies.md#androidxhilt-artifacts)
  - [Media3](dependencies.md#media3)
  - [Navigation3 and SavedState](dependencies.md#navigation3-and-savedstate)
  - [Paging 3 test artifact](dependencies.md#paging-3-test-artifact)
- [Version Strategy](dependencies.md#version-strategy)
  - [Existing project (brownfield)](dependencies.md#existing-project-brownfield)
  - [Stability Requirements](dependencies.md#stability-requirements)
  - [Pinned prerelease required for feature parity](dependencies.md#pinned-prerelease-required-for-feature-parity)
  - [Visual regression tooling (catalog)](dependencies.md#visual-regression-tooling-catalog)
  - [Version update cadence](dependencies.md#version-update-cadence)
  - [Version Conflict Resolution](dependencies.md#version-conflict-resolution)
- [Kotlin & Compose Compiler Compatibility](dependencies.md#kotlin--compose-compiler-compatibility)
  - [Kotlin requires a matching AGP / R8](dependencies.md#kotlin-requires-a-matching-agp--r8)
- [Platform Dependencies (BOMs)](dependencies.md#platform-dependencies-boms)
  - [Not covered by the Compose BOM](dependencies.md#not-covered-by-the-compose-bom)
- [Testing Dependencies](dependencies.md#testing-dependencies)
  - [Test Scopes](dependencies.md#test-scopes)
  - [Test Bundles](dependencies.md#test-bundles)
- [Build Performance Considerations](dependencies.md#build-performance-considerations)
  - [`api` vs `implementation`](dependencies.md#api-vs-implementation)
  - [Annotation Processing: KSP > Kapt](dependencies.md#annotation-processing-ksp--kapt)
- [ProGuard/R8 Considerations](dependencies.md#proguardr8-considerations)
- [Adding a New Dependency](dependencies.md#adding-a-new-dependency)

### design-patterns.md (1760 lines)

Open when: Gang-of-four style patterns adapted for Android modules
Quick routing: [design-patterns-quick.md](design-patterns-quick.md)

- [Table of Contents](design-patterns.md#table-of-contents)
- [Principles](design-patterns.md#principles)
- [Architectural Patterns](design-patterns.md#architectural-patterns)
  - [MVVM (Model-View-ViewModel)](design-patterns.md#mvvm-model-view-viewmodel)
  - [Repository Pattern](design-patterns.md#repository-pattern)
- [Creational Patterns](design-patterns.md#creational-patterns)
  - [Singleton](design-patterns.md#singleton)
  - [Factory Method](design-patterns.md#factory-method)
  - [Abstract Factory](design-patterns.md#abstract-factory)
  - [Builder](design-patterns.md#builder)
  - [Prototype](design-patterns.md#prototype)
- [Structural Patterns](design-patterns.md#structural-patterns)
  - [Adapter](design-patterns.md#adapter)
  - [Bridge](design-patterns.md#bridge)
  - [Composite](design-patterns.md#composite)
  - [Decorator](design-patterns.md#decorator)
  - [Delegation](design-patterns.md#delegation)
  - [Facade](design-patterns.md#facade)
  - [Flyweight](design-patterns.md#flyweight)
  - [Proxy](design-patterns.md#proxy)
- [Behavioral Patterns](design-patterns.md#behavioral-patterns)
  - [Observer](design-patterns.md#observer)
  - [Strategy](design-patterns.md#strategy)
  - [Chain of Responsibility](design-patterns.md#chain-of-responsibility)
  - [Command](design-patterns.md#command)
  - [Iterator](design-patterns.md#iterator)
  - [Mediator](design-patterns.md#mediator)
  - [Memento](design-patterns.md#memento)
  - [State](design-patterns.md#state)
  - [Template Method](design-patterns.md#template-method)
  - [Visitor](design-patterns.md#visitor)
- [Kotlin-Specific Patterns](design-patterns.md#kotlin-specific-patterns)
  - [Result Type](design-patterns.md#result-type)
  - [Sealed Classes for Exhaustive State](design-patterns.md#sealed-classes-for-exhaustive-state)
  - [Data Classes with Copy](design-patterns.md#data-classes-with-copy)
  - [Extension Functions for Domain Logic](design-patterns.md#extension-functions-for-domain-logic)
- [Anti-Patterns to Avoid](design-patterns.md#anti-patterns-to-avoid)
  - [Static Context References](design-patterns.md#static-context-references)
  - [LiveData in New Code](design-patterns.md#livedata-in-new-code)
  - [God Objects](design-patterns.md#god-objects)
  - [GlobalScope Usage](design-patterns.md#globalscope-usage)
  - [Mutable Collections in Data Classes](design-patterns.md#mutable-collections-in-data-classes)
  - [Premature Abstraction](design-patterns.md#premature-abstraction)
  - [Nested Callbacks (Callback Hell)](design-patterns.md#nested-callbacks-callback-hell)
  - [Feature-to-Feature Dependencies](design-patterns.md#feature-to-feature-dependencies)
- [Room Database Patterns](design-patterns.md#room-database-patterns)
  - [The `@Upsert` Caveat](design-patterns.md#the-upsert-caveat)
  - [Critical Performance Rules](design-patterns.md#critical-performance-rules)
  - [Full-Text Search (FTS) Pattern](design-patterns.md#full-text-search-fts-pattern)

### gradle-setup.md (1321 lines)

Open when: Convention plugins, flavors, R8 audit, build performance, verify Gradle

- [Verify after toolchain or module changes](gradle-setup.md#verify-after-toolchain-or-module-changes)
- [AGP 9 Key Changes](gradle-setup.md#agp-9-key-changes)
  - [AGP 9 Migration: Post-Upgrade Cleanup](gradle-setup.md#agp-9-migration-post-upgrade-cleanup)
  - [kapt under AGP 9](gradle-setup.md#kapt-under-agp-9)
  - [Per-module escape hatches (temporary)](gradle-setup.md#per-module-escape-hatches-temporary)
  - [Built-in Kotlin (AGP 9)](gradle-setup.md#built-in-kotlin-agp-9)
  - [AGP version pin (resolve before merge)](gradle-setup.md#agp-version-pin-resolve-before-merge)
  - [AGP requires a minimum Gradle wrapper](gradle-setup.md#agp-requires-a-minimum-gradle-wrapper)
  - [Example tested stack (re-verify after every bump)](gradle-setup.md#example-tested-stack-re-verify-after-every-bump)
  - [AGP 9 Verification](gradle-setup.md#agp-9-verification)
  - [AGP 9 Toolchain Compatibility Notes](gradle-setup.md#agp-9-toolchain-compatibility-notes)
- [Table of Contents](gradle-setup.md#table-of-contents)
- [Project Structure](gradle-setup.md#project-structure)
- [Version Catalog](gradle-setup.md#version-catalog)
- [Convention Plugins](gradle-setup.md#convention-plugins)
  - [Android and Compose plugin order](gradle-setup.md#android-and-compose-plugin-order)
  - [androidTest dependencies when androidTest is off](gradle-setup.md#androidtest-dependencies-when-androidtest-is-off)
  - [Build Logic Setup](gradle-setup.md#build-logic-setup)
  - [Convention Plugin Files](gradle-setup.md#convention-plugin-files)
  - [Registering a root-level reporting task (Play Vitals)](gradle-setup.md#registering-a-root-level-reporting-task-play-vitals)
- [Module Build Files](gradle-setup.md#module-build-files)
  - [App Module](gradle-setup.md#app-module)
  - [Feature Module](gradle-setup.md#feature-module)
  - [Core Domain Module (Pure Kotlin)](gradle-setup.md#core-domain-module-pure-kotlin)
  - [Core Data Module](gradle-setup.md#core-data-module)
  - [Core UI Module](gradle-setup.md#core-ui-module)
  - [Core Network Module](gradle-setup.md#core-network-module)
  - [Core Database Module](gradle-setup.md#core-database-module)
  - [Benchmark module](gradle-setup.md#benchmark-module)
  - [Build-managed devices](gradle-setup.md#build-managed-devices)
  - [Aggregated test and coverage reports (optional, AGP 9.2+)](gradle-setup.md#aggregated-test-and-coverage-reports-optional-agp-92)
  - [Compose stability analyzer](gradle-setup.md#compose-stability-analyzer)
- [Code Quality (Detekt)](gradle-setup.md#code-quality-detekt)
- [Build Variants & Optimization](gradle-setup.md#build-variants--optimization)
  - [Product Flavors for Different Environments](gradle-setup.md#product-flavors-for-different-environments)
  - [Build Optimization Configuration](gradle-setup.md#build-optimization-configuration)
  - [Non-Transitive R Classes](gradle-setup.md#non-transitive-r-classes)
  - [R8 and ProGuard Configuration](gradle-setup.md#r8-and-proguard-configuration)
    - [Legacy DSL (AGP < 9.3 only)](gradle-setup.md#legacy-dsl-agp--93-only)
    - [AGP 9 R8 defaults that change existing behavior](gradle-setup.md#agp-9-r8-defaults-that-change-existing-behavior)
    - [R8 option changes worth knowing](gradle-setup.md#r8-option-changes-worth-knowing)
    - [Incremental R8 adoption on a brownfield app (`packageScope`)](gradle-setup.md#incremental-r8-adoption-on-a-brownfield-app-packagescope)
  - [R8 Keep-Rules Audit](gradle-setup.md#r8-keep-rules-audit)
- [Build Performance](gradle-setup.md#build-performance)
  - [Settings Configuration](gradle-setup.md#settings-configuration)
  - [Root Build File](gradle-setup.md#root-build-file)
  - [Build Cache Configuration](gradle-setup.md#build-cache-configuration)
  - [Optimization Workflow](gradle-setup.md#optimization-workflow)
  - [Lazy Task Configuration](gradle-setup.md#lazy-task-configuration)
  - [Avoid I/O During Configuration](gradle-setup.md#avoid-io-during-configuration)
  - [Pin Dependency Versions](gradle-setup.md#pin-dependency-versions)
  - [Bottleneck Troubleshooting](gradle-setup.md#bottleneck-troubleshooting)
- [Rules](gradle-setup.md#rules)
- [Common Gradle Commands](gradle-setup.md#common-gradle-commands)
- [Cross-references](gradle-setup.md#cross-references)

### kotlin-delegation.md (750 lines)

Open when: Interface delegation instead of base ViewModels

- [Table of Contents](kotlin-delegation.md#table-of-contents)
- [Delegation routing](kotlin-delegation.md#delegation-routing)
- [Class Delegation](kotlin-delegation.md#class-delegation)
  - [Basic Pattern](kotlin-delegation.md#basic-pattern)
  - [Inheritance vs Delegation Comparison](kotlin-delegation.md#inheritance-vs-delegation-comparison)
  - [Multiple Interface Delegation](kotlin-delegation.md#multiple-interface-delegation)
  - [Overriding Delegated Methods](kotlin-delegation.md#overriding-delegated-methods)
  - [Form Validation with Sealed Errors](kotlin-delegation.md#form-validation-with-sealed-errors)
- [Property Delegation](kotlin-delegation.md#property-delegation)
  - [Lazy Initialization](kotlin-delegation.md#lazy-initialization)
  - [State Delegation with mutableStateOf](kotlin-delegation.md#state-delegation-with-mutablestateof)
  - [Observable Properties (Custom Delegates)](kotlin-delegation.md#observable-properties-custom-delegates)
- [Advanced Patterns](kotlin-delegation.md#advanced-patterns)
  - [Complex Real-World Example](kotlin-delegation.md#complex-real-world-example)
- [Testing with Delegation](kotlin-delegation.md#testing-with-delegation)
  - [Creating Test Fakes](kotlin-delegation.md#creating-test-fakes)
- [Rules](kotlin-delegation.md#rules)
  - [Interface shape](kotlin-delegation.md#interface-shape)
  - [Implementation](kotlin-delegation.md#implementation)
  - [Auditing Existing Base Classes](kotlin-delegation.md#auditing-existing-base-classes)
  - [Testing](kotlin-delegation.md#testing)
  - [Performance](kotlin-delegation.md#performance)
- [Related References](kotlin-delegation.md#related-references)
- [Sources](kotlin-delegation.md#sources)

### kotlin-patterns.md (1053 lines)

Open when: Kotlin style, Result types, ViewModel patterns (all Kotlin code)

- [Table of Contents](kotlin-patterns.md#table-of-contents)
- [Kotlin 2.x and the K2 Compiler](kotlin-patterns.md#kotlin-2x-and-the-k2-compiler)
  - [Behavioural differences vs K1](kotlin-patterns.md#behavioural-differences-vs-k1)
  - [Compose compiler](kotlin-patterns.md#compose-compiler)
  - [Explicit API mode](kotlin-patterns.md#explicit-api-mode)
  - [Things to remove on Kotlin 2.x](kotlin-patterns.md#things-to-remove-on-kotlin-2x)
- [Delegation (Composition over Inheritance)](kotlin-patterns.md#delegation-composition-over-inheritance)
- [Pragmatic layering & import hygiene](kotlin-patterns.md#pragmatic-layering--import-hygiene)
  - [Import hygiene](kotlin-patterns.md#import-hygiene)
  - [Use cases that only wrap repositories](kotlin-patterns.md#use-cases-that-only-wrap-repositories)
  - [State updates without extra type layers](kotlin-patterns.md#state-updates-without-extra-type-layers)
  - [Composable boundaries](kotlin-patterns.md#composable-boundaries)
- [Collection APIs](kotlin-patterns.md#collection-apis)
  - [Read-only collection APIs](kotlin-patterns.md#read-only-collection-apis)
  - [Use Explicit State Transitions for Collections](kotlin-patterns.md#use-explicit-state-transitions-for-collections)
  - [Persistent Collections for State](kotlin-patterns.md#persistent-collections-for-state)
- [Sealed Classes & Exhaustive When](kotlin-patterns.md#sealed-classes--exhaustive-when)
- [Generics & Reified Types](kotlin-patterns.md#generics--reified-types)
  - [Generic Result Wrapper](kotlin-patterns.md#generic-result-wrapper)
  - [Reified Type Parameters](kotlin-patterns.md#reified-type-parameters)
  - [Generic Collections with Bounds](kotlin-patterns.md#generic-collections-with-bounds)
- [Extension Functions](kotlin-patterns.md#extension-functions)
- [Inline Value Classes](kotlin-patterns.md#inline-value-classes)
- [Sequences for Lazy Evaluation](kotlin-patterns.md#sequences-for-lazy-evaluation)
  - [Avoid Memory Churn](kotlin-patterns.md#avoid-memory-churn)
- [Companion Objects](kotlin-patterns.md#companion-objects)
  - [Constants and Factory Methods](kotlin-patterns.md#constants-and-factory-methods)
- [Type Aliases](kotlin-patterns.md#type-aliases)
- [Destructuring](kotlin-patterns.md#destructuring)
- [Inline Functions & Reified Types](kotlin-patterns.md#inline-functions--reified-types)
  - [Inline Functions](kotlin-patterns.md#inline-functions)
  - [Reified Type Parameters](kotlin-patterns.md#reified-type-parameters)
  - [`noinline` and `crossinline`](kotlin-patterns.md#noinline-and-crossinline)
- [Named Arguments](kotlin-patterns.md#named-arguments)
- [Android View Lifecycle (Interop)](kotlin-patterns.md#android-view-lifecycle-interop)
- [Coroutines routing](kotlin-patterns.md#coroutines-routing)
  - [Structured Concurrency](kotlin-patterns.md#structured-concurrency)
  - [Generic Suspending Functions](kotlin-patterns.md#generic-suspending-functions)
- [Rules Summary](kotlin-patterns.md#rules-summary)

### migration.md (960 lines)

Open when: XML→Compose, LiveData, RxJava, Nav2→3, Room 2→3, API 37

- [Table of Contents](migration.md#table-of-contents)
- [XML to Compose](migration.md#xml-to-compose)
  - [Strategy: Screen-by-Screen](migration.md#strategy-screen-by-screen)
  - [Per-Screen Workflow (mandatory)](migration.md#per-screen-workflow-mandatory)
  - [Compose in XML (Adding Compose to Existing Screens)](migration.md#compose-in-xml-adding-compose-to-existing-screens)
  - [XML in Compose (Using Legacy Views in Compose Screens)](migration.md#xml-in-compose-using-legacy-views-in-compose-screens)
  - [Migration Checklist](migration.md#migration-checklist)
  - [Compose-XML interop (hardening)](migration.md#compose-xml-interop-hardening)
- [LiveData to StateFlow](migration.md#livedata-to-stateflow)
  - [ViewModel Migration](migration.md#viewmodel-migration)
  - [UI Collection](migration.md#ui-collection)
  - [Transformations](migration.md#transformations)
  - [Key Differences](migration.md#key-differences)
- [RxJava to Coroutines](migration.md#rxjava-to-coroutines)
  - [Coexistence (Migration Not Yet Planned)](migration.md#coexistence-migration-not-yet-planned)
  - [Disposal Management](migration.md#disposal-management)
  - [Paging with RxJava](migration.md#paging-with-rxjava)
  - [Migration Path (When Ready)](migration.md#migration-path-when-ready)
  - [Coexistence rules](migration.md#coexistence-rules)
- [Navigation 2.x to Navigation3](migration.md#navigation-2x-to-navigation3)
  - [Key Changes](migration.md#key-changes)
  - [Migration Steps](migration.md#migration-steps)
- [Accompanist to Official APIs](migration.md#accompanist-to-official-apis)
  - [System UI Controller -> enableEdgeToEdge()](migration.md#system-ui-controller---enableedgetoedge)
  - [Pager -> Foundation HorizontalPager/VerticalPager](migration.md#pager---foundation-horizontalpagerverticalpager)
  - [SwipeRefresh -> PullToRefreshBox](migration.md#swiperefresh---pulltorefreshbox)
  - [FlowLayout -> Foundation FlowRow/FlowColumn](migration.md#flowlayout---foundation-flowrowflowcolumn)
  - [Permissions -> activity-compose](migration.md#permissions---activity-compose)
- [Compose API Migrations](migration.md#compose-api-migrations)
  - [collectAsState -> collectAsStateWithLifecycle](migration.md#collectasstate---collectasstatewithlifecycle)
  - [mutableStateOf(0) -> mutableIntStateOf(0)](migration.md#mutablestateof0---mutableintstateof0)
  - [animateItemPlacement -> animateItem](migration.md#animateitemplacement---animateitem)
  - [Modifier.composed -> Modifier.Node](migration.md#modifiercomposed---modifiernode)
  - [Modifier.onFirstVisible -> Modifier.onVisibilityChanged](migration.md#modifieronfirstvisible---modifieronvisibilitychanged)
  - [String Routes -> Type-Safe Routes -> Navigation3](migration.md#string-routes---type-safe-routes---navigation3)
  - [@ExperimentalMaterial3Api Graduations](migration.md#experimentalmaterial3api-graduations)
  - [Scaffold innerPadding (Mandatory)](migration.md#scaffold-innerpadding-mandatory)
- [Material 2 to Material 3](migration.md#material-2-to-material-3)
- [Edge-to-Edge](migration.md#edge-to-edge)
- [Legacy splash to Splash Screen API](migration.md#legacy-splash-to-splash-screen-api)
- [Room 2.x to Room 3](migration.md#room-2x-to-room-3)
  - [Gradle and artifacts](migration.md#gradle-and-artifacts)
  - [Packages and generated code](migration.md#packages-and-generated-code)
  - [SupportSQLite and `SQLiteDriver`](migration.md#supportsqlite-and-sqlitedriver)
  - [DAO return type converters](migration.md#dao-return-type-converters)
  - [Builder and configuration changes](migration.md#builder-and-configuration-changes)
  - [Schema and entity features new in Room 3](migration.md#schema-and-entity-features-new-in-room-3)
  - [Invalidation and tests](migration.md#invalidation-and-tests)
  - [Room 2.x lifecycle (context only)](migration.md#room-2x-lifecycle-context-only)
- [Android 17 (API 37) Migration](migration.md#android-17-api-37-migration)
  - [16 KB memory page size (Play and native code)](migration.md#16-kb-memory-page-size-play-and-native-code)
  - [Launcher `Activity` soft input (IME baseline)](migration.md#launcher-activity-soft-input-ime-baseline)
  - [Cleartext traffic](migration.md#cleartext-traffic)
  - [Cross-profile loopback (127.0.0.1)](migration.md#cross-profile-loopback-127001)
  - [Local network access (target SDK 37)](migration.md#local-network-access-target-sdk-37)
  - [Certificate Transparency](migration.md#certificate-transparency)
  - [Background media playback](migration.md#background-media-playback)
  - [Large-screen orientation and resizability](migration.md#large-screen-orientation-and-resizability)
  - [IME after rotation](migration.md#ime-after-rotation)
  - [Activity recreation defaults inverted (`recreateOnConfigChanges`)](migration.md#activity-recreation-defaults-inverted-recreateonconfigchanges)
  - [JVM unit tests without Robolectric](migration.md#jvm-unit-tests-without-robolectric)
  - [Robolectric JVM tests](migration.md#robolectric-jvm-tests)
  - [Espresso instrumented tests](migration.md#espresso-instrumented-tests)
  - [Memory limiter (all apps on affected devices)](migration.md#memory-limiter-all-apps-on-affected-devices)
  - [Android 17 location privacy](migration.md#android-17-location-privacy)
  - [Explicit URI grants on shares](migration.md#explicit-uri-grants-on-shares)
  - [Reflection and JNI hardening (target SDK 37)](migration.md#reflection-and-jni-hardening-target-sdk-37)
  - [Background activity launch (target SDK 37)](migration.md#background-activity-launch-target-sdk-37)
  - [Keystore key cap (target SDK 37)](migration.md#keystore-key-cap-target-sdk-37)
  - [Contacts provider tightening (target SDK 37)](migration.md#contacts-provider-tightening-target-sdk-37)
  - [SMS one-time passcodes (all apps)](migration.md#sms-one-time-passcodes-all-apps)
  - [Play targetSdk deadlines (context for scheduling)](migration.md#play-targetsdk-deadlines-context-for-scheduling)
  - [Libraries that force the AGP floor](migration.md#libraries-that-force-the-agp-floor)

### modularization.md (417 lines)

Open when: Module types, dependency rules, feature modules, existing-project alignment

- [Table of Contents](modularization.md#table-of-contents)
- [Existing project alignment](modularization.md#existing-project-alignment)
- [Build Configuration](modularization.md#build-configuration)
- [Module Types](modularization.md#module-types)
  - [App Module (`app/`)](modularization.md#app-module-app)
  - [Feature Modules (`feature/*`)](modularization.md#feature-modules-feature)
  - [Core Modules (`core/`)](modularization.md#core-modules-core)
- [Module Structure](modularization.md#module-structure)
  - [Complete Project Structure](modularization.md#complete-project-structure)
  - [Feature Module Structure](modularization.md#feature-module-structure)
  - [Core Module Structure](modularization.md#core-module-structure)
- [Dependency Rules](modularization.md#dependency-rules)
  - [Allowed Dependencies](modularization.md#allowed-dependencies)
  - [Strict Rules:](modularization.md#strict-rules)
  - [Visual Dependency Graph](modularization.md#visual-dependency-graph)
- [Creating Modules](modularization.md#creating-modules)
  - [1. Create Feature Module](modularization.md#1-create-feature-module)
  - [2. Create Core Module](modularization.md#2-create-core-module)
  - [3. Create App Module Configuration](modularization.md#3-create-app-module-configuration)
- [Navigation Coordination](modularization.md#navigation-coordination)
- [Build Configuration](modularization.md#build-configuration)

### testing.md (2611 lines)

Open when: Fakes, Turbine, Hilt tests, Compose UI, ADB/UIAutomator, deep links
Quick routing: [testing-quick.md](testing-quick.md)

- [Table of Contents](testing.md#table-of-contents)
- [Testing Philosophy](testing.md#testing-philosophy)
  - [No Mocking Libraries](testing.md#no-mocking-libraries)
  - [Test Doubles Naming Convention](testing.md#test-doubles-naming-convention)
  - [Test Types by Module](testing.md#test-types-by-module)
- [Test Doubles](testing.md#test-doubles)
  - [Fake Repository Pattern (in `core:testing` module)](testing.md#fake-repository-pattern-in-coretesting-module)
  - [Fake Navigator Pattern](testing.md#fake-navigator-pattern)
  - [UseCase Setup Pattern](testing.md#usecase-setup-pattern)
- [ViewModel Tests](testing.md#viewmodel-tests)
  - [AuthViewModel Test with Fakes](testing.md#authviewmodel-test-with-fakes)
  - [Test Dispatcher Rule (in `core:testing`)](testing.md#test-dispatcher-rule-in-coretesting)
  - [Testing StateFlow with Turbine and Truth](testing.md#testing-stateflow-with-turbine-and-truth)
- [Repository Tests](testing.md#repository-tests)
  - [Testing AuthRepository Implementation with Truth](testing.md#testing-authrepository-implementation-with-truth)
- [Coroutine Testing](testing.md#coroutine-testing)
  - [Test Dispatcher Rule (in `core:testing`)](testing.md#test-dispatcher-rule-in-coretesting)
  - [Testing with `runTest` and Shared Scheduler](testing.md#testing-with-runtest-and-shared-scheduler)
  - [Using `advanceUntilIdle()` for Async Operations](testing.md#using-advanceuntilidle-for-async-operations)
  - [Testing Delays and Timeouts with `advanceTimeBy()`](testing.md#testing-delays-and-timeouts-with-advancetimeby)
  - [Testing Timeout Behavior](testing.md#testing-timeout-behavior)
  - [Checking Virtual Time with `currentTime`](testing.md#checking-virtual-time-with-currenttime)
  - [Testing Flow Emissions with Turbine](testing.md#testing-flow-emissions-with-turbine)
  - [Testing Cancellation](testing.md#testing-cancellation)
  - [Coroutine test rules](testing.md#coroutine-test-rules)
    - [Testing a `StateFlow`](testing.md#testing-a-stateflow)
  - [Dispatcher Choices in Tests](testing.md#dispatcher-choices-in-tests)
- [Hilt Testing](testing.md#hilt-testing)
  - [Testing Hilt-Injected ViewModels](testing.md#testing-hilt-injected-viewmodels)
  - [Custom Test Module](testing.md#custom-test-module)
  - [Testing Without Hilt](testing.md#testing-without-hilt)
- [Robolectric and SDK 37 (Android 17)](testing.md#robolectric-and-sdk-37-android-17)
- [Room Database Testing](testing.md#room-database-testing)
  - [In-Memory Database for Tests](testing.md#in-memory-database-for-tests)
  - [Testing Database Migrations](testing.md#testing-database-migrations)
- [SavedStateHandle Testing](testing.md#savedstatehandle-testing)
  - [Testing Navigation Arguments](testing.md#testing-navigation-arguments)
  - [Testing State Persistence](testing.md#testing-state-persistence)
- [Navigation Tests](testing.md#navigation-tests)
  - [Testing Navigator Implementations in App Module](testing.md#testing-navigator-implementations-in-app-module)
  - [Testing Navigation3 State](testing.md#testing-navigation3-state)
  - [Testing Compose Stability Annotations](testing.md#testing-compose-stability-annotations)
  - [Testing Deep Links](testing.md#testing-deep-links)
- [UI Tests](testing.md#ui-tests)
  - [Compose UI Tests for Auth Screen with Truth](testing.md#compose-ui-tests-for-auth-screen-with-truth)
  - [Compose tests v2 (Compose 1.11+)](testing.md#compose-tests-v2-compose-111)
  - [Trackpad input tests (Compose 1.11+)](testing.md#trackpad-input-tests-compose-111)
- [Agent automation (ADB and UIAutomator)](testing.md#agent-automation-adb-and-uiautomator)
  - [Agent vs device](testing.md#agent-vs-device)
  - [Device targeting](testing.md#device-targeting)
  - [Install, reset, launch](testing.md#install-reset-launch)
  - [Logcat for smoke proof](testing.md#logcat-for-smoke-proof)
  - [UIAutomator (instrumented smoke)](testing.md#uiautomator-instrumented-smoke)
  - [When Compose test vs UIAutomator](testing.md#when-compose-test-vs-uiautomator)
  - [CI wiring (reference only)](testing.md#ci-wiring-reference-only)
  - [Further ADB](testing.md#further-adb)
- [Pre-release UI state checklist](testing.md#pre-release-ui-state-checklist)
  - [State routing](testing.md#state-routing)
- [Screenshot Testing](testing.md#screenshot-testing)
  - [Preview Screenshot Testing vs Roborazzi](testing.md#preview-screenshot-testing-vs-roborazzi)
  - [Setup](testing.md#setup)
  - [Writing Screenshot Tests](testing.md#writing-screenshot-tests)
  - [Multi-Preview for Theme/Device Variants](testing.md#multi-preview-for-themedevice-variants)
  - [Configuring Image Difference Threshold](testing.md#configuring-image-difference-threshold)
  - [Gradle Commands](testing.md#gradle-commands)
  - [Requirements](testing.md#requirements)
  - [Rules](testing.md#rules)
- [Performance Benchmarks](testing.md#performance-benchmarks)
- [Test Utilities](testing.md#test-utilities)
  - [Test Data Factories (in `core:testing`)](testing.md#test-data-factories-in-coretesting)
  - [Running Tests](testing.md#running-tests)
- [Rules](testing.md#rules)
- [Paging 3 Testing](testing.md#paging-3-testing)
  - [Testing ViewModels with PagingData](testing.md#testing-viewmodels-with-pagingdata)
  - [`cachedIn()` limitations](testing.md#cachedin-limitations)
  - [Testing with AsyncPagingDataDiffer](testing.md#testing-with-asyncpagingdatadiffer)
  - [`paging-testing`: `asSnapshot` and `TestPager`](testing.md#paging-testing-assnapshot-and-testpager)
  - [Paging rules](testing.md#paging-rules)
- [Localization Testing](testing.md#localization-testing)
- [Cross-references](testing.md#cross-references)

### workflows.md (342 lines)

Open when: Task not in Quick Reference; greenfield bootstrap; multi-topic routing

- (no `##` sections; read file header)
