@cometchat/skills 4.4.1 → 5.0.0

package/skills/cometchat-native-troubleshooting/SKILL.md

@@ -1,501 +0,0 @@
----
-name: cometchat-native-troubleshooting
-description: "Diagnose CometChat React Native UI Kit integration failures — init/login, gesture handler, pod install, iOS privacy manifest, Android Maven, Metro cache, permissions, calls, extensions, v4-to-v5 upgrade. For push-specific symptoms see cometchat-native-push § 12."
-license: "MIT"
-compatibility: "Node.js >=18; React Native >=0.70; @cometchat/chat-uikit-react-native ^5"
-metadata:
-  author: "CometChat"
-  version: "3.0.0"
-  tags: "cometchat react-native troubleshooting metro pods permissions upgrade"
----
-
-## Purpose
-
-Teaches Claude how to diagnose and fix CometChat React Native integration failures. Covers every category of failure I've seen across Expo + bare RN, with an up-front triage flow so Claude asks the right questions before assuming a fix.
-
-**Read `cometchat-native-core` first** — most "why doesn't this work" issues trace to the init/login/wrapper chain explained there.
-
-Ground truth: `docs/ui-kit/react-native/troubleshooting.mdx`, `apple-privacy-manifest-guide.mdx`, `upgrading-from-v4.mdx`, and first-hand failure modes from real integrations. **Official docs:** https://www.cometchat.com/docs/ui-kit/react-native/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP).
-
----
-
-## 1. Triage — read project state before guessing
-
-When the user reports a problem, gather facts before proposing a fix. Ask + run these first:
-
-### 1a. Which framework?
-
-```bash
-# Expo or bare?
-grep -E '"expo":|"expo-router":' package.json
-ls -d ios android 2>/dev/null   # bare RN has these dirs at root
-ls app.json app.config.js 2>/dev/null
-```
-
-- `expo` in dependencies + no `ios/android` folders → **Expo managed** → route to `cometchat-native-expo-patterns`
-- `ios/` + `android/` folders at root → **bare RN** → route to `cometchat-native-bare-patterns`
-- Both (`expo` + `ios/android`) → bare-after-prebuild. Treat as bare.
-
-### 1b. Is the wrapper chain correct?
-
-```bash
-# Confirm four wrappers in entry file
-grep -E "GestureHandlerRootView|SafeAreaProvider|CometChatThemeProvider|CometChatProvider" \
-  App.tsx index.js index.ts app/_layout.tsx 2>/dev/null
-```
-
-If any are missing, that's almost certainly the cause. See `cometchat-native-core` § 3.
-
-### 1c. Is `react-native-gesture-handler` imported first?
-
-```bash
-# Must be line 1 (or 2 with a shebang) of entry
-head -5 index.js index.ts App.tsx app/_layout.tsx 2>/dev/null
-```
-
-If the import is missing or below React, swipe gestures and bottom sheets silently break — often only in release builds.
-
-### 1d. Is init complete before login?
-
-```bash
-grep -A 10 "CometChatUIKit.init" src/providers/CometChatProvider.tsx 2>/dev/null
-```
-
-Look for the init-then-login sequence with an `await` or module-level `initialized` flag. Fire-and-forget init is a common cause of "components don't render."
-
-### 1e. Pod install state (iOS)
-
-```bash
-ls ios/Pods/ | head -5 2>/dev/null       # should list dozens of pods
-cat ios/Podfile.lock | head -3 2>/dev/null
-```
-
-If `ios/Pods/` is missing or sparse, native modules aren't linked. `cd ios && pod install && cd ..` is the fix.
-
-### 1f. Package deps
-
-```bash
-# Check the full UI Kit peer-dep set is installed
-for dep in \
-  @cometchat/chat-sdk-react-native \
-  @cometchat/chat-uikit-react-native \
-  react-native-gesture-handler \
-  react-native-safe-area-context \
-  react-native-svg \
-  @react-native-async-storage/async-storage; do
-  node -e "try{require.resolve('$dep'); console.log('✓ $dep')}catch(e){console.log('✗ MISSING: $dep')}"
-done
-```
-
-Missing peer deps → install + `pod install` (bare) or `expo install` (Expo) + rebuild.
-
-> ⚠️ **`--legacy-peer-deps` silently DROPS peers.** If the project installed with `npm install --legacy-peer-deps` (common to dodge RN peer-range conflicts), npm **skips** unmet peer deps instead of erroring — you get a "successful" install with `react-native-svg` / `gesture-handler` / `safe-area-context` / async-storage missing, then a runtime crash. Re-run the check above after any `--legacy-peer-deps` install and install the missing ones **explicitly**.
-> ⚠️ **`@cometchat/calls-lib-webrtc` is Cloudsmith-only — NOT on npm** (`npm view @cometchat/calls-lib-webrtc` → 404, verified). If a calls install fails resolving it, add the Cloudsmith tarball/registry per `cometchat-native-calls`; a plain `npm install @cometchat/calls-lib-webrtc` will never work.
-
----
-
-## 2. Symptom → fix lookup tables
-
-Quick-reference tables. Work through in order; if none match, drop into § 3 deep-dives.
-
-### 2a. Initialization + login
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| `CometChatUIKit.init()` fails silently | Invalid `APP_ID` / `REGION` / `AUTH_KEY` | Re-verify from dashboard → your app → Credentials |
-| Components render nothing after login | `init()` not awaited before mount | Use the provider pattern from `cometchat-native-core` § 6 with `isReady` gating |
-| Blank screen, no errors | Component mounted before init completed | Conditionally render: `if (!isReady) return null` |
-| `getLoggedInUser()` returns `null` | Login not called or session expired | Call `CometChatUIKit.login({ uid })` after init resolves |
-| Login fails: "UID not found" | User doesn't exist in CometChat | Create via dashboard, SDK, or REST API. For dev, use `cometchat-uid-1` through `cometchat-uid-5` (pre-seeded) |
-| "Please wait until the previous login request ends" | `login()` called concurrently (React StrictMode double-mount / navigation remount) | Use the `ensureLoggedIn` module-level promise guard from `cometchat-native-core` § 2 |
-| `sendTextMessage()` fails | Not logged in or invalid receiver | Verify `getLoggedInUser()` returns a user + receiver user/group object exists |
-| Production build exposes Auth Key | Using `authKey` in production | Switch to server-minted auth tokens via `login({ authToken })`. See `cometchat-native-production` |
-
-### 2b. Gesture handler + wrapper chain
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| Composer swipe gestures not working | `import "react-native-gesture-handler"` not at TOP of entry file | Move to line 1 of `index.js` / `index.ts` / Expo Router's `app/_layout.tsx` |
-| BottomSheet doesn't open on swipe | Missing `GestureHandlerRootView` wrapper | Wrap at app root with `<GestureHandlerRootView style={{ flex: 1 }}>` |
-| Content overlaps status bar / home indicator | Missing `SafeAreaProvider` | Wrap inside `GestureHandlerRootView` with `<SafeAreaProvider>` |
-| Theme tokens return undefined | Missing `CometChatThemeProvider` | Add wrapper. See `cometchat-native-core` § 3 for the full chain |
-| "Couldn't find SafeArea context" error | `SafeAreaView` used outside `SafeAreaProvider` | Add `SafeAreaProvider` at root, or use plain `View` inside chat screens |
-| Release build: swipe/gesture broken, dev build fine | `react-native-gesture-handler` not line 1 (some bundlers defer it) | Move to line 1 unconditionally |
-
-### 2c. iOS build failures
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| `No such module 'RNGestureHandler'` | Pods not installed | `cd ios && pod install && cd ..` + rebuild |
-| `Undefined symbol: _OBJC_CLASS_$_RNCAsyncStorage` | Pods out of sync after `npm install` | `cd ios && pod install && cd ..` |
-| `TurboModuleRegistry.getEnforcing(...)` crash at runtime | Native module not linked | `cd ios && pod install && cd ..` + reset Metro cache (`--reset-cache`) |
-| App Store rejection `ITMS-91053` | Missing Apple Privacy Manifest | Add `ios/<App>/PrivacyInfo.xcprivacy` with 4 API types. See `cometchat-native-bare-patterns` § 2c |
-| Simulator build fails: "arm64 excluded" | Architecture mismatch on Apple Silicon | Add `EXCLUDED_ARCHS[sdk=iphonesimulator*]` post_install in Podfile. See `cometchat-native-features` § 3c |
-| Camera/mic permission dialog doesn't appear | Missing `NSCameraUsageDescription` / `NSMicrophoneUsageDescription` | Add to `ios/<App>/Info.plist` (bare) or `app.json` `ios.infoPlist` (Expo) |
-| iOS build fails: "deployment target too low" | Calls SDK needs 12+ | Set `IPHONEOS_DEPLOYMENT_TARGET = '12.0'` in Podfile post_install |
-| Expo Go crashes: "Main module field cannot be resolved" | Expo Go doesn't support native modules | Use dev builds: `npx expo run:ios` or `eas build --profile development` |
-
-### 2d. Android build failures
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| `Could not find :react-native-async-storage_async-storage:` | Local Maven repo entry missing | Add to `android/build.gradle` `allprojects.repositories` — see `cometchat-native-bare-patterns` § 3b |
-| Build crashes on launch | `compileSdkVersion` too low | Set `compileSdkVersion` to 33+ and `minSdkVersion` to 24+ in `android/app/build.gradle` |
-| "Permission denied" when picking photos | Missing Android permissions | Add `READ_MEDIA_IMAGES` (API 33+) or `READ_EXTERNAL_STORAGE` (API ≤32) to `AndroidManifest.xml` |
-| "Camera permission denied" | Missing permission in manifest or runtime denial | Add `CAMERA` to `AndroidManifest.xml` + verify runtime-grant flow |
-| Gradle sync fails after `npm install` | Native module autolinking stale | `cd android && ./gradlew clean && cd ..` then rebuild |
-| `Unable to delete file: ...node_modules/...` | Metro lockfile on Windows (if cross-OS) | Restart Metro + IDE |
-
-### 2e. Metro / JS runtime
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| "Unable to resolve module ..." for a dep that IS installed | Metro cache stale | Stop Metro, run with `--reset-cache`: `npx react-native start --reset-cache` or `npx expo start --clear` |
-| Fast Refresh doesn't pick up new deps | Native dep change (requires rebuild) | Restart Metro + rebuild (iOS/Android) |
-| "Maximum update depth exceeded" after theme change | Theme object recreated each render | Define theme at module scope or in `useMemo(() => ..., [])` |
-| App crashes on first JS load | Entry file error (syntax or import order) | Check `index.js` — `react-native-gesture-handler` should be line 1 |
-| Unhandled promise rejection at startup with `id=0` / module-load TypeError, but chat + calls work fine | Known non-blocking init artifact from the kit/calls-sdk module-level code (F77); source-map unresolvable | **Non-blocking — do NOT chase it.** Chat and calls are fully functional. Documented as a known v4.x artifact. Don't refactor user code to "fix" it. |
-| Error banner shows literal `[object Object]` instead of a message | `setError(String(e))` / `setError(\`${e}\`)` — CometChatException stringifies to `[object Object]` | Use `e.message` (or a `formatCometChatError(e)` helper): `setError(e?.message ?? String(e))`. |
-| (Expo) Credentials/config changes don't take effect after editing app config | `expo.extra` manifest is **cached** | Restart with `npx expo start --clear`; for a dev build, rebuild. The `expo.extra` block is baked into the manifest at build/start time. |
-
-### 2f. Theming
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| Theme overrides don't apply | Missing `CometChatThemeProvider` wrapper | Add at app root. See `cometchat-native-theming` § 2 |
-| Dark mode doesn't switch when system toggled | `mode` hardcoded to `"light"` / `"dark"` | Omit the `mode` field to follow system |
-| Custom color shows as fallback | Color not a hex string | Use `#RRGGBB` format. `rgb()` / named colors / `hsl()` break the extendedPrimary auto-derivation |
-| Custom font shows system default (iOS) / crashes (Android) | Font not loaded before render | Gate the provider on font loading (Expo `useFonts` or bare `react-native-asset`) |
-| Icon color not changing via `imageStyle` | Only `tintColor`, `height`, `width` work on default SVG icons | Use `tintColor`. Other props are ignored for built-in icons |
-| `useTheme()` returns undefined | Called outside `CometChatThemeProvider` | Ensure the component is a descendant of the provider |
-
-### 2g. Components
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| Slot view (`TitleView`, `LeadingView`, etc.) renders nothing | Slot returned `null` / `undefined` | Slot must return valid JSX |
-| Empty message list despite sent messages | `user` vs `group` prop mixed up | Pass exactly one of `user` OR `group` — never both, never neither |
-| "Reply in Thread" option does nothing when tapped | Thread panel not wired | Set `hideReplyInThreadOption` (see `cometchat-native-components` § 11) OR wire a thread panel (§ 2b) |
-| `onItemPress` callback not firing | Wrong prop name (RN uses `Press` not `Click`) | It's `onItemPress`, not `onItemClick` — web and RN diverge here |
-| Conversations list empty but data exists | Wrong request builder | Check `conversationsRequestBuilder` filters (tags, types) |
-| List components collapse to zero height | Container has no bounded height | Wrap in `<View style={{ flex: 1 }}>` or explicit `height: N`. See `cometchat-native-placement` Hard rule #8 |
-| Component renders but data never loads | User/group passed as UID string instead of `CometChat.User`/`Group` instance | `await CometChat.getUser(uid)` first, pass the resolved object |
-
-### 2h. Calling
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| Call buttons missing from MessageHeader | `@cometchat/calls-sdk-react-native` not installed | Install + rebuild. See `cometchat-native-features` § 3 |
-| Incoming call UI doesn't show | `CometChatIncomingCall` not mounted or listener not registered | Register `CometChat.addCallListener(...)` and mount `<CometChatIncomingCall>` at app root |
-| Call connects but no audio/video | Missing Podfile settings or Android SDK versions | Check `IPHONEOS_DEPLOYMENT_TARGET = 12.0` + Android `minSdkVersion = 24` |
-| WebRTC errors on load | Missing peer deps | Install `react-native-webrtc` + `@react-native-community/netinfo` + `react-native-background-timer` + `react-native-callstats` |
-| Call crashes on Android after accept | Permissions denied at runtime | Request `RECORD_AUDIO` + `CAMERA` runtime permissions before call |
-| `onIncomingCallReceived` silent | Listener registered before login completes | Register the listener INSIDE the `useEffect` that runs after login |
-
-### 2i. Extensions
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| Polls option missing from composer | Extension not enabled in dashboard | `cometchat features enable polls --json` or toggle in dashboard → Features |
-| Stickers not rendering | Sticker extension not enabled | Same as above — enable via CLI |
-| Extension enabled but UI doesn't appear | Cached session — hard reload needed | Stop Metro, clear cache (`--reset-cache`), rebuild |
-| Extension says enabled but `auto_wired_in_uikit: false` | Needs `extensions` field on `CometChatUIKit.init({ ... })` | Add `extensions: [new StickersExtension(), ...]` to the init settings — see `cometchat-native-features` § 2 |
-| Message translation "Translate" option missing | Extension not enabled | Enable `MessageTranslation` via CLI / dashboard |
-
-### 2j. AI features
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| AI suggestions don't appear | AI feature not enabled in dashboard | Enable via dashboard → AI → individual feature |
-| Smart Replies not showing | Smart Replies extension off | Enable via CLI: `cometchat features enable smart-replies` |
-| Conversation Starter missing | Feature off + no conversation context | Enable feature + ensure chat has at least one previous message |
-
-### 2k. Localization
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| UI text not translated | Language code mismatch | Use full codes like `en-US`, not short `en` |
-| Auto-detection not working | `react-native-localize` missing | Install: `npm install react-native-localize` + pod install |
-| Custom translations not applied | Missing `CometChatI18nProvider` | Wrap app inside `CometChatThemeProvider` with `<CometChatI18nProvider>` |
-
-### 2l. Events
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| Listener doesn't fire | Wrong event name | Check `docs/events.mdx` for exact event names (e.g., `ccMessageSent` not `onMessageSent`) |
-| Listener fires twice | Duplicate registration (common with hot reload / remount) | Remove in `useEffect` cleanup: `return () => CometChatUIEventHandler.removeMessageListener(id)` |
-| Listener ID collision | Hardcoded ID reused across components | Use a unique constant per component: `const LISTENER_ID = "APP_SCREEN_LISTENER"` |
-| Call events not received | `CometChat.addCallListener` registered before login | Move registration into `useEffect` after login completes |
-
-### 2m. Production / auth tokens
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| `login({ authToken })` fails: "user does not exist" | User not created in CometChat before token mint | Create user server-side via REST API on your signup flow. See `cometchat-native-production` § 6 |
-| Token endpoint returns 401 | Backend auth check failing | Verify `Authorization: Bearer <jwt>` header is attached to the fetch |
-| 429 rate limit on token endpoint | Minting tokens too often (e.g. per screen mount) | Cache client-side, reuse until expiry. See `cometchat-native-production` § 10 |
-| SDK disconnects after a few hours | Token expired | Wire `onDisconnected` listener to re-fetch + re-login. See `cometchat-native-production` § 5c |
-| `CometChatUIKit.loginWithAuthToken` not found | Wrong API name | It's `CometChatUIKit.login({ authToken })` — same method as dev, different key |
-
----
-
-## 3. Deep dives on common failures
-
-### 3a. "The most common 'why is my chat blank' bug"
-
-CometChat components fill 100% of their parent's height. If the parent has no bounded height, the components render at 0px and look empty.
-
-Diagnostic:
-
-```bash
-grep -B5 -A5 "CometChatMessageList\|CometChatConversations" src/**/*.tsx | grep -B2 -A2 "style"
-```
-
-Look for the message list's parent. One of these must be true:
-
-- Parent has `flex: 1`
-- Parent has an explicit `height: N`
-- Parent is a flex column with the list getting `flex: 1`
-
-Broken example:
-```tsx
-<ScrollView>
-  <CometChatMessageList user={user} />   {/* ← ScrollView doesn't constrain height */}
-</ScrollView>
-```
-
-Fixed:
-```tsx
-<View style={{ flex: 1 }}>
-  <CometChatMessageList user={user} hideReplyInThreadOption />
-</View>
-```
-
-### 3b. Apple Privacy Manifest rejection (`ITMS-91053`)
-
-Apple's App Store Connect rejects RN apps that use certain APIs without declaring them in `PrivacyInfo.xcprivacy`. The CometChat kit (through React Native + `react-native-video`) triggers 4 of these APIs.
-
-Full manifest content is in `cometchat-native-bare-patterns` § 2c. Required reason codes:
-
-| API | Code |
-|---|---|
-| FileTimestamp | `C617.1` |
-| UserDefaults | `CA92.1` |
-| SystemBootTime | `35F9.1` |
-| DiskSpace | `E174.1` |
-
-If the user's rejection email lists OTHER API categories, their app uses additional Apple APIs through other SDKs (analytics, crash reporters, etc.). Add those codes too — the CometChat-specific 4 aren't exhaustive for all apps.
-
-After updating:
-1. `cd ios && pod install && cd ..`
-2. Rebuild the archive
-3. Resubmit
-
-### 3bb. `react-native-document-picker` build failure on RN 0.85+ (F70)
-
-**Symptom:** Android debug build fails with a hard Java compile error inside `react-native-document-picker`'s source — typically `cannot find symbol class GuardedResultAsyncTask`.
-
-**Root cause:** `react-native-document-picker` references `GuardedResultAsyncTask`, which React Native removed from its Android internals in 0.85. The package is unmaintained — the last useful release predates RN 0.85.
-
-**Fix:** uninstall it and switch to a maintained alternative if document picking is needed.
-
-```bash
-# Uninstall the broken package
-npm uninstall react-native-document-picker
-
-# For Expo apps — official maintained pick
-npx expo install expo-document-picker
-
-# For bare RN — maintained community fork
-npm install @react-native-documents/picker
-```
-
-`cometchat verify` flags this combination automatically (`rn_doc_picker_compat` check) — runs as part of every verify since v4.3.0.
-
-### 3bc. `Cannot read property 'CometChatThemeProvider' of undefined` on bare RN (F78 — chat-sdk 4.0.22 packaging regression)
-
-**Symptom (bare RN only):** the app builds cleanly (`BUILD SUCCESSFUL`) but crashes at JS startup with `TypeError: Cannot read property 'CometChatThemeProvider' of undefined`. The error often links to RN's own AsyncStorage troubleshooting text ("Make sure your project's `package.json` depends on `@react-native-async-storage/async-storage`…").
-
-**This is NOT the §3b Maven-repo build failure** — that one fails the Gradle build. F78 builds fine, then crashes at runtime.
-
-**Root cause (confirmed):** `@cometchat/chat-sdk-react-native` **4.0.22** declares `react`, `react-native@0.64.2`, and `@react-native-async-storage/async-storage@^1.13.4` as **hard `dependencies`** (4.0.21 had none). npm therefore installs **nested duplicate copies inside the SDK**:
-
-```
-node_modules/@cometchat/chat-sdk-react-native/node_modules/
-  ├── react-native/               → 0.64.2   (duplicate of your app's 0.85.x)
-  └── @react-native-async-storage/async-storage/  → 1.24.0
-```
-
-Two react-native copies = two native-module registries. The SDK's persistence code resolves AsyncStorage against its nested 1.24.0 copy, whose native module isn't the one your app autolinked → `RCTAsyncStorage` not found → the kit's `theme` module throws during evaluation → `CometChatThemeProvider` ends up `undefined`. **Expo is unaffected** because its resolver dedupes react-native to a single copy; bare RN installs the nested copy.
-
-Confirm you're hit by it:
-```bash
-ls node_modules/@cometchat/chat-sdk-react-native/node_modules/react-native/package.json && echo "F78: nested RN present"
-```
-
-**Fix — pick one (both verified to remove the nested install):**
-
-1. **npm `overrides`** (keep chat-sdk 4.0.22) — add to the app's `package.json`, then reinstall:
-   ```jsonc
-   "overrides": {
-     "@cometchat/chat-sdk-react-native": {
-       "react": "$react",
-       "react-native": "$react-native",
-       "@react-native-async-storage/async-storage": "$@react-native-async-storage/async-storage"
-     }
-   }
-   ```
-   yarn uses the equivalent top-level `resolutions`.
-2. **Pin the known-good SDK:** `npm i @cometchat/chat-sdk-react-native@4.0.21` (zero deps → no nesting).
-3. **Prefer Expo** for greenfield — the Expo cohort is fresh-validated and never hits this.
-
-After applying (1) or (2): `rm -rf node_modules && npm install`, then verify the nested `react-native` is gone with the `ls` check above. Tried and confirmed **NOT** to fix it: downgrading async-storage, `newArchEnabled=false`, clean rebuild, Metro `--reset-cache` — none address the duplicate-RN root cause.
-
-The permanent fix is SDK-side (move react/react-native to `peerDependencies`) — tracked in **ENG-35653**.
-
-### 3c. Metro cache issues (post-dep-install "not found" errors)
-
-Happens when you `npm install` a native module and Metro's bundler still has the old module graph cached.
-
-```bash
-# Full reset
-watchman watch-del-all 2>/dev/null          # watchman (if installed)
-rm -rf $TMPDIR/metro-*                       # Metro cache on macOS
-rm -rf $TMPDIR/haste-map-*                   # Haste cache on macOS
-rm -rf node_modules
-npm install
-cd ios && pod install && cd ..               # iOS only
-npx react-native start --reset-cache         # bare
-# OR for Expo:
-npx expo start --clear
-```
-
-If the error persists after a clean cache + pod install, the native module isn't autolinked. Check `react-native.config.js` for exclusions.
-
-### 3d. "App crashes on first launch" — entry file order
-
-`index.js` MUST have `import "react-native-gesture-handler"` as line 1. Not line 2. Not after a `// comment`. Not after a `"use strict"`. Literally line 1.
-
-Wrong:
-```js
-import React from "react";              // ← line 1
-import "react-native-gesture-handler";  // ← line 2 — TOO LATE
-```
-
-Right:
-```js
-import "react-native-gesture-handler";  // ← line 1
-import React from "react";
-```
-
-For Expo Router, the same rule applies to `app/_layout.tsx`.
-
-### 3e. Push notification issues
-
-Push setup is covered end-to-end in `cometchat-native-push`. That skill
-has:
-
-- § 3 APNs p8 setup (Apple Developer portal)
-- § 4 FCM setup (Firebase project + service account)
-- § 5 CometChat dashboard provider upload (dev + prod for iOS)
-- § 7 Client registration with `CometChatNotifications.registerPushToken(token, platform, providerId)` (the correct API — not `CometChat.registerTokenForPushNotification`)
-- § 9 Foreground display + tap-to-deep-link handlers
-- § 12 Troubleshooting table mapping symptoms to fixes (production APNs cert missing, token registered before login, Expo Go can't receive push, etc.)
-
-When diagnosing a push issue, route the user to `cometchat-native-push § 12`
-rather than re-triaging here.
-
----
-
-## 4. v4 → v5 upgrade gotchas
-
-If the user is upgrading from `@cometchat/chat-uikit-react-native@4`, these are the common breakages. Full migration guide: `docs/upgrading-from-v4.mdx`.
-
-| v4 | v5 | Notes |
-|---|---|---|
-| `CometChatContext` provider | `CometChatThemeProvider` + `CometChatI18nProvider` | Split into theme + i18n providers |
-| `<CometChatConversationsWithMessages>` composite | `<CometChatConversations>` + navigate to separate screen | Composite component removed; use two-screen navigation pattern |
-| `theme` prop on components | Theme via `CometChatThemeProvider` only | Per-component theme prop removed |
-| `Palette` object | Color tokens under `theme.color` | Renamed + restructured |
-| `onClick` callback names | `onPress` callback names | React Native convention |
-| `CometChat.login(uid, authKey)` | `CometChatUIKit.login({ uid })` | Object-form argument |
-| Native deps in `peerDependencies` | Must explicitly install peer deps | See `cometchat-native-core` § 9 |
-| Single NPM package for calls | Separate `@cometchat/calls-sdk-react-native` package | Calls broken out |
-
-### Upgrade sequence
-
-```bash
-# 1. Update the main kit
-npm install @cometchat/chat-uikit-react-native@^5
-
-# 2. Install the full peer-dep set (v5 doesn't auto-install them like v4 did)
-npm install @cometchat/chat-sdk-react-native@^4 \
-  @react-native-async-storage/async-storage \
-  @react-native-clipboard/clipboard \
-  @react-native-community/datetimepicker \
-  react-native-gesture-handler react-native-localize \
-  react-native-safe-area-context react-native-svg \
-  react-native-video dayjs punycode
-
-# 3. iOS
-cd ios && pod install && cd ..
-
-# 4. Android — add the local Maven repo for async-storage
-#    (see cometchat-native-bare-patterns § 3b)
-
-# 5. Entry file — add `import "react-native-gesture-handler"` as line 1
-#    (new requirement in v5)
-
-# 6. Replace `<CometChatContext>` with the 4-wrapper chain
-#    (see cometchat-native-core § 3)
-
-# 7. Split composite components — e.g. `<CometChatConversationsWithMessages>`
-#    becomes two screens with navigation
-
-# 8. Rename `onClick*` → `onPress*` throughout
-
-# 9. Replace `Palette` → theme tokens
-
-# 10. Rebuild + test
-```
-
----
-
-## 5. Escalation — when the above doesn't solve it
-
-If none of the lookup tables or deep dives apply:
-
-1. **Run `cometchat doctor`** (the structured first pass — combines detect + info + verify + known-issue matching). Start here; it often pinpoints the layer (state / drift / env / deps) before you read logs.
-2. **Read the raw error.** RN errors are usually specific ("Module 'X' not found in app 'Y'" is different from "TurboModuleRegistry.getEnforcing").
-2. **Check the dev console + native logs.** For iOS: Xcode → View → Debug Area → Activate Console. For Android: `adb logcat | grep -E "cometchat|CometChat|ReactNative"`.
-3. **Search the upstream docs MCP** (`cometchat-docs` if installed).
-4. **Search the sample app** (`examples/SampleApp/` or `examples/SampleAppExpo/`) for a working version of the pattern the user is trying.
-5. **If the issue is a kit bug**, file at https://github.com/cometchat/cometchat-uikit-react-native/issues with a minimal repro.
-
----
-
-## 6. Hard rules (diagnostic best-practice)
-
-1. **Don't assume — triage first.** § 1 gets the framework, wrapper chain, pod state, and dep list before proposing a fix. A "I don't see messages" could be 10 different things.
-2. **Don't suggest "try reinstalling node_modules" as a first step.** It's rarely the actual fix and it takes minutes; check the entry file, wrapper chain, and pod state first.
-3. **Always verify against the ground-truth doc** (`troubleshooting.mdx`). If a user's symptom matches a table row, use the doc's fix verbatim — don't paraphrase.
-4. **Never guess a fix that requires code changes without first gathering facts.** Changing code based on a wrong hypothesis wastes user time.
-5. **When recommending a rebuild, say why + what to rebuild.** "pod install + rebuild iOS" is more useful than "try rebuilding."
-6. **If a symptom matches the Apple Privacy Manifest rejection, always paste the full 4-code XML.** Don't describe it; show it.
-
----
-
-## Skill routing reference
-
-| Skill | When to route |
-|---|---|
-| `cometchat-native-core` | Most "doesn't work" bugs trace back here — init/login/wrapper chain |
-| `cometchat-native-components` | Wrong prop / slot view / request builder |
-| `cometchat-native-placement` | Blank chat / bounded-height issues |
-| `cometchat-native-expo-patterns` | Expo-specific build errors (dev client required, `expo install`) |
-| `cometchat-native-bare-patterns` | Bare RN build errors (pod install, Android Maven, privacy manifest) |
-| `cometchat-native-theming` | Theme not applying, dark mode not switching, font not loading |
-| `cometchat-native-features` | Calls don't work, extension UI missing after enable |
-| `cometchat-native-customization` | Formatter not rendering, listener not firing, template not showing |
-| `cometchat-native-production` | 401 on token fetch, user-does-not-exist on login |
-| `cometchat-native-troubleshooting` | This skill — cross-category diagnosis + v4→v5 upgrade |