wize-dev-kit 0.1.4 → 0.1.5

package/src/app-overlay/playbooks/mobile-perf-budgets.md

@@ -0,0 +1,145 @@
+---
+playbook: mobile-perf-budgets
+owner: wize-agent-test-architect   # Hawkeye (with Tony for platform tuning)
+applies_when: app-overlay active
+status: ready
+---
+
+# Mobile Performance Budgets — Hawkeye Playbook
+
+Mobile users measure your app in milliseconds and megabytes. Budgets are how you protect both.
+
+## 1. The numbers that matter
+
+| Metric | Good | Needs work | Poor |
+|---|---|---|---|
+| **Cold start** (launch → first frame) | < 1.5s | 1.5–2.5s | > 2.5s |
+| **Warm start** | < 0.8s | 0.8–1.5s | > 1.5s |
+| **Time to interactive** (TTI) | < 2.0s | 2.0–3.5s | > 3.5s |
+| **Frame rate** (sustained) | 60 fps stable | drops < 5/sec | drops > 5/sec |
+| **Jank** (frames > 16ms) | < 0.5% | 0.5–2% | > 2% |
+| **App size** (download) | < 50 MB | 50–150 MB | > 150 MB |
+| **App size** (installed) | < 200 MB | 200–500 MB | > 500 MB |
+| **Memory** (steady-state) | < 150 MB | 150–300 MB | > 300 MB |
+| **Battery drain** (per hour, foreground) | < 5% | 5–10% | > 10% |
+
+Targets for **mid-range phones, not your flagship**. Hawkeye runs benchmarks on the device matrix (see `device-matrix.md`).
+
+## 2. App size budget
+
+### Per-platform ceiling
+
+- iOS App Store: 200 MB OTA download cellular ceiling. Plan for **< 150 MB** to leave headroom.
+- Google Play: 150 MB APK ceiling; use App Bundle splits. Plan for **< 30 MB** initial download.
+
+### Where size goes
+
+Audit on every release:
+
+| Slice | Tool |
+|---|---|
+| RN / Expo JS bundle | `metro-visualizer`, `react-native-bundle-visualizer` |
+| Native deps | Xcode Linker map / Android Studio APK Analyzer |
+| Assets (images, fonts, video) | Compare to design tokens — anything unused? |
+| Third-party SDKs | Each SDK > 1 MB needs a written justification |
+
+### Reductions that work
+
+1. **Vector over bitmap** wherever the design allows (PDF for iOS asset catalog, VectorDrawable for Android).
+2. **WebP/AVIF over PNG** for bitmaps.
+3. **Subset fonts**; ship one weight, derive others via OS faux-bold when acceptable.
+4. **Tree-shake JS bundle** (Hermes, ProGuard/R8). Verify with the visualizer.
+5. **App Thinning** (iOS) and **App Bundle splits** (Android) so each user downloads only their architecture/density.
+6. **On-demand resources** (iOS) / **Play Asset Delivery** (Android) for content not needed at launch.
+
+## 3. Cold start
+
+Cold start is dominated by:
+
+1. **Process launch** — Apple/Google control, but linking and dyld matter (fewer, smaller binaries help).
+2. **Framework init** — every SDK initialized in `application(_:didFinishLaunching)` adds to it. Defer non-essential to first-screen-rendered.
+3. **First view render** — keep the launch screen → first interactive screen path empty of heavy work.
+
+### Patterns
+
+- Lazy-init analytics, crash reporting, ad SDKs, A/B testing — after first frame.
+- Pre-render the first screen's skeleton; populate from cache; refresh in background.
+- For RN/Expo: enable **Hermes** + **bundleAssetName splitting**.
+- For Android: keep Application.onCreate empty; init via lifecycle observer.
+
+### Measurement
+
+| Platform | Tool |
+|---|---|
+| iOS | Xcode Instruments → "App Launch", Time Profiler |
+| Android | Macrobenchmark library (Jetpack) for ColdStartup. `adb shell am start -W` for rough numbers. |
+| RN | `Performance.now()` markers + Flipper Perf plugin. |
+
+## 4. Frame rate & jank
+
+60 fps = 16.67ms/frame. 120 fps target on ProMotion / 90 Hz Androids = 8.33ms.
+
+### Common culprits
+
+- **Layout thrashing** — measuring layout inside scroll/animation handlers.
+- **Image decoding on main thread** — decode async, cache decoded.
+- **Synchronous bridge calls (RN)** — batch updates, use native modules.
+- **Heavy `onLayout` / `LaunchedEffect` on each render**.
+- **Re-rendering large lists** — use `FlatList` with `keyExtractor` + `getItemLayout`, or `LazyColumn`.
+
+### Measurement
+
+- iOS: Instruments → Core Animation → FPS.
+- Android: GPU profiling overlay + Macrobenchmark FrameTimingMetric.
+- RN: Flipper Perf, `react-native-performance`.
+
+## 5. Memory
+
+- Aim for steady-state **< 150 MB** on mid-range.
+- Audit images caches; cap at `min(50 MB, 100 thumbnails)`.
+- Release video / audio assets on pause.
+- Watch out for retain cycles (iOS) and Activity / Fragment leaks (Android) — use LeakCanary / Xcode memory graph.
+
+## 6. Battery
+
+- Don't poll. Use OS push (silent push), BLE listeners (low-power), location updates with low frequency.
+- Background tasks: respect the OS budget (BGTaskScheduler / WorkManager).
+- Avoid wake-locks; trade off freshness for energy.
+
+## 7. Network
+
+- HTTP/2 minimum; HTTP/3 where supported.
+- gzip / brotli on responses.
+- Aggressive cache headers; SWR (stale-while-revalidate) pattern for read-heavy data.
+- Image CDN with on-the-fly format/quality negotiation.
+- Don't fan out 30 small requests; batch with GraphQL or a dedicated endpoint.
+
+## 8. Build-time enforcement
+
+| Check | Tool |
+|---|---|
+| Bundle size growth > 5% per release | `danger-js` rule on the bundle visualizer output. |
+| Cold start regression > 10% | Macrobenchmark in CI; fail PR on threshold. |
+| Frame timing | Compose Compiler metrics for Android; Hermes profiler for RN. |
+
+## 9. Field measurement
+
+- iOS: `MetricKit` for power, hangs, scroll latency.
+- Android: Firebase Performance + Macrobenchmark.
+- Cross-platform: Sentry Performance, NewRelic Mobile.
+
+Look at **p75** and **p90** in field data. The user is the 75th percentile, not the 50th.
+
+## 10. Hawkeye's gate inputs
+
+For each epic NFR review (`tea/nfr/{epic}.md`):
+
+- Cold start (mid-range device).
+- Bundle size delta vs last release.
+- Steady-state memory.
+- Critical-flow frame rate (one E2E run with FPS capture).
+- Battery (instrumented test with consistent workload).
+
+## 11. Hand-off
+
+Fury sets the targets in `nfr-principles.md`. Tony picks the stack respecting the targets. Mantis designs without animation excess. Shuri implements. Hawkeye verifies on each release; regressions hit Concerns/Fail at the gate.

package/src/app-overlay/playbooks/permissions-ux.md

@@ -0,0 +1,147 @@
+---
+playbook: permissions-ux
+owner: wize-agent-ux-designer   # Mantis (paired with Pepper on copy)
+applies_when: app-overlay active
+status: ready
+---
+
+# Permissions UX — Mantis Playbook
+
+The system dialog you can't customize. Everything *around* it is yours. Use it well — denied permissions are usually a UX failure, not a privacy choice.
+
+## 1. The four states for every permission
+
+1. **Not determined** — system never asked.
+2. **Granted** — you can use the feature.
+3. **Denied** — user said no; system won't re-prompt; only Settings can flip.
+4. **Restricted / Limited** — partial access (iOS photos limited library; Android approximate location).
+
+Design **all four** for every permission your app uses.
+
+## 2. The "pre-flight" pattern
+
+Never trigger the system prompt as the first thing the user sees. Always:
+
+1. **In-context trigger.** The user tries a feature that needs the permission.
+2. **Mantis pre-flight UI.** A custom screen/sheet explains *why*, *what*, *what happens if no*.
+3. **System prompt.** User decides.
+4. **Outcome path.** Granted → feature works. Denied → degraded mode; offer Settings deep-link.
+
+```
+[user taps "Add photo"]
+   ↓
+┌────────────────────────────────────┐
+│ Why we need your photos            │
+│ To attach an image to your post.   │
+│ We never upload without confirm.   │
+│                                    │
+│ [ Not now ]      [ Continue ]      │
+└────────────────────────────────────┘
+   ↓ Continue
+[system prompt — uneditable]
+   ↓
+Granted → flow continues
+Denied → fallback UI + "Open Settings"
+```
+
+## 3. Per-permission guidance
+
+### Camera & microphone
+
+- Ask only when the user starts a recording/capture action.
+- Pre-flight explains what's recorded, stored, and uploaded.
+- If denied: show a permanent banner with "Open Settings" inside the feature; don't auto-re-prompt.
+
+### Photo library
+
+- iOS 14+: **Limited Library is the default**. Embrace it — show a "Manage" button to add more later.
+- Android 13+: granular media access (images / video / audio).
+- Don't ask for full library if you only need one picker — use `PHPickerViewController` / `Photo Picker` which need **no permission** at all.
+
+### Location
+
+- Pre-flight has a *map screenshot* showing the precision and the purpose ("nearby restaurants" vs "your route").
+- Android 12+: approximate location is the default. Justify precise.
+- Background location: **only** if the feature truly needs it (delivery, fitness route). Otherwise foreground-only.
+
+### Notifications
+
+- Don't ask at launch. Ask the first time a notification would actually be useful.
+- Pre-flight: list the categories you'll use (mention, reminder, marketing). Tie each to a setting in-app.
+- Provide per-category opt-in inside the app — match to OS notification channels (Android) / authorization options (iOS).
+
+### Contacts / Calendar / Reminders
+
+- High-friction permission; only when essential.
+- If you just need a single contact, use the system picker — **no permission required**.
+
+### Bluetooth / Local Network
+
+- iOS: bluetooth-LE for peripherals only; Local Network for Bonjour discovery — both prompt.
+- Pre-flight should explain it's for nearby devices, not internet access.
+
+### Health / Motion (iOS)
+
+- HealthKit asks per data type. Group requests by user-task, not by data field.
+- Motion: pre-flight explains it's used for step-count or activity recognition only.
+
+### Tracking (App Tracking Transparency, iOS)
+
+- The system prompt is required if you track across other apps/sites.
+- Apple disallows incentivizing the choice; respect it.
+
+## 4. Copy template (Pepper helps phrase)
+
+Pre-flight title: **"Why we need [permission]"**.
+One-line value statement.
+One-line "what we will not do" (privacy promise).
+Two buttons: **Not now** (no permission requested) and **Continue** (triggers system prompt).
+
+Avoid: "Allow Camera Access" (system already says that).
+
+## 5. Denied state UI
+
+Never silently fail. Show:
+- The state badge ("Camera access off").
+- A one-line reason.
+- A direct **"Open Settings"** button.
+
+```swift
+// iOS
+if let url = URL(string: UIApplication.openSettingsURLString) {
+  UIApplication.shared.open(url)
+}
+```
+
+```kotlin
+// Android
+startActivity(Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS, Uri.fromParts("package", packageName, null)))
+```
+
+## 6. Settings mirror inside the app
+
+Every permission you request has a corresponding row in **Settings → Permissions** inside the app. Mirrors the OS state, with the same Open Settings deep-link. This is the user's escape hatch.
+
+## 7. Background work
+
+Some Android/iOS background permissions (location, background refresh, BLE in background) require user education and energy disclosure. Pre-flight mentions battery cost explicitly.
+
+## 8. Don'ts
+
+- Multiple prompts on first launch ("camera, mic, location, notifications" in a row). Cardinal sin.
+- Re-asking immediately after denial — many OSes block; users get frustrated.
+- Using "we can't function without this" as the reason — design for the denied state.
+- Pre-flight that already says "tap Allow" — the system dialog handles that. Just convince them *why*.
+- Modal blocking UI when the user denies. The feature degrades; the app doesn't.
+
+## 9. Audit list
+
+For every release, Hawkeye verifies in `tea-design.md`:
+- Every permission has a pre-flight UI.
+- Every permission has a denied-state UI.
+- Every permission has a Settings deep-link.
+- App functions (degraded) without each non-essential permission.
+
+## 10. Hand-off
+
+Mantis owns flow + copy strings. Pepper polishes copy. Tony picks the entitlement / manifest. Shuri implements; Hawkeye walks the four states (not-asked / granted / denied / limited) per permission.

package/src/app-overlay/playbooks/touch-targets-and-gestures.md

@@ -0,0 +1,127 @@
+---
+playbook: touch-targets-and-gestures
+owner: wize-agent-ux-designer   # Mantis
+applies_when: app-overlay active
+status: ready
+---
+
+# Touch Targets & Gestures — Mantis Playbook
+
+The thumb is the cursor. Design every screen around how it actually reaches the controls.
+
+## 1. Minimum touch target sizes
+
+| Platform | Minimum | Recommended primary |
+|---|---|---|
+| **iOS** (HIG) | 44×44 pt | 48×48+ pt for primary CTAs |
+| **Android** (Material) | 48×48 dp | 56×56 dp for FABs |
+| **Web** (WCAG 2.5.8) | 24×24 CSS px | 44×44 CSS px for primary |
+
+If a visible glyph must be smaller (icon-only toolbar), expand the **hit area** via padding or `hitSlop` — the visual icon stays small but the touch is large.
+
+```swift
+// SwiftUI hit area
+Button { /* */ } label: { Image(systemName: "star") }
+  .contentShape(Rectangle())
+  .frame(minWidth: 44, minHeight: 44)
+```
+
+```kotlin
+// Compose
+Modifier.minimumInteractiveComponentSize() // ≥ 48dp
+```
+
+```jsx
+// React Native
+<Pressable hitSlop={{ top: 10, bottom: 10, left: 10, right: 10 }}>...</Pressable>
+```
+
+## 2. Spacing between adjacent targets
+
+- **≥ 8 dp/pt** between adjacent interactive elements.
+- Bottom row of nav must clear the home indicator (iOS) / gesture region (Android).
+
+## 3. Thumb reach zones (one-handed use)
+
+Three zones, on a 6.1" phone:
+
+| Zone | Region | Use for |
+|---|---|---|
+| **Easy** | Bottom 1/3 | Primary actions, nav. |
+| **OK** | Middle 1/3 | Secondary, content tap. |
+| **Hard** | Top 1/3 | Status, branding, low-frequency. |
+
+Put destructive or rarely-used controls in the **Hard** zone. Put the primary CTA in **Easy**.
+
+## 4. Standard gestures (use the system's vocabulary)
+
+| Gesture | Reserved meaning |
+|---|---|
+| **Tap** | Default action. |
+| **Long press** | Reveal secondary actions / context menu. Optional path — never the only one. |
+| **Swipe left/right on row** | Quick actions (archive, delete). |
+| **Swipe down on modal** | Dismiss. |
+| **Pull down on list** | Refresh. |
+| **Pinch** | Zoom (content). |
+| **Two-finger drag** | Multi-select (mac/iPad). |
+| **Edge swipe (iOS)** | Back navigation. |
+| **System back gesture (Android)** | Back; **don't** intercept lightly. |
+
+## 5. Custom gestures — pick wisely
+
+If you must invent a gesture:
+
+1. **Don't make it the only path.** Pair with a visible tap affordance.
+2. **Onboard once.** Show the gesture on first launch; never again.
+3. **Make it cancellable.** Mid-gesture the user must be able to abort.
+4. **Don't fight system gestures.** Edge swipes on iOS = back; you'll lose.
+5. **Test with system Voice Control** (iOS) / Switch Access (Android) — discoverable to users who can't gesture.
+
+## 6. Multi-touch caveats
+
+- iOS: `MultipleTouchEnabled = true` per view; default is single.
+- Android: track pointer IDs on every event; don't assume one finger.
+- Two-finger gestures (pinch, rotate) need an alternative for users with motor limitations — usually a button.
+
+## 7. Drag-and-drop
+
+| Platform | Native |
+|---|---|
+| iOS | `UIDragInteraction` / SwiftUI `.draggable + .dropDestination` |
+| Android | `View.startDragAndDrop` / Compose `dragGestures` |
+| React Native | community lib (e.g., `react-native-draggable-flatlist`) |
+
+Drag-and-drop must:
+- Show a visible drag preview.
+- Highlight valid drop targets.
+- Support keyboard equivalent (or selection + "Move to…") for accessibility (WCAG 2.5.7).
+
+## 8. Haptics
+
+| Use | Pattern |
+|---|---|
+| Successful confirmation | Light impact (.light / `VibrationEffect.EFFECT_TICK`) |
+| Failure / invalid | Notification error / double tick |
+| Long-press triggered | Selection change |
+| Pull-to-refresh release | Light impact |
+
+Haptics are noise without a system event behind them. Don't trigger them on every tap.
+
+## 9. Reduce Motion / Reduce Transparency
+
+Reduce gesture-driven motion: replace swipe-to-reveal animations with simple cross-fades. Detect with:
+
+- iOS: `UIAccessibility.isReduceMotionEnabled`
+- Android: `Settings.Global.TRANSITION_ANIMATION_SCALE`
+
+## 10. Don'ts
+
+- Targets smaller than the platform minimum, even if "the icon is small".
+- Hover-only affordances (no hover on touch).
+- Gestures that conflict with system gestures (edge swipes, pull-from-top).
+- Long-press-only access to a critical feature.
+- "Discover this gesture by trial" — onboarding it costs less than the support tickets.
+
+## 11. Hand-off
+
+Mantis annotates every interactive element with: `hit area`, `gesture`, `haptic`, `state on disabled`. Shuri implements; Hawkeye verifies hit-area sizes in `tea-design.md` using device-pixel measurements.

package/src/app-overlay/stack-catalog.md

@@ -0,0 +1,178 @@
+---
+catalog: app-stack
+owner: wize-agent-architect   # Tony (with Fury on strategy)
+applies_when: app-overlay active
+status: ready
+---
+
+# App Stack Catalog — Tony's Reference
+
+The mobile stack decision is harder to reverse than the web one. Pick deliberately. This catalog lists each option with the **trade-off honest enough that you don't relitigate it in six months**.
+
+## 1. Decision dimensions
+
+Order them: **distribution → team → performance → reuse**.
+
+1. **Distribution** — App Store + Play Store only? B2B enterprise (TestFlight/internal)? Sideload?
+2. **Team** — primary skill set: web, native (Swift/Kotlin), Flutter (Dart)?
+3. **Performance** — animation-heavy / camera / AR / ML on-device? Or list + form?
+4. **Code reuse** — does a web app share business logic? How much?
+5. **Hiring tail** — what skill set will be easy to hire from in 2 years?
+
+## 2. Frameworks
+
+### React Native + Expo (managed workflow)
+
+| | |
+|---|---|
+| **Pick when** | Team is JS/TS-strong; cross-platform with one codebase + fast iteration. |
+| **Strengths** | EAS Build/Update/Submit; OTA updates; same team can ship the web product. |
+| **Costs** | Native modules sometimes need ejecting; SDK lag for very-new OS features. |
+| **Perf ceiling** | 60 fps for typical UIs; deep native work requires bridging or custom modules. |
+| **Best for** | Most cross-platform B2C apps with shared web team. |
+
+### React Native (bare / community CLI)
+
+| | |
+|---|---|
+| **Pick when** | Need native modules Expo doesn't ship + full control over Xcode/Gradle. |
+| **Strengths** | Maximum flexibility, integrate any SDK. |
+| **Costs** | Maintain native build configs; lose EAS conveniences (unless self-hosted). |
+| **Best for** | Apps with heavy custom native (BLE, advanced camera, ML, payments SDKs). |
+
+### Flutter
+
+| | |
+|---|---|
+| **Pick when** | Pixel-perfect cross-platform UI with custom motion; team is Dart-OK. |
+| **Strengths** | Skia rendering = identical UI across platforms; great motion; mature widgets. |
+| **Costs** | Dart hiring pool smaller; web/desktop story uneven; non-trivial native interop. |
+| **Perf ceiling** | High — Skia bypasses platform UI thread for many cases. |
+| **Best for** | Animation-heavy or brand-precise apps; shop already on Flutter. |
+
+### SwiftUI (native iOS)
+
+| | |
+|---|---|
+| **Pick when** | iOS-only or iOS-primary; want platform-best UX and access to newest APIs day-one. |
+| **Strengths** | Best feel, best APIs (Live Activities, WidgetKit, Vision, etc.). |
+| **Costs** | Min iOS support shifts upward; doesn't help Android at all. |
+| **Best for** | Premium iOS-led products; products with deep Apple-ecosystem integrations. |
+
+### Jetpack Compose (native Android)
+
+| | |
+|---|---|
+| **Pick when** | Android-only or Android-primary; want first-party Material 3 + platform integrations. |
+| **Strengths** | Declarative + modern; Compose Multiplatform offers iOS path now. |
+| **Costs** | Doesn't help iOS unless you commit to CMP. |
+| **Best for** | Android-led products. |
+
+### Compose Multiplatform (KMP + Compose)
+
+| | |
+|---|---|
+| **Pick when** | Kotlin team, want shared business logic + shared UI. |
+| **Strengths** | Code reuse high; same Kotlin stack on backend possible. |
+| **Costs** | Newer; iOS UI parity caveats; ecosystem younger than RN/Flutter. |
+| **Best for** | Kotlin-fluent teams comfortable with bleeding edge. |
+
+### Capacitor / Ionic (hybrid)
+
+| | |
+|---|---|
+| **Pick when** | Mostly-web app needs a thin native wrapper for store distribution. |
+| **Strengths** | Reuse the existing web codebase 1:1; fastest path to store. |
+| **Costs** | Performance ceiling lower than RN/Flutter; UI feel rarely passes "native". |
+| **Best for** | Internal tools, content apps, MVPs where store presence > performance. |
+
+### Native + KMP shared logic
+
+| | |
+|---|---|
+| **Pick when** | Want native UIs (SwiftUI + Compose) + shared business logic in Kotlin. |
+| **Strengths** | Best-of-both: native UX + shared domain. |
+| **Costs** | Two UIs to maintain; KMP infra to manage. |
+| **Best for** | Mature teams with enough size to maintain both fronts. |
+
+## 3. Build & release
+
+| Choice | Pick when |
+|---|---|
+| **Expo EAS** (Build, Submit, Update) | RN+Expo project, want a turn-key pipeline. |
+| **Fastlane** | Native or RN bare, want scriptable lanes; established tool. |
+| **Bitrise** | Cloud CI specialized for mobile, integrates with EAS/Fastlane. |
+| **GitHub Actions + matrices** | Already on GitHub, custom needs, fewer mobile-specific shortcuts. |
+| **App Center (sunset path)** | Legacy; migrate off. |
+
+## 4. Auth
+
+| Choice | Pick when |
+|---|---|
+| **Firebase Auth** | RN/Flutter; want SDK on every platform, simple onboarding. |
+| **Auth0 / Clerk / WorkOS** | Enterprise SSO needs. |
+| **Sign in with Apple / Google / Microsoft** | Required (Apple) when other social auth is offered; minimal friction. |
+| **Custom OAuth via Supabase / your backend** | Want full control; team has experience. |
+
+## 5. Data / sync
+
+| Choice | Pick when |
+|---|---|
+| **WatermelonDB** (RN) | Offline-first apps with large local datasets. |
+| **Realm / Atlas Sync** | Need bi-di sync to MongoDB. |
+| **PowerSync / Replicache / Triplit** | Modern offline + sync over Postgres / custom. |
+| **TanStack Query + AsyncStorage / EncryptedStorage** | Most apps — fetch + cache. |
+| **GraphQL + Apollo** | Single API for many clients (web + mobile share schema). |
+
+## 6. State management
+
+| Choice | Pick when |
+|---|---|
+| **Zustand / Jotai** | Small global state; RN |
+| **TanStack Query** | Server-derived data dominates. |
+| **MobX-State-Tree** | Bigger app, opinionated structure. |
+| **Recoil** | (Niche; less active recently — verify.) |
+| **Provider / Riverpod** | Flutter. |
+
+## 7. Storage
+
+- **AsyncStorage** (RN) — small KV only; not for sensitive data.
+- **EncryptedStorage** / **react-native-keychain** — tokens, secrets.
+- **MMKV** — fast KV; sub-ms reads; replaces AsyncStorage for perf-critical paths.
+- **SQLite (Op-SQLite / better-sqlite)** — relational on device.
+- **Realm** — object DB with sync.
+
+## 8. Push notifications
+
+| Choice | Pick when |
+|---|---|
+| **Expo Push** | RN/Expo; simplest path. |
+| **OneSignal** | Cross-platform, segmentation features. |
+| **Firebase Cloud Messaging (FCM) + APNs** | Custom backend; full control. |
+| **Customer.io / Iterable** | Marketing-driven (campaigns, journeys). |
+
+## 9. Analytics + observability
+
+| Choice | Pick when |
+|---|---|
+| **Amplitude / Mixpanel / PostHog** | Product analytics. |
+| **Sentry / Bugsnag** | Crash + performance. |
+| **Firebase Performance / Crashlytics** | Free, broad coverage. |
+| **DataDog Mobile RUM** | Already on DataDog. |
+
+## 10. Anti-patterns Tony flags fast
+
+- **React Native for an animation-heavy / camera-heavy app** without scoping native modules upfront.
+- **Flutter for an iOS-primary product** when the team has no Dart history.
+- **Capacitor for a product needing 60 fps gestures** — pick RN/native.
+- **One framework for two products** that don't share the audience or team.
+- **Side-loading internal apps with no signing strategy.**
+
+## 11. Recording the choice
+
+Tony documents the chosen stack into:
+
+- `.wize/planning/tech-vision.md` (Fury): platforms covered, non-negotiables.
+- `.wize/solutioning/architecture.md` (Tony): runtime, build, release pipeline, native modules required.
+- `.wize/solutioning/adrs/ADR-002-mobile-stack.md`: trade-off log.
+- `.wize/planning/app/device-matrix.md`: targets that justified the perf choice.