@cometchat/skills 4.0.0 → 4.2.0

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

@@ -0,0 +1,206 @@
+# CometChat Calls Android SDK v4 → v5 migration
+
+`com.cometchat:calls-sdk-android:5.+` is a drop-in upgrade for v4 — bump the Gradle dependency, existing code still compiles thanks to deprecated method shims.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/android/migration-guide-v5
+
+**Important:** This is the migration for the **Calls SDK** (v4 → v5 of the calls dependency). It is NOT the same as the **UI Kit cohort migration** (V5 cohort → V6 Compose cohort), which is documented in `cometchat-android-v6-migration`. You can be on UI Kit V5 cohort with Calls SDK v5 — they version independently.
+
+---
+
+## Step 1 — Bump the Gradle dependency
+
+```kotlin
+// app/build.gradle.kts
+dependencies {
+  implementation("com.cometchat:calls-sdk-android:5.+")
+}
+```
+
+```bash
+./gradlew :app:dependencies | grep calls-sdk
+```
+
+Should show `com.cometchat:calls-sdk-android:5.x.x`.
+
+---
+
+## Step 2 — Migrate init to plain config
+
+```diff
+- val callAppSettings = CallAppSettings.Builder()
+-   .setAppId("APP_ID")
+-   .setRegion("REGION")
+-   .build()
+- CometChatCalls.init(callAppSettings, object : CometChatCalls.CallbackListener<String>() {
+-   override fun onSuccess(s: String) { /* ... */ }
+-   override fun onError(e: CometChatException) { /* ... */ }
+- })
+
++ val settings = CallAppSettings(appId = "APP_ID", region = "REGION")
++ CometChatCalls.init(settings, object : CometChatCalls.CallbackListener<String>() {
++   override fun onSuccess(s: String) { /* ... */ }
++   override fun onError(e: CometChatException) { /* ... */ }
++ })
+```
+
+(V5 also supports coroutine-suspend `init` via `kotlinx.coroutines` extensions, if you've enabled them.)
+
+---
+
+## Step 3 — Add Calls SDK login (mandatory)
+
+In v5 the Calls SDK has its own auth state, separate from the Chat SDK. Without a Calls SDK login step, the FIRST calls API call (initiate, join, generateToken) throws **"auth token cannot be null"**.
+
+The Android v5 Calls SDK exposes two `CometChatCalls.login` overloads — match the API exactly:
+
+```kotlin
+import com.cometchat.calls.core.CometChatCalls
+import com.cometchat.calls.exceptions.CometChatException as CallsException
+import com.cometchat.calls.model.CallUser   // ← callback returns CallUser, NOT User
+
+// Dev mode (Auth Key)
+CometChatCalls.login(uid, AUTH_KEY,
+    object : CometChatCalls.CallbackListener<CallUser>() {
+        override fun onSuccess(callUser: CallUser) {
+            // calls SDK is now ready
+        }
+        override fun onError(e: CallsException) {
+            // surface to user — common cause: typo in app id / auth key
+        }
+    })
+
+// Production mode (server-minted auth token)
+CometChatCalls.login(authToken,
+    object : CometChatCalls.CallbackListener<CallUser>() { /* … */ })
+```
+
+**Hard rules:**
+
+1. **Call this AFTER `CometChat.login()` succeeds** — the Calls SDK login won't work until the Chat SDK has a valid session.
+2. **The callback receives `com.cometchat.calls.model.CallUser`**, not `com.cometchat.chat.models.User`. Importing the wrong type produces "Type mismatch" at compile time.
+3. **Re-login on every cold start** — the Chat SDK persists login across launches via Shared Prefs; the Calls SDK does NOT. Each app launch where `CometChat.getLoggedInUser()` returns non-null still needs a fresh `CometChatCalls.login` call.
+4. **Don't try `user.authToken`** — `com.cometchat.chat.models.User` does NOT expose `authToken` as a Kotlin property or Java getter on Android. Use the (uid, apiKey) overload for dev, or fetch the auth token from your backend for production. *(This trapped a real smoke run — the chat-side User object hides the auth token.)*
+
+After this step, `generateToken()` no longer needs the authToken parameter — the Calls SDK uses its internal session.
+
+---
+
+## Step 4 — Migrate CallSettings.Builder to SessionSettings
+
+```diff
+- val callSettings = CallSettings.Builder(activity)
+-   .setSessionType(SessionType.VIDEO)
+-   .startWithAudioMuted(false)
+-   .showRecordingButton(true)
+-   .build()
+
++ val sessionSettings = SessionSettings(
++   sessionType = SessionType.VIDEO,
++   startAudioMuted = false,
++   hideRecordingButton = false,    // INVERTED
++   layout = LayoutType.TILE,
++ )
+```
+
+---
+
+## Step 5 — Migrate listener interface to event listeners
+
+```diff
+- class MyCallEvents : CometChatCallsEventsListener {
+-   override fun onCallEnded() { /* ... */ }
+-   override fun onUserJoined(user: User) { /* ... */ }
+-   override fun onUserLeft(user: User) { /* ... */ }
+-   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()
++ }
+```
+
+---
+
+## 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.
+
+```diff
+// session lifecycle — receiver changes from CometChatCalls (static) to CallSession (instance)
+- CometChatCalls.endSession()
++ callSession.leaveSession()                       // call on the CallSession from joinSession's onSuccess
++ // OR if you don't have the reference handy:
++ CallSession.getInstance().leaveSession()
+
+// media controls — same receiver shift
+- CometChatCalls.muteAudio(true)
++ callSession.muteAudio()
+- CometChatCalls.muteAudio(false)
++ callSession.unmuteAudio()
+
+- CometChatCalls.pauseVideo(true)
++ callSession.pauseVideo()
+- CometChatCalls.pauseVideo(false)
++ callSession.resumeVideo()
+
+- CometChatCalls.startScreenShare()
++ callSession.startScreenShare()
+- CometChatCalls.stopScreenShare()
++ callSession.stopScreenShare()
+
+// layout — static on CometChatCalls in v5 (different from session methods)
+- CometChatCalls.setMode(mode)
++ CometChatCalls.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.
+
+---
+
+## Step 7 — Compose call surface unchanged
+
+If you're using XML `CometChatCallActivity`, no changes. If you've embedded the call surface via `CometChatOngoingCallView`, the v5 SDK's view component takes `SessionSettings` directly:
+
+```diff
+- callView.startCall(callSettings)
++ callView.joinSession(sessionSettings)
+```
+
+---
+
+## ConnectionService + ForegroundServiceType (no v5 changes)
+
+The seven hard rules from `cometchat-android-v5-calls/SKILL.md` still apply post-v5:
+- ConnectionService for incoming calls
+- `foregroundServiceType="microphone"` (or `camera|microphone`) for active calls
+- Hangup teardown sequence
+
+---
+
+## Verification checklist
+
+- [ ] `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`
+- [ ] Method renames applied
+- [ ] FCM VoIP push still arrives + ConnectionService still surfaces UI
+- [ ] Real-device smoke: 2 phones, foreground + backgrounded recipient, mic/camera/screenshare/end
+
+---
+
+## Pointers
+
+- Canonical migration: https://www.cometchat.com/docs/calls/android/migration-guide-v5
+- `cometchat-android-v5-calls/SKILL.md` — seven hard rules (unchanged in v5)
+- `cometchat-android-v5-calls/references/server-fcm-voip.md` — FCM (unchanged in v5)

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

@@ -0,0 +1,110 @@
+---
+name: participant-management
+description: Manage call participants — mute, pause video, pin/unpin, raise hand, view participant list. Use when implementing moderation, participant actions, or custom participant UI. Triggers on "mute participant", "pin participant", "participant list", "raise hand", "kick participant", "participant management".
+inclusion: manual
+---
+
+# CometChat Calls SDK v5 — Participant Management
+
+## Overview
+
+Control other participants during calls: mute their audio, pause their video, pin/unpin in layout. Monitor participant state via `ParticipantEventListener`. Raise hand is available for self.
+
+## Key Imports
+
+```kotlin
+import com.cometchat.calls.core.CallSession
+import com.cometchat.calls.listeners.ParticipantEventListener
+import com.cometchat.calls.model.Participant
+```
+
+## Implementation
+
+### Participant Actions
+
+```kotlin
+val callSession = CallSession.getInstance()
+
+// Mute a participant's audio
+callSession.muteParticipant(participant.uid)
+
+// Pause a participant's video
+callSession.pauseParticipantVideo(participant.uid)
+
+// Pin a participant (keeps them prominent in layout)
+callSession.pinParticipant(participant.uid)
+
+// Unpin (return to automatic speaker highlighting)
+callSession.unPinParticipant()
+```
+
+### Raise Hand (Self)
+
+Raise hand is controlled via the built-in UI button. Listen for it:
+
+```kotlin
+callSession.addButtonClickListener(this, object : ButtonClickListener() {
+    override fun onRaiseHandButtonClicked() {
+        Log.d(TAG, "Hand raised/lowered")
+    }
+    // ... other overrides
+})
+```
+
+### Listen for Participant Events
+
+```kotlin
+callSession.addParticipantEventListener(this, object : ParticipantEventListener() {
+    override fun onParticipantJoined(participant: Participant) {}
+    override fun onParticipantLeft(participant: Participant) {}
+    override fun onParticipantListChanged(participants: List<Participant>) {
+        // Full participant list — use for UI updates
+    }
+    override fun onParticipantAudioMuted(participant: Participant) {}
+    override fun onParticipantAudioUnmuted(participant: Participant) {}
+    override fun onParticipantVideoPaused(participant: Participant) {}
+    override fun onParticipantVideoResumed(participant: Participant) {}
+    override fun onParticipantHandRaised(participant: Participant) {}
+    override fun onParticipantHandLowered(participant: Participant) {}
+    override fun onDominantSpeakerChanged(participant: Participant) {}
+    override fun onParticipantStartedScreenShare(participant: Participant) {}
+    override fun onParticipantStoppedScreenShare(participant: Participant) {}
+    override fun onParticipantStartedRecording(participant: Participant) {}
+    override fun onParticipantStoppedRecording(participant: Participant) {}
+})
+```
+
+### Participant Object Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `uid` | String | CometChat user ID |
+| `name` | String | Display name |
+| `avatar` | String | Avatar URL |
+| `isAudioMuted` | Boolean | Audio muted? |
+| `isVideoPaused` | Boolean | Video paused? |
+| `isPinned` | Boolean | Pinned in layout? |
+| `isPresenting` | Boolean | Screen sharing? |
+| `raisedHandTimestamp` | Long | 0 if not raised |
+
+### Show/Hide Participant List Button
+
+```kotlin
+val sessionSettings = CometChatCalls.SessionSettingsBuilder()
+    .hideParticipantListButton(false)  // show participant list
+    .hideRaiseHandButton(false)        // show raise hand
+    .build()
+```
+
+## Gotchas
+
+- 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
+- `raisedHandTimestamp > 0` means hand is raised
+- There is no "kick" API — only mute and pause video
+
+## Sample App Reference
+
+- `CallActivity.kt` — `setupCallListeners()` with `ButtonClickListener`

package/skills/cometchat-android-v5-calls/references/picture-in-picture.md

@@ -0,0 +1,106 @@
+---
+name: picture-in-picture
+description: Enable Picture-in-Picture mode for calls. Use when implementing PiP, floating call window, auto-PiP on home press, or PiP layout events. Triggers on "picture in picture", "PiP", "pip mode", "floating window".
+inclusion: manual
+---
+
+# CometChat Calls SDK v5 — Picture-in-Picture
+
+## Overview
+
+PiP lets users continue calls in a floating window while using other apps. Your app manages Android's PiP APIs; the Calls SDK adjusts the call UI layout to fit the smaller window.
+
+## Prerequisites
+
+- Android 8.0+ (API 26+)
+- Active call session
+
+## Key Imports
+
+```kotlin
+import android.app.PictureInPictureParams
+import android.util.Rational
+import com.cometchat.calls.core.CallSession
+import com.cometchat.calls.listeners.LayoutListener
+import com.cometchat.calls.model.LayoutType
+```
+
+## Implementation
+
+### Manifest Configuration
+
+```xml
+<activity
+    android:name=".CallActivity"
+    android:supportsPictureInPicture="true"
+    android:configChanges="screenSize|smallestScreenSize|screenLayout|orientation" />
+```
+
+### Enable/Disable PiP Layout
+
+```kotlin
+val callSession = CallSession.getInstance()
+
+// Tell SDK to adjust UI for PiP
+callSession.enablePictureInPictureLayout()
+
+// Restore full UI
+callSession.disablePictureInPictureLayout()
+```
+
+### Auto-Enter PiP on Home Press
+
+```kotlin
+override fun onUserLeaveHint() {
+    super.onUserLeaveHint()
+    if (CallSession.getInstance().isSessionActive) {
+        enterPictureInPictureMode(
+            PictureInPictureParams.Builder()
+                .setAspectRatio(Rational(16, 9))
+                .build()
+        )
+        CallSession.getInstance().enablePictureInPictureLayout()
+    }
+}
+```
+
+### Handle PiP Mode Changes
+
+```kotlin
+override fun onPictureInPictureModeChanged(isInPiPMode: Boolean, config: Configuration) {
+    super.onPictureInPictureModeChanged(isInPiPMode, config)
+    if (isInPiPMode) {
+        CallSession.getInstance().enablePictureInPictureLayout()
+    } else {
+        CallSession.getInstance().disablePictureInPictureLayout()
+    }
+}
+```
+
+### Listen for PiP Events
+
+```kotlin
+callSession.addLayoutListener(this, object : LayoutListener() {
+    override fun onPictureInPictureLayoutEnabled() {
+        // Hide custom overlays/controls
+    }
+    override fun onPictureInPictureLayoutDisabled() {
+        // Show custom overlays/controls
+    }
+    override fun onCallLayoutChanged(layoutType: LayoutType) {}
+    override fun onParticipantListVisible() {}
+    override fun onParticipantListHidden() {}
+})
+```
+
+## Gotchas
+
+- The SDK only adjusts the **call UI layout** — your app must call `enterPictureInPictureMode()` itself
+- `configChanges` in manifest prevents activity restart during PiP transitions
+- PiP has no effect on Android < 8.0
+- Hide custom controls in PiP mode — they won't be usable in the small window
+- Use `isSessionActive` check before entering PiP to avoid errors
+
+## Sample App Reference
+
+- `CallActivity.kt` — Call activity that could be extended with PiP support

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

@@ -0,0 +1,242 @@
+# Raise hand on Android V5 (Java + Kotlin Views)
+
+Native CometChat Calls SDK for Android. The shape mirrors web (raise/lower + listener events + button-hide flag); Android-specific is the listener attachment lifecycle (Activity/Fragment) + accessibility via `View.announceForAccessibility`.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/android/raise-hand
+**Read first:** `cometchat-react-calls/references/raise-hand.md` — UX shape + anti-patterns.
+
+---
+
+## SDK API
+
+```kotlin
+import com.cometchat.calls.core.CometChatCalls
+import com.cometchat.calls.listeners.CometChatCallsEventsListener
+import com.cometchat.calls.model.Participant
+
+// Local user
+CometChatCalls.raiseHand()
+CometChatCalls.lowerHand()
+
+// Listener — attached at session start
+val listener = object : CometChatCallsEventsListener {
+  override fun onParticipantHandRaised(participant: Participant) {
+    // participant.uid, participant.name
+  }
+
+  override fun onParticipantHandLowered(participant: Participant) {
+    // ...
+  }
+  // ... other event handlers
+}
+
+// Settings flag
+val settings = SessionSettingsBuilder(context, callContainer)
+  .setSessionType(SessionType.VIDEO)
+  .hideRaiseHandButton(true)
+  .build()
+```
+
+For **Java**:
+
+```java
+CometChatCalls.raiseHand();
+CometChatCalls.lowerHand();
+
+CometChatCallsEventsListener listener = new CometChatCallsEventsListener() {
+  @Override
+  public void onParticipantHandRaised(Participant participant) { /* ... */ }
+
+  @Override
+  public void onParticipantHandLowered(Participant participant) { /* ... */ }
+  // ...
+};
+```
+
+---
+
+## Lifecycle: where to attach the listener
+
+For a single-Activity call surface:
+
+```kotlin
+class CallActivity : AppCompatActivity() {
+
+  private lateinit var raiseHandViewModel: RaiseHandViewModel
+  private val callListener = object : CometChatCallsEventsListener {
+    override fun onParticipantHandRaised(p: Participant) {
+      raiseHandViewModel.onRaised(p)
+    }
+    override fun onParticipantHandLowered(p: Participant) {
+      raiseHandViewModel.onLowered(p)
+    }
+    // ...
+  }
+
+  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)
+  }
+
+  override fun onDestroy() {
+    super.onDestroy()
+    // Listener cleanup happens in CometChatCalls.endSession
+  }
+}
+```
+
+For Fragment-hosted calls, attach in `onViewCreated`, detach in `onDestroyView`.
+
+---
+
+## ViewModel pattern (Kotlin coroutines + StateFlow)
+
+```kotlin
+data class RaisedParticipant(val uid: String, val name: String, val raisedAt: Long)
+
+data class RaiseHandUiState(
+  val localRaised: Boolean = false,
+  val raised: List<RaisedParticipant> = emptyList(),
+)
+
+class RaiseHandViewModel : ViewModel() {
+  private val _state = MutableStateFlow(RaiseHandUiState())
+  val state: StateFlow<RaiseHandUiState> = _state
+
+  fun toggle() {
+    if (_state.value.localRaised) {
+      CometChatCalls.lowerHand()
+    } else {
+      CometChatCalls.raiseHand()
+    }
+    _state.update { it.copy(localRaised = !it.localRaised) }
+  }
+
+  fun onRaised(p: Participant) {
+    val entry = RaisedParticipant(p.uid, p.name, System.currentTimeMillis())
+    _state.update { state ->
+      val next = state.raised.filter { it.uid != p.uid } + entry
+      state.copy(raised = next.sortedBy { it.raisedAt })
+    }
+  }
+
+  fun onLowered(p: Participant) {
+    _state.update { state ->
+      state.copy(raised = state.raised.filter { it.uid != p.uid })
+    }
+  }
+}
+```
+
+`StateFlow` is the canonical Android single-source-of-truth pattern. Activities collect via `viewLifecycleOwner.lifecycleScope.launch` + `repeatOnLifecycle(STARTED)`.
+
+---
+
+## Toggle button
+
+```kotlin
+class RaiseHandButton @JvmOverloads constructor(
+  context: Context,
+  attrs: AttributeSet? = null,
+) : MaterialButton(context, attrs) {
+
+  init {
+    setOnClickListener {
+      val raised = (tag as? Boolean) ?: false
+      tag = !raised
+      // VM toggle handled by Activity wiring — see below
+    }
+  }
+
+  fun bind(viewModel: RaiseHandViewModel, lifecycleOwner: LifecycleOwner) {
+    setOnClickListener {
+      viewModel.toggle()
+    }
+
+    lifecycleOwner.lifecycleScope.launch {
+      lifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) {
+        viewModel.state.collect { state ->
+          text = if (state.localRaised) "Lower" else "Raise"
+          icon = ContextCompat.getDrawable(context,
+            if (state.localRaised) R.drawable.ic_hand_raised_filled
+            else R.drawable.ic_hand_raised)
+          contentDescription = if (state.localRaised) "Lower hand" else "Raise hand"
+          // a11y announcement on state change
+          announceForAccessibility(if (state.localRaised) "Hand raised" else "Hand lowered")
+          isSelected = state.localRaised
+        }
+      }
+    }
+  }
+}
+```
+
+`announceForAccessibility` is the Android equivalent of web's `aria-live` and iOS's `UIAccessibility.post(.announcement, ...)`. TalkBack picks it up.
+
+---
+
+## Raised-hands BottomSheet
+
+```kotlin
+class RaisedHandsBottomSheet : BottomSheetDialogFragment() {
+
+  private val viewModel: RaiseHandViewModel by activityViewModels()
+
+  override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View {
+    val view = inflater.inflate(R.layout.bottomsheet_raised_hands, container, false)
+    val recyclerView = view.findViewById<RecyclerView>(R.id.raised_hands_list)
+    val adapter = RaisedHandsAdapter()
+    recyclerView.adapter = adapter
+
+    viewLifecycleOwner.lifecycleScope.launch {
+      viewLifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) {
+        viewModel.state.collect { state ->
+          adapter.submitList(state.raised)
+        }
+      }
+    }
+
+    return view
+  }
+}
+```
+
+Use `BottomSheetDialogFragment` from `com.google.android.material.bottomsheet` — the canonical Material Design pattern for raised-hands roster on phones.
+
+---
+
+## Anti-patterns
+
+Web sister reference rules apply, plus Android-specific:
+
+1. **Listener in `init { }` of an Activity.** Activity init runs before `onCreate`; SDK might not be ready. Attach in `onCreate` or later.
+2. **Skipping `repeatOnLifecycle(STARTED)`.** Without it, `StateFlow.collect` runs even when Activity is paused — burns CPU during background.
+3. **Forgetting `lifecycleScope`.** Detached coroutines leak across activity destruction.
+4. **`MutableStateFlow.value = ...` from background thread without `_state.update`.** Race conditions on the list. Always use `update { ... }` for atomic state transitions.
+5. **`announceForAccessibility` from `setOnClickListener`** before the visual state has changed. Order matters — update the View first, then announce.
+
+---
+
+## Verification checklist
+
+- [ ] `RaiseHandViewModel` uses `StateFlow` (not LiveData) for the call state
+- [ ] Listener attached at session start, detached on `endSession`
+- [ ] `repeatOnLifecycle(Lifecycle.State.STARTED)` wraps every collect
+- [ ] Toggle button has `contentDescription` + `isSelected` set
+- [ ] `announceForAccessibility` on state change
+- [ ] `hideRaiseHandButton(true)` in SessionSettingsBuilder if custom UI
+- [ ] BottomSheetDialogFragment for raised-hands roster (phones) OR side panel (tablets)
+- [ ] Real-device smoke: 3 Android phones in same call, 2 raise → host's sheet shows both
+- [ ] TalkBack smoke: hand raise + lower announces correctly
+
+---
+
+## Pointers
+
+- `cometchat-react-calls/references/raise-hand.md` — sister reference (UX shape)
+- `cometchat-android-v5-calls` SKILL.md — V5 hard rules
+- `references/participant-management.md` — group call moderation patterns
+- `references/custom-ui.md` — Android custom call UI
+- Canonical docs: https://www.cometchat.com/docs/calls/android/raise-hand
+- For V6 (Compose / Kotlin Views split): `cometchat-android-v6-calls/references/raise-hand.md`