{
  "schema_version": 1,
  "skill_name": "mobile-development",
  "evals": [
    {
      "id": "ios-build-signing-review",
      "prompt": "Our iOS team has a release build that only works on the lead developer's Mac. Reviewing their setup: the .xcodeproj references a distribution certificate and provisioning profile stored in a shared drive, builds are run from Xcode's UI, and the ExportOptions.plist is regenerated by hand each release. Walk me through reviewing and fixing the build and signing setup so any machine or CI runner can produce a signed .ipa.",
      "expected_output": "A build-and-signing review that separates building from signing. The review recommends a reproducible release build: a committed scheme and ExportOptions.plist (secrets-free), the distribution certificate and provisioning profile injected via CI secrets or a secure secrets store rather than a shared drive, and the archive/export flow scripted with xcodebuild -archive and xcodebuild -exportArchive so any machine with the same Xcode version produces the same signed artifact. It flags that regenerating ExportOptions.plist by hand is a review risk (a wrong export method or team produces a rejected upload) and that the certificate/profile must be versioned and renewed on a calendar. It verifies the .ipa actually signs with the distribution identity before upload and that build numbers increment per release.",
      "assertions": [
        "The review separates build configuration from signing assets and keeps secrets out of the repository",
        "The review scripts the archive/export flow with xcodebuild so builds reproduce on any machine or CI runner",
        "The review flags hand-regenerated ExportOptions.plist and shared-drive certificates as risks with concrete fixes",
        "The review covers certificate/profile expiry management and monotonic build numbers",
        "The review verifies the signed .ipa with the distribution identity before store upload"
      ]
    },
    {
      "id": "android-release-signing-readiness",
      "prompt": "We are about to release an Android app to Google Play for the first time. Our release keystore exists but only one engineer has it, the version code has never been set explicitly, and we have been shipping debug APKs to testers. Prepare the release build and signing for the Play Store and tell us exactly what to check before the first upload.",
      "expected_output": "A release-readiness plan for Android: configure signing in build.gradle.kts via a keystore referenced from environment variables or a gitignored keystore.properties (never committed passwords), set versionName and a monotonic versionCode explicitly, and build the Android App Bundle (bundleRelease) since Google Play requires AAB for new apps and signs per-device APKs via Play App Signing with the upload key. The plan backs up the keystore and document who holds it, verifies the signed artifact with apksigner, and lays out the Play Console flow: upload the AAB to internal/closed testing first, complete the data-safety declaration and store listing, then a staged production rollout with crash monitoring. It calls out that losing the keystore means the app identity cannot be updated.",
      "assertions": [
        "The plan configures release signing from secrets and commits no keystore or passwords",
        "The plan sets versionCode and versionName explicitly and builds the AAB required by Play",
        "The plan explains Play App Signing and the upload key versus the app signing key",
        "The plan verifies the artifact signature and tests via internal/closed tracks before production",
        "The plan covers keystore backup/custody and staged rollout with crash monitoring"
      ]
    },
    {
      "id": "mobile-testing-strategy",
      "prompt": "We just built a shopping app for iOS and Android with a shared React Native codebase. So far the only testing is developers tapping through the app on their own phones. Design a realistic mobile testing strategy covering the device and emulator matrix, the right test layers, and what runs in CI versus on a device farm.",
      "expected_output": "A layered mobile testing strategy: fast unit and component tests (Jest + React Native Testing Library) running in CI on every commit; a small set of critical E2E flows (sign-in, checkout, offline sync) with Detox on simulators and emulators in CI; and a device-farm run (Firebase Test Lab or BrowserStack) across the declared device matrix (min SDK, current SDK, mid-range device, both OSes) on every release candidate. The strategy explains what emulators/simulators hide (real networking, sensors, battery, low-memory behavior) and therefore mandates physical-device smoke tests of the signed release build, plus cold-install testing and debug-vs-release parity checks. It assigns ownership: developers own unit/component tests, a release gate requires the E2E suite and device-farm run to pass, and failures block the store submission.",
      "assertions": [
        "The strategy layers unit/component tests, E2E tests, and device-farm coverage with clear CI placement",
        "The strategy defines a concrete device matrix including min and current OS versions on both platforms",
        "The strategy explains the limits of simulators/emulators and requires physical-device release smoke tests",
        "The strategy covers cold-install and debug-vs-release parity checks",
        "The strategy assigns a release gate that blocks store submission until the suite and farm pass"
      ]
    },
    {
      "id": "store-submission-readiness",
      "prompt": "We are submitting our app to both the Apple App Store and Google Play next week. The app collects email addresses, tracks analytics events, and supports sign-in with Apple and Google. Give us a store-readiness review: what must be in place for each store, what will get us rejected, and what order to submit in.",
      "expected_output": "A store-readiness review that walks the submission checklist for both stores. For the App Store: TestFlight beta to internal and external testers first, privacy nutrition labels matching the collected data (email, analytics), Info.plist usage descriptions, complete listing with required screenshots, a demo account or demo mode since the app requires sign-in, and export compliance answers. For Google Play: the AAB uploaded to internal/closed testing, the data-safety form declaring the same data collection, privacy policy URL, and a staged production rollout. It flags the classic rejection causes: undeclared data collection, broken sign-in at review time, crashing on launch, and misleading metadata. It recommends submitting to a testing track on both stores for at least a few days before production review, and staggering the two releases so a regression can be caught on one platform before the other rolls out.",
      "assertions": [
        "The review covers TestFlight and internal/closed testing before production on both stores",
        "The review requires privacy disclosures (nutrition labels and data-safety) to match the app's actual data collection",
        "The review flags the common rejection causes: undeclared data, broken sign-in, launch crashes, misleading metadata",
        "The review covers listing assets, privacy policy, and demo access for sign-in-gated apps",
        "The review recommends staged rollout and staggered cross-platform release timing"
      ]
    },
    {
      "id": "framework-selection-and-scaffolding",
      "prompt": "We are building a new field-service app for technicians: it needs offline access to job lists, barcode scanning, GPS location capture, and push notifications, and our team is experienced in TypeScript but not Swift or Kotlin. We are deciding between native iOS + Android, Flutter, and React Native. Recommend a framework and walk through scaffolding the project correctly.",
      "expected_output": "A framework recommendation grounded in the constraints: the team's TypeScript experience and the need for shared offline, barcode, GPS, and push logic across both platforms point to React Native (Expo for new apps), with native fallback reserved only for features that need deep platform integration beyond existing modules. The response evaluates the alternatives honestly: native iOS/Android give the deepest platform control but double the implementation cost for a TypeScript team, and Flutter is a strong cross-platform option but adds Dart as a new language. It then scaffolds correctly: create-expo-app, TypeScript from the start, React Navigation or Expo Router for navigation, app.json config for bundle IDs, and a plan to verify each required capability (offline SQLite store, barcode library, expo-location, expo-notifications) early with a spike before committing to the full build.",
      "assertions": [
        "The recommendation is grounded in team skills and the required device capabilities, not hype",
        "The response compares native, Flutter, and React Native with honest tradeoffs",
        "The response scaffolds with the canonical tool for the chosen framework with TypeScript",
        "The response covers navigation, config, and bundle IDs at scaffold time",
        "The response verifies the hard device capabilities (offline, barcode, GPS, push) with an early spike"
      ]
    },
    {
      "id": "offline-sync-design",
      "prompt": "Our field-service app must work in basements and rural areas with no connectivity for hours. Technicians create and complete jobs offline, and those changes must reach the server without data loss or duplication, while the same job may be edited by a dispatcher at the same time. Design the offline storage and sync architecture.",
      "expected_output": "An offline-first architecture: local storage (SQLite-based, e.g., WatermelonDB/Realm or Room/drift depending on stack) is the source of truth while disconnected; every write is persisted locally and queued as a mutation with a client-generated ID so replay is idempotent. Sync runs when connectivity returns (with retry and exponential backoff, and a network-constraint-triggered job), uploading queued mutations in order and downloading changes since a cursor. Conflict resolution is explicit: per-field merge with timestamps for independent edits, and a visible conflict-resolution flow when the same field changed on both sides — never silent last-write-wins over newer remote data. The design covers partial sync (only the technician's assigned jobs), a clear sync-state indicator in the UI, and a strategy for handling the same job edited by a dispatcher concurrently, including server-side revision tokens.",
      "assertions": [
        "The design makes local storage the source of truth while offline and persists writes immediately",
        "The design queues mutations with idempotent replay and retry with backoff on reconnect",
        "The design defines explicit conflict resolution for concurrent edits, including the dispatcher case",
        "The design covers partial sync and a user-visible sync state indicator",
        "The design includes server-side revision tokens or equivalent to detect stale writes"
      ]
    }
  ]
}

# Android Reference — Kotlin, Gradle, Google Play

> **Last Updated:** 2026-08-03

Load this reference when the target platform is **Android** — native Kotlin
apps built with Gradle, or an Android target inside a Flutter or React Native
project (tooling for those is in [flutter.md](flutter.md) and
[react-native.md](react-native.md); this file is the platform layer under
them). It complements the shared workflow in `SKILL.md`; this file is the
Android-specific detail for scaffolding, building and signing, emulator and
device testing, and Play Store submission.

## Android fundamentals

An Android app is a compiled, signed package built by Gradle:

- **Gradle project** — a project root with `settings.gradle(.kts)`, an `app`
  module with `build.gradle(.kts)`, and `gradle/libs.versions.toml` for version
  catalog dependency management. Kotlin DSL (`.kts`) is the current default.
- **Manifest** — `AndroidManifest.xml` declares the application, activities,
  services, receivers, permissions, and the minimum/target SDK.
- **Build outputs** — `assembleDebug`/`assembleRelease` produce APKs;
  `bundleRelease` produces an **Android App Bundle (AAB)**, the required
  submission format for new apps on Google Play (since 2021, and still the
  rule). Google Play derives per-device APKs from the AAB via **Play App
  Signing**.
- **Gradle wrapper** — commit `gradlew` and `gradle/wrapper/` so builds use a
  pinned Gradle version on every machine and CI runner.

Keep the version name (`versionName`) and version code (`versionCode`, a
monotonic integer) in `build.gradle.kts` — Play rejects a build whose version
code is lower than a previous upload.

## Scaffolding

- **New native app** — create the project in Android Studio or with the Gradle
  template (`gradle init`); choose Kotlin and Jetpack Compose for new UI.
- **Minimum and target SDK** — set `minSdk` to the oldest Android version in
  scope and keep `targetSdk` current; Play enforces minimum target API levels
  for new and updated submissions, and raised target levels are announced
  annually.
- **Dependencies** — prefer version catalogs (`libs.versions.toml`) and commit
  the lockfile (`gradle.lockfile` or dependency locking) for reproducibility.
- **App structure** — a single-activity app with Compose navigation for new
  work; keep the manifest minimal and declare only the permissions the app
  actually uses.

## Builds and signing

### Signing model

- **Local signing** — a Java keystore (`.jks`/`.keystore`) with an alias,
  configured via `signingConfigs` in `build.gradle.kts`. Signing configs must
  never be committed with their passwords; read them from environment
  variables or a secrets store at build time.
- **Play App Signing** — Google holds the app signing key; the **upload key**
  you sign with is only used to upload the AAB to Play. Upload keys can be
  rotated without user-visible changes; losing the upload key requires Play
  Console support intervention.
- **Keystore custody** — the release keystore is a production secret: back it
  up, store it outside the repository, and restrict access. Losing it means
  the app can no longer be updated under the same identity.

### Signing practices

- **Debug builds sign automatically** with the debug keystore — never ship
  them.
- **Release builds in CI** — inject keystore path, passwords, and aliases via
  CI secrets; keep `keystore.properties` (or equivalent) out of version
  control. Use `signingConfig` referenced from a file that CI can generate.
- **Two build types** — `debug` and `release` differ in signing, shrinking
  (R8/ProGuard), and manifest merging. Smoke-test the signed release artifact,
  not just the debug build.

### Build commands

```sh
# Debug APK (fast iteration)
./gradlew assembleDebug

# Release APK (signed, shrunk)
./gradlew assembleRelease

# Release App Bundle (required for Play Store submission)
./gradlew bundleRelease
```

The AAB lives in `app/build/outputs/bundle/release/`; the signed APK in
`app/build/outputs/apk/release/`. Verify the APK signature with
`apksigner verify --print-certs app-release.apk` before distribution.

## Emulators and devices

- **Emulators (AVD)** — Android Studio AVD Manager creates virtual devices;
  headless emulators are scriptable for CI:

  ```sh
  emulator -avd Pixel_8 -no-window -no-audio -no-boot-anim &
  adb wait-for-device
  adb install app/build/outputs/apk/debug/app-debug.apk
  adb shell am start -n com.example.app/.MainActivity
  ```

- **Physical devices** — enable USB debugging and use `adb devices` to verify
  the connection; real devices reveal networking, battery, and sensor
  behavior the emulator hides.
- **Debugging** — `adb logcat` for logs, `adb shell dumpsys` for system
  state, and Android Studio Profiler for CPU/memory/network. `adb reverse`
  maps device ports to the host for local API servers.
- **Device matrix** — cover the min SDK, the current SDK, and a mid-range
  device; use Firebase Test Lab (or a farm) for broad matrix coverage without
  local hardware.

## Lifecycle and backgrounding

- **Component lifecycle** — Activities/Fragments move through
  started/paused/stopped states; ViewModels survive configuration changes and
  should own UI state. `Process death` can destroy everything else.
- **State persistence** — save and restore instance state (`SavedStateHandle`,
  `rememberSaveable` in Compose) for process death; persist anything important
  to a durable store.
- **Background work is restricted** — Android restricts background execution
  and network. Use `WorkManager` for deferrable, guaranteed work, and
  foreground services (with a visible notification) only for user-visible
  tasks. `AlarmManager` is for alarms, not general scheduling.
- **Doze and app standby** — the system batches background work when idle;
  test offline sync and push handling under Doze, not just with the screen on.

## Offline and sync

- **Local persistence** — Room (SQLite ORM) for structured data, DataStore
  (Preferences/Proto) for settings, and file storage under the app's
  internal/external storage. Keep the database schema versioned with
  migrations tested.
- **Sync pattern** — write locally, then sync: queue writes, replay them with
  retry and backoff when connectivity returns, and resolve conflicts
  explicitly. `WorkManager` with network constraints is the idiomatic sync
  trigger.
- **Connectivity** — use `ConnectivityManager`/NetworkCallback to observe
  connectivity, but design for a lost network degrading gracefully.

## Testing

- **Unit tests** — JUnit + MockK/mockito for logic; Robolectric runs
  Android-framework code on the JVM for fast local tests.
- **Instrumented/UI tests** — Espresso (Views) or Compose UI tests
  (`createAndroidComposeRule`) drive the real app on an emulator/device.
- **Snapshot tests** — Compose Preview-based snapshot testing (e.g.,
  Roborazzi, Paparazzi) catches UI regressions without a device.
- **Device farms** — run the instrumentation suite on Firebase Test Lab
  across the device matrix; a test passing on one API level is not a
  guarantee across them.

## Store submission

1. **Play Console setup** — the $25 developer account, app record, and
   developer verification (new developers complete identity verification and
   a closed-test requirement with at least 12 testers for 14 days before
   production access).
2. **Upload the AAB** — upload `app-release.aab` to an internal, closed, or
   open testing track first; run internal testing with your own devices before
   production. Play generates and signs per-device APKs via Play App Signing.
3. **Store listing and policies** — screenshots, feature graphic, privacy
   policy URL, and a **data safety** declaration matching what the app
   collects. Play policy review rejects apps for undeclared data collection,
   broken core functionality, and misleading metadata.
4. **Staged rollout** — use phased rollouts (e.g., 10% → 50% → 100%) and
   monitor crash and ANR rates in Play Console before full release. Pause the
   rollout immediately if a serious regression appears.

## Key references

- Google Play Console help and policy center (support.google.com/googleplay)
  — current data-safety and testing-track requirements.
- Android developer documentation (developer.android.com) — target API
  level deadlines and app bundle guidance change annually.

# Flutter Reference — Dart, flutter CLI, iOS + Android

> **Last Updated:** 2026-08-03

Load this reference when the project is built with **Flutter** — a single Dart
codebase compiled to native iOS and Android binaries. It complements the
shared workflow in `SKILL.md` and the platform references ([ios.md](ios.md),
[android.md](android.md)): Flutter delegates signing, lifecycle, and store
mechanics to the underlying platforms, so this file focuses on the Flutter
layer — scaffolding, builds, device workflows, and testing.

## Flutter fundamentals

- **Flutter SDK** — install the current stable channel (`flutter stable`).
  Pin the Flutter version (via the `flutter` SDK manager or the repo's
  `.fvmrc`/FVM config) so CI and machines build the same binary.
- **Project structure** — `lib/` (Dart source), `test/` (tests), `pubspec.yaml`
  (dependencies and assets), and platform folders `android/`, `ios/`,
  `linux/`, `macos/`, `web/`, `windows/`. Cross-platform code lives in `lib/`;
  the platform folders are generated and rarely edited directly.
- **Dependencies** — `pubspec.yaml` with the `pubspec.lock` committed for
  reproducibility; `flutter pub get` resolves them. Prefer the Flutter
  ecosystem packages maintained by the Flutter team.
- **Rendering** — Flutter renders its own UI with Skia/Impeller; fonts,
  text, and layout behave consistently across platforms, which simplifies
  cross-device visual testing.

## Scaffolding

```sh
flutter create --org com.example --project-name my_app --platforms ios,android my_app
```

- **Project name matters** — it becomes the Dart package name and the default
  bundle ID prefix; changing it later is disruptive. `--org` sets the bundle
  identifier base (`com.example.my_app`).
- **App entry point** — `lib/main.dart` runs `runApp()` with the root widget;
  keep it thin and delegate to feature-level code.
- **State management** — choose per app size: `setState` for local state,
  Provider/Riverpod/Bloc for shared state. Keep state logic testable in Dart
  without a device.
- **Platform tooling** — iOS targets still need Xcode, Android targets still
  need the Android SDK/JDK; `flutter doctor` verifies the whole toolchain.

## Builds and signing

### Build commands

```sh
# Debug build + hot reload on a connected device
flutter run

# Release APK (Android)
flutter build apk --release

# Release App Bundle (Android, for Play Store)
flutter build appbundle --release

# iOS archive + export (requires macOS + Xcode; produces .ipa via Xcode)
flutter build ipa --release
```

### Signing

Flutter delegates signing to the platform toolchains:

- **Android** — signing is configured in `android/app/build.gradle.kts`
  exactly as for a native app: keystore + `signingConfigs`, with secrets via
  environment or a gitignored `key.properties`. `flutter build appbundle`
  produces the AAB that Play signs via Play App Signing.
- **iOS** — `flutter build ipa` runs the Xcode archive/export flow under the
  hood; configure automatic signing (developer team) in the Xcode project or
  supply an `ExportOptions.plist`. TestFlight and App Store upload work the
  same way as native iOS.
- **Flutter specific** — `flutter build` embeds the Dart AOT snapshot into
  the platform binary; `--release` differs from `--debug` in tree shaking and
  compilation, so test the release build.

## Devices and emulators

```sh
flutter devices          # list connected devices and emulators
flutter emulators        # list available emulators
flutter run -d <device>  # run on a specific device
```

- **Hot reload** — `flutter run` supports hot reload (state preserved) and hot
  restart (state reset) for fast iteration; hot reload does not run on
  release builds.
- **iOS simulator** — boot via Xcode or `open -a Simulator`; `flutter run -d
  "iPhone 16"`.
- **Android emulator** — start an AVD first; `flutter run` picks it up.
- **Physical devices** — USB debugging (Android) and trust the computer (iOS);
  test on real devices for networking, sensors, and performance.
- **Debug vs release parity** — `flutter run` (debug) enables hot reload but
  is slower and includes assertions; verify the release build (`flutter run
  --release`) before shipping.

## Lifecycle and backgrounding

- **App lifecycle** — `WidgetsBindingObserver` + `AppLifecycleState`
  (inactive/paused/resumed/detached) tells the widget tree about backgrounding
  and resumption. Persist state on `paused`, not on `resumed`.
- **Platform behavior underneath** — iOS and Android still enforce their own
  background rules; Flutter code stops executing when the app is suspended.
  Use platform channels or plugins (`WorkManager`, background fetch) for
  background work, and be aware that plugins wrap the platform APIs covered in
  [ios.md](ios.md) and [android.md](android.md).
- **Process death** — the OS can kill the app at any time; persist state to
  local storage rather than relying on widget state.

## Offline and sync

- **Local persistence** — `sqflite`/`drift` (SQLite) for structured data,
  `shared_preferences` for small settings, and file/asset storage for larger
  data. Keep database migrations versioned and tested.
- **Sync pattern** — persist locally first, queue mutations, and replay them
  against the API with retry and backoff when connectivity returns.
  `connectivity_plus` observes reachability; design for offline to degrade
  gracefully regardless.
- **Conflict resolution** — define an explicit strategy (last-write-wins,
  per-field merge, or conflict UI) so offline edits never silently clobber
  remote data.

## Testing

```sh
flutter test                       # unit + widget tests
flutter test integration_test      # integration tests on device/emulator
```

- **Widget tests** — fast, headless tests of widget trees (`WidgetTester`,
  `pumpAndSettle`); cover state, navigation, and rendering logic without a
  device.
- **Unit tests** — plain Dart tests for models, reducers, and services;
  dependency-inject network and storage so tests run offline.
- **Integration tests** — `integration_test` runs the real app on a device or
  emulator, driving the UI and asserting end-to-end behavior; run these on the
  device matrix (locally or on Firebase Test Lab) before release.
- **Golden/snapshot tests** — `matchesGoldenFile` renders widgets to images
  for visual regression; commit golden files with reviewed diffs.

## Store submission

Flutter apps ship through the same stores as native apps; the store-facing
work is platform mechanics:

- **Android** — upload `build/app/outputs/bundle/release/app-release.aab` to
  Play Console (internal/closed/open testing, data-safety declaration, staged
  rollout). See [android.md](android.md) for the full checklist.
- **iOS** — `flutter build ipa`, upload the `.ipa` to App Store Connect
  (TestFlight first), complete privacy labels and listing, submit for review.
  See [ios.md](ios.md) for the full checklist.
- **Version parity** — keep `version`/`build` aligned between `pubspec.yaml`
  and the platform configs so a release is identifiable across stores.

## Key references

- Flutter documentation (docs.flutter.dev) — current stable channel releases,
  platform integration guides, and release notes.
- Per-platform references in this skill — [ios.md](ios.md) and
  [android.md](android.md) for signing, lifecycle, and store mechanics.

# iOS Reference — Swift, Xcode, App Store

> **Last Updated:** 2026-08-03

Load this reference when the target platform is **iOS** — native Swift apps
built with Xcode, or an iOS target inside a Flutter or React Native project
(that tooling is covered in [flutter.md](flutter.md) and
[react-native.md](react-native.md); this file is the platform layer under
them). It complements the shared workflow in `SKILL.md`; this file is the
iOS-specific detail for scaffolding, building and signing, simulator and
device testing, and App Store submission.

## iOS fundamentals

An iOS app is a signed, structured bundle (`.app`) archived into an `.ipa` for
distribution:

- **Xcode project** — `.xcodeproj` (single target) or `.xcworkspace` (when
  using CocoaPods or Swift Package Manager workspace integration). The project
  file holds build settings, targets, schemes, and signing configuration.
- **Build products** — the `.app` bundle contains the compiled binary
  (Mach-O), `Info.plist` (bundle ID, version, permissions), entitlements, and
  resources. Xcode "Archive" produces the `.xcarchive` used for store upload.
- **Distribution artifacts** — `.ipa` (signed `.app` inside a `Payload/`
  directory) for TestFlight and App Store, and `.xcarchive` for archival and
  re-export. Ad-hoc and enterprise distribution reuse the same `.ipa` format
  with different signing profiles.

Keep `Info.plist` keys (bundle identifier, `CFBundleShortVersionString`,
`CFBundleVersion`, usage-description strings for camera/location/etc.) accurate
and reviewed — store review and crash reporting both depend on them.

## Scaffolding

- **New native app** — create the project in Xcode or with `xcodebuild`
  templates; choose SwiftUI for new apps (UIKit remains for legacy or
  fine-grained control). Set the deployment target to the minimum iOS version
  you committed to in scope.
- **Dependencies** — prefer Swift Package Manager (SPM) for new work;
  CocoaPods is still common in existing codebases. Commit the lockfile
  (`Package.resolved`, `Podfile.lock`) so builds are reproducible.
- **App structure** — keep the app entry point (the `@main` `App`/`AppDelegate`
  and scene) thin, and organize the rest by feature rather than by type.
- **Signing early** — set up a development team and automatic signing before
  the first device run; the simulator can build unsigned, but a device needs a
  valid signing identity and provisioning profile.

## Builds and signing

### Signing model

iOS signing has two assets, both managed per Apple Developer account:

- **Certificates** — a development certificate (for device installs) and a
  distribution certificate (for TestFlight/App Store). Certificates are tied
  to the account; distribution certificates can be shared between machines but
  should be kept in secure storage.
- **Provisioning profiles** — bind a certificate to app IDs and (for
  development) devices. Profiles expire and must be renewed; automatic signing
  in Xcode handles this when a developer account is configured.

### Signing practices

- **Automatic signing for development** — let Xcode manage profiles against
  the developer account for local device builds.
- **Release signing in CI** — export the distribution certificate and profile
  as secrets; never commit `.p12`, `.mobileprovision`, or private keys to the
  repository. Use `xcodebuild -exportArchive -exportOptionsPlist` with the
  `-exportOptionsPlist` file committed (it contains no secrets) so CI produces
  the same artifact as a local Archive.
- **Two app IDs, two signing identities** — a development build and a release
  build are different signed artifacts. Verify both sign correctly; a profile
  mismatch is the most common first-upload rejection.

### Build commands

```sh
# Build for a simulator (no signing needed)
xcodebuild -workspace App.xcworkspace -scheme App -configuration Debug \
  -sdk iphonesimulator build

# Archive for distribution (signs with the distribution identity)
xcodebuild -workspace App.xcworkspace -scheme App -configuration Release \
  -archivePath build/App.xcarchive archive

# Export an .ipa for TestFlight / App Store from the archive
xcodebuild -exportArchive -archivePath build/App.xcarchive \
  -exportOptionsPlist ExportOptions.plist -exportPath build/ipa
```

## Simulators and devices

- **Simulators** — `xcrun simctl` lists, boots, installs, and launches
  simulators headlessly, which makes it scriptable for CI smoke tests:

  ```sh
  xcrun simctl list devices
  xcrun simctl boot "iPhone 16"
  xcrun simctl install booted build/App.app
  xcrun simctl launch booted com.example.app
  ```

- **Physical devices** — a device build requires the device's UDID in a
  development provisioning profile. Verify on a physical device: real
  networking, background execution, push, and sensors behave differently from
  the simulator.
- **Debugging** — `xcodebuild` + Instruments for profiling; `log stream` and
  unified logging (OSLog) for diagnostics on device. Crash reports appear in
  Xcode Organizer and App Store Connect once TestFlight testers use the app.

## Lifecycle and backgrounding

- **Scene-based lifecycle** — modern iOS apps manage `Scene` lifecycle
  (active/inactive/background); the app delegate owns launch and termination.
  Persist state in `sceneDidEnterBackground` or at state transitions — do not
  assume the app will be resumed.
- **Background modes** — background execution requires a declared background
  mode (audio, location, background fetch, push notifications) in
  `Info.plist` capabilities. Apple reviews these declarations; use them only
  for their stated purpose.
- **Push notifications** — the app must register for remote notifications and
  handle both foreground presentation and background delivery; silent pushes
  are rate-limited by the OS.
- **Process death** — the OS can terminate the app at any time. Save
  user-visible state and restore it on launch rather than keeping it in
  memory.

## Offline and sync

- **Local persistence** — Core Data or SwiftData for relational models,
  `FileManager`/Documents for files, `UserDefaults` for small settings.
  Consider that `UserDefaults` is not a database.
- **Sync pattern** — persist locally first, then sync: queue writes in a local
  store, replay them against the API when connectivity returns, and resolve
  conflicts with an explicit strategy. `URLSession` with `waitsForConnectivity`
  and background URL sessions handle retries and large transfers.
- **Reachability** — use `NWPathMonitor` to react to connectivity changes, but
  design so a lost network degrades gracefully instead of crashing.

## Testing

- **Unit tests** — XCTest with the `@testable import` pattern; run in the
  simulator (`xcodebuild test`).
- **UI tests** — XCUITest drives the real app via accessibility identifiers;
  keep those identifiers stable and semantic.
- **Snapshot/visual tests** — libraries such as Swift Snapshot Testing render
  views to images for regression detection; keep fixtures in-repo and
  reviewed.
- **Performance** — measure launch time, frame rate, and memory with
  Instruments (or XCTest metrics) on a physical device; simulator numbers are
  not representative.

## Store submission

1. **TestFlight first** — upload the archive to App Store Connect
   (`xcrun altool`/`notarytool` or Xcode Organizer), distribute to internal
   and external testers, and let real devices exercise the app before review.
2. **App Store Connect setup** — the app record, bundle ID, pricing, and
   availability; export compliance questions; and the build must match the
   uploaded binary.
3. **Review readiness** — privacy nutrition labels for collected data,
   `Info.plist` usage descriptions, a complete store listing (screenshots for
   the required device sizes), and a working demo account or demo mode if the
   app requires sign-in. The App Review guidelines are enforced by humans;
   flaky sign-in, hidden features, and misleading metadata are common
   rejection causes.
4. **Staged release** — submit for review with a gradual release or schedule
   the release so a regression reaches few users first. Monitor crash rates
   after release.

## Key references

- Apple Developer Program and App Store Connect documentation
  (developer.apple.com/app-store/submitting).
- Xcode release notes and current SDK requirements near submission time —
  minimum Xcode and iOS SDK versions change annually.

# React Native Reference — Metro, Expo, iOS + Android

> **Last Updated:** 2026-08-03

Load this reference when the project is built with **React Native** — a
JavaScript/TypeScript codebase rendering native UI components on iOS and
Android. It complements the shared workflow in `SKILL.md` and the platform
references ([ios.md](ios.md), [android.md](android.md)): React Native
delegates signing, lifecycle, and store mechanics to the underlying
platforms, so this file focuses on the React Native layer — scaffolding,
builds, device workflows, and testing, including the Expo toolchain.

## React Native fundamentals

- **Two toolchains** — the **React Native CLI** (`@react-native-community/cli`,
  bare workflow, owns the `ios/` and `android/` folders) and **Expo**
  (`create-expo-app`, managed workflow with `expo prebuild`/EAS for native
  code when needed). Expo is the recommended starting point for new apps; the
  CLI is for apps that need full native control from day one.
- **Metro bundler** — Metro compiles and bundles the JS/TS into the native
  binary; the Metro config (`metro.config.js`) controls transforms, and the
  Metro dev server powers fast refresh during development.
- **New Architecture** — current React Native releases (0.7x/0.8x line, with
  Expo SDK 56 bundling the stable line) default to the New Architecture
  (Fabric + TurboModules). Verify third-party libraries support the New
  Architecture before adoption.
- **Dependencies** — `package.json` with `package-lock.json`/`yarn.lock`
  committed; use the React Native/Expo version alignment (`npx
  expo install` keeps packages SDK-compatible).

## Scaffolding

```sh
# Expo (recommended for new apps)
npx create-expo-app@latest MyApp

# React Native CLI (bare workflow)
npx @react-native-community/cli@latest init MyApp
```

- **App entry point** — `App.tsx` renders the root component; keep it thin
  and route via React Navigation (or Expo Router) rather than hand-rolled
  navigation state.
- **Platform folders** — the CLI keeps `ios/` and `android/` in the repo;
  Expo hides them until `expo prebuild`. Treat generated platform folders as
  build outputs, not app code.
- **TypeScript** — use TypeScript from the start; the default templates are
  typed and the ecosystem type definitions are mature.
- **Environment config** — app config (`app.json`/`app.config.js` for Expo,
  `.env` for secrets via `expo-constants` or a config loader); never commit
  real secrets.

## Builds and signing

### Build commands

```sh
# Dev server with fast refresh (Metro)
npx expo start        # Expo: QR code / dev client
npm run start         # RN CLI: Metro dev server

# Android release APK/AAB
cd android && ./gradlew assembleRelease      # RN CLI
npx expo run:android --variant release      # Expo with prebuild
npx eas build --platform android --profile production   # EAS cloud build

# iOS archive + export (requires macOS + Xcode)
cd ios && xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -configuration Release archive
npx eas build --platform ios --profile production          # EAS cloud build
```

### Signing

React Native delegates signing to the platform toolchains:

- **RN CLI** — Android signing via `android/app/build.gradle.kts` keystore
  config (as native Android); iOS via the Xcode project's automatic signing or
  an `ExportOptions.plist` (as native iOS). See [android.md](android.md) and
  [ios.md](ios.md) for the platform details.
- **Expo / EAS** — EAS Build can manage credentials: it generates and stores
  keystores and Apple certificates (with `eas credentials`), handles
  provisioning, and can run in a cloud environment without a Mac for iOS
  builds. Credentials live in Expo's secure storage or your own
  `credentials.json` (gitignored).
- **Signing secrets** — keystores, `.p12`, provisioning profiles, and Expo
  credentials are production secrets; never commit them, and back them up so
  an app can be updated under the same identity.

## Devices and emulators

```sh
npx expo start              # scan QR with Expo Go or a dev client
npx expo run:ios            # build and run on the iOS simulator
npx expo run:android        # build and run on an Android emulator
```

- **Expo Go vs dev client** — Expo Go runs the JS without a native build (fast
  iteration); a development build (dev client) is required for custom native
  modules. Test both the debug JS experience and the release bundle.
- **Fast refresh** — Metro hot-reloads edited JS while preserving state;
  restart the app (not just refresh) after native or config changes.
- **Physical devices** — Android: USB debugging or Expo Go via QR; iOS: Expo
  Go via QR on the same network. Real devices expose networking, permissions,
  and performance differences from simulators.
- **Debug vs release parity** — the release bundle is minified, tree-shaken,
  and runs without the dev server; smoke-test `--variant release`/production
  builds before store submission.

## Lifecycle and backgrounding

- **AppState** — `AppState` (active/background/inactive) is the
  cross-platform lifecycle signal; persist state on `background` and resume
  cleanly on `active`. `AppState.addEventListener` covers both platforms.
- **Background execution** — JS stops when the app is backgrounded; use
  platform mechanisms (headless tasks, background fetch, push) via native
  modules or libraries. iOS and Android background rules from
  [ios.md](ios.md) and [android.md](android.md) apply underneath.
- **Process death** — the OS can kill the app at any time; persist
  user-visible state to local storage rather than relying on in-memory React
  state.

## Offline and sync

- **Local persistence** — `AsyncStorage` (small key-value), `MMKV`
  (performant key-value), or SQLite-based stores (`react-native-sqlite-storage`,
  WatermelonDB, Realm) for structured offline data. Keep schemas versioned.
- **Sync pattern** — persist locally first, queue mutations, and replay them
  against the API with retry and backoff when connectivity returns.
  `@react-native-community/netinfo` observes reachability; design for offline
  to degrade gracefully regardless.
- **Conflict resolution** — define an explicit strategy (last-write-wins,
  per-field merge, or conflict UI) so offline edits never silently clobber
  remote data.

## Testing

```sh
npm test                 # Jest unit/component tests
npx detox test           # Detox E2E tests on iOS/Android
```

- **Unit/component tests** — Jest with React Native Testing Library;
  dependency-inject services and mock native modules so tests run headless.
- **E2E tests** — **Detox** drives the real app on a simulator/emulator with
  native synchronization; test critical user flows (sign-in, checkout, sync)
  on both platforms. Detox requires the app to build for testing.
- **Expo testing** — `jest-expo` preset with `@testing-library/react-native`
  for component tests; `expo prebuild` + Detox or Maestro for E2E.
- **Device farms** — run E2E suites across the device matrix (Firebase Test
  Lab, BrowserStack) before release; a flow that passes on one device is not a
  guarantee across versions and screen sizes.
- **Performance** — measure JS thread time, native render, and memory with
  the React Native DevTools/Perf Monitor or platform profilers on a device;
  Hermes is the default JS engine for the current releases.

## Store submission

React Native apps ship through the same stores as native apps:

- **Android** — upload the signed AAB (`android/app/build/outputs/bundle/
  release/app-release.aab`, or the EAS-produced artifact) to Play Console with
  internal/closed/open testing, data-safety declaration, and staged rollout.
  See [android.md](android.md).
- **iOS** — archive via Xcode or EAS, upload the `.ipa` to App Store Connect
  (TestFlight first), complete privacy labels and listing, submit for review.
  See [ios.md](ios.md).
- **Version parity** — keep `version` in `app.json`/`package.json` aligned
  with the platform build numbers so a release is identifiable across stores
  and in crash reports.

## Key references

- React Native documentation (reactnative.dev) — New Architecture, Hermes, and
  release notes.
- Expo documentation (docs.expo.dev) — SDK versions, EAS Build credentials,
  and upgrade guides.
- Per-platform references in this skill — [ios.md](ios.md) and
  [android.md](android.md) for signing, lifecycle, and store mechanics.