@cometchat/skills 4.2.1 → 4.4.0

package/skills/cometchat-android-v5-calls/references/migration-v4-to-v5.md

@@ -25,7 +25,9 @@ Should show `com.cometchat:calls-sdk-android:5.x.x`.
 
 ---
 
-## Step 2 — Migrate init to plain config
+## Step 2 — Migrate init to the v5 builder + `Context`
+
+v5 still uses a builder — but the class is the **nested `CallAppSettings.CallAppSettingBuilder`** (singular "Setting"), and `init` now takes `Context` as its first argument.
 
 ```diff
 - val callAppSettings = CallAppSettings.Builder()
@@ -37,13 +39,18 @@ Should show `com.cometchat:calls-sdk-android:5.x.x`.
 -   override fun onError(e: CometChatException) { /* ... */ }
 - })
 
-+ val settings = CallAppSettings(appId = "APP_ID", region = "REGION")
-+ CometChatCalls.init(settings, object : CometChatCalls.CallbackListener<String>() {
++ val callAppSettings = CallAppSettings.CallAppSettingBuilder()   // nested, singular "Setting"
++   .setAppId("APP_ID")
++   .setRegion("REGION")
++   .build()
++ CometChatCalls.init(context, callAppSettings, object : CometChatCalls.CallbackListener<String>() {
 +   override fun onSuccess(s: String) { /* ... */ }
 +   override fun onError(e: CometChatException) { /* ... */ }
 + })
 ```
 
+> Verified against `calls-sdk-android` 5.x: `CometChatCalls.init(Context, CallAppSettings, CallbackListener<String>)` and `CallAppSettings.CallAppSettingBuilder().setAppId(...).setRegion(...).build()`. There is NO `CallAppSettings(appId =, region =)` constructor and NO `CallAppSettings.Builder()`.
+
 (V5 also supports coroutine-suspend `init` via `kotlinx.coroutines` extensions, if you've enabled them.)
 
 ---
@@ -95,18 +102,27 @@ After this step, `generateToken()` no longer needs the authToken parameter — t
 -   .showRecordingButton(true)
 -   .build()
 
-+ val sessionSettings = SessionSettings(
-+   sessionType = SessionType.VIDEO,
-+   startAudioMuted = false,
-+   hideRecordingButton = false,    // INVERTED
-+   layout = LayoutType.TILE,
-+ )
++ val sessionSettings = CometChatCalls.SessionSettingsBuilder()
++   .setSessionType(SessionType.VIDEO)
++   .startAudioMuted(false)
++   .hideRecordingButton(false)     // INVERTED — showRecordingButton(true) → hideRecordingButton(false)
++   .setLayout(LayoutType.TILE)
++   .build()
 ```
 
+> There is NO `SessionSettings(sessionType =, startAudioMuted =, hideRecordingButton =, layout =)` data-class constructor on Android — use `CometChatCalls.SessionSettingsBuilder()` with the chained flag methods (cf. `call-session.md` rule 2).
+
 ---
 
 ## Step 5 — Migrate listener interface to event listeners
 
+v5 splits the old single events interface into five abstract listeners (`SessionStatusListener`,
+`ParticipantEventListener`, `MediaEventsListener`, `ButtonClickListener`, `LayoutListener`).
+Register them on the `CallSession` instance from `joinSession`'s `onSuccess` callback — there is
+NO `CometChatCalls.addEventListener` and NO `CallEvent` enum on Android (cf. `call-session.md`
+rule 3 and `references/event-listeners.md`). The listeners are lifecycle-aware (pass the
+Activity/Fragment as the first arg) and auto-removed on destroy.
+
 ```diff
 - class MyCallEvents : CometChatCallsEventsListener {
 -   override fun onCallEnded() { /* ... */ }
@@ -115,24 +131,23 @@ After this step, `generateToken()` no longer needs the authToken parameter — t
 -   override fun onError(error: CometChatException) { /* ... */ }
 - }
 
-+ // Granular event subscriptions
-+ val unsub1 = CometChatCalls.addEventListener(CallEvent.SESSION_LEFT) { /* ... */ }
-+ val unsub2 = CometChatCalls.addEventListener(CallEvent.PARTICIPANT_JOINED) { participant -> /* ... */ }
-+ val unsub3 = CometChatCalls.addEventListener(CallEvent.PARTICIPANT_LEFT) { participant -> /* ... */ }
-+
-+ // Cleanup in onDestroy or scope cancellation
-+ override fun onDestroy() {
-+   unsub1.invoke()
-+   unsub2.invoke()
-+   unsub3.invoke()
-+ }
++ // In joinSession's onSuccess(callSession: CallSession):
++ callSession.addSessionStatusListener(this, object : SessionStatusListener() {
++   override fun onSessionLeft() { /* ... */ }
++ })
++ callSession.addParticipantEventListener(this, object : ParticipantEventListener() {
++   override fun onParticipantJoined(participant: Participant) { /* ... */ }
++   override fun onParticipantLeft(participant: Participant) { /* ... */ }
++ })
++ // ...plus MediaEventsListener / ButtonClickListener / LayoutListener as needed.
++ // See references/event-listeners.md for the full override set on each.
 ```
 
 ---
 
 ## Step 6 — Method renames + receiver shift (Android-specific)
 
-v5 moved most call-control APIs from static methods on `CometChatCalls` to **instance methods on `CallSession`** (the object returned by `joinSession`'s callback). The static `endSession()` is the only one preserved as a deprecated shim — the others throw "method not found" if you keep the v4 receiver.
+v5 moved call-control APIs from static methods on `CometChatCalls` to **instance methods on `CallSession`** (the object returned by `joinSession`'s callback). Session teardown moved from the v4 static `CometChatCalls.endSession()` to the instance method `callSession.leaveSession()` — this is what both calls-sdk-android sample apps use and what the migration guide maps it to. Keep a reference to the `CallSession` (or use `CallSession.getInstance()`); v4 static receivers throw "method not found" against the v5 SDK.
 
 ```diff
 // session lifecycle — receiver changes from CometChatCalls (static) to CallSession (instance)
@@ -152,14 +167,15 @@ v5 moved most call-control APIs from static methods on `CometChatCalls` to **ins
 - CometChatCalls.pauseVideo(false)
 + callSession.resumeVideo()
 
+// screen share — Android is RECEIVE-ONLY in v5: there is NO screen-share initiation API.
+// Drop any startScreenShare()/stopScreenShare() calls; observe incoming shares via
+// ParticipantEventListener.onParticipantStartedScreenShare / onParticipantStoppedScreenShare.
 - CometChatCalls.startScreenShare()
-+ callSession.startScreenShare()
 - CometChatCalls.stopScreenShare()
-+ callSession.stopScreenShare()
 
-// layout — static on CometChatCalls in v5 (different from session methods)
+// layout — instance method on the CallSession in v5 (NOT static on CometChatCalls)
 - CometChatCalls.setMode(mode)
-+ CometChatCalls.setLayout(layout)
++ callSession.setLayout(layout)              // or CallSession.getInstance().setLayout(layout)
 ```
 
 **Hold onto the `CallSession` reference** returned by `joinSession`'s `onSuccess(callSession: CallSession)` callback — most v5 in-call APIs live there. Stashing it in an Activity field or ViewModel is the canonical pattern; the SDK also exposes `CallSession.getInstance()` as a fallback if you've lost the reference.
@@ -191,8 +207,8 @@ The seven hard rules from `cometchat-android-v5-calls/SKILL.md` still apply post
 - [ ] `app/build.gradle.kts` lists calls-sdk-android v5+
 - [ ] `./gradlew :app:dependencies` shows v5 resolved
 - [ ] `CometChatCalls.login(authToken)` called after `CometChat.login`
-- [ ] `CometChatCallsEventsListener` replaced with `addEventListener`
-- [ ] `CallSettings.Builder` replaced with `SessionSettings`
+- [ ] `CometChatCallsEventsListener` replaced with the five split listeners on the `CallSession` instance
+- [ ] `CallSettings.Builder` replaced with `CometChatCalls.SessionSettingsBuilder()`
 - [ ] Method renames applied
 - [ ] FCM VoIP push still arrives + ConnectionService still surfaces UI
 - [ ] Real-device smoke: 2 phones, foreground + backgrounded recipient, mic/camera/screenshare/end

package/skills/cometchat-android-v5-calls/references/participant-management.md

@@ -32,10 +32,10 @@ callSession.muteParticipant(participant.uid)
 callSession.pauseParticipantVideo(participant.uid)
 
 // Pin a participant (keeps them prominent in layout)
-callSession.pinParticipant(participant.uid)
+callSession.pinParticipant(participant.uid)  // per official docs (calls/android/participant-management)
 
 // Unpin (return to automatic speaker highlighting)
-callSession.unPinParticipant()
+callSession.unpinParticipant()
 ```
 
 ### Raise Hand (Self)
@@ -101,7 +101,7 @@ val sessionSettings = CometChatCalls.SessionSettingsBuilder()
 - By default, **all participants** have moderator access (can mute/pause others)
 - Implement role-based restrictions in your app logic if needed
 - Pinning only affects **your local view** — other participants can pin independently
-- `unPinParticipant()` takes no arguments — unpins whoever is currently pinned
+- `unpinParticipant()` takes no arguments — unpins whoever is currently pinned
 - `raisedHandTimestamp > 0` means hand is raised
 - There is no "kick" API — only mute and pause video
 

package/skills/cometchat-android-v5-calls/references/raise-hand.md

@@ -11,15 +11,18 @@ Native CometChat Calls SDK for Android. The shape mirrors web (raise/lower + lis
 
 ```kotlin
 import com.cometchat.calls.core.CometChatCalls
-import com.cometchat.calls.listeners.CometChatCallsEventsListener
+import com.cometchat.calls.core.CallSession
+import com.cometchat.calls.listeners.ParticipantEventListener
 import com.cometchat.calls.model.Participant
+import com.cometchat.calls.model.SessionType
 
-// Local user
-CometChatCalls.raiseHand()
-CometChatCalls.lowerHand()
+// Local user — raiseHand / lowerHand are instance methods on the CallSession singleton.
+CallSession.getInstance().raiseHand()
+CallSession.getInstance().lowerHand()
 
-// Listener — attached at session start
-val listener = object : CometChatCallsEventsListener {
+// Listener — raise/lower hand are participant events in v5.
+// Register on the CallSession instance from joinSession's onSuccess callback.
+callSession.addParticipantEventListener(this, object : ParticipantEventListener() {
   override fun onParticipantHandRaised(participant: Participant) {
     // participant.uid, participant.name
   }
@@ -27,11 +30,11 @@ val listener = object : CometChatCallsEventsListener {
   override fun onParticipantHandLowered(participant: Participant) {
     // ...
   }
-  // ... other event handlers
-}
+  // ... other participant event handlers
+})
 
 // Settings flag
-val settings = SessionSettingsBuilder(context, callContainer)
+val settings = CometChatCalls.SessionSettingsBuilder()
   .setSessionType(SessionType.VIDEO)
   .hideRaiseHandButton(true)
   .build()
@@ -40,17 +43,17 @@ val settings = SessionSettingsBuilder(context, callContainer)
 For **Java**:
 
 ```java
-CometChatCalls.raiseHand();
-CometChatCalls.lowerHand();
+CallSession.getInstance().raiseHand();
+CallSession.getInstance().lowerHand();
 
-CometChatCallsEventsListener listener = new CometChatCallsEventsListener() {
+callSession.addParticipantEventListener(this, new ParticipantEventListener() {
   @Override
   public void onParticipantHandRaised(Participant participant) { /* ... */ }
 
   @Override
   public void onParticipantHandLowered(Participant participant) { /* ... */ }
   // ...
-};
+});
 ```
 
 ---
@@ -63,7 +66,7 @@ For a single-Activity call surface:
 class CallActivity : AppCompatActivity() {
 
   private lateinit var raiseHandViewModel: RaiseHandViewModel
-  private val callListener = object : CometChatCallsEventsListener {
+  private val callListener = object : ParticipantEventListener() {
     override fun onParticipantHandRaised(p: Participant) {
       raiseHandViewModel.onRaised(p)
     }
@@ -76,12 +79,15 @@ class CallActivity : AppCompatActivity() {
   override fun onCreate(savedInstanceState: Bundle?) {
     super.onCreate(savedInstanceState)
     raiseHandViewModel = ViewModelProvider(this)[RaiseHandViewModel::class.java]
-    // Listener attached when session starts (rule 1.7 in cometchat-android-v5-calls)
+    // Register on the CallSession instance (from joinSession's onSuccess) when
+    // the session starts: callSession.addParticipantEventListener(this, callListener)
+    // (rule 1.7 in cometchat-android-v5-calls). Listeners are lifecycle-aware.
   }
 
   override fun onDestroy() {
     super.onDestroy()
-    // Listener cleanup happens in CometChatCalls.endSession
+    // Listeners are lifecycle-aware (bound to the Activity passed as the first
+    // arg) and auto-removed on destroy; otherwise leaveSession() tears them down.
   }
 }
 ```
@@ -106,9 +112,9 @@ class RaiseHandViewModel : ViewModel() {
 
   fun toggle() {
     if (_state.value.localRaised) {
-      CometChatCalls.lowerHand()
+      CallSession.getInstance().lowerHand()
     } else {
-      CometChatCalls.raiseHand()
+      CallSession.getInstance().raiseHand()
     }
     _state.update { it.copy(localRaised = !it.localRaised) }
   }
@@ -221,7 +227,7 @@ Web sister reference rules apply, plus Android-specific:
 ## Verification checklist
 
 - [ ] `RaiseHandViewModel` uses `StateFlow` (not LiveData) for the call state
-- [ ] Listener attached at session start, detached on `endSession`
+- [ ] `ParticipantEventListener` attached on the `CallSession` at session start (lifecycle-aware; also torn down by `leaveSession()`)
 - [ ] `repeatOnLifecycle(Lifecycle.State.STARTED)` wraps every collect
 - [ ] Toggle button has `contentDescription` + `isSelected` set
 - [ ] `announceForAccessibility` on state change

package/skills/cometchat-android-v5-calls/references/recording.md

@@ -51,11 +51,11 @@ callSession.addMediaEventsListener(this, object : MediaEventsListener() {
     override fun onAudioUnMuted() {}
     override fun onVideoPaused() {}
     override fun onVideoResumed() {}
-    override fun onScreenShareStarted() {}
-    override fun onScreenShareStopped() {}
     override fun onAudioModeChanged(audioMode: AudioMode) {}
     override fun onCameraFacingChanged(facing: CameraFacing) {}
 })
+// Screen-share is observed via ParticipantEventListener.onParticipantStartedScreenShare /
+// onParticipantStoppedScreenShare — NOT MediaEventsListener.
 ```
 
 ### Track Participant Recording

package/skills/cometchat-android-v5-calls/references/ringing-integration.md

@@ -15,7 +15,7 @@ Implement call ringing using both CometChat Chat SDK (signaling) and Calls SDK (
 - Both SDKs added to `build.gradle.kts`:
   ```kotlin
   implementation("com.cometchat:chat-sdk-android:4.0.+")
-  implementation("com.cometchat:calls-sdk-android:5.0.0-beta.2")
+  implementation("com.cometchat:calls-sdk-android:5.0.+")
   ```
 - Both SDKs initialized and user logged in to both
 

package/skills/cometchat-android-v5-calls/references/screen-sharing.md

@@ -61,21 +61,17 @@ override fun onParticipantListChanged(participants: List<Participant>) {
 }
 ```
 
-### Show/Hide Screen Share Button
+### Receive-only — no screen-share button
 
-```kotlin
-val sessionSettings = CometChatCalls.SessionSettingsBuilder()
-    .hideScreenSharingButton(true)  // hide since Android can't initiate
-    .build()
-```
+Android is **receive-only** for screen sharing — there is no screen-share initiation API and no screen-share button setting in `SessionSettingsBuilder`. There is nothing to hide; the SDK simply renders incoming screen shares from web clients.
 
 ## Gotchas
 
-- Android **cannot initiate** screen sharing — only web clients can
+- Android **cannot initiate** screen sharing — only web clients can; the SDK is receive-only
+- There is no screen-share button or `hideScreenSharingButton(...)` setting on Android
 - The SDK automatically adjusts the layout when a screen share starts
 - Use `participant.isPresenting` to check if someone is sharing
-- Consider hiding the screen share button on Android since it's not functional for initiating
-- `MediaEventsListener` also has `onScreenShareStarted()`/`onScreenShareStopped()` for local events
+- Screen-share is observed via `ParticipantEventListener.onParticipantStartedScreenShare(...)` / `onParticipantStoppedScreenShare(...)`
 
 ## Sample App Reference
 

package/skills/cometchat-android-v5-calls/references/session-settings.md

@@ -17,7 +17,7 @@ import com.cometchat.calls.core.CometChatCalls
 import com.cometchat.calls.model.SessionType   // VIDEO, VOICE
 import com.cometchat.calls.model.LayoutType    // TILE, SIDEBAR, SPOTLIGHT
 import com.cometchat.calls.model.AudioMode     // SPEAKER, EARPIECE, BLUETOOTH, HEADPHONES
-import com.cometchat.calls.model.CameraFacing  // FRONT, BACK
+import com.cometchat.calls.model.CameraFacing  // FRONT, REAR
 ```
 
 ## Implementation
@@ -38,7 +38,7 @@ val sessionSettings = CometChatCalls.SessionSettingsBuilder()
     .startAudioMuted(false)
     .startVideoPaused(false)
     .setAudioMode(AudioMode.SPEAKER)         // SPEAKER, EARPIECE, BLUETOOTH, HEADPHONES
-    .setInitialCameraFacing(CameraFacing.FRONT) // FRONT or BACK
+    .setInitialCameraFacing(CameraFacing.FRONT) // FRONT or REAR
 
     // Timeout & recording
     .setIdleTimeoutPeriod(300)               // seconds (default 300)
@@ -72,7 +72,7 @@ val sessionSettings = CometChatCalls.SessionSettingsBuilder()
 | `SessionType` | `VIDEO`, `VOICE` |
 | `LayoutType` | `TILE`, `SIDEBAR`, `SPOTLIGHT` |
 | `AudioMode` | `SPEAKER`, `EARPIECE`, `BLUETOOTH`, `HEADPHONES` |
-| `CameraFacing` | `FRONT`, `BACK` |
+| `CameraFacing` | `FRONT`, `REAR` |
 
 ### Common Presets
 

package/skills/cometchat-android-v5-calls/references/setup.md

@@ -46,7 +46,7 @@ In app-level `build.gradle.kts`:
 ```kotlin
 dependencies {
     // CometChat Calls SDK v5
-    implementation("com.cometchat:calls-sdk-android:5.0.0-beta.2")
+    implementation("com.cometchat:calls-sdk-android:5.0.+")
 
     // If using ringing (dual-SDK), also add Chat SDK:
     // implementation("com.cometchat:chat-sdk-android:4.0.+")

package/skills/cometchat-android-v5-calls/references/share-invite.md

@@ -70,17 +70,22 @@ private fun handleDeepLink(intent: Intent?) {
 ## SDK API
 
 ```kotlin
-val settings = CallSettingsBuilder(activity)
-  .setHideShareInviteButton(false)
+import com.cometchat.calls.core.CometChatCalls
+import com.cometchat.calls.listeners.ButtonClickListener
+
+val settings = CometChatCalls.SessionSettingsBuilder()
+  .hideShareInviteButton(false)
   .build()
 
-val callsEventsListener = object : CometChatCallsEventsListener {
+// onShareInviteButtonClicked() lives on ButtonClickListener in v5.
+// Register on the CallSession instance from joinSession's onSuccess callback.
+callSession.addButtonClickListener(activity, object : ButtonClickListener() {
   override fun onShareInviteButtonClicked() {
     activity.runOnUiThread {
       shareCallInvite(sessionId)
     }
   }
-}
+})
 ```
 
 ---

package/skills/cometchat-android-v5-calls/references/video-controls.md

@@ -48,7 +48,7 @@ callSession.addMediaEventsListener(this, object : MediaEventsListener() {
     override fun onCameraFacingChanged(facing: CameraFacing) {
         when (facing) {
             CameraFacing.FRONT -> { /* front camera active */ }
-            CameraFacing.BACK -> { /* rear camera active */ }
+            CameraFacing.REAR -> { /* rear camera active */ }
         }
     }
     // ... other required overrides
@@ -56,10 +56,10 @@ callSession.addMediaEventsListener(this, object : MediaEventsListener() {
     override fun onAudioUnMuted() {}
     override fun onRecordingStarted() {}
     override fun onRecordingStopped() {}
-    override fun onScreenShareStarted() {}
-    override fun onScreenShareStopped() {}
     override fun onAudioModeChanged(audioMode: AudioMode) {}
 })
+// Screen-share is observed via ParticipantEventListener.onParticipantStartedScreenShare /
+// onParticipantStoppedScreenShare — NOT MediaEventsListener.
 ```
 
 ### Initial Video Settings (Pre-Session)
@@ -78,7 +78,7 @@ val sessionSettings = CometChatCalls.SessionSettingsBuilder()
 
 - `pauseVideo()` / `resumeVideo()` only work during an active session
 - `switchCamera()` toggles between front and back — no parameter needed
-- `CameraFacing` enum: `FRONT`, `BACK`
+- `CameraFacing` enum: `FRONT`, `REAR`
 - For voice calls (`SessionType.VOICE`), set `.startVideoPaused(true)`
 - Camera permissions must be granted at runtime before joining
 

package/skills/cometchat-android-v5-calls/references/voip-calling.md

@@ -12,7 +12,7 @@ Native VoIP calling using Android's Telecom framework (`ConnectionService`). Sho
 
 ## Prerequisites
 
-- Chat SDK v4 (`com.cometchat:chat-sdk-android:4.0.+`) + Calls SDK v5 (`com.cometchat:calls-sdk-android:5.0.0-beta.2`) integrated
+- Chat SDK v4 (`com.cometchat:chat-sdk-android:4.0.+`) + Calls SDK v5 (`com.cometchat:calls-sdk-android:5.0.+`) integrated
 - Firebase Cloud Messaging (FCM) configured with `com.google.gms.google-services` plugin
 - Push notifications enabled in CometChat Dashboard
 - Android 8.0+ (API 26+), compileSdk 35
@@ -480,7 +480,7 @@ When a call is accepted (via ConnectionService or fallback notification), launch
 val isVoiceOnly = callType == CometChatConstants.CALL_TYPE_AUDIO
 val settings = CometChatCalls.SessionSettingsBuilder()
     .setTitle("CometChat Call")
-    .setType(if (isVoiceOnly) SessionType.VOICE else SessionType.VIDEO)
+    .setSessionType(if (isVoiceOnly) SessionType.VOICE else SessionType.VIDEO)
     .setLayout(if (isVoiceOnly) LayoutType.SPOTLIGHT else LayoutType.TILE)
     .setAudioMode(if (isVoiceOnly) AudioMode.EARPIECE else AudioMode.SPEAKER)
     .startVideoPaused(isVoiceOnly)

package/skills/cometchat-android-v5-components/SKILL.md

@@ -3,13 +3,14 @@ name: cometchat-android-v5-components
 description: "Complete catalog of CometChat Android UI Kit v5 components. Reference before writing integration code — never invent component names."
 license: "MIT"
 compatibility: "Android 7.0+; Java 8+; Kotlin 1.8+; com.cometchat:chat-uikit-android:5.x"
-allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"
   tags: "chat cometchat android components catalog reference ui-kit views"
 ---
 
+> **Ground truth:** `com.cometchat:chat-uikit-android:5.x` (legacy/maintenance-only) component catalog (javap the AAR) + `docs/ui-kit/android`. **Official docs:** https://www.cometchat.com/docs/ui-kit/android/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.
+
 > **Companion skills:** `cometchat-android-v5-core` covers initialization and login;
 > `cometchat-android-v5-placement` covers where to put these components;
 > `cometchat-android-v5-customization` covers how to modify component behavior.
@@ -18,7 +19,7 @@ metadata:
 
 This is the single source of truth for CometChat Android UI Kit v5 component names, key methods, and usage. **Check this catalog before writing any CometChat view code.** If a component is not listed here, it does not exist in the UI Kit.
 
-All components extend `MaterialCardView` and can be used in XML layouts or created programmatically. They follow a consistent pattern: set a `User` or `Group` object, configure visibility/style via setters, and attach callbacks for user interactions.
+Most top-level components extend `MaterialCardView` and can be used in XML layouts or created programmatically. Some lower-level views have different base classes — e.g. `CometChatDate` extends `LinearLayout`, `CometChatMessageReceipt` extends `AppCompatImageView`, `CometChatEmojiKeyboard` extends `BottomSheetDialogFragment`, and `CometChatConfirmDialog` extends `Dialog`. The main components follow a consistent pattern: set a `User` or `Group` object, configure visibility/style via setters, and attach callbacks for user interactions.
 
 
 ---
@@ -213,7 +214,7 @@ Renders a scrollable list of users with alphabetical sticky headers.
 | `setSelectionMode(UIKitConstants.SelectionMode)` | Config | `NONE`, `SINGLE`, `MULTIPLE` |
 | `setSearchBoxVisibility(int)` | Visibility | Show/hide search bar |
 | `setUserStatusVisibility(int)` | Visibility | Show/hide online status |
-| `setOnSelection(OnSelection<User>)` | Callback | Called when selection changes |
+| `setOnSelect(OnSelection<User>)` | Callback | Called when selection changes (note: `setOnSelect` for Users + Conversations; `setOnSelection` for Groups + GroupMembers) |
 
 ### CometChatGroups
 

package/skills/cometchat-android-v5-core/SKILL.md

@@ -3,13 +3,14 @@ name: cometchat-android-v5-core
 description: "Foundational rules for CometChat Android UI Kit v5. Initialization, login, UIKitSettings builder, dependency setup, and anti-patterns. Read this first."
 license: "MIT"
 compatibility: "Android 7.0+; Java 8+; Kotlin 1.8+; com.cometchat:chat-uikit-android:5.x"
-allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"
   tags: "chat cometchat android core rules initialization login builder patterns"
 ---
 
+> **Ground truth:** `com.cometchat:chat-uikit-android:5.x` (+ `chat-sdk-android:4.x`, `calls-sdk-android:5.x`) — `javap` the resolved AARs from the Gradle cache + `docs/ui-kit/android`. **Official docs:** https://www.cometchat.com/docs/ui-kit/android/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP). V5 is legacy/maintenance-only (V6 is current); verify symbols against the resolved AAR.
+
 > **Companion skills:** `cometchat-android-v5-components` provides the component
 > catalog (what exists); `cometchat-android-v5-placement` covers where to put
 > chat in your app; `cometchat-android-v5-theming` covers visual customization.
@@ -57,7 +58,7 @@ The UI Kit transitively pulls in the CometChat Chat SDK. For voice/video calling
 ```groovy
 dependencies {
     implementation 'com.cometchat:chat-uikit-android:5.+'
-    implementation 'com.cometchat:calls-sdk-android:4.+'  // optional — only for calls
+    implementation 'com.cometchat:calls-sdk-android:5.0.+'  // optional — only for calls (V5 calls SDK = 5.x; matches cometchat-android-v5-calls)
 }
 ```
 
@@ -466,3 +467,20 @@ class SplashActivity : AppCompatActivity() {
 - **App theme must inherit from `CometChatTheme.DayNight`.** The kit itself parents on `Theme.MaterialComponents.DayNight.NoActionBar` (Material 2). Inheriting from `Theme.AppCompat.*` or `Theme.Material3.*` triggers `UnsupportedOperationException: Failed to resolve attribute` at inflate time.
 - **Always use the published Maven artifact for dependencies, never local project modules.** Use `implementation 'com.cometchat:chat-uikit-android:5.+'` — never `implementation project(':chatuikit')`. Local module references only apply to CometChat's own internal sample apps. External apps must always depend on the published artifact from the CometChat Maven repository.
 - **`gradle.properties` MUST contain `android.useAndroidX=true` AND `android.enableJetifier=true`.** Both lines, no exceptions. The CometChat V5 Android SDK transitively depends on the legacy `com.android.support:support-compat`. Without Jetifier rewriting those references to `androidx.*` at build time, Gradle hits "Duplicate class android.support.v4.os.ResultReceiver$1" and the build fails. Modern Android Studio scaffolds set `useAndroidX=true` by default but leave Jetifier off — the integration must add the Jetifier line. Idempotent — if both lines are already present, no change.
+
+## Visual Builder integration
+
+**Android V5 is the primary home for Visual Builder integration.** The canonical repo at the Android Visual Builder ZIP (download from https://preview.cometchat.com/downloads/cometchat-builder-android.zip) ships **V5-shaped code** — `com.cometchat:chat-uikit-android:5.2.6` + `com.cometchat:calls-sdk-android:4.3.1`. The Gradle plugin `com.cometchat.builder.settings:5.0.1` auto-generates a `CometChatBuilderSettings` constants class from `cometchat-builder-settings.json` at build time. The plugin's output is plain Kotlin `object` declarations — usable from both V5 Views (the canonical path) and V6 Compose / Kotlin Views code, though V6 deps need to be added separately to a V6 project.
+
+> **➡️ FOLLOW THE FULL RECIPE IN `cometchat-android-v6-core` §"Visual Builder integration" AS-IS.** That page holds the complete validated content (`builder export` flow, the Place + patch table, the F50/F51 `BuilderSettingsHelper.kt` transforms, the default Views `MessagesActivity` surface, the Files-patched table). Both skills reference the same V5-shaped canonical, so V5 customers follow it verbatim — it targets V5 deps natively (no shim needed). The only V5-specific deltas are listed under "Differences" below.
+
+Validated 2026-05-21 against builder-plugin 5.0.1: `./gradlew :chat-builder:assembleDebug` produces `chat-builder-debug.apk` after applying:
+- **`settings.gradle.kts` — add the Cloudsmith Maven repo `maven("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/")` to BOTH `pluginManagement.repositories` AND `dependencyResolutionManagement.repositories`.** Without it in `pluginManagement`, the `com.cometchat.builder.settings:5.0.1` plugin fails to resolve (`Plugin [id: 'com.cometchat.builder.settings', version: '5.0.1'] was not found`); without it in `dependencyResolutionManagement`, the `chat-uikit-android` / `calls-sdk-android` artifacts fail to resolve. This matches the canonical repo's `settings.gradle.kts` (Cloudsmith present in both blocks).
+- Envelope-wrapped `cometchat-builder-settings.json` (`{ builderId, name, settings: {...} }` — NOT raw settings blob)
+- Two missing-field defaults injected pre-write: `chatFeatures.deeperUserEngagement.mentionAll: true` + `chatFeatures.inAppSounds: { incomingMessageSound: true, outgoingMessageSound: true }`
+- `android.enableJetifier=true` in `gradle.properties`
+- `@style/CometChat.Builder.Theme` set on `<application>` in `AndroidManifest.xml`
+
+Differences from the V6 page's recipe text:
+- V5 calls integration uses `cometchat-android-v5-calls` patterns (see [[project_v6_calls_sdk_still_required]] for context — V5 customers don't hit the V6-specific workarounds, but the calls SDK requirement is the same).
+- The Compose stack split (`chatuikit-compose-android` vs `chatuikit-kotlin-android`) doesn't apply to V5 — the V5 UI Kit is Kotlin Views only.