reis-mobile 0.4.0 → 0.6.0

package/skills/mobile-ios/references/performance-release.md

@@ -0,0 +1,37 @@
+# iOS performance and release
+
+## Measure before optimizing
+
+- **Instruments:** Time Profiler for CPU, Allocations and Leaks for memory, Hangs for main-thread blocks, the SwiftUI template for view updates. Profile a Release build on a device, not the simulator.
+- **In the field:** Xcode Organizer (launch time, hangs, memory, energy, disk writes) and MetricKit (`MXMetricManager`) for diagnostics from users' devices.
+
+## Common fixes
+
+- **Launch:** defer SDK initialization and data loading that the first screen does not need; avoid synchronous work in the `App` initializer or `application(_:didFinishLaunchingWithOptions:)`.
+- **Hangs:** move disk, network, JSON decoding and image decoding off the main actor.
+- **Scrolling:** stable identity in lists, no heavy work in `body` or `cellForItemAt`, downsampled images.
+- **Memory:** break retain cycles (`[weak self]`, weak delegates), bound in-memory caches and clear them on memory warnings.
+- **Size:** check the App Thinning size report from an archive export; keep images in asset catalogs, remove unused resources and dependencies.
+
+## Versioning and signing
+
+- `CFBundleShortVersionString` (Marketing Version) is the user-facing version; `CFBundleVersion` (build number) must increase for every upload of the same version.
+- Automatic signing is simplest for teams; CI usually uses manual signing or an App Store Connect API key with `xcodebuild -allowProvisioningUpdates`. Keep certificates and keys in the CI secret store, never in the repository.
+- Each extension (widgets, notification services) needs its own bundle identifier, prefixed by the app's, and a matching profile.
+
+## Build and upload
+
+```bash
+xcodebuild -scheme App -configuration Release -archivePath build/App.xcarchive archive
+xcodebuild -exportArchive -archivePath build/App.xcarchive -exportOptionsPlist ExportOptions.plist -exportPath build/export
+```
+
+- Upload with Xcode Organizer, Transporter, fastlane, or a tool based on the App Store Connect API; check which command-line upload method Apple currently supports before scripting it.
+- Keep dSYMs for crash symbolication (upload them to the crash reporter).
+
+## TestFlight and App Store
+
+- Internal testers (members of the App Store Connect team) get builds without review; external testers need a Beta App Review for the first build of a version.
+- Before submitting: screenshots and metadata, privacy details (the App Privacy section must match the privacy manifest and SDKs), export compliance (`ITSAppUsesNonExemptEncryption` in `Info.plist` avoids the question on each upload), sign-in credentials for the reviewer when the app requires an account, and account deletion in the app if it allows creating accounts.
+- Check the current App Store Review Guidelines and the minimum Xcode/SDK required for uploads; both change regularly.
+- Use phased release for updates to limit the impact of a bad build.

package/skills/mobile-ios/references/platform-features.md

@@ -0,0 +1,52 @@
+# iOS platform features
+
+## Permissions
+
+- Every protected API needs its usage description in `Info.plist` (`NSCameraUsageDescription`, `NSLocationWhenInUseUsageDescription`, `NSPhotoLibraryUsageDescription`...) with text that explains the benefit; a missing key crashes the app when the API is used.
+- Ask in context, when the user starts the feature, and handle denied and restricted states with a path to Settings (`UIApplication.openSettingsURLString`).
+- Photo picking with `PhotosPicker` (SwiftUI) or `PHPickerViewController` needs no library permission.
+
+## Push notifications
+
+- Enable the Push Notifications capability; request authorization with `UNUserNotificationCenter.current().requestAuthorization(options:)`; register with `UIApplication.shared.registerForRemoteNotifications()`.
+- Implement `UNUserNotificationCenterDelegate` to show notifications in the foreground and handle taps.
+- Rich media needs a Notification Service Extension; silent pushes need the Background Modes → Remote notifications capability and are throttled by the system.
+- With Firebase Cloud Messaging, follow `mobile-firebase`.
+
+## Universal links and URL schemes
+
+- Universal links: add the Associated Domains capability (`applinks:example.com`) and host `apple-app-site-association` on the domain over HTTPS.
+- Handle incoming URLs with `.onOpenURL` (SwiftUI) or the scene delegate, route through the navigation model, and validate parameters before acting.
+- Custom URL schemes can be claimed by other apps; do not use them for authentication callbacks or privileged actions.
+
+## Background work
+
+- `BGTaskScheduler` with `BGAppRefreshTask` for short refreshes and `BGProcessingTask` for longer maintenance; register identifiers in `Info.plist` (`BGTaskSchedulerPermittedIdentifiers`) and schedule again after each run. The system decides when tasks run.
+- Finishing a short task after the app goes to background: `beginBackgroundTask(withName:)` with the matching `endBackgroundTask`.
+
+## Widgets, Live Activities and App Intents
+
+- Widgets use WidgetKit in an extension target with a `TimelineProvider`; share data with the app through an App Group container, and reload timelines from the app when data changes.
+- Live Activities use ActivityKit and need `NSSupportsLiveActivities` in the app's `Info.plist`.
+- App Intents expose actions to Shortcuts, Siri, Spotlight, widgets and controls; define `AppIntent` types and `AppShortcutsProvider` for discoverable shortcuts.
+
+## In-app purchases with StoreKit 2
+
+```swift
+let products = try await Product.products(for: ["com.example.pro.monthly"])
+let result = try await products[0].purchase()
+if case .success(let verification) = result, case .verified(let transaction) = verification {
+    // unlock content, then:
+    await transaction.finish()
+}
+```
+
+- Start listening to `Transaction.updates` at launch to catch renewals, refunds and purchases made on other devices.
+- Only unlock content for `.verified` transactions; validate entitlements on your server for anything valuable.
+- Test with a StoreKit configuration file in Xcode, then in the sandbox and TestFlight.
+- Check the App Store Review Guidelines on digital goods before choosing a payment method.
+
+## Privacy
+
+- Keep the app's privacy manifest (`PrivacyInfo.xcprivacy`) accurate: data collected, tracking domains and required-reason APIs. Third-party SDKs must ship their own.
+- Request App Tracking Transparency (`ATTrackingManager`) before tracking across apps, with `NSUserTrackingUsageDescription`.

package/skills/mobile-ios/references/ui-navigation.md

@@ -0,0 +1,64 @@
+# iOS UI and navigation
+
+## SwiftUI state
+
+| Wrapper | Use for |
+|---|---|
+| `@State` | Value state owned by the view; also owns an `@Observable` model the view creates |
+| `@Binding` | Two-way access to state owned by a parent |
+| `@Observable` class (iOS 17+) | A model; views update only for properties they read |
+| `@Bindable` | Bindings to properties of an `@Observable` model the view does not own |
+| `ObservableObject` + `@StateObject` / `@ObservedObject` | Models before iOS 17: `@StateObject` where created, `@ObservedObject` where passed in |
+| `@Environment` | Values and models injected from an ancestor |
+| `@FocusState` | Keyboard focus in forms |
+
+A view must not recreate a model it does not own on every update; that resets state.
+
+## Navigation
+
+```swift
+enum Route: Hashable { case order(Order.ID), settings }
+
+struct RootView: View {
+    @State private var path: [Route] = []
+
+    var body: some View {
+        NavigationStack(path: $path) {
+            OrdersList(onSelect: { path.append(.order($0)) })
+                .navigationDestination(for: Route.self) { route in
+                    switch route {
+                    case .order(let id): OrderDetail(id: id)
+                    case .settings: SettingsView()
+                    }
+                }
+        }
+    }
+}
+```
+
+- `NavigationStack` with a path (iOS 16+) makes deep links and state restoration possible; `NavigationView` is deprecated.
+- Pass identifiers in routes, not whole models.
+- Sheets and full-screen covers are driven by optional state (`.sheet(item:)`), not booleans plus separate data.
+
+## Lists and forms
+
+- `List` and `LazyVStack` need stable identity: `Identifiable` models, not indices, for data that changes.
+- Heavy work does not belong in `body`: format, sort and filter in the model.
+- Forms: `Form`, `TextField` with `.textContentType` and `.keyboardType`, `@FocusState` to move between fields and dismiss the keyboard, validation in the model.
+
+## UIKit interop
+
+- Use a UIKit view in SwiftUI with `UIViewRepresentable` / `UIViewControllerRepresentable`, coordinating delegates through a `Coordinator`.
+- Embed SwiftUI in UIKit with `UIHostingController`.
+- In UIKit, prefer diffable data sources and compositional layouts for collections.
+
+## Accessibility and localization
+
+- Support Dynamic Type: system text styles (`.font(.body)`), no fixed heights around text.
+- Label icon-only controls (`.accessibilityLabel`), group related elements, and keep touch targets at least 44×44 points.
+- Test with VoiceOver and the largest accessibility text sizes.
+- Localize user-facing strings with String Catalogs (`.xcstrings`) or `String(localized:)`; SwiftUI `Text("key")` literals are localizable automatically.
+
+## Previews
+
+`#Preview { OrdersList(orders: .fixtures) }` with fixture data and injected fake services, so previews never hit the network.

package/skills/mobile-release/SKILL.md

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

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

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

package/skills/mobile-release/references/ci-cd.md

@@ -0,0 +1,94 @@
+# CI/CD for mobile apps
+
+## Pipeline shape
+
+| Trigger | Jobs |
+|---|---|
+| Pull request | Static analysis or lint, unit tests, a debug or release build per platform that compiles (no signing, no upload) |
+| Merge to the main branch | The above, plus a signed build uploaded to internal testing (Play internal track, TestFlight internal) |
+| Release tag (`v1.4.0`) | Signed release builds, symbol upload, upload to the release track, artifacts attached to the release |
+
+Keep Android and iOS in separate jobs: Android runs on Linux runners, iOS needs macOS runners, which cost more and are slower — do not run iOS builds on every push if the team does not need them.
+
+## Principles
+
+- **Reproducible toolchain.** Pin the Flutter version, Node version, JDK, Xcode version (`sudo xcode-select -s /Applications/Xcode_<version>.app` or the runner image's documented selector) and Ruby/fastlane through `Gemfile.lock`. CI that builds with a different toolchain than developers is how "works on my machine" reaches the store.
+- **Caching.** Gradle (`~/.gradle/caches`, or `gradle/actions/setup-gradle`), pub cache, `node_modules` keyed by the lock file, CocoaPods `Pods/` keyed by `Podfile.lock`. Never cache build outputs across different commits for release builds.
+- **Secrets.** Keystore as a base64 CI secret decoded to a temporary file; keystore passwords, the Play service account JSON, the App Store Connect API key (`.p8`, key ID, issuer ID) and `match` passwords as secrets. Nothing written to logs; files deleted at the end of the job. Release jobs run only on protected branches or tags, so a pull request from a fork cannot read them.
+- **Build numbers from CI.** Derive the build number from the run number or the store's latest build (fastlane `latest_testflight_build_number`, `google_play_track_version_codes`) instead of committing a bump on every build.
+- **Artifacts.** Keep the `.aab`/`.ipa`, the R8 mapping, dSYMs, Dart symbols and source maps for every release build.
+- **One way to ship.** Once CI publishes, nobody uploads from a laptop: a manual upload skips the checks and breaks the build number sequence.
+
+## GitHub Actions sketch (Flutter, Android)
+
+Adapt names and versions to the project; check each action's current major version in its repository.
+
+```yaml
+name: android-release
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  android:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '17'
+      - uses: subosito/flutter-action@v2
+        with:
+          flutter-version-file: pubspec.yaml   # or a pinned flutter-version
+          cache: true
+      - run: flutter pub get
+      - run: flutter analyze
+      - run: flutter test
+      - name: Decode keystore
+        run: |
+          echo "$ANDROID_KEYSTORE_BASE64" | base64 -d > android/app/upload.jks
+          cat > android/key.properties <<EOF
+          storeFile=upload.jks
+          storePassword=$ANDROID_KEYSTORE_PASSWORD
+          keyAlias=$ANDROID_KEY_ALIAS
+          keyPassword=$ANDROID_KEY_PASSWORD
+          EOF
+        env:
+          ANDROID_KEYSTORE_BASE64: ${{ secrets.ANDROID_KEYSTORE_BASE64 }}
+          ANDROID_KEYSTORE_PASSWORD: ${{ secrets.ANDROID_KEYSTORE_PASSWORD }}
+          ANDROID_KEY_ALIAS: ${{ secrets.ANDROID_KEY_ALIAS }}
+          ANDROID_KEY_PASSWORD: ${{ secrets.ANDROID_KEY_PASSWORD }}
+      - run: flutter build appbundle --release --build-number=${{ github.run_number }} --obfuscate --split-debug-info=build/symbols
+      - uses: actions/upload-artifact@v4
+        with:
+          name: android-release
+          path: |
+            build/app/outputs/bundle/release/app-release.aab
+            build/app/outputs/mapping/release/mapping.txt
+            build/symbols
+```
+
+`flutter-version-file` reads the version from the `environment.flutter` constraint only when it is an exact version; otherwise pin `flutter-version`. Upload to Play in a following step with fastlane `supply` or an upload action, using the service account secret.
+
+## fastlane
+
+- `Fastfile` lanes per platform: `beta` (build, upload to internal testing or TestFlight) and `release` (upload to production or submit for review).
+- iOS signing: `match` (certificates and profiles in an encrypted store) with `readonly: true` in CI; `app_store_connect_api_key` for authentication instead of an Apple ID with two-factor authentication.
+- Android upload: `upload_to_play_store(track: 'internal', aab: ...)` with `json_key_data` from a secret.
+- Run with `bundle exec fastlane <lane>` so CI uses the fastlane version in `Gemfile.lock`.
+
+## Other services
+
+- **EAS (Expo):** `eas build` and `eas submit` run on Expo's builders; trigger them from CI with `EXPO_TOKEN`, or use EAS Workflows. `eas update` in CI publishes over-the-air updates — gate it like a release.
+- **Codemagic, Bitrise, Xcode Cloud, Azure DevOps, GitLab CI:** the same pipeline shape applies; prefer the service's managed code signing when the team already uses it, and keep secrets in the service's encrypted variables.
+
+## Reviewing an existing pipeline
+
+- [ ] Toolchain versions pinned and matching local development.
+- [ ] Secrets never printed (`set -x`, `cat` of decoded files, verbose tool flags) and not available to untrusted pull requests.
+- [ ] Release jobs restricted to tags or protected branches.
+- [ ] Tests run before the signed build, and a failure stops the upload.
+- [ ] Symbols and mapping files uploaded or archived for every release build.
+- [ ] Build numbers cannot collide between parallel runs or re-runs.
+- [ ] Third-party actions pinned to a version (or a commit SHA for sensitive jobs).

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

@@ -0,0 +1,37 @@
+# Releasing a Flutter app
+
+A Flutter release is an Android release and an iOS release produced by the Flutter tool. Store details, signing and rollout follow [android.md](android.md) and [ios.md](ios.md); this guide covers what Flutter changes.
+
+## Version
+
+- `pubspec.yaml` holds both numbers: `version: 1.4.0+42` → version name `1.4.0`, build number `42`.
+- On Android it becomes `versionName`/`versionCode` through `flutter.versionName` and `flutter.versionCode` in `android/app/build.gradle(.kts)`. On iOS it becomes `FLUTTER_BUILD_NAME`/`FLUTTER_BUILD_NUMBER`, which `Info.plist` must reference (`$(FLUTTER_BUILD_NAME)`, `$(FLUTTER_BUILD_NUMBER)`). Check both files: a hard-coded value there silently ignores `pubspec.yaml`.
+- CI can override without editing the file: `--build-name=1.4.0 --build-number=$GITHUB_RUN_NUMBER`.
+
+## Build
+
+```bash
+flutter build appbundle --release --obfuscate --split-debug-info=build/symbols
+flutter build ipa --release --obfuscate --split-debug-info=build/symbols \
+  --export-options-plist=ios/ExportOptions.plist
+```
+
+- `--obfuscate` requires `--split-debug-info`. The symbol files in that folder are per build and per architecture: archive them with the build or stack traces from that release cannot be read.
+- Symbolize a stack trace with `flutter symbolize -i trace.txt -d build/symbols/app.android-arm64.symbols`. Crashlytics needs the symbols uploaded (`firebase crashlytics:symbols:upload --app=<firebase-app-id> build/symbols`).
+- Obfuscation renames Dart types: code that relies on `runtimeType.toString()` or type names in logs and analytics changes behavior in release.
+- Pass environment configuration with `--dart-define` or `--dart-define-from-file`, and check which file the release command uses. Anything passed this way is in the binary: no secrets.
+- Android signing: `android/key.properties` (untracked) read by the `signingConfigs.release` block. A release build that falls back to `signingConfig = signingConfigs.debug` — the default in new projects — is rejected by Play and must be caught before upload.
+
+## Before uploading
+
+- [ ] `flutter analyze` and `flutter test` pass on the release commit.
+- [ ] The app runs in `--release` (or `--profile`) on a real device: assertions, `kDebugMode` branches and the debug banner behave differently in debug.
+- [ ] `debugPrint` and logging do not print sensitive data in release.
+- [ ] Plugins that need platform setup for release are configured: Android permissions and R8 keep rules some plugins document, iOS usage descriptions, `Podfile` platform version.
+- [ ] `flutter build ipa` warnings about the app icon, launch image or bundle identifier are resolved.
+- [ ] App size checked (`--analyze-size`) when the release adds assets or packages.
+
+## Automation
+
+- fastlane lanes in `android/` and `ios/` run after `flutter build`, or call it themselves.
+- Codemagic and GitHub Actions with `subosito/flutter-action` are common CI setups; pin the Flutter version to the one the team uses locally (`.fvmrc` or a documented version) so CI builds what was tested. See [ci-cd.md](ci-cd.md).

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

@@ -0,0 +1,48 @@
+# Releasing on iOS
+
+App Store Connect, TestFlight and signing basics also appear in `mobile-ios` → `references/performance-release.md`; this guide focuses on getting a version out safely.
+
+## Version
+
+- **Version** (`CFBundleShortVersionString`, build setting `MARKETING_VERSION`) is what users see.
+- **Build** (`CFBundleVersion`, build setting `CURRENT_PROJECT_VERSION`) identifies the upload. App Store Connect rejects a build number already used for the same version; incrementing it for every upload avoids the problem entirely.
+- Keep both in build settings, not hard-coded in `Info.plist`, so every target (app, extensions, widgets) shares them. Extensions whose version differs from the app produce an upload warning or error.
+- `agvtool new-version -all <n>` and `agvtool new-marketing-version <x.y.z>` update them when the project uses Apple Generic versioning; fastlane's `increment_build_number` wraps it.
+
+## Archive, export and upload
+
+```bash
+xcodebuild -workspace App.xcworkspace -scheme App -configuration Release \
+  -archivePath build/App.xcarchive archive
+xcodebuild -exportArchive -archivePath build/App.xcarchive \
+  -exportOptionsPlist ExportOptions.plist -exportPath build/export
+```
+
+- Use `-project App.xcodeproj` when there is no workspace (no CocoaPods).
+- `ExportOptions.plist` sets the method (App Store Connect distribution), team and signing style.
+- Upload with Xcode's Organizer, the Transporter app, or fastlane (`upload_to_testflight`, `upload_to_app_store`) using an App Store Connect API key.
+- Automatic signing in CI needs the API key or an account with access; manual signing needs the distribution certificate and provisioning profile installed. fastlane `match` keeps them in an encrypted repository or bucket.
+
+## Symbols
+
+- Release builds need **Debug Information Format = DWARF with dSYM File**.
+- The dSYMs are inside the archive (`App.xcarchive/dSYMs`). Upload them to the crash reporter (Crashlytics `upload-symbols`, Sentry, others) and keep the archive: Xcode Organizer symbolicates its own crash reports only when it has the matching dSYM.
+
+## Before uploading
+
+- [ ] The build uses the current minimum Xcode and iOS SDK Apple requires for uploads (confirm on Apple's upcoming requirements page).
+- [ ] Every permission the app requests has its `NS...UsageDescription` string, written for the user.
+- [ ] `PrivacyInfo.xcprivacy` declares required-reason APIs and collected data, and third-party SDKs ship their own manifests and signatures.
+- [ ] `ITSAppUsesNonExemptEncryption` set in `Info.plist` when the app uses only exempt encryption (HTTPS), so each build does not ask for export compliance.
+- [ ] Capabilities and entitlements (push, associated domains, App Groups, Sign in with Apple) enabled for the App ID and present in the distribution profile. Push needs `aps-environment` = `production` in distribution builds, which the profile sets.
+- [ ] No `NSAllowsArbitraryLoads` without a justification Apple will accept.
+- [ ] App Privacy details in App Store Connect match the data the app and its SDKs collect.
+- [ ] Review notes and a demo account when features need login; release notes ready — see [store-copy.md](store-copy.md).
+
+## TestFlight and rollout
+
+- **Internal testers** (members of the App Store Connect team) get builds after processing, without review. **External testers** need the first build of a version to pass Beta App Review.
+- TestFlight builds expire after 90 days.
+- For updates, **phased release** distributes the version over seven days to users with automatic updates on; it can be paused (for a limited total time) or released to everyone. Anyone can still update manually from the App Store during the phase.
+- Choose manual or scheduled release after approval when the launch must match a backend change or an announcement.
+- A bad version cannot be withdrawn to the previous binary: remove it from sale only in extreme cases, and ship a fix with a new build (expedited review can be requested for critical bugs).

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

@@ -0,0 +1,36 @@
+# Releasing a React Native app
+
+A React Native release is an Android and an iOS release plus a JavaScript bundle. Store details, signing and rollout follow [android.md](android.md) and [ios.md](ios.md); EAS Build and Submit commands are also in `mobile-rn` → `references/performance-release.md`.
+
+## Version
+
+- **Bare React Native:** `versionCode`/`versionName` in `android/app/build.gradle`, and `MARKETING_VERSION`/`CURRENT_PROJECT_VERSION` in the Xcode project. `package.json`'s `version` is not used by either store unless a script copies it.
+- **Expo:** `expo.version` in `app.json`/`app.config.(js|ts)` is the version name; `android.versionCode` and `ios.buildNumber` are the build numbers. With EAS, `"cli": { "appVersionSource": "remote" }` in `eas.json` lets EAS keep the build numbers, and `"autoIncrement": true` on the production profile increments them on each build.
+
+## Build
+
+- **Expo / EAS:** `eas build --platform all --profile production`, then `eas submit`. Credentials (keystore, certificates, provisioning) are managed by EAS unless the project configured local credentials.
+- **Bare:** `./gradlew bundleRelease` in `android/`, and an Xcode archive for iOS.
+- Environment: values in `EXPO_PUBLIC_*`, `react-native-config` and similar end up in the JavaScript bundle. Confirm the release build points at production and holds no secrets.
+
+## Symbols and source maps
+
+- JavaScript stack traces from release builds need the **source map** of that exact bundle. With Hermes, the map must be the composed one (Metro map combined with the Hermes bytecode map); crash reporters' React Native integrations (Sentry, Bugsnag, Crashlytics tooling) document how to generate and upload it.
+- The native side still needs the R8 mapping and dSYMs, as in the Android and iOS guides.
+
+## Over-the-air updates
+
+- EAS Update (or another OTA service) changes JavaScript and assets without a store review. It cannot change native code, permissions or native dependencies: those need a store build.
+- The **runtime version** decides which binaries can receive an update. A policy such as `fingerprint` or `appVersion` prevents shipping JavaScript that calls native code the installed binary does not have; a manual runtime version that nobody bumps is the classic cause of crashes after an update.
+- Publish to a **channel** mapped to the production build (`eas update --channel production`), test it first on a preview channel with a build from the same commit, and know how to roll back (republish a previous update or roll back to the embedded bundle — check `eas update --help` for the commands in the installed CLI version).
+- Store rules still apply: an OTA update must not change the app's purpose or add features that would need review.
+
+## Before uploading
+
+- [ ] `tsc --noEmit`, lint and tests pass on the release commit.
+- [ ] Release build tested on real devices: Hermes, minification and the absence of the dev menu change behavior.
+- [ ] `console.log` removed from release bundles (a Babel plugin such as `transform-remove-console`) when logs can contain user data.
+- [ ] Config plugins and `expo prebuild` output match the committed native folders, when the project commits them.
+- [ ] `expo-doctor` (Expo) or the React Native upgrade helper's checklist shows no version mismatches for native dependencies.
+
+See [ci-cd.md](ci-cd.md) for pipelines.

package/skills/mobile-release/references/store-copy.md

@@ -0,0 +1,52 @@
+# Release notes and store listing copy
+
+## Limits
+
+Check the console when a field is rejected; these are the long-standing limits.
+
+| Field | Google Play | App Store |
+|---|---|---|
+| App name | 30 characters | 30 characters |
+| Short text | Short description: 80 | Subtitle: 30 |
+| Editable without a new version | — | Promotional text: 170 |
+| Description | 4,000 | 4,000 |
+| Keywords | — (indexed from the listing text) | 100 bytes, comma-separated |
+| Release notes | 500 per language | What's New: 4,000 |
+
+The App Store description, keywords and What's New change only with a new version; promotional text changes at any time. Google Play listing text changes independently of releases.
+
+## Release notes from the git history
+
+1. **Collect the range.** `git log <last-release-tag>..HEAD --no-merges --pretty='%h %s'`. In a monorepo, limit it to the app folder (`-- apps/mobile`). When commits reference issues or pull requests, read their titles for context.
+2. **Drop the noise.** Merges, version bumps, CI and tooling changes, formatting, typo fixes in code, dependency bumps without user impact, and reverted pairs.
+3. **Classify what is left.** New or changed features, fixes the user could notice, performance improvements the user could feel, and internal changes (refactors, infrastructure, removed APIs).
+4. **Write per audience:**
+   - **Store notes (users):** only what users can see or feel, in plain language and benefit first. No ticket numbers, class names, library names or "various bug fixes" as the only line. Within the limit, in every listed language — flag missing translations instead of inventing them.
+   - **Changelog (developers):** technical and complete, with commit hashes or issue references, grouped by type.
+   - **QA notes (internal):** the risky areas — new features, refactored core flows, data migrations, removed code, SDK upgrades — each with what to test and on which OS versions or devices.
+5. **Do not invent.** A change is described only when a commit or issue supports it. When a commit message is unclear, read the diff (`git show <hash> --stat`, then the relevant hunk) or list it as "needs description" for the team.
+
+Template:
+
+```markdown
+## Store — <version>
+<3–6 short lines, most valuable first>
+
+## Changelog — <version> (<date>)
+### Added
+### Changed
+### Fixed
+### Performance
+### Internal
+
+## QA focus — <version>
+- <area>: <what changed> → <what to test, where>
+```
+
+## Store listing
+
+- **First 80–170 characters matter most:** the short description (Play) and subtitle or promotional text (App Store) are what users read before tapping. Lead with what the app does for the user, not the company.
+- **Description structure:** one-sentence value proposition, three to six feature bullets written as benefits, then details (plans, requirements, support contact). No claims the app does not deliver and no competitor names.
+- **Keywords (App Store):** no repeated words already in the app name or subtitle, no spaces after commas, no competitor or trademarked names.
+- **Policy traps:** Google Play rejects keyword stuffing, misleading claims ("#1", "best") without attribution, and emojis or capitals used to attract attention in the title; Apple rejects references to other platforms and pricing claims that do not match the in-app purchases.
+- **Localization:** translate the listing for each market the app is sold in, and keep screenshots consistent with the localized UI.

package/skills/mobile-rn/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: mobile-rn
+description: Builds React Native and Expo apps in TypeScript — navigation with React Navigation or Expo Router, lists, forms, styling, gestures and animations with Reanimated, safe areas, accessibility and localization; networking with TanStack Query, response validation, persistence with MMKV, AsyncStorage, SQLite and secure storage; permissions, push notifications, deep links, background tasks, native modules and config plugins; performance with Hermes and the React profiler; and release with EAS Build, EAS Submit and EAS Update or bare Gradle and Xcode builds. Use when writing or changing React Native code, adding a native capability, configuring Expo, preparing a store build or an over-the-air update, or when the user asks how to do something in React Native, even if they do not name the library.
+intents: [performance, release, accessibility]
+stacks: [react-native]
+---
+
+# Mobile React Native
+
+Guides for building React Native and Expo apps. Cross-platform topics live in their own skills and have React Native references there: architecture and state in `mobile-architecture`, tests in `mobile-test`, debugging (Metro, native modules, builds) in `mobile-debug`, code review in `mobile-code-review`, security in `mobile-security` and Firebase in `mobile-firebase`.
+
+## Pick the topic
+
+| Topic | Read |
+|---|---|
+| Navigation, lists, forms, styling, gestures, animations, accessibility, localization | [references/ui-navigation.md](references/ui-navigation.md) |
+| Networking, server state, validation, persistence, offline | [references/data-networking.md](references/data-networking.md) |
+| Permissions, push, deep links, background work, native modules, config plugins | [references/platform-features.md](references/platform-features.md) |
+| Performance, bundle, EAS Build, store submission and over-the-air updates | [references/performance-release.md](references/performance-release.md) |
+
+## Before writing code
+
+- Detect the setup: Expo (managed with Continuous Native Generation, or with committed `android/` and `ios/`) or bare React Native; the React Native and Expo SDK versions; whether the New Architecture is enabled.
+- Install libraries with `npx expo install` in Expo projects, so versions match the SDK.
+- Libraries with native code need a new native build (a development build in Expo); they do not work in Expo Go unless the Expo SDK includes them.
+- Native requirements of each platform still apply; see `mobile-ios` and `mobile-android` for store and platform specifics.

package/skills/mobile-rn/references/data-networking.md

@@ -0,0 +1,59 @@
+# React Native data and networking
+
+## Server state with TanStack Query
+
+```tsx
+const queryClient = new QueryClient({ defaultOptions: { queries: { staleTime: 30_000, retry: 2 } } });
+
+export function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <RootNavigator />
+    </QueryClientProvider>
+  );
+}
+
+export const useOrder = (orderId: string) =>
+  useQuery({ queryKey: ['orders', orderId], queryFn: () => api.orders.get(orderId) });
+
+export function useCancelOrder() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: api.orders.cancel,
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['orders'] }),
+  });
+}
+```
+
+The names are illustrative. Use RTK Query instead if the project is built on Redux Toolkit.
+
+- React Native has no window focus or online events: wire `focusManager` to `AppState` and `onlineManager` to NetInfo so queries refetch when the app returns to the foreground or reconnects.
+- Keys include every variable the request depends on.
+
+## HTTP client
+
+- One typed client on `fetch` (or axios, if the project uses it) with a base URL, auth header injection, token refresh and timeouts. `fetch` has no timeout: use an `AbortController` with a timer.
+- `fetch` does not reject on 4xx/5xx; check `response.ok`.
+- Validate or map responses at the boundary (for example with zod) instead of `as` casts in screens.
+- Base URLs and public config come from app config or EAS environment variables; secrets stay on the backend.
+
+## Persistence
+
+| Data | Store |
+|---|---|
+| Tokens, credentials | `expo-secure-store` or `react-native-keychain` (Keychain/Keystore) |
+| Preferences, small key-value data | MMKV (`react-native-mmkv`) or AsyncStorage |
+| Relational or large data | SQLite (`expo-sqlite` or the library the project uses), optionally with an ORM such as Drizzle |
+| Files and media | `expo-file-system` or the file library the project uses |
+| Query cache across launches | TanStack Query persisters, for data that is safe to show stale |
+
+AsyncStorage is unencrypted and asynchronous; do not store secrets there, and avoid large values.
+
+## Offline
+
+- Detect connectivity with `@react-native-community/netinfo` to show offline state, but still handle request failures.
+- For offline-first flows, read from local storage, sync from the network into it, and queue writes with retry and a visible pending state.
+
+## Real-time
+
+WebSockets or server-sent updates must pause or reconnect with `AppState` changes; the OS suspends connections in the background.