@cometchat/skills 4.3.0 → 4.4.1

package/skills/cometchat-calls/SKILL.md

@@ -2,13 +2,14 @@
 name: cometchat-calls
 description: Entry-point for adding CometChat Voice & Video Calling to any React, React Native, Angular, native Android, native iOS, or Flutter project. Detects the framework, picks standalone (calls-only) vs additive (calls on top of existing chat) mode, and routes to the per-family calls skill. Invoked by the top-level `cometchat` dispatcher when `product === "voice-video"` or `chat-messaging+voice-video`, and directly when the user asks for calls explicitly.
 license: "MIT"
-allowed-tools: "shell, file-read, file-search, file-list, ask-user"
 metadata:
   author: "CometChat"
   version: "4.0.0"
   tags: "cometchat calls voice video webrtc dispatcher react react-native angular android ios flutter callkit pushkit voip"
 ---
 
+> **Ground truth:** the per-platform Calls SDK + `docs/calls`. **Official docs:** https://www.cometchat.com/docs/calls/javascript/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them.
+
 ## Use this skill when
 
 - The top-level `cometchat` dispatcher's Step 3.0 routes here because `product === "voice-video"` or `chat-messaging+voice-video`
@@ -25,12 +26,14 @@ This is the **entry point for every calls integration**. Do NOT invoke per-famil
 | **React Native** (Expo + bare) | `cometchat-native-calls` | `@cometchat/calls-sdk-react-native` | Yes |
 | **Angular** (12–15) | `cometchat-angular-calls` | `@cometchat/calls-sdk-javascript` | Yes |
 | **Android** (V5 stable) | `cometchat-android-v5-calls` | `com.cometchat:calls-sdk-android:5.x` (Cloudsmith) | Yes — production-ready |
-| **Android** (V6 beta) | `cometchat-android-v6-calls` | Calls fold into `chatuikit-{compose,kotlin}-android:6.x` for V6 | Beta |
+| **Android** (V6 GA) | `cometchat-android-v6-calls` | `chatuikit-{compose,kotlin}-android:6.0.+` **+ explicit `com.cometchat:calls-sdk-android:5.0.+` peer dep** (the "calls fold in" marketing is incomplete) | Yes — GA 2026-05-25, but ships broken OOTB: **5 required workarounds (W1–W5)**, incl. the peer dep + not using `CometChatCallButtons`. See per-family skill. |
 | **iOS** (V5 stable) | `cometchat-ios-calls` | `CometChatCallsSDK` (SPM / CocoaPods) | Yes |
 | **Flutter** (V5 stable) | `cometchat-flutter-v5-calls` (already exists) | `cometchat_calls_sdk` (Cloudsmith) | Yes |
-| **Flutter** (V6 beta) | `cometchat-flutter-v6-calls` (already exists) | Calls fold into `cometchat_chat_uikit:^6.0.0-beta2` | Beta |
+| **Flutter** (V6 GA) | `cometchat-flutter-v6-calls` (already exists) | Calls fold into `cometchat_chat_uikit: ^6.0.1` | Yes — GA 2026-05-25 (one explicit `MaterialApp(navigatorKey: CallNavigationContext.navigatorKey)` wiring required, see per-family skill) |
+
+> **Status:** All nine calls skills (this dispatcher + react, native, angular, ios, android-v5, android-v6, flutter-v5, flutter-v6) are authored and source-verified against each family's real SDK surface (decompiled `calls-sdk-android` AARs, `CometChatCallsSDK.swiftinterface`, `@cometchat/calls-sdk-{javascript,react-native}` `.d.ts`, and the Flutter `cometchat_calls_*` pub-cache). Android V5 ships 17 pre-authored sub-skills folded into `cometchat-android-v5-calls/references/`. Per-family caveats that are load-bearing: **Android V6 needs 5 workarounds (W1–W5)**; **Flutter V6 needs the `MaterialApp(navigatorKey: CallNavigationContext.navigatorKey)` wiring**; **iOS has no `CometChatCalls.login()`** (auth is per-session via `generateToken`).
 
-> **Status:** This dispatcher is the v4.1 entry point. Per-family skill stubs are scaffolded and being filled in. Flutter v5/v6 calls skills already exist from v4.0.0 and will be audited and brought into the same shape; the other six are being authored against `~/Downloads/calls-sdk/calls-sdk-{android,ios,javascript,react-native}-5/` as ground truth (Android ships 17 pre-authored sub-skills folded into `cometchat-android-v5-calls/references/`).
+> **Clarification contract (ALL coding agents) — read `references/asking-questions.md`.** Every "ask"/"AskUserQuestion" in this skill follows that contract: on any agent without a structured-question primitive, render the question as a **numbered text list and WAIT** for a real answer (never default/infer; auto-mode doesn't authorize skipping), map by value/label not position, and accept a free-text fallback.
 
 ## Why a separate calls dispatcher
 
@@ -279,6 +282,7 @@ These are the production-grade non-negotiables. The dispatcher checks them in St
 5. **Cleanup on hangup.** Camera-light-stays-on / mic-stays-hot is the canonical "looks fine in dev, fails review" bug. Every per-family skill includes the explicit teardown checklist.
 6. **Permissions with rationale.** Microphone, camera, screen-record (where supported), notifications. All four, all with usage strings.
 7. **`IncomingCall` mounted at app root in standalone mode.** Not at the chat surface — calls is the whole product, the listener has to be alive everywhere.
+8. **Honor "SDK only" when the user says SDK only (ENG-35711).** If the developer explicitly asks for the Calls SDK without UI Kit components — phrasing like *"pure SDK,"* *"no UI Kit components,"* *"build my own call UI,"* *"SDK-only path"* — the per-family skill MUST NOT scaffold `CometChatCallButtons`, `CometChatIncomingCall`, `CometChatOutgoingCall`, or `CometChatOngoingCall`. Use Chat SDK `CometChat.initiateCall` for signaling + Calls SDK `joinSession` (and a hand-written button/screen) for the surface. **Never silently fall back to UI Kit components** "because they're easier" — that's a documented frustration from two testers. If the developer's request can't be served without a UI Kit component, ask explicitly: *"This piece needs the kit's `<CometChatXxx>` — happy to use it, or do you want a hand-written equivalent?"* Don't decide for them.
 
 ## Anti-patterns
 
@@ -290,26 +294,28 @@ These are the production-grade non-negotiables. The dispatcher checks them in St
 
 ## Ground truth references
 
-Per-family `-calls` skills cite from these sources. The dispatcher itself doesn't write code; the per-family skills do. References listed here so a future audit can verify which SDK signatures the skills target.
+Per-family `-calls` skills cite from these sources. The dispatcher itself doesn't write code; the per-family skills do. To verify which SDK signatures the skills target, check each family's **published SDK artifact + public docs** (the source-of-truth — an earlier draft pointed at a local `~/Downloads/calls-sdk/` clone that no longer exists; use the installed/published packages instead):
 
-- **Android V5:** `~/Downloads/calls-sdk/calls-sdk-android-5/` — pre-authored 17-skill pack at `skills/`, dispatcher at `AGENTS.md`. Folded into `cometchat-android-v5-calls/references/{recording,screen-sharing,picture-in-picture,background-handling,voip-calling,audio-controls,video-controls,participant-management,custom-ui,in-call-chat,call-logs,session-settings,event-listeners,join-session,ringing-integration,setup}.md`.
-- **iOS V5:** `~/Downloads/calls-sdk/calls-sdk-ios-5/sample-apps/` — sample-app code as ground truth (no pre-authored skill pack).
-- **JavaScript (web):** `~/Downloads/calls-sdk/calls-sdk-javascript-5/sample-apps/` — sample-app code as ground truth.
-- **React Native:** `~/Downloads/calls-sdk/calls-sdk-react-native-5/sample-apps/` — sample-app code as ground truth.
-- **Flutter:** `~/Downloads/calls-sdk/calls-sdk-flutter-5/sample-apps/` + existing `cometchat-flutter-v5-calls` and `cometchat-flutter-v6-calls` skills (audited against the SDK).
-- **Angular:** Same JS Calls SDK (`@cometchat/calls-sdk-javascript`) wrapped in Angular Inputs/Outputs. Sample-app code from `~/Downloads/calls-sdk/calls-sdk-javascript-5/` plus existing `cometchat-angular-features` calls section.
+- **Android V5:** `com.cometchat:calls-sdk-android:5.x` (decompile the Maven AAR, or `javap` the Gradle-cached classes) + [docs](https://www.cometchat.com/docs/sdk/android/overview). The 17 sub-topics are folded into `cometchat-android-v5-calls/references/{recording,screen-sharing,picture-in-picture,background-handling,voip-calling,audio-controls,video-controls,participant-management,custom-ui,in-call-chat,call-logs,session-settings,event-listeners,join-session,ringing-integration,setup}.md`.
+- **iOS V5:** `CometChatCallsSDK` 5.x — the `.swiftinterface` inside the resolved framework (SPM `.build/artifacts/…` or CocoaPods `Pods/…`; it ships vendored inside `CometChatUIKitSwift` for additive) + [docs](https://www.cometchat.com/docs/calls/ios/overview).
+- **JavaScript (web):** `@cometchat/calls-sdk-javascript@5` — the package `.d.ts` (`node_modules/@cometchat/calls-sdk-javascript/dist/index.d.ts`) + [docs](https://www.cometchat.com/docs/calls/javascript/overview).
+- **React Native:** `@cometchat/calls-sdk-react-native@5` — the package `.d.ts` + `@cometchat/calls-lib-webrtc` (Cloudsmith) + [docs](https://www.cometchat.com/docs/calls/react-native/overview).
+- **Flutter:** `cometchat_calls_sdk` (V5: paired `cometchat_calls_uikit:^5.0`; V6: folded into `cometchat_chat_uikit:^6.0`) — the pub-cache source — plus the `cometchat-flutter-v5-calls` / `cometchat-flutter-v6-calls` skills (audited against it).
+- **Angular:** the same JS Calls SDK (`@cometchat/calls-sdk-javascript`) wrapped in Angular Inputs/Outputs — verify via `@cometchat/chat-uikit-angular` `.d.ts` + the JS SDK `.d.ts`.
 
-## Three calling modes — pick the right one (Tier 1.8 + 1.9)
+## Two calling modes (Ringing + Session) — and the kit's prebuilt UI for Ringing
 
-CometChat supports three distinct calling workflows. Route the user to the matching per-family reference:
+> **Naming clarification (ENG-35699 follow-up):** This section labels three rows below — "Standard", "Ringing", and "Call Session" — but **architecturally there are only TWO modes**: Ringing (signaling-driven) and Session (URL-driven). "Standard" is the **kit's prebuilt UI for Ringing** (using `<CometChatCallButtons>` + `<CometChatIncomingCall>`), not a third architectural mode. The Step 3.0 prompt above asks Ringing vs Session — that's the load-bearing decision. The Standard row is the most-common rendering choice WITHIN Ringing mode.
 
-| Mode | Driver | When to use | Per-family ref |
-|---|---|---|---|
-| **Standard** | UI Kit (`CometChatCallButtons` + `CometChatIncomingCall`) | 80% case — chat-driven calls with prebuilt UI | covered in per-family `SKILL.md` |
-| **Ringing** | Chat SDK call entity + Calls SDK session | Custom incoming/outgoing call UI on top of CometChat signaling | `references/ringing-integration.md` |
-| **Call Session** | Calls SDK `joinSession` directly (no ringing) | Meeting-room URLs, scheduled calls, conference rooms | `references/call-session.md` |
+CometChat supports two underlying calling workflows; the table below splits Ringing into "Standard (kit-prebuilt UI)" vs "Ringing (custom UI on signaling)" for routing purposes only:
+
+| Row | Underlying mode | Driver | When to use | Per-family ref |
+|---|---|---|---|---|
+| **Standard** | Ringing | UI Kit (`CometChatCallButtons` + `CometChatIncomingCall`) | 80% case — chat-driven calls with prebuilt UI | covered in per-family `SKILL.md` |
+| **Ringing (custom UI)** | Ringing | Chat SDK call entity + Calls SDK session | Custom incoming/outgoing call UI on top of CometChat signaling | `references/ringing-integration.md` |
+| **Call Session** | Session | Calls SDK `joinSession` directly (no ringing) | Meeting-room URLs, scheduled calls, conference rooms | `references/call-session.md` |
 
-Standard is the default unless the user explicitly says "custom incoming call UI" (→ Ringing) or "meeting link / join with sessionId" (→ Call Session). The Tier 4 use-cases telegraph which mode they want — broadcast + team huddles use Call Session; telehealth + marketplace + support use Standard or Ringing.
+Standard is the default Ringing rendering unless the user explicitly says "custom incoming call UI" (→ Ringing custom) or "meeting link / join with sessionId" (→ Call Session). The Tier 4 use-cases telegraph which mode they want — broadcast + team huddles use Call Session; telehealth + marketplace + support use Standard or Ringing custom.
 
 ## Use-case integration patterns (Tier 4)
 

package/skills/cometchat-calls/references/use-case-broadcast.md

@@ -39,10 +39,9 @@ const settings = {
   hideChangeLayoutButton: true,           // Don't let attendees change
 
   hideRecordingButton: false,             // Presenter records
-  startRecordingOnCallStart: true,        // Always record broadcasts (replay value)
+  autoStartRecording: true,        // Always record broadcasts (replay value)
 
-  hideScreenShareButton: false,           // For slides
-  hideVirtualBackgroundButton: false,
+  hideScreenSharingButton: false,           // For slides
 
   hideChatButton: false,                  // Q&A overflow + reactions
   hideShareInviteButton: false,           // Encourage sharing
@@ -53,7 +52,7 @@ const settings = {
   joinWithMutedAudio: true,
   joinWithMutedVideo: true,
 
-  callIdleTime: 0,                        // Disable idle timeout — events run long
+  idleTimeoutPeriodBeforePrompt: 86_400_000,                        // Disable idle timeout — events run long
 };
 ```
 
@@ -113,12 +112,18 @@ function PresenterRaisedHandsList() {
     });
   }, []);
 
-  function unmuteParticipant(uid: string) {
-    // Send a custom message asking participant to unmute themselves
-    // (CometChat doesn't support force-unmute — privacy)
-    CometChat.sendCustomMessage(/* type: 'unmute_request', target: uid */);
-    // Optimistically lower their hand
-    CometChatCalls.lowerParticipantHand(uid);
+  async function unmuteParticipant(uid: string) {
+    // Send a custom message asking the participant to unmute themselves
+    // (CometChat doesn't support force-unmute — privacy).
+    // There is NO CometChatCalls.lowerParticipantHand(uid) — the SDK only
+    // exposes lowerHand() for the LOCAL user. To lower someone else's hand,
+    // message them and let their client call lowerHand() (see raise-hand.md).
+    const msg = new CometChat.CustomMessage(
+      uid, CometChat.RECEIVER_TYPE.USER, "lower_hand", {},
+    );
+    await CometChat.sendCustomMessage(msg);
+    // Optimistically drop them from our local raised-hands list
+    setRaised((prev) => prev.filter((p) => p.uid !== uid));
   }
 
   return (

package/skills/cometchat-calls/references/use-case-marketplace.md

@@ -64,12 +64,11 @@ const settings = {
 
   hideRecordingButton: true,              // No platform-side recording — privacy + dispute via chat archive
   hideShareInviteButton: true,            // Buyer ↔ seller only — don't allow inviting
-  hideScreenShareButton: false,           // Useful for "show me the actual condition"
-  hideVirtualBackgroundButton: false,     // Privacy — most people are in their home
+  hideScreenSharingButton: false,           // Useful for "show me the actual condition"
   hideChatButton: false,                  // For sharing photos/details mid-call
 
   hideRaiseHandButton: true,
-  callIdleTime: 600,                      // 10min idle = end (sometimes deals die)
+  idleTimeoutPeriodBeforePrompt: 600_000,                      // 10min idle = end (sometimes deals die)
 };
 ```
 

package/skills/cometchat-calls/references/use-case-support.md

@@ -57,18 +57,17 @@ const settings = {
   hideChangeLayoutButton: false,          // Agent may want grid for note-taking workflows
 
   hideRecordingButton: true,              // Don't let agent toggle — server-side auto-record
-  startRecordingOnCallStart: true,        // QA recording is the policy
+  autoStartRecording: true,        // QA recording is the policy
                                           // (consent text in the in-app "By starting the call,
                                           //  you agree to recording for quality" notice)
-  hideScreenShareButton: false,           // Critical for troubleshooting
+  hideScreenSharingButton: false,           // Critical for troubleshooting
 
-  hideVirtualBackgroundButton: false,     // Agent uses brand background
 
   hideChatButton: false,                  // For pasting links/error messages
   hideShareInviteButton: true,            // Customer ↔ agent only
 
   hideRaiseHandButton: true,
-  callIdleTime: 300,                      // 5min — short, agents are busy
+  idleTimeoutPeriodBeforePrompt: 300_000,                      // 5min — short, agents are busy
 };
 ```
 

package/skills/cometchat-calls/references/use-case-team.md

@@ -34,17 +34,16 @@ const settings = {
   hideChangeLayoutButton: false,          // Let users pick (some prefer SPOTLIGHT)
 
   hideRecordingButton: false,             // Anyone can record; team norms decide
-  startRecordingOnCallStart: false,
+  autoStartRecording: false,
 
-  hideScreenShareButton: false,           // Critical
-  hideVirtualBackgroundButton: false,
+  hideScreenSharingButton: false,           // Critical
 
   hideChatButton: false,                  // Side-chat for links
   hideShareInviteButton: false,           // Pull others in mid-call
 
   hideRaiseHandButton: false,             // For larger team meetings (10+)
 
-  callIdleTime: 1800,                     // 30min — meetings can have lulls
+  idleTimeoutPeriodBeforePrompt: 1_800_000,                     // 30min — meetings can have lulls
 };
 ```
 
@@ -56,24 +55,36 @@ const settings = {
 // When someone starts a call in a team group, fire a custom message
 // so other members see "🟢 Huddle started by Sarah" in the channel.
 async function startHuddle(group: CometChat.Group) {
-  // 1. Initiate the call
-  const session = await CometChatCalls.startSession({
-    sessionId: `huddle-${group.guid}-${Date.now()}`,
-    participants: [...group.memberUids],
-  });
+  // 1. Mint a session via the Chat SDK. A Call returned by initiateCall carries
+  //    a server-issued sessionId — getSessionId() (chat-sdk Call.getSessionId).
+  //    There is NO object-form CometChatCalls.startSession({sessionId,participants}).
+  const call = new CometChat.Call(
+    group.guid,
+    CometChat.CALL_TYPE.VIDEO,
+    CometChat.RECEIVER_TYPE.GROUP,
+  );
+  const initiatedCall = await CometChat.initiateCall(call); // returns Call
+  const sessionId = initiatedCall.getSessionId();
 
-  // 2. Post a custom message in the chat group
+  // 2. Post a custom message in the chat group so members see the huddle + can join
   const customMessage = new CometChat.CustomMessage(
     group.guid,
     CometChat.RECEIVER_TYPE.GROUP,
     "huddle_started",
     {
-      sessionId: session.sessionId,
+      sessionId,
       startedBy: currentUserUid,
       startedAt: Date.now(),
     },
   );
   await CometChat.sendCustomMessage(customMessage);
+
+  // 3. The starter joins the session. Each joiner does the same with the shared
+  //    sessionId: generateToken(sessionId) → joinSession(token, settings, container).
+  //    (calls-sdk joinSession(callToken, SessionSettings, HTMLElement) is canonical;
+  //     the old startSession(callToken, callSettings, container) is deprecated.)
+  const { token } = await CometChatCalls.generateToken(sessionId);
+  await CometChatCalls.joinSession(token, sessionSettings, callContainer);
 }
 ```
 
@@ -124,7 +135,7 @@ app.post("/webhooks/call", async (req, res) => {
 ## Anti-patterns
 
 1. **Force-ringing all team members.** Annoying — they might be focused. Use channel notification + opt-in join.
-2. **No screen-share quality config.** Default screen-share is 720p; for code review, bump to 1080p (`screenShareQuality: 'high'`).
+2. **Assuming a screen-share quality knob exists in SessionSettings.** There is no `screenShareQuality` field on SessionSettings (verified against the calls-sdk types) — don't promise a non-API setting. Screen-share resolution is negotiated by the browser/WebRTC; tune the source (share a tab vs full screen) rather than a SessionSettings field.
 3. **Idle timeout too short.** Standup runs 35min, idle of 600s ends it during a debate. Use 1800s (30min).
 4. **Recording auto-on without team norms.** Some teams hate being recorded; surprise recording = trust hit. Default off; let team decide.
 5. **No way to invite outside team mid-call.** Sometimes you need to pull in a designer or PM. Don't hide share-invite for team calls.

package/skills/cometchat-calls/references/use-case-telehealth.md

@@ -47,16 +47,15 @@ const settings = {
   hideChangeLayoutButton: true,           // Don't let user switch — calmer UX
 
   hideRecordingButton: false,             // Provider needs it
-  startRecordingOnCallStart: false,       // NEVER auto-record without consent
+  autoStartRecording: false,       // NEVER auto-record without consent
 
-  hideScreenShareButton: false,           // Sharing labs is core
-  hideVirtualBackgroundButton: false,     // Patient often wants privacy
+  hideScreenSharingButton: false,           // Sharing labs is core
 
   hideChatButton: false,                  // For sending links/PDFs
   hideShareInviteButton: true,            // Patient ↔ provider only — no inviting
   hideRaiseHandButton: true,              // 1:1 — no need
 
-  callIdleTime: 600,                      // 10min — long enough for thinking pauses
+  idleTimeoutPeriodBeforePrompt: 600_000,                      // 10min — long enough for thinking pauses
 };
 ```
 

package/skills/cometchat-components/SKILL.md

@@ -3,19 +3,36 @@ name: cometchat-components
 description: "Complete catalog of CometChat React UI Kit v6 components. Reference before writing integration code -- never invent component names."
 license: "MIT"
 compatibility: "@cometchat/chat-uikit-react ^6; @cometchat/chat-sdk-javascript ^4"
-allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"
   tags: "chat cometchat react components catalog reference ui-kit"
 ---
 
+> **Ground truth:** `@cometchat/chat-uikit-react@^6` component catalog (installed package types) + `docs/ui-kit/react`. **Official docs:** https://www.cometchat.com/docs/ui-kit/react/components-overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them.
+
 ## Purpose
 
 This is the single source of truth for CometChat React UI Kit v6 component names, props, and usage. **Check this catalog before writing any `<CometChat*>` JSX.** If a component is not listed here, it does not exist in the exported API.
 
 All components are imported from `@cometchat/chat-uikit-react`. All SDK types are imported from `@cometchat/chat-sdk-javascript`.
 
+## When to use
+
+- Any React-family integration emitting `<CometChat*>` JSX: Vite + React, Next.js (App or Pages Router), React Router v6/v7, Astro with React islands.
+- Before scaffolding any chat surface (conversations, messages, users, groups, calls UI).
+- When verifying a component name or prop signature — this catalog is authoritative; the kit's `node_modules/@cometchat/chat-uikit-react/dist/types/` is the runtime source of truth that backs it.
+
+## When NOT to use
+
+- **React Native** (Expo or bare) — load `cometchat-native-components`. Class names are similar but **prop conventions diverge** (RN uses `onItemPress`, web uses `onItemClick` — runtime smoke 2026-06-02 confirmed). Cross-family copy-paste produces silent broken event bindings.
+- **Angular** — load `cometchat-angular-components`. Angular kit class names are **`Component`-suffixed** (`CometChatConversationsComponent` not `CometChatConversations` — verified by runtime smoke 2026-06-02), HTML selectors are kebab-case, event bindings use round brackets for `@Output()` events. Different shape entirely.
+- **Native Android** — load `cometchat-android-v6-{compose,kotlin}-components` (V6) or `cometchat-android-v5-components` (V5). Different package namespaces (`com.cometchat.uikit.compose.*` vs `com.cometchat.chatuikit.*`) — never reuse React component names.
+- **iOS V5** — load `cometchat-ios-components`. UIKit Swift surface; `CometChatConversations()` zero-arg initializer + `.set(group: ...)` pattern; nothing like the React prop API.
+- **Flutter V5 / V6** — load `cometchat-flutter-{v5,v6}-components`. Dart widget API with named parameters; V5 GetX vs V6 Bloc state-management split changes lifecycle.
+- **Theming-only tasks** — load `cometchat-theming` (CSS variables, recipes) for color/font customization without component changes.
+- **SDK-only chat (no UI Kit)** — this catalog assumes UI Kit components. If a future skill ships for the pure-SDK path (no `<CometChat*>` JSX), defer to it; today the closest analog is the SDK-only patterns inside `cometchat-react-calls` §4c.
+
 ### Importing `CometChat.User` / `CometChat.Group` / etc.
 
 `CometChat.User`, `CometChat.Group`, `CometChat.BaseMessage`, `CometChat.Conversation`, `CometChat.GroupMember`, `CometChat.TextMessage` are **classes** (runtime values), not pure types. That means the import strategy depends on how you use them:
@@ -50,6 +67,35 @@ function renderHeader(user: CometChat.User) { ... }
 
 ## 1. Core messaging
 
+> ⛔ **STOP — only the components in THIS catalog exist. Do not invent or recall component names from v4/older memory.** Before emitting ANY `CometChat*` component, confirm it appears in this catalog (or the kit's exports). If it's not here, it does not exist — using it produces an **unresolved-import build failure** or a blank screen. This is the #1 failure class on this skill.
+>
+> **The real v6 component set (the ONLY ones — `import { … } from "@cometchat/chat-uikit-react"`):** `CometChatConversations`, `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer` (+ `CometChatCompactMessageComposer`), `CometChatUsers`, `CometChatGroups`, `CometChatMessageInformation` (+ the calling/feature components in their own catalogs).
+>
+> **Commonly hallucinated names that were REMOVED in v6 (verified absent from the kit exports) — do NOT use:** the all-in-one composites `CometChatConversationsWithMessages`, `CometChatUsersWithMessages`, `CometChatGroupsWithMessages`, the `CometChatMessages` composite, and the `CometChatUI` god-component. **There is no single "conversations + messages" component in v6** — you compose the two panes yourself (recipe below). (Note: `CometChatMessages`/`CometChatConversationsWithMessages` DO still exist in the Flutter v6 kit — this removal is web/RN/Angular. Always check the per-family catalog.)
+
+> **The canonical two-pane experience (what "CometChatConversationsWithMessages" used to do — now hand-composed):**
+> ```tsx
+> const [active, setActive] = useState<CometChat.Conversation | null>(null);
+> // pick the peer the message views need from the selected conversation:
+> const peer = active?.getConversationWith(); // CometChat.User | CometChat.Group
+> return (
+>   <div style={{ display: "flex", height: "100%" }}>
+>     <div style={{ width: 320 }}>
+>       <CometChatConversations activeConversation={active ?? undefined}
+>         onItemClick={(c) => setActive(c)} />
+>     </div>
+>     <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
+>       {peer && <>
+>         <CometChatMessageHeader {...(peer instanceof CometChat.User ? { user: peer } : { group: peer })} />
+>         <CometChatMessageList   {...(peer instanceof CometChat.User ? { user: peer } : { group: peer })} />
+>         <CometChatMessageComposer {...(peer instanceof CometChat.User ? { user: peer } : { group: peer })} />
+>       </>}
+>     </div>
+>   </div>
+> );
+> ```
+> A `CometChatMessageHeader`/`List`/`Composer` takes EITHER `user=` OR `group=` (never both) — derive it from the clicked conversation. Conversations-list-only and single-conversation-only are both valid subsets of this.
+
 These are the components you use to build a chat experience. Most integrations use some combination of these seven.
 
 ### CometChatConversations
@@ -172,6 +218,20 @@ Displays the name, avatar, and status of the user or group at the top of a messa
 
 **Works with:** CometChatMessageList (below), CometChatCallButtons (in auxiliaryButtonView slot)
 
+> ⚠️ **Header `onItemClick` has NO default behavior (ENG-35705).** The kit ships no built-in `<CometChatUserDetails />` / `<CometChatGroupDetails />` panel — clicking the header name/avatar produces zero visible feedback unless YOU pass an `onItemClick` callback. **Four testers flagged this as "kit feels broken."** Rule when emitting `<CometChatMessageHeader>`:
+> 1. Either provide an `onItemClick` that opens a details panel YOU built (use the sample-app reference at `sample-app/src/components/CometChatDetails/`), OR
+> 2. Wrap the header in a clickable region that goes elsewhere, so the avatar+name doesn't *look* like a dead end. (There is no `showInfo` prop on `CometChatMessageHeader` — don't emit it.)
+> Do NOT mount the header bare without an `onItemClick` — it's a customer-facing dead end.
+
+> ⚠️ **`Reply in Thread` action requires the host to wire the thread panel (ENG-35705 — clarified 2026-06-02 from "broken" to "requires wiring").** The kit's `<CometChatMessageList>` renders a "Reply in Thread" item in the message-options menu and fires `onThreadRepliesClick(parentMessage)` when tapped — but the kit does NOT ship a default thread screen. If the host doesn't bind `onThreadRepliesClick` to a thread surface, the action visually does nothing (callback fires; no UI follows). Two paths:
+>
+> 1. **You're not building threads** — set `hideReplyInThreadOption={true}` on `<CometChatMessageList>` to remove the menu item entirely.
+> 2. **You ARE building threads** — bind `onThreadRepliesClick={(parent) => /* open thread surface */}` and render a separate `<CometChatMessageList parentMessageId={parent.getId()} />` inside the thread surface. Sample app's pattern: `cometchat-uikit-react-v6/sample-app/src/components/CometChatMessages/CometChatMessages.tsx:74` wires this via parent component routing.
+>
+> The dispatcher hard rule still defaults to option 1 (hide threads) because most integrations don't want them. Restated here at point-of-use so the catalog reader makes a conscious choice.
+
+> ⚠️ **`Message Privately` action — hide it via the kit prop if it misbehaves (ENG-35705).** In group chats the message-options menu shows a "Message Privately" item that may do nothing on click in some kit versions. `<CometChatMessageList>` exposes `hideMessagePrivatelyOption={true}` to remove it cleanly — set that rather than living with a dead menu item.
+
 ---
 
 ### CometChatSearch
@@ -295,12 +355,13 @@ A standalone search input component. Used for filtering within other components.
 **Key props:**
 | Prop | Type | Description |
 |---|---|---|
-| `onSearch` | `(text: string) => void` | Called as the user types |
-| `text` | `string` | Controlled input value |
+| `onChange` | `(input: { value?: string }) => void` | Called as the user types — read `input.value` |
+| `searchText` | `string` | Controlled input value |
+| `placeholderText` | `string` | Placeholder text |
 
 **Usage:**
 ```tsx
-<CometChatSearchBar onSearch={(text) => filterUsers(text)} />
+<CometChatSearchBar onChange={(input) => filterUsers(input.value ?? "")} />
 ```
 
 **Works with:** Any list component for client-side filtering
@@ -328,7 +389,7 @@ Renders voice and video call buttons. Typically placed in the `auxiliaryButtonVi
 <CometChatCallButtons user={selectedUser} />
 ```
 
-**Works with:** CometChatMessageHeader (in `menu` prop), CometChatIncomingCall (at app root)
+**Works with:** CometChatMessageHeader (via its `auxiliaryButtonView` prop — there is no `menu` prop), CometChatIncomingCall (at app root)
 
 ---
 
@@ -413,6 +474,60 @@ Shows a detailed list of who reacted with what emoji on a specific message.
 
 ---
 
+## 5. Notifications (catalog gap closed 2026-06-02)
+
+Three notification-related exports that were missing from this catalog before today. Verified against `cometchat-uikit-react-v6/src/index.ts:167-169`.
+
+### CometChatNotificationFeed
+
+A scrollable inbox of campaign / promotional notifications. Renders a list view; integrators wire it as a dropdown or dedicated route.
+
+**Key props:** `onItemClick: (feedItem: NotificationFeedItem) => void` to handle taps; `notificationFeedRequestBuilder` (and `notificationCategoriesRequestBuilder`) to filter — NOT `notificationsRequestBuilder`.
+
+**Usage:**
+```tsx
+import { CometChatNotificationFeed } from "@cometchat/chat-uikit-react";
+
+// feedItem is a NotificationFeedItem (campaign notification) — it has no
+// `conversationId`; route off its own fields / deep-link payload.
+<CometChatNotificationFeed onItemClick={(feedItem) => handleNotification(feedItem)} />
+```
+
+---
+
+### CometChatNotificationBadge
+
+A small unread-count pill, designed to attach to a nav item / icon. Auto-updates as new notifications arrive via the kit's notification feed listener.
+
+**Key props:** All optional — defaults to showing the current unread count of the logged-in user. Style with the standard `CometChat*Style` pattern.
+
+**Usage:**
+```tsx
+import { CometChatNotificationBadge } from "@cometchat/chat-uikit-react";
+
+<button onClick={openNotificationFeed}>
+  <BellIcon />
+  <CometChatNotificationBadge />
+</button>
+```
+
+---
+
+### useNotificationUnreadCount (hook)
+
+React hook returning the current unread-notification count for the logged-in user. Use this when `<CometChatNotificationBadge />` doesn't fit your layout — gives you the raw number to render however you like.
+
+**Signature:**
+```tsx
+import { useNotificationUnreadCount } from "@cometchat/chat-uikit-react";
+
+const { count, isLoading } = useNotificationUnreadCount({ /* optional UseNotificationUnreadCountOptions */ });
+```
+
+Internally subscribes to the same notification stream as `CometChatNotificationBadge` — using both is safe (single shared source).
+
+---
+
 ### CometChatEmojiKeyboard
 
 A full emoji picker. Automatically rendered inside the message composer when the emoji button is clicked.
@@ -439,9 +554,9 @@ An AI chatbot interface that users can interact with for automated responses. Ty
 
 **Prerequisites:** Enable "Conversation Starter" and/or "Smart Replies" in the dashboard.
 
-**Usage:**
+**Usage:** `user` is a **required** prop (the AI assistant user to chat with):
 ```tsx
-<CometChatAIAssistantChat />
+<CometChatAIAssistantChat user={assistantUser} />
 ```
 
 ---
@@ -459,13 +574,14 @@ Displays past AI assistant interactions. Used alongside `CometChatAIAssistantCha
 
 ### CometChatAIAssistantTools
 
-Renders AI tool options (summarize conversation, translate message, etc.) that can be applied to messages or conversations.
+⚠️ **This is a CLASS, not a renderable component.** You instantiate it with a map of action functions and pass it to `<CometChatAIAssistantChat>` via the `aiAssistantTools` prop — do NOT render `<CometChatAIAssistantTools />` (it's a type error).
 
 **Prerequisites:** Enable "Conversation Summary" and/or other AI tools in the dashboard.
 
 **Usage:**
 ```tsx
-<CometChatAIAssistantTools />
+const toolkit = new CometChatAIAssistantTools({ /* actionsMap */ });
+<CometChatAIAssistantChat user={assistantUser} aiAssistantTools={toolkit} />
 ```
 
 > **Note:** For detailed props, configuration options, and customization of AI components, query the docs MCP — these components' APIs evolve with CometChat's AI feature releases.
@@ -615,10 +731,15 @@ import {
   CometChatConversations,
   CometChatMessageHeader,
   CometChatMessageList,
-  CometChatMessageComposer,
+  CometChatCompactMessageComposer,
 } from "@cometchat/chat-uikit-react";
 import { CometChat } from "@cometchat/chat-sdk-javascript";
 
+// The message list must scroll inside a flex column without pushing the
+// composer off-screen. Mirror the sample app's list wrapper.
+// .cc-msg-list { flex: 1 1 0; min-height: 0; overflow: hidden; }
+// .cc-msg-list > .cometchat { height: 100%; overflow: hidden; }
+
 function MultiConversation() {
   const [activeConversation, setActiveConversation] = useState<CometChat.Conversation>();
 
@@ -639,15 +760,19 @@ function MultiConversation() {
         {selectedUser && (
           <>
             <CometChatMessageHeader user={selectedUser} />
-            <CometChatMessageList user={selectedUser} />
-            <CometChatMessageComposer user={selectedUser} />
+            <div className="cc-msg-list">
+              <CometChatMessageList user={selectedUser} />
+            </div>
+            <CometChatCompactMessageComposer user={selectedUser} />
           </>
         )}
         {selectedGroup && (
           <>
             <CometChatMessageHeader group={selectedGroup} />
-            <CometChatMessageList group={selectedGroup} />
-            <CometChatMessageComposer group={selectedGroup} />
+            <div className="cc-msg-list">
+              <CometChatMessageList group={selectedGroup} />
+            </div>
+            <CometChatCompactMessageComposer group={selectedGroup} />
           </>
         )}
       </div>
@@ -666,7 +791,7 @@ One chat window for a known user or group. No conversation list.
 import {
   CometChatMessageHeader,
   CometChatMessageList,
-  CometChatMessageComposer,
+  CometChatCompactMessageComposer,
 } from "@cometchat/chat-uikit-react";
 import { CometChat } from "@cometchat/chat-sdk-javascript";
 
@@ -675,15 +800,20 @@ interface SingleThreadProps {
   group?: CometChat.Group;
 }
 
+// .cc-msg-list { flex: 1 1 0; min-height: 0; overflow: hidden; }
+// .cc-msg-list > .cometchat { height: 100%; overflow: hidden; }
+
 function SingleThread({ user, group }: SingleThreadProps) {
   return (
     <div style={{ display: "flex", flexDirection: "column", height: "100%" }}>
       {user && <CometChatMessageHeader user={user} />}
       {group && <CometChatMessageHeader group={group} />}
-      {user && <CometChatMessageList user={user} />}
-      {group && <CometChatMessageList group={group} />}
-      {user && <CometChatMessageComposer user={user} />}
-      {group && <CometChatMessageComposer group={group} />}
+      <div className="cc-msg-list">
+        {user && <CometChatMessageList user={user} />}
+        {group && <CometChatMessageList group={group} />}
+      </div>
+      {user && <CometChatCompactMessageComposer user={user} />}
+      {group && <CometChatCompactMessageComposer group={group} />}
     </div>
   );
 }
@@ -717,10 +847,13 @@ import {
   CometChatGroups,
   CometChatMessageHeader,
   CometChatMessageList,
-  CometChatMessageComposer,
+  CometChatCompactMessageComposer,
 } from "@cometchat/chat-uikit-react";
 import { CometChat } from "@cometchat/chat-sdk-javascript";
 
+// .cc-msg-list { flex: 1 1 0; min-height: 0; overflow: hidden; }
+// .cc-msg-list > .cometchat { height: 100%; overflow: hidden; }
+
 type Tab = "chats" | "calls" | "users" | "groups";
 
 function FullMessenger() {
@@ -794,15 +927,19 @@ function FullMessenger() {
         {selectedUser && (
           <>
             <CometChatMessageHeader user={selectedUser} />
-            <CometChatMessageList user={selectedUser} />
-            <CometChatMessageComposer user={selectedUser} />
+            <div className="cc-msg-list">
+              <CometChatMessageList user={selectedUser} />
+            </div>
+            <CometChatCompactMessageComposer user={selectedUser} />
           </>
         )}
         {selectedGroup && (
           <>
             <CometChatMessageHeader group={selectedGroup} />
-            <CometChatMessageList group={selectedGroup} />
-            <CometChatMessageComposer group={selectedGroup} />
+            <div className="cc-msg-list">
+              <CometChatMessageList group={selectedGroup} />
+            </div>
+            <CometChatCompactMessageComposer group={selectedGroup} />
           </>
         )}
       </div>
@@ -968,7 +1105,8 @@ User and group detail panels are **custom-built** — there is no pre-built `Com
         // Switch to 1:1 chat with this member
       }}
     />
-    {/* CometChatBannedMembers is a real kit component */}
+    {/* Banning is handled inside CometChatGroupMembers — there is no separate
+        CometChatBannedMembers export in the v6 kit. */}
   </div>
 )}
 ```