reis-mobile 0.7.2 → 0.8.0

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

@@ -0,0 +1,82 @@
+# Performance on native iOS
+
+iOS performance work is mostly main-thread work. The main thread renders, handles touch and runs SwiftUI/UIKit updates; anything that blocks it becomes a hitch, a hang or a watchdog termination. Instruments explains a single run, MetricKit and Xcode Organizer explain the installed base.
+
+Related material already in this plugin: [`mobile-ios/references/performance-release.md`](../../mobile-ios/references/performance-release.md).
+
+## Measure
+
+**Release configuration, physical device.** The Simulator has a different GPU path and no thermal or memory pressure; debug builds skip optimization and enable extra checks.
+
+| Question | Tool |
+|---|---|
+| Where CPU time goes | Instruments → Time Profiler, with "Record Waiting Threads" to catch blocking |
+| Why a scroll drops frames | Instruments → Animation Hitches (hitch time per frame, scroll and commit phases) |
+| What SwiftUI is doing and why a view updated | Instruments → SwiftUI template; `Self._printChanges()` inside `body` in debug |
+| Main thread blocked | Instruments → Hangs; the Thread Performance Checker in a debug run |
+| Allocations, growth and leaks | Instruments → Allocations (mark generations around the journey) and Leaks; the Memory Graph Debugger for retain cycles |
+| Launch cost | Instruments → App Launch; `DYLD_PRINT_STATISTICS=1` for pre-main dynamic linking time |
+| Field data from real users | MetricKit (`MXMetricManager`), and Xcode Organizer → Launch Time, Hangs, Memory, Disk Writes, Battery |
+| Download size | App Store Connect → App Store → the build's app size report, per device variant |
+
+Apple treats the main thread being blocked for more than about 250 ms as a hang; Organizer reports it as a hang rate per hour of use. A scroll hitch is measured as *hitch time ratio* — milliseconds of hitch per second of scrolling.
+
+## Launch
+
+Launch splits into pre-main (dynamic linker, runtime setup) and post-main (your `AppDelegate`/`App` initialization up to the first usable frame). Apple's guidance is to finish launch in roughly 400 ms, before the system's launch animation ends.
+
+- **Pre-main:** the number of dynamically linked frameworks dominates. Merge small dynamic frameworks into static libraries or use mergeable libraries; remove `+load` methods and heavy static initializers (`__attribute__((constructor))`, non-lazy Swift globals with side effects).
+- **Post-main:** every SDK initialized synchronously in `application(_:didFinishLaunchingWithOptions:)` is launch cost. Defer analytics, remote config, crash-symbol upload and network prefetch to after the first frame. Read persisted state asynchronously; `UserDefaults` is cheap but a Core Data or SwiftData stack opened on the main queue is not.
+- **Measure the right end point.** `os_signpost` a span from `didFinishLaunching` to the moment content is on screen, and query it in a UI test with `XCTOSSignpostMetric`.
+
+```swift
+import XCTest
+
+final class LaunchTests: XCTestCase {
+    func testLaunchPerformance() {
+        measure(metrics: [XCTApplicationLaunchMetric()]) {
+            XCUIApplication().launch()
+        }
+    }
+}
+```
+
+`measure(metrics:)` records a baseline in the test bundle and fails the test when a later run regresses past the configured deviation — this is the cheapest regression gate on iOS.
+
+## SwiftUI updates
+
+- **Identity drives everything.** A view whose identity changes is torn down and rebuilt; a `ForEach` over indices instead of stable `id`s rebuilds every row on any change. Use `Identifiable` with an id that survives a refresh.
+- **Narrow what `body` observes.** With `@Observable`, SwiftUI tracks the exact properties read inside `body`; reading a whole model object where one property is needed widens the dependency. With `ObservableObject`, every `@Published` change invalidates every observer — split the object instead.
+- `Self._printChanges()` at the top of `body` prints which dependency caused the update. It is the fastest way to answer "why did this redraw".
+- **Lazy containers for long content:** `LazyVStack`/`LazyHStack` inside a `ScrollView`, or `List`. A plain `VStack` in a `ScrollView` builds every row.
+- **`AnyView` and heavy type erasure** defeat structural identity and the diffing fast path; prefer `@ViewBuilder` and generics.
+- **Expensive work in `body`.** `body` may run many times per frame. Format dates, sort and filter outside it, in the model.
+
+For UIKit: cell reuse (`dequeueReusableCell`), self-sizing cells with cached heights, `UICollectionViewDiffableDataSource` over `reloadData`, image decoding off the main thread (`UIImage.prepareForDisplay`/`preparingForDisplay`), and avoiding `layoutIfNeeded` inside `layoutSubviews`.
+
+## Memory
+
+- Retain cycles are the dominant leak: a closure capturing `self` strongly in a long-lived object, a delegate declared `strong`, a `Timer` or `NotificationCenter` observer never invalidated, a `Task` that outlives its owner. `[weak self]` in escaping closures and the Memory Graph Debugger's cycle detection cover most of it.
+- Images: decode at display size (`UIGraphicsImageRenderer`, `prepareThumbnail(of:)`, or `ImageIO` with `kCGImageSourceThumbnailMaxPixelSize`). Full-resolution decoding into a small view is the standard memory spike.
+- `MXAppExitMetric` from MetricKit tells you how often users' apps were terminated for memory pressure in the field — the only reliable signal that the footprint is too large on the devices you actually ship to.
+
+## Concurrency and the main thread
+
+- `@MainActor` isolates UI state; work that is not UI should not be on it. An `actor` or a detached `Task` with an explicit priority keeps parsing and I/O off the main thread.
+- A synchronous call into a `DispatchQueue.sync`, a `NSLock`, or an `await` on an actor already busy on the main thread all produce a hang. The Hangs instrument names the blocking frame.
+- Background `URLSession` configurations continue transfers after suspension; ordinary sessions do not. See [background.md](background.md).
+
+## Regression detection in CI
+
+- `XCTMetric` based tests (`XCTApplicationLaunchMetric`, `XCTClockMetric`, `XCTMemoryMetric`, `XCTOSSignpostMetric`) with committed baselines fail the build on regression. Run them on a pinned simulator or device model; baselines are per-device.
+- Track binary size per build from the archive and compare against the previous baseline.
+- Feed MetricKit payloads into your backend so launch, hang and memory metrics have a per-release series. See [mobile-observability](../../mobile-observability/SKILL.md).
+
+## Official documentation
+
+- Improving your app's performance: https://developer.apple.com/documentation/xcode/improving-your-app-s-performance
+- Reducing your app's launch time: https://developer.apple.com/documentation/xcode/reducing-your-app-s-launch-time
+- Understanding hangs in your app: https://developer.apple.com/documentation/xcode/understanding-hangs-in-your-app
+- Analyzing responsiveness issues: https://developer.apple.com/documentation/xcode/analyzing-responsiveness-issues-in-your-shipping-app
+- MetricKit: https://developer.apple.com/documentation/metrickit
+- Performance tests with XCTest: https://developer.apple.com/documentation/xctest/performance-tests

package/skills/mobile-performance/references/kotlin-multiplatform.md

@@ -0,0 +1,62 @@
+# Performance in Kotlin Multiplatform
+
+A KMP performance problem is either **shared Kotlin cost**, which shows up on both targets, or a **target-specific consequence** — the Kotlin/Native binary on iOS, the interop boundary, or the host UI. Deciding which comes first is the whole job: optimizing shared code that is not the bottleneck is wasted work, and so is profiling the Android host for a cost that lives in `commonMain`.
+
+Related material already in this plugin: [`mobile-kmp/references/build-performance.md`](../../mobile-kmp/references/build-performance.md) and [`source-sets.md`](../../mobile-kmp/references/source-sets.md).
+
+## 1. Split shared cost from host cost
+
+Run the same journey on both hosts and compare:
+
+| Observation | Where the cost lives |
+|---|---|
+| Slow on Android and iOS, similar magnitude | Shared Kotlin: algorithm, serialization, database access in `commonMain` |
+| Slow only on iOS | Kotlin/Native: memory management, the Swift/Kotlin bridge, a suspend function crossing into Swift, framework initialization |
+| Slow only on Android | The Android host: Compose recomposition, main-thread work in the ViewModel, `ContentProvider` initializers |
+| Both slow, different symptoms | Two problems. Fix them separately |
+
+Then profile with the host's own tools — there is no KMP profiler. Android Studio Profiler and Macrobenchmark for the Android host ([android.md](android.md)); Instruments for the iOS host ([ios.md](ios.md)), where Kotlin frames appear once the framework's dSYM is available to the trace.
+
+Benchmark the shared code directly where you can: `kotlinx-benchmark` runs the same benchmark on JVM and Native targets, which is the only way to compare the two compilers' output for your algorithm rather than guessing.
+
+## 2. The interop boundary
+
+Every call from Swift into the generated framework crosses a bridge. One call per frame is free; one call per list row per frame is not.
+
+- **Batch the crossing.** Return a whole page of prepared view state in one call instead of exposing a getter per field. The shared layer should expose data already shaped for the screen.
+- **Suspend functions and `Flow` become callbacks in Swift.** Each emission crosses the boundary and hops a dispatcher. A `Flow` that emits per keystroke from shared code into SwiftUI is a per-keystroke bridge crossing plus a SwiftUI update — debounce or conflate in shared code, not in Swift.
+- **Collections cross by conversion.** A Kotlin `List` handed to Swift is bridged; a large list converted on every access is a hidden O(n) per call. Hold the reference, do not re-fetch.
+- **Objective-C interop erases generics and sealed hierarchies**, which pushes Swift callers into exhaustive `switch`es over erased types and sometimes into defensive copies. Design a flat, explicitly-typed API surface at the boundary.
+
+## 3. Kotlin/Native specifics
+
+- The current Kotlin/Native memory manager removes the old freezing rules, so shared mutable state across threads is allowed — but objects still cross into Objective-C autorelease pools, and retain cycles between a Kotlin object and a Swift closure leak exactly like they do in pure Swift. Break them with `[weak self]` on the Swift side and explicit cancellation on the Kotlin side.
+- **Framework initialization is launch cost on iOS.** Anything in a Kotlin top-level property with an initializer, or in a Koin/DI module built at framework load, runs before your first screen. Keep it lazy.
+- **Framework size** counts against the app's download size. Check `isStatic`, dead-code elimination and whether you export more modules than the host actually calls (`export(...)` in the framework block pulls whole modules into the public API and prevents their elimination).
+- Release builds only. Kotlin/Native debug binaries are dramatically slower than release ones, and a "KMP is slow" report measured on a debug framework is a measurement bug.
+
+## 4. Shared code that is usually the bottleneck
+
+- **Serialization.** `kotlinx.serialization` over a large payload on the main dispatcher blocks both hosts. Parse on `Dispatchers.Default`, and parse once — not per screen.
+- **Database access.** SQLDelight queries on the calling thread; map rows lazily and do not materialize a whole table to display twenty rows.
+- **Flow operators.** An unconfined chain of `map`/`combine` re-running on every upstream emission multiplies work across the boundary. `distinctUntilChanged`, `conflate` and `stateIn` with a sharing policy bound to the host lifecycle keep it bounded.
+- **`expect`/`actual` asymmetry.** A cheap JVM implementation and an expensive Native one for the same declaration produces the "slow only on iOS" case above. Measure both actuals.
+
+## 5. Compose Multiplatform UI
+
+When the UI is shared, the Compose performance rules in [android.md](android.md) apply unchanged — stability of parameters, deferred state reads, lazy layouts, `derivedStateOf`. What changes is measurement: the Android host gives you Layout Inspector recomposition counts and composition tracing; on iOS you have Instruments' time profile with Kotlin frames and no recomposition counter, so validate recomposition behaviour on Android and confirm the frame result on iOS.
+
+## 6. Regression detection in CI
+
+- Macrobenchmark on the Android host guards startup and frame time for the shared stack ([android.md](android.md)).
+- `XCTApplicationLaunchMetric` on the iOS host guards framework initialization cost ([ios.md](ios.md)).
+- `kotlinx-benchmark` on JVM and Native guards the shared algorithms themselves, and is the only gate that fails for a shared-code regression before either host notices.
+- Track the produced framework size and the Android AAB size per build; an `export(...)` added to the framework block can move both without any UI change.
+
+## Official documentation
+
+- Kotlin Multiplatform documentation: https://kotlinlang.org/docs/multiplatform.html
+- Kotlin/Native memory management: https://kotlinlang.org/docs/native-memory-manager.html
+- Swift/Objective-C interop: https://kotlinlang.org/docs/native-objc-interop.html
+- kotlinx-benchmark: https://github.com/Kotlin/kotlinx-benchmark
+- Compose Multiplatform: https://www.jetbrains.com/help/kotlin-multiplatform-dev/compose-multiplatform-and-jetpack-compose.html

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

@@ -0,0 +1,85 @@
+# Performance in React Native and Expo
+
+A React Native frame crosses three execution contexts: the **JavaScript thread** (your React code), the **native UI thread**, and — with the New Architecture — the shadow tree and Fabric's rendering pipeline. A slow app is slow in one of them, and the fix differs. Identify the thread first.
+
+Related material already in this plugin: [`mobile-rn/references/performance-release.md`](../../mobile-rn/references/performance-release.md).
+
+## Measure
+
+**Release build, physical device, Hermes enabled.** A Metro dev build carries the dev bundle, React strict-mode double renders, and the bridge dev listeners; its numbers are not the shipped app's.
+
+```bash
+npx react-native run-android --mode=release
+npx expo run:ios --configuration Release
+```
+
+| Question | Tool |
+|---|---|
+| Which React components render, and why | React DevTools Profiler (React Native DevTools), "Highlight updates" |
+| JavaScript CPU time | Hermes sampling profiler via React Native DevTools → Performance, or `.cpuprofile` capture |
+| Frame drops and native thread cost | The platform tools: Perfetto/system trace on Android, Instruments on iOS (see [android.md](android.md) and [ios.md](ios.md)) |
+| Startup cost breakdown | `performance.now()` marks around module require and first render; on Android, `adb shell am start -W` for the whole process |
+| Bundle size and what is in it | `npx react-native bundle --platform android --dev false --sourcemap-output bundle.map` then a source-map explorer; `npx expo export` for Expo |
+
+Instrument your own spans, and keep them in release behind a flag, so the same marks exist in the field:
+
+```js
+const start = performance.now();
+const parsed = parseOrders(payload);
+track('parse_orders_ms', performance.now() - start);
+```
+
+## The JavaScript thread
+
+- **Re-renders are the default problem.** A context value recreated each render, an inline object/array/function prop, or a parent that re-renders on every keystroke will cascade. `React.memo` on the child plus `useCallback`/`useMemo` on the props, or moving the state down so the parent is not involved at all.
+- **Selectors, not whole stores.** Subscribing to an entire Zustand/Redux store re-renders on every change; subscribe to the slice. With React Query/TanStack Query, `select` narrows what a component observes.
+- **Never block JS.** JSON parsing of a large payload, sorting thousands of rows, crypto, image manipulation — these freeze every touch handler. Move them to the native side, a worklet, or chunk them across frames with `InteractionManager.runAfterInteractions` and batched state updates.
+- **Text input and animation state** should not live in React state when they change per frame. Use `Animated` with `useNativeDriver: true`, or Reanimated shared values, so the animation runs on the UI thread and never touches JS.
+
+## Lists
+
+`FlatList`/`SectionList` are virtualized but still render through React. The props that matter:
+
+| Prop | Why |
+|---|---|
+| `keyExtractor` | Stable keys; without them React remounts rows on any change |
+| `getItemLayout` | Skips measurement, enables instant `scrollToIndex` — only valid for fixed-height rows |
+| `initialNumToRender` | Keep it to what a screen actually shows; the default renders more |
+| `maxToRenderPerBatch` / `updateCellsBatchingPeriod` | Trade blank space during fast scrolls against JS work per batch |
+| `windowSize` | How many screens are kept mounted around the viewport |
+| `removeClippedSubviews` | Detaches offscreen native views; helps on Android, test it — it has edge cases with absolute positioning |
+
+Memoize the row component (`React.memo`) and make `renderItem` stable. If the list is long and rows are heavy, `@shopify/flash-list` recycles native views instead of mounting new ones and is usually a larger win than tuning the props above.
+
+## Images
+
+- Size the remote image on the server or CDN; downloading a 3000 px JPEG for a 120 px avatar costs bandwidth, decode time and memory on every row.
+- `expo-image` (or `react-native-fast-image` on bare projects) adds disk/memory caching and progressive loading that the core `Image` does not.
+- Set explicit `width`/`height` so layout does not reflow when the image resolves.
+
+## Startup
+
+- **Enable Hermes** (the default in current React Native). Hermes precompiles to bytecode, which removes JS parse time at launch.
+- **Enable the New Architecture** where the project's dependencies support it: Fabric and TurboModules remove the asynchronous bridge serialization, and TurboModules load lazily instead of all at startup.
+- **Audit top-level requires.** Every module imported at the entry point is evaluated at launch. Lazy-import screens through the navigator's lazy options, and defer SDK initialization until after the first screen.
+- **Native side still counts.** Time to first JS frame includes the Android `Application.onCreate` and the iOS `didFinishLaunching` path; see the native references.
+
+## Bundle and app size
+
+- Inspect the release source map with a source-map explorer to find the heavy dependency. Moment/lodash-style full imports, duplicated polyfills and an icon font shipped whole are the usual entries.
+- On Android, enable Proguard/R8 for the release variant and ship an App Bundle. On iOS, check the App Store Connect size report per device variant.
+- Expo: `expo-updates` OTA payloads are downloaded by every user — size matters there too, and an update that grows the bundle grows every launch that has to apply it.
+
+## Regression detection in CI
+
+- Wrap a scripted journey in Detox or Maestro on a pinned device/emulator, capture the platform's frame data (see [android.md](android.md) and [ios.md](ios.md)), and compare percentiles against a baseline.
+- Assert bundle size in CI: build the release bundle, read its byte size, fail past a percentage delta.
+- `react-native-performance` exposes native startup marks (`nativeLaunchStart`, `runJsBundleStart/End`) as `PerformanceEntry`s, which gives a startup number you can assert on and also report from production.
+
+## Official documentation
+
+- React Native performance overview: https://reactnative.dev/docs/performance
+- Optimizing FlatList configuration: https://reactnative.dev/docs/optimizing-flatlist-configuration
+- Profiling with Hermes and React Native DevTools: https://reactnative.dev/docs/react-native-devtools
+- The New Architecture: https://reactnative.dev/architecture/landing-page
+- Expo performance guidance: https://docs.expo.dev/guides/analyzing-bundles/

package/skills/mobile-release/SKILL.md

@@ -13,23 +13,27 @@ One release process for every mobile stack. This file holds the process and what
 
 | Need | Read |
 |---|---|
+| Evidence-backed readiness audit, verdict and report | [references/readiness.md](references/readiness.md) |
 | 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) |
 | Kotlin Multiplatform shared module and both host apps | [references/kotlin-multiplatform.md](references/kotlin-multiplatform.md) |
+| In-app purchases and subscription lifecycle | [references/billing.md](references/billing.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`.
+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`, and production crash, error and release-health signals are in [mobile-observability](../mobile-observability/SKILL.md).
 
 ## 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).
+For readiness audits, first follow [the readiness contract](references/readiness.md): resolve each artifact identity, collect per-target evidence and apply its required gates and deterministic verdict helper.
+
+Check each item against the project, not against memory. For the readiness verdict, a missing artifact or unavailable check is **unknown**; use **fail** only for an observed failure with evidence. Record a source reference and next action for every gate.
 
 **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.
+- [ ] The version name follows the app's actual versioning scheme and is verified in the artifact and applicable CI overrides.
+- [ ] The build number satisfies the destination store’s numbering scope, verified against upload history: Android versionCode increases across tracks; iOS build numbers must be unused within the applicable version train. See the native references.
 - [ ] Android, iOS and any cross-platform manifest (`pubspec.yaml`, `app.json`) agree on the version.
 
 **Build quality**
@@ -47,25 +51,10 @@ Check each item against the project, not against memory. Mark each one **pass**,
 **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.
+- [ ] The release commit is tagged and the tag matches the version, when this is the project's release convention.
 
 ## 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.
-```
+Use the [readiness report and decision rules](references/readiness.md#report). Any failed or unknown required gate means **NO-GO**. **GO WITH RISKS** requires all gates to pass with explicitly documented non-blocking risks; **GO** requires no outstanding risks.
 
-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.
+Readiness audits inspect existing evidence without running builds/tests or modifying the app. Version bumps, tags, uploads and store changes follow the user's explicit execution scope and existing authorization.

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

@@ -0,0 +1,92 @@
+# In-app purchases and subscription lifecycle
+
+Applies to every stack. Billing bugs are expensive in a way other mobile bugs are not: a user who paid and did not receive the entitlement files a store complaint, a chargeback, and a one-star review, and the store holds *you* responsible for the reconciliation. The design that avoids this is the same on both platforms.
+
+## The rule everything follows from
+
+**The client never decides entitlement.** The app's job is to start a purchase and to hand the resulting receipt/token to your backend. The backend verifies it with the store's server, records the entitlement, and answers "what does this user own?". Every screen reads that answer.
+
+An app that grants a feature because a local purchase callback returned success can be defeated with a patched binary, and — more commonly — simply gets it wrong: the callback is missed because the app was killed mid-purchase, or the subscription was cancelled from the store's settings and the app never hears about it.
+
+```
+app ──buy──▶ store ──token/receipt──▶ app ──▶ your backend ──verify──▶ store server
+                                                   │
+ app ◀────── entitlement state ─────────────────────┘
+                                   ▲
+ store server ──server notifications──┘   (renewals, cancellations, refunds, billing retries)
+```
+
+## Server notifications are not optional
+
+The purchase callback covers the moment of purchase. Everything afterwards — a renewal at 3am, a cancellation, a refund, a failed payment entering a retry window, an upgrade, a family-sharing change — happens with the app closed and reaches you only through the store's server-to-server notifications:
+
+- **Google Play:** Real-time developer notifications (Pub/Sub), plus the Google Play Developer API for the authoritative subscription state.
+- **Apple:** App Store Server Notifications V2, plus the App Store Server API and signed transactions.
+
+Without them, a cancelled subscription keeps working until the app next happens to check, and a refunded purchase is never revoked. "We poll on app launch" is not equivalent: the user who cancelled may not open the app for weeks, and a refunded purchase must be revoked immediately.
+
+## The states to model
+
+A subscription is not a boolean. At minimum, entitlement must distinguish:
+
+| State | Behaviour |
+|---|---|
+| Active | Full access |
+| Active, cancelled (will not renew) | Full access until the period ends; a good place to ask why |
+| In a billing retry / grace period | **Keep access** and prompt the user to fix payment — revoking here loses users who would have paid |
+| On hold / suspended | Access revoked, recoverable if payment succeeds |
+| Paused (Android) | Access revoked, scheduled to resume |
+| Expired | No access |
+| Refunded / revoked | Access removed immediately, on the notification |
+| Trial / introductory offer | Active, but the eligibility rules differ and are per-account, not per-device |
+
+Treating anything other than "active" as "no access" is the standard way to break grace periods and lose revenue.
+
+## Purchase acknowledgement
+
+Both stores require the purchase to be consumed or acknowledged, and both **refund automatically** if you do not.
+
+- **Google Play:** a purchase not acknowledged (or consumed, for consumables) within three days is automatically refunded and revoked. Acknowledge only **after** your backend has recorded the entitlement, so a failure to record cannot produce a user who paid and owns nothing.
+- **Apple:** a transaction that is not finished is re-delivered on every launch. Finish it only after the entitlement is recorded — the re-delivery is the recovery mechanism, and finishing early discards it.
+
+The crash-in-the-middle case is the one to test: purchase succeeds, the app is killed before the backend call. On the next launch, the pending purchase must still be visible, sent, recorded and only then acknowledged.
+
+## Restore and multi-device
+
+- A **restore** path is mandatory on iOS (App Review rejects apps without one for non-consumables and subscriptions) and expected everywhere. It must be reachable without being logged in to *your* account if the purchase is tied to the store account.
+- Entitlement follows the **store account**, but your product follows **your** user account. Decide explicitly what happens when they disagree: one store account buying for two of your users, or one of your users signing in on a device with a different store account. This is where fraud and support tickets concentrate; the backend must own the mapping, and it must be enforced there.
+- Prices, currencies and availability come from the store per region. Never hard-code a price string; read it from the product query and display the localized formatted price the store returns.
+
+## Testing
+
+- **Google Play:** licence testers with test payment methods, internal testing track, and shortened subscription periods for renewal testing. Purchases must come from a build uploaded to a track with the same package name and signing key.
+- **Apple:** StoreKit Testing in Xcode (a local `.storekit` configuration file, with time acceleration and error injection — the only practical way to test renewals, billing retry and refunds) and Sandbox accounts for the end-to-end path with real server notifications.
+- Test on the backend, not only in the app: replay a server notification payload and assert the entitlement change. That is the code that actually decides access.
+- Cases worth a test each: purchase interrupted by process death; a refund notification; a cancellation followed by a resubscribe; a user who already owns the product buying again; an expired subscription that renews after a grace period.
+
+## Per-stack notes
+
+| Stack | Client library |
+|---|---|
+| Native Android | Google Play Billing Library — the deep migration and version material is in [`mobile-android/references/play.md`](../../mobile-android/references/play.md) |
+| Native iOS | StoreKit 2 (`Product`, `Transaction`, `Transaction.updates`, `Transaction.currentEntitlements`) — the `Transaction.updates` listener must be started at launch, or transactions completed outside the app are missed |
+| Flutter | `in_app_purchase` (federated, both stores) or a vendor SDK; the purchase stream must be subscribed before the first purchase and on every launch |
+| React Native / Expo | `react-native-iap`, `expo-in-app-purchases` where available, or a vendor SDK; Expo managed projects need a development build — in-app purchases do not work in Expo Go |
+| Kotlin Multiplatform | Billing is host-specific. Keep the entitlement *model* and the backend calls in `commonMain`, and the store client in each host |
+
+A subscription infrastructure vendor (RevenueCat, Adapty and similar) exists precisely because the server-side half above is substantial. Using one is a legitimate decision; it does not remove the need to decide entitlement on a server rather than in the app — it moves that server.
+
+## Store policy
+
+Both stores require that digital content consumed in the app is sold through their billing system, with a narrow and changing set of exceptions that vary by region and by court ruling. Alternative payment links have specific, enforced requirements. Before designing anything that bypasses store billing, read the current policy for the target markets — this is the most volatile area of store policy and the most expensive one to get wrong, since the penalty is removal.
+
+Release-time checks for the store submission itself are in [readiness.md](readiness.md).
+
+## Official documentation
+
+- Google Play Billing: https://developer.android.com/google/play/billing
+- Real-time developer notifications: https://developer.android.com/google/play/billing/getting-ready#configure-rtdn
+- Google Play Developer API, subscriptions: https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.subscriptionsv2
+- StoreKit: https://developer.apple.com/documentation/storekit
+- App Store Server Notifications V2: https://developer.apple.com/documentation/appstoreservernotifications
+- Testing in-app purchases with StoreKit Test: https://developer.apple.com/documentation/xcode/setting-up-storekit-testing-in-xcode

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

@@ -0,0 +1,88 @@
+# Evidence-backed readiness audit
+
+Use this contract for `/reis-mobile:release` and any readiness request. Other release tasks (store copy, pipeline implementation, deployment) retain their requested scope.
+
+## Release identity and target coverage
+
+For every intended artifact, record **app/package or bundle ID → flavor/scheme/environment → version/build → source revision → store/track → built artifact** with evidence. Inspect build overrides, CI parameters and artifact metadata; distinguish configured values from values verified in the binary. A directory or configured KMP target does not prove a shippable host exists. A shared framework is not an iOS app archive.
+
+Use detection as an inventory, then confirm actual Android/iOS hosts and requested destinations. Flutter, React Native/Expo and KMP shipping to both stores need separate gate rows for both artifacts. A prompt focusing on Android does not silently approve the iOS artifact. If the user explicitly limits the audit to one store, state the exclusion and do not issue a combined verdict. Expo can generate native folders: inspect app configuration and EAS profiles without running prebuild. Unknown targets or missing binaries stay unknown.
+
+Read the stack reference plus [android.md](android.md) and/or [ios.md](ios.md) for the actual destinations. KMP also needs [kotlin-multiplatform.md](kotlin-multiplatform.md). Do not substitute a shared-code test for a native host test.
+
+## Required gates
+
+Each target has these gate IDs. Every gate is **pass**, **fail**, or **unknown**, with a source reference and an exact next action/owner when unresolved. A failed check needs observed failure evidence; unavailable evidence is unknown. A local config file proves configuration only, not an executed check, successful upload, current console state or store approval.
+
+| ID | Evidence required |
+|---|---|
+| `identity` | All identity fields above, including artifact provenance and agreement with the intended source revision. Record dirty/untracked source and unknown CI overrides. |
+| `build` | Successful release build log/CI job for this revision and artifact, with the actual variant and production environment. A workflow YAML or debug build is insufficient. |
+| `tests` | Actual results for applicable unit/integration/device checks on this revision, with counts and skipped/failed checks. Resolve required suites from project policy and the changed behavior. |
+| `analysis` | Actual lint/static-analysis results for the release revision and applicable targets. Missing tools or logs are unknown, not pass. |
+| `version` | Artifact version/build matched to source/CI inputs and store upload history, applying the platform's numbering scope. Verify the previous release using the project's convention, not merely the closest tag. See [Android versioning](https://developer.android.com/studio/publish/versioning) and [Apple's build identification](https://developer.apple.com/help/app-store-connect/reference/app-information/app-information). |
+| `signing` | Signed artifact verification, intended distribution identity, and applicable entitlements/profile or upload-key setup. Never read or print private keys, passwords or tokens. |
+| `symbols` | Matching R8/native symbols, dSYMs, Dart debug info and/or JS source maps, with archive/upload evidence as required by the app. Verify build IDs/UUIDs or provenance. |
+| `store` | Current official requirement URL and access date, target SDK/toolchain evidence, and any account/track eligibility or review state needed for the intended action. Unavailable portal confirmation stays unknown. |
+| `privacy` | Permissions/data collection and third-party SDK inventory reconciled with manifests, usage descriptions, privacy policy and store disclosures. Local declarations alone do not prove console forms agree. |
+| `listing` | Required locales, release notes/screenshots/metadata, and reviewer access where applicable. Account secrets never enter the report. |
+| `rollout` | Owner, stages, monitoring signals and halt thresholds, plus a verified halt/kill-switch/higher-build hotfix path. Mark proposed thresholds as proposals until accepted. A halt does not revert installed binaries. See [Play staged rollouts](https://support.google.com/googleplay/android-developer/answer/6346149) and [Apple phased releases](https://developer.apple.com/help/app-store-connect/update-your-app/release-a-version-update-in-phases); confirm their current behavior before planning recovery. |
+
+If a requirement within a gate does not apply (for example no R8 mapping when R8 is disabled), cite evidence and the reason; do not omit the gate. A gate can pass with a justified non-applicability statement only after verifying all of its applicable requirements. No gate is waived simply to obtain GO.
+
+Current store rules must be checked against official sources, such as [Google Play target API requirements](https://support.google.com/googleplay/android-developer/answer/11926878) and [Apple's upcoming requirements](https://developer.apple.com/news/upcoming-requirements/). State the exact unresolved confirmation if browsing or store access is unavailable. Do not reuse a date or minimum SDK from memory.
+
+## Decision rule
+
+- **NO-GO:** any required gate fails, is unknown, is missing, or has no supporting evidence. Missing targets also block. Distinguish observed failures from missing verification.
+- **GO WITH RISKS:** every required gate passes and explicitly documented non-blocking risks remain. A risk cannot waive an unresolved required gate.
+- **GO:** every required gate passes and there are no outstanding risks.
+
+The combined verdict covers every included target; one platform passing cannot approve another.
+
+Use [the verdict helper](../scripts/verdict.mjs) to check the report's decision. It validates completeness and consistency, **not the truth of the evidence or whether a risk is truly non-blocking**. Supply JSON on stdin using a quoted heredoc delimiter (no shell expansion):
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/skills/mobile-release/scripts/verdict.mjs" <<'REIS_RELEASE_EVIDENCE'
+{"targets":[{"target":"android:production","gates":[{"id":"build","status":"unknown","evidence":[],"nextAction":"Release owner: provide the release CI job and artifact for the requested revision."}]}],"risks":[]}
+REIS_RELEASE_EVIDENCE
+```
+
+This intentionally incomplete example returns NO-GO. Replace it with the actual targets and all 11 gates; use one target name per artifact/store/track combination. `evidence` is an array of non-empty references (`file:line`, command plus result/log, artifact metadata, CI URL or dated portal confirmation). `nextAction` explains what resolves each fail/unknown. `risks` is an optional array of objects with `id`, `description`, evidence references, `mitigation` and `owner`; include only evidenced issues whose impact truly does not block the release. The auditor is responsible for that classification. Do not place secrets in JSON. Choose a heredoc delimiter absent from the payload. The helper writes only stdout; exit 0 means evaluation succeeded, **not** GO. Malformed input exits 1 and must be corrected before reporting a verdict. Preserve returned unknowns and blockers; do not manually upgrade the result.
+
+## Report
+
+Write in the requested language; keep gate IDs and verdict identifiers stable.
+
+```markdown
+## Release readiness — <app> <version/build>
+Verdict: GO | GO WITH RISKS | NO-GO
+Scope: <included artifacts/stores/tracks and explicit exclusions>
+
+### Release identity
+| Target | App ID | Variant/environment | Version/build | Revision | Store/track | Artifact | Evidence |
+|---|---|---|---|---|---|---|---|
+
+### Gates
+| Target | Gate | Status | Evidence / missing confirmation | Next action / owner |
+|---|---|---|---|---|
+
+### Blockers
+Observed failures and unverified required gates, separately identified.
+
+### Risks
+Non-blocking risks, mitigation and owner.
+
+### Unknowns
+Missing evidence and the exact external confirmation needed.
+
+### Next actions
+Ordered resolution steps; commands prepared versus commands actually executed.
+
+### Rollout and rollback
+Stages, signals, thresholds, owner and recovery for users already updated.
+```
+
+## Read-only boundary
+
+A readiness audit inspects files, existing artifacts/logs and accessible CI/store records. Do not build, run tests, install dependencies, execute Fastlane lanes, prebuild, bump versions, tag, upload, change signing or store settings by default. Inspect scripts before considering execution. Prepare exact commands for missing checks and label them **not executed**. An explicit request to execute a release authorizes only that requested scope; reuse existing authorization, and complete reviewable preparation before any additional approval that is actually needed. Never change an app merely to make the audit green.

package/skills/mobile-release/scripts/verdict.mjs

@@ -0,0 +1,59 @@
+import { realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+
+const REQUIRED_GATES = ['identity', 'build', 'tests', 'analysis', 'version', 'signing', 'symbols', 'store', 'privacy', 'listing', 'rollout'];
+const text = (value) => typeof value === 'string' && value.trim().length > 0;
+
+/** Validate decision consistency. Evidence truth and applicability remain the auditor's job. */
+export function evaluateReadiness(report) {
+  if (!report || !Array.isArray(report.targets)) throw new Error('targets must be an array');
+  const risks = report.risks ?? [];
+  if (!Array.isArray(risks) || !risks.every((risk) => risk && text(risk.id) && text(risk.description)
+    && Array.isArray(risk.evidence) && risk.evidence.length > 0 && risk.evidence.every(text)
+    && text(risk.mitigation) && text(risk.owner))) {
+    throw new Error('risks must include id, description, evidence, mitigation and owner');
+  }
+  const targets = new Set();
+  const gates = [];
+  for (const item of report.targets) {
+    if (!item || !text(item.target) || !Array.isArray(item.gates)) throw new Error('each target needs a name and gates array');
+    if (targets.has(item.target)) throw new Error(`duplicate target: ${item.target}`);
+    targets.add(item.target);
+    const byId = new Map();
+    for (const gate of item.gates) {
+      if (!gate || !REQUIRED_GATES.includes(gate.id)) throw new Error('unknown gate id');
+      if (byId.has(gate.id)) throw new Error(`duplicate gate: ${gate.id}`);
+      if (!['pass', 'fail', 'unknown'].includes(gate.status)) throw new Error(`invalid status for ${gate.id}`);
+      if (gate.evidence !== undefined && (!Array.isArray(gate.evidence) || !gate.evidence.every((value) => typeof value === 'string'))) {
+        throw new Error(`evidence for ${gate.id} must be a string array`);
+      }
+      byId.set(gate.id, gate);
+    }
+    for (const id of REQUIRED_GATES) {
+      const supplied = byId.get(id);
+      const evidence = (supplied?.evidence ?? []).filter(text);
+      const status = !supplied || (supplied.status !== 'unknown' && !evidence.length) ? 'unknown' : supplied.status;
+      gates.push({
+        target: item.target, id, status, evidence,
+        nextAction: status === 'pass' ? 'None.' : (text(supplied?.nextAction) && supplied.nextAction !== 'None.'
+          ? supplied.nextAction : `Provide and verify ${id} evidence for ${item.target}.`),
+      });
+    }
+  }
+  if (!targets.size) gates.push({ target: 'unresolved', id: 'targets', status: 'unknown', evidence: [], nextAction: 'Identify the app artifacts and intended store targets.' });
+  const blockers = gates.filter((gate) => gate.status !== 'pass');
+  const unknowns = gates.filter((gate) => gate.status === 'unknown');
+  return { verdict: blockers.length ? 'NO-GO' : risks.length ? 'GO WITH RISKS' : 'GO', gates, blockers, risks, unknowns };
+}
+
+// stdin avoids creating an audit file in the inspected project. Exit zero means evaluated, not GO.
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  try {
+    let input = '';
+    for await (const chunk of process.stdin) input += chunk;
+    console.log(JSON.stringify(evaluateReadiness(JSON.parse(input)), null, 2));
+  } catch (error) {
+    console.error(`readiness: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/skills/mobile-security/SKILL.md

@@ -18,6 +18,7 @@ Organized by the OWASP MASVS categories. Apply the general checks below, then th
 | Native iOS (Swift/Objective-C), or `ios/` in any app | [references/ios.md](references/ios.md) |
 | React Native or Expo | [references/react-native.md](references/react-native.md) |
 | Kotlin Multiplatform shared code and platform implementations | [references/kotlin-multiplatform.md](references/kotlin-multiplatform.md) |
+| OAuth 2.0 / OIDC login, PKCE, tokens and biometric gating, on any stack | [references/auth.md](references/auth.md) |
 
 Firebase-specific protection (security rules, App Check) is covered by `mobile-firebase`.
 
@@ -44,6 +45,8 @@ Every finding needs evidence in the code or configuration at `file:line`. Severi
 - [ ] Sessions without expiration, or refresh tokens never invalidated on logout.
 - [ ] Biometrics used only as a local boolean, without unlocking a key in the Keychain or Keystore.
 
+For anything involving a login flow — OAuth 2.0, OpenID Connect, PKCE, redirect URIs, token rotation or biometric-gated keys — read [references/auth.md](references/auth.md) before reviewing the stack reference.
+
 **MASVS-NETWORK**
 - [ ] `http://` URLs for APIs.
 - [ ] Certificate validation disabled or overridden to accept everything.