reis-mobile 0.4.0 → 0.6.0

package/skills/{ios-code-review/SKILL.md → mobile-code-review/references/ios.md}

@@ -1,10 +1,3 @@
----
-name: ios-code-review
-description: Reviews native iOS code in Swift and Objective-C for the bugs that reach production — retain cycles in closures, delegates, timers and observers, Swift concurrency mistakes such as UI updates off the main actor, uncancelled tasks and data races, SwiftUI ownership and identity bugs (@StateObject vs @ObservedObject, ForEach ids), force unwraps and try! in production paths, main-thread blocking, and privacy and permission handling. Use when reviewing Swift or Objective-C files in an iOS app, view controllers, SwiftUI views, view models, networking or persistence code, or when the user asks for an iOS code review or PR review.
-intents: [review, performance]
-stacks: [ios]
----
-
 # iOS Code Review
 
 Apply to Swift and Objective-C sources of the app and its extensions. Items are ordered by impact: the first sections cause crashes, leaks or data races. Before flagging an API, check the deployment target (`IPHONEOS_DEPLOYMENT_TARGET`) — `@Observable`, for example, requires iOS 17.
@@ -39,7 +32,7 @@ Apply to Swift and Objective-C sources of the app and its extensions. Items are
 
 ## 5. Platform and privacy
 
-- [ ] **Credentials and tokens** in `UserDefaults` or files instead of the Keychain. Details in `mobile-security-audit`.
+- [ ] **Credentials and tokens** in `UserDefaults` or files instead of the Keychain. Details in `mobile-security`.
 - [ ] **Permissions.** Each protected API used needs its `NS...UsageDescription` in `Info.plist`, and the code must handle denied and restricted states, not only granted.
 - [ ] **Background execution.** Work that must finish when the app goes to background without `beginBackgroundTask` or `BGTaskScheduler`.
 - [ ] **Deployment target.** APIs used without `#available` checks when the deployment target is lower than the API's availability.

package/skills/mobile-code-review/references/react-native.md

@@ -0,0 +1,58 @@
+# React Native Code Review
+
+Apply to TypeScript and JavaScript sources of a React Native or Expo app, and to its native modules with the native checklists. Items are ordered by impact: the first sections cause crashes, leaks or wrong data. Check the React Native or Expo SDK version and the library versions in `package.json` before recommending an API.
+
+## 1. Hooks and effects (bug / leak)
+
+- [ ] **Missing effect cleanup.** Listeners (`AppState`, `Keyboard`, `Linking`, `Dimensions`), subscriptions, intervals and timeouts added in `useEffect` without returning a cleanup function.
+- [ ] **Stale closures.** Effects, callbacks or memoized values that read props or state not listed in the dependency array. `react-hooks/exhaustive-deps` warnings silenced without a reason are findings.
+- [ ] **State updates after unmount.** Requests started in an effect and never cancelled (no `AbortController`, no ignore flag) updating state of a screen the user left.
+- [ ] **Hooks called conditionally** or inside loops.
+- [ ] **Effects used for derived data.** State computed from props in an effect instead of during render causes an extra render and flicker.
+
+## 2. State and data
+
+- [ ] **Server data copied into global state** (Redux, Zustand, context) and synchronized by hand, instead of a server-state cache such as TanStack Query or RTK Query.
+- [ ] **Impossible states.** Separate `loading`, `error` and `data` flags that can contradict each other; missing error and empty states.
+- [ ] **Unvalidated responses.** API data used with `as` casts and no runtime validation at the boundary, so a contract change crashes deep in the UI.
+- [ ] **Navigation params** carrying large objects, functions or data that should be fetched by id; params not typed.
+
+## 3. Rendering performance
+
+- [ ] **Long lists in `ScrollView` + `.map()`** instead of `FlatList`/`SectionList` (or FlashList, if the project uses it); missing or index-based `keyExtractor` for lists that change.
+- [ ] **Context values recreated every render**, re-rendering every consumer; one large context for unrelated state.
+- [ ] **Inline objects and callbacks** passed to memoized components, defeating `React.memo`. Only report on hot paths.
+- [ ] **Animations driven by JavaScript state** per frame instead of Reanimated or `useNativeDriver: true`.
+- [ ] **Remote images** without caching or sized far larger than displayed.
+
+## 4. Platform and native code
+
+- [ ] **Platform branches** (`Platform.OS`) scattered through screens instead of `.ios.tsx`/`.android.tsx` files or a small platform module.
+- [ ] **Permissions** requested without handling denial or "don't ask again"; Android 13+ notification permission missing when push is used.
+- [ ] **Deep links** (`Linking`, navigation linking config) acting on parameters without validating them.
+- [ ] **Native modules** called directly from many components instead of one typed wrapper; changes to native code without the matching iOS and Android updates.
+- [ ] **Safe areas and keyboard:** screens without safe area handling; forms hidden by the keyboard.
+
+## 5. Security
+
+- [ ] Tokens or credentials in `AsyncStorage` instead of the Keychain/Keystore (`react-native-keychain`, `expo-secure-store`).
+- [ ] Secrets in `.env` files read through `react-native-config` or `EXPO_PUBLIC_*` variables: they are bundled into the app and readable.
+- [ ] `react-native-webview` with `originWhitelist={['*']}` and an `onMessage` handler that acts on messages.
+- [ ] Sensitive data in `console.log`, which stays in release builds unless removed. Details in `mobile-security`.
+
+## 6. Expo and release
+
+- [ ] Config plugins or `app.json`/`app.config.*` changes that require a new native build, shipped as an over-the-air update. Check that `runtimeVersion` changes when native code or config changes.
+- [ ] Secrets placed in `app.json` `extra` fields, which are bundled into the app.
+- [ ] Hermes disabled, or debug-only code (`__DEV__` branches missing) reachable in production.
+
+## 7. Maintainability, accessibility and tests
+
+- [ ] `any` types and `@ts-ignore` added without a reason; `strict` mode relaxed.
+- [ ] Touchable elements without `accessibilityRole` and `accessibilityLabel`; touch targets smaller than about 44–48 points; text that ignores font scaling.
+- [ ] User-visible strings hardcoded when the project uses i18n.
+- [ ] New logic, hooks or screens without tests when the project has a Jest suite.
+
+## Output
+
+Report in the matching section of the review (Bugs for sections 1–2, Performance for section 3, Security for section 5), always with `file:line` and the corrected snippet when the fix is short.

package/skills/mobile-debug/SKILL.md

@@ -0,0 +1,51 @@
+---
+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, 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: ["*"]
+---
+
+# Mobile Debug
+
+One debugging process for every mobile stack. This file holds how to find a cause; each platform's error signatures and fixes live in its reference.
+
+## 1. Pick the reference
+
+Choose by the stack **and** by the layer the error comes from — a Flutter or React Native build often fails inside Gradle or Xcode:
+
+| The failure is in | Read |
+|---|---|
+| A Flutter app: pub, Dart compilation, generated code, widgets, runtime exceptions | [references/flutter.md](references/flutter.md) |
+| 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.
+
+## 2. Find the first real error
+
+Build and crash logs bury the cause under cascading failures. Quote the line that starts the failure — the first `error:`, the `What went wrong` block, the top of the exception with its `Caused by` — not the final `BUILD FAILED` or the last frame. Ask for the full output when the user pasted only the end.
+
+## 3. Collect versions before theorizing
+
+Most build failures after an upgrade are toolchain mismatches. Read the versions that decide the behavior — the SDK and toolchain versions (the doctor report shows them), wrapper and lock files, build scripts, deployment targets — and quote them in the diagnosis. Check compatibility against the official tables named in the reference; do not state compatibility ranges from memory.
+
+## 4. Reproduce safely
+
+Read-only commands can run: version checks, dependency trees, `flutter doctor -v`, `./gradlew --version`, `pod --version`, `xcodebuild -version`. A build that only compiles can run when the user already ran it or agrees, since it takes time and writes build outputs.
+
+## 5. Confirm the cause
+
+Tie the cause to evidence: `file:line`, a version, a build setting or a log line. If two causes are plausible, say what evidence would separate them instead of picking one.
+
+## 6. Propose, then wait
+
+Answer with:
+
+- **Cause** — one or two sentences, with the evidence.
+- **Fix** — the minimal change, as a diff or exact commands, in order.
+- **Side effects** — what else the fix changes: a higher minimum Android or iOS version, a Gradle or Kotlin upgrade that CI needs too, pods changing version.
+- **Verify** — the command that failed, run again.
+
+Do not edit files, upgrade dependencies or run commands that change the project, the caches or the machine — `flutter clean`, `pod install`, `pod repo update`, `npx expo prebuild --clean`, deleting `DerivedData`, `~/.gradle` caches or `node_modules` — until the user asks you to apply the fix. Then apply it, run the verification and report the result.

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/{android-gradle-build-debug/SKILL.md → mobile-debug/references/android/gradle-build.md}

@@ -1,11 +1,3 @@
----
-name: android-gradle-build-debug
-description: Diagnoses failing Android Gradle builds — JDK, Gradle, Android Gradle Plugin and Kotlin version mismatches, dependency resolution and duplicate classes, compileSdk and minSdk errors, manifest merger and namespace failures, kapt/KSP, R8 missing classes, signing and out-of-memory builds. Use whenever an Android, Kotlin Multiplatform, Flutter or React Native build fails in Gradle, when the log shows "What went wrong", "Execution failed for task" or "BUILD FAILED", or after upgrading AGP, Gradle, Kotlin or the JDK, even if the user only pastes the error.
-intents: [debug, build, dependency, migration]
-stacks: [android, kotlin-multiplatform]
-areas: [gradle, manifest, proguard, signing]
----
-
 # Android Gradle Build Debug
 
 A Gradle failure is usually one of a few causes wearing a long stack trace. Work in this order: find the first real error, check the toolchain versions, then match the error to a section below. Confirm every cause in the build files before proposing a fix.

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

@@ -0,0 +1,32 @@
+# Debugging Android
+
+## Build failures
+
+Gradle, AGP, JDK and Kotlin mismatches, dependency resolution and duplicate classes, compileSdk and minSdk errors, manifest merger, namespace, kapt/KSP, R8 and signing: [android/gradle-build.md](android/gradle-build.md).
+
+In Flutter and React Native apps, run Gradle from `android/` to see the full output.
+
+## Crashes at runtime
+
+1. **Get the stack trace.** `adb logcat -b crash` shows the crash buffer; `adb logcat *:E` all errors. Start from the first `FATAL EXCEPTION` and follow every `Caused by:` to the root.
+2. **Deobfuscate release traces.** Stack traces from R8-minified builds show short names; retrace them with the `retrace` tool from the Android SDK command-line tools and the `mapping.txt` of that exact build (`app/build/outputs/mapping/<variant>/`). Crashlytics and Play Console do it automatically when the mapping file was uploaded.
+3. **Match the signature:**
+   - `NullPointerException` / `lateinit property has not been initialized` → an object used before its lifecycle creates it, or after it is destroyed (a Fragment view after `onDestroyView`).
+   - `IllegalStateException: Fragment not attached to a context`, `Can not perform this action after onSaveInstanceState` → work finishing after the screen stopped; tie it to the lifecycle.
+   - `NetworkOnMainThreadException`, `Cannot access database on the main thread` → I/O on the main thread; move it to `Dispatchers.IO`.
+   - `ClassNotFoundException` / `NoSuchMethodError` only in release → R8 removed or renamed something used through reflection; add the library's keep rules.
+   - `SecurityException: Permission Denial` → a missing runtime permission, or an exported component contract mismatch.
+   - `ForegroundServiceStartNotAllowedException`, `SecurityException` for exact alarms → restrictions that depend on `targetSdk`; check the behavior changes for that API level.
+4. **Native (C/C++) crashes** (`signal 11 (SIGSEGV)`, tombstones) need symbols: symbolize with `ndk-stack` and the unstripped libraries of that build.
+
+## ANRs
+
+- 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/{flutter-build-debug/SKILL.md → mobile-debug/references/flutter/build.md}

@@ -1,11 +1,3 @@
----
-name: flutter-build-debug
-description: Diagnoses failing Flutter builds by locating the layer that broke — Dart compilation, pub version solving, generated code, the Android Gradle side or the iOS Xcode and CocoaPods side — and checking the Flutter SDK, JDK, Gradle, AGP, Kotlin and deployment target versions Flutter requires. Use whenever `flutter run`, `flutter build apk/appbundle/ios/ipa`, `flutter pub get` or a Flutter CI job fails, after upgrading Flutter, or when a plugin breaks the native build, even if the user only pastes the error.
-intents: [debug, build, dependency, migration]
-stacks: [flutter]
-areas: [pub, gradle, cocoapods, xcode]
----
-
 # Flutter Build Debug
 
 A Flutter build runs four toolchains in sequence: pub, the Dart compiler, Gradle for Android and Xcode with CocoaPods for iOS. The error message comes from one of them, and the fix belongs to that one. Identify the layer first.
@@ -16,8 +8,8 @@ A Flutter build runs four toolchains in sequence: pub, the Dart compiler, Gradle
 |---|---|---|
 | `version solving failed`, `Because X depends on Y` | pub | Section 3 |
 | `lib/...dart:LINE:COL: Error:` | Dart compiler | Section 4 |
-| `FAILURE: Build failed with an exception`, `Execution failed for task`, `Gradle task assembleDebug failed` | Android / Gradle | Section 5, then `android-gradle-build-debug` |
-| `Xcode build done` with errors, `Error (Xcode):`, `pod install` output | iOS / Xcode / CocoaPods | Section 6, then `ios-xcode-build-debug` or `ios-cocoapods-debug` |
+| `FAILURE: Build failed with an exception`, `Execution failed for task`, `Gradle task assembleDebug failed` | Android / Gradle | Section 5, then [../android/gradle-build.md](../android/gradle-build.md) |
+| `Xcode build done` with errors, `Error (Xcode):`, `pod install` output | iOS / Xcode / CocoaPods | Section 6, then [../ios/xcode-build.md](../ios/xcode-build.md) or [../ios/cocoapods.md](../ios/cocoapods.md) |
 
 `flutter run -v` or `flutter build <target> -v` prints the underlying tool output when the summary is not enough.
 
@@ -48,14 +40,14 @@ Collect the versions in `android/`: Gradle in `gradle/wrapper/gradle-wrapper.pro
 - [ ] `You are applying Flutter's main Gradle plugin imperatively using the apply script method` → the project uses the old `apply from: .../flutter.gradle` setup. Migrate to the declarative `plugins {}` block described in Flutter's "Deprecated imperative apply of Flutter's Gradle plugins" guide.
 - [ ] Wrong JDK → `flutter config --jdk-dir <path>` points Flutter at a specific JDK; check `flutter doctor -v` again afterwards.
 - [ ] A plugin requiring a higher `minSdk` or `compileSdk` → set it in `android/app/build.gradle(.kts)`. `flutter.minSdkVersion` is Flutter's default, which a plugin may exceed.
-- For anything else in Gradle, apply `android-gradle-build-debug`.
+- For anything else in Gradle, apply [../android/gradle-build.md](../android/gradle-build.md).
 
 ## 6. iOS side
 
-- [ ] `pod install` errors or `CocoaPods not installed` → apply `ios-cocoapods-debug`. Run pod commands from `ios/`.
+- [ ] `pod install` errors or `CocoaPods not installed` → apply [../ios/cocoapods.md](../ios/cocoapods.md). Run pod commands from `ios/`.
 - [ ] `Module 'x' not found` in Xcode → open `ios/Runner.xcworkspace`, not `Runner.xcodeproj`.
 - [ ] Deployment target conflicts → `platform :ios` in `ios/Podfile` and `IPHONEOS_DEPLOYMENT_TARGET` in the Runner project must be at least what the plugins require.
-- [ ] Signing errors on `flutter build ipa` → apply `ios-xcode-build-debug`.
+- [ ] Signing errors on `flutter build ipa` → apply [../ios/xcode-build.md](../ios/xcode-build.md).
 
 ## 7. Cleaning, with confirmation
 

package/skills/{flutter-errors/SKILL.md → mobile-debug/references/flutter/errors.md}

@@ -1,11 +1,4 @@
----
-name: flutter-errors
-description: Diagnoses and fixes common Flutter errors. Use when encountering layout errors (RenderFlex overflow, unbounded constraints, RenderBox not laid out), scroll errors, or setState-during-build errors.
-intents: [debug]
-stacks: [flutter]
-source: https://github.com/evanca/flutter-ai-rules
-license: MIT
----
+> Adapted from the `flutter-errors` skill in [evanca/flutter-ai-rules](https://github.com/evanca/flutter-ai-rules) (MIT). See `THIRD_PARTY_NOTICES.md`.
 
 # Flutter Errors Skill
 

package/skills/{flutter-fix-layout-issues/SKILL.md → mobile-debug/references/flutter/layout-issues.md}

@@ -1,14 +1,5 @@
----
-name: flutter-fix-layout-issues
-description: Fixes Flutter layout errors (overflows, unbounded constraints) using Dart and Flutter MCP tools. Use when addressing "RenderFlex overflowed", "Vertical viewport was given unbounded height", or similar layout issues.
-metadata:
-  model: models/gemini-3.1-pro-preview
-  last_modified: Tue, 21 Apr 2026 19:45:59 GMT
-intents: [debug]
-stacks: [flutter]
-source: https://github.com/flutter/skills
-license: BSD-3-Clause
----
+> Adapted from the `flutter-fix-layout-issues` skill in [flutter/skills](https://github.com/flutter/skills) (BSD-3-Clause). See `THIRD_PARTY_NOTICES.md`.
+
 # Resolving Flutter Layout Errors
 
 ## Contents

package/skills/{flutter-dart-resolve-package-conflicts/SKILL.md → mobile-debug/references/flutter/package-conflicts.md}

@@ -1,14 +1,5 @@
----
-name: flutter-dart-resolve-package-conflicts
-description: Workflow for fixing package version conflicts. Use this when `pub get` fails due to incompatible package versions.
-metadata:
-  model: models/gemini-3.1-pro-preview
-  last_modified: Fri, 24 Apr 2026 15:11:14 GMT
-intents: [debug, dependency]
-stacks: [flutter]
-source: https://github.com/dart-lang/skills
-license: BSD-3-Clause
----
+> Adapted from the `dart-resolve-package-conflicts` skill in [dart-lang/skills](https://github.com/dart-lang/skills) (BSD-3-Clause). See `THIRD_PARTY_NOTICES.md`.
+
 # Managing Dart Dependencies
 
 ## Contents

package/skills/{flutter-dart-fix-runtime-errors/SKILL.md → mobile-debug/references/flutter/runtime-errors.md}

@@ -1,14 +1,5 @@
----
-name: flutter-dart-fix-runtime-errors
-description: Uses get_runtime_errors and lsp to fetch an active stack trace, locate the failing line, apply a fix, and verify resolution via hot_reload.
-metadata:
-  model: models/gemini-3.1-pro-preview
-  last_modified: Fri, 24 Apr 2026 15:13:22 GMT
-intents: [debug]
-stacks: [flutter]
-source: https://github.com/dart-lang/skills
-license: BSD-3-Clause
----
+> Adapted from the `dart-fix-runtime-errors` skill in [dart-lang/skills](https://github.com/dart-lang/skills) (BSD-3-Clause). See `THIRD_PARTY_NOTICES.md`.
+
 # Resolving Dart Static Analysis Errors
 
 ## Contents

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

@@ -0,0 +1,23 @@
+# Debugging Flutter apps
+
+Identify whether the failure happens while **building** or while **running**, then open the matching guide.
+
+| Symptom | Guide |
+|---|---|
+| `flutter run` / `flutter build` fails: pub version solving, Dart compile errors, generated code, the Gradle or Xcode step | [flutter/build.md](flutter/build.md) — locates the failing layer and hands off to the native guides |
+| `version solving failed`, incompatible package constraints | [flutter/package-conflicts.md](flutter/package-conflicts.md) |
+| Exceptions at runtime: red screen, `Null check operator used on a null value`, `setState() called after dispose()`, assertion failures | [flutter/errors.md](flutter/errors.md) |
+| An exception with a live app and the Dart/Flutter MCP tools available | [flutter/runtime-errors.md](flutter/runtime-errors.md) |
+| `RenderFlex overflowed`, `unbounded height/width`, `Vertical viewport was given unbounded height` | [flutter/layout-issues.md](flutter/layout-issues.md) |
+
+## First checks for any Flutter failure
+
+```bash
+flutter --version
+flutter doctor -v          # Flutter, Dart, Android toolchain and the JDK it uses, Xcode, CocoaPods
+flutter run -v             # or flutter build <target> -v, for the full underlying output
+```
+
+- A project pinned with FVM (`.fvmrc`, `.fvm/`) or asdf must run with that Flutter version, not the global one.
+- Native failures inside `android/` follow [android.md](android.md); inside `ios/`, [ios.md](ios.md).
+- `flutter clean` removes `build/` and `.dart_tool/`: it fixes stale outputs, not version conflicts. Propose it only after the version checks, and run it only when the user agrees.

package/skills/{ios-cocoapods-debug/SKILL.md → mobile-debug/references/ios/cocoapods.md}

@@ -1,11 +1,3 @@
----
-name: ios-cocoapods-debug
-description: Diagnoses CocoaPods failures in iOS, Flutter and React Native projects — "could not find compatible versions", outdated spec repos, "sandbox is not in sync with the Podfile.lock", deployment target conflicts, Ruby and CocoaPods installation problems on Apple Silicon, Bundler-managed CocoaPods, post_install hooks and private spec sources. Use whenever `pod install` or `pod update` fails, when an iOS build breaks inside the Pods project, when Podfile or Podfile.lock is involved, or when the user asks whether to delete Pods or run pod update, even if they only paste the error.
-intents: [debug, dependency, build, migration]
-stacks: [ios]
-areas: [cocoapods]
----
-
 # iOS CocoaPods Debug
 
 Most CocoaPods failures come from three places: the spec repository is out of date, the version constraints cannot be satisfied, or the Ruby installation running `pod` is broken. Identify which one before touching `Podfile.lock`.
@@ -44,7 +36,7 @@ In Flutter, run these from `ios/`; `flutter build ios` and `flutter run` already
 ## 4. Build errors inside Pods
 
 - [ ] Pods compiled with a lower deployment target than Xcode supports (warnings like `The iOS deployment target 'IPHONEOS_DEPLOYMENT_TARGET' is set to 9.0, but the range of supported deployment target versions is ...`) → a `post_install` hook that sets the deployment target for the pod targets. Keep the existing hook content (Flutter's `flutter_additional_ios_build_settings` must stay).
-- [ ] Script phases failing with sandbox `deny` errors after moving to Xcode 15 or later → see `ios-xcode-build-debug` (user script sandboxing); updating CocoaPods is the first step.
+- [ ] Script phases failing with sandbox `deny` errors after moving to Xcode 15 or later → see [xcode-build.md](xcode-build.md) (user script sandboxing); updating CocoaPods is the first step.
 - [ ] `No such module` for a pod → the project was built as `.xcodeproj` instead of `.xcworkspace`, or the target is missing from the `Podfile`.
 - [ ] `use_frameworks!` changes (static vs dynamic) → some pods require one mode; changing it affects every pod. Check each pod's installation notes before switching.
 

package/skills/{ios-xcode-build-debug/SKILL.md → mobile-debug/references/ios/xcode-build.md}

@@ -1,11 +1,3 @@
----
-name: ios-xcode-build-debug
-description: Diagnoses failing iOS builds in Xcode and xcodebuild — code signing and provisioning, deployment target mismatches, "No such module", Apple Silicon simulator architecture errors, script phases failing under user script sandboxing, Swift Package Manager resolution, duplicate build outputs and errors after upgrading Xcode or Swift. Use whenever an iOS, Flutter or React Native build fails in Xcode, when the log shows "Command PhaseScriptExecution failed", "Signing for ... requires a development team", "Undefined symbols" or "BUILD FAILED", or when an archive or TestFlight upload breaks, even if the user only pastes the error.
-intents: [debug, build, release, migration]
-stacks: [ios]
-areas: [xcode, signing, spm]
----
-
 # iOS Xcode Build Debug
 
 Xcode shows the last error loudly and the first one quietly. Work in this order: find the first real error, collect the versions, then match the error to a section below. Confirm every cause in the project files before proposing a fix.

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

@@ -0,0 +1,23 @@
+# Debugging iOS
+
+## Build failures
+
+| Symptom | Guide |
+|---|---|
+| Xcode or `xcodebuild` errors: signing and provisioning, deployment target, `No such module`, `Undefined symbols`, script phases and sandboxing, Swift Package Manager, errors after upgrading Xcode or Swift | [ios/xcode-build.md](ios/xcode-build.md) |
+| `pod install` / `pod update` failures, `Podfile.lock` conflicts, Ruby and CocoaPods installation, build errors inside the Pods project | [ios/cocoapods.md](ios/cocoapods.md) |
+
+In Flutter and React Native apps, run pod commands and open the workspace from `ios/`.
+
+## Crashes at runtime
+
+1. **Get the crash report.** While debugging, Xcode stops at the crash; for devices and TestFlight, use Xcode's Organizer (Crashes) or the device logs in *Devices and Simulators*. Crash reports (`.ips`) need the build's dSYM to be symbolicated; unsymbolicated frames show only addresses.
+2. **Read the exception type and the crashed thread**, not the first frame of the main thread only.
+3. **Match the signature:**
+   - `Fatal error: Unexpectedly found nil while unwrapping an Optional value` / `EXC_BREAKPOINT` in Swift code → a force unwrap, `try!`, `as!` or an out-of-range index on the crashed line.
+   - `EXC_BAD_ACCESS` → use of freed memory or a data race; reproduce with **Address Sanitizer** or **Thread Sanitizer** enabled in the scheme's diagnostics.
+   - `Main Thread Checker: UI API called on a background thread` → UI updated off the main actor; the Main Thread Checker diagnostic reports the exact call.
+   - `This app has crashed because it attempted to access privacy-sensitive data without a usage description` → a missing `NS...UsageDescription` key in `Info.plist`.
+   - `Terminating app due to uncaught exception 'NSInternalInconsistencyException'` in table or collection views → the data source changed without matching updates; use diffable data sources.
+   - Watchdog terminations (`0x8badf00d`) → the main thread blocked too long, often at launch.
+4. **Crashes only in release or TestFlight** → optimization-dependent races, missing entitlements or capabilities in the distribution profile, or code under `#if DEBUG`. Reproduce with the Release configuration.

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

@@ -0,0 +1,43 @@
+# Debugging React Native apps
+
+A React Native app fails in one of three layers: the JavaScript bundle (Metro), the native build (Gradle or Xcode), or at runtime. Find the layer before changing anything.
+
+| Output contains | Layer | Next step |
+|---|---|---|
+| `Unable to resolve module`, `SyntaxError` in the bundle, Metro red screen before the app renders | Metro / JavaScript bundle | Section 2 |
+| `FAILURE: Build failed with an exception`, `Execution failed for task` | Android build | [android.md](android.md) — run Gradle from `android/` |
+| `pod install` errors, Xcode `error:` lines | iOS build | [ios.md](ios.md) — run pods from `ios/` |
+| `TurboModuleRegistry.getEnforcing(...): 'X' could not be found`, `requireNativeComponent: 'X' was not found in the UIManager`, `The package 'X' doesn't seem to be linked` | Native module missing from the running binary | Section 3 |
+| A red screen or LogBox error after the app renders | JavaScript runtime | Section 4 |
+
+## 1. Versions
+
+- `npx react-native info` (or `npx expo-doctor` in Expo projects): React Native, Node, Java, Xcode, CocoaPods and package versions in one place.
+- React Native, the Expo SDK and native libraries must be versions that support each other; check each library's compatibility notes. After a React Native upgrade, compare native file changes with the React Native Upgrade Helper for the two versions.
+- Check whether the New Architecture is enabled (`newArchEnabled` in `android/gradle.properties`, the Podfile or `app.json`) before debugging a native module: older libraries may not support it.
+
+## 2. Metro and the JavaScript bundle
+
+- `Unable to resolve module X` → the package is not installed, the import path is wrong, or Metro's cache is stale after installing. Check `package.json` and the path first; then restart Metro with a clean cache (`npx react-native start --reset-cache`, or `npx expo start -c`).
+- Monorepos and symlinked packages need `watchFolders` and resolver settings in `metro.config.js`.
+- `Invariant Violation: "main" has not been registered` → the bundle failed to load earlier (read the first error in the Metro terminal), or the name in `AppRegistry.registerComponent` differs from the native side.
+
+## 3. Native module not found
+
+The JavaScript side expects a native module that the installed binary does not contain.
+
+- The app was not rebuilt after installing a library with native code: rebuild (`npx react-native run-android` / `run-ios`, or a new development build with Expo).
+- Expo Go only contains the Expo SDK's modules; libraries with other native code need a development build.
+- iOS: `pod install` did not run after installing the library.
+- The library does not support the architecture the app runs (New Architecture vs legacy); check its documentation.
+
+## 4. JavaScript runtime errors
+
+- Read the component stack in LogBox, not only the message. `undefined is not an object (evaluating 'x.y')` and `Cannot read property 'y' of undefined` point to data that has not loaded yet or a changed API response; handle loading and error states.
+- `Rendered more hooks than during the previous render` → a hook called conditionally.
+- `Maximum update depth exceeded` → a state update inside render or an effect whose dependencies change on every render.
+- Release-only crashes: stack traces from Hermes release bundles need the source maps of that build to map back to source files; check that source maps are generated and uploaded to the crash reporter. Also check `__DEV__`-only code and environment variables missing from the release configuration.
+
+## Cleaning, with confirmation
+
+These fix stale caches, not version conflicts. Propose them with what they delete, and run them only when the user agrees: restarting Metro with `--reset-cache`, `watchman watch-del-all`, deleting `node_modules` and reinstalling, `./gradlew clean` in `android/`, removing `ios/Pods` and running `pod install`. In Expo projects with Continuous Native Generation, `npx expo prebuild --clean` regenerates `android/` and `ios/` and discards manual native changes; confirm that the project does not rely on them first.