@eltonssouza/development-utility-kit 0.10.0

package/dashboard/public/content/manual/mobile.en.md

@@ -0,0 +1,837 @@
+# Mobile — React Native 0.84+ + Expo SDK 54+
+
+Onboarding guide for mobile development with React Native, Expo, and development-utility-kit.
+
+## Who this manual is for
+
+Mobile developer working on a React Native app (Expo managed or bare) that will use the development-utility-kit harness as an orchestration layer for skills + agents. The guide covers everything from an empty folder to EAS Build in production, including discovery, sprints, tests, and debugging.
+
+Prerequisites:
+
+- Node.js 22+ and npm 10+ on PATH
+- Expo CLI (`npm install --global expo-cli` optional; prefer `npx`)
+- Android Studio (with SDK 35+) for local Android builds
+- Xcode 16+ + CocoaPods for local iOS builds (macOS only)
+- EAS account (`npx eas-cli login`)
+- Git, Git Bash, or WSL on Windows
+
+Cowork or Claude Code open in the project folder. The harness lives at `C:\development\tools\development-utility-kit` (Windows) or `~/development/tools/development-utility-kit` (macOS/Linux).
+
+## Real CLI (duk)
+
+The `duk` binary covers 3 verbs:
+
+```bash
+duk install                       # install/update harness in current folder
+duk install --sub mobile          # install in ./mobile subfolder
+duk install --dry-run             # show what it would do, no writes
+duk dashboard                     # open local dashboard
+duk update                        # alias for `duk install`
+```
+
+**Important**: there is NO `duk <skill>`. Skills trigger by keyword match in chat with Claude. Do not type `duk bootstrap-mobile`, `duk run-sprint`, `duk grill-me`. Everything is conversation.
+
+## 5-min onboarding
+
+Mobile has no `bootstrap-mobile` skill. Scaffolding is the responsibility of the `mobile-developer` agent via `project-manager` (catch-all skill). Step by step:
+
+```bash
+# 1. Create Expo project (manual, outside the harness)
+npx create-expo-app@latest MyApp --template blank-typescript
+cd MyApp
+
+# 2. Install harness in the app folder
+duk install
+# Expected output:
+# ✓ .claude/ provisioned (skills + agents + hooks)
+# ✓ CLAUDE.md created (fill in Project Identity)
+# ✓ docs/brain/ provisioned (Obsidian vault)
+# ✓ scripts/hooks/ installed
+```
+
+Edit `CLAUDE.md` under the `Project Identity` section:
+
+```markdown
+## Project Identity
+
+- **Project name**: `my-mobile-app`
+- **Project type**: `mobile`
+- **Primary stack**: `React Native 0.84+ / Expo SDK 54+`
+- **Database**: `MMKV (local) + remote REST API`
+- **Domain**: `e-commerce`
+- **Team size**: `2 mobile`
+- **Additional rules**:
+```
+
+Optional dashboard to inspect harness state:
+
+```bash
+duk dashboard
+# Opens http://localhost:4300
+```
+
+Open the folder in Cowork or Claude Code. First chat configures the app:
+
+```
+you:
+configure mobile project with Expo Router, TypeScript strict, New Architecture
+
+Claude (project-manager -> mobile-developer):
+> Applied:
+>   - app.json: newArchEnabled: true, scheme "myapp"
+>   - tsconfig.json: strict: true, noUncheckedIndexedAccess: true
+>   - expo-router installed, app/_layout.tsx + app/(tabs)/_layout.tsx
+>   - app/(tabs)/index.tsx Home
+>   - app/(tabs)/profile.tsx Profile
+>   - .eslintrc with @typescript-eslint strict
+>   - jest.config.ts + jest-expo preset
+> Run `npx expo start` to validate.
+```
+
+## Mandatory stack
+
+| Technology | Version | Notes |
+|---|---|---|
+| React Native | 0.84+ | New Architecture mandatory (Fabric + TurboModules) |
+| React | 19+ | Server Components awareness, but RN stays client-only |
+| TypeScript | strict | `tsconfig.json` with `strict: true`, `noUncheckedIndexedAccess: true` |
+| Expo | SDK 54+ | Prefer managed; bare workflow only with justification |
+| Navigation | React Navigation 7+ or Expo Router | Expo Router default in new apps |
+| State | Zustand / TanStack Query / Jotai | Zustand for local state; TanStack for server state |
+| Styling | NativeWind 4+ or StyleSheet | NativeWind if the team comes from Tailwind |
+| Animation | Reanimated 4 + Gesture Handler | Always animate on the UI thread |
+| Lists | FlashList 2+ | FlatList only for lists < 20 items |
+| Storage | MMKV (sync) or AsyncStorage | MMKV default; AsyncStorage only on legacy |
+| Secure storage | expo-secure-store | Token, refresh token, biometric secret |
+| Forms | react-hook-form + zod | Validation with zod, single schema client+API |
+| Unit testing | Jest + React Native Testing Library | jest-expo preset |
+| E2E testing | Detox or Maestro | Detox for native iOS+Android; Maestro for simple flows |
+| Build | EAS Build | Cloud build default |
+| Submit | EAS Submit | Automated store submission |
+| OTA | expo-updates + EAS Update | Hotfix without store review |
+
+## CLAUDE.md Project Identity (mobile)
+
+```markdown
+## Project Identity
+
+- **Project name**: `my-mobile-app`
+- **Project type**: `mobile`
+- **Primary stack**: `React Native 0.84+ / Expo SDK 54+`
+- **State**: `Zustand + TanStack Query`
+- **Navigation**: `Expo Router`
+- **Storage**: `MMKV + expo-secure-store`
+- **Domain**: `e-commerce`
+- **Team size**: `2 mobile`
+```
+
+## Skills applicable to mobile
+
+Mobile uses the harness's general skill catalog. There is no mobile-specific skill. `project-manager` does the catch-all routing to `mobile-developer`.
+
+| Skill | EN trigger | Output |
+|---|---|---|
+| `project-manager` | "create mobile app", "react native", "convert Angular to mobile" | Delegates to `mobile-developer` via Task |
+| `grill-me` | "grill me about X", "interview me about X" | `DISCOVERY_*.md` |
+| `to-prd` | "generate PRD" | `PRD_*.md` |
+| `to-issues` | "split into issues" | `ISSUES_*.md` |
+| `run-sprint` | "run sprint N", "execute the sprint" | Sprint implemented with green tests |
+| `auto-test-guard` | "run tests", "generate tests" | Suite + senior+ gate |
+| `pair-debug` | "let's debug X", "investigate this bug" | Hypothesis -> probe -> confirm loop |
+| `prd-ready-check` | "PRD ready?", "DoD" | GO / NO-GO |
+| `brain-keeper` | "record in brain", end of PLAN | Notes in `docs/brain/` |
+| `active-project` | "/active-project <path>" | Fast-lane adoption |
+| `update-template` | "update template" | Sync `.claude/` + `CLAUDE.md` |
+| `caveman` | always-on, "stop caveman" | Telegraphic output |
+
+### `project-manager` (catch-all — replaces bootstrap-mobile)
+
+Since there is NO `bootstrap-mobile`, all scaffolding or structural changes go through `project-manager`:
+
+```
+you:
+create mobile app with Expo SDK 54 and tab navigation
+
+Claude (project-manager):
+> Intent identified: mobile scaffold.
+> Delegating to mobile-developer.
+
+Claude (mobile-developer):
+> npx create-expo-app@latest --template blank-typescript .
+> Configured Expo Router with (tabs).
+> Installed: zustand, @tanstack/react-query, react-native-mmkv,
+>   expo-secure-store, react-hook-form, zod, @shopify/flash-list
+> jest-expo + RNTL + Detox in devDependencies.
+> CLAUDE.md updated for type=mobile.
+> Done. `npx expo start` to validate.
+```
+
+### `grill-me` (typical mobile discovery)
+
+Mobile discovery covers platform-specific topics:
+
+- iOS-first vs Android-first vs parallel
+- Online-first vs offline-first
+- Biometric auth (Face ID, Touch ID, Android Biometric)
+- Push notification (Expo Notifications vs native FCM/APNs)
+- Universal deep linking vs custom scheme
+- OTA strategy (which channel, which SLA)
+- Accessibility (Screen reader, dynamic type, touch targets)
+
+```
+you:
+grill me about checkout screen with Apple Pay and Google Pay
+
+Claude (grill-me):
+> 1. What price range is supported?
+> 2. Multi-currency?
+> 3. Idempotency: does the backend have an idempotency-key already?
+> 4. Fallback if Apple/Google Pay unavailable? Stripe? PIX in Brazil?
+> 5. Lock orientation during payment — yes or no?
+> 6. Offline behavior: can payment start without internet?
+> 7. iOS-first launch or Android-first?
+```
+
+### `auto-test-guard` (mobile thresholds)
+
+Senior+ gate adapts for mobile (Detox flakiness tolerated):
+
+| Metric | Mobile threshold |
+|---|---|
+| Jest statements | >= 85% |
+| Jest branches | >= 80% |
+| RN Testing Library a11y | 0 critical |
+| Detox/Maestro E2E | critical flows green, retry up to 3x |
+| ESLint | 0 errors, 0 new warnings |
+| TS strict | no `any` in new code |
+| Bundle size delta | < 200KB per feature (warn), block > 500KB |
+
+### `pair-debug` (typically mobile)
+
+Mobile has its own class of bugs that warrant the hypothesis-driven loop:
+
+- Metro cache corrupted after `git pull`
+- `pod install` failing on CocoaPods version
+- Gradle daemon stuck
+- New Architecture incompatible with legacy lib
+- Hermes crash with no stack trace
+- EAS Build failing on signing
+
+## Workflow 1 — Feature from scratch (15 turns)
+
+Scenario: product list screen with pull-to-refresh, infinite scroll, and API integration.
+
+```
+Turn 1 — you:
+grill me about product list screen with pull-to-refresh and infinite scroll
+
+Turn 1 — Claude (grill-me):
+> Let's scope this.
+> 1. How many products per page? I recommend 20 with cursor pagination
+>    (not offset — avoids drift when the list changes during scroll).
+> 2. Cache: TanStack Query with 5min staleTime? Persisted to MMKV?
+> 3. Offline: show last cache + "offline" banner when no network?
+> 4. Skeleton during initial load or native ProgressView?
+> 5. Does pull-to-refresh invalidate cache or just refetch the first page?
+> 6. Error: auto-retry or manual button?
+> 7. Accessibility: VoiceOver / TalkBack — announce "loading more"?
+```
+
+```
+Turn 2 — you:
+20 per page with cursor. TanStack staleTime 5min. Offline shows cache + banner.
+Initial skeleton. Pull-to-refresh invalidates everything. Auto-retry 2x then manual.
+A11y mandatory.
+
+Turn 2 — Claude (grill-me):
+> Discovery complete. Saved to docs/discovery/DISCOVERY_product-list.md.
+> Next: "generate PRD" to produce PRD_product-list.md.
+```
+
+```
+Turn 3 — you:
+generate PRD
+
+Turn 3 — Claude (to-prd):
+> docs/prd/PRD_product-list.md created.
+> Overview, Goals, User Stories (US-1..US-4), Functional Requirements,
+> Non-functional (a11y AA, p95 < 800ms first page, offline fallback),
+> Out of scope (filters, sorting — backlog).
+```
+
+```
+Turn 4 — you:
+split into issues
+
+Turn 4 — Claude (to-issues):
+> docs/issues/ISSUES_product-list.md created with 6 [ISSUE-N] blocks.
+> To open all on GitHub:
+>   gh issue create --title "..." --body-file ...
+> (commands ready in the file)
+```
+
+```
+Turn 5 — you:
+analyst generate plan
+
+Turn 5 — Claude (analyst):
+> docs/plans/PLAN_product-list.md created.
+> Sprint 1: hook + service + cache (3 tasks)
+> Sprint 2: UI + FlashList + skeleton (4 tasks)
+> Sprint 3: pull-to-refresh + error + offline banner (3 tasks)
+> Sprint 4: E2E tests + a11y audit (2 tasks)
+> Each task with goal-ready DoD.
+```
+
+```
+Turn 6 — you:
+prd ready?
+
+Turn 6 — Claude (prd-ready-check):
+> Evaluating PRD_product-list.md + PLAN_product-list.md.
+> ✓ User Stories with measurable criteria
+> ✓ Non-functional with numeric thresholds
+> ✓ Out of scope explicit
+> ✓ Goal-ready DoD on all tasks
+> GO. Can start sprint 1.
+```
+
+```
+Turn 7 — you:
+run sprint 1 of PLAN_product-list.md
+
+Turn 7 — Claude (run-sprint):
+> Sprint 1 — initial backlog:
+>   [Task 1.1] qa-engineer writes failing test (Red)
+>   [Task 1.2] mobile-developer implements hook + service (Green)
+>   [Task 1.3] gate-keeper validates senior+
+>
+> [Task 1.1] qa-engineer:
+>   features/products/useProductList.test.ts created, 4 scenarios failing.
+>
+> [Task 1.2] mobile-developer:
+>   - features/products/useProductList.ts (TanStack Query infinite)
+>   - features/products/product.service.ts (cursor fetch)
+>   - features/products/product.types.ts (zod schema)
+>   - 4 scenarios passing ✓
+>
+> [Task 1.3] gate-keeper:
+>   Jest statements 91% ✓
+>   ESLint 0 warnings ✓
+>   TS strict 0 any ✓
+> GREEN. Sprint 1 done.
+```
+
+```
+Turn 8 — you:
+run sprint 2
+
+Turn 8 — Claude (run-sprint):
+> Sprint 2 — UI with FlashList:
+>   [Task 2.1] qa-engineer writes RNTL test (snapshot + a11y)
+>   [Task 2.2] mobile-developer implements screen
+>   [Task 2.3] gate-keeper validates
+>
+> [Task 2.2] mobile-developer:
+>   - features/products/ProductListScreen.tsx (FlashList 2 estimatedItemSize 96)
+>   - features/products/ProductCard.tsx (memo, OnPress callback)
+>   - features/products/ProductSkeleton.tsx (Reanimated 4 pulse)
+>   - app/(tabs)/products/index.tsx (Expo Router route)
+>
+> [Task 2.3] gate-keeper:
+>   Jest 88% ✓
+>   RNTL a11y 0 critical ✓
+>   FlashList warnings: 0 ✓
+> GREEN.
+```
+
+```
+Turn 9 — you:
+run sprint 3
+
+Turn 9 — Claude (run-sprint):
+> Sprint 3 — pull-to-refresh, error, offline:
+>   - RefreshControl with invalidateQueries
+>   - Local ErrorBoundary + retry button
+>   - NetInfo subscription -> "offline" banner
+>   - MMKV persister for TanStack cache
+>
+> gate-keeper GREEN.
+```
+
+```
+Turn 10 — you:
+run sprint 4
+
+Turn 10 — Claude (run-sprint):
+> Sprint 4 — E2E + a11y:
+>   [Task 4.1] qa-engineer writes Detox test
+>   [Task 4.2] qa-engineer runs axe-core/react-native scan
+>
+> [Task 4.1]:
+>   e2e/product-list.e2e.ts — scroll, pull-to-refresh, offline mode
+>   Dev client build + Detox run: 3 scenarios green, retry used in 1
+>
+> [Task 4.2]:
+>   0 critical, 0 serious. 2 minor (low contrast on badge).
+>   Auto-fix applied.
+>
+> gate-keeper GREEN.
+```
+
+```
+Turn 11 — you:
+record in brain
+
+Turn 11 — Claude (brain-keeper):
+> docs/brain/features/product-list.md created.
+> docs/brain/daily/2026-05-27.md updated.
+> Obsidian links to PRD, PLAN, ADR (none created this sprint).
+> MOC.md updated.
+```
+
+```
+Turn 12 — you:
+ready for production?
+
+Turn 12 — Claude (gate-keeper):
+> Final senior+ gate:
+>   ✓ Jest 87% statements
+>   ✓ RNTL 0 critical a11y
+>   ✓ Detox critical flows green
+>   ✓ Bundle delta +180KB (warn — ok)
+>   ✓ TS strict
+>   ✓ ESLint clean
+> Cleared for production build.
+```
+
+## Workflow 2 — Biometric authentication
+
+```
+you:
+create auth flow with biometric using expo-local-authentication
+
+Claude (project-manager -> mobile-developer):
+> Installs expo-local-authentication, expo-secure-store.
+> Creates:
+>   - features/auth/BiometricAuthScreen.tsx ("Sign in with Face ID" button)
+>   - features/auth/PasswordFallbackScreen.tsx
+>   - services/biometric.service.ts:
+>       authenticateAsync({ promptMessage, fallbackLabel: 'Use password' })
+>   - services/credentials.store.ts (SecureStore, namespace "auth.v1")
+>   - store/auth.store.ts (Zustand: { user, token, refreshAt })
+>   - app/(auth)/_layout.tsx (gate for authenticated routes)
+>
+> Unit test: services/biometric.service.test.ts (mock LocalAuth)
+> E2E test: e2e/biometric.e2e.ts (skipped on CI without biometric device)
+>
+> Applied. Want to run "run tests"?
+```
+
+## Workflow 3 — EAS Build + Submit setup
+
+```
+you:
+configure EAS Build for Android and iOS
+
+Claude (devops-engineer):
+> Commands for you to run locally (needs your login):
+>   npm install --global eas-cli
+>   eas login
+>   eas build:configure
+>
+> I'll create eas.json with 3 profiles:
+
+> {
+>   "build": {
+>     "development": {
+>       "developmentClient": true,
+>       "distribution": "internal",
+>       "channel": "development"
+>     },
+>     "preview": {
+>       "distribution": "internal",
+>       "channel": "preview",
+>       "ios": { "simulator": false },
+>       "android": { "buildType": "apk" }
+>     },
+>     "production": {
+>       "channel": "production",
+>       "autoIncrement": true
+>     }
+>   },
+>   "submit": {
+>     "production": {
+>       "android": { "track": "production" },
+>       "ios": { "ascAppId": "1234567890" }
+>     }
+>   }
+> }
+>
+> Build commands:
+>   eas build --platform all --profile production
+>   eas submit -p android --latest
+>   eas submit -p ios --latest
+```
+
+```
+you:
+generate OTA update production with hotfix
+
+Claude (devops-engineer):
+> Pre-checks:
+>   ✓ expo-updates installed and configured (app.json runtimeVersion)
+>   ✓ "production" channel exists in eas.json
+>   ✓ No native code changes (verified git diff android/ ios/)
+>
+> Command:
+>   eas update --branch production --message "Hotfix: fix crash on list"
+>
+> After publish:
+>   - Prod devices get update on next cold start (or checkAutomatically: ON_LOAD)
+>   - Monitor: https://expo.dev/accounts/<org>/projects/<app>/updates
+>
+> Warning: if you changed native code, OTA will not work. You must rebuild.
+```
+
+## Workflow 4 — Angular -> React Native conversion
+
+```
+you:
+convert my existing Angular app to React Native preserving business logic
+
+Claude (mobile-developer):
+> Phase 1 — Catalog (read-only, no Angular changes):
+>   ✓ 12 features detected in src/app/features/
+>   ✓ 8 HttpClient services in src/app/core/services/
+>   ✓ 5 guards (auth, role-admin, role-user, has-tenant, feature-flag)
+>   ✓ 23 standalone components
+>   ✓ 4 pipes (currency, date-relative, mask-cpf, truncate)
+>
+> Phase 2 — Mapping:
+>   Angular service -> custom hook + Zustand
+>     UserService.getMe() -> useMe() (TanStack Query)
+>     CartService.add() -> useCart() (Zustand action)
+>   Angular component -> functional component + hooks
+>     ProductCardComponent -> ProductCard.tsx (memo)
+>   Guard -> Expo Router middleware
+>     authGuard -> app/(auth)/_layout.tsx redirect
+>   Pipe -> pure function
+>     currencyPipe -> formatCurrency(value, locale)
+>
+> Phase 3 — Incremental migration, feature by feature:
+>   Sprint A: auth + me + bootstrap
+>   Sprint B: signup feature
+>   Sprint C: listing feature
+>   ...
+>
+> Phase 4 — RN Testing Library + Detox tests per feature.
+>
+> Want to start with Sprint A? Type "run sprint A".
+```
+
+## Workflow 5 — pair-debug (Metro stuck)
+
+```
+you:
+let's debug — Metro is stuck and build won't run after git pull
+
+Claude (pair-debug):
+> Symptom: after recent git pull, npx expo start hangs at "Starting Metro Bundler".
+> Hypothesis 1 (85% confidence): Metro cache invalid due to changes in
+>   node_modules or metro.config.js.
+> Probe: run `watchman watch-del-all && rm -rf $TMPDIR/metro-* /tmp/metro-*`.
+> Confirm probe? (yes/no)
+
+you: yes
+
+Claude:
+> Executed. Caches cleared.
+> Next step: `npx expo start --clear`.
+> If still stuck, hypothesis 2 (60%): outdated node_modules.
+>   Probe: rm -rf node_modules && npm ci.
+
+you:
+didn't work. still stuck
+
+Claude:
+> Hypothesis 2 active.
+> Probe: rm -rf node_modules package-lock.json .expo && npm install.
+> Confirm? (yes/no)
+
+you: yes
+
+Claude:
+> Executed. npm install complete in 47s.
+> Run again: npx expo start --clear.
+> If it persists, hypothesis 3 (40%): watchman conflict with WSL/Windows
+>   filesystem. Check `watchman --version` and `watchman watch-list`.
+```
+
+## Workflow 6 — Push notifications
+
+```
+you:
+create push notification with expo-notifications
+
+Claude (project-manager -> mobile-developer):
+> Installs expo-notifications + expo-device.
+> Configures:
+>   - app.json: plugins ["expo-notifications", { icon, color }]
+>   - iOS: requests notifyOnUserAction permission
+>   - Android: creates "default" channel on boot
+> Creates:
+>   - services/notifications.service.ts:
+>       registerForPushNotificationsAsync()
+>       getExpoPushTokenAsync({ projectId })
+>   - hooks/useNotificationListener.ts:
+>       Notifications.addNotificationReceivedListener
+>       Notifications.addNotificationResponseReceivedListener
+>   - store/notifications.store.ts (list, badge count, mark-read)
+> Backend (suggested):
+>   POST /api/v1/devices { expoPushToken, platform, locale }
+>   POST /api/v1/notifications/dispatch (server -> Expo Push API)
+> Test: mock Notifications.scheduleNotificationAsync in jest setup.
+> Next: configure permission in the onboarding flow.
+```
+
+## Workflow 7 — Deep linking
+
+```
+you:
+configure universal deep linking for /products/:id
+
+Claude (mobile-developer):
+> app.json:
+>   "scheme": "myapp",
+>   "ios": { "associatedDomains": ["applinks:myapp.com"] },
+>   "android": { "intentFilters": [{ "action": "VIEW",
+>     "data": [{ "scheme": "https", "host": "myapp.com",
+>     "pathPrefix": "/products" }], "category": ["BROWSABLE","DEFAULT"] }] }
+> Expo Router automatically maps /products/[id] to app/products/[id].tsx.
+> Creates:
+>   - app/products/[id].tsx (loads product via useProduct(id))
+>   - Linking.createURL helper in utils/links.ts
+> Test:
+>   adb shell am start -W -a android.intent.action.VIEW \
+>     -d "myapp://products/42" com.example.myapp
+>   xcrun simctl openurl booted "myapp://products/42"
+> Universal link requires apple-app-site-association + assetlinks.json
+>   hosted at https://myapp.com/.well-known/.
+```
+
+## Cheat sheet — mobile triggers
+
+| I want to... | Type in chat |
+|---|---|
+| Create mobile app from scratch | `create mobile app with Expo SDK 54` |
+| Add a screen with discovery | `grill me about <screen>` -> `generate PRD` -> `run sprint` |
+| Biometric auth | `create auth flow with biometric` |
+| Push notification | `create push notification with expo-notifications` |
+| Deep link | `configure deep linking for /products/:id` |
+| EAS Build | `configure EAS Build` |
+| EAS Submit | `submit to Google Play and App Store` |
+| Production OTA update | `generate OTA update production` |
+| Migrate Angular -> RN | `convert Angular app to React Native` |
+| Debug stuck Metro | `let's debug — Metro stuck` |
+| Debug pod install | `let's debug — pod install fail` |
+| Run tests | `run tests` |
+| Final pre-store gate | `ready for production?` |
+| Record history | `record in brain` |
+| Remember preference | `remember that <X>` |
+
+## Decision tree
+
+```
+Empty app?                      -> create mobile app with Expo SDK 54
+                                   (project-manager -> mobile-developer)
+
+New screen or feature?          -> grill me about <X>
+                                   -> generate PRD
+                                   -> analyst generate plan
+                                   -> run sprint N
+
+Native auth (Face/Touch ID)?    -> create auth flow with biometric
+
+Notification?                   -> create push notification
+
+Deep link / universal link?     -> configure deep linking
+
+Build for store?                -> configure EAS Build
+                                   -> eas build --profile production
+
+Update without review?          -> generate OTA update production
+                                   (only if no native changes)
+
+Angular conversion?             -> convert Angular app to React Native
+
+Mysterious crash?               -> let's debug
+                                   (pair-debug hypothesis-driven)
+
+Tests missing?                  -> run tests
+                                   (auto-test-guard + gate-keeper)
+```
+
+## Sub-agents relevant to mobile
+
+| Agent | Model | Acts on |
+|---|---|---|
+| `mobile-developer` | Sonnet 4.6 | React Native 0.84+, Expo SDK 54+, New Architecture, TS strict, Reanimated 4, FlashList 2 |
+| `ux-designer` | Sonnet 4.6 | Mobile-specific: touch targets (>= 44pt), safe area, dynamic type, dark mode |
+| `architect` | Sonnet 4.6 | State mgmt (Zustand vs TanStack vs Jotai), navigation pattern, OTA strategy |
+| `qa-engineer` | Sonnet 4.6 | Jest + RN Testing Library + Detox/Maestro |
+| `gate-keeper` | Sonnet 4.6 | Senior+ gate adapted for mobile (Detox flakiness tolerated) |
+| `devops-engineer` | Sonnet 4.6 | EAS Build, EAS Submit, EAS Update, fastlane (if bare workflow) |
+| `tech-lead` | Opus 4.7 | Mobile stack decision, OTA strategy, native breaking changes |
+| `product-owner` | Opus 4.7 | Scope, MVP iOS-first vs Android-first, mobile persona |
+| `security-engineer` | Opus 4.7 | SecureStore, jailbreak/root detection, certificate pinning, OWASP MASVS |
+| `database-engineer` | Sonnet 4.6 | MMKV schema, AsyncStorage migration, encrypted local DB (SQLite + sqlcipher) |
+
+## Senior+ gate adapted for mobile
+
+| Metric | Threshold | Tool |
+|---|---|---|
+| Jest statements | >= 85% | `jest --coverage` |
+| Jest branches | >= 80% | `jest --coverage` |
+| RNTL a11y violations | 0 critical, 0 serious | adapted `jest-axe` |
+| Detox/Maestro critical flows | 100% (retry up to 3x) | Detox runner |
+| ESLint | 0 errors, 0 new warnings | `eslint --max-warnings 0` |
+| TypeScript strict | no `any` in new code | `tsc --noEmit` |
+| Bundle size delta | warn > 200KB, block > 500KB | `expo export` + size script |
+| Cold start (Android median) | < 2500ms | EAS Build profile + Detox metrics |
+| Crash-free sessions | >= 99.5% | Sentry/Bugsnag |
+
+## Active hooks in the harness
+
+| Event | Script | Function |
+|---|---|---|
+| `UserPromptSubmit` | `prompt-gate-reminder.sh` | senior+ gate reminder |
+| `PreToolUse` (Bash) | `pre-push-guard.sh`, `block-test-deletion.sh` | Blocks direct push to main/develop; blocks deletion of `*.test.ts` / `*.e2e.ts` |
+| `PostToolUse` (Edit/Write) | inline prettier, `post-edit-test-reminder.sh` | Formats + reminds to run suite |
+| `Stop` | `stop-brain-reminder.sh` | brain-keeper records session |
+
+See [Hooks reference](../docs/hooks-reference).
+
+## Antipatterns (DON'T do this)
+
+- Class components — always functional + hooks
+- `any` in TypeScript — gate-keeper blocks
+- `duk <skill>` — doesn't exist, skills trigger by keyword in chat
+- Inline styles without `StyleSheet.create` — slow on the shadow tree
+- Skipping Detox/Maestro E2E on critical flows (auth, checkout, payment)
+- AsyncStorage for token, password, PII — use `expo-secure-store`
+- Libraries without New Architecture support (check before installing)
+- FlatList on long lists — always FlashList 2+
+- Reanimated 1/2 in new code — always 4+
+- Outdated Cocoapods — sync version with Expo SDK
+- Commit with `Co-Authored-By: Claude` — gate-keeper blocks
+- Mentioning Claude/Anthropic/AI/LLM/assistant in commit messages
+- OTA when native code changed — devices will crash
+- Permission prompt for notification or camera without prior UI context
+
+## Mobile troubleshooting
+
+**Metro cache corrupted after git pull:**
+
+```bash
+watchman watch-del-all
+rm -rf $TMPDIR/metro-* /tmp/metro-* node_modules/.cache
+npx expo start --clear
+```
+
+**pod install failing on Cocoapods version:**
+
+```bash
+cd ios && pod deintegrate && pod install --repo-update
+# If it persists:
+sudo gem install cocoapods -v 1.15.2
+```
+
+**Gradle daemon stuck (Android):**
+
+```bash
+cd android && ./gradlew --stop
+rm -rf ~/.gradle/caches/transforms-*
+./gradlew clean
+```
+
+**AsyncStorage migration (legacy -> MMKV):**
+
+Use `react-native-mmkv` with a one-shot migration helper at boot. Reads AsyncStorage, copies to MMKV, marks a migration flag.
+
+**New Architecture incompatible with a lib:**
+
+Check at https://github.com/reactwg/react-native-new-architecture/discussions/175. Lib without support: contact the maintainer or swap to an alternative.
+
+**EAS Build failing on signing:**
+
+Check:
+- `eas.json` -> production profile -> credentials configured
+- `eas credentials` -> verify Android keystore and iOS provisioning profile
+- Active Apple developer membership
+- Google Play service account with release permission
+
+**OTA update not reaching devices:**
+
+Checklist:
+- `expo-updates` installed and configured
+- `runtimeVersion` in `app.json` matches the production build
+- Correct channel in `eas update --branch production`
+- Devices opened the app at least once (background update)
+
+**Push notification not firing on iOS:**
+
+Check:
+- aps-environment entitlement in provisioning profile
+- "Push Notifications" capability in app.json
+- APNs key configured in EAS (`eas credentials`)
+- `notifyOnUserAction` permission requested and accepted
+
+**Detox flaky:**
+
+- Bump `waitFor(...).withTimeout(10000)`
+- Use `device.disableSynchronization()` only at critical points
+- Clean state between tests (`device.reloadReactNative()`)
+- Retry up to 3x in CI (`--retries 3`)
+
+## Quick glossary
+
+- **Skill** — entry point triggered by keyword match in the prompt. Defined in `.claude/skills/<slug>/SKILL.md`.
+- **Agent** — specialist executor invoked via Task tool. Defined in `.claude/agents/<name>.md`.
+- **Task tool** — harness mechanism to invoke subagents in parallel or sequence.
+- **PLAN_*.md** — goal-ready technical plan in `docs/plans/`, generated by `analyst`.
+- **PRD_*.md** — Product Requirements Document in `docs/prd/`.
+- **DISCOVERY_*.md** — output of the `grill-me` interview in `docs/discovery/`.
+- **ISSUES_*.md** — decomposed issues in `docs/issues/`.
+- **ADR-NNN** — Architecture Decision Record in `docs/decisions/`.
+- **EAS** — Expo Application Services. Build (cloud), Submit (auto-publish), Update (OTA).
+- **OTA** — Over-The-Air update. JS update bypassing store review. JS/assets only.
+- **New Architecture** — Fabric (renderer) + TurboModules + JSI. Replaces the old bridge.
+- **FlashList** — Shopify's virtualized list. Replaces FlatList for performance.
+- **MMKV** — native sync key-value storage (Facebook). Replaces AsyncStorage.
+- **Detox** — gray-box E2E. Runs on real device or emulator.
+- **Maestro** — black-box E2E via declarative YAML.
+- **Expo Router** — file-based routing inspired by Next.js. Default in SDK 50+.
+- **Zustand** — simple global store, no Redux boilerplate.
+- **TanStack Query** — server state cache + sync (replaces SWR).
+- **Reanimated** — UI-thread animations (JS worklet).
+- **Senior+ gate** — non-negotiable quality gate.
+- **Obsidian vault** — `docs/brain/` with daily/features/decisions.
+- **Autonomy Matrix** — who-decides-what table.
+
+## Cross references
+
+- [Architecture overview](../docs/architecture-overview) — 2-layer model (skill + agent)
+- [Agents reference](../docs/agents-reference) — all 25 agents
+- [Skills reference](../docs/skills-reference) — all 18 skills
+- [Pipeline](../docs/pipeline) — end-to-end flow
+- [Quality gate](../docs/quality-gate) — senior+ thresholds
+- [Stack rules](../docs/stack-rules) — mandatory conventions
+- [Autonomy matrix](../docs/autonomy-matrix) — who decides what
+- [Hooks reference](../docs/hooks-reference) — active hooks
+- [Git Flow](../docs/git-flow) — branches and commits
+- [Troubleshooting](../docs/troubleshooting) — common issues
+- [Backend manual](./backend) — Java 25 + Spring Boot 4
+- [Frontend manual](./frontend) — Angular 21
+- [Fullstack manual](./fullstack) — backend + frontend monorepo
+- [Existing project manual](./existing-project) — adoption via active-project