reis-mobile 0.5.0 → 0.7.0

package/skills/mobile-accessibility/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: mobile-accessibility
+description: Audits and fixes accessibility in mobile apps on every stack — screen reader labels, roles, states and reading order for TalkBack and VoiceOver, decorative elements, grouping, touch target size, text scaling and Dynamic Type, color contrast, focus in dialogs and announcements for dynamic content — with the exact APIs for Flutter (Semantics), native Android (Jetpack Compose semantics and Views), native iOS (SwiftUI and UIKit) and React Native, plus automated checks in tests. Use when building or reviewing UI for accessibility, preparing an accessibility audit, fixing TalkBack or VoiceOver issues, or when the user mentions a11y, WCAG, screen readers, font scaling or contrast, even if they only point at one screen.
+intents: [accessibility]
+stacks: ["*"]
+---
+
+# Mobile Accessibility
+
+One accessibility process for every mobile stack. This file holds what is true everywhere; each platform's APIs, tools and pitfalls live in its reference.
+
+## 1. Pick the reference
+
+| Project | Read |
+|---|---|
+| Flutter | [references/flutter.md](references/flutter.md) |
+| Native Android: Jetpack Compose or Views | [references/android.md](references/android.md) |
+| Native iOS: SwiftUI or UIKit | [references/ios.md](references/ios.md) |
+| React Native or Expo | [references/react-native.md](references/react-native.md) |
+
+In Flutter and React Native apps, the native reference applies only to screens or components written natively (platform views, native modules with UI).
+
+## 2. What a screen reader user needs
+
+Every interactive element exposes four things to the accessibility tree. Check them in this order:
+
+1. **Name.** What it is or does, in words: "Delete task", not "trash icon" or nothing. Text children usually provide it; icon-only controls, images that carry meaning and custom-drawn controls need an explicit label.
+2. **Role.** Button, checkbox, switch, slider, link, header, image. A tappable container without a role is read as plain text, and the user does not know it can be activated.
+3. **State and value.** Checked, selected, expanded, disabled, the slider's value. When the state changes, the new state is read.
+4. **Order and grouping.** Reading order follows the visual order. Related pieces (an avatar, a name and a timestamp in a list row) are one element, not three swipes.
+
+And the tree must not contain noise: decorative images, dividers and duplicated text are hidden from assistive technology.
+
+## 3. Checks (all stacks)
+
+**Perceivable**
+- [ ] Icon-only buttons, image buttons and meaningful images have a label that describes the action or content.
+- [ ] Decorative images and icons next to text that already says the same are excluded from the accessibility tree.
+- [ ] Text contrast is at least 4.5:1, or 3:1 for large text; icons and control borders that carry meaning reach 3:1 (WCAG 1.4.3 and 1.4.11). Contrast cannot be proven from code alone when colors come from themes or images: say so and name the tool that measures it.
+- [ ] Information is not conveyed by color only (an error shown only as a red border).
+
+**Operable**
+- [ ] Touch targets are at least 48×48 dp on Android and 44×44 pt on iOS, even when the visible icon is smaller. The layout extends the tappable area instead of the icon.
+- [ ] Gestures (swipe to delete, long press, drag) have an alternative: a visible button or a custom accessibility action.
+- [ ] Modal dialogs and bottom sheets move focus inside when they open and return it when they close; content behind them is not reachable.
+- [ ] Timeouts, auto-advancing carousels and animations can be paused or respect the system's reduce motion setting.
+
+**Understandable**
+- [ ] Form fields have a persistent label, not only a placeholder; errors are announced and say how to fix the input.
+- [ ] Screen titles and section headers are marked as headers, so users can jump between them.
+- [ ] Dynamic changes the user did not trigger by moving focus — a snackbar, a validation error, "3 results", loading finished — are announced.
+
+**Robust**
+- [ ] Text scales with the system font size setting up to the largest accessibility sizes without truncation, overlap or clipped containers. Fixed heights on text containers are the usual cause.
+- [ ] Custom-drawn controls (canvas, custom painters, gesture detectors) expose name, role, state and actions explicitly.
+- [ ] The layout works in landscape and with the display size (screen zoom) setting increased.
+
+## 4. Evidence and severity
+
+Point to `file:line` for every finding and give the fix in the platform's own API, not pseudocode.
+
+- **Critical:** a screen reader user cannot complete the flow — an unlabeled primary action, a control that cannot be activated with the screen reader, focus trapped or lost, a custom control invisible to the tree.
+- **High:** the flow is possible but misleading or very hard — wrong role, missing state, targets far below the minimum, text that clips at larger sizes, unannounced errors.
+- **Medium:** noise and friction — decorative elements read aloud, rows split into many swipes, missing headers.
+- **Low:** polish — hints, custom action names, reading order inside a well-labeled group.
+
+## 5. Verify on a device
+
+Code review finds most problems; only assistive technology confirms the experience. Recommend the automated checks listed in the reference for the test suite, then a manual pass: TalkBack on Android and VoiceOver on iOS through the flow, the largest font size, and the platform's scanner (Accessibility Scanner on Android, Accessibility Inspector in Xcode). Say which findings came from code only.

package/skills/mobile-accessibility/references/android.md

@@ -0,0 +1,54 @@
+# Accessibility on native Android
+
+TalkBack reads the accessibility tree built from Compose semantics or from View properties. Material components fill in roles and states; custom composables with `Modifier.clickable`, `pointerInput` or `Canvas`, and custom Views, need them explicitly.
+
+## Jetpack Compose
+
+| Need | API |
+|---|---|
+| Label an icon-only control | `Icon(Icons.Default.Delete, contentDescription = "Delete task")` inside `IconButton` |
+| Hide a decorative icon or image | `contentDescription = null` |
+| Role for a custom clickable | `Modifier.clickable(role = Role.Button, onClickLabel = "Open details") { }` |
+| Toggle with role and state | `Modifier.toggleable(value = checked, role = Role.Checkbox, onValueChange = ...)` on the whole row |
+| Merge a row into one element | `Modifier.semantics(mergeDescendants = true) {}` |
+| Replace children's semantics | `Modifier.clearAndSetSemantics { contentDescription = "..." }` |
+| Header | `Modifier.semantics { heading() }` |
+| Custom state text | `Modifier.semantics { stateDescription = "Expanded" }` |
+| Live updates | `Modifier.semantics { liveRegion = LiveRegionMode.Polite }` |
+| Gesture alternative | `Modifier.semantics { customActions = listOf(CustomAccessibilityAction("Archive") { archive(); true }) }` |
+| Dialog or pane title | `Modifier.semantics { paneTitle = "Filters" }` |
+| Reading order | `Modifier.semantics { traversalIndex = 1f }` with `isTraversalGroup = true` on the container |
+
+Pitfalls:
+
+- A `Checkbox` or `Switch` next to a `Text` in a `Row` produces two elements and a checkbox without a name. Make the `Row` `toggleable` and pass `onCheckedChange = null` to the inner control.
+- `Modifier.size(24.dp)` on an `IconButton` shrinks the touch target. Material components apply `Modifier.minimumInteractiveComponentSize()` (48 dp); keep the icon small, not the button.
+- `Modifier.pointerInput` and `detectTapGestures` add no semantics at all; prefer `clickable`, or add `onClick` in `semantics`.
+- Text sizes in `dp` instead of `sp` do not scale with the font size setting.
+
+## Views
+
+| Need | API |
+|---|---|
+| Label | `android:contentDescription`, or `android:labelFor` on the `TextView` that labels an input |
+| Hide decorative | `android:importantForAccessibility="no"` (or `contentDescription="@null"` on `ImageView`) |
+| Group | `android:focusable="true"` on the container with `android:screenReaderFocusable="true"` |
+| Header | `android:accessibilityHeading="true"` / `ViewCompat.setAccessibilityHeading` |
+| Live updates | `android:accessibilityLiveRegion="polite"` |
+| Role, state, actions | `ViewCompat.setAccessibilityDelegate` with `onInitializeAccessibilityNodeInfo`, or `ViewCompat.addAccessibilityAction` |
+| Text field hint and error | `TextInputLayout` with `hint` and `error` |
+
+`View.announceForAccessibility` is discouraged in recent Android releases in favor of live regions and pane titles; check the `compileSdk` and the method's documentation before recommending it.
+
+## Touch targets and text
+
+- 48×48 dp minimum. For small icons use padding or `TouchDelegate` in Views.
+- Text in `sp`; containers with `wrap_content` or minimum heights, not fixed heights.
+- Test at the largest font size and display size in Settings, including the nonlinear font scaling of Android 14 and later.
+
+## Automated checks
+
+- Espresso: `AccessibilityChecks.enable()` from `androidx.test.espresso:espresso-accessibility` runs the Accessibility Test Framework on every view action.
+- Compose UI tests can assert semantics: `onNodeWithContentDescription("Delete task").assertHasClickAction()`, `assert(hasStateDescription("Expanded"))`.
+- Lint flags missing `contentDescription` on `ImageView` and `ImageButton` (`ContentDescription`) and small touch targets in some layouts.
+- Manual: TalkBack, the Accessibility Scanner app, and Settings → Accessibility → font and display size.

package/skills/mobile-accessibility/references/flutter.md

@@ -0,0 +1,59 @@
+# Accessibility in Flutter
+
+Flutter builds its own semantics tree from widgets and hands it to TalkBack and VoiceOver. Material and Cupertino widgets already fill in most of it; custom widgets built from `GestureDetector`, `InkWell` without children text, `CustomPaint` and images do not. For the broader Flutter guide (including localization), see `mobile-flutter` → `references/accessibility-i18n.md`.
+
+## Labels, roles and states
+
+| Need | API |
+|---|---|
+| Label an icon button | `IconButton(tooltip: 'Delete task', ...)` — the tooltip becomes the label |
+| Label a meaningful image | `Image.asset(..., semanticLabel: 'Profile photo of Ana')` |
+| Hide a decorative image | `Image.asset(..., excludeFromSemantics: true)`, or wrap in `ExcludeSemantics` |
+| Custom tappable widget | `Semantics(button: true, label: '...', onTap: ..., child: ...)` |
+| Toggle state | `Semantics(toggled: value, ...)` or `checked:` for checkbox-like controls |
+| Header | `Semantics(header: true, child: Text('Settings'))` |
+| Replace children's semantics | `Semantics(label: '...', excludeSemantics: true, child: ...)` |
+| Merge a row into one element | `MergeSemantics(child: ListTile(...))` |
+| Extra actions for gestures | `Semantics(customSemanticsActions: {CustomSemanticsAction(label: 'Archive'): _archive})` |
+| Text field label | `TextField(decoration: InputDecoration(labelText: 'Email', errorText: ...))` |
+
+Pitfalls:
+
+- `GestureDetector` and `InkWell` around an `Icon` expose a tap action but no label. Prefer `IconButton`, or add `Semantics`.
+- `Icon(semanticLabel: ...)` labels the icon, but it is still not a button. Put the label on the tappable widget.
+- `Semantics` without `container: true` may merge into an ancestor; set it when a widget must be its own node.
+- `CustomPaint` is invisible to screen readers unless its painter implements `semanticsBuilder` or it is wrapped in `Semantics`.
+
+## Announcements and focus
+
+- Mark text that changes on its own (a counter, a status) with `Semantics(liveRegion: true, ...)`.
+- For one-off messages, `SemanticsService.announce(message, textDirection)` exists in `package:flutter/semantics.dart`; check its status in the Flutter version in `pubspec.lock`'s SDK constraint before recommending it, since the announcement APIs have been evolving for multi-view support.
+- `SnackBar`s shown through `ScaffoldMessenger` are announced by the framework.
+- Dialogs opened with `showDialog` and routes block the semantics of what is behind them; custom overlays built with `Stack` and `Positioned` do not — use `BlockSemantics` or a route.
+- Control reading order with `Semantics(sortKey: OrdinalSortKey(n))` only when the visual order and the widget order genuinely differ.
+
+## Touch targets and text scaling
+
+- Material's minimum is `kMinInteractiveDimension` (48). `ThemeData.materialTapTargetSize: MaterialTapTargetSize.shrinkWrap` shrinks it — flag it on interactive components.
+- Small icons: keep the visual size and give the tappable widget `constraints: BoxConstraints(minWidth: 48, minHeight: 48)` or padding.
+- Text scaling comes from `MediaQuery.textScalerOf(context)`. Flag code that overrides it for the whole app (`MediaQuery(data: ...copyWith(textScaler: TextScaler.noScaling))`) and fixed-height containers around text.
+- Respect reduced motion with `MediaQuery.disableAnimationsOf(context)`.
+
+## Automated checks
+
+Widget tests can assert the guidelines that `flutter_test` ships:
+
+```dart
+testWidgets('login screen meets accessibility guidelines', (tester) async {
+  final handle = tester.ensureSemantics();
+  await tester.pumpWidget(const MaterialApp(home: LoginScreen()));
+
+  await expectLater(tester, meetsGuideline(androidTapTargetGuideline));
+  await expectLater(tester, meetsGuideline(iOSTapTargetGuideline));
+  await expectLater(tester, meetsGuideline(labeledTapTargetGuideline));
+  await expectLater(tester, meetsGuideline(textContrastGuideline));
+  handle.dispose();
+});
+```
+
+Find semantics nodes in tests with `find.bySemanticsLabel('Delete task')`. On a device, use TalkBack and VoiceOver, and the `showSemanticsDebugger: true` flag of `MaterialApp` to see the tree.

package/skills/mobile-accessibility/references/ios.md

@@ -0,0 +1,50 @@
+# Accessibility on native iOS
+
+VoiceOver reads accessibility elements built from SwiftUI modifiers or UIKit properties. Standard controls come with traits and values; custom views, gesture recognizers and drawn content need them explicitly. For the broader iOS UI guide, see `mobile-ios` → `references/ui-navigation.md`.
+
+## SwiftUI
+
+| Need | API |
+|---|---|
+| Label an icon-only button | `Button { } label: { Image(systemName: "trash") }.accessibilityLabel("Delete task")`, or `Label("Delete task", systemImage: "trash").labelStyle(.iconOnly)` |
+| Hide a decorative image | `Image(decorative: "divider")` or `.accessibilityHidden(true)` |
+| Trait for a custom tappable view | Use `Button` instead of `.onTapGesture`; otherwise `.accessibilityAddTraits(.isButton)` |
+| Header | `.accessibilityAddTraits(.isHeader)` |
+| Group a row | `.accessibilityElement(children: .combine)` |
+| Replace children | `.accessibilityElement(children: .ignore).accessibilityLabel("...")` |
+| Value | `.accessibilityValue("3 of 5")` |
+| Hint | `.accessibilityHint("Opens the order details")` — only when the label is not enough |
+| Gesture alternative | `.accessibilityAction(named: "Archive") { archive() }` |
+| Adjustable control | `.accessibilityAdjustableAction { direction in ... }` |
+| Reading order | `.accessibilitySortPriority(_:)` inside a container |
+| Announcement | `AccessibilityNotification.Announcement("Saved").post()` (iOS 17+) or `UIAccessibility.post(notification: .announcement, argument: "Saved")` |
+
+Pitfalls:
+
+- `.onTapGesture` on an `HStack` does not add the button trait, so VoiceOver does not say the row can be activated; `Button` with a custom style keeps the look and the trait.
+- `.font(.system(size: 17))` does not scale with Dynamic Type. Use text styles (`.font(.body)`) and `@ScaledMetric` for custom sizes and spacing.
+- `.frame(height:)` on text containers clips at accessibility sizes; use `minHeight`, and switch `HStack` to `VStack` with `@Environment(\.dynamicTypeSize)` when `dynamicTypeSize.isAccessibilitySize`.
+- Respect `@Environment(\.accessibilityReduceMotion)` for animations.
+
+## UIKit
+
+| Need | API |
+|---|---|
+| Element and label | `isAccessibilityElement = true`, `accessibilityLabel` |
+| Hide decorative | `isAccessibilityElement = false` or `accessibilityElementsHidden = true` on a container |
+| Traits | `accessibilityTraits = [.button]`, `.header`, `.selected`, `.notEnabled` |
+| Group a cell | set `isAccessibilityElement = true` and a combined label on the cell |
+| Custom actions | `accessibilityCustomActions = [UIAccessibilityCustomAction(name: "Archive") { _ in ... }]` |
+| Modal | `accessibilityViewIsModal = true` on the presented view |
+| Screen or layout change | `UIAccessibility.post(notification: .screenChanged, argument: firstElement)` / `.layoutChanged` |
+| Dynamic Type | `UIFont.preferredFont(forTextStyle:)`, `UIFontMetrics`, `adjustsFontForContentSizeCategory = true` |
+
+## Touch targets
+
+Apple's Human Interface Guidelines recommend at least 44×44 points. In SwiftUI, extend the hit area with `.frame(minWidth: 44, minHeight: 44)` and `.contentShape(Rectangle())`; in UIKit, override `point(inside:with:)` or enlarge the button's frame, not the image.
+
+## Automated checks
+
+- XCUITest: `try app.performAccessibilityAudit()` (Xcode 15, iOS 17 and later) checks contrast, hit regions, element descriptions, Dynamic Type clipping and traits; pass a set of audit types or a handler to ignore known issues.
+- Query by label in UI tests (`app.buttons["Delete task"]`): a test that finds elements by label breaks when a label disappears.
+- Manual: VoiceOver on a device, Accessibility Inspector in Xcode (audit and inspection), and Environment Overrides in the debug bar for Dynamic Type, contrast and reduce motion.

package/skills/mobile-accessibility/references/react-native.md

@@ -0,0 +1,38 @@
+# Accessibility in React Native
+
+React Native maps accessibility props to the native TalkBack and VoiceOver APIs. Core components such as `Button` and `Switch` fill in roles; `Pressable`, `TouchableOpacity` and `View` do not. Recent React Native versions also accept ARIA-style props (`role`, `aria-label`, `aria-checked`...) that map to the same native properties; follow whichever style the project already uses. For the broader guide, see `mobile-rn` → `references/ui-navigation.md`.
+
+## Labels, roles and states
+
+| Need | API |
+|---|---|
+| Label an icon-only control | `<Pressable accessibilityRole="button" accessibilityLabel="Delete task">` |
+| Hide decorative content | `accessible={false}` on images; for subtrees `accessibilityElementsHidden` (iOS) **and** `importantForAccessibility="no-hide-descendants"` (Android) |
+| Group a row | `accessible` on the container, with a combined `accessibilityLabel` when children's text is not enough |
+| State | `accessibilityState={{ checked, selected, disabled, expanded, busy }}` |
+| Value | `accessibilityValue={{ min: 0, max: 100, now: 40 }}` or `{{ text: '3 of 5' }}` |
+| Header | `accessibilityRole="header"` |
+| Hint | `accessibilityHint="Opens the order details"` |
+| Gesture alternative | `accessibilityActions={[{ name: 'archive', label: 'Archive' }]}` with `onAccessibilityAction` |
+| Live updates | `accessibilityLiveRegion="polite"` (Android); `AccessibilityInfo.announceForAccessibility('Saved')` for both |
+| Modal | `<Modal>` handles focus; custom overlays need `accessibilityViewIsModal` (iOS) and `importantForAccessibility="no-hide-descendants"` on the content behind (Android) |
+| Move focus | `AccessibilityInfo.setAccessibilityFocus(findNodeHandle(ref.current))` |
+
+Pitfalls:
+
+- A `Pressable` without `accessibilityRole` is read as plain text: the user does not know it is tappable.
+- A checkbox built from `Pressable` and an icon needs `accessibilityRole="checkbox"` and `accessibilityState={{ checked }}`.
+- The iOS-only and Android-only props are silently ignored on the other platform; hiding and modal behavior need both.
+- `TextInput` without a visible label: add `accessibilityLabel`; placeholders are not labels.
+
+## Touch targets and text scaling
+
+- Keep interactive elements at 44×44 pt / 48×48 dp. Use `hitSlop` or padding to extend the area of small icons; `hitSlop` does not extend beyond the parent's bounds on Android.
+- Text scales with the system font size by default. Flag `allowFontScaling={false}` on body text; prefer `maxFontSizeMultiplier` when a layout has a real limit. Avoid fixed `height` on text containers.
+- Respect reduced motion with `AccessibilityInfo.isReduceMotionEnabled()` or Reanimated's `useReducedMotion()`.
+
+## Automated checks
+
+- React Native Testing Library queries by role and label (`screen.getByRole('button', { name: 'Delete task' })`), so tests fail when a role or label disappears. `toBeChecked`, `toBeDisabled` and `toBeExpanded` matchers read the accessibility state.
+- ESLint: `eslint-plugin-react-native-a11y` flags missing roles and labels, when the project uses ESLint.
+- Manual: TalkBack and VoiceOver on devices, the Accessibility Scanner app on Android and Accessibility Inspector in Xcode on the iOS build.

package/skills/mobile-debug/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mobile-debug
-description: Finds the cause of failing builds and runtime errors in mobile apps on every stack — Flutter (pub version solving, Dart compilation, generated code, layout overflows, runtime exceptions), native Android (Gradle, AGP, JDK and Kotlin mismatches, dependency conflicts, manifest merger, R8, logcat crashes and ANRs), native iOS (Xcode signing and provisioning, deployment targets, CocoaPods, Swift Package Manager, crash logs) and React Native (Metro, native modules not found, Hermes, the Android and iOS builds underneath). Use whenever a build, `flutter run`, `pod install`, Gradle task, Xcode archive or app launch fails, when the user pastes a stack trace, "BUILD FAILED" or a red screen, or runs /reis-mobile:debug, even if they only paste the error.
+description: Finds the cause of failing builds and runtime errors in mobile apps on every stack — Flutter (pub version solving, Dart compilation, generated code, layout overflows, runtime exceptions), native Android (Gradle, AGP, JDK and Kotlin mismatches, dependency conflicts, manifest merger, R8, logcat crashes, ANRs and memory leaks), native iOS (Xcode signing and provisioning, deployment targets, CocoaPods, Swift Package Manager, crash logs) and React Native (Metro, native modules not found, Hermes, the Android and iOS builds underneath), plus deep links, App Links and Universal Links that do not open the app. Use whenever a build, `flutter run`, `pod install`, Gradle task, Xcode archive or app launch fails, when the user pastes a stack trace, "BUILD FAILED" or a red screen, or runs /reis-mobile:debug, even if they only paste the error.
 intents: [debug, build, dependency, migration]
 stacks: ["*"]
 ---
@@ -19,6 +19,7 @@ Choose by the stack **and** by the layer the error comes from — a Flutter or R
 | Gradle, the Android build, logcat crashes or ANRs (native Android, or the `android/` folder of any app) | [references/android.md](references/android.md) |
 | Xcode, signing, CocoaPods, Swift packages or iOS crash logs (native iOS, or the `ios/` folder of any app) | [references/ios.md](references/ios.md) |
 | A React Native or Expo app: Metro, native modules, JavaScript errors | [references/react-native.md](references/react-native.md) |
+| A deep link, App Link or Universal Link that opens the browser, the wrong screen or crashes (any stack) | [references/deep-links.md](references/deep-links.md) |
 
 When `reis-mobile debug` (or `/reis-mobile:debug`) ran, its `area` line points at the layer: `gradle`, `manifest`, `proguard` → Android; `xcode`, `signing`, `cocoapods`, `spm` → iOS; `pub` → Flutter; `metro` → React Native.
 

package/skills/mobile-debug/references/android/anr.md

@@ -0,0 +1,59 @@
+# Investigating Android ANRs
+
+An ANR (Application Not Responding) is reported when the main thread cannot process an input event for about five seconds, or when a broadcast receiver, service or job does not finish its callback in the time the system allows. The top frame of the main thread is often the victim, not the cause: find what the main thread was waiting for.
+
+## 1. Get the evidence
+
+| Source | What it gives |
+|---|---|
+| Play Console → Android vitals → ANRs | Clusters with the main thread's stack, affected versions, devices and Android versions |
+| Crashlytics or another reporter with ANR support | Main thread stack; other threads depend on the SDK |
+| `ApplicationExitInfo` (Android 11+) | `REASON_ANR` exits of previous processes, with `getTraceInputStream()` returning the full thread dump — log or upload it on the next launch |
+| `adb bugreport` | ANR traces of all threads when reproduced on a test device |
+| Local reproduction | `adb logcat` shows `ANR in <package>` with the reason; `StrictMode` flags disk and network on the main thread before it becomes an ANR |
+
+High confidence needs the **whole thread dump**, not only the main thread. With a single stack, say the conclusion is tentative and ask for the full trace.
+
+## 2. Read the reason
+
+- `Input dispatching timed out` → the main thread did not handle a touch or key event in time.
+- `Broadcast of Intent { ... }` / `executing service` / `ContentProvider not responding` → a component callback ran too long on the main thread.
+- `Context.startForegroundService() did not then call Service.startForeground()` → the service did not promote itself in time. On recent Android versions this is reported as a crash (`ForegroundServiceDidNotStartInTimeException`) as well.
+
+## 3. Read the main thread's state
+
+In the dump, find `"main" prio=5 tid=1 <State>`:
+
+| State | Look for |
+|---|---|
+| **Runnable** | Work on the main thread: JSON parsing, database queries, `SharedPreferences.commit()`, file I/O, bitmap decoding, crypto, class loading of large SDKs, a loop in layout or composition |
+| **Blocked** | `- waiting to lock <0x...> held by thread N`: open thread N and see what it does while holding the lock |
+| **Waiting / TimedWaiting** | `Object.wait`, `Future.get`, `CountDownLatch.await`, `Thread.join`, `runBlocking`, a `Semaphore` or `Mutex`: find who should release it |
+| **Native** | Binder calls into system services (`BinderProxy.transact`), `SharedPreferences` `apply()` flushing in `QueuedWork.waitToFinish` during `onPause`/`onStop`, file system or graphics calls |
+
+For a deadlock, write down the cycle: thread A holds lock 1 and waits for lock 2; thread B holds lock 2 and waits for lock 1.
+
+## 4. Match the code
+
+- `runBlocking` anywhere reachable from the main thread, including inside interceptors, `ContentProvider`s and DI factories.
+- `@Synchronized` or `synchronized` blocks that also do network or disk work: the lock is held for the whole I/O.
+- Eager initialization in `Application.onCreate`, `ContentProvider.onCreate` (including library initializers) or the first Activity.
+- Room queries without `suspend`/`Flow`, or with `allowMainThreadQueries()`.
+- `BroadcastReceiver.onReceive` doing work beyond starting a `WorkManager` job; `goAsync()` without calling `finish()`.
+- `SharedPreferences.apply()` writes piling up and flushed on lifecycle transitions: move hot data to DataStore.
+- Third-party SDK calls that are synchronous on first use (ads, analytics, feature flags).
+
+## 5. Fix
+
+- Remove the blocking path that the evidence proves, not the top frame. Moving work to `Dispatchers.IO` fixes main-thread I/O; it does not fix a lock held across I/O — shorten the critical section instead.
+- Replace `runBlocking` with a suspending call chain, or with an in-memory value that is refreshed asynchronously.
+- Defer SDK initialization (App Startup with lazy initializers, or initialization after the first frame).
+- Keep receivers, services and job callbacks short; hand long work to `WorkManager`.
+- Do not trade an ANR for lost work or a race: if the result is needed, expose loading state instead of blocking.
+
+## 6. Verify
+
+- Reproduce with the slow dependency made slower (a delay in the network call or the lock owner) on a low-end device or emulator with a cold start.
+- `StrictMode.ThreadPolicy` with `detectAll()` in debug builds shows no violations on the path.
+- A system trace (Perfetto, Android Studio's CPU profiler) shows the main thread free during the flow. See `mobile-android` → the profiler guide.
+- After release, watch the cluster and the user-perceived ANR rate in Android vitals for the new version.

package/skills/mobile-debug/references/android/memory-leaks.md

@@ -0,0 +1,43 @@
+# Investigating Android memory leaks
+
+A leak is an object that should have been garbage collected — usually an Activity, Fragment view, View or Context — kept alive by a reference from something that lives longer. Symptoms: memory growing each time a screen opens, `OutOfMemoryError` after long sessions, and slow GC pauses.
+
+## 1. Get the evidence
+
+- **LeakCanary** (`debugImplementation("com.squareup.leakcanary:leakcanary-android:<version>")`, no code needed) detects retained Activities, Fragments, Fragment views, ViewModels and Services in debug builds and prints the **leak trace**: the chain of references from a GC root to the leaked object. Check the version in the project before adding it.
+- **Android Studio Memory Profiler:** capture a heap dump after opening and closing the screen a few times and forcing GC; filter by the Activity class and look for more instances than screens on the back stack. *Show activity/fragment leaks* highlights destroyed ones.
+- **`OutOfMemoryError` reports** show where the last allocation failed, which is rarely the leak itself; use them to know which flow to profile.
+
+## 2. Read the leak trace
+
+LeakCanary marks each reference as leaking, not leaking or unknown. The bug is in the references between the last **not leaking** object and the first **leaking** one. Typical shape:
+
+```text
+GC Root: static field
+↓ SessionManager.INSTANCE
+↓ SessionManager.listeners        ← likely cause: never unregistered
+↓ ProfileActivity$1 (anonymous listener)
+↓ ProfileActivity                 ← destroyed but retained
+```
+
+## 3. Common causes and fixes
+
+| Cause | Fix |
+|---|---|
+| Singleton, `object` or static field holding an Activity, View or Context | Hold `applicationContext`, or do not store it; pass it per call |
+| Listener or callback registered in `onStart`/`onCreate` and never removed | Unregister in the symmetric callback, or use lifecycle-aware APIs (`repeatOnLifecycle`, `LifecycleObserver`) |
+| Fragment keeping a binding or views after `onDestroyView` | Clear the binding in `onDestroyView`, or use `viewLifecycleOwner` for observers |
+| Coroutine launched in `GlobalScope` or a custom scope that captures the Activity | Use `lifecycleScope`/`viewModelScope`; never capture views in long-running work |
+| ViewModel holding an Activity, Fragment, View or its Context | Keep only data; use `AndroidViewModel` or an injected application context when a Context is needed |
+| Inner or anonymous classes (Handler, Runnable, AsyncTask) outliving the Activity | Static nested class with a weak reference, or cancel pending work in `onDestroy` |
+| `Handler.postDelayed` pending when the screen closes | `removeCallbacksAndMessages(null)` in the teardown |
+| Third-party SDK holding the Activity passed at init | Pass the application context, or report it upstream and add it to LeakCanary's known library leaks |
+| Compose: objects captured in `remember` that hold an Activity, or `DisposableEffect` without cleanup in `onDispose` | Use `LocalContext` at call time; release in `onDispose` |
+
+Not every growth is a leak: image caches and pools are bounded by design. Check whether memory stabilizes after several repetitions before calling it a leak.
+
+## 4. Verify
+
+- Run the flow again with LeakCanary: no retained instance reported.
+- Heap dump after repeating the flow and forcing GC: one or zero instances of the Activity.
+- For large bitmaps and caches, compare the Java and native heap in the profiler before and after.

package/skills/mobile-debug/references/android.md

@@ -24,3 +24,9 @@ In Flutter and React Native apps, run Gradle from `android/` to see the full out
 - An ANR means the main thread was blocked for about five seconds (input) or a broadcast receiver or service ran too long.
 - Get the main thread's stack from Play Console vitals, or from `adb bugreport` (the ANR traces are included), and look at what the main thread was waiting on: disk, network, a lock, `runBlocking`, a binder call.
 - `StrictMode` in debug builds flags disk and network access on the main thread before it becomes an ANR.
+
+Full investigation — evidence sources, reading thread states, locks and deadlocks, fixes and verification: [android/anr.md](android/anr.md).
+
+## Memory leaks and OutOfMemoryError
+
+Retained Activities, Fragments and Contexts, reading LeakCanary traces and heap dumps: [android/memory-leaks.md](android/memory-leaks.md).

package/skills/mobile-debug/references/deep-links.md

@@ -0,0 +1,60 @@
+# Debugging deep links
+
+Deep links fail in three places: the **domain verification** (the link opens the browser), the **app's registration** (the system does not know the app handles the URL) and the **in-app routing** (the app opens on the wrong screen or crashes). Find which one before changing anything. Security checks for deep links (validating parameters, not acting without confirmation) are in `mobile-security`.
+
+## 1. Classify the symptom
+
+| Symptom | Layer to check first |
+|---|---|
+| Opens the browser instead of the app | Verification: `assetlinks.json` / `apple-app-site-association`, entitlement, fingerprint |
+| Works in debug, not from the store build | Verification with the release signing key (Android) or the distribution Team ID (iOS) |
+| Shows a chooser dialog on Android | App Links not verified; the link is treated as a plain intent filter |
+| Opens the app on the home screen | In-app routing: the URL reaches the app but no route matches, or it is lost during cold start |
+| Crashes on open | In-app routing: navigation before the navigator or the auth state is ready |
+| Custom scheme (`myapp://`) does nothing | The scheme is not registered, or the test tool is quoting the URL wrong |
+
+## 2. Android App Links
+
+**Checklist**
+- [ ] `<intent-filter android:autoVerify="true">` with `ACTION_VIEW`, categories `DEFAULT` and `BROWSABLE`, `android:scheme="https"` and the exact `android:host`.
+- [ ] `https://<host>/.well-known/assetlinks.json` returns 200 over HTTPS without redirects, with `Content-Type: application/json`, for **every host** in the filters (including `www` and subdomains).
+- [ ] The file lists the package name and the SHA-256 fingerprint of the certificate that signs the installed build. For Play builds that is the **app signing key** from the Play Console (App integrity), not the upload key; debug builds use the debug keystore fingerprint (`keytool -list -v -keystore ~/.android/debug.keystore`).
+
+**Commands**
+
+```bash
+# Verification state per domain (Android 12+)
+adb shell pm get-app-links com.example.app
+# Re-run verification after fixing the server file
+adb shell pm verify-app-links --re-verify com.example.app
+# Open a link as the system would
+adb shell am start -W -a android.intent.action.VIEW -d "https://example.com/product/42" com.example.app
+```
+
+`verified` means the domain passed; `legacy_failure` or other states mean the server file or the fingerprint is wrong. Google's Statement List Generator and Tester checks a published `assetlinks.json`.
+
+## 3. iOS Universal Links
+
+**Checklist**
+- [ ] The **Associated Domains** capability is on for the App ID and the target, with `applinks:example.com` (and each subdomain) in the entitlements of the build being tested.
+- [ ] `https://<domain>/.well-known/apple-app-site-association` (no file extension) returns 200 over HTTPS without redirects, as JSON.
+- [ ] The file's `applinks.details` contains `<TeamID>.<BundleID>` of that build and `components` (or legacy `paths`) that match the URL's path, query and fragment.
+- [ ] Apple fetches the file through its CDN, not from the device: after changing it, check what the CDN serves at `https://app-site-association.cdn-apple.com/a/v1/<domain>`. To test against your server directly during development, use `applinks:example.com?mode=developer` with Developer Mode enabled on the device.
+
+**Behavior that looks like a bug but is not**
+- Typing or pasting a Universal Link in Safari's address bar opens the website. Test by tapping the link in Notes, Messages or a page on **another** domain.
+- If the user chose to open the site in Safari from the banner, iOS remembers it for that domain; long-press the link and choose *Open in "App"* to reset.
+
+**Tools:** Settings → Developer → Universal Links → Diagnostics on a device with Developer Mode checks a URL against the installed app. For custom schemes on the simulator: `xcrun simctl openurl booted "myapp://product/42"`.
+
+## 4. In-app routing
+
+- **Cold start vs warm start.** The URL arrives through different paths: Android `onCreate` intent vs `onNewIntent`; iOS `scene(_:willConnectTo:options:)` (`connectionOptions.userActivities`/`urlContexts`) vs `scene(_:continue:)`/`scene(_:openURLContexts:)`, or `.onOpenURL` in SwiftUI. A handler implemented only for the warm path loses links that launch the app.
+- **Timing.** Links handled before the navigator, the auth state or remote config is ready either crash or are dropped. Store the pending link and route after initialization; send users to login first and resume the link afterward.
+- **Route matching.** Log the received URL at the entry point and compare with the route patterns: trailing slashes, case, encoded characters and query parameters are frequent mismatches.
+- **Flutter:** with `go_router`, the Flutter deep linking flag (`flutter_deeplinking_enabled` meta-data in `AndroidManifest.xml`, `FlutterDeepLinkingEnabled` in `Info.plist`) lets the router receive links; when a plugin such as `app_links` handles them instead, follow the plugin's instructions for that flag. Check the Flutter version's default before changing it.
+- **React Native:** the `linking` config of React Navigation (`prefixes` and `config.screens`) or Expo Router's file routes decide the screen; test with `npx uri-scheme open "myapp://product/42" --android` (or `--ios`). Expo Go uses its own scheme; test real links in a development build.
+
+## 5. Verify
+
+Test on a device with the build type that will ship, for each link type and host, from cold start and from background, logged in and logged out.

package/skills/mobile-release/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: mobile-release
+description: Prepares and checks mobile app releases on every stack — release readiness (go/no-go) checklist, version name and build number, signing, crash symbols (R8 mappings, dSYMs, Dart split debug info, JavaScript source maps), store requirements, staged rollout and rollback, release notes and store listing copy with the Google Play and App Store character limits, and CI/CD pipelines with GitHub Actions, fastlane and EAS — for Flutter, native Android, native iOS and React Native. Use when preparing a version for Google Play or the App Store, auditing whether a build is ready to ship, writing release notes or store descriptions from the git history, setting up or reviewing a build and deploy pipeline, or planning a rollout, even if the user only says "we ship on Friday".
+intents: [release, deployment]
+stacks: ["*"]
+---
+
+# Mobile Release
+
+One release process for every mobile stack. This file holds the process and what is true everywhere; each platform's versioning, signing, symbols and store details live in its reference.
+
+## 1. Pick the references
+
+| Need | Read |
+|---|---|
+| Flutter app | [references/flutter.md](references/flutter.md) |
+| Native Android, or the Android build of any app | [references/android.md](references/android.md) |
+| Native iOS, or the iOS build of any app | [references/ios.md](references/ios.md) |
+| React Native or Expo app | [references/react-native.md](references/react-native.md) |
+| Release notes and store listing text | [references/store-copy.md](references/store-copy.md) |
+| A CI/CD pipeline that builds, signs and uploads | [references/ci-cd.md](references/ci-cd.md) |
+
+Flutter and React Native apps also need the Android and iOS references for signing and store details. Deeper platform guides live in the platform skills: Google Play policy and Play Billing in `mobile-android`, TestFlight and App Store Connect in `mobile-ios`, EAS in `mobile-rn`. Security hardening before release is in `mobile-security`.
+
+## 2. Readiness checklist
+
+Check each item against the project, not against memory. Mark each one **pass**, **fail** (with `file:line` or the missing artifact) or **unknown** (needs information only the team has, such as the store console state).
+
+**Version**
+- [ ] The version name follows the project's scheme and changed since the last release tag (`git describe --tags --abbrev=0`).
+- [ ] The build number is higher than any build already uploaded. Both stores reject a build number they have seen.
+- [ ] Android, iOS and any cross-platform manifest (`pubspec.yaml`, `app.json`) agree on the version.
+
+**Build quality**
+- [ ] CI is green on the release commit: lint or analysis, tests, and a release build for each platform.
+- [ ] The release build is the one tested: release configuration, production environment, real signing — not a debug build.
+- [ ] No debug leftovers: logging of sensitive data, debug menus, test endpoints, `debuggable` or development entitlements, feature flags pointing at staging.
+- [ ] Crash symbols for this exact build are uploaded or archived: R8 mapping, dSYMs, Dart debug info, JavaScript source maps.
+
+**Store and compliance**
+- [ ] The target SDK, minimum OS and build toolchain meet the store's current requirements. These change every year: tell the user to confirm them in the Play Console and Apple's upload requirements instead of stating dates from memory.
+- [ ] New permissions, tracking or data collection are reflected in the Play Data safety form, the App Store privacy details, privacy manifests and the privacy policy.
+- [ ] Reviewers can reach every feature: a demo account and notes for anything behind login, hardware or location.
+- [ ] Release notes and, when features changed, screenshots and description are ready in every listed language.
+
+**Rollout**
+- [ ] Staged rollout (Play) or phased release (App Store) planned for updates, with the crash-free and ANR metrics to watch and the threshold that halts it.
+- [ ] Rollback plan: stores do not roll back a binary. Halting a rollout stops new installs; users who updated need a new build with a higher build number, a server-side kill switch or a remote config flag. Know which one applies before shipping.
+- [ ] The release commit is tagged and the tag matches the version.
+
+## 3. Report
+
+```markdown
+## Release readiness — <app> <version> (<build>)
+Verdict: GO | GO WITH RISKS | NO-GO
+
+### Blockers
+- item — evidence (file:line or missing artifact) — fix
+
+### Risks
+- item — why it matters — mitigation
+
+### Unknown
+- item — who or what can confirm it
+
+### Rollout plan
+Stages, metrics to watch, halt threshold, rollback path.
+```
+
+A single blocker makes the verdict NO-GO. Do not bump versions, create tags, upload builds or change store settings unless the user asks; propose the exact commands instead.

package/skills/mobile-release/references/android.md

@@ -0,0 +1,47 @@
+# Releasing on Android
+
+Google Play specifics: policy compliance and Play Billing live in `mobile-android` → `references/play.md`; R8 keep rules in its build and performance guides.
+
+## Version
+
+- `versionCode` (integer) must increase with every upload to Play, across all tracks. `versionName` is what users see.
+- Set them in `defaultConfig` of `app/build.gradle(.kts)`, or from CI (`-PversionCode=...` read in the build script). Flutter and Expo generate them from their own manifests; see their references.
+- When several APKs or bundles share a version (Wear OS, TV, different ABIs), each needs a distinct `versionCode`.
+
+## Build and signing
+
+```bash
+./gradlew bundleRelease          # app/build/outputs/bundle/release/app-release.aab
+```
+
+- Google Play requires an Android App Bundle (`.aab`) for new apps. Use APKs only for other stores or direct distribution.
+- With **Play App Signing**, Google holds the app signing key and you sign uploads with the **upload key**. A lost upload key can be reset through the Play Console; a lost app signing key outside Play App Signing cannot. Check in *Test and release → App integrity* which setup the app uses.
+- Keystore passwords and the keystore itself never live in the repository. Read them from environment variables or an untracked `keystore.properties`, and check `.gitignore`.
+- Fingerprints for App Links (`assetlinks.json`), Google Sign-In and Firebase come from the **app signing key** shown in the Play Console for Play builds, not from the upload or debug key.
+
+## Symbols
+
+- **R8 mapping** (`app/build/outputs/mapping/release/mapping.txt`) deobfuscates stack traces. Check in the Play Console's App bundle explorer that the deobfuscation file is attached to the version, and upload it when it is not. Crashlytics uploads it through its Gradle plugin. Archive it with the build either way.
+- **Native symbols** for apps with C/C++ code: `android { buildTypes { release { ndk { debugSymbolLevel = "FULL" } } } }` (or `"SYMBOL_TABLE"`) adds them to the bundle.
+
+## Before uploading
+
+- [ ] `targetSdk` meets Google Play's current target API level requirement (it moves every year; confirm in the Play Console or the Play policy guide).
+- [ ] `isMinifyEnabled` and `isShrinkResources` enabled for release, and the release build tested with them.
+- [ ] `android:debuggable` not set, no `usesCleartextTraffic="true"` without a scoped network security config, `android:allowBackup` decided on purpose.
+- [ ] New permissions justified; sensitive ones (location in background, SMS, call log, all files access, exact alarms) have the Play declaration they need.
+- [ ] Data safety form updated for new SDKs or data collection.
+- [ ] Release notes (500 characters per language) ready — see [store-copy.md](store-copy.md).
+
+## Tracks and rollout
+
+- **Internal testing** for fast team builds, **closed testing** for a group of testers, **open testing** for a public beta, **production**.
+- New personal developer accounts must run a closed test with a minimum number of testers for a minimum period before applying for production access; check the current numbers in the Play Console.
+- Production updates go out as a **staged rollout** (a percentage of users). Increase it while the Android vitals (user-perceived crash rate and ANR rate) stay at the baseline of the previous version; **halt** the rollout when they regress. Halting stops new installs but does not revert users who already updated: the fix is a new build with a higher `versionCode`.
+- **Managed publishing** holds approved changes until you publish them, useful to coordinate with a backend release.
+
+## Automation
+
+- `fastlane supply` (`upload_to_play_store`) uploads bundles, notes and listing text with a service account JSON key.
+- The Gradle Play Publisher plugin (`com.github.triplet.play`) does the same from Gradle.
+- The service account needs access granted in the Play Console (*Users and permissions*), limited to the app and the tracks it publishes to.