@cometchat/skills 4.2.1 → 4.4.0

package/skills/cometchat-android-v6-calls/SKILL.md

@@ -1,18 +1,19 @@
 ---
 name: cometchat-android-v6-calls
-description: CometChat Calls v6 integration for native Android (V6 beta — Compose + Kotlin Views). Works end-to-end on chatuikit-compose-android:6.0.0 (validated 2026-05-12 against web peer) — but only with FIVE non-obvious workarounds the kit itself doesn't ship: (1) explicit `calls-sdk-android:5.0.+` peer dep, (2) `annotations-java5` exclude, (3) stub classes for legacy `com.cometchat.calls.{CometChatRTCView, model.RTCUser, model.RTCReceiver, model.RTCCallback}` to satisfy chat-sdk's CallManager bytecode, (4) AVOID `CometChatCallButtons` (broken — captures first-rendered user globally; ignores per-row prop) — instead wire your own button → `CometChat.initiateCall` → `CometChatCallActivity.Companion.launchOutgoingCallScreen(context, call, null)`, (5) `Call` constructor arg order CHANGED in chat-sdk 5.x: `(receiverUid, receiverType, type)` not `(receiverUid, type, receiverType)`. Covers UIKitSettings calling configuration, surface-aware Compose+Views routing, foreground service correctness on Android 14+, ConnectionService + FCM VoIP push.
+description: "CometChat Calls v6 integration for native Android (V6 stable, GA 2026-05-25 — Compose + Kotlin Views). Works end-to-end on chatuikit-compose-android:6.0.0 (validated 2026-05-12 against web peer) — but only with FIVE non-obvious workarounds the kit itself doesn't ship — (1) explicit calls-sdk-android:5.0.+ peer dep, (2) annotations-java5 exclude, (3) stub classes for legacy com.cometchat.calls.{CometChatRTCView, model.RTCUser, model.RTCReceiver, model.RTCCallback} to satisfy chat-sdk's CallManager bytecode, (4) AVOID CometChatCallButtons (broken — captures first-rendered user globally; ignores per-row prop) — instead wire your own button to CometChat.initiateCall then CometChatCallActivity.Companion.launchOutgoingCallScreen(context, call, null), (5) Call constructor arg order CHANGED in chat-sdk 5.x — (receiverUid, receiverType, type) not (receiverUid, type, receiverType). Covers UIKitSettings calling configuration, surface-aware Compose+Views routing, foreground service correctness on Android 14+, ConnectionService + FCM VoIP push."
 license: "MIT"
 compatibility: "Android Studio Hedgehog+, JDK 17, Gradle 8+, AGP 8+, minSdk 28+ (V6 raised the floor); chatuikit-compose-android:6.0.+ OR chatuikit-kotlin-android:6.0.+ PAIRED with com.cometchat:calls-sdk-android:5.0.+ (peer dep required despite the V6 marketing — see §1.0)"
-allowed-tools: "shell, file-read, file-search, file-list, ask-user"
 metadata:
   author: "CometChat"
   version: "4.0.0"
-  tags: "cometchat android v6 calls voice video webrtc compose kotlin-views uikitsettings calling-configuration foreground-service voip fcm connectionservice beta"
+  tags: "cometchat android v6 calls voice video webrtc compose kotlin-views uikitsettings calling-configuration foreground-service voip fcm connectionservice ga"
 ---
 
+> **Ground truth:** `com.cometchat:chatuikit-{compose,kotlin}-android:6.x` (+ `calls-sdk-android:5.x`) — resolved AAR (javap) + `ui-kit/android/v6`. **Official docs:** https://www.cometchat.com/docs/calls/android/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.
+
 ## ⚠️ Five required workarounds for chatuikit-compose-android:6.0.0
 
-Validated end-to-end on Pixel 3 (Android 12) ↔ Next.js peer on 2026-05-12. **All five must be applied** — the V6 beta artifacts ship without them and the app crashes on first call attempt without one of them in place.
+Validated end-to-end on Pixel 3 (Android 12) ↔ Next.js peer on 2026-05-12. **All five must be applied** — the V6 calls artifacts ship without them and the app crashes on first call attempt without one of them in place. (V6 is GA since 2026-05-25; GA software can still need these workarounds — they were validated against the 6.0.0 line and are not yet confirmed removed on later patches.)
 
 ### W1 — `calls-sdk-android:5.0.+` is a REQUIRED peer dep
 
@@ -109,7 +110,7 @@ Bytecode-confirmed against chat-sdk-android:5.0.1: `arg1 → receiverUid`, `arg2
 
 ## Purpose
 
-Production-grade voice + video calling for native Android v6 (beta). Loaded by `cometchat-calls` when `android_version === "v6"`. Routes to the **Compose** or **Kotlin Views** sub-flow based on the surface the project uses (already determined by `cometchat-android-v6-core` from the presence of `androidx.compose.ui:ui` / `compose.material3` in the dependency graph).
+Production-grade voice + video calling for native Android v6 (stable, GA 2026-05-25). Loaded by `cometchat-calls` when `android_version === "v6"`. Routes to the **Compose** or **Kotlin Views** sub-flow based on the surface the project uses (already determined by `cometchat-android-v6-core` from the presence of `androidx.compose.ui:ui` / `compose.material3` in the dependency graph).
 
 **⚠️ Important — V6 still needs `calls-sdk-android` on the classpath despite marketing claims.** The V6 chatuikit packages advertise "bundled calling," but at runtime `CometChatUIKit.init` references `com.cometchat.calls.core.CometChatCalls$SessionSettingsBuilder` — a class that lives in `com.cometchat:calls-sdk-android`, NOT in the chatuikit AAR. Without the peer dep, the app crashes on `Application.onCreate` with `ClassNotFoundException`. Always add:
 
@@ -129,19 +130,76 @@ The `UIKitSettings` builder must still call `.setEnableCalling(true)` to registe
 - `cometchat-android-v6-{compose,kotlin}-components` — surface-specific component catalogs
 
 **Ground truth:**
-- SDK source — installed `chatuikit-{compose,kotlin}-android@6.0.0-beta2` artifacts under `~/.gradle/caches/`
+- SDK source — installed `chatuikit-{compose,kotlin}-android@6.0.+` (GA) artifacts under `~/.gradle/caches/`
 - V5 sibling skill — `cometchat-android-v5-calls` (different module shape, same hard rules)
 - Public docs — https://www.cometchat.com/docs/calls/android/overview (note: V6 docs may still reference V5 module split)
 
+## When to use
+
+- Android V6 project (`chatuikit-compose-android:6.x` OR `chatuikit-kotlin-android:6.x` detected by `cometchat-android-v6-core`)
+- The integration needs voice / video calling (ringing OR session OR additive on top of chat)
+- The project is on `minSdk = 28` or higher (V6 floor)
+
+## When NOT to use
+
+- **Standalone session-mode meeting-room flow (no ringing, no chat UI Kit)** — load `cometchat-android-v6-calls` §4a only; W1–W5 do NOT apply. The chatuikit AAR is never loaded in this path, so the broken-CometChatCallButtons bug + the classloader stub issue never trigger.
+- **`minSdk < 28`** — V6 is unsupported. Route back to `cometchat-android-v5-calls` (V5 supports minSdk 21+).
+- **V5 chatuikit already in project** (`chat-uikit-android:5.x`) — do NOT introduce V6 calls alongside V5 chat; use `cometchat-android-v5-calls`. The two namespaces collide on `com.cometchat.chat.core.Call` resolution.
+- **Mixed Compose + Kotlin Views surface in the same Activity** — pick one surface before continuing. Importing both `com.cometchat.uikit.compose.*` and `com.cometchat.uikit.kotlin.*` in the same call screen will compile but ship inconsistent UX. Confirm via `cometchat-android-v6-core` Step 1 surface-detection output.
+- **iOS** — load `cometchat-ios-calls`.
+- **Cross-platform mobile** (Flutter / React Native) — load `cometchat-flutter-v6-calls` or `cometchat-native-calls`.
+
+## Common Rationalizations — and why they're wrong (HIGH-RISK: W1–W5 contradict vendor marketing)
+
+W1–W5 directly contradict the published V6 release notes and the most discoverable kit API (`CometChatCallButtons`). An agent reading newer-sounding vendor docs mid-task will silently drop a workaround. Pre-rebut every excuse the agent might invent.
+
+| Excuse the agent might invent | Reality |
+|---|---|
+| "V6 release notes say calling is bundled, so `calls-sdk-android:5.0.+` must be redundant" | **FALSE.** The chatuikit-compose AAR references `CometChatCalls$SessionSettingsBuilder` at bytecode level but doesn't ship it. Without the peer dep, the app crashes on `Application.onCreate` with `ClassNotFoundException`. Verify with `./gradlew :app:dependencies \| grep calls-sdk`. See W1. |
+| "`CometChatCallButtons` is the documented composable, so W4's hand-wired button must be a workaround for an older version" | **FALSE.** Validated broken on `chatuikit-compose-android:6.0.0` on 2026-05-12 — the per-row `user` prop is captured-by-first-composition (ENG-35711). Re-test only after a confirmed 6.0.1+ release-notes entry that explicitly fixes per-row state. Until then: hand-wire your own button to `CometChat.initiateCall` then `CometChatCallActivity.Companion.launchOutgoingCallScreen`. See W4. |
+| "I'll skip the `annotations-java5` exclude — build works locally" | **FALSE in CI.** The duplicate-class error only fires on clean builds; incremental local builds mask it. ENG-35701 — testers shipped to CI and the build failed there. The exclude is one line; the cost of skipping is a CI red. See W2. |
+| "Stub classes are old V4 cruft — V5 calls-sdk doesn't need `com.cometchat.calls.{CometChatRTCView,model.RTCUser,...}`" | **FALSE.** The chat-sdk's `CallManager` references those legacy classes at bytecode level. Without the four no-op stubs, `Application.onCreate` throws `NoClassDefFoundError` even though you never call them. See W3 stubs — copy verbatim. |
+| "I'll add `FOREGROUND_SERVICE_PHONE_CALL` permissions later — calling works without them in dev" | **FALSE on Android 14+.** Calls work in dev because the test device hasn't enforced the new permission model yet (or has the dev override). Production / Play Store devices on API 34+ silently kill the foreground service the second the user backgrounds the app. The four FOREGROUND_SERVICE_* permissions go in the manifest from day one. |
+| "The `Call(uid, type, receiverType)` constructor is what the docs show, so I'll use that arg order" | **FALSE in chat-sdk 5.x.** Bytecode-confirmed against chat-sdk-android:5.0.1: the arg order is `Call(receiverUid, receiverType, callType)` — receiverType comes BEFORE callType, opposite of v4. Skipping yields server `ERR_BAD_REQUEST: Failed to validate the data sent with the request`. See W5. |
+| "I'll use `CometChatCalls.endSession(callback)` to clean up — most APIs take a callback" | **FALSE.** `endSession()` is void/no-callback (ENG-35698). The v5 canonical teardown is `CallSession.getInstance().leaveSession()`. Passing a callback compiles in some versions but is silently ignored. |
+
+## Red Flags — symptom → cause lookup
+
+When debugging an Android V6 calls integration, match the symptom to the workaround you skipped:
+
+| Symptom (in logcat or build output) | You skipped... |
+|---|---|
+| `java.lang.ClassNotFoundException: com.cometchat.calls.core.CometChatCalls$SessionSettingsBuilder` on app launch | **W1** — calls-sdk-android peer dep is missing. Add `implementation("com.cometchat:calls-sdk-android:5.0.+")`. |
+| `Duplicate class org.jetbrains.annotations.NotNull` / `ApiStatus` / `ScheduledForRemoval` on clean build | **W2** — annotations-java5 exclude. Add `configurations.all { exclude(group = "org.jetbrains", module = "annotations-java5") }` to `app/build.gradle.kts`. |
+| `java.lang.NoClassDefFoundError: com.cometchat.calls.CometChatRTCView` (or `RTCUser` / `RTCReceiver` / `RTCCallback`) on `Application.onCreate` | **W3** — the four legacy no-op stub classes. Copy verbatim from the §"Five required workarounds" W3 block. |
+| Every call-button row dials the same person regardless of which row was tapped | **W4** — you used `CometChatCallButtons` instead of hand-wiring. The per-row `user` prop is captured-by-first-composition. Switch to manual `CometChat.initiateCall` + `CometChatCallActivity.Companion.launchOutgoingCallScreen`. |
+| Server returns `ERR_BAD_REQUEST: Failed to validate the data sent with the request` on `initiateCall` | **W5** — `Call()` constructor arg order is v4-style. Switch to `Call(receiverUid, receiverType, callType)`. |
+| Foreground service silently dies when user backgrounds the app on Android 14+ | The four `FOREGROUND_SERVICE_*` permissions are missing from `AndroidManifest.xml`. Add `FOREGROUND_SERVICE`, `FOREGROUND_SERVICE_PHONE_CALL`, `FOREGROUND_SERVICE_MICROPHONE`, `FOREGROUND_SERVICE_CAMERA`. |
+| Outgoing call rings on the peer but never joins after accept | The accept→join handoff isn't wired. The `onIncomingCallReceived` listener must call `CometChat.acceptCall` THEN `CometChatCalls.joinSession` — and the receiver app needs the same workaround chain (W1–W5) to play back. |
+| `endSession()` takes 0 args error | You passed a callback. v5 `CometChatCalls.endSession()` is void. For teardown with state, use `CallSession.getInstance().leaveSession()`. |
+
+## Verification — before declaring this skill applied
+
+- [ ] `grep -nE "implementation.*calls-sdk-android" app/build.gradle.kts` returns ≥ 1 match (W1).
+- [ ] `grep -nE 'exclude.*annotations-java5' app/build.gradle.kts` returns ≥ 1 match (W2).
+- [ ] `grep -rnE "class (CometChatRTCView|RTCUser|RTCReceiver|RTCCallback)" app/src/main/java/com/cometchat/calls/` returns 4 matches — the W3 stub classes are in place.
+- [ ] **`grep -rnE "CometChatCallButtons\(" app/src/` returns ZERO matches** (W4 — the per-row global-state bug). If any matches exist, the agent regressed to vendor marketing.
+- [ ] `grep -nE "Call\((\w+),\s*CometChatConstants.RECEIVER_TYPE_" app/src/` confirms `RECEIVER_TYPE_` is the SECOND arg (W5 — receiverType before callType).
+- [ ] `AndroidManifest.xml` declares all four `FOREGROUND_SERVICE_*` permissions.
+- [ ] App runs `./gradlew :app:assembleDebug` cleanly — no duplicate-class, no ClassNotFoundException, no compile errors.
+- [ ] Pairwise test (caller + receiver, two devices or sim+device) confirms: outgoing call rings, accept→join handoff completes, both sides see WebRTC frames.
+
 ---
 
 ## 1. The seven hard rules — Android v6 specialization
 
 The same seven non-negotiables from the dispatcher; v6 changes the *how* but not the *what*.
 
-### 1.0 Calls SDK login is its own step (v5+)
+### 1.0 Calls SDK login — only the STANDALONE/raw-SDK path needs it
+
+> ✅ **The additive UI-Kit path does NOT call `CometChatCalls.login`.** When you use the V6 UI Kit (the common case — `CometChatIncomingCall` + the auto call buttons in `CometChatMessageHeader`, with `.setEnableCalling(true)`), the kit registers the calling extension at init and chains the Calls-SDK auth off `CometChatUIKit.login` for you. **Both canonical Android v6 sample apps wire calls end-to-end with ZERO `CometChatCalls.login`** (verified: no `CometChatCalls.login` in `sample-app-kotlin`/`sample-app-compose`). Adding it yourself on the UI-Kit path is redundant. (Matches the standing finding: UI Kit login chains Calls-SDK login; the explicit step only fires on raw-SDK paths.)
 
-Same as v5 cohort — the v5 Calls SDK has its own auth state, separate from the Chat SDK. After `CometChat.login(uid, AUTH_KEY)` succeeds, you MUST also call `CometChatCalls.login(uid, AUTH_KEY, ...)` — without it, the FIRST calls API call throws **"auth token cannot be null"**.
+**`CometChatCalls.login(uid, AUTH_KEY, ...)` is required ONLY on the STANDALONE / raw-Calls-SDK path** — when you call `CometChatCalls.generateToken` / `startSession` directly without the UI Kit's calling components. There, the Calls SDK has its own auth state separate from the Chat SDK: after `CometChat.login(uid, AUTH_KEY)` succeeds, also call `CometChatCalls.login(uid, AUTH_KEY, ...)` — without it the first raw calls API call throws **"auth token cannot be null"**.
 
 ```kotlin
 import com.cometchat.calls.core.CometChatCalls
@@ -249,7 +307,7 @@ class MainActivity : ComponentActivity() {
 }
 ```
 
-In Kotlin Views, the equivalent is a top-level `FrameLayout` in the Activity's layout XML containing both the host `<fragment>` and `<com.cometchat.chatuikit.calling.CometChatIncomingCall>`.
+In Kotlin Views, the equivalent is a top-level `FrameLayout` in the Activity's layout XML containing both the host `<fragment>` and `<com.cometchat.uikit.kotlin.presentation.incomingcall.CometChatIncomingCall>`.
 
 ---
 
@@ -259,12 +317,12 @@ V6 has no separate calls module. If `chatuikit-{compose,kotlin}-android` is alre
 
 1. Adds calling configuration to `UIKitSettings`:
    ```kotlin
-   val settings = UIKitSettings.Builder()
+   val settings = UIKitSettings.UIKitSettingsBuilder()
      .setAppId(BuildConfig.COMETCHAT_APP_ID)
      .setRegion(BuildConfig.COMETCHAT_REGION)
      .setAuthKey(BuildConfig.COMETCHAT_AUTH_KEY)
      .subscribePresenceForAllUsers()
-     .enableCalling()                              // ← v6 flips calling on here
+     .setEnableCalling(true)                       // ← v6 flips calling on here (real method: setEnableCalling)
      .build()
    ```
 2. Ensures the four FOREGROUND_SERVICE permissions and the four call permissions are in `AndroidManifest.xml`.
@@ -278,7 +336,9 @@ Detailed V6 init order: `cometchat-android-v6-core`. UIKitSettings option-by-opt
 
 Both surfaces ship the same five call components with the same parameter names. Surface determines which import you use.
 
-### Compose (`com.cometchat.chatuikit.calling.compose.*`)
+### Compose (`com.cometchat.uikit.compose.presentation.<component>.ui.*`)
+
+> Real namespace is `com.cometchat.uikit.compose.presentation.{incomingcall,callbuttons,ongoingcall,outgoingcall,calllogs}.ui.*` (NOT `com.cometchat.chatuikit.calling.*` — that package does not exist). Use the exact per-component import from `cometchat-android-v6-compose-components`.
 
 | Composable | Purpose |
 |---|---|
@@ -288,12 +348,12 @@ Both surfaces ship the same five call components with the same parameter names.
 | `CometChatOngoingCall(callSettingsBuilder, sessionId)` | WebRTC view — handles camera/mic/end controls |
 | `CometChatCallLogs(onItemClick)` | Paginated history; integrates with Compose Navigation |
 
-### Kotlin Views (`com.cometchat.chatuikit.calling.views.*`)
+### Kotlin Views (`com.cometchat.uikit.kotlin.presentation.<component>.*`)
 
-Same names, different package. Inflate via XML or programmatically:
+Same names, different package — real namespace `com.cometchat.uikit.kotlin.presentation.{incomingcall,callbuttons,ongoingcall.ui,outgoingcall,calllogs}.*` (NOT `com.cometchat.chatuikit.calling.*`). Use the exact per-component import from `cometchat-android-v6-kotlin-components`. Inflate via XML or programmatically:
 
 ```xml
-<com.cometchat.chatuikit.calling.views.CometChatCallButtons
+<com.cometchat.uikit.kotlin.presentation.callbuttons.CometChatCallButtons
     android:id="@+id/callButtons"
     android:layout_width="wrap_content"
     android:layout_height="wrap_content" />
@@ -337,7 +397,7 @@ Dual-SDK + telecom + push + V6 chatuikit:
 
 When chat is already integrated via V6. The skill:
 
-- Adds `.enableCalling()` to the existing `UIKitSettings.Builder()` chain.
+- Adds `.setEnableCalling(true)` to the existing `UIKitSettings.UIKitSettingsBuilder()` chain.
 - Adds the four `FOREGROUND_SERVICE_*` permissions to manifest.
 - Mounts `CometChatIncomingCall` at the root of the existing Activity (Compose: in `setContent`; Views: in the root layout XML).
 - Wires call buttons inline — `CometChatMessageHeader` (V6) already renders them; the kit calls `initiateCall` automatically when calling is enabled.
@@ -345,7 +405,7 @@ When chat is already integrated via V6. The skill:
 
 ## 6. Anti-patterns
 
-1. **Treating V6 calls as a separate module.** No `com.cometchat:calls-sdk-android` dependency on V6 — adding it pulls a V5 module that conflicts at runtime. The setup is just `.enableCalling()`.
+1. **Omitting the `calls-sdk-android:5.0.+` peer dep because "V6 folds calls in."** This is the OPPOSITE of the truth — see **W1**. Despite the V6 marketing, `chatuikit-{compose,kotlin}-android:6.0.0` bytecode-references `CometChatCalls.SessionSettingsBuilder`, which ships ONLY in `com.cometchat:calls-sdk-android:5.0.+`. Without that explicit dependency the app crashes at runtime (`NoClassDefFoundError`). `.setEnableCalling(true)` alone is NOT enough. (What you must NOT add is the separate V5 *calls UI Kit* — that's the module that conflicts; the bare `calls-sdk-android` peer dep is required.)
 2. **Mounting `CometChatIncomingCall` inside the navigation graph.** Disappears on navigation events. Mount at root (rule 1.7).
 3. **Activity theme not inheriting `CometChatTheme.DayNight` for V6 Kotlin Views.** Calls components extend `MaterialCardView` and crash with `Failed to resolve attribute at index N` if hosted in `Theme.AppCompat.*`. Compose surfaces are not affected. Already documented in `cometchat-android-v6-troubleshooting`; surfaced here because calls components are the canary that exposes the bug.
 4. **Skipping the four `FOREGROUND_SERVICE_*` permissions** because the kit "already" registers the service. Manifest merge does not pull permissions — your app must declare them.
@@ -354,7 +414,7 @@ When chat is already integrated via V6. The skill:
 ## 7. Verification checklist
 
 - [ ] `chatuikit-compose-android` OR `chatuikit-kotlin-android` (NOT both) in `app/build.gradle.kts` — V6 picks one surface
-- [ ] `.enableCalling()` on `UIKitSettings.Builder()`
+- [ ] `.setEnableCalling(true)` on `UIKitSettings.UIKitSettingsBuilder()`
 - [ ] Activity theme is `CometChatTheme.DayNight` (Kotlin Views only)
 - [ ] All four `FOREGROUND_SERVICE_*` permissions in `AndroidManifest.xml`
 - [ ] All four call permissions (RECORD_AUDIO / CAMERA / POST_NOTIFICATIONS / MANAGE_OWN_CALLS)
@@ -368,6 +428,7 @@ When chat is already integrated via V6. The skill:
 
 ## 8. Pointers
 
+- `references/advanced-features.md` — Recording, Picture-in-Picture, Screen-share (receive) — source-verified against `calls-sdk-android` 5.x
 - `cometchat-android-v5-calls/references/` — VoIP push, foreground service, ConnectionService, FCM payload shape — all unchanged on V6
 - `cometchat-android-v6-builder-settings` — every UIKitSettings option including calling block details
 - `cometchat-android-v6-{compose,kotlin}-components` — full surface-specific component catalogs

package/skills/cometchat-android-v6-calls/references/advanced-features.md

@@ -0,0 +1,87 @@
+# Android V6 — advanced in-call features (Recording, PiP, Screen-share)
+
+These use the same `calls-sdk-android:5.x` the rest of V6 calls relies on (the W1 peer dep). Every symbol below is verified against the decompiled `calls-sdk-android` 5.x API. Works in both the Compose and Kotlin-Views surfaces — drive UI state from a ViewModel; the SDK calls are surface-agnostic.
+
+**Session handle:** `CallSession.getInstance()` returns the active `CallSession` singleton. Several controls also have static convenience methods directly on `CometChatCalls`.
+
+---
+
+## 1. Recording
+
+Server-gated — recording must be enabled for the app in the CometChat dashboard first; otherwise the calls below no-op.
+
+```kotlin
+// Start / stop on demand (static convenience)
+CometChatCalls.startRecording()
+CometChatCalls.stopRecording()
+
+// …or on the active session
+CallSession.getInstance().startRecording()
+CallSession.getInstance().stopRecording()
+```
+
+**Auto-start + hide the default button** at session config time (both builders expose these):
+
+```kotlin
+val sessionSettings = CometChatCalls.SessionSettingsBuilder(activity)  // or no-arg SessionSettingsBuilder()
+    .enableAutoStartRecording(true)   // begin recording when the call connects
+    .hideRecordingButton(false)        // keep the kit's built-in record toggle (default UI)
+    .build()
+```
+
+**React to recording state** via `MediaEventsListener` (registered the same way as the other call event listeners in this skill):
+
+```kotlin
+object : MediaEventsListener() {
+    override fun onRecordingStarted() { /* show REC indicator */ }
+    override fun onRecordingStopped() { /* hide REC indicator */ }
+}
+```
+
+Verified: `CometChatCalls.startRecording()/stopRecording()` (static + `CallSession` instance), `SessionSettingsBuilder.enableAutoStartRecording(boolean)` + `hideRecordingButton(boolean)` (NOTE: `CallSettingsBuilder` is the deprecated v4 name, replaced by `SessionSettingsBuilder` in calls-sdk v5 — it no longer exists on android-v6), `MediaEventsListener.onRecordingStarted()/onRecordingStopped()`.
+
+---
+
+## 2. Picture-in-Picture
+
+Two distinct things — don't confuse them:
+
+- **In-call compact layout** (the SDK shrinks the call grid to a floating tile *inside your app*): `CallSession.enablePictureInPictureLayout()` / `disablePictureInPictureLayout()`.
+- **System PiP** (the OS floats the call over other apps when the user leaves): static `CometChatCalls.enterPIPMode()` / `exitPIPMode()`. For OS-level PiP you must also declare the Activity `android:supportsPictureInPicture="true"` in the manifest and call `enterPIPMode()` from `onUserLeaveHint()`.
+
+```kotlin
+// in-call compact layout
+CallSession.getInstance().enablePictureInPictureLayout()
+CallSession.getInstance().disablePictureInPictureLayout()
+
+// system PiP (manifest: android:supportsPictureInPicture="true")
+override fun onUserLeaveHint() {
+    super.onUserLeaveHint()
+    CometChatCalls.enterPIPMode()
+}
+```
+
+Verified: `CallSession.enablePictureInPictureLayout()/disablePictureInPictureLayout()`, static `CometChatCalls.enterPIPMode()/exitPIPMode()`.
+
+---
+
+## 3. Screen sharing — receive only
+
+**Android cannot locally INITIATE screen share** (that's a web-only capability). It *renders a remote participant's* shared screen automatically inside the call grid. You only wire a listener to react to it (e.g. switch to spotlight layout, show a banner):
+
+```kotlin
+object : ParticipantEventListener() {
+    override fun onParticipantStartedScreenShare(participant: Participant) {
+        // optional: CallSession.getInstance().setLayout(LayoutType.SPOTLIGHT)
+    }
+    override fun onParticipantStoppedScreenShare(participant: Participant) { }
+}
+```
+
+Verified: `ParticipantEventListener.onParticipantStartedScreenShare(Participant)/onParticipantStoppedScreenShare(Participant)`. There is NO local `startScreenShare` symbol in `calls-sdk-android` 5.x — do not author one.
+
+---
+
+## Audio modes (cross-reference)
+
+Speaker / earpiece / Bluetooth routing is already covered in `references/device-management.md` (`setAudioMode(AudioMode.SPEAKER/EARPIECE/BLUETOOTH/HEADPHONES)` + `MediaEventsListener.onAudioModeChanged`). Virtual Background is **not supported** by `calls-sdk-android` 5.x (no symbol) — it is a web / React Native / Flutter capability only; do not author it for Android.

package/skills/cometchat-android-v6-calls/references/call-layouts.md

@@ -9,27 +9,36 @@ Same SDK API as V5; V6 adds Compose-native `SegmentedButton` for the switcher.
 
 ## ViewModel
 
+Layout is the `LayoutType` enum (`TILE` / `SIDEBAR` / `SPOTLIGHT`) — there is no `CometChatCallsConstants.LAYOUT_*` and `setLayout` is an instance method on the `CallSession` singleton (not a static on `CometChatCalls`).
+
 ```kotlin
+import com.cometchat.calls.core.CallSession
+import com.cometchat.calls.listeners.LayoutListener
+import com.cometchat.calls.model.LayoutType
+
 class CallLayoutViewModel : ViewModel() {
-  private val _layout = MutableStateFlow(CometChatCallsConstants.LAYOUT_TILE)
-  val layout: StateFlow<String> = _layout
+  private val _layout = MutableStateFlow(LayoutType.TILE)
+  val layout: StateFlow<LayoutType> = _layout
 
-  fun set(next: String) {
-    CometChatCalls.setLayout(next)
+  fun set(next: LayoutType) {
+    CallSession.getInstance().setLayout(next)
     _layout.value = next
   }
 
-  fun onSDKChanged(next: String) {
+  fun onSDKChanged(next: LayoutType) {
     _layout.value = next  // already updated by kit's switcher
   }
 }
 
-// Wire from CometChatCallsEventsListener:
-override fun onCallLayoutChanged(layout: String) {
-  Handler(Looper.getMainLooper()).post {
-    callLayoutViewModel.onSDKChanged(layout)
+// Register a LayoutListener via CallSession.addLayoutListener(lifecycleOwner, ...).
+// onCallLayoutChanged is a LayoutListener member (NOT a CometChatCallsEventsListener one).
+CallSession.getInstance().addLayoutListener(lifecycleOwner, object : LayoutListener() {
+  override fun onCallLayoutChanged(layout: LayoutType) {
+    Handler(Looper.getMainLooper()).post {
+      callLayoutViewModel.onSDKChanged(layout)
+    }
   }
-}
+})
 ```
 
 ---
@@ -43,9 +52,9 @@ fun LayoutSwitcher(viewModel: CallLayoutViewModel = viewModel()) {
   val layout by viewModel.layout.collectAsStateWithLifecycle()
 
   val options = listOf(
-    CometChatCallsConstants.LAYOUT_TILE to "Tile",
-    CometChatCallsConstants.LAYOUT_SIDEBAR to "Sidebar",
-    CometChatCallsConstants.LAYOUT_SPOTLIGHT to "Spotlight",
+    LayoutType.TILE to "Tile",
+    LayoutType.SIDEBAR to "Sidebar",
+    LayoutType.SPOTLIGHT to "Spotlight",
   )
 
   SingleChoiceSegmentedButtonRow {
@@ -76,10 +85,10 @@ V5 sister rules apply, plus Compose-specific:
 
 ## Verification checklist
 
-- [ ] `CallLayoutViewModel` exposes `StateFlow<String>`
+- [ ] `CallLayoutViewModel` exposes `StateFlow<LayoutType>`
 - [ ] `SingleChoiceSegmentedButtonRow` wraps the layout options
 - [ ] `collectAsStateWithLifecycle` (not `collectAsState`)
-- [ ] `onCallLayoutChanged` syncs the ViewModel on main thread
+- [ ] `LayoutListener.onCallLayoutChanged` (registered via `addLayoutListener`) syncs the ViewModel on main thread
 - [ ] Real-device smoke: cycles all 3, survives rotation
 
 ---

package/skills/cometchat-android-v6-calls/references/call-session.md

@@ -6,7 +6,7 @@ V6 uses the same SDK (`com.cometchat.calls-sdk-android`) as V5. The canonical SD
 - `cometchat-android-v5-calls/references/call-session.md` — canonical SDK API (single-call `joinSession`, `SessionSettingsBuilder`, `SessionStatusListener`, `CometChatOngoingCallService`)
 - `cometchat-react-calls/references/call-session.md` — cross-platform architecture
 
-**Source of truth:** `~/Downloads/calls-sdk/calls-sdk-android-5/samples/sample-app/src/main/kotlin/com/cometchat/samplecalls/ui/activity/CallActivity.kt` (no Compose-specific upstream sample exists; the SDK surface is identical).
+**Source of truth:** `calls-sdk-android-5/samples/sample-app/src/main/kotlin/com/cometchat/samplecalls/ui/activity/CallActivity.kt` (no Compose-specific upstream sample exists; the SDK surface is identical).
 
 ---
 
@@ -159,5 +159,5 @@ V5 checklist applies, plus Compose-specific:
 - `cometchat-android-v5-calls/references/call-session.md` — canonical SDK API + Views patterns
 - `cometchat-android-v6-calls/SKILL.md` — V6 Compose architecture (W1–W5 workarounds for the kit)
 - `cometchat-android-v6-calls/references/share-invite.md` — App Links config
-- Upstream Android sample — `~/Downloads/calls-sdk/calls-sdk-android-5/samples/sample-app/src/main/kotlin/com/cometchat/samplecalls/ui/activity/CallActivity.kt`
+- Upstream Android sample — `calls-sdk-android-5/samples/sample-app/src/main/kotlin/com/cometchat/samplecalls/ui/activity/CallActivity.kt`
 - Canonical docs: https://www.cometchat.com/docs/calls/android/join-session

package/skills/cometchat-android-v6-calls/references/device-management.md

@@ -74,7 +74,7 @@ class CallControlsViewModel : ViewModel() {
   fun toggleMic() {
     val callSession = CallSession.getInstance()
     if (_state.value.micMuted) {
-      callSession.unMuteAudio()
+      callSession.unmuteAudio()
     } else {
       callSession.muteAudio()
     }
@@ -92,13 +92,10 @@ class CallControlsViewModel : ViewModel() {
   }
 
   fun flipCamera() {
-    val callSession = CallSession.getInstance()
-    val newFacing = if (callSession.currentCameraFacing == CameraFacing.FRONT) {
-      CameraFacing.BACK
-    } else {
-      CameraFacing.FRONT
-    }
-    callSession.switchCamera(newFacing)
+    // switchCamera() takes NO argument — it toggles front/rear internally.
+    // (The enum, when you need it, is CameraFacing.{FRONT,REAR} — there is no BACK,
+    //  and CallSession has no currentCameraFacing getter.)
+    CallSession.getInstance().switchCamera()
   }
 
   fun toggleSpeaker() {
@@ -121,23 +118,27 @@ class CallControlsViewModel : ViewModel() {
 V6 still uses the V5 SDK's `MediaEventsListener` for audio mode change detection:
 
 ```kotlin
-class CallControlsViewModel : ViewModel(), MediaEventsListener {
+class CallControlsViewModel(
+  lifecycleOwner: LifecycleOwner,
+) : ViewModel(), MediaEventsListener {
   init {
-    CallSession.getInstance().addMediaEventsListener("controls", this)
+    // addMediaEventsListener takes (LifecycleOwner, MediaEventsListener) — there is no String-keyed overload.
+    CallSession.getInstance().addMediaEventsListener(lifecycleOwner, this)
   }
 
-  override fun onAudioModeUpdated(mode: AudioMode) {
+  override fun onAudioModeChanged(mode: AudioMode) {
     _state.update { it.copy(audioMode = mode) }
   }
 
   override fun onCleared() {
-    CallSession.getInstance().removeMediaEventsListener("controls")
+    // There is no removeMediaEventsListener — clear all listeners on teardown.
+    CallSession.getInstance().clearAllListeners()
   }
   // ... other MediaEventsListener methods
 }
 ```
 
-When the user connects Bluetooth headphones mid-call, `onAudioModeUpdated(BLUETOOTH)` fires. Update the UI button accordingly.
+When the user connects Bluetooth headphones mid-call, `onAudioModeChanged(BLUETOOTH)` fires. Update the UI button accordingly. (Lifecycle-scoped registration auto-removes when the owner is destroyed; `clearAllListeners()` is the explicit teardown.)
 
 ---
 
@@ -147,7 +148,7 @@ V5 audio-controls + video-controls references list the SDK-level anti-patterns;
 
 1. **`Icons.Filled.MicOff` without `tint`.** Default tint is theme-dependent; on dark call surfaces, the icon may be invisible.
 2. **`collectAsState()` instead of `collectAsStateWithLifecycle()`.** State updates run while paused; CPU waste.
-3. **Camera flip without checking current facing.** SDK's `switchCamera()` (no arg) toggles, but `switchCamera(CameraFacing)` requires explicit value. Use the explicit-arg form for clarity.
+3. **Calling `switchCamera(CameraFacing)` with an argument.** No such overload exists — `switchCamera()` takes no arg and toggles front/rear internally. There is also no `currentCameraFacing` getter, and the enum is `CameraFacing.{FRONT,REAR}` (no `BACK`).
 
 ---
 
@@ -155,8 +156,8 @@ V5 audio-controls + video-controls references list the SDK-level anti-patterns;
 
 - [ ] ViewModel uses `StateFlow` + `collectAsStateWithLifecycle()`
 - [ ] All toggle buttons have `contentDescription` (a11y)
-- [ ] `MediaEventsListener` registered with stable ID
-- [ ] Listener cleaned up in `onCleared()`
+- [ ] `MediaEventsListener` registered via `addMediaEventsListener(lifecycleOwner, this)`
+- [ ] Listeners cleared in `onCleared()` via `clearAllListeners()`
 - [ ] Real-device smoke: mute / camera / flip / speaker all work
 - [ ] Bluetooth smoke: connect headphones → audio mode icon updates
 

package/skills/cometchat-android-v6-calls/references/idle-timeout.md

@@ -9,14 +9,17 @@ Same SDK API as V5. V6-specific: Compose `AlertDialog` for new code, ViewModel +
 
 ## SDK API (same as V5)
 
+There is a single `setIdleTimeoutPeriod(int)` — there is no separate before/after-prompt pair. `SessionSettingsBuilder` has only `()` and `(Activity)` constructors (no `(context, container)` form).
+
 ```kotlin
-val settings = SessionSettingsBuilder(context, callContainer)
+val settings = SessionSettingsBuilder(activity)  // or no-arg SessionSettingsBuilder()
   .setSessionType(SessionType.VIDEO)
-  .setIdleTimeoutPeriodBeforePrompt(60_000)
-  .setIdleTimeoutPeriodAfterPrompt(120_000)
+  .setIdleTimeoutPeriod(60)   // SECONDS (= 60s); default 300
   .build()
 ```
 
+> **⚠ Unit footgun — Android takes SECONDS, not milliseconds.** `setIdleTimeoutPeriod(int)` is in **seconds** (default `300` = 5 min; docs: calls/android/idle-timeout). The **web / React Native / Angular** Calls SDK uses **milliseconds** for `SessionSettings.idleTimeoutPeriodBeforePrompt/AfterPrompt` — copying a web value like `60000` here is a ~16.7-hour timeout, not 60 seconds. Use `60` for one minute.
+
 ---
 
 ## Compose prompt
@@ -91,7 +94,7 @@ V5 sister rules apply, plus V6-specific:
 
 ## Verification checklist
 
-- [ ] SessionSettingsBuilder sets both idle periods
+- [ ] SessionSettingsBuilder sets `setIdleTimeoutPeriod(int)`
 - [ ] Compose AlertDialog `onDismissRequest = { }` (empty)
 - [ ] `collectAsStateWithLifecycle()` for state binding
 - [ ] LaunchedEffect on specific field, not whole state

package/skills/cometchat-android-v6-calls/references/in-call-chat.md

@@ -73,12 +73,12 @@ class InCallChatViewModel : ViewModel(), MessageListener {
     if (message.receiverType != CometChatConstants.RECEIVER_TYPE_GROUP) return
     if (message.receiverUid != _state.value.group?.guid) return
     _state.update { it.copy(unread = it.unread + 1) }
-    CometChatCalls.setChatButtonUnreadCount(_state.value.unread)
+    CallSession.getInstance().setChatButtonUnreadCount(_state.value.unread)
   }
 
   fun open() {
     _state.update { it.copy(open = true, unread = 0) }
-    CometChatCalls.setChatButtonUnreadCount(0)
+    CallSession.getInstance().setChatButtonUnreadCount(0)
   }
 
   fun close() {
@@ -95,15 +95,20 @@ class InCallChatViewModel : ViewModel(), MessageListener {
 
 ## Triggering from SDK event
 
-In your `CometChatCallsEventsListener` impl:
+`onChatButtonClicked()` is a `ButtonClickListener` member (NOT on `CometChatCallsEventsListener`). Register it via `CallSession.addButtonClickListener(lifecycleOwner, ...)`:
 
 ```kotlin
-override fun onChatButtonClicked() {
-  // Listener is on background thread — dispatch to UI
-  Handler(Looper.getMainLooper()).post {
-    inCallChatViewModel.open()
+import com.cometchat.calls.core.CallSession
+import com.cometchat.calls.listeners.ButtonClickListener
+
+CallSession.getInstance().addButtonClickListener(lifecycleOwner, object : ButtonClickListener() {
+  override fun onChatButtonClicked() {
+    // Listener is on background thread — dispatch to UI
+    Handler(Looper.getMainLooper()).post {
+      inCallChatViewModel.open()
+    }
   }
-}
+})
 ```
 
 ---

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

@@ -10,14 +10,16 @@ V6 ships the same SDK API as V5 with two key delta: (1) Compose-first surface fo
 ## SDK API (same as V5)
 
 ```kotlin
-import com.cometchat.calls.core.CometChatCalls
+import com.cometchat.calls.core.CallSession
 import com.cometchat.calls.listeners.CometChatCallsEventsListener
 import com.cometchat.calls.model.Participant
 
-CometChatCalls.raiseHand()
-CometChatCalls.lowerHand()
+// raiseHand / lowerHand are instance methods on the CallSession singleton.
+CallSession.getInstance().raiseHand()
+CallSession.getInstance().lowerHand()
 
-val settings = SessionSettingsBuilder(context, callContainer)
+// SessionSettingsBuilder has only () and (Activity) constructors — no (context, container) form.
+val settings = SessionSettingsBuilder(activity)  // or no-arg SessionSettingsBuilder()
   .setSessionType(SessionType.VIDEO)
   .hideRaiseHandButton(true)
   .build()