@cometchat/skills 4.4.2 → 5.0.0

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

@@ -1,594 +0,0 @@
----
-name: cometchat-native-push
-description: "Push notifications for React Native CometChat — APNs + FCM setup, dashboard provider configuration, client registration, token lifecycle, foreground display, background wake, tap-to-deep-link, and the Expo Go / APNs-environment traps that silently break production."
-license: "MIT"
-compatibility: "Node.js >=18; React Native >=0.70; @cometchat/chat-uikit-react-native ^5; @cometchat/chat-sdk-react-native ^4; @react-native-firebase/messaging ^18"
-metadata:
-  author: "CometChat"
-  version: "3.0.0"
-  tags: "cometchat react-native push notifications apns fcm firebase expo"
----
-
-## Purpose
-
-Teaches Claude how to add push notifications to a CometChat React Native integration — end-to-end, from Apple Developer / Google Cloud setup through CometChat dashboard provider configuration, client token registration, foreground/background handling, and tap-to-deep-link.
-
-**Push is non-negotiable for production chat.** Without it, a backgrounded app never wakes when a message arrives. The user doesn't see the message, doesn't re-open the app, and stops using chat. This is THE feature that separates "works in demo" from "works in production."
-
-Ground truth: `examples/SampleAppWithPushNotifications/` in `@cometchat/chat-uikit-react-native@5.3.3`, `docs/sdk/react-native/push-notification-setup.mdx`, and `https://www.cometchat.com/docs/notifications/push-integration`.
-
----
-
-## 1. The moving pieces
-
-Push spans four systems that must all agree:
-
-```
-┌─────────────┐    ┌─────────────┐    ┌──────────────┐    ┌────────┐
-│ Apple /     │    │ CometChat   │    │ CometChat    │    │ RN     │
-│ Google      │ →  │ Dashboard   │ →  │ server       │ →  │ client │
-│ (APNs/FCM)  │    │ (providers) │    │ (via SDK)    │    │ (app)  │
-└─────────────┘    └─────────────┘    └──────────────┘    └────────┘
- p8 key / JSON     Uploaded creds    Webhook on message   Displays notif
-```
-
-When user A sends a message to user B:
-1. CometChat server receives the message
-2. Looks up B's registered push tokens (client did this at login)
-3. Sends a push via APNs (iOS) or FCM (Android) using the credentials the dashboard holds
-4. B's device receives it, OS wakes the app (or fires foreground handler)
-5. Notification displays; tap → app navigates to the conversation
-
-All five steps must work. A broken step is almost always silent — no log, no error, just no notification. Debugging requires checking each layer.
-
----
-
-## 2. Expo Go CANNOT receive push notifications
-
-**This is the #1 support ticket from Expo users.** Expo Go is a prebuilt shell app without your custom native modules — it has no APNs entitlement, no FCM configuration, no way to receive your app's push.
-
-**For push, Expo projects require a development build:**
-```bash
-npx expo install expo-dev-client
-npx expo prebuild --clean   # generates ios/ + android/ with native configuration
-eas build --profile development --platform ios       # or android
-```
-
-Open the resulting `.ipa` / `.apk` and run `npx expo start --dev-client`. This is the only Expo setup that can receive push.
-
-If a user reports "I set everything up but no notifications arrive" and they're running Expo Go, that's the answer — no code fix will help.
-
----
-
-## 3. APNs setup (iOS)
-
-### 3a. Create an APNs Auth Key (p8)
-
-Apple's two options for signing push — certificate (`.p12`) or auth key (`.p8`). Use `.p8`. It never expires, one key works for all your apps, and CometChat accepts the simpler key format.
-
-1. https://developer.apple.com/account → **Certificates, Identifiers & Profiles** → **Keys** → "+"
-2. Name it (e.g., "CometChat APNs"), check **Apple Push Notifications service (APNs)**, Continue, Register
-3. **Download the `.p8` file** (one-time — Apple never lets you download it again)
-4. Copy the **Key ID** (10-char alphanumeric, shown on the key page)
-5. From the membership page, copy your **Team ID** (10-char alphanumeric, top-right)
-6. Collect your app's **Bundle ID** (from `ios/<Name>.xcodeproj` → Targets → General)
-
-You'll paste all four into the CometChat dashboard in §5.
-
-### 3b. Enable Push Notifications capability in Xcode
-
-```
-Open ios/<Name>.xcworkspace
-Select the project → Signing & Capabilities tab
-Click "+ Capability" → "Push Notifications"
-Click "+ Capability" → "Background Modes"
-  In Background Modes, check:
-    - Remote notifications
-    - Voice over IP (only if integrating CometChat calls)
-```
-
-This writes `aps-environment` (development or production) into the entitlements file. Wrong environment is the #1 silent-failure in §10.
-
-### 3c. Two environments — the TestFlight / App Store trap
-
-APNs has two parallel networks:
-- **Development** (`aps-environment: development`) — Xcode dev builds. Uses dev key paths.
-- **Production** (`aps-environment: production`) — TestFlight, App Store, Ad-Hoc. Uses prod key paths.
-
-The p8 auth key you generated in 3a works for **both** environments. But CometChat has to know which environment the token came from. If you upload the p8 only as "Development" in the dashboard, TestFlight builds silently fail — a token arrives from production APNs but the dashboard has no matching credentials.
-
-**Fix:** upload the same p8 twice in the CometChat dashboard — once as Development provider, once as Production provider. Then register with the matching provider ID at runtime (§7).
-
----
-
-## 4. FCM setup (Android)
-
-### 4a. Create a Firebase project + service account
-
-1. https://console.firebase.google.com → **Add project** → name it, continue through setup
-2. **Project Settings** (gear icon) → **Service accounts** tab
-3. **Generate new private key** → downloads a `.json` file with your server credentials
-
-This JSON file is what CometChat's dashboard needs.
-
-> **Coexistence check first (P0-10).** If `detect` reported `coexistence.existing_firebase: true` (a `firebase` / `@react-native-firebase/*` dep, an existing `google-services.json`, or a `GoogleService-Info.plist`), the app already uses Firebase. Reuse that **same** Firebase project + config files — don't add a second `google-services.json`/`initializeApp` or a duplicate `@react-native-firebase/app` plugin entry, which causes "Default FirebaseApp is not initialized" / duplicate-plugin prebuild failures. If a competing push provider (e.g. OneSignal) was listed in `coexistence.competing_sdks`, confirm with the user whether both should register for notifications before wiring CometChat's token registration — two providers fighting over the device token leads to dropped notifications.
-
-### 4b. Add Android app to Firebase + download google-services.json
-
-1. Project Overview → **Add app** → Android
-2. Enter your app's **package name** (from `android/app/build.gradle` → `applicationId`)
-3. Download `google-services.json`
-4. Place it at `android/app/google-services.json`
-5. Add this line at the end of `android/app/build.gradle`:
-   ```gradle
-   apply plugin: 'com.google.gms.google-services'
-   ```
-6. In `android/build.gradle` under `buildscript.dependencies`:
-   ```gradle
-   classpath 'com.google.gms:google-services:4.4.2'
-   ```
-
-**Expo managed:** `google-services.json` goes in the project root, and you reference it in `app.json`:
-```json
-{
-  "expo": {
-    "android": {
-      "googleServicesFile": "./google-services.json"
-    },
-    "plugins": ["@react-native-firebase/app", "@react-native-firebase/messaging"]
-  }
-}
-```
-
-### 4c. iOS Firebase config (if using firebase/messaging on iOS)
-
-`react-native-firebase/messaging` wraps APNs under the hood on iOS, so the APNs setup in §3 is what actually powers iOS push. BUT Firebase expects a `GoogleService-Info.plist` even though it doesn't route iOS push through FCM:
-1. Add iOS app in Firebase console (Project Overview → Add app → iOS)
-2. Download `GoogleService-Info.plist`
-3. Add it to `ios/<Name>/` via Xcode (Right-click project → Add Files)
-4. In Expo: put it at project root and reference in `app.json`:
-   ```json
-   { "expo": { "ios": { "googleServicesFile": "./GoogleService-Info.plist" } } }
-   ```
-
----
-
-## 5. CometChat dashboard — upload credentials
-
-https://app.cometchat.com → your app → **Notifications** → **Push Notifications**
-
-### 5a. Add an APNs provider (per environment)
-
-- **Add Provider** → choose APNs
-- Provider name: `apns-dev` (or similar)
-- Environment: **Development**
-- Upload the `.p8` file from §3a
-- Paste Key ID, Team ID, Bundle ID
-- Save → copy the **Provider ID** string (you'll need it in §7)
-
-Repeat for Production:
-- Provider name: `apns-prod`
-- Environment: **Production**
-- Same p8, Key ID, Team ID, Bundle ID
-- Save → copy the second Provider ID
-
-If you skip the production provider, TestFlight / App Store builds will silently not receive push.
-
-### 5b. Add an FCM provider
-
-- **Add Provider** → choose FCM
-- Provider name: `fcm-default`
-- Upload the service account `.json` file from §4a
-- Save → copy the Provider ID
-
-### 5c. Cache the Provider IDs
-
-You'll have 2-3 provider IDs. Store them in a config constant in your app:
-```ts
-// src/config/push.ts
-export const PUSH_PROVIDERS = {
-  fcm: "fcm-<hex-from-dashboard>",
-  apnsDev: "apns-dev-<hex-from-dashboard>",
-  apnsProd: "apns-prod-<hex-from-dashboard>",
-};
-```
-
-At runtime (§7), you'll pick the right one based on platform + `__DEV__`.
-
----
-
-## 6. Install client packages
-
-### Bare React Native
-
-```bash
-npm install @react-native-firebase/app @react-native-firebase/messaging \
-  @notifee/react-native @react-native-community/push-notification-ios
-
-cd ios && pod install && cd ..
-```
-
-- `@react-native-firebase/app` — initializes Firebase (reads GoogleService-Info.plist / google-services.json)
-- `@react-native-firebase/messaging` — FCM on Android AND APNs on iOS (Firebase handles both)
-- `@notifee/react-native` — local notification display (for foreground messages on Android; required because FCM data-only pushes don't auto-display)
-- `@react-native-community/push-notification-ios` — iOS APNs device token retrieval + notification tap handling (`getInitialNotification`, `addEventListener`)
-
-### Expo managed (dev build)
-
-```bash
-npx expo install @react-native-firebase/app @react-native-firebase/messaging \
-  @notifee/react-native @react-native-community/push-notification-ios expo-dev-client
-npx expo prebuild --clean
-```
-
-Then build a dev client (§2) and run `npx expo start --dev-client`.
-
-**iOS permissions in `ios/<Name>/Info.plist`:** no changes needed for basic push.
-
-**Android permissions in `android/app/src/main/AndroidManifest.xml`:**
-```xml
-<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
-<uses-permission android:name="android.permission.WAKE_LOCK" />
-```
-
-For Expo managed, put permissions in `app.json`:
-```json
-{
-  "expo": {
-    "android": {
-      "permissions": ["POST_NOTIFICATIONS", "WAKE_LOCK"]
-    }
-  }
-}
-```
-
----
-
-## 7. Register the push token with CometChat
-
-The canonical API — confirmed from `examples/SampleAppWithPushNotifications/src/utils/PushNotification.tsx`:
-
-```ts
-import { CometChatNotifications } from "@cometchat/chat-sdk-react-native";
-```
-
-`CometChatNotifications.PushPlatforms` enum values:
-
-| Platform | Enum value |
-|---|---|
-| Android (FCM) | `FCM_REACT_NATIVE_ANDROID` |
-| iOS (FCM — Firebase proxies APNs) | `FCM_REACT_NATIVE_IOS` |
-| iOS (APNs direct, non-VoIP) | `APNS_REACT_NATIVE_DEVICE` |
-| iOS (APNs VoIP — calls only) | `APNS_REACT_NATIVE_VOIP` |
-
-Most apps use FCM on both platforms (simpler — Firebase handles the APNs dance). Only use `APNS_REACT_NATIVE_DEVICE` if you're registering the raw APNs device token without Firebase in between.
-
-### 7a. Canonical register helper
-
-```ts
-// src/push/registerPushToken.ts
-import { Platform } from "react-native";
-import { CometChatNotifications } from "@cometchat/chat-sdk-react-native";
-import { PUSH_PROVIDERS } from "../config/push";
-
-export async function registerPushToken(token: string): Promise<void> {
-  const platform =
-    Platform.OS === "android"
-      ? CometChatNotifications.PushPlatforms.FCM_REACT_NATIVE_ANDROID
-      : CometChatNotifications.PushPlatforms.FCM_REACT_NATIVE_IOS;
-
-  // Single FCM provider covers both platforms when using firebase/messaging.
-  const providerId = PUSH_PROVIDERS.fcm;
-
-  try {
-    await CometChatNotifications.registerPushToken(token, platform, providerId);
-  } catch (err) {
-    console.error("[push] registerPushToken failed", err);
-  }
-}
-```
-
-### 7b. Fetch the FCM token and register (after login)
-
-```ts
-// src/push/bootstrap.ts
-import messaging from "@react-native-firebase/messaging";
-import { registerPushToken } from "./registerPushToken";
-
-export async function bootstrapPushAfterLogin(): Promise<void> {
-  await messaging().registerDeviceForRemoteMessages();
-  const token = await messaging().getToken();
-  await registerPushToken(token);
-
-  // Re-register when the token rotates (rare but it happens — new install, app restore).
-  messaging().onTokenRefresh(async (newToken) => {
-    await registerPushToken(newToken);
-  });
-}
-```
-
-Call `bootstrapPushAfterLogin()` in the same effect that runs `CometChatUIKit.login()`. Order matters — the SDK needs a logged-in user to associate the token with.
-
-### 7c. Unregister on logout
-
-```ts
-import { CometChatNotifications } from "@cometchat/chat-sdk-react-native";
-
-export async function unregisterPushTokenOnLogout(): Promise<void> {
-  try {
-    await CometChatNotifications.unregisterPushToken();
-  } catch (err) {
-    console.error("[push] unregisterPushToken failed", err);
-  }
-}
-```
-
-Call this BEFORE `CometChatUIKit.logout()` — after logout the SDK can't resolve the user to unregister the token against.
-
-If the user switches accounts without logging out (bad pattern, but it happens), re-register with the new user after login. CometChat auto-scopes push to the current user.
-
----
-
-## 8. Permissions — ask early, handle deny gracefully
-
-### iOS
-
-iOS prompts the user on the first call to `messaging().requestPermission()`. Do it early in the onboarding flow (post-login is fine), not in the first render — a permission prompt on app open looks hostile.
-
-```ts
-import messaging from "@react-native-firebase/messaging";
-
-async function requestIosPush(): Promise<boolean> {
-  const status = await messaging().requestPermission();
-  return (
-    status === messaging.AuthorizationStatus.AUTHORIZED ||
-    status === messaging.AuthorizationStatus.PROVISIONAL
-  );
-}
-```
-
-### Android
-
-Android 13+ requires the `POST_NOTIFICATIONS` runtime permission (prior versions grant it automatically from the manifest).
-
-```ts
-import { PermissionsAndroid, Platform } from "react-native";
-
-async function requestAndroidPush(): Promise<boolean> {
-  if (Platform.OS !== "android" || Platform.Version < 33) return true;
-  const status = await PermissionsAndroid.request(
-    PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS,
-  );
-  return status === PermissionsAndroid.RESULTS.GRANTED;
-}
-```
-
-### Handle deny
-
-If the user denies, don't retry — it just shows the system "open Settings" prompt. Surface a small UI nudge in chat settings: "Enable push notifications — so you know when you get a message." Link to `Linking.openSettings()`.
-
----
-
-## 9. Display, background, tap
-
-### 9a. Foreground messages (Android)
-
-FCM on Android delivers data-only pushes while the app is foregrounded — the OS does NOT display them automatically. You have to render a local notification with `@notifee/react-native`:
-
-```ts
-import messaging from "@react-native-firebase/messaging";
-import notifee, { AndroidImportance } from "@notifee/react-native";
-
-messaging().onMessage(async (remoteMessage) => {
-  const { title, body } = remoteMessage.data ?? {};
-  const channelId = await notifee.createChannel({
-    id: "chat-messages",
-    name: "Chat Messages",
-    importance: AndroidImportance.HIGH,
-  });
-  await notifee.displayNotification({
-    title: title ?? "New Message",
-    body: body ?? "You received a new message.",
-    android: { channelId, pressAction: { id: "default" } },
-    data: remoteMessage.data, // preserved for tap handling
-  });
-});
-```
-
-iOS foregrounding behavior is configured by `messaging().setForegroundNotificationPresentationOptions(...)` — set it once at app startup. Default is "don't display" (iOS assumes the app handles it), so you must opt-in to badges/banners/sounds.
-
-### 9b. Background / killed messages
-
-OS-delivered, no code needed. The notification displays as an OS notification. Tap handling: see §9c.
-
-### 9c. Tap to deep-link
-
-Three scenarios to handle:
-
-**iOS — app killed, tap opens the app:**
-```ts
-import PushNotificationIOS from "@react-native-community/push-notification-ios";
-
-async function checkInitialNotificationIOS(): Promise<void> {
-  const notification = await PushNotificationIOS.getInitialNotification();
-  if (!notification) return;
-  const data = notification.getData();
-  navigateFromPayload(data);
-}
-```
-
-**iOS — app in background, tap foregrounds:**
-```ts
-PushNotificationIOS.addEventListener("notification", (notification) => {
-  const data = notification.getData();
-  if (data.userInteraction === 1) {
-    navigateFromPayload(data);
-  }
-  notification.finish(PushNotificationIOS.FetchResult.NoData);
-});
-```
-
-**Android (via messaging):**
-```ts
-import messaging from "@react-native-firebase/messaging";
-
-// App killed → tap → opens app
-messaging().getInitialNotification().then((remoteMessage) => {
-  if (remoteMessage?.data) navigateFromPayload(remoteMessage.data);
-});
-
-// App backgrounded → tap → foregrounds
-messaging().onNotificationOpenedApp((remoteMessage) => {
-  if (remoteMessage?.data) navigateFromPayload(remoteMessage.data);
-});
-
-// Foreground local notification (displayed via notifee in §9a) → tap
-import notifee, { EventType } from "@notifee/react-native";
-notifee.onForegroundEvent(({ type, detail }) => {
-  if (type === EventType.PRESS) {
-    navigateFromPayload(detail.notification?.data ?? {});
-  }
-});
-```
-
-### 9d. Payload → navigation
-
-CometChat's push payload schema (confirmed from `examples/SampleAppWithPushNotifications/src/utils/helper.ts`):
-
-```ts
-{
-  type: "chat",
-  receiverType: "user" | "group",
-  sender: "<uid>",
-  receiver: "<uid-or-guid>",
-  conversationId: "<compound-id>",
-  unreadMessageCount: "<number-as-string>",
-  title: "Alice",
-  body: "Hey, you around?",
-  senderAvatar: "<url>",
-  tag: "<messageId>",
-  message: "<JSON-stringified-full-message>",   // parse for parentId, id, etc.
-}
-```
-
-Parse it into navigation params:
-
-```ts
-import { CometChat } from "@cometchat/chat-sdk-react-native";
-import { navigate } from "./NavigationService";   // createNavigationContainerRef wrapper
-
-async function navigateFromPayload(data: Record<string, unknown>): Promise<void> {
-  if (data.type !== "chat") return;
-
-  let parentMessageId: string | undefined;
-  if (typeof data.message === "string") {
-    try {
-      parentMessageId = JSON.parse(data.message).parentId;
-    } catch {}
-  }
-
-  if (data.receiverType === "group" && typeof data.receiver === "string") {
-    const group = await CometChat.getGroup(data.receiver);
-    navigate("Messages", { group, ...(parentMessageId ? { parentMessageId } : {}) });
-  } else if (data.receiverType === "user" && typeof data.sender === "string") {
-    const user = await CometChat.getUser(data.sender);
-    navigate("Messages", { user, ...(parentMessageId ? { parentMessageId } : {}) });
-  }
-}
-```
-
-Use React Navigation's `createNavigationContainerRef` so you can navigate from outside React (the tap handler fires before the component tree mounts on app launch):
-
-```ts
-// src/navigation/NavigationService.ts
-import { createNavigationContainerRef } from "@react-navigation/native";
-
-export const navigationRef = createNavigationContainerRef();
-
-export function navigate(name: string, params?: unknown): void {
-  if (navigationRef.isReady()) navigationRef.navigate(name as never, params as never);
-  else setTimeout(() => navigate(name, params), 100);   // wait for mount
-}
-```
-
-In the root layout:
-```tsx
-<NavigationContainer ref={navigationRef}>…</NavigationContainer>
-```
-
-For Expo Router, use the `router` from `expo-router` inside the tap handler — no navigation ref needed, but check `router.canGoBack()` before pushing on cold start.
-
----
-
-## 10. Badge count
-
-CometChat sends `unreadMessageCount` in the payload. Set it on iOS via `PushNotificationIOS.setApplicationIconBadgeNumber(count)` inside the notification handler. On Android, Notifee's `setBadgeCount()` works on most launchers but is inconsistent (Samsung, Xiaomi have their own rules).
-
-Reset badge to 0 when the user opens a conversation:
-```ts
-import { AppState, Platform } from "react-native";
-import PushNotificationIOS from "@react-native-community/push-notification-ios";
-import notifee from "@notifee/react-native";
-
-function clearBadge(): void {
-  if (Platform.OS === "ios") PushNotificationIOS.setApplicationIconBadgeNumber(0);
-  else notifee.setBadgeCount(0);
-}
-```
-
----
-
-## 11. Testing the push pipeline
-
-End-to-end verification — run each step in order and stop at the first failure. Silent failures are the norm, so testing each layer separately is faster than chasing a black box.
-
-1. **APNs alone** (iOS): In Firebase Console → Cloud Messaging → Send test message to your FCM token. If this arrives, Firebase + APNs are fine.
-2. **FCM alone** (Android): Same as above — Firebase test message. If it arrives, FCM + `google-services.json` are fine.
-3. **CometChat provider → device**: Send a message to the logged-in user from another user. If this fails but step 1/2 worked, the issue is in the CometChat dashboard provider config (wrong p8 environment, wrong bundle ID, expired service account).
-4. **Tap deep-links correctly**: Put the app in background, send a message, tap the notification. App should land on the right conversation.
-5. **TestFlight / App Store**: Build an archive, upload to TestFlight, install on a real device (NOT the simulator — iOS simulator cannot receive real APNs). Repeat step 3. This is where the "production APNs provider not uploaded" trap appears.
-
----
-
-## 12. Troubleshooting — common silent failures
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| Dev works, TestFlight doesn't | Production APNs provider not uploaded OR `aps-environment` is still `development` in release build | Upload prod p8 provider (§5a). Check `ios/<Name>/<Name>.entitlements` has `aps-environment: production` for Release config |
-| No iOS simulator notifications | Simulator can't receive real APNs | Use a real device |
-| `requestPermission()` never prompts | Already denied — prompt won't re-show | `Linking.openSettings()` and tell user to toggle Notifications on |
-| Token prints but no push arrives | Token registered BEFORE login | Call `registerPushToken` AFTER `CometChatUIKit.login` resolves |
-| Android foreground: OS notif shows | FCM delivered as notification + data (CometChat sends data-only now); old app code | Update to firebase/messaging ≥18 — old versions force auto-display |
-| Android foreground: nothing shows | No `onMessage` handler OR no notifee channel created | Add `messaging().onMessage` + `notifee.createChannel` (§9a) |
-| "Default FirebaseApp is not initialized" | google-services.json missing or build plugin not applied | Re-check §4b. Clean build: `cd android && ./gradlew clean` |
-| Notification tap doesn't navigate | NavigationContainer not ready when tap handler fires | Use the `setTimeout` retry pattern in `navigate()` (§9d) |
-| Expo app receives nothing in Expo Go | Expo Go can't receive push | Build a dev client (§2) |
-| Token refreshes but CometChat still uses old | `onTokenRefresh` listener not wired | Wire in `bootstrapPushAfterLogin` (§7b) |
-| Works for User A but not User B after logout | `unregisterPushToken` not called on logout | Call BEFORE `logout()` (§7c) |
-| iOS push arrives but `data` is empty | Payload is APS-only (no `content-available`) — CometChat default is correct; check if custom template stripped data | Check dashboard → Notifications → Template |
-
----
-
-## 13. Hard rules
-
-- **Register AFTER login.** The SDK needs a logged-in user to scope the token. Register before login and the token lands against "anonymous."
-- **Unregister BEFORE logout.** The SDK needs to know the user to dissociate the token.
-- **Call `onTokenRefresh`.** FCM rotates tokens. Missing the rotation means push stops working after a few weeks for some users.
-- **Upload both APNs environments.** Dev + Production. Missing Production = silent TestFlight/App Store breakage.
-- **Expo Go is a dead-end.** Build a dev client for push. No exceptions.
-- **Don't auto-display on Android foreground.** Show a local notification via Notifee so the user sees the message.
-- **Don't ship without testing on a real device.** iOS simulator doesn't receive real APNs.
-
----
-
-## 14. Skill routing
-
-| This skill | Covers |
-|---|---|
-| `cometchat-native-push` (this) | APNs + FCM + CometChat dashboard + client registration + tap handling |
-| `cometchat-native-core` | Init, login, four-wrapper chain, login concurrency guard |
-| `cometchat-native-features` | Calling SDK (`@cometchat/calls-sdk-react-native`) — push for VoIP is a separate channel (use `APNS_REACT_NATIVE_VOIP` + `react-native-voip-push-notification`) |
-| `cometchat-native-production` | Server-minted auth tokens + user CRUD. Register push only after login; if using auth tokens, register after `login({ authToken })` |
-| `cometchat-native-bare-patterns` | `pod install` + Xcode capability steps |
-| `cometchat-native-expo-patterns` | `expo prebuild` + dev client setup |
-| `cometchat-native-troubleshooting` | Metro cache, Podfile.lock, Android Maven. Push-specific symptoms are in §12 here |