android-ai-skills 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.3.0](https://github.com/noloman/Android-AI-skills/compare/v1.2.0...v1.3.0) (2026-02-12)
+
+
+### Features
+
+* add 8 cross-cutting Android platform skills ([821a0d3](https://github.com/noloman/Android-AI-skills/commit/821a0d34bb2f193ea395a990411f2ef0d9c2c23a))
+
 # [1.2.0](https://github.com/noloman/Android-AI-skills/compare/v1.1.0...v1.2.0) (2026-02-12)
 
 

package/README.md

@@ -47,6 +47,14 @@ These AI skills:
 - Prevent architecture drift
 - Protect performance budgets
 - Keep KMP boundaries clean
+- Harden **security** (secrets, storage, network, components)
+- Ensure **Play Store compliance** (Data Safety, permissions, target SDK)
+- Enforce **accessibility** (WCAG AA contrast, touch targets, TalkBack)
+- Optimize **performance** (startup, memory, battery, app size)
+- Maintain **test quality** (test pyramid, Compose testing, screenshot tests)
+- Standardize **build infrastructure** (version catalogs, convention plugins, modularization)
+- Govern **background work** (WorkManager, foreground services, notifications)
+- Guide **navigation** (type-safe routes, deep links, App Links)
 - Scale from indie to enterprise
 - Adapt automatically (Enterprise Mode auto-detection)
 
@@ -76,6 +84,46 @@ flowchart LR
     D --- L
     E --- L
     L --> M[Structured Concurrency & Flow]
+
+    N[android-security-best-practices]
+    C --- N
+    D --- N
+    E --- N
+
+    O[android-performance-best-practices]
+    C --- O
+    D --- O
+    E --- O
+
+    P[play-store-readiness]
+    C --- P
+    D --- P
+    E --- P
+
+    Q[android-testing-best-practices]
+    C --- Q
+    D --- Q
+    E --- Q
+
+    R[android-accessibility-best-practices]
+    C --- R
+    D --- R
+    E --- R
+
+    S[android-build-infra]
+    C --- S
+    D --- S
+    E --- S
+
+    T[android-background-work]
+    C --- T
+    D --- T
+    E --- T
+
+    U[android-navigation-best-practices]
+    C --- U
+    D --- U
+    E --- U
 ```
 
 ---
@@ -139,6 +187,123 @@ Cross-cutting skill that always activates alongside the project-type-specific sk
 
 ---
 
+### 5. android-security-best-practices
+
+Cross-cutting skill — secrets management, secure storage, network security, component hardening.
+
+**Enforces:**
+- No hardcoded secrets in source code
+- EncryptedSharedPreferences / Android Keystore for sensitive data
+- HTTPS enforcement with Network Security Config
+- exported="false" by default on all components
+- PendingIntent.FLAG_IMMUTABLE, WebView file access disabled
+- R8 enabled for release builds
+- No sensitive data in logs
+
+---
+
+### 6. android-performance-best-practices
+
+Cross-cutting skill — startup optimization, memory management, battery, app size.
+
+**Enforces:**
+- TTID < 2s, TTFD < 4s
+- No heavy init on main thread during onCreate()
+- App Startup library, Baseline Profiles
+- No static Activity/Context references
+- StrictMode in debug builds
+- R8 + resource shrinking for release
+- WebP assets, Doze-aware networking
+
+---
+
+### 7. play-store-readiness
+
+Cross-cutting skill — Data Safety, permissions, target SDK, signing, release process.
+
+**Enforces:**
+- Data Safety section matches actual SDK behavior
+- Runtime permissions at point of use with rationale
+- Annual target SDK compliance
+- Play App Signing with separate upload key
+- AAB format, staged rollout (5-10%)
+- Crash-free rate target >= 99%
+- No debuggable release builds
+
+---
+
+### 8. android-testing-best-practices
+
+Cross-cutting skill — Compose UI testing, screenshot tests, Room migrations, CI strategy.
+
+**Enforces:**
+- Test pyramid (unit > integration > E2E)
+- Compose testing APIs for Compose UI (not Espresso)
+- Fakes over mocks
+- Room schema export + migration tests
+- Descriptive test names, no Thread.sleep()
+- Deterministic tests, flaky test quarantine
+- TestDispatcher + runTest for coroutines
+
+---
+
+### 9. android-accessibility-best-practices
+
+Cross-cutting skill — content descriptions, TalkBack, touch targets, contrast, semantics.
+
+**Enforces:**
+- contentDescription on all interactive non-text elements
+- 48dp minimum touch targets
+- WCAG AA contrast (4.5:1 normal, 3:1 large text)
+- No color-only information
+- Logical TalkBack reading order
+- Correct semantics on custom composables
+- sp (not dp) for text sizes
+
+---
+
+### 10. android-build-infra
+
+Cross-cutting skill — version catalogs, convention plugins, modularization, build variants.
+
+**Enforces:**
+- Gradle version catalogs (libs.versions.toml) for all dependencies
+- Convention plugins for shared build config
+- Feature modularization (feature-api/feature-impl)
+- Dependencies flow inward, no feature-to-feature deps
+- implementation scope by default
+- Build variants for debug/release/staging
+
+---
+
+### 11. android-background-work
+
+Cross-cutting skill — WorkManager, foreground services, notifications, scheduling.
+
+**Enforces:**
+- WorkManager for deferrable persistent work
+- Foreground service types declared (API 34+)
+- Notification channels (API 26+)
+- Never hold WakeLocks indefinitely
+- Exact alarms only for user-visible scheduling
+- POST_NOTIFICATIONS permission (API 33+)
+
+---
+
+### 12. android-navigation-best-practices
+
+Cross-cutting skill — type-safe routes, deep links, App Links, navigation patterns.
+
+**Enforces:**
+- Type-safe navigation (data class/object routes)
+- App Links verified with Digital Asset Links
+- Deep link fallbacks for non-installed users
+- No heavy logic in navigation callbacks
+- Standard launch mode with Navigation
+- Deep link parameter validation
+
+---
+
 ## Enterprise Mode (Auto-Detection)
 
 Enterprise Mode activates automatically if the repository contains:
@@ -249,27 +414,59 @@ npx android-ai-skills@latest init --force
 Running `init` with defaults creates:
 
 ```
-AGENTS.md                                    # Codex
-CLAUDE.md                                    # Claude Code
-.github/copilot-instructions.md              # GitHub Copilot
-.cursor/rules/compose-best-practices.mdc     # Cursor (per skill)
+AGENTS.md                                            # Codex
+CLAUDE.md                                            # Claude Code
+.github/copilot-instructions.md                      # GitHub Copilot
+.cursor/rules/compose-best-practices.mdc             # Cursor (per skill)
 .cursor/rules/kmp-architecture-best-practices.mdc
 .cursor/rules/compose-multiplatform-best-practices.mdc
 .cursor/rules/kotlin-coroutines-best-practices.mdc
-.windsurfrules                               # Windsurf
-.clinerules/compose-best-practices.md        # Cline (per skill)
+.cursor/rules/android-security-best-practices.mdc
+.cursor/rules/android-performance-best-practices.mdc
+.cursor/rules/play-store-readiness.mdc
+.cursor/rules/android-testing-best-practices.mdc
+.cursor/rules/android-accessibility-best-practices.mdc
+.cursor/rules/android-build-infra.mdc
+.cursor/rules/android-background-work.mdc
+.cursor/rules/android-navigation-best-practices.mdc
+.windsurfrules                                       # Windsurf
+.clinerules/compose-best-practices.md                # Cline (per skill)
 .clinerules/kmp-architecture-best-practices.md
 .clinerules/compose-multiplatform-best-practices.md
 .clinerules/kotlin-coroutines-best-practices.md
-.aiassistant/rules/compose-best-practices.md # JetBrains AI (per skill)
+.clinerules/android-security-best-practices.md
+.clinerules/android-performance-best-practices.md
+.clinerules/play-store-readiness.md
+.clinerules/android-testing-best-practices.md
+.clinerules/android-accessibility-best-practices.md
+.clinerules/android-build-infra.md
+.clinerules/android-background-work.md
+.clinerules/android-navigation-best-practices.md
+.aiassistant/rules/compose-best-practices.md         # JetBrains AI (per skill)
 .aiassistant/rules/kmp-architecture-best-practices.md
 .aiassistant/rules/compose-multiplatform-best-practices.md
 .aiassistant/rules/kotlin-coroutines-best-practices.md
-.amazonq/rules/compose-best-practices.md     # Amazon Q (per skill)
+.aiassistant/rules/android-security-best-practices.md
+.aiassistant/rules/android-performance-best-practices.md
+.aiassistant/rules/play-store-readiness.md
+.aiassistant/rules/android-testing-best-practices.md
+.aiassistant/rules/android-accessibility-best-practices.md
+.aiassistant/rules/android-build-infra.md
+.aiassistant/rules/android-background-work.md
+.aiassistant/rules/android-navigation-best-practices.md
+.amazonq/rules/compose-best-practices.md             # Amazon Q (per skill)
 .amazonq/rules/kmp-architecture-best-practices.md
 .amazonq/rules/compose-multiplatform-best-practices.md
 .amazonq/rules/kotlin-coroutines-best-practices.md
-CONVENTIONS.md                               # Aider
+.amazonq/rules/android-security-best-practices.md
+.amazonq/rules/android-performance-best-practices.md
+.amazonq/rules/play-store-readiness.md
+.amazonq/rules/android-testing-best-practices.md
+.amazonq/rules/android-accessibility-best-practices.md
+.amazonq/rules/android-build-infra.md
+.amazonq/rules/android-background-work.md
+.amazonq/rules/android-navigation-best-practices.md
+CONVENTIONS.md                                       # Aider
 .aider.conf.yml
 ```
 
@@ -342,6 +539,14 @@ compose-best-practices/
 kmp-architecture-best-practices/
 compose-multiplatform-best-practices/
 kotlin-coroutines-best-practices/
+android-security-best-practices/
+android-performance-best-practices/
+play-store-readiness/
+android-testing-best-practices/
+android-accessibility-best-practices/
+android-build-infra/
+android-background-work/
+android-navigation-best-practices/
 README.md
 ```
 

package/android-accessibility-best-practices/SKILL.md

@@ -0,0 +1,36 @@
+
+---
+name: android-accessibility-best-practices
+description: Android accessibility — content descriptions, TalkBack, touch targets, contrast, Compose semantics.
+---
+
+# Android Accessibility Best Practices
+
+Cross-cutting skill — always activates alongside the project-type-specific skill.
+
+## Hard Rules
+- Provide contentDescription on all interactive non-text elements.
+- Set contentDescription = null on purely decorative images.
+- Minimum touch target size: 48dp × 48dp.
+- Meet WCAG AA contrast ratios: 4.5:1 for normal text, 3:1 for large text.
+- Never convey information by color alone — add icons, patterns, or labels.
+- Ensure logical TalkBack reading order matches visual layout.
+- Apply correct semantics (Role, stateDescription) on custom composables.
+- Time-based content must be pausable or extendable.
+- All form fields must have associated labels.
+- Use sp (not dp) for text sizes to respect user font scaling.
+
+## Core Patterns
+- Use Modifier.semantics {} to expose custom component meaning.
+- Use mergeDescendants to group related elements for TalkBack.
+- Test with TalkBack enabled on a real device.
+- Run Accessibility Scanner for automated checks.
+- Support dynamic font sizes — test at maximum font scale.
+- Verify dark theme meets contrast requirements separately.
+
+## References
+- references/content_descriptions.md
+- references/talkback_navigation.md
+- references/touch_targets.md
+- references/color_contrast.md
+- references/compose_semantics.md

package/android-accessibility-best-practices/references/color_contrast.md

@@ -0,0 +1,30 @@
+# Color & Contrast
+
+## WCAG AA Requirements
+- Normal text (< 18sp or < 14sp bold): contrast ratio ≥ 4.5:1.
+- Large text (≥ 18sp or ≥ 14sp bold): contrast ratio ≥ 3:1.
+- Non-text elements (icons, borders, form fields): contrast ratio ≥ 3:1.
+- WCAG AAA (optional, stricter): 7:1 for normal text, 4.5:1 for large text.
+
+## Exceptions
+- Disabled/inactive elements: no contrast requirement (but consider usability).
+- Logos and decorative elements: no contrast requirement.
+- Text within images: same contrast requirements as regular text.
+
+## Color Independence
+- Never use color alone to convey information (e.g., red=error, green=success).
+- Add icons, patterns, underlines, or labels alongside color indicators.
+- Error states: use error icon + red color + descriptive text.
+- Charts/graphs: use patterns, labels, or shapes in addition to color.
+
+## Dark Theme
+- Verify contrast ratios for both light and dark themes separately.
+- Dark theme surfaces use lighter text — ensure sufficient contrast.
+- Surface color hierarchy matters: surface, surfaceVariant, surfaceContainer.
+- Test dynamic theming (Material You) — user-generated colors may fail contrast.
+
+## Tools
+- Accessibility Scanner (Android): scans visible UI for contrast issues.
+- WebAIM Contrast Checker: manual ratio calculation.
+- Colour Contrast Analyser (desktop): eyedropper-based tool.
+- Android Studio Layout Inspector: check rendered colors.

package/android-accessibility-best-practices/references/compose_semantics.md

@@ -0,0 +1,48 @@
+# Compose Semantics
+
+## Modifier.semantics
+- Use Modifier.semantics { } to add accessibility information to composables.
+- mergeDescendants = true: combines child semantics into a single TalkBack announcement.
+- clearAndSetSemantics { }: removes all child semantics and sets custom ones.
+
+## Roles
+- Role.Button: announces as "button" (double-tap to activate).
+- Role.Checkbox, Role.Switch, Role.RadioButton: announces toggle state.
+- Role.Tab: announces as "tab" with position.
+- Role.Image: announces as "image".
+- Set via: Modifier.semantics { role = Role.Button }.
+
+## State Description
+- stateDescription: announces the current state (e.g., "Selected", "Expanded", "50%").
+- toggleableState: ToggleableState.On, Off, Indeterminate.
+- selected: Boolean for selectable items.
+- Use for custom components that have states TalkBack should announce.
+
+## Headings & Structure
+- heading(): marks element as a heading for navigation.
+- Modifier.semantics { heading() } — TalkBack users can jump between headings.
+- Use for screen titles, section headers, group labels.
+
+## Content & Actions
+- contentDescription: text read by TalkBack.
+- customActions: list of CustomAccessibilityAction for contextual actions.
+- onClick(label = "action description") { }: labeled click action.
+- disabled(): marks element as non-interactive.
+- error("message"): announces error state.
+
+## Password & Input
+- password(): hides text from TalkBack, announces "password".
+- editableText: programmatic text for text fields.
+- textSelectionRange: cursor position information.
+- imeAction: announces expected keyboard action.
+
+## Live Regions
+- liveRegion = LiveRegionMode.Polite: announce changes when idle.
+- liveRegion = LiveRegionMode.Assertive: announce changes immediately.
+- Use for: toast messages, loading states, live counters, error banners.
+
+## Testing Semantics
+- Use ComposeTestRule.onNodeWithText().assertHasClickAction().
+- assert(SemanticsMatcher.keyIsDefined(SemanticsProperties.Heading)).
+- printToLog() to dump the semantic tree for debugging.
+- Verify role, state, and content description in tests.

package/android-accessibility-best-practices/references/content_descriptions.md

@@ -0,0 +1,32 @@
+# Content Descriptions
+
+## Required Elements
+- All interactive non-text elements: IconButton, Image (clickable), FAB, custom icons.
+- Compose: Image(contentDescription = "description") or Icon(contentDescription = "description").
+- View system: android:contentDescription or setContentDescription().
+
+## Decorative Elements
+- Set contentDescription = null on decorative images (Compose).
+- View system: android:importantForAccessibility="no".
+- Decorative = adds no information beyond what's already visible as text.
+
+## Writing Descriptions
+- Describe the action, not the appearance: "Delete item" not "Red trash can icon".
+- Keep it concise: 2–5 words is ideal.
+- Avoid "button" or "image" — TalkBack announces the role automatically.
+- Match the language of the UI locale.
+
+## Dynamic Descriptions
+- Update contentDescription when state changes (e.g., "Play" → "Pause").
+- Use stateDescription for toggle states (e.g., "Selected", "Expanded").
+- Compose: Modifier.semantics { stateDescription = "Expanded" }.
+
+## Icon + Text Combinations
+- If an icon is next to text that describes it, set icon contentDescription = null.
+- TalkBack reads both — redundant descriptions cause confusion.
+- Use mergeDescendants to group icon and text into one TalkBack announcement.
+
+## Live Regions
+- Use Modifier.semantics { liveRegion = LiveRegionMode.Polite } for dynamic updates.
+- Polite: announces when TalkBack is idle. Assertive: interrupts immediately.
+- Use for: snackbars, loading indicators, real-time counters.

package/android-accessibility-best-practices/references/talkback_navigation.md

@@ -0,0 +1,38 @@
+# TalkBack Navigation
+
+## Default Traversal Order
+- TalkBack reads nodes top-to-bottom, start-to-end (LTR/RTL aware).
+- Order follows the semantic tree, which mirrors the composable tree by default.
+- Ensure visual order matches semantic order — mismatches confuse users.
+
+## Custom Ordering
+- Compose: Modifier.semantics { traversalIndex = 1f } to reorder.
+- Lower traversalIndex = announced earlier.
+- Use sparingly — prefer restructuring the composable tree over overriding traversal.
+- View system: android:accessibilityTraversalBefore / accessibilityTraversalAfter.
+
+## Focus Management
+- Use FocusRequester to programmatically move focus (e.g., after navigation).
+- Announce screen changes to TalkBack — user needs context after navigation.
+- Compose: LaunchedEffect to request focus on the first meaningful element.
+
+## Headings
+- Mark section headings: Modifier.semantics { heading() }.
+- TalkBack users can navigate by headings (swipe up/down gesture).
+- Use headings for screen titles, section dividers, list group headers.
+
+## Dialogs and Modals
+- Focus must be trapped inside dialogs — TalkBack should not escape to background.
+- Compose Dialog and BottomSheet handle this automatically.
+- On dismiss, return focus to the element that opened the dialog.
+
+## Custom Actions
+- Use Modifier.semantics { customActions = listOf(CustomAccessibilityAction("Delete") { ... }) }.
+- Provides additional actions without visible UI controls.
+- TalkBack users access via the actions menu.
+
+## Testing
+- Enable TalkBack (Settings > Accessibility > TalkBack) and navigate your app.
+- Verify: every element is reachable, descriptions are meaningful, order is logical.
+- Test with the screen off (TalkBack Braille mode) for additional confidence.
+- Use Accessibility Scanner app for automated checks.

package/android-accessibility-best-practices/references/touch_targets.md

@@ -0,0 +1,28 @@
+# Touch Targets
+
+## Minimum Size
+- 48dp × 48dp minimum for all interactive elements (Material Design guideline).
+- WCAG 2.5.8 requires at least 24×24 CSS px — Android's 48dp exceeds this.
+- Applies to: buttons, icons, checkboxes, switches, list items, links.
+
+## Compose
+- Use Modifier.sizeIn(minWidth = 48.dp, minHeight = 48.dp) on interactive elements.
+- Material components set minimumInteractiveComponentSize automatically.
+- For custom composables, ensure the clickable area includes padding.
+- Use Modifier.clickable with indication and correct hit area.
+
+## Expanding Touch Area
+- Add padding around small visual elements to expand the touch target.
+- Compose: Modifier.padding() outside Modifier.clickable() expands the touch area.
+- View system: use TouchDelegate to extend touch area beyond the view bounds.
+- ViewCompat.setMinimumTouchTargetSize for backward-compatible touch targets.
+
+## Spacing
+- Maintain at least 8dp spacing between adjacent touch targets.
+- Prevents accidental taps on the wrong element.
+- Especially important for dense layouts: toolbars, bottom navigation, list actions.
+
+## Verification
+- Use Accessibility Scanner to detect targets smaller than 48dp.
+- Enable "Show layout bounds" in Developer Options for visual verification.
+- Test on actual devices — touch accuracy varies by device and user.

package/android-background-work/SKILL.md

@@ -0,0 +1,33 @@
+
+---
+name: android-background-work
+description: Android background work — WorkManager, foreground services, notifications, scheduling.
+---
+
+# Android Background Work
+
+Cross-cutting skill — always activates alongside the project-type-specific skill.
+
+## Hard Rules
+- Use WorkManager for all deferrable, persistent background work.
+- Declare foreground service types explicitly (API 34+ requirement).
+- Use notification channels (API 26+) for all notifications.
+- Never hold WakeLocks indefinitely — always release in a finally block.
+- Use exact alarms only for user-visible scheduling (alarms, reminders).
+- FCM high-priority messages only for user-visible notifications.
+- Stop foreground services when work completes — do not leave them running.
+- Request POST_NOTIFICATIONS permission (API 33+) before posting notifications.
+
+## Core Patterns
+- WorkManager with constraints (network, charging, storage) for intelligent scheduling.
+- Use ExistingWorkPolicy.KEEP or REPLACE to avoid duplicate work.
+- Chain work requests with then() for sequential dependencies.
+- Use expedited work for urgent tasks that must run immediately.
+- Prefer inexact alarms (setInexactRepeating) to save battery.
+- Use Hilt @AssistedInject for WorkManager Worker injection.
+
+## References
+- references/workmanager.md
+- references/foreground_services.md
+- references/notifications.md
+- references/scheduling.md

package/android-background-work/references/foreground_services.md

@@ -0,0 +1,30 @@
+# Foreground Services
+
+## Service Types (API 34+)
+- Must declare foreground service type in AndroidManifest.xml.
+- Types: dataSync, camera, connectedDevice, health, location, mediaPlayback, mediaProjection, microphone, phoneCall, remoteMessaging, shortService, specialUse, systemExempted.
+- Declare in manifest: android:foregroundServiceType="location|dataSync".
+- Pass type when starting: ServiceCompat.startForeground(service, id, notification, FOREGROUND_SERVICE_TYPE_LOCATION).
+
+## Permissions
+- Declare <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />.
+- API 34+: also declare <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" /> (per type).
+- Some types require runtime permissions (location, camera, microphone).
+
+## Notification Requirement
+- Foreground services must display a persistent notification.
+- Call startForeground(notificationId, notification) within 5 seconds of service start.
+- Notification cannot be dismissed by the user while service is running.
+- Use a meaningful notification — explain what the service is doing.
+
+## Lifecycle
+- Start with Context.startForegroundService() (API 26+).
+- Call startForeground() immediately in onCreate() or onStartCommand().
+- Stop when work completes: stopForeground(STOP_FOREGROUND_REMOVE) + stopSelf().
+- Do not leave foreground services running indefinitely — system may restrict.
+
+## Short-Lived Services
+- shortService type: for tasks that complete in under ~3 minutes.
+- System may stop shortService after the timeout.
+- Use for: quick uploads, brief processing, transient operations.
+- Prefer WorkManager expedited work over short foreground services when possible.

package/android-background-work/references/notifications.md

@@ -0,0 +1,34 @@
+# Notifications
+
+## Notification Channels (API 26+)
+- Create channels in Application.onCreate() — must exist before posting notifications.
+- Each channel has: id, name, importance level, optional description.
+- Importance levels: IMPORTANCE_HIGH (sound + popup), IMPORTANCE_DEFAULT (sound), IMPORTANCE_LOW (no sound), IMPORTANCE_MIN (no sound or visual).
+- Users can customize per channel — respect their settings.
+- Don't create too many channels — group by user-facing feature.
+
+## POST_NOTIFICATIONS Permission (API 33+)
+- Request android.permission.POST_NOTIFICATIONS before posting.
+- Without permission, notifications are silently dropped.
+- Time the request: after user understands value, not at app startup.
+- Handle denial gracefully — app should still function.
+
+## Building Notifications
+- Use NotificationCompat.Builder for backward compatibility.
+- Required: setSmallIcon(), setContentTitle(), setContentText().
+- Set PendingIntent with FLAG_IMMUTABLE for tap action.
+- Use setAutoCancel(true) to dismiss on tap.
+
+## Styles
+- BigTextStyle: expandable text content.
+- BigPictureStyle: large image preview.
+- InboxStyle: multi-line list format.
+- MessagingStyle: chat conversation format (required for messaging apps).
+- Use appropriate style — improves user experience and system ranking.
+
+## Actions & Grouping
+- Add up to 3 notification actions with addAction().
+- Use PendingIntent with FLAG_IMMUTABLE for each action.
+- Group related notifications: setGroup("group_key").
+- Provide a group summary notification for the bundle.
+- Use direct reply action for messaging-style notifications.

package/android-background-work/references/scheduling.md

@@ -0,0 +1,31 @@
+# Scheduling
+
+## AlarmManager
+- Use setInexactRepeating() for periodic tasks — allows system batching.
+- Use setExactAndAllowWhileIdle() only for user-visible alarms (alarm clock, reminders).
+- Use setExact() when exact timing matters but Doze exemption isn't needed.
+- SCHEDULE_EXACT_ALARM permission required (API 31+) for exact alarms.
+- User can revoke exact alarm permission — check with canScheduleExactAlarms().
+
+## Alarm Delivery
+- Use BroadcastReceiver as the alarm target.
+- PendingIntent with FLAG_IMMUTABLE for the alarm PendingIntent.
+- Alarms are lost on reboot — re-schedule in BOOT_COMPLETED receiver.
+- Use AlarmManager.AlarmClockInfo for user-visible alarm clock features.
+
+## Doze & Standby Implications
+- Doze defers alarms, network, and jobs when device is idle.
+- setAndAllowWhileIdle(): fires during Doze but with rate limiting (~1 per 9 min).
+- setExactAndAllowWhileIdle(): exact timing during Doze, also rate-limited.
+- App Standby buckets throttle alarms for infrequently-used apps.
+
+## Network Scheduling
+- Add jitter to periodic network requests — avoid thundering herd on server.
+- Use WorkManager with network constraint instead of AlarmManager for network tasks.
+- Batch multiple network operations into a single work request.
+
+## Migration from JobScheduler
+- JobScheduler is lower-level — use WorkManager as the recommended wrapper.
+- WorkManager handles backward compatibility, constraints, and chaining.
+- Migrate JobService implementations to Worker/CoroutineWorker.
+- WorkManager supports all JobScheduler constraints plus more.

package/android-background-work/references/workmanager.md

@@ -0,0 +1,41 @@
+# WorkManager
+
+## Request Types
+- OneTimeWorkRequest: single execution, optionally expedited.
+- PeriodicWorkRequest: repeating work with minimum interval of 15 minutes.
+- Periodic work has a flex window — work runs within [interval - flex, interval].
+
+## Constraints
+- NetworkType: CONNECTED, UNMETERED, METERED, NOT_ROAMING.
+- requiresCharging(): run only when device is charging.
+- requiresStorageNotLow(): run only when storage is sufficient.
+- requiresBatteryNotLow(): run only when battery is adequate.
+- Combine constraints: Constraints.Builder().setRequiredNetworkType(CONNECTED).setRequiresCharging(true).
+
+## Work Policies
+- ExistingWorkPolicy.KEEP: skip if existing work with same unique name is running.
+- ExistingWorkPolicy.REPLACE: cancel existing work and start new.
+- ExistingWorkPolicy.APPEND: chain after existing work completes.
+- Use enqueueUniqueWork() with a descriptive unique name.
+
+## Chaining
+- then(): sequential execution — output of one feeds into next.
+- WorkManager.getInstance().beginWith(a, b).then(c): a and b run in parallel, then c.
+- Pass data via Data objects (key-value, max 10KB).
+- Use inputMerger for combining outputs from parallel work.
+
+## Retry
+- BackoffPolicy.LINEAR or BackoffPolicy.EXPONENTIAL.
+- Minimum backoff delay: 10 seconds, maximum: 5 hours.
+- Return Result.retry() from doWork() to trigger retry.
+
+## Observation
+- Observe WorkInfo via LiveData or Flow: getWorkInfoByIdFlow(workId).
+- Check state: ENQUEUED, RUNNING, SUCCEEDED, FAILED, BLOCKED, CANCELLED.
+- Use tags for querying groups of work: getWorkInfosByTagFlow("sync").
+
+## Hilt Integration
+- Use @HiltWorker annotation on Worker class.
+- Inject dependencies via @AssistedInject constructor.
+- @Assisted for workerParams: Context and WorkerParameters.
+- Register HiltWorkerFactory in Application.