@cometchat/skills 4.4.1 → 5.0.0

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

@@ -0,0 +1,116 @@
+---
+name: cometchat-react-native-expo-patterns
+description: "Expo-specific wiring for the CometChat React Native UI Kit v5 — why Expo Go cannot work, development builds, app.json permissions, and the Expo-only extra dependency. Triggers: CometChat in Expo, Expo chat app, expo development build CometChat, Expo Go chat not working, expo run ios CometChat."
+license: "MIT"
+compatibility: "Expo SDK >=53 (development builds; ships React Native 0.79 — SDK 52 ships RN 0.76, below the pack's RN floor); React Native >=0.77; @cometchat/chat-uikit-react-native ^5.4.0"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "chat cometchat react-native expo development-build app-json permissions"
+---
+
+> **Ground truth:** `@cometchat/chat-uikit-react-native@5` + catalog `rn-v5.json`.
+> Docs: `/ui-kit/react-native/expo-integration` · `expo-conversation` · `expo-tab-based-chat`.
+
+## Companion skills (read first)
+- `cometchat-react-native-core` — install, provider chain, init→login→render. Assumed, not repeated here.
+- `cometchat-react-native-bare-patterns` — the bare React Native CLI equivalent. Use that one, not this, for a non-Expo app.
+
+## Use this skill when
+- the project has `app.json`/`app.config.js` with an `expo` key, or `expo` in `package.json`
+- "add chat to my Expo app" · "chat isn't working in Expo Go"
+
+## Prerequisites & install
+
+### ⚠️ Expo Go does not work — and this is the #1 support issue
+The UI Kit ships **custom native modules**. Expo Go is a fixed prebuilt binary that cannot load them.
+There is no workaround, no config flag, and nothing to fix in code. You need a **development build**.
+
+Symptom: the app runs in Expo Go but chat screens crash or render nothing, with a NativeModule error
+that names `gesture-handler` / `svg` / `video` rather than CometChat — so it reads as unrelated.
+
+```bash
+npx expo run:ios      # or: npx expo run:android
+```
+
+Both produce a development build. From then on use that build, not Expo Go.
+
+### Packages
+Same list as bare RN, **plus `punycode`, which is Expo-only**:
+
+```bash
+npm install @cometchat/chat-uikit-react-native@5 @cometchat/chat-sdk-react-native@4
+npm install @react-native-clipboard/clipboard \
+  react-native-svg react-native-video react-native-localize react-native-gesture-handler \
+  react-native-safe-area-context @react-native-async-storage/async-storage@^2.1.2 dayjs punycode
+```
+
+## Native config lives in `app.json` — never in ios/ or android/
+
+This is the whole Expo/bare divergence: Expo **generates** the native projects, so hand-editing
+`Info.plist` or `AndroidManifest.xml` is pointless — the next prebuild overwrites it. Declare
+permissions in `app.json` and let Expo write them:
+
+```json
+{
+  "expo": {
+    "ios": {
+      "infoPlist": {
+        "NSCameraUsageDescription": "Camera access for video calls",
+        "NSMicrophoneUsageDescription": "Microphone access for voice/video calls"
+      }
+    },
+    "android": {
+      "permissions": [
+        "android.permission.INTERNET",
+        "android.permission.CAMERA",
+        "android.permission.MODIFY_AUDIO_SETTINGS",
+        "android.permission.RECORD_AUDIO",
+        "android.permission.ACCESS_NETWORK_STATE",
+        "android.permission.BLUETOOTH_CONNECT",
+        "android.permission.VIBRATE"
+      ]
+    }
+  }
+}
+```
+- **`BLUETOOTH_CONNECT`** (Android 12+) lets calls route audio to a Bluetooth headset — `/calls/react-native/setup` lists it; the calls SDK's own manifest only merges the legacy `BLUETOOTH`.
+- **No `READ_`/`WRITE_EXTERNAL_STORAGE`**, though the `expo-integration` page lists them: they are no-ops on modern Android (WRITE from 11, READ from 13), and the UI Kit's own manifest already merges them for older devices.
+
+After changing `app.json`, **rebuild** — a JS reload will not pick up a native permission change.
+
+## Calling on Expo
+Calling adds native WebRTC, so it needs a fresh development build too:
+
+```bash
+npm install @cometchat/calls-sdk-react-native@5
+# 6 REQUIRED peer deps — the calls SDK's declared peerDependencies. Pinned; do NOT float them.
+npm install @react-native-async-storage/async-storage@^2.1.2 react-native-background-timer@^2.4.1 \
+  react-native-performance@^5.1.2 react-native-svg@^15.12.0 react-native-url-polyfill@2.0.0 \
+  react-native-webrtc@124.0.7
+npx expo run:ios
+```
+⚠️ `react-native-url-polyfill` + `react-native-performance` are **bundle-critical** (the UIKit
+module-scope `require()`s the calls SDK, so Metro resolves its peers even in a chat-only build — a
+missing one fails the bundle). Keep `react-native-performance` on **5.x** (a floated `^6` breaks every
+later `npm install` with ERESOLVE). `@react-native-community/netinfo` / `react-native-callstats` are
+NOT declared peers — do not add them.
+
+Simulators cannot capture camera or microphone — verify calls on a real device.
+
+## What is the same as bare RN
+Everything above the native layer: the provider chain, `init → login → render`, every component,
+theming, navigation. Only install and native config differ. Do not re-derive app code per toolchain.
+
+## Common pitfalls
+1. **Testing in Expo Go** — custom native modules cannot load. Development build, always.
+2. **Editing `ios/` or `android/` directly** — prebuild overwrites it. Use `app.json`.
+3. **Forgetting `punycode`** — Expo-only, and its absence surfaces as an unrelated module error.
+4. **Reloading JS after an `app.json` change** — native config needs a rebuild.
+5. **Expecting calls to work on a simulator** — no camera or mic capture.
+
+## Verify it works
+- The app runs from a development build, not Expo Go.
+- `npm run verify:fences:rn-v5` is green.
+- On device: chat renders, the composer survives the keyboard, gestures respond, and — if calling is
+  installed — the permission prompts appear on first call.

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

@@ -0,0 +1,122 @@
+---
+name: cometchat-react-native-features
+description: "Turn a named CometChat capability on in a React Native app — look it up in the feature oracle, take the right enablement branch (already-on / dashboard extension / AI toggle / npm package / SDK fallback), and wire only what that branch needs. Triggers: enable reactions React Native, add polls RN chat, turn on smart replies RN, add voice video calling RN, enable message translation RN, add stickers RN, enable read receipts, typing indicator React Native, collaborative whiteboard."
+license: "MIT"
+compatibility: "React Native >=0.77; @cometchat/chat-uikit-react-native ^5.4.0; @cometchat/chat-sdk-react-native ^4.0.28"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "chat cometchat react-native features extensions enablement dashboard ai calls"
+---
+
+> **Ground truth:** `features.rn-v5.json` (48 entries) + catalog `rn-v5.json`.
+> **The oracle decides, not memory.** Every claim below — whether a capability exists, whether it is
+> on by default, which components render it — comes from that file. Fetch props via
+> `core/references/docs-map.md`.
+
+## Companion skills (read first)
+- `cometchat-react-native-core` — install, provider chain, init→login→render. Assumed, not repeated here.
+
+## Use this skill when
+- "enable reactions / polls / translation / stickers" · "turn on smart replies"
+- "add voice and video calling" · "is X supported" · "how do I switch on Y"
+
+## Prerequisites & install
+None beyond `core` unless the feature's branch says otherwise (only two features install a package).
+
+## Step 1 — look the feature up in the oracle
+
+Find the entry in `features.rn-v5.json`. **If there is no entry, the feature does not exist** — say so
+rather than inventing an API. The entry tells you everything:
+
+| Field | What it decides |
+|---|---|
+| `category` · `enablement` | which branch below to take |
+| `ui_components` | what to render (all validated against the catalog) |
+| `sdk_fallback` | the SDK methods to use when the kit has **no** component |
+| `needs_stitching` | you must wire host state, not just drop a component in |
+| `needs_dashboard` | a dashboard toggle is required as well as code |
+| `auto_rendered_ui` | **the kit renders it — emit no client code** |
+| `platform_delta` | how React Native differs from React here. Read it before writing anything. |
+| `docs_gap` | the docs don't cover this yet — flag it, don't silently source-fill |
+
+## Step 2 — take exactly one branch
+
+### A. Already on — `category: default`, `enablement: auto` (12 features)
+Nothing to enable. Reactions, mentions, typing indicators, receipts, threads and attachments are
+**core messaging in v5**, not extensions.
+
+⚠️ **Do not offer these as "enable this extension".** The dashboard still lists legacy Reactions and
+Mentions extensions; their own docs say they are already part of core and scheduled for deprecation.
+Suggesting them is a bug, not a helpful extra — it is the exact defect the React pack hit (AUDIT-077).
+Customization is via component props, not enablement.
+
+### B. Dashboard extension — `enablement: dashboard-extension` (20 features)
+Enable in the CometChat dashboard **first**, then wire any `ui_components`. Polls, stickers,
+translation, link preview, whiteboard, document and similar. Without the dashboard step the code
+compiles and silently does nothing.
+
+Some are `auto_rendered_ui: true` (e.g. polls' bubble) — the message list renders them once enabled.
+**Emit no client code for those**; hand-wiring produces a duplicate.
+
+### C. AI — `category: ai`, `needs_dashboard: true` (4 features)
+Two steps, and the second is the one people miss: enable the feature in the dashboard **and** set the
+code prop. The props default to **off**, so a dashboard-only change looks like nothing happened.
+Smart replies, conversation starter, conversation summary, AI assistant.
+Fetch the exact prop name from `/ui-kit/react-native/ai-features.md` — do not guess it.
+
+### D. npm package — `enablement: npm-package` (2 features)
+Only calling. React Native needs its **own** calls SDK:
+
+```bash
+npm install @cometchat/calls-sdk-react-native@5   # + its 6 pinned peer deps — exact list in cometchat-react-native-calls
+cd ios && pod install
+```
+
+⚠️ **Not `@cometchat/calls-sdk-javascript`** — that is the web package and will not work.
+Its peers include `react-native-webrtc`, a native module: declare camera and microphone permissions
+(`NSCameraUsageDescription` / `NSMicrophoneUsageDescription`; `CAMERA` / `RECORD_AUDIO`).
+**Simulators cannot capture camera or mic — calling must be verified on a real device.**
+Depth lives in `cometchat-react-native-calls`.
+
+### E. SDK fallback — the kit has no component (3 features)
+Kit v5 removed the detail and management screens. `sdk_fallback` names the methods:
+
+| Feature | Why | Use |
+|---|---|---|
+| `group-member-management` | no add/ban/transfer components | `addMembersToGroup` · `banGroupMember` · `unbanGroupMember` · `transferGroupOwnership` · `BannedMembersRequestBuilder` |
+| `user-group-details` | no details component | `getUser` · `getGroup` · `updateGroup` |
+| `call-log-details` | only the list ships | `CometChatCalls.CallLogRequestBuilder` (**calls** SDK) |
+
+> **Banned members have no UI surface at all.** An app that can ban but cannot view or unban is an
+> unclosed round-trip — ship both halves.
+
+Do not invent a layout: cite the official sample app's implementation
+(`github.com/cometchat/cometchat-uikit-react-native/tree/v5/examples/SampleApp`). Those are sample-app
+**directory paths**, never imports.
+
+## Step 3 — wire only what the branch needs
+Render the entry's `ui_components` and nothing else. A feature that is `auto_rendered_ui` gets **no**
+client code. A feature that is `needs_stitching` gets host state and callbacks wired, not just a mount.
+
+Never enable a neighbouring feature because it seemed related — that is unrequested scope.
+
+## Known docs gaps (flag, don't silently source-fill)
+`reactions` · `typing-indicators` · `delivery-read-receipts` · `media-file-attachments` (the whole
+multi-attachment cluster) · and the three SDK-fallback features above carry a `docs_gap` marker.
+Build from the catalog and kit source, and **tell the developer the page is missing**.
+
+## Common pitfalls
+1. **Offering reactions/mentions as an extension** — they are core in v5; the dashboard entries are legacy.
+2. **Dashboard toggled, prop not set** — AI features default to off in code.
+3. **Installing the web calls SDK** — RN has its own.
+4. **Hand-wiring an `auto_rendered_ui` feature** — duplicate UI.
+5. **Assuming a feature exists** — no oracle entry means no feature.
+6. **Testing calls on a simulator** — no camera or mic capture.
+
+## Verify it works
+- The feature has an entry in `features.rn-v5.json` and you took its branch.
+- Every emitted component appears in `catalogs/rn-v5.json`.
+- `npm run verify:fences:rn-v5` is green.
+- On device: the capability actually appears — a dashboard-gated feature with no code change, or a
+  code change with no dashboard step, produces silence rather than an error.

package/skills/cometchat-react-native-migration/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: cometchat-react-native-migration
+description: "Migrate a React Native app from CometChat UI Kit v4 to v5 — the 16 removed components, what replaces each, the composite-to-modular rewrite, and the theming change from setter objects to a provider. Triggers: upgrade CometChat React Native v4 to v5, CometChatConversationsWithMessages removed, migrate RN chat uikit, CometChatDetails not found, v4 to v5 breaking changes."
+license: "MIT"
+compatibility: "migrating @cometchat/chat-uikit-react-native ^4 → ^5.4.0"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "chat cometchat react-native migration upgrade v4 v5 breaking-changes"
+---
+
+> **Ground truth:** the public-export diff between kit v4 and `@cometchat/chat-uikit-react-native@5.4.0`,
+> verified against `catalogs/rn-v5.json` (216 symbols) — every removal below is confirmed absent, not
+> assumed. Docs: `/ui-kit/react-native/upgrading-from-v4` · `property-changes`.
+
+## Companion skills (read first)
+- `cometchat-react-native-core` — the v5 install, provider chain and ordering you are migrating **to**.
+
+## Use this skill when
+- "upgrade our chat from v4 to v5" · "`CometChatConversationsWithMessages` is gone" · "`CometChatDetails` not found"
+
+## Prerequisites & install
+v5 changes the peer set as well as the API — reinstall from `core`'s list rather than bumping one
+package.
+
+## What actually changed: composites became parts
+
+v4 shipped end-to-end components. One tag gave you a list, a message view, details and threads. v5
+removes them so each piece is customizable — which is better, and is also a **rewrite of your chat
+screen**, not a version bump. Budget accordingly.
+
+## 16 components removed — each verified absent from the v5 catalog
+
+### Composites → stitch the parts yourself
+| v4 | v5 |
+|---|---|
+| `CometChatConversationsWithMessages` | `CometChatConversations` + a message screen |
+| `CometChatUsersWithMessages` | `CometChatUsers` + a message screen |
+| `CometChatGroupsWithMessages` | `CometChatGroups` + a message screen |
+| `CometChatMessages` | `CometChatMessageHeader` + `CometChatMessageList` + `CometChatMessageComposer` |
+| `CometChatThreadedMessages` | `CometChatThreadHeader` on its own screen |
+
+The message screen is three components in a `flex: 1` container — see `core`. Navigation between list
+and pane is `placement`.
+
+### Detail & management screens → **no replacement component**
+`CometChatDetails` · `CometChatContacts` · `CometChatAddMembers` · `CometChatBannedMembers` ·
+`CometChatTransferOwnership` · `CometChatUserMemberWrapper`
+
+> ⚠️ **This is the migration's real cost.** v5 ships nothing equivalent. You build these screens on
+> the SDK:
+>
+> | Screen | SDK |
+> |---|---|
+> | user / group details | `CometChat.getUser` · `getGroup` · `updateGroup` |
+> | add members | `addMembersToGroup` |
+> | **banned members** | `BannedMembersRequestBuilder` · `unbanGroupMember` |
+> | transfer ownership | `transferGroupOwnership` |
+>
+> `CometChatGroupMembers` lists **active** members only. If your v4 app could ban, it could also show
+> and unban — keep that pair, or you ship a one-way door.
+>
+> Do not invent a layout: the official sample app has real implementations —
+> `github.com/cometchat/cometchat-uikit-react-native/tree/v5/examples/SampleApp`. Those are sample-app
+> **directory paths**, never imports.
+
+### Call-log detail screens → list only
+`CometChatCallLogDetails` · `CometChatCallLogHistory` · `CometChatCallLogParticipants` ·
+`CometChatCallLogRecordings` · `CometChatCallLogsWithDetails` are gone. `CometChatCallLogs` (the list)
+remains; details come from `CometChatCalls.CallLogRequestBuilder` in the **calls** SDK.
+
+## Theming: setter objects → provider
+
+```diff
+- let myTheme = new CometChatTheme({});
+- myTheme.palette.setMode("dark");
++ <CometChatThemeProvider theme={{ mode: "dark" }}>
+```
+
+`CometChatContext` / `CometChatProvider` are gone. Read the active theme with `useTheme()`.
+Details in `customization`.
+
+## Migration order that avoids a broken middle
+1. Upgrade the packages and the peer set; get it **building** before touching UI.
+2. Replace composites with the three-part message screen (`core`).
+3. Add navigation so each surface is its own screen (`placement`).
+4. Rebuild the detail/management screens on the SDK — the longest step; scope it explicitly.
+5. Move theming to the provider (`customization`).
+6. Re-check calls and push on real devices; the native layer changed too.
+
+## Common pitfalls
+1. **Treating it as a version bump** — the chat screen is rewritten.
+2. **Looking for a v5 details component** — there isn't one.
+3. **Dropping banned-members** because there is no component — you lose the unban path.
+4. **Porting v4 theming setters** — replaced by the provider.
+5. **Keeping v4's single-screen conditional rendering** — v5 apps want a navigator.
+6. **Skipping the device pass** — peers and native config changed.
+
+## Verify it works
+- No removed symbol appears anywhere: grep for `WithMessages`, `CometChatDetails`, `CometChatMessages`.
+- Every emitted symbol is in `catalogs/rn-v5.json`.
+- `npm run verify:fences:rn-v5` is green.
+- On device: every v4 flow still exists — including viewing and unbanning banned members.

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

@@ -0,0 +1,158 @@
+---
+name: cometchat-react-native-placement
+description: "Where the CometChat React Native UI Kit v5 surfaces go in a real app — one screen per route on a stack navigator, tab-based layouts, growing from the core surface to the full app, and embedding chat in an existing screen. Triggers: add a chat tab React Native, chat screen navigation RN, react-navigation CometChat, embed chat in my RN app, full chat app layout."
+license: "MIT"
+compatibility: "React Native >=0.77; @cometchat/chat-uikit-react-native ^5.4.0; @react-navigation/native ^7"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "chat cometchat react-native placement navigation layout tabs screens"
+---
+
+> **Ground truth:** `@cometchat/chat-uikit-react-native@5` + catalog `rn-v5.json`.
+> Docs: `/ui-kit/react-native/react-native-conversation` · `react-native-tab-based-chat` ·
+> `expo-tab-based-chat`. Fetch props via `core/references/docs-map.md`.
+
+## Companion skills (read first)
+- `cometchat-react-native-core` — install, provider chain, init→login→render. Assumed, not repeated here.
+
+## Use this skill when
+- "add a chat tab" · "put chat on its own screen" · "chat inside my existing app"
+- "build the whole chat app" · "how do I navigate from the list to a conversation"
+
+## Prerequisites & install
+
+Navigation is **not** bundled. The documented stack:
+
+```bash
+npm install @react-navigation/native @react-navigation/native-stack @react-navigation/bottom-tabs
+npm install react-native-screens react-native-safe-area-context
+```
+⚠️ **Align these to YOUR React Native version — do not take the latest.** The UI Kit declares its peers
+as `"*"`, so nothing constrains them for you. `react-native-screens` 4.x / `safe-area-context` 5.x use
+Fabric codegen that RN 0.77's `@react-native/codegen` cannot parse; Metro then fails with
+`Unknown prop type for "moduleId"` / `"onFinishTransitioning"` — an error naming a native codegen file,
+never CometChat. Run `npx react-native doctor`, or match a known-good set for your RN
+(on **0.77**: `gesture-handler@2.32.0` + `screens@4.4.0` + `safe-area-context@4.14.0`).
+
+## The rule that governs every layout: one screen per route
+
+**This is the single biggest difference from the web UI Kit.** React places a list and a message pane
+side by side and toggles side panels with state. On a phone that is wrong:
+
+- each surface is its **own screen** on a stack navigator
+- navigation is `navigation.navigate(...)`, not conditional rendering
+- **back is the hardware/gesture back button** — the OS provides it; do not hand-roll one
+- there are **no side panels**. Search, thread and details are screens you push.
+
+Conditional rendering (`{selected ? <Chat/> : <List/>}`) appears in the simplest docs recipe and is
+fine for a single-screen demo, but it breaks the Android back button and loses navigation state.
+Anything beyond a demo uses the navigator.
+
+## Provider chain vs navigator — order matters
+
+Providers wrap the navigator, not the other way round. `GestureHandlerRootView` stays outermost:
+
+```tsx
+import { GestureHandlerRootView } from "react-native-gesture-handler";
+import { SafeAreaProvider } from "react-native-safe-area-context";
+import { NavigationContainer } from "@react-navigation/native";
+import {
+  CometChatI18nProvider, CometChatThemeProvider,
+} from "@cometchat/chat-uikit-react-native";
+
+export const Root = ({ children }: { children: React.ReactNode }) => (
+  <GestureHandlerRootView style={{ flex: 1 }}>
+    <SafeAreaProvider>
+      <CometChatI18nProvider>
+        <CometChatThemeProvider>
+          <NavigationContainer>{children}</NavigationContainer>
+        </CometChatThemeProvider>
+      </CometChatI18nProvider>
+    </SafeAreaProvider>
+  </GestureHandlerRootView>
+);
+```
+
+Putting `NavigationContainer` outside the providers means screens mount without a theme and the kit
+falls back to defaults.
+
+## Placement 1 — chat on its own screen (the default)
+
+Two routes: the list, and the message pane. This is what an unscoped "add chat" should produce.
+
+```tsx
+import { createNativeStackNavigator } from "@react-navigation/native-stack";
+import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
+
+const Stack = createNativeStackNavigator();
+
+const ConversationsScreen = () => <CometChatConversations />;
+const MessagesScreen = () => null; // header + list + composer — see `core`
+
+export const ChatStack = () => (
+  <Stack.Navigator>
+    <Stack.Screen name="Conversations" component={ConversationsScreen} />
+    <Stack.Screen name="Messages" component={MessagesScreen} options={{ headerShown: false }} />
+  </Stack.Navigator>
+);
+```
+
+`headerShown: false` on the message screen because `CometChatMessageHeader` **is** the header —
+leaving the native header on gives you two stacked headers.
+
+The list screen navigates on `onItemPress`; the message screen reads `user`/`group` from route params,
+sets `showBackButton` (it defaults to `false` on RN) and wires `onBack` to `navigation.goBack()`.
+
+## Placement 2 — a chat tab in an existing app
+
+Chat becomes one tab beside your own screens. The bottom-tab navigator holds the tabs; a stack sits
+**above** it so the message screen covers the tab bar when a conversation opens.
+
+```tsx
+<Stack.Navigator>
+  <Stack.Screen name="Tabs" component={TabNavigator} options={{ headerShown: false }} />
+  <Stack.Screen name="Messages" component={MessagesScreen} options={{ headerShown: false }} />
+</Stack.Navigator>;
+```
+
+If `Messages` lives *inside* the tab navigator instead, the tab bar stays visible over the composer —
+the classic "keyboard and tab bar fighting" bug.
+
+## Placement 3 — grow to the full app
+
+Add tabs for the other directories as they are asked for, each its own screen:
+`CometChatConversations` (Chats) · `CometChatUsers` (Users) · `CometChatGroups` (Groups) ·
+`CometChatCallLogs` (Calls). Push, don't panel:
+
+| Surface | How it appears |
+|---|---|
+| thread replies | push a screen with `CometChatThreadHeader` |
+| search | push a screen with `CometChatSearch`, wire `onBack` |
+| group members | push a screen with `CometChatGroupMembers` |
+| user/group details | **you build this** — kit v5 ships no details component (SDK fallback, see `core/references/docs-map.md`) |
+
+`CometChatIncomingCall` is the exception: mount it **once above the navigator** so a call can arrive
+on any screen.
+
+## Placement 4 — embed in an existing screen
+Chat as part of a screen rather than the whole of it. The container must still be `flex: 1` with
+`minHeight: 0`; a fixed height breaks when the keyboard opens.
+
+## Sizing and the keyboard
+Every ancestor of a kit component is `flex: 1`. A scrolling column also needs `minHeight: 0`. Verify
+with the keyboard **open** — the composer must stay visible, which a simulator can mislead you about.
+
+## Common pitfalls
+1. **Two headers** — `headerShown: false` on any screen using `CometChatMessageHeader`.
+2. **Message screen inside the tab navigator** — tab bar overlaps the composer.
+3. **Side panels ported from web** — push a screen instead.
+4. **`NavigationContainer` outside the providers** — screens mount unthemed.
+5. **Hand-rolled back buttons** — use the navigator's; wire `onBack` to `navigation.goBack()`.
+6. **`CometChatIncomingCall` inside one screen** — calls then only arrive on that screen.
+
+## Verify it works
+- Every emitted component appears in `catalogs/rn-v5.json`.
+- `npm run verify:fences:rn-v5` is green.
+- On device: hardware back returns from the message screen; opening search/thread and pressing back
+  returns cleanly; the composer survives the keyboard; a call arrives while on any tab.

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

@@ -0,0 +1,78 @@
+---
+name: cometchat-react-native-production
+description: "Ship a CometChat React Native app safely — server-minted auth tokens instead of the Auth Key, what actually stays secret in a mobile bundle, release-build checks, and logout hygiene. Triggers: CometChat production React Native, auth token instead of auth key RN, secure CometChat RN, release build chat, is my auth key safe in the app."
+license: "MIT"
+compatibility: "React Native >=0.77; @cometchat/chat-uikit-react-native ^5.4.0; @cometchat/chat-sdk-react-native ^4.0.28"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "chat cometchat react-native production security auth-token release"
+---
+
+> **Ground truth:** `@cometchat/chat-uikit-react-native@5` + `catalogs/rn-sdk-v4.json`.
+> Docs: `/ui-kit/react-native/react-native-cli-integration` · `/sdk/react-native/authentication-overview`.
+
+## Companion skills (read first)
+- `cometchat-react-native-core` — install, provider chain, init→login→render. Assumed, not repeated here.
+
+## Use this skill when
+- "is this safe to ship" · "swap the auth key for a token" · "prepare the release build"
+
+## Prerequisites & install
+None beyond `core`, plus a backend endpoint you control for minting tokens.
+
+## The one rule: the Auth Key never ships
+
+`login({ uid })` uses the **Auth Key**, which can create and impersonate any user in your app. Fine on
+your laptop; unacceptable in a shipped binary.
+
+### Nothing in a mobile app is secret
+This is the part web developers get wrong. A React Native bundle is **not** a server. `.env` files,
+`react-native-config`, `Constants.expoConfig`, obfuscation, ProGuard — all of them end up readable in
+the shipped app. Anyone can unzip an IPA or APK.
+
+"Hide the Auth Key in an env var" is not a mitigation. **Remove it.**
+
+### Production shape
+
+```tsx
+import { CometChatUIKit } from "@cometchat/chat-uikit-react-native";
+
+// your backend authenticates the user, then mints a short-lived CometChat
+// auth token for that UID and returns it
+const authToken: string = await fetchAuthTokenFromYourBackend();
+await CometChatUIKit.login({ authToken });
+```
+
+The client never sees the Auth Key. The token is per-user, short-lived and revocable.
+`UIKitSettings.authKey` is only needed for the `login({ uid })` path — a production build should not
+carry it at all.
+
+## User creation belongs on the server
+`CometChat.createUser` needs the Auth Key, so it is a **backend** call made when your own signup
+completes. A client that can create users can create *any* user.
+
+## Logout hygiene
+`CometChatUIKit.logout()` on sign-out, and **unregister the push token first** (see the `push` skill)
+— otherwise the device keeps receiving the previous user's notifications. On a shared device that is
+a privacy incident, not a bug.
+
+## Before you ship
+- **Test a release build**, not just debug. Some failures appear only there — most notably the
+  `react-native-gesture-handler` import-ordering crash (`bare-patterns`).
+- Build, then grep the output bundle for the Auth Key. It must not be present.
+- Verify calls and push on **real devices** — neither is provable on a simulator.
+- Check both platforms; Android and iOS diverge in native config, permissions and build failures.
+
+## Common pitfalls
+1. **Shipping the Auth Key** — env vars and obfuscation do not hide it.
+2. **Creating users client-side** — needs the Auth Key; move it to the backend.
+3. **Not unregistering push on logout** — the next user receives the previous user's messages.
+4. **Signing off from a debug build** — release-only failures exist.
+5. **Testing one platform only** — the native layer differs.
+
+## Verify it works
+- Every emitted symbol is in `catalogs/rn-sdk-v4.json` / `rn-v5.json`.
+- `npm run verify:fences:rn-v5` is green.
+- Grep a **release** bundle for the Auth Key — absent.
+- Sign out, then confirm the device stops receiving that user's notifications.

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

@@ -0,0 +1,88 @@
+---
+name: cometchat-react-native-push
+description: "Push notifications for CometChat in React Native — FCM on Android, APNs on iOS, registering the device token with CometChatNotifications, and why none of it can be verified without a real device. Triggers: CometChat push notifications React Native, FCM CometChat RN, APNs chat notifications, notifications not arriving React Native, VoIP call push RN."
+license: "MIT"
+compatibility: "React Native >=0.77; @cometchat/chat-sdk-react-native ^4.0.28; @react-native-firebase/messaging"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "chat cometchat react-native push notifications fcm apns voip token"
+---
+
+> **Ground truth:** `@cometchat/chat-sdk-react-native@4` + catalog `rn-sdk-v4.json` +
+> `features.rn-v5.json` → `push-notifications`. Docs:
+> `/notifications/react-native-push-notifications-android` · `…-ios`.
+> This skill is **docs-first** — fetch the current setup steps; do not bake a Firebase tutorial.
+
+## Companion skills (read first)
+- `cometchat-react-native-core` — install, provider chain, init→login→render. Assumed, not repeated here.
+
+## Use this skill when
+- "add push notifications" · "notifications aren't arriving" · "VoIP call push" · "register the FCM token"
+
+## Prerequisites & install
+
+Push is **not** web push. There is no service worker. React Native uses the OS transports:
+
+| Platform | Transport | Needs |
+|---|---|---|
+| Android | **FCM** | `google-services.json` in `android/app/` |
+| iOS | **FCM (via Firebase → APNs)** | `GoogleService-Info.plist`, an APNs key uploaded to the dashboard, Push capability in Xcode |
+
+Enable Push Notifications in the CometChat dashboard **first** and add the provider for the right
+platform. With `@react-native-firebase/messaging`, **both** Android and iOS use the **FCM** provider —
+Firebase relays to APNs on iOS and hands your app an FCM token, so you register it with CometChat as an
+FCM platform (see below). A raw-APNs (`APNS_REACT_NATIVE_*`) provider is only for a hand-rolled PushKit /
+native-APNs setup that skips Firebase.
+
+## The wiring — three steps, in this order
+
+1. **`init()` → `login()` must have completed.** A token registered before login belongs to nobody.
+2. **Get the device token** from your messaging library (typically `@react-native-firebase/messaging`).
+3. **Register it with CometChat:**
+
+```
+CometChatNotifications.registerPushToken(token, CometChatNotifications.PushPlatforms.FCM_REACT_NATIVE_ANDROID, providerId)
+```
+
+Platform constants match the token you actually hold. Because the Firebase library above yields an
+**FCM** token on **both** platforms, use `PushPlatforms.FCM_REACT_NATIVE_ANDROID` on Android and
+`PushPlatforms.FCM_REACT_NATIVE_IOS` on iOS (verified in `@cometchat/chat-sdk-react-native` `CometChat.d.ts`).
+The `APNS_REACT_NATIVE_DEVICE` / `APNS_REACT_NATIVE_VOIP` constants are ONLY for a raw APNs device/VoIP
+token from a hand-rolled PushKit setup — do **not** use them with a Firebase FCM token. **Fetch the exact
+argument order from the docs page for that platform.** `CometChatNotifications`, `registerPushToken`,
+`unregisterPushToken` and `PushPlatforms` are all verified present in `catalogs/rn-sdk-v4.json`.
+
+4. **Unregister on logout** — `unregisterPushToken()`. Skipping this is why a shared or re-used device
+keeps delivering the previous user's notifications.
+
+## Token refresh is not optional
+Device tokens rotate. Subscribe to your messaging library's token-refresh event and re-register, or
+push silently stops working days later for a subset of users — the hardest push bug to diagnose
+because nothing fails at the time.
+
+## VoIP / call notifications
+Calls need a **data-only** push plus a native dialer integration (CallKeep) so the device rings while
+the app is killed. That is a materially bigger build than message push, with its own iOS entitlements.
+Fetch `/notifications/react-native-push-notifications-android` and `…-ios` and follow them — do not
+improvise it.
+
+## Why this cannot be smoke-tested
+Push requires a real device (or an emulator image **with Play services** for FCM), real credentials,
+and the app in background or killed. It cannot be verified headlessly, in CI, or on an iOS simulator.
+`features.rn-v5.json` marks it accordingly — treat a "works" claim without device evidence as unproven.
+
+## Common pitfalls
+1. **Registering before login** — the token is attached to no user.
+2. **Not unregistering on logout** — the next user gets the previous user's pushes.
+3. **Ignoring token refresh** — push dies quietly, later.
+4. **Wrong platform constant** — registration succeeds, delivery never happens.
+5. **Missing `google-services.json` / `GoogleService-Info.plist`** — build or registration failure.
+6. **Testing on an iOS simulator** — APNs does not work there.
+7. **Expecting message-push setup to cover calls** — VoIP needs data-only push + CallKeep.
+
+## Verify it works
+- Every emitted symbol is in `catalogs/rn-sdk-v4.json`.
+- Dashboard: push enabled, correct provider added for the platform.
+- **On a real device:** notification arrives with the app backgrounded **and** killed; tapping it opens
+  the right conversation; after logout the device stops receiving that user's notifications.