@cometchat/skills 4.4.2 → 5.0.0

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

@@ -0,0 +1,142 @@
+---
+name: cometchat-react-native-components
+description: "The closed list of CometChat React Native UI Kit v5 components, what each one is for, and how to put custom UI INSIDE a component's view slot instead of stacking it on top. Triggers: which CometChat component React Native, custom header RN chat, add a button to the conversation list, custom list item RN, CometChat component list, add an avatar to my chat, show a profile picture, status indicator RN, badge RN, list item RN."
+license: "MIT"
+compatibility: "React Native >=0.77; @cometchat/chat-uikit-react-native ^5.4.0"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "chat cometchat react-native components slots views composition"
+---
+
+> **Ground truth:** catalog `rn-v5.json` (216 public symbols) — the closed list below IS the catalog.
+> A component not in it does not exist. Fetch props per component 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
+- "which component do I use for X" · "add a button to the conversation list header"
+- "custom list row" · "replace the message bubble" · "what components ship in v5"
+
+## Prerequisites & install
+None beyond `core`.
+
+## Component catalog (closed list)
+
+**Lists**
+| Component | Purpose |
+|---|---|
+| `CometChatConversations` | recent-conversations list — the usual entry screen |
+| `CometChatUsers` | user directory |
+| `CometChatGroups` | group directory |
+| `CometChatGroupMembers` | **active** members of a group (not banned — see below) |
+
+**Message pane**
+| Component | Purpose |
+|---|---|
+| `CometChatMessageHeader` | title, presence, back, call buttons |
+| `CometChatMessageList` | the scrollback; renders bubbles, receipts, reactions |
+| `CometChatMessageComposer` | input, attachments, voice notes |
+| `CometChatCompactMessageComposer` | single-line composer for tight layouts |
+| `CometChatThreadHeader` | thread replies — a **screen** on RN, not a side panel |
+| `CometChatMessageInformation` | per-message delivery/read detail |
+
+**Search · AI · notifications**
+| Component | Purpose |
+|---|---|
+| `CometChatSearch` | message + conversation search |
+| `CometChatAIAssistantChatHistory` · `CometChatAIAssistantTools` | AI assistant surfaces |
+| `CometChatConversationStarter` · `CometChatSmartReplies` · `CometChatConversationSummary` | AI suggestions |
+| `CometChatNotificationFeed` | in-app notification feed |
+
+**Calling** — needs `@cometchat/calls-sdk-react-native`
+| Component | Purpose |
+|---|---|
+| `CometChatCallButtons` | audio/video call triggers |
+| `CometChatIncomingCall` · `CometChatOutgoingCall` · `CometChatOngoingCall` | call lifecycle screens |
+| `CometChatCallLogs` | call history **list** (detail views were removed in v5) |
+
+**Bubbles** — the list renders these itself; place them only in a custom template
+`CometChatTextBubble` · `CometChatImageBubble` · `CometChatVideoBubble` · `CometChatAudioBubble` ·
+`CometChatFileBubble` · `CometChatVoiceNoteBubble` · `CometChatStickerBubble` ·
+`CometChatCollaborativeDocumentBubble` · `CometChatCollaborativeWhiteBoardBubble` · `CometChatMeetCallBubble`
+
+**Multi-attachment — RN only, no React equivalent**
+`CometChatAttachmentPreview` · `CometChatAttachmentPreviewItem` · `CometChatAttachmentTile` ·
+`CometChatAttachmentTray` · `CometChatAttachmentViewer` and the **plural** bubbles
+`CometChatImagesBubble` · `CometChatVideosBubble` · `CometChatAudiosBubble` · `CometChatFilesBubble`.
+> **DOCS GAP (RN-G4):** all nine are undocumented. Build from the kit source and say so.
+
+**Not components — but public and load-bearing**
+`ChatConfigurator` · `DataSourceDecorator` · `CometChatMessageTemplate` (custom message types →
+`customization`) · `CometChatThemeProvider` + `useTheme()` · `CometChatI18nProvider` ·
+`CometChatUIEventHandler` · `CometChatUiKitConstants`.
+
+**Primitives & building blocks** — exported, and what you reach for when composing a custom row,
+header or bubble yourself. Existence is baked here; **fetch each one's props from the docs**
+(`core/references/docs-map.md`) — do not infer them from `.d.ts`.
+| Group | Exports |
+|---|---|
+| Identity | `CometChatAvatar` · `CometChatStatusIndicator` · `CometChatBadge` · `CometChatDate` |
+| Row shell | `CometChatListItem` |
+| Overlays | `CometChatActionSheet` · `CometChatBottomSheet` · `CometChatConfirmDialog` · `CometChatReportDialog` · `CometChatMediaViewer` |
+| Composer add-ons | `CometChatEmojiKeyboard` · `CometChatMediaRecorder` · `CometChatInlineAudioRecorder` · `CometChatCreatePoll` · `CometChatSuggestionList` · `CometChatMessagePreview` · `CometChatMessageComposerAction` · `CometChatMessageOption` |
+| Reactions | `CometChatReactions` · `CometChatQuickReactions` · `CometChatReactionList` |
+| Text formatters | `CometChatTextFormatter` · `CometChatMentionsFormatter` · `CometChatUrlsFormatter` · `CometChatRichTextFormatter` |
+| Helpers | `CometChatUIKit` · `CometChatUIKitHelper` · `CometChatSoundManager` |
+
+> Changing a user's own avatar/name is **not** a component — it is the SDK call
+> `CometChat.updateCurrentUserDetails()`; see `cometchat-react-native-sdk`.
+
+### Components that do NOT exist in v5
+`CometChatErrorBoundary` · `CometChatDetails` · `CometChatAddMembers` · `CometChatBannedMembers` ·
+`CometChatTransferOwnership` · `CometChatContacts` · every `*WithMessages` composite ·
+`CometChatCallLogDetails` / `History` / `Participants` / `Recordings`.
+They were removed in kit v5. Each has an SDK-fallback path in `core/references/docs-map.md` —
+**banned members has no UI surface at all**, so an app that bans must also wire view + unban.
+
+## Custom UI goes IN a slot, not on top
+
+Every list and header exposes **view slots**. Custom UI belongs inside the slot so the component keeps
+its own layout, scrolling and empty/error states. Stacking a sibling above the list is the classic
+mistake — it double-renders headers and breaks scroll.
+
+⚠️ **RN slot props are PascalCase.** React's are camelCase; a ported snippet silently does nothing
+because an unknown prop is simply ignored.
+
+| Component | Slots |
+|---|---|
+| `CometChatConversations` | `ItemView` · `TitleView` · `SubtitleView` · `LeadingView` · `TrailingView` · `SearchView` · `EmptyView` · `ErrorView` · `LoadingView` |
+| `CometChatUsers` / `CometChatGroups` | `ItemView` · `TitleView` · `SubtitleView` · `LeadingView` · `TrailingView` · `EmptyView` · `ErrorView` · `LoadingView` |
+| `CometChatMessageHeader` | `ItemView` · `TitleView` · `SubtitleView` · `LeadingView` · `TrailingView` · `AuxiliaryButtonView` |
+| `CometChatMessageList` | `HeaderView` · `FooterView` · `EmptyView` · `ErrorView` · `LoadingView` |
+| `CometChatMessageComposer` | `HeaderView` · `SendButtonView` · `AuxiliaryButtonView` · `CustomView` |
+
+```tsx
+import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
+import { Pressable, Text } from "react-native";
+
+<CometChatConversations
+  TrailingView={() => (
+    <Pressable onPress={onArchive}>
+      <Text>Archive</Text>
+    </Pressable>
+  )}
+/>;
+```
+
+Slot names differ per component — fetch the exact list from that component's docs page rather than
+copying from a sibling.
+
+## Common pitfalls
+1. **camelCase slot props** — `itemView` is ignored silently. RN uses `ItemView`.
+2. **Rendering a sibling above a list** instead of using its slot — duplicate headers, broken scroll.
+3. **Placing a bubble component directly** — the list renders bubbles; use a template (`customization`).
+4. **Reaching for a removed component** — check the closed list above before emitting.
+5. **Assuming `CometChatGroupMembers` covers banned users** — it lists active members only.
+
+## Verify it works
+- Every emitted component appears in `catalogs/rn-v5.json`.
+- `npm run verify:fences:rn-v5` is green.
+- On device: custom slot content renders inside the component, and the list still scrolls.

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

@@ -0,0 +1,313 @@
+---
+name: cometchat-react-native-core
+description: "Foundational rules for the CometChat React Native UI Kit v5 — install and the exact native peer deps, the provider chain, init → login → render ordering, the component map, and the production-ready core chat surface. Read this first for any React Native CometChat task. Triggers: add chat to my React Native app, CometChat React Native setup, Expo chat, RN chat UI kit, integrate CometChat RN, log out of chat RN, add a logout button, chat lifecycle React Native."
+license: "MIT"
+compatibility: "Node.js >=18; React Native >=0.77; @cometchat/chat-uikit-react-native ^5.4.0; @cometchat/chat-sdk-react-native ^4.0.28; optional @cometchat/calls-sdk-react-native ^5.0.4"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "chat cometchat react-native expo core rules initialization provider native"
+---
+
+> **Ground truth:** `@cometchat/chat-uikit-react-native@5` + catalog `rn-v5.json` (216 public symbols) +
+> `features.rn-v5.json`. Official docs: <https://www.cometchat.com/docs/ui-kit/react-native/overview> ·
+> scoped index `…/ui-kit/react-native/llms-react-native-v5.md`. Verify every symbol against the catalog;
+> fetch signatures from docs (`references/docs-map.md`); never trust memory.
+>
+> ⚠️ **React Native is NOT React.** Different package, different API, native views instead of DOM.
+> A React UI Kit snippet will not compile here. `references/docs-map.md` ends with the verified
+> React → React Native name table — read it before porting anything.
+
+## Use this skill when
+- "add chat to my React Native app" · "integrate CometChat in Expo" · "RN chat UI"
+- any React Native CometChat task — it is the assumed base for every other `cometchat-react-native-*` skill
+
+## Prerequisites & install
+
+**One package per platform.** Never mix `@cometchat/chat-uikit-react` (web) into an RN app.
+
+```bash
+npm install @cometchat/chat-uikit-react-native@5 @cometchat/chat-sdk-react-native@4
+```
+
+Then the **native peer deps — required, not optional.** Verified against `5.4.0` + the integration pages:
+
+```bash
+npm install @react-native-clipboard/clipboard \
+  react-native-gesture-handler react-native-svg react-native-video react-native-localize \
+  react-native-safe-area-context @react-native-async-storage/async-storage@^2.1.2 dayjs
+# Expo also needs: punycode
+```
+
+`cd ios && pod install` for bare RN. **A missing native module fails at MOUNT, not at build** — the
+error names a NativeModule, not CometChat, so it reads as unrelated.
+
+
+## Setup & credentials (essentials — full detail: `references/setup-credentials.md`)
+1. **Detect** the project: Expo (`app.json`/`app.config.js`) or bare RN (`metro.config.js`). Reuse an existing `.cometchat/config.json` or env if present — skip re-setup.
+2. **version_conflict — STOP** if `@cometchat/chat-uikit-react-native` is already in `package.json` at a non-v5 major; reconcile first, never mix majors (`RULES.md`).
+3. **Credentials — OFFER the dashboard fetch FIRST** (never silently "paste it yourself" — AUDIT-039). Offer both, defaulting to fetch: **(a) dashboard fetch (recommended)** — `npx @cometchat/skills-cli@3 auth login`, pick an EXISTING app (`provision list --json`; never auto-create), `provision use --app-id <id> --json` writes `.cometchat/config.json`; **(b) manual paste** from Dashboard → Credentials (dev-only Auth Key). **Then the SKILL writes the env (§4)** — the CLI stops at the fetch; env-writing and codegen are the SKILL's job. Full flow: `references/setup-credentials.md`.
+4. **Write env**: bare RN → `.env` (read via `react-native-config`); Expo → `.env` (read via `Constants.expoConfig.extra` or `process.env`). Gitignore it; never echo the Auth Key. Prod → server-minted auth token, not the Auth Key. **Nothing in a mobile bundle is secret** (IPA/APK are readable) — see `references/setup-credentials.md`.
+5. **Authorize** = `initFromSettings` then `login` both resolve; auth error is almost always the wrong Region.
+
+## Integration ordering (BAKED — invariant)
+
+**`init()` must resolve before `login()`. `login()` must resolve before you render any component.**
+Breaking it gives a blank screen, not an error.
+
+Use **`initFromSettings`**, not the classic `init` — it persists `integrationSource="ai-agent"`
+so CometChat can attribute the integration. The classic init does not (AUDIT-084), and a machine
+gate enforces this.
+
+```tsx
+import { CometChatUIKit } from "@cometchat/chat-uikit-react-native";
+import { CometChat } from "@cometchat/chat-sdk-react-native";
+
+const settings: CometChat.CometChatSettings = {
+  appId: APP_ID,
+  region: REGION,
+  credentials: { authKey: AUTH_KEY }, // dev only — production mints an auth token server-side
+  chatSDK: {
+    presenceSubscription: { type: "ALL_USERS" },
+    autoEstablishSocketConnection: true,
+  },
+};
+
+await CometChatUIKit.initFromSettings(settings);
+await CometChatUIKit.login({ uid: UID });   // or ({ authToken }) in production
+```
+
+Note the shape: presence moves **into** `chatSDK.presenceSubscription.type` — it is not a
+top-level field and not a builder call.
+
+⚠️ **Two shapes that differ from React and will not compile if ported:**
+- settings is a **plain object** — there is no `UIKitSettingsBuilder` export in RN
+- `login` takes an **object**: `login({ uid })`, not `login(uid)`
+
+Use an existing UID from your dashboard (the sample apps seed `cometchat-uid-1`). Never invent one.
+
+## The provider chain (BAKED — order is load-bearing)
+
+Outermost first. Verified against the integration + recipe pages:
+
+```tsx
+<GestureHandlerRootView style={{ flex: 1 }}>
+  <SafeAreaProvider>
+    <CometChatI18nProvider>
+      <SafeAreaView style={{ flex: 1 }}>
+        <CometChatThemeProvider>
+          {/* screens */}
+        </CometChatThemeProvider>
+      </SafeAreaView>
+    </CometChatI18nProvider>
+  </SafeAreaProvider>
+</GestureHandlerRootView>
+```
+
+**`GestureHandlerRootView` is outermost and must carry `flex: 1`.** Omit it and swipe / long-press
+silently do nothing — no error, no warning. It is the single most common "the UI renders but nothing
+responds" cause on RN.
+
+## Sizing — flex, never viewport units
+
+There is no `100dvh` and no CSS. The rule: **every ancestor of a kit component is `flex: 1`**, and a
+scrolling column also needs `minHeight: 0`. A fixed pixel height breaks when the soft keyboard opens.
+The composer must remain visible with the keyboard up — verify on a device, not only a simulator.
+
+## Component / API map (BAKED closed list — from `catalogs/rn-v5.json`)
+
+| Need | Component |
+|---|---|
+| conversation list | `CometChatConversations` |
+| message pane | `CometChatMessageHeader` · `CometChatMessageList` · `CometChatMessageComposer` |
+| compact composer | `CometChatCompactMessageComposer` |
+| threads | `CometChatThreadHeader` |
+| search | `CometChatSearch` |
+| users / groups / members | `CometChatUsers` · `CometChatGroups` · `CometChatGroupMembers` |
+| calls | `CometChatCallButtons` · `CometChatIncomingCall` · `CometChatOutgoingCall` · `CometChatOngoingCall` · `CometChatCallLogs` |
+| theming / i18n | `CometChatThemeProvider` + `useTheme()` · `CometChatI18nProvider` |
+| extension chain | `ChatConfigurator` + `DataSourceDecorator` |
+
+Anything not in `catalogs/rn-v5.json` **does not exist** — do not emit it. Notably absent in v5:
+`CometChatErrorBoundary`, `CometChatDetails`, `CometChatAddMembers`, `CometChatBannedMembers`,
+`CometChatTransferOwnership`, and every `*WithMessages` composite. See `references/docs-map.md`
+for the SDK-fallback path for each.
+
+## Callback names — RN uses `Press`, not `Click`
+
+| Component | Wire these |
+|---|---|
+| `CometChatConversations` | `onItemPress` · `onSearchBarClicked` · `onError` |
+| `CometChatMessageList` | `onThreadRepliesPress` · `onError` |
+| `CometChatMessageHeader` | `showBackButton` (default `false`) + `onBack` · `onError` |
+| `CometChatSearch` | `onBack` · `onConversationClicked` · `onMessageClicked` |
+
+React's `onItemClick` / `onThreadRepliesClick` do not exist here.
+
+> ⚠️ **On `CometChatGroupMembers`, `onError` takes NO argument** in kits up to **5.5.0** —
+> `onError?: () => void`, unlike every other list. Type the handler with a parameter there and it fails
+> with TS2322. Write `onError={() => …}` and show the failure with the `ErrorView` slot, which needs no
+> error object. Fixed in the kit (uikit-react-native#1452); once that ships, the parameter is available
+> and this note goes away.
+
+## Golden path — the production-ready core surface
+
+The default for an unscoped "add chat". **One screen per route on a stack navigator with a real back
+button** — never two panes side by side, and never a web-style side panel.
+
+```tsx
+// ChatScreen.tsx — the message pane
+import {
+  CometChatMessageHeader, CometChatMessageList, CometChatMessageComposer,
+} from "@cometchat/chat-uikit-react-native";
+import { CometChat } from "@cometchat/chat-sdk-react-native";
+import { View } from "react-native";
+
+export const ChatScreen = ({ user, group, onBack }: {
+  user?: CometChat.User; group?: CometChat.Group; onBack: () => void;
+}) => (
+  <View style={{ flex: 1 }}>
+    {/* showBackButton defaults to FALSE on RN — without it onBack never fires */}
+    <CometChatMessageHeader user={user} group={group} showBackButton onBack={onBack} />
+    <CometChatMessageList user={user} group={group} />
+    <CometChatMessageComposer user={user} group={group} />
+  </View>
+);
+```
+
+```tsx
+// ConversationsScreen.tsx — the list, wired to open the pane
+import { CometChatConversations, CometChatUiKitConstants } from "@cometchat/chat-uikit-react-native";
+import { CometChat } from "@cometchat/chat-sdk-react-native";
+
+export const ConversationsScreen = ({ onOpen }: {
+  onOpen: (user?: CometChat.User, group?: CometChat.Group) => void;
+}) => (
+  <CometChatConversations
+    onItemPress={(conversation: CometChat.Conversation) => {
+      const isUser =
+        conversation.getConversationType() ===
+        CometChatUiKitConstants.ConversationTypeConstants.user;
+      isUser
+        ? onOpen(conversation.getConversationWith() as CometChat.User, undefined)
+        : onOpen(undefined, conversation.getConversationWith() as CometChat.Group);
+    }}
+  />
+);
+```
+
+### The core surface is FOUR things, not two
+
+`contracts.rn-v5.json` → `core-chat-surface` mandates all four by default, and the reviewer's G1
+gate fails an emit that ships fewer. A list ↔ message pane is **half the surface**:
+
+| Capability | Component | Wire |
+|---|---|---|
+| conversations | `CometChatConversations` | `onItemPress` |
+| messages | `CometChatMessageHeader` + `List` + `Composer` | `showBackButton` + `onBack` |
+| **threaded replies** | `CometChatThreadHeader` | `onThreadRepliesPress` → push a thread screen |
+| **search** | `CometChatSearch` | `showSearchBar={true}` **+** `onSearchBarClicked` → push a search screen |
+
+On RN both are **pushed screens**, not side panels. Search is opt-out only, and must cover the
+global (list) case *and* the in-chat case scoped to the open conversation.
+
+```tsx
+// message pane — thread entry point
+<CometChatMessageList
+  user={user}
+  group={group}
+  onThreadRepliesPress={(message) => openThread(message)}
+/>
+
+// conversation list — search entry point.
+// showSearchBar defaults to FALSE on RN (it is true on React), so the callback alone
+// silently ships a surface with no search. Both props, always.
+<CometChatConversations
+  onItemPress={open}
+  showSearchBar={true}
+  onSearchBarClicked={() => openSearch()}
+/>
+```
+
+The callbacks above are only the **entry points**. `openThread` and `openSearch` push screens, and
+those screens are where the two mandated components actually render — emit both, or the surface
+has tap targets that lead nowhere:
+
+```tsx
+// ThreadScreen — what openThread(message) pushes to.
+// parentMessageId is typed `string` on the list and `string | number` on the composer,
+// so the list needs .toString().
+function ThreadScreen({ route, navigation }) {
+  const { parentMessage, user, group } = route.params;
+  return (
+    <View style={{ flex: 1, minHeight: 0 }}>
+      <CometChatThreadHeader parentMessage={parentMessage} />
+      <CometChatMessageList
+        user={user}
+        group={group}
+        parentMessageId={parentMessage.getId().toString()}
+      />
+      <CometChatMessageComposer
+        user={user}
+        group={group}
+        parentMessageId={parentMessage.getId()}
+      />
+    </View>
+  );
+}
+```
+
+```tsx
+// SearchScreen — what openSearch() pushes to.
+// Omit uid/guid for the GLOBAL case (from the conversation list); pass one to scope the
+// search to the open conversation. Both cases are mandated — one screen serves both.
+function SearchScreen({ route, navigation }) {
+  const { user, group } = route.params ?? {};
+  return (
+    <CometChatSearch
+      onBack={() => navigation.goBack()}
+      uid={user?.getUid()}
+      guid={group?.getGuid()}
+      onConversationClicked={(conversation) => navigation.navigate("Messages", { conversation })}
+      onMessageClicked={(message) => navigation.navigate("Messages", { message })}
+      onError={(e) => console.error(e)}
+    />
+  );
+}
+```
+
+> **DOCS GAP (RN-G1):** there is no `components/search` page for React Native — `CometChatSearch`
+> is exported and mentioned only inside a task guide. Build from the catalog and flag it; do not
+> conclude search is unavailable.
+
+**Every affordance that is visible by default is wired or hidden.** A tap target that does nothing is
+a defect, and so is an opened surface with no way back — if you open search or a thread, wire its
+`onBack` in the same edit.
+
+## Deep references (load only when the task needs them)
+- `references/docs-map.md` — intent → the exact docs page; the SDK-fallback table; the React→RN name table. **Read before porting any React snippet.**
+- `references/component-props.md` — baked props + **PascalCase view slots** per drop-in, and the defaults that differ from React (`showSearchBar` is `false` here). **Read before placing custom UI** — it goes in a slot, never as a sibling.
+- `references/anti-patterns.md` — the 13 failures that actually break an RN integration, each with why its error names the wrong thing.
+- `references/lifecycle.md` — `initFromSettings` → login → render, and the promise-cached boot guard (a boolean flag does not work).
+- `references/layout.md` — the four sizing invariants the `core-chat-surface` contract gates on.
+- `references/dependencies.md` — the exact peer set + the native config that is not optional (Podfile modular headers, gesture-handler import order).
+- `references/setup-credentials.md` — dev vs production auth, and why nothing in a mobile bundle is secret.
+
+## Common pitfalls
+1. **Missing `GestureHandlerRootView`** — gestures silently dead. Outermost, `flex: 1`.
+2. **Rendering before `login()` resolves** — blank screen, no error.
+3. **Porting React code** — `UIKitSettingsBuilder`, `login(uid)`, `onItemClick`, CSS, `document.*`: none exist here.
+4. **Fixed heights** — breaks on keyboard open. Use `flex: 1` + `minHeight: 0`.
+5. **Shipping the Auth Key** — dev only; production mints an auth token server-side.
+
+## Verify it works
+- Every emitted symbol appears in `catalogs/rn-v5.json`.
+- Code compiles against the pinned kit: `npm run verify:fences:rn-v5`.
+- Oracles agree with the kit and docs: `npm run verify:sync:rn-v5`.
+- On a device: chat fills the screen, the composer survives the keyboard, back works, gestures respond.
+
+## Explain what you built (REQUIRED close)
+Tell the user briefly: **(1) what I wired** (3–5 bullets, NAME the files); **(2) decisions & why**, flagging dev-only AS dev-only (the **Auth Key** is dev-only → server-minted auth token for production; the `<uid>` you used; Expo vs bare RN path); **(3) what I did NOT touch** (additive — navigation/auth/styles intact). Then **offer these THREE options as a selectable choice and WAIT — do not auto-continue:**
+- **① Add another feature** — check what's already wired; ASK which Dashboard extensions are enabled; suggest 3–4 gaps (**calls · push · AI smart replies · polls · stickers · translation · notification feed**). Never suggest reactions or mentions — they are ON by default in v5. → `cometchat-react-native-features` / `cometchat-react-native-calls` / `cometchat-react-native-push`.
+- **② Customize theming** — ask for brand color / light-dark → `cometchat-react-native-customization`.
+- **③ Test it manually** — hand it back so they run it on a device.

package/skills/cometchat-react-native-core/references/anti-patterns.md

@@ -0,0 +1,79 @@
+# anti-patterns — what breaks a CometChat React Native integration
+
+Every entry here is a failure **observed in this codebase**, not a generic warning. Ordered by how
+often it bites and how misleading its error is.
+
+## The meta-pattern: RN errors name the wrong culprit
+Three properties make RN bugs hard to read, and all of them appear below:
+- **native modules fail at MOUNT, not build** — the app starts, then a screen explodes
+- **the error names a peer dependency**, not CometChat — `gesture-handler`, `svg`, Ruby, generated C++
+- **an unknown prop is silently ignored** — no error, nothing renders
+
+So "the error doesn't mention CometChat" is evidence of nothing.
+
+---
+
+## 1. Porting React code
+The React UI Kit is a **different package with a different API**. These do not exist on RN:
+
+| React | React Native |
+|---|---|
+| `new UIKitSettingsBuilder()…build()` | a plain `CometChatSettings` object |
+| `CometChatUIKit.login(uid)` | `login({ uid })` — an **object** |
+| `onItemClick` · `onThreadRepliesClick` | `onItemPress` · `onThreadRepliesPress` |
+| `itemView` · `trailingView` (camelCase) | `ItemView` · `TrailingView` (**PascalCase**) |
+| `CometChatMessagePlugin` / `PluginRegistry` | `ChatConfigurator` + `DataSourceDecorator` |
+| `CometChatErrorBoundary` | none — use a plain React error boundary |
+| `setCallingEnabled(true)` | **nothing** — installing the calls package IS the switch |
+| CSS variables / `className` | `CometChatThemeProvider` + `useTheme()` |
+
+**The PascalCase one is the nastiest**: an unknown prop throws nothing and renders nothing, so the
+custom UI just never appears.
+
+## 2. Same prop name, opposite default
+`showSearchBar` is **`true` on React** and **`false` on React Native**. Wiring
+`onSearchBarClicked` without `showSearchBar={true}` ships a surface where search can never be
+reached — and it compiles, and every symbol exists. See `component-props.md`.
+
+## 3. Missing `GestureHandlerRootView`
+Gestures silently stop working. No error. It must be **outermost** and carry `flex: 1`.
+On bare RN, `import 'react-native-gesture-handler'` must also be the **first line of `index.js`** —
+wrong ordering often works in debug and **crashes in release**.
+
+## 4. Rendering before `login()` resolves
+Blank screen, no exception. Gate the render; cache the boot **promise**, not a boolean
+(`lifecycle.md`).
+
+## 5. Fixed heights
+Breaks the moment the soft keyboard opens. `flex: 1` everywhere, `minHeight: 0` on scrolling
+columns (`layout.md`).
+
+## 6. Web-shaped layout
+Side panels, two panes side by side, state-toggled views. On a phone every surface is its own
+**screen** on a stack navigator with the OS back button (`placement`).
+
+## 7. Two headers
+The navigator's header plus `CometChatMessageHeader`. Set `headerShown: false` on that screen.
+
+## 8. Hand-rolling what the kit ships
+A `TextInput` composer, a `FlatList` of messages, a `react-native-image-picker` flow. All exist as
+drop-ins. Custom UI goes **in a view slot**, never as a sibling above the component.
+
+## 9. Shipping the Auth Key
+No client-side hiding works. Production mints an auth token server-side (`setup-credentials.md`).
+
+## 10. Leaking listeners
+Every `add*Listener(id, …)` needs `remove*Listener(id)` on teardown. The **SDK** holds the
+listener, not React, so it survives unmount — the top cause of duplicate messages, and it worsens
+the longer the app runs.
+
+## 11. Ban without unban
+`CometChatGroupMembers` lists **active** members only, and v5 ships no banned-members UI. An app
+that can ban but not view or unban is an unclosed round trip.
+
+## 12. Believing a simulator
+Calls need camera and mic; push needs delivery to a backgrounded or killed app. **Neither works on
+a simulator.** A green simulator run proves the screens render, not that the feature works.
+
+## 13. Reloading after a native change
+Metro reload only refreshes JavaScript. New native module, Gradle edit or plist change ⇒ **rebuild**.

package/skills/cometchat-react-native-core/references/component-props.md

@@ -0,0 +1,105 @@
+# component-props — BAKED stable props + view slots for the React Native v5 drop-ins
+
+Verified against `@cometchat/chat-uikit-react-native@5.4.0` **source**, not prose. Exhaustive prop
+lists still come from the docs (`docs-map.md`); this file bakes the ones you need on the hot path
+and the ones that are traps.
+
+## THE RULE — custom UI goes in the component's OWN view slot, NEVER as a sibling on top
+A custom header, search icon or action button rendered *above* a list double-renders the header and
+breaks scrolling. Put it in the component's slot so the component keeps its own layout, scroll and
+empty/error states.
+
+⚠️ **RN slot props are PascalCase** (`ItemView`, `TrailingView`). React's camelCase form is
+**silently ignored** — no error, nothing renders.
+
+---
+
+## ⚠️ Defaults that differ from React — verified from source
+
+| Prop | React | **React Native** | Consequence |
+|---|---|---|---|
+| `showSearchBar` | `true` | **`false`** | **The search bar is HIDDEN by default.** `onSearchBarClicked` can never fire unless you also pass `showSearchBar={true}`. Wiring the callback alone silently ships a surface with no search. |
+| `showSmartReplies` | `false` | `false` | same |
+| `showConversationStarters` | `false` | `false` | same |
+| `showConversationSummaryButton` | `false` | `false` | same |
+| `showMarkAsUnreadOption` | `false` | `false` | same |
+
+Every `show*` prop is opt-**in**; every `hide*` prop is opt-**out**. When a feature "does nothing
+after enabling it in the dashboard", the missing `show*` prop is the usual cause.
+
+---
+
+## CometChatConversations
+**Props:** `onItemPress(conversation)` · `onItemLongPress` · `onSearchBarClicked` · `onSelection` ·
+`onError` · `onEmpty` · `onLoad` · `showSearchBar` (**default `false`**) · `hideHeader` ·
+`hideBackButton` · `hideError` · `disableSoundForMessages` · `conversationsRequestBuilder`.
+
+**View slots (PascalCase):** `ItemView` · `TitleView` · `SubtitleView` · `LeadingView` ·
+`TrailingView` · `SearchView` · `EmptyView` · `ErrorView` · `LoadingView`.
+
+> **Search in the list → `showSearchBar={true}` + `onSearchBarClicked` → push a search screen.**
+> Both, or search is invisible.
+
+> **Scope the list with `conversationsRequestBuilder`.** 1:1-only app →
+> `.setConversationType("user")`; groups-only → `.setConversationType("group")`.
+> ⚠️ **Pass the builder INSTANCE, not `.build()`** — the kit calls `.build()` internally
+> (`CometChatConversations.tsx:1670`), and the RN docs say so explicitly. Passing the built object
+> breaks the list.
+> ```tsx
+> import { CometChat } from "@cometchat/chat-sdk-react-native";
+> <CometChatConversations
+>   conversationsRequestBuilder={new CometChat.ConversationsRequestBuilder().setLimit(30)}
+> />
+> ```
+
+## CometChatUsers / CometChatGroups
+**Props:** `onItemPress` · `onError` · `onEmpty` · `onLoad` · `usersRequestBuilder` /
+`groupsRequestBuilder` (same instance-not-`.build()` rule).
+**Slots:** `ItemView` · `TitleView` · `SubtitleView` · `LeadingView` · `TrailingView` ·
+`EmptyView` · `ErrorView` · `LoadingView`.
+
+## CometChatMessageHeader
+**Props:** `user` · `group` · `onBack` · `onError` · `showBackButton` · `hideVoiceCallButton` ·
+`hideVideoCallButton` · `hideNewChatButton` · `hideChatHistoryButton` ·
+`showConversationSummaryButton` (**default `false`**) · `onConversationSummaryPress`.
+**Slots:** `ItemView` · `TitleView` · `SubtitleView` · `LeadingView` · `TrailingView` ·
+`AuxiliaryButtonView`.
+
+> Call buttons render here **by default** — do not also mount `CometChatCallButtons` in the header
+> or they double up.
+
+## CometChatMessageList
+**Props:** `user` · `group` · `onThreadRepliesPress` · `onError` · `onEmpty` · `onLoad` ·
+`messageRequestBuilder` · `reactionsRequestBuilder` · `showSmartReplies` (**default `false`**) ·
+`showConversationStarters` (**default `false`**) · `showMarkAsUnreadOption` (**default `false`**) ·
+plus `hide*` toggles for every message option (`hideReplyInThreadOption`, `hideReactionOption`,
+`hideCopyMessageOption`, `hideDeleteMessageOption`, `hideEditMessageOption`,
+`hideMessagePrivatelyOption`, `hideTranslateMessageOption`, `hideFlagMessageOption`,
+`hideMessageInfoOption`, `hideShareMessageOption`, `hideTimestamp`, `hideGroupActionMessages`).
+**Slots:** `HeaderView` · `FooterView` · `EmptyView` · `ErrorView` · `LoadingView` ·
+`messageBubbleView` · `NewMessageIndicatorView`.
+
+> **Threads:** `onThreadRepliesPress` → push a screen with `CometChatThreadHeader`. Not
+> `onThreadRepliesClick` (React's name), and not a side panel.
+> **AI features need BOTH** the dashboard toggle **and** the `show*` prop — the prop is `false` by default.
+
+## CometChatMessageComposer
+**Props:** `user` · `group` · `disableTypingEvents` · `disableMentions` · `disableMentionAll` ·
+`disableSoundForOutgoingMessages` · `hideAttachmentButton` · `hideSendButton` ·
+`hideVoiceRecordingButton` · `hideStickersButton` · `hideAuxiliaryButtons` · plus per-attachment
+toggles (`hideImageAttachmentOption`, `hideVideoAttachmentOption`, `hideFileAttachmentOption`,
+`hideAudioAttachmentOption`, `hideCameraOption`, `hidePollsAttachmentOption`,
+`hideCollaborativeDocumentOption`, `hideCollaborativeWhiteboardOption`).
+**Slots:** `HeaderView` · `SendButtonView` · `AuxiliaryButtonView` · `CustomView`.
+
+> The composer owns attachments. A hand-rolled `react-native-image-picker` flow means the built-in
+> was missed.
+
+## CometChatSearch
+**Props:** `onBack` · `onConversationClicked` · `onMessageClicked` · `onError` ·
+`hideBackButton` · `conversationsRequestBuilder` · `messagesRequestBuilder`.
+
+> Opened from `onSearchBarClicked` as a **pushed screen**. Wire `onBack` in the same edit — an
+> opened surface with no way back is a dead end.
+> **In-chat search must be SCOPED** to the open conversation via the request builders; unscoped, a
+> header search leaks whole-app results.