reis-mobile 0.4.0 → 0.5.0

package/skills/mobile-code-review/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: mobile-code-review
+description: Reviews mobile code for the bugs that reach production on every stack — Flutter and Dart (pull request checklist, widget lifecycle and rebuilds, project health, static analysis), native Android (Kotlin, coroutines, Jetpack Compose, lifecycle), native iOS (Swift concurrency, SwiftUI, retain cycles) and React Native (hooks, re-renders, platform code, Expo) — with file:line evidence and a structured report. Use whenever the user asks for a code review, PR or merge request review, project audit or quality check of a mobile app, or runs /reis-mobile:review, even if they only point at a diff or a folder.
+intents: [review, performance]
+stacks: ["*"]
+---
+
+# Mobile Code Review
+
+One review process for every mobile stack. This file holds how to review and what always matters; each platform's checklist lives in its reference.
+
+## 1. Pick the checklists
+
+Detect the stack first, then apply the platform checklist to the files in scope:
+
+| Project | Read |
+|---|---|
+| Flutter / Dart | [references/flutter.md](references/flutter.md), which orders the Flutter checklists in `references/flutter/` |
+| Native Android (Kotlin/Java), or the Android side of Kotlin Multiplatform | [references/android.md](references/android.md) |
+| Native iOS (Swift/Objective-C) | [references/ios.md](references/ios.md) |
+| React Native or Expo | [references/react-native.md](references/react-native.md) |
+
+In a cross-platform app, native code in `android/`, `ios/` or native modules gets the native checklist too. Security findings follow `mobile-security` when it is loaded.
+
+## 2. Scope
+
+- **Changes (diff or pull request):** review what changed, reading the whole file when the hunk is not enough to understand it. New untracked files are not in the diff; read them.
+- **Whole project:** start at the entry points (app startup, navigation, dependency setup), then the data layer, authentication and the most complex screens.
+
+## 3. Evidence before findings
+
+- Open the code and confirm every suspicion. A finding without evidence at `file:line` does not go in the report.
+- Do not invent APIs, versions or lint rules. Check the lock files and build files (`pubspec.lock`, version catalog, `Package.resolved`, `package.json`) before claiming something is missing, deprecated or unavailable.
+- Do not report style that a configured linter already enforces.
+- When the project deliberately does something differently and it is coherent, say so instead of flagging it.
+
+## 4. What always matters, on any stack
+
+- **Lifecycle:** async work that outlives its screen; listeners, subscriptions, timers and controllers never released.
+- **Threading:** I/O or heavy parsing on the main/UI thread; UI updated off it.
+- **State:** impossible states that can be represented; loading and error handled; state lost on rotation, backgrounding or process death.
+- **Network:** timeouts, retries without backoff, offline handling, unvalidated responses.
+- **Credentials:** tokens in insecure storage, secrets in code or the bundle, sensitive data in logs.
+- **Platform:** permissions requested without handling denial; manifest, `Info.plist`, entitlements or config changes that affect store publishing.
+- **Tests:** new logic without tests when the project already has a suite.
+
+## 5. Severity
+
+Rank by real impact on users: crash or data loss, credential leak, store rejection, then noticeable degradation, then maintainability. Say why each finding matters, not only what rule it breaks.
+
+## Report
+
+Unless an agent defines its own format, answer with:
+
+```markdown
+## Summary
+Stack, scope (diff or project), verdict: approve | approve-with-changes | request-changes.
+
+## Critical
+## Bugs
+## Architecture
+## Security
+## Performance
+## Maintainability
+
+## Suggested changes
+Prioritized list. For each item: file:line, problem, why it matters, fix.
+```
+
+Write "No findings." in a section with nothing to report.

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

@@ -1,10 +1,3 @@
----
-name: android-code-review
-description: Reviews native Android code in Kotlin and Java for the bugs that reach production — lifecycle and Context leaks, coroutine scope, dispatcher and cancellation mistakes, Flow collection outside the lifecycle, Jetpack Compose state, recomposition and side effects, state lost on configuration change or process death, main-thread I/O, WorkManager and permission handling, and exported components. Use when reviewing Kotlin or Java files in an Android app or module, Activities, Fragments, ViewModels, Composables, repositories or Gradle modules, or when the user asks for an Android code review or PR review.
-intents: [review, performance]
-stacks: [android, kotlin-multiplatform]
----
-
 # Android Code Review
 
 Apply to Kotlin and Java sources under `src/main` (and `androidMain` in KMP). Items are ordered by impact: the first sections cause crashes, leaks or lost user data. Before flagging an API as missing or deprecated, check the library versions in the version catalog or build files.
@@ -41,7 +34,7 @@ Apply to Kotlin and Java sources under `src/main` (and `androidMain` in KMP). It
 
 ## 5. Platform
 
-- [ ] **Exported components.** `android:exported="true"` on activities, services, receivers or providers without a permission, that act on the incoming `Intent` without validating it. Details in `mobile-security-audit`.
+- [ ] **Exported components.** `android:exported="true"` on activities, services, receivers or providers without a permission, that act on the incoming `Intent` without validating it. Details in `mobile-security`.
 - [ ] **Runtime permissions.** Features used without checking the permission, or denial ("don't ask again") not handled.
 - [ ] **Background work.** Long work started from an Activity or a plain `Service` that the system will stop; persistent or deferrable work belongs in `WorkManager`. Starting foreground services and exact alarms have restrictions that depend on `targetSdk`; check it before reviewing.
 - [ ] **`PendingIntent` mutability.** Flags must include `FLAG_IMMUTABLE` or `FLAG_MUTABLE` explicitly on apps targeting Android 12 or higher.

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

@@ -1,11 +1,4 @@
----
-name: flutter-code-review
-description: Performs thorough code reviews for Flutter/Dart pull requests and merge requests. Use when asked to review a PR, MR, branch, or a set of changed files. Follows a structured checklist covering correctness, security, style, testing, and documentation.
-intents: [review]
-stacks: [flutter]
-source: https://github.com/evanca/flutter-ai-rules
-license: MIT
----
+> Adapted from the `code-review` skill in [evanca/flutter-ai-rules](https://github.com/evanca/flutter-ai-rules) (MIT). See `THIRD_PARTY_NOTICES.md`.
 
 # Code Review Skill
 

package/skills/{flutter-project-audit/SKILL.md → mobile-code-review/references/flutter/project-audit.md}

@@ -1,10 +1,3 @@
----
-name: flutter-project-audit
-description: Audits the health of a Flutter project as a whole — pubspec constraints and lock file, analysis_options and lints, SDK and platform configuration (minSdk, iOS deployment target), flavors and environments, generated code, folder structure and test setup. Use when reviewing or auditing a Flutter app or plugin, before a release, or when the user asks whether a Flutter project is well configured.
-intents: [review, architecture, dependency]
-stacks: [flutter]
----
-
 # Flutter Project Audit
 
 Project health checklist. Every item must be confirmed by reading the cited file; do not report what you could not verify.

package/skills/{flutter-dart-run-static-analysis/SKILL.md → mobile-code-review/references/flutter/static-analysis.md}

@@ -1,14 +1,5 @@
----
-name: flutter-dart-run-static-analysis
-description: Execute `dart analyze` to identify warnings and errors, and use `dart fix --apply` to automatically resolve mechanical lint issues. Use during development to ensure code quality and before committing changes.
-metadata:
-  model: models/gemini-3.1-pro-preview
-  last_modified: Fri, 24 Apr 2026 15:09:34 GMT
-intents: [review]
-stacks: [flutter]
-source: https://github.com/dart-lang/skills
-license: BSD-3-Clause
----
+> Adapted from the `dart-run-static-analysis` skill in [dart-lang/skills](https://github.com/dart-lang/skills) (BSD-3-Clause). See `THIRD_PARTY_NOTICES.md`.
+
 # Analyzing and Fixing Dart Code
 
 ## Contents

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

@@ -1,10 +1,3 @@
----
-name: flutter-widget-review
-description: Reviews Flutter widget code for lifecycle bugs, BuildContext misuse across async gaps, missing dispose, side effects in build, unnecessary rebuilds, list and image performance, layout overflow risks and accessibility. Use when reviewing Dart files under lib/ that contain widgets, screens or pages, or when the user asks to review Flutter UI code.
-intents: [review, performance]
-stacks: [flutter]
----
-
 # Flutter Widget Review
 
 Apply to Dart files with widgets (`StatelessWidget`, `StatefulWidget`, `ConsumerWidget`, `HookWidget`...). Items are ordered by impact: the first ones cause crashes or visible bugs.

package/skills/mobile-code-review/references/flutter.md

@@ -0,0 +1,18 @@
+# Reviewing Flutter and Dart code
+
+Apply the checklists in this order; stop early for a small diff that only touches widgets.
+
+| Step | Checklist | When |
+|---|---|---|
+| 1 | [flutter/static-analysis.md](flutter/static-analysis.md) — `dart analyze`, `dart fix` | Always, when the Dart SDK is available; report the analyzer output before manual findings |
+| 2 | [flutter/pr-review.md](flutter/pr-review.md) — pull request checklist: correctness, security, style, tests, docs | Reviewing a diff, branch or pull request |
+| 3 | [flutter/widget-review.md](flutter/widget-review.md) — lifecycle, `BuildContext` across async gaps, dispose, rebuilds, lists, layout, accessibility | Files with widgets, screens or pages; performance reviews |
+| 4 | [flutter/project-audit.md](flutter/project-audit.md) — `pubspec.yaml`, lints, native configuration, flavors, structure, CI | Auditing a whole project, or a diff that touches `pubspec.yaml`, `android/`, `ios/` or CI |
+
+## Flutter-specific notes
+
+- Dart style and idioms: the Effective Dart and Dart 3 guides in the `mobile-flutter` skill (`references/dart.md`).
+- Follow the project's state management (BLoC/Cubit, Riverpod, Provider) instead of suggesting another one.
+- Check the Flutter and Dart versions in `pubspec.lock` before recommending newer APIs (`MediaQuery.sizeOf`, Dart 3 patterns).
+- Generated files (`*.g.dart`, `*.freezed.dart`, `*.mocks.dart`) are reviewed through their source annotations, not line by line.
+- Native code under `android/` and `ios/` follows [android.md](android.md) and [ios.md](ios.md).

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,50 @@
+---
+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.
+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) |
+
+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/{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.md

@@ -0,0 +1,26 @@
+# 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.

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.

package/skills/mobile-flutter/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: mobile-flutter
+description: Builds Flutter apps with guides for everything specific to Flutter and Dart — layouts, responsive UI, forms, animations, theming, declarative routing with go_router, widget previews and home screen widgets; HTTP, JSON serialization, local databases and caching; plugins, platform channels and native views; isolates and app size; accessibility and localization; Effective Dart, Dart 3 features and pattern matching; and macOS setup. Use when writing or changing Flutter UI, data or native integration code, or when the user asks how to do something in Flutter, even if they do not name the topic.
+intents: [review, performance, accessibility, migration]
+stacks: [flutter]
+---
+
+# Mobile Flutter
+
+Guides for building Flutter apps. Cross-platform topics live in their own skills and have Flutter references there: architecture and state management in `mobile-architecture`, tests in `mobile-test`, debugging in `mobile-debug`, code review in `mobile-code-review`, security in `mobile-security` and Firebase in `mobile-firebase`.
+
+## Pick the topic
+
+| Topic | Read |
+|---|---|
+| UI, layout and navigation | [references/ui.md](references/ui.md) |
+| Data and networking | [references/data.md](references/data.md) |
+| Native code and plugins | [references/native.md](references/native.md) |
+| Performance and size | [references/performance.md](references/performance.md) |
+| Accessibility and internationalization | [references/accessibility-i18n.md](references/accessibility-i18n.md) |
+| Dart language | [references/dart.md](references/dart.md) |
+| Environment | [references/setup.md](references/setup.md) |
+
+Each topic file lists its guides; open only the ones the task needs.
+
+## Before writing code
+
+- Follow the project: its state management, folder structure, lints and packages already in `pubspec.yaml`.
+- Check the Flutter and Dart versions in `pubspec.lock` before using newer APIs; guides may describe features that a pinned SDK does not have.
+- Prefer packages the project already depends on over adding new ones; when adding one, check that it supports every platform the app targets.