@cometchat/skills 4.2.1 → 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
@@ -90,7 +99,10 @@ npm install dayjs punycode
 If the user's flow includes voice / video calls (the `cometchat-native-features` skill's § Calls gates this):
 
 ```bash
-npm install @cometchat/calls-sdk-react-native
+npm install @cometchat/calls-sdk-react-native \
+  react-native-url-polyfill \
+  react-native-performance \
+  valibot
 npx expo install \
   @react-native-community/netinfo \
   react-native-background-timer \
@@ -98,6 +110,8 @@ npx expo install \
   react-native-webrtc
 ```
 
+> **`react-native-url-polyfill`, `react-native-performance`, and `valibot` are not in the calls-sdk `peerDependencies` array** — but the calls-sdk's `dist/polyfills/browser.js` imports them at module top, so Metro fails the bundle without them. Omitting any of the three yields `Unable to resolve module …` at startup with no app render. (Validated 2026-05-26 on `@cometchat/calls-sdk-react-native@5.0.0` + Expo SDK 56.)
+
 Skip these until the user actually wants calls. Adding WebRTC to an Expo project bloats the prebuild and requires extra permissions — don't speculatively enable it.
 
 ---
@@ -153,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";
@@ -166,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>
@@ -181,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
 
@@ -275,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";
@@ -288,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>
@@ -339,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,
@@ -363,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>
   );
 }
@@ -443,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:
@@ -500,3 +535,18 @@ Push notifications need additional setup (APNs + FCM + maybe `expo-notifications
 | `cometchat-native-customization` | Text formatters, events, custom views |
 | `cometchat-native-production` | Server-side auth tokens + user management |
 | `cometchat-native-troubleshooting` | Prebuild failures, Expo Go errors, keyboard issues, blank chat |
+
+## Visual Builder integration (v4.3)
+
+If the customer picks **Visually** in dispatcher Step 3.1, the Expo recipe diverges from the standard provider chain. Skills runs `cometchat builder export --platform react-native --json` to emit `src/config/{store.ts, config.json}` (the Zustand-backed config store + 7-field envelope JSON), then patches `App.tsx` with `useConfig` + theme derivation.
+
+**Full recipe lives in `cometchat-native-core` §"Visual Builder integration".** Expo-specific notes:
+
+- Use `npx expo install` for the deps (not raw `npm install`) — Expo SDK pins compatible versions.
+- 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 |
 |---|---|---|---|
@@ -207,63 +206,92 @@ android {
 }
 ```
 
-### 3d — Register the call listener at app root
+### 3d — Register the call listeners at app root (incoming + outgoing + ongoing)
 
-The incoming-call UI only shows up if you've registered a listener to pick up call events. Add this once at the app root (typically in `App.tsx` or Expo Router's `_layout.tsx`):
+All three call surfaces — `<CometChatIncomingCall>`, `<CometChatOutgoingCall>`, `<CometChatOngoingCall>` — are parent-controlled. None auto-mount the others. The parent must register **both** `CometChat.addCallListener` (SDK socket; surfaces incoming calls from the network) **and** `CometChatUIEventHandler.addCallListener` (UI event bus; surfaces outgoing calls fired by `<CometChatCallButtons>` / `<CometChatMessageHeader>`). Add this once at the app root (typically in `App.tsx` or Expo Router's `_layout.tsx`). Validated 2026-05-26 against `@cometchat/chat-uikit-react-native@5.3.5` end-to-end on Pixel 3 ([[project_v4_3_f75_rn_call_ui_missing]]).
 
 ```tsx
-import React, { useEffect, useRef, useState } from "react";
+import React, { useEffect, useState } from "react";
+import { StyleSheet, View } from "react-native";
 import { CometChat } from "@cometchat/chat-sdk-react-native";
-import { CometChatIncomingCall } from "@cometchat/chat-uikit-react-native";
+import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
+import {
+  CometChatIncomingCall,
+  CometChatOutgoingCall,
+  CometChatOngoingCall,
+  CometChatUIEventHandler,
+} from "@cometchat/chat-uikit-react-native";
+
+const CALL_LISTENER_ID = "APP_CALL_LISTENER";
 
 function CallEventsProvider({ children }: { children: React.ReactNode }) {
-  const [callReceived, setCallReceived] = useState(false);
-  const incomingCall = useRef<CometChat.Call | null>(null);
-  const LISTENER_ID = "APP_CALL_LISTENER";
+  const [incomingCall, setIncomingCall] = useState<CometChat.Call | null>(null);
+  const [outgoingCall, setOutgoingCall] = useState<CometChat.Call | null>(null);
+  const [ongoingCall, setOngoingCall] = useState<CometChat.Call | null>(null);
 
   useEffect(() => {
+    // SDK socket — incoming side
     CometChat.addCallListener(
-      LISTENER_ID,
+      CALL_LISTENER_ID,
       new CometChat.CallListener({
-        onIncomingCallReceived: (call) => {
-          incomingCall.current = call;
-          setCallReceived(true);
-        },
-        onOutgoingCallAccepted: (call) => {
-          // navigate to the ongoing-call screen
-        },
-        onOutgoingCallRejected: () => {
-          incomingCall.current = null;
-          setCallReceived(false);
-        },
-        onIncomingCallCancelled: () => {
-          incomingCall.current = null;
-          setCallReceived(false);
-        },
-        onCallEndedMessageReceived: () => {
-          incomingCall.current = null;
-          setCallReceived(false);
-        },
+        onIncomingCallReceived: (call: CometChat.Call) => setIncomingCall(call),
+        onIncomingCallCancelled: () => setIncomingCall(null),
+        onOutgoingCallAccepted: () => {},   // kit owns the transition
+        onOutgoingCallRejected: () => setOutgoingCall(null),
       })
     );
-    return () => CometChat.removeCallListener(LISTENER_ID);
+    // UI event bus — outgoing side (fired by CallButtons / MessageHeader)
+    CometChatUIEventHandler.addCallListener(CALL_LISTENER_ID, {
+      ccOutgoingCall: ({ call }) => setOutgoingCall(call),
+      ccCallEnded: () => {
+        setOutgoingCall(null);
+        setIncomingCall(null);
+        setOngoingCall(null);
+      },
+      ccShowOngoingCall: ({ call }) => setOngoingCall(call),
+    });
+    return () => {
+      CometChat.removeCallListener(CALL_LISTENER_ID);
+      CometChatUIEventHandler.removeCallListener(CALL_LISTENER_ID);
+    };
   }, []);
 
   return (
     <>
       {children}
-      {callReceived && incomingCall.current && (
-        <CometChatIncomingCall
-          call={incomingCall.current}
-          onAccept={() => { /* navigate to ongoing-call screen */ }}
-          onDecline={() => setCallReceived(false)}
-        />
+      {incomingCall && (
+        <View style={StyleSheet.absoluteFill}>
+          <CometChatIncomingCall
+            call={incomingCall}
+            onDecline={() => setIncomingCall(null)}
+            onError={() => setIncomingCall(null)}
+          />
+        </View>
+      )}
+      {outgoingCall && (
+        <View style={StyleSheet.absoluteFill}>
+          <CometChatOutgoingCall call={outgoingCall} />
+        </View>
+      )}
+      {ongoingCall && (
+        <View style={StyleSheet.absoluteFill}>
+          {/* 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>
       )}
     </>
   );
 }
 ```
 
+> **DO NOT pass `onAccept` to `<CometChatIncomingCall>`** — short-circuits the kit's internal `acceptCall` + OngoingCall transition. The kit fires `ccShowOngoingCall` after `acceptCall` resolves; the listener above wires that into `setOngoingCall`, which mounts `<CometChatOngoingCall>`. Handle only `onDecline` + `onError` here. See `cometchat-native-calls` §1.8.c.
+
+> **DO NOT skip `CometChatUIEventHandler.addCallListener`.** Without it, tapping video/voice on `<CometChatMessageHeader>` fires WebRTC + camera at the native layer but no overlay UI ever mounts — the user sees nothing change after the tap. This was [[project_v4_3_f75_rn_call_ui_missing]] (F75).
+
 Wrap the app (inside the existing provider chain, below `CometChatProvider`):
 
 ```tsx
@@ -283,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} />
   )}
 />
 ```
@@ -307,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.
   );
 }
 ```
@@ -365,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()}
 />
 ```
 
@@ -565,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).
 
 ---