@cometchat/skills 4.3.0 → 4.4.0

package/skills/cometchat-native-expo-patterns/SKILL.md

@@ -3,7 +3,6 @@ name: cometchat-native-expo-patterns
 description: "Integration patterns for Expo managed workflow — app.json config, permissions, gesture handler setup, env vars, Expo Router file-based routing subsection."
 license: "MIT"
 compatibility: "Node.js >=18; Expo SDK >=50; @cometchat/chat-uikit-react-native ^5"
-allowed-tools: "shell, file-read, file-search, file-list, ask-user"
 metadata:
   author: "CometChat"
   version: "3.0.0"
@@ -24,7 +23,7 @@ Teaches Claude how to integrate CometChat into an Expo managed workflow project.
 
 **Read `cometchat-native-core` first** (init/login/wrapper chain + anti-patterns), then `cometchat-native-components` (prop reference), then `cometchat-native-placement` (where chat goes).
 
-Ground truth: `docs/ui-kit/react-native/expo-integration.mdx`, `expo-conversation.mdx`, `expo-one-to-one-chat.mdx`, `expo-tab-based-chat.mdx`, and `examples/SampleAppExpo/`.
+Ground truth: `docs/ui-kit/react-native/expo-integration.mdx`, `expo-conversation.mdx`, `expo-one-to-one-chat.mdx`, `expo-tab-based-chat.mdx`, and `examples/SampleAppExpo/`. **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).
 
 ---
 
@@ -81,8 +80,18 @@ npx expo install \
 
 # dayjs + punycode — no native code but required by the kit
 npm install dayjs punycode
+
+# Navigation — REQUIRED if you follow cometchat-native-placement's stack pattern
+# (createNativeStackNavigator + NavigationContainer). Not transitive — add them:
+npx expo install \
+  @react-navigation/native \
+  @react-navigation/native-stack \
+  react-native-screens \
+  expo-constants
 ```
 
+> **`expo-constants` is also imported directly** by Step 3 / Step 4 Option A (`import Constants from "expo-constants"`). It ships transitively with Expo, but importing it directly is a direct-dependency contract — the `expo install` line above lists it explicitly so a fresh install doesn't break.
+
 **Why `npx expo install` for the natively-linked deps?** `expo install` picks versions compatible with the project's Expo SDK. Using `npm install` directly can land incompatible versions that break prebuild.
 
 ### Optional — calling SDK
@@ -158,8 +167,8 @@ Expo projects use the same four-wrapper chain as bare RN (see `cometchat-native-
 import "react-native-gesture-handler";   // MUST be the first import
 import React from "react";
 import { GestureHandlerRootView } from "react-native-gesture-handler";
-import { SafeAreaProvider } from "react-native-safe-area-context";
-import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";
+import { SafeAreaProvider, SafeAreaView } from "react-native-safe-area-context";
+import { CometChatThemeProvider, CometChatI18nProvider } from "@cometchat/chat-uikit-react-native";
 import { CometChatProvider } from "./src/providers/CometChatProvider";
 import { AppNavigator } from "./src/navigation/AppNavigator";
 import Constants from "expo-constants";
@@ -171,14 +180,18 @@ export default function App() {
     <GestureHandlerRootView style={{ flex: 1 }}>
       <SafeAreaProvider>
         <CometChatThemeProvider>
-          <CometChatProvider
-            appId={extra.COMETCHAT_APP_ID}
-            region={extra.COMETCHAT_REGION}
-            authKey={extra.COMETCHAT_AUTH_KEY}
-            uid="cometchat-uid-1"   // dev mode only
-          >
-            <AppNavigator />
-          </CometChatProvider>
+          <CometChatI18nProvider>
+            <CometChatProvider
+              appId={extra.COMETCHAT_APP_ID}
+              region={extra.COMETCHAT_REGION}
+              authKey={extra.COMETCHAT_AUTH_KEY}
+              uid="cometchat-uid-1"   // dev mode only
+            >
+              <SafeAreaView edges={["top", "bottom"]} style={{ flex: 1 }}>
+                <AppNavigator />
+              </SafeAreaView>
+            </CometChatProvider>
+          </CometChatI18nProvider>
         </CometChatThemeProvider>
       </SafeAreaProvider>
     </GestureHandlerRootView>
@@ -186,7 +199,7 @@ export default function App() {
 }
 ```
 
-The `CometChatProvider` itself is defined per `cometchat-native-core` § 6 — reuse that implementation; don't invent another one.
+The provider chain matches the kit sample app (`examples/SampleApp/App.tsx`): `CometChatI18nProvider` sits inside `CometChatThemeProvider`, and a root `SafeAreaView edges={["top", "bottom"]}` wraps the navigator. The `CometChatProvider` itself is defined per `cometchat-native-core` § 6 — reuse that implementation; don't invent another one.
 
 ### `import "react-native-gesture-handler"` must be first
 
@@ -280,8 +293,8 @@ In Expo Router, the `app/_layout.tsx` file is the root layout — wrap the provi
 // app/_layout.tsx
 import "react-native-gesture-handler";
 import { GestureHandlerRootView } from "react-native-gesture-handler";
-import { SafeAreaProvider } from "react-native-safe-area-context";
-import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";
+import { SafeAreaProvider, SafeAreaView } from "react-native-safe-area-context";
+import { CometChatThemeProvider, CometChatI18nProvider } from "@cometchat/chat-uikit-react-native";
 import { CometChatProvider } from "../src/providers/CometChatProvider";
 import { Slot } from "expo-router";
 import Constants from "expo-constants";
@@ -293,14 +306,18 @@ export default function RootLayout() {
     <GestureHandlerRootView style={{ flex: 1 }}>
       <SafeAreaProvider>
         <CometChatThemeProvider>
-          <CometChatProvider
-            appId={extra.COMETCHAT_APP_ID}
-            region={extra.COMETCHAT_REGION}
-            authKey={extra.COMETCHAT_AUTH_KEY}
-            uid="cometchat-uid-1"
-          >
-            <Slot />   {/* Expo Router renders child routes here */}
-          </CometChatProvider>
+          <CometChatI18nProvider>
+            <CometChatProvider
+              appId={extra.COMETCHAT_APP_ID}
+              region={extra.COMETCHAT_REGION}
+              authKey={extra.COMETCHAT_AUTH_KEY}
+              uid="cometchat-uid-1"
+            >
+              <SafeAreaView edges={["top", "bottom"]} style={{ flex: 1 }}>
+                <Slot />   {/* Expo Router renders child routes here */}
+              </SafeAreaView>
+            </CometChatProvider>
+          </CometChatI18nProvider>
         </CometChatThemeProvider>
       </SafeAreaProvider>
     </GestureHandlerRootView>
@@ -344,7 +361,7 @@ export default function Home() {
 // app/messages/[uid].tsx
 import { useLocalSearchParams, router } from "expo-router";
 import { useEffect, useState } from "react";
-import { View } from "react-native";
+import { Platform, View } from "react-native";
 import { CometChat } from "@cometchat/chat-sdk-react-native";
 import {
   CometChatMessageHeader,
@@ -368,7 +385,10 @@ export default function ChatScreen() {
     <View style={{ flex: 1 }}>
       <CometChatMessageHeader user={user} onBack={() => router.back()} showBackButton />
       <CometChatMessageList user={user} hideReplyInThreadOption />
-      <CometChatMessageComposer user={user} />
+      <CometChatMessageComposer
+        user={user}
+        keyboardAvoidingViewProps={Platform.OS === "android" ? {} : { behavior: "padding" }}
+      />
     </View>
   );
 }
@@ -448,7 +468,17 @@ Subsequent runs use `npx expo start` with the dev client — no rebuild needed u
 ## Step 7 — Verify integration
 
 ```bash
-npx tsc --noEmit    # TypeScript check
+# ⚠️ Plain `npx tsc --noEmit` will report DOZENS of errors that are NOT yours.
+# The kit (@cometchat/chat-uikit-react-native) ships raw uncompiled .tsx and
+# points "types" at src/index, so tsc compiles the kit's own source into your
+# program. `skipLibCheck` (only skips .d.ts) and `exclude: [node_modules]`
+# (imported files are still checked) do NOT silence it. Verified on a clean
+# Expo SDK 56 + kit 5.3.7 + chat-sdk 4.0.24 install: 32 kit-internal errors.
+#
+# PASS CRITERION = zero errors OUTSIDE node_modules. Filter the kit noise:
+npx tsc --noEmit 2>&1 | grep -v node_modules | grep 'error TS'
+# ^ EMPTY output = your integration type-checks clean (PASS).
+#   Any line here = a real error in YOUR code — fix it.
 ```
 
 Then in the running app:
@@ -516,6 +546,7 @@ If the customer picks **Visually** in dispatcher Step 3.1, the Expo recipe diver
 - Env via `process.env.EXPO_PUBLIC_COMETCHAT_*` (no extra Babel plugin needed; Expo handles this).
 - Required additional deps beyond the standard provider set: `zustand`, `@react-native-async-storage/async-storage`.
 - `useConfig(s => s.settings.style)` — note the selector takes `AppConfig` directly, NOT `s.config.settings.style` (the `.config.` wrapper is internal to the Zustand store — Finding F6, 2026-05-21).
+- Envelope is `settings: { chatFeatures, callFeatures, layout, style, noCode }` — theme tokens live under `settings.style` (there's no `settings.theme`/`settings.agent`); the engagement feature group is `chatFeatures.deeperUserEngagement` (not `deeperEngagement`). See core §"Feature flag access".
 - A2 smoke validated: Metro bundles 10.8 MB iOS export clean on Expo SDK 54.
 
 If the customer picks **In code**, ignore this section — the standard four-wrapper chain + provider pattern from §"Provider chain" applies.

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

@@ -3,7 +3,6 @@ name: cometchat-native-features
 description: "Feature catalog for React Native — calls (separate SDK + WebRTC), extensions (polls / stickers / translation / link preview / collaborative doc / whiteboard / smart replies), AI agent, in-call chat. When to toggle, install, or swap."
 license: "MIT"
 compatibility: "Node.js >=18; React Native >=0.70; @cometchat/chat-uikit-react-native ^5"
-allowed-tools: "shell, file-read, file-search, file-list, ask-user"
 metadata:
   author: "CometChat"
   version: "3.0.0"
@@ -22,7 +21,7 @@ Ground truth: `docs/ui-kit/react-native/core-features.mdx`, `calling-integration
 
 ## 1. Feature taxonomy
 
-Every CometChat feature falls into exactly one of four categories. The category determines the recipe:
+Every CometChat feature falls into exactly one of these five **mechanism** categories — these tell you *how* to wire each feature (the actionable RN view). They map onto the product's canonical **5-tier "work-needed" model** (Core Zero-Setup → Builder-Enabled → Config-Only → Config+Settings → SDK-Integrated; see `cometchat-features` §3 + `packages/registry/v6/features/catalog.json`; canonical public matrix → [Features & Extensions Guide](https://www.cometchat.com/docs/fundamentals/features-and-extensions-guide), which outranks this snapshot on conflict): Default ≈ Core; Extension/AI ≈ Config-Only / Config+Settings; Package-install + Component-swap ≈ SDK-Integrated. The category determines the recipe:
 
 | Category | What it means | Example features | How to enable |
 |---|---|---|---|
@@ -215,6 +214,7 @@ All three call surfaces — `<CometChatIncomingCall>`, `<CometChatOutgoingCall>`
 import React, { useEffect, useState } from "react";
 import { StyleSheet, View } from "react-native";
 import { CometChat } from "@cometchat/chat-sdk-react-native";
+import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
 import {
   CometChatIncomingCall,
   CometChatOutgoingCall,
@@ -275,7 +275,12 @@ function CallEventsProvider({ children }: { children: React.ReactNode }) {
       )}
       {ongoingCall && (
         <View style={StyleSheet.absoluteFill}>
-          <CometChatOngoingCall call={ongoingCall} />
+          {/* CometChatOngoingCallInterface = { sessionID (required), callSettingsBuilder (required), onError? } — there is NO `call` prop (verified vs uikit-react-native-v5 CometChatOngoingCall.tsx) */}
+          <CometChatOngoingCall
+            sessionID={ongoingCall.getSessionId()}
+            callSettingsBuilder={new CometChatCalls.CallSettingsBuilder().setIsAudioOnlyCall(ongoingCall.getType() === "audio")}
+            onError={() => setOngoingCall(null)}
+          />
         </View>
       )}
     </>
@@ -306,13 +311,12 @@ Once the calls SDK is installed, `CometChatMessageHeader` auto-renders voice + v
   user={selectedUser}
   hideVoiceCallButton={false}
   hideVideoCallButton={false}
-  AuxiliaryButtonView={(user, group) => (
-    <CometChatCallButtons
-      user={user}
-      group={group}
-      onVoiceCallPress={(session) => navigation.navigate("OngoingCall", { session })}
-      onVideoCallPress={(session) => navigation.navigate("OngoingCall", { session })}
-    />
+  AuxiliaryButtonView={({ user, group }) => (
+    // Slot views receive ONE destructured object ({ user, group }) — NOT positional args.
+    // CometChatCallButtons has NO onVoiceCallPress/onVideoCallPress — it initiates the call
+    // itself and emits ccOutgoingCall / ccShowOngoingCall on the UI event bus. Mount the
+    // in-call surface from those listeners (§3d), not from a press callback.
+    <CometChatCallButtons user={user} group={group} />
   )}
 />
 ```
@@ -330,9 +334,12 @@ export function OngoingCallScreen({ route, navigation }: any) {
   return (
     <CometChatOngoingCall
       sessionID={session.sessionId}
-      callType={session.type}   // "audio" | "video"
-      onCallEnded={() => navigation.goBack()}
+      // REQUIRED: a CometChatCalls.CallSettingsBuilder instance (the kit calls .build() on it).
+      callSettingsBuilder={new CometChatCalls.CallSettingsBuilder().setIsAudioOnlyCall(session.type === "audio")}
+      onError={() => navigation.goBack()}
     />
+    // There is no `callType`/`onCallEnded` prop. End-of-call navigation is driven by the
+    // ccCallEnded listener (§3d) resetting the parent's state.
   );
 }
 ```
@@ -388,9 +395,9 @@ During an active call, users can chat without leaving the call UI. This is a tog
 ```tsx
 <CometChatOngoingCall
   sessionID={session.sessionId}
-  callType={session.type}
-  callSettingsBuilder={/* ... with enableInCallChat(true) */}
-  onCallEnded={() => navigation.goBack()}
+  // REQUIRED — a CometChatCalls.CallSettingsBuilder (enable in-call chat via its setter).
+  callSettingsBuilder={callSettingsBuilder}
+  onError={() => navigation.goBack()}
 />
 ```
 
@@ -588,7 +595,7 @@ When a user asks for a feature, use this flow:
 2. **Is it voice / video / call history?** → Calls (§ 3). Package install.
 3. **Is it polls, stickers, message translation, link preview, collaborative doc / whiteboard, thumbnails?** → Extension (§ 2). Run `cometchat apply-feature <id>`.
 3a. **Is it smart replies, conversation summary, or conversation starter?** → AI feature (§ 2). Run `cometchat apply-feature <id> --openai-key sk-...`.
-3b. **Is it Giphy / Stipop / Tenor / Chatwoot / Intercom / Disappearing Messages / Message Shortcuts?** → Dashboard-only (§ 2). User must enter third-party config in https://app.cometchat.com → Extensions.
+3b. **Is it Giphy / Stipop / Tenor / Chatwoot / Intercom / Disappearing Messages / Message Shortcuts?** → Dashboard-only (§ 2). User must enter third-party config in https://app.cometchat.com → Chat & Messaging → Features.
 4. **Is it AI agent?** → § 5.
 5. **Is it custom text formatting, custom message templates, custom slot views, custom theme?** → This is **customization**, not a feature. Route to `cometchat-native-customization` or `cometchat-native-theming`.
 6. **Not on this list?** → Check `docs/ui-kit/react-native/guide-overview.mdx` + the kit's `src/index.ts` exports. If still nothing, tell the user the feature isn't in the UI Kit; they may need to build it with the SDK directly.

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

@@ -3,7 +3,6 @@ name: cometchat-native-placement
 description: "Where to put chat in a React Native app — Stack screen, BottomTab, Modal, BottomSheet, Embedded. Maps each to CometChat component composition with ASCII layout references."
 license: "MIT"
 compatibility: "Node.js >=18; React Native >=0.70; @cometchat/chat-uikit-react-native ^5"
-allowed-tools: "shell, file-read, file-search, file-list, ask-user"
 metadata:
   author: "CometChat"
   version: "3.0.0"
@@ -19,7 +18,7 @@ Teaches Claude the five canonical placement patterns for putting chat inside a R
 3. Platform gotchas (safe-area, keyboard avoiding, gesture handling)
 4. When to choose this placement over the alternatives
 
-Ground truth: `docs/ui-kit/react-native/react-native-conversation.mdx`, `react-native-one-to-one-chat.mdx`, `react-native-tab-based-chat.mdx`, their `expo-*.mdx` equivalents, and the `examples/SampleApp/` + `examples/SampleAppExpo/` sample apps.
+Ground truth: `docs/ui-kit/react-native/react-native-conversation.mdx`, `react-native-one-to-one-chat.mdx`, `react-native-tab-based-chat.mdx`, their `expo-*.mdx` equivalents, and the `examples/SampleApp/` + `examples/SampleAppExpo/` sample apps. **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).
 
 **Read `cometchat-native-core` and `cometchat-native-components` before this skill** — the provider wrapper chain and component catalog are prerequisites.
 
@@ -155,7 +154,7 @@ export function ConversationsScreen({ navigation }: { navigation: NativeStackNav
 
 ```tsx
 // MessagesScreen.tsx
-import { View } from "react-native";
+import { Platform, View } from "react-native";
 import {
   CometChatMessageHeader,
   CometChatMessageList,
@@ -168,7 +167,11 @@ export function MessagesScreen({ route, navigation }: any) {
     <View style={{ flex: 1 }}>
       <CometChatMessageHeader user={user} group={group} onBack={() => navigation.goBack()} showBackButton />
       <CometChatMessageList user={user} group={group} hideReplyInThreadOption />
-      <CometChatMessageComposer user={user} group={group} />
+      <CometChatMessageComposer
+        user={user}
+        group={group}
+        keyboardAvoidingViewProps={Platform.OS === "android" ? {} : { behavior: "padding" }}
+      />
     </View>
   );
 }
@@ -176,13 +179,19 @@ export function MessagesScreen({ route, navigation }: any) {
 
 ```tsx
 // AppNavigator.tsx
+import { NavigationContainer } from "@react-navigation/native";
 import { createNativeStackNavigator } from "@react-navigation/native-stack";
 const Stack = createNativeStackNavigator();
 
-<Stack.Navigator screenOptions={{ headerShown: false }}>
-  <Stack.Screen name="Conversations" component={ConversationsScreen} />
-  <Stack.Screen name="Messages" component={MessagesScreen} />
-</Stack.Navigator>
+// The <Stack.Navigator> MUST be wrapped in <NavigationContainer> (react-navigation
+// throws "Couldn't find a navigation object" at runtime without it). One container
+// per app, at the root.
+<NavigationContainer>
+  <Stack.Navigator screenOptions={{ headerShown: false }}>
+    <Stack.Screen name="Conversations" component={ConversationsScreen} />
+    <Stack.Screen name="Messages" component={MessagesScreen} />
+  </Stack.Navigator>
+</NavigationContainer>
 ```
 
 ### Pattern B — Single thread (no conversation list)
@@ -220,7 +229,7 @@ export function SupportChatScreen() {
 
 - The screen is wrapped in a `<View style={{ flex: 1 }}>` so the composer sits at the bottom and the list fills the middle.
 - `CometChatMessageHeader`'s `onBack` should call `navigation.goBack()`. Set `showBackButton` explicitly so the header knows to render it.
-- **Keyboard avoiding**: when the composer is visible, RN needs `KeyboardAvoidingView` on iOS or `android:windowSoftInputMode="adjustResize"` on Android. The framework patterns (`cometchat-native-expo-patterns`, `cometchat-native-bare-patterns`) cover the platform-specific wiring.
+- **Keyboard avoiding**: do **not** wrap Header/List/Composer in an external `KeyboardAvoidingView`. The kit composer owns keyboard avoidance via its own `keyboardAvoidingViewProps` — pass `keyboardAvoidingViewProps={Platform.OS === 'android' ? {} : { behavior: 'padding' }}` on `<CometChatMessageComposer>` (this is what the kit sample app does). Android relies on the standard `android:windowSoftInputMode="adjustResize"` in the manifest, not the prop.
 
 ---
 
@@ -452,7 +461,7 @@ export function ProductDetailScreen({ product }: any) {
 
 - **Fixed height required.** CometChat components fill 100% of their parent. If you put them inside a `ScrollView` without a bounded height, the list collapses to zero height. Wrap in a `<View style={{ height: NNN }}>` or flex container with an explicit height.
 - **Scroll conflict.** If the parent is a `ScrollView`, the message list's internal scroll competes with the parent's scroll. Consider the single-thread-as-stack-screen pattern instead if the chat is a primary UX.
-- **Composer focus.** When the user taps the composer, the keyboard rises and can push the embedded chat off-screen on iOS. `keyboardShouldPersistTaps="handled"` on the parent ScrollView + `KeyboardAvoidingView` at the root help.
+- **Composer focus.** When the user taps the composer, the keyboard rises and can push the embedded chat off-screen on iOS. Set `keyboardShouldPersistTaps="handled"` on the parent ScrollView, and let the kit composer handle avoidance via `keyboardAvoidingViewProps={Platform.OS === 'android' ? {} : { behavior: 'padding' }}` — don't add your own root `KeyboardAvoidingView`.
 
 Usually the embedded pattern is the wrong default — prefer a Modal or BottomSheet trigger from a button on the screen, which gives users a dedicated surface for chatting.
 

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

@@ -3,7 +3,6 @@ name: cometchat-native-production
 description: "Production-readiness for React Native — server-minted auth tokens, user management CRUD, external-backend recipes (Express / Hono / Firebase Functions / Vercel Serverless). RN has no API routes, so the backend is always external."
 license: "MIT"
 compatibility: "Node.js >=18; React Native >=0.70; @cometchat/chat-uikit-react-native ^5"
-allowed-tools: "shell, file-read, file-search, file-list, ask-user"
 metadata:
   author: "CometChat"
   version: "3.0.0"
@@ -23,7 +22,7 @@ Teaches Claude how to move a React Native CometChat integration from dev-mode Au
 
 **Read `cometchat-native-core` first** (init/login/wrapper chain) before this skill — production just swaps one prop on the provider, but understanding the provider lifecycle is the prerequisite.
 
-Ground truth: `docs/ui-kit/react-native/methods.mdx`, and the cross-platform REST API at `https://{APP_ID}.api-{REGION}.cometchat.io/v3/`.
+Ground truth: `docs/ui-kit/react-native/methods.mdx`, and the cross-platform REST API at `https://{APP_ID}.api-{REGION}.cometchat.io/v3/`. **Official docs:** https://www.cometchat.com/docs/fundamentals/user-auth · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP).
 
 ---
 
@@ -253,7 +252,14 @@ let initialized = false;
 let loginInFlight: Promise<unknown> | null = null;
 
 async function ensureLoggedIn(authToken?: string, uid?: string): Promise<void> {
-  const existing = await CometChatUIKit.getLoggedInUser();
+  // getLoggedInUser() THROWS { code: "NOT_FOUND" } when there's no session — it does NOT
+  // return null. An uncaught throw here leaves the app stuck on splash (see core §2/§6).
+  let existing;
+  try {
+    existing = await CometChatUIKit.getLoggedInUser();
+  } catch (e: any) {
+    if (e?.code !== "NOT_FOUND") throw e;   // no-session is the expected first-run path
+  }
   if (existing) return;
   if (loginInFlight) {
     await loginInFlight;

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

@@ -3,7 +3,6 @@ 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"
-allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"
@@ -112,6 +111,8 @@ The p8 auth key you generated in 3a works for **both** environments. But CometCh
 
 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

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

@@ -3,7 +3,6 @@ name: cometchat-native-testing
 description: "Testing patterns for CometChat React Native — Jest + React Native Testing Library setup, mocking the UI Kit + SDK, testing custom bubbles / headers / composer actions, snapshot pitfalls, E2E with Detox vs Maestro, and CI integration. Covers what to test vs what to skip."
 license: "MIT"
 compatibility: "Node.js >=18; React Native >=0.70; @cometchat/chat-uikit-react-native ^5; Jest ^29; @testing-library/react-native ^12"
-allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"
@@ -21,7 +20,7 @@ Teaches Claude how to write and run tests against a CometChat React Native integ
 - E2E with Detox (iOS + Android native drivers) vs Maestro (declarative YAML)
 - Which tests catch real regressions vs which are flaky churn
 
-Ground truth: `@cometchat/chat-uikit-react-native@5.3.3`'s example jest config (`examples/SampleAppWithPushNotifications/jest.config.js`) and the standard RN testing toolkit docs (callstack.github.io/react-native-testing-library, wix.github.io/Detox, maestro.mobile.dev).
+Ground truth: `@cometchat/chat-uikit-react-native@5.3.3`'s example jest config (`examples/SampleAppWithPushNotifications/jest.config.js`) and the standard RN testing toolkit docs (callstack.github.io/react-native-testing-library, wix.github.io/Detox, maestro.mobile.dev). **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).
 
 ---
 

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

@@ -3,7 +3,6 @@ name: cometchat-native-theming
 description: "CometChatThemeProvider + CometChatI18nProvider — color tokens, typography, dark mode, per-component style overrides, and localization (18 built-in languages + custom translations). The JS theme object replaces CSS variables."
 license: "MIT"
 compatibility: "Node.js >=18; React Native >=0.70; @cometchat/chat-uikit-react-native ^5"
-allowed-tools: "shell, file-read, file-search, file-list, ask-user"
 metadata:
   author: "CometChat"
   version: "3.0.0"
@@ -16,7 +15,7 @@ Teaches Claude how to theme and localize the React Native UI Kit via `CometChatT
 
 **Read `cometchat-native-core` first** (the wrapper chain that includes `CometChatThemeProvider`) before this skill. `cometchat-native-components` § 13 covers per-component `style={}` overrides, which are a sibling concern to theming.
 
-Ground truth: `docs/ui-kit/react-native/theme.mdx`, `colors.mdx`, `component-styling.mdx`, `message-bubble-styling.mdx`, and `packages/ChatUiKit/src/theme/type.ts` (the canonical type definitions).
+Ground truth: `docs/ui-kit/react-native/theme.mdx`, `colors.mdx`, `component-styling.mdx`, `message-bubble-styling.mdx`, and `packages/ChatUiKit/src/theme/type.ts` (the canonical type definitions). **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).
 
 ---
 
@@ -308,10 +307,18 @@ The theme has a `typography` block with tokens per role:
   theme={{
     light: {
       typography: {
-        heading1: { fontFamily: "Inter-Bold", fontSize: 28, fontWeight: "700" },
-        heading2: { fontFamily: "Inter-SemiBold", fontSize: 20 },
-        body1: { fontFamily: "Inter-Regular", fontSize: 15 },
-        caption1: { fontFamily: "Inter-Regular", fontSize: 12 },
+        fontFamily: "Inter",   // flat string — the global family
+        // Every role EXCEPT `fontFamily`/`link` is a variant object with
+        // `bold` / `medium` / `regular`, each an RN TextStyle:
+        heading1: {
+          bold:    { fontFamily: "Inter-Bold", fontSize: 28, fontWeight: "700" },
+          medium:  { fontFamily: "Inter-SemiBold", fontSize: 28, fontWeight: "600" },
+          regular: { fontFamily: "Inter-Regular", fontSize: 28, fontWeight: "400" },
+        },
+        body: {
+          regular: { fontFamily: "Inter-Regular", fontSize: 15 },
+        },
+        link: { fontFamily: "Inter-Regular", fontSize: 15 }, // `link` is a flat TextStyle
         // ... etc
       },
     },
@@ -319,7 +326,7 @@ The theme has a `typography` block with tokens per role:
 >
 ```
 
-Common tokens: `heading1`, `heading2`, `heading3`, `heading4`, `body1`, `body2`, `caption1`, `caption2`, `button1`, `button2`. Each follows the RN `TextStyle` shape — `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`.
+Common tokens: `title`, `heading1`, `heading2`, `heading3`, `heading4`, `body`, `caption1`, `caption2`, `button` (there is NO `body1/body2/button1/button2`). Each of these is a **variant object** `{ bold, medium, regular }` where each weight is an RN `TextStyle` (`fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`). The two exceptions — `fontFamily` and `link` — are flat (a string and a single `TextStyle` respectively).
 
 ### Custom font setup
 
@@ -345,18 +352,17 @@ Beyond color / typography, the theme has per-component style blocks for fine con
         containerStyle: { backgroundColor: "#FAFAFA" },
       },
       messageHeaderStyles: {
-        titleStyle: { fontSize: 18 },
+        titleTextStyle: { fontSize: 18 },   // key is titleTextStyle, NOT titleStyle
       },
       messageListStyles: {
         containerStyle: { padding: 8 },
-        sendBubbleStyle: {
-          backgroundColor: "#F76808",
-          textStyle: { color: "#FFFFFF" },
-        },
-        receiveBubbleStyle: {
-          backgroundColor: "#F5F5F5",
-          textStyle: { color: "#141414" },
-        },
+        // Bubble styling is NESTED — the keys are `incomingMessageBubbleStyles`
+        // and `outgoingMessageBubbleStyles` (each a DeepPartial<BubbleStyles>
+        // with `containerStyle`/`textBubbleStyles`/… — there is no flat
+        // `sendBubbleStyle`/`receiveBubbleStyle` with backgroundColor+textStyle).
+        // For simple bubble color changes, prefer the color tokens in §7
+        // (sendBubbleBackground / receiveBubbleBackground) — cleaner than the
+        // per-component bubble blocks.
       },
       messageComposerStyles: {
         containerStyle: { backgroundColor: "#FFF", borderTopWidth: 1, borderTopColor: "#E8E8E8" },
@@ -366,7 +372,7 @@ Beyond color / typography, the theme has per-component style blocks for fine con
 >
 ```
 
-Common component-style keys: `conversationStyles`, `usersStyles`, `groupsStyles`, `groupMembersStyles`, `messageHeaderStyles`, `messageListStyles`, `messageComposerStyles`, `threadHeaderStyles`, `callButtonsStyles`, `callLogsStyles`.
+Common component-style keys (exact names from `theme/type.ts`): `conversationStyles`, `userStyles`, `groupStyles`, `groupMemberStyle` (singular "Member" + singular "Style"), `messageHeaderStyles`, `messageListStyles`, `messageComposerStyles`, `threadHeaderStyles`, `callButtonStyles` (no "s" after "Button"), `callLogsStyles`. Note the irregular pluralization — `userStyles`/`groupStyles` are singular-noun, and `groupMemberStyle`/`callButtonStyles` don't follow the `*Styles` pattern.
 
 Each block has the same nested shape as the component's `style` prop (see `cometchat-native-components` § 13).
 
@@ -436,17 +442,18 @@ Overriding the bubble tokens directly is cleaner than doing it via `messageListS
 <CometChatThemeProvider
   theme={{
     light: {
+      // Roles: title, heading1-4, body, caption1, caption2, button (NO body1/body2/button1/button2).
+      // Each role is a VARIANT object { bold, medium, regular } — not a flat { fontFamily }.
+      // Verified vs uikit-react-native-v5 theme/default/typography.ts.
       typography: {
-        heading1: { fontFamily: "Inter-Bold" },
-        heading2: { fontFamily: "Inter-SemiBold" },
-        heading3: { fontFamily: "Inter-SemiBold" },
-        heading4: { fontFamily: "Inter-Medium" },
-        body1: { fontFamily: "Inter-Regular" },
-        body2: { fontFamily: "Inter-Regular" },
-        caption1: { fontFamily: "Inter-Regular" },
-        caption2: { fontFamily: "Inter-Regular" },
-        button1: { fontFamily: "Inter-SemiBold" },
-        button2: { fontFamily: "Inter-Medium" },
+        heading1: { bold: { fontFamily: "Inter-Bold" } },
+        heading2: { bold: { fontFamily: "Inter-SemiBold" } },
+        heading3: { medium: { fontFamily: "Inter-SemiBold" } },
+        heading4: { medium: { fontFamily: "Inter-Medium" } },
+        body: { regular: { fontFamily: "Inter-Regular" } },
+        caption1: { regular: { fontFamily: "Inter-Regular" } },
+        caption2: { regular: { fontFamily: "Inter-Regular" } },
+        button: { medium: { fontFamily: "Inter-Medium" } },
       },
     },
   }}
@@ -467,8 +474,9 @@ function CustomTitle({ user }: any) {
   return (
     <Text style={{
       color: theme.color.textPrimary,
-      fontFamily: theme.typography.heading3.fontFamily,
-      fontSize: theme.typography.heading3.fontSize,
+      // heading3 is a variant object — read a weight (regular/medium/bold):
+      fontFamily: theme.typography.heading3.regular.fontFamily,
+      fontSize: theme.typography.heading3.regular.fontSize,
     }}>
       {user.getName()}
     </Text>
@@ -597,6 +605,23 @@ Calling `useCometChatTranslation()` from a component rendered OUTSIDE `CometChat
 
 ---
 
+## Sound Manager — custom notification & call sounds
+
+Sounds are a **behavioral** customization (not styling) — driven by `CometChatSoundManager`, exported from the kit. The UI Kit plays the built-in cues automatically; use this to override or trigger them. Sound-event keys are passed as strings. (Docs: ui-kit/react-native/sound-manager.)
+
+```tsx
+import { CometChatSoundManager } from "@cometchat/chat-uikit-react-native";
+
+// Play a default cue — keys: incomingMessage | incomingMessageFromOther
+//                              | outgoingMessage | incomingCall | outgoingCall
+CometChatSoundManager.play("incomingMessage");
+
+// Stop whatever is playing
+CometChatSoundManager.pause();
+```
+
+> RN audio assets differ from web URLs — for custom sounds, follow the per-platform asset guidance in ui-kit/react-native/sound-manager rather than passing a web URL.
+
 ## 10. Anti-patterns
 
 1. **Don't pass non-hex colors.** `"rgb(...)"`, `"rgba(...)"`, named colors, or `hsl(...)` will break the kit's internal color math (used to derive `extendedPrimary`). Use `"#RRGGBB"` or `"#RRGGBBAA"` (opacity via alpha).

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

@@ -3,7 +3,6 @@ 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"
-allowed-tools: "shell, file-read, file-search, file-list, ask-user"
 metadata:
   author: "CometChat"
   version: "3.0.0"
@@ -16,7 +15,7 @@ Teaches Claude how to diagnose and fix CometChat React Native integration failur
 
 **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.
+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).
 
 ---
 
@@ -90,6 +89,9 @@ 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
@@ -152,6 +154,9 @@ Quick-reference tables. Work through in order; if none match, drop into § 3 dee
 | 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
 
@@ -460,7 +465,8 @@ cd ios && pod install && cd ..
 
 If none of the lookup tables or deep dives apply:
 
-1. **Read the raw error.** RN errors are usually specific ("Module 'X' not found in app 'Y'" is different from "TurboModuleRegistry.getEnforcing").
+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.