@cometchat/skills 4.1.0 → 4.2.0

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

@@ -0,0 +1,375 @@
+---
+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.
+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"
+---
+
+## ⚠️ 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.
+
+### W1 — `calls-sdk-android:5.0.+` is a REQUIRED peer dep
+
+The V6 chatuikit advertises bundled calling, but its compose AAR references `com.cometchat.calls.core.CometChatCalls$SessionSettingsBuilder` at bytecode level — that class lives in `calls-sdk-android:5.0.0`, not in the chatuikit AAR. Without this dep, `Application.onCreate` crashes with `ClassNotFoundException`.
+
+```kotlin
+implementation("com.cometchat:chatuikit-compose-android:6.0.+")
+implementation("com.cometchat:calls-sdk-android:5.0.+")  // REQUIRED
+```
+
+### W2 — `annotations-java5` duplicate-class exclude
+
+Build fails with `Duplicate class org.jetbrains.annotations.*` from a transitive legacy dep.
+
+```kotlin
+configurations.all {
+    exclude(group = "org.jetbrains", module = "annotations-java5")
+}
+```
+
+### W3 — Stub classes for chat-sdk's legacy CallManager references
+
+chat-sdk-android's `CallManager` bytecode references legacy `com.cometchat.calls.{CometChatRTCView, model.RTCUser, model.RTCReceiver, model.RTCCallback}` (V3-era paths). calls-sdk-android:5.0.0 moved everything to `com.cometchat.calls.core.*` and dropped these. Without stubs in your source tree, the first call attempt fires `E/CallManager: CometChat Calling module not found`.
+
+Create empty stubs at the legacy paths:
+
+```java
+// app/src/main/java/com/cometchat/calls/CometChatRTCView.java
+package com.cometchat.calls;
+public class CometChatRTCView {}
+
+// app/src/main/java/com/cometchat/calls/model/RTCUser.java
+package com.cometchat.calls.model;
+public class RTCUser {
+    public RTCUser(String uid, String name, String avatar) {}
+}
+
+// app/src/main/java/com/cometchat/calls/model/RTCReceiver.java
+package com.cometchat.calls.model;
+public class RTCReceiver {
+    public RTCReceiver(String uid, String name, String type) {}
+}
+
+// app/src/main/java/com/cometchat/calls/model/RTCCallback.java
+package com.cometchat.calls.model;
+public interface RTCCallback<T> { void onSuccess(T result); }
+```
+
+Class verification finds these locally and lets CallManager load. They're never actually invoked at runtime because the V6 chatuikit uses `com.cometchat.calls.core.CometChatCalls.startSession` (a different code path) for the real call surface.
+
+### W4 — Do NOT use `CometChatCallButtons` — wire your own
+
+The kit's `CometChatCallButtons(user = user)` composable IGNORES the per-row `user` prop and dials whichever user was first rendered (it captures global state on first composition). Symptom: every call regardless of which row you tap rings the same person. Workaround:
+
+```kotlin
+@Composable
+fun UserRow(user: User) {
+    val context = LocalContext.current
+    Row(...) {
+        Text(user.name ?: user.uid)
+        IconButton(onClick = {
+            val outgoing = Call(
+                user.uid,
+                CometChatConstants.RECEIVER_TYPE_USER,   // see W5 — order matters
+                CometChatConstants.CALL_TYPE_VIDEO,
+            )
+            CometChat.initiateCall(outgoing, object : CometChat.CallbackListener<Call>() {
+                override fun onSuccess(call: Call) {
+                    // Hand off to the kit's outgoing-call screen — this part works correctly
+                    CometChatCallActivity.Companion.launchOutgoingCallScreen(context, call, null)
+                }
+                override fun onError(e: CometChatException) { /* surface */ }
+            })
+        }) { Text("📹") }
+    }
+}
+```
+
+`CometChatCallActivity.launchOutgoingCallScreen` handles the full lifecycle (ringing UI, token mint, joinSession, transition to in-call surface) correctly — only the button composable is broken.
+
+### W5 — `Call` constructor arg order CHANGED in chat-sdk 5.x
+
+```kotlin
+// ❌ v4 style — server returns ERR_BAD_REQUEST: "Failed to validate the data sent with the request"
+Call(receiverUid, CALL_TYPE_VIDEO, RECEIVER_TYPE_USER)
+
+// ✅ v5 (what chatuikit-compose:6.0.0 pulls in transitively as chat-sdk-android:5.0.1)
+Call(receiverUid, RECEIVER_TYPE_USER, CALL_TYPE_VIDEO)
+```
+
+Bytecode-confirmed against chat-sdk-android:5.0.1: `arg1 → receiverUid`, `arg2 → receiverType`, `arg3 → type`.
+
+---
+
+## 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).
+
+**⚠️ 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:
+
+```kotlin
+dependencies {
+    implementation("com.cometchat:chatuikit-compose-android:6.0.+") // or chatuikit-kotlin-android
+    implementation("com.cometchat:calls-sdk-android:5.0.+")          // REQUIRED — not optional
+}
+```
+
+The `UIKitSettings` builder must still call `.setEnableCalling(true)` to register the calling extension at init time.
+
+**Read these other skills first:**
+- `cometchat-calls` — dispatcher (modes, hard rules, anti-patterns)
+- `cometchat-android-v6-core` — UIKitSettings shape, Compose vs Views detection, init order
+- `cometchat-android-v6-builder-settings` — every option on `UIKitSettings` including the calling block
+- `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/`
+- 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)
+
+---
+
+## 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+)
+
+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"**.
+
+```kotlin
+import com.cometchat.calls.core.CometChatCalls
+import com.cometchat.calls.exceptions.CometChatException as CallsException
+import com.cometchat.calls.model.CallUser   // ← callback type, NOT chat User
+
+// ✓ RIGHT — chat login first, then calls login
+CometChat.login(uid, AUTH_KEY, object : CometChat.CallbackListener<User>() {
+  override fun onSuccess(user: User) {
+    CometChatCalls.login(uid, AUTH_KEY,
+      object : CometChatCalls.CallbackListener<CallUser>() {
+        override fun onSuccess(callUser: CallUser) { /* both ready */ }
+        override fun onError(e: CallsException) { /* surface */ }
+      })
+  }
+  override fun onError(e: CometChatException) { /* surface */ }
+})
+```
+
+**Surprises (verified on real hardware, Android 12 + 14):**
+- `com.cometchat.chat.models.User` does **NOT** expose `authToken` on Android — don't try `user.authToken`. Use the `(uid, apiKey)` overload for dev or fetch the auth token from your backend for production.
+- The Calls SDK callback returns `com.cometchat.calls.model.CallUser`, NOT `com.cometchat.chat.models.User`. Importing the wrong type gives "Type mismatch" at compile time.
+- The Calls SDK does NOT persist login across launches like the Chat SDK does. Re-login on every cold start where `CometChat.getLoggedInUser()` returns a non-null user.
+
+### 1.1 Dual-SDK contract — same shape, simpler imports
+
+V6 still routes ringing through Chat SDK (`CometChat.initiateCall`) and the WebRTC session through the Calls SDK — but both are accessed via the unified V6 facade. The two-`Call`-classes problem from V5 still exists internally; the V6 components hide it but custom code that imports `com.cometchat.chat.core.Call` directly must still pick the right one.
+
+```kotlin
+// ⚠️ DO NOT USE — broken at chatuikit-compose:6.0.0 (see W4 above).
+// Captures first-rendered user globally; every row dials the same person.
+// CometChatCallButtons(user = user, group = null)
+
+// ✓ RIGHT — wire your own button + use the kit's outgoing-call Activity directly.
+// See §"Five required workarounds" W4 for the full pattern.
+IconButton(onClick = {
+    val call = Call(user.uid, RECEIVER_TYPE_USER, CALL_TYPE_VIDEO)  // see W5 — arg order
+    CometChat.initiateCall(call, object : CometChat.CallbackListener<Call>() {
+        override fun onSuccess(c: Call) {
+            CometChatCallActivity.Companion.launchOutgoingCallScreen(context, c, null)
+        }
+        override fun onError(e: CometChatException) { /* surface */ }
+    })
+}) { Text("📹") }
+```
+
+### 1.2 VoIP push — same architecture, ConnectionService + FCM
+
+Identical to V5 (rule 1.2 in `cometchat-android-v5-calls`). The V6 UIKit doesn't ship its own ConnectionService — you write one. Reference implementation in `cometchat-android-v5-calls/references/voip-calling.md` works unchanged for V6 (the FCM payload shape and ConnectionService API are platform-level, not SDK-version-specific).
+
+### 1.3 Build prerequisite — annotations-java5 duplicate-class conflict
+
+**⚠️ Mandatory exclude.** A transitive dep of `chatuikit-compose-android:6.0.+` pulls in the legacy `org.jetbrains:annotations-java5:17.0.0`, which conflicts with the modern `org.jetbrains:annotations:23.0.0` brought in by Kotlin 2.0+. AGP fails the build with dozens of `Duplicate class org.jetbrains.annotations.*` lines. Add to `app/build.gradle.kts`:
+
+```kotlin
+configurations.all {
+    exclude(group = "org.jetbrains", module = "annotations-java5")
+}
+```
+
+The exclude must be on `configurations.all` (not on a specific configuration) because the legacy artifact leaks into runtime, compile, and androidTest classpaths.
+
+### 1.4 Foreground service type — UIKit-managed in V6
+
+V6 ships its own `CometChatOngoingCallService` registered automatically via the kit's manifest merge. You still must declare the Android 14+ `FOREGROUND_SERVICE_PHONE_CALL` / `FOREGROUND_SERVICE_MICROPHONE` / `FOREGROUND_SERVICE_CAMERA` permissions in your app's manifest — manifest merge does NOT pull permissions across module boundaries.
+
+```xml
+<!-- AndroidManifest.xml — required even though the service is kit-provided -->
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE_PHONE_CALL" />
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" />
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA" />
+```
+
+### 1.5 Server-minted auth tokens
+
+Unchanged from V5 / chat dispatcher — see `cometchat-android-v6-production` for the token-endpoint pattern.
+
+### 1.6 Hangup cleanup — V6 components handle it
+
+The V6 `CometChatOngoingCall` composable / Kotlin View handles the camera-light / mic-release cleanup via its own `DisposableEffect` (Compose) or `onDetachedFromWindow` (Views). Custom OngoingCall surfaces (Section 5) must replicate this — the hard rule still applies, just the canonical implementation is in the kit.
+
+### 1.7 Permissions with rationale
+
+Same set as V5, plus V6's `minSdk = 28` floor means `POST_NOTIFICATIONS` runtime prompt (Android 13+) is always required. The V6 kit ships a `CallPermissionsHandler` that runs the standard request flow with rationale strings.
+
+### 1.8 IncomingCall mounted at app root
+
+V6 exposes `CometChatIncomingCall` as a top-level composable / View. In standalone mode, mount it inside `setContent { ... }` at the root of your `MainActivity`, OUTSIDE the navigation graph, so it survives screen transitions.
+
+```kotlin
+// MainActivity.kt — Compose, standalone mode
+class MainActivity : ComponentActivity() {
+  override fun onCreate(savedInstanceState: Bundle?) {
+    super.onCreate(savedInstanceState)
+    setContent {
+      CometChatTheme {
+        Box(modifier = Modifier.fillMaxSize()) {
+          AppNavigation()                          // Your nav graph (calls or otherwise)
+          CometChatIncomingCall(modifier = Modifier.fillMaxSize())  // overlays everything
+        }
+      }
+    }
+  }
+}
+```
+
+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>`.
+
+---
+
+## 2. Setup — the V6 difference
+
+V6 has no separate calls module. If `chatuikit-{compose,kotlin}-android` is already in `app/build.gradle.kts` from `cometchat-android-v6-core`, calls are already on the classpath. The skill only:
+
+1. Adds calling configuration to `UIKitSettings`:
+   ```kotlin
+   val settings = UIKitSettings.Builder()
+     .setAppId(BuildConfig.COMETCHAT_APP_ID)
+     .setRegion(BuildConfig.COMETCHAT_REGION)
+     .setAuthKey(BuildConfig.COMETCHAT_AUTH_KEY)
+     .subscribePresenceForAllUsers()
+     .enableCalling()                              // ← v6 flips calling on here
+     .build()
+   ```
+2. Ensures the four FOREGROUND_SERVICE permissions and the four call permissions are in `AndroidManifest.xml`.
+3. Adds the V6 Kotlin Views theme parent rule from `cometchat-android-v6-troubleshooting`: Activity themes hosting V6 Views must inherit from `CometChatTheme.DayNight` (V6 components extend `MaterialCardView` and reference kit-specific theme attrs that aren't in `Theme.AppCompat.*` or `Theme.MaterialComponents.*`). Compose surfaces are immune.
+
+Detailed V6 init order: `cometchat-android-v6-core`. UIKitSettings option-by-option: `cometchat-android-v6-builder-settings`.
+
+---
+
+## 3. Components — Compose vs Kotlin Views
+
+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.*`)
+
+| Composable | Purpose |
+|---|---|
+| `CometChatCallButtons(user, group)` | Voice + video buttons — typically in a top-bar trailing slot or contact card |
+| `CometChatIncomingCall(modifier)` | Root-mounted overlay; renders nothing when no call active |
+| `CometChatOutgoingCall(call, user, group)` | Pushed when local user initiates; auto-dismisses on accept/reject |
+| `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.*`)
+
+Same names, different package. Inflate via XML or programmatically:
+
+```xml
+<com.cometchat.chatuikit.calling.views.CometChatCallButtons
+    android:id="@+id/callButtons"
+    android:layout_width="wrap_content"
+    android:layout_height="wrap_content" />
+```
+
+Then in code: `binding.callButtons.setUser(user)`.
+
+Full component-by-component catalogs live in the existing `cometchat-android-v6-compose-components` and `cometchat-android-v6-kotlin-components` skills — read whichever matches the project's surface.
+
+---
+
+## 4. Standalone integration
+
+When `product === "voice-video"` and there is no V6 chat integration yet.
+
+**Split by calling mode:**
+
+### 4a. Standalone — Session mode (meeting-room UX, no ringing)
+
+Calls SDK ONLY. NO chatuikit-android, NO ConnectionService, NO FCM-for-VoIP. Same SDK as V5 (`com.cometchat.calls-sdk-android`). Scaffold:
+
+1. **`Application` class** — `CometChatCalls.init(...)` ONLY. No chatuikit, no Chat SDK init.
+2. **`MainActivity` (Compose)** — `setContent` with `NavHost` for `/`, `/meet/{sessionId}`.
+3. **`CallRoom` composable** — `AndroidView` factory wrapping `RelativeLayout` (remember-stable), `LaunchedEffect(sessionId)` fires `CometChatCalls.joinSession(sessionId, settings, container, CallbackListener)`, `DisposableEffect` cleanup. See `references/call-session.md`.
+4. **`AndroidManifest.xml`** — Camera + microphone permissions + `FOREGROUND_SERVICE_MICROPHONE/CAMERA` + `CometChatOngoingCallService` registration. NO ConnectionService.
+5. **App Links** — `https://yourapp.com/meet/<sessionId>` deep-link routing.
+
+**Why no chatuikit / no ConnectionService:** session mode never touches kit components or push. The W1–W5 V6 workarounds (which are for chatuikit's broken integration with the Calls SDK) DO NOT apply to standalone session-only — they're only relevant when the V6 kit is loaded.
+
+### 4b. Standalone — Ringing mode (kit-driven with W1–W5 workarounds)
+
+Dual-SDK + telecom + push + V6 chatuikit:
+
+- **Compose path:** A `MainActivity` with `setContent` that holds: nav graph (with `/profile`, `/calls`, `/ongoing-call/{sessionId}` routes), `CometChatIncomingCall` overlay (rule 1.7), top-level theme with `CometChatTheme`. Profile screen has `CometChatCallButtons` next to the user's name.
+- **Kotlin Views path:** `MainActivity` extending `AppCompatActivity` with theme `CometChatTheme.DayNight`, a `FragmentContainerView` for nav + a sibling `CometChatIncomingCall` view in the same `FrameLayout`. Profile fragment hosts `CometChatCallButtons`.
+- VoIP push: ConnectionService + FCM (rule 1.2 — implementation copied from V5 references/voip-calling.md, unchanged on V6).
+- Manifest permissions, foreground service permissions, ProGuard rules (`-keep class com.cometchat.** { *; }`).
+- **W1–W5 workarounds apply** (see "Five required workarounds" above).
+
+## 5. Additive integration
+
+When chat is already integrated via V6. The skill:
+
+- Adds `.enableCalling()` to the existing `UIKitSettings.Builder()` 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.
+- VoIP push: opt-in (asks user).
+
+## 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()`.
+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.
+5. **Mixing V5 and V6 call types.** The V5 `SessionType.VOICE` and the V6 `CallType.AUDIO` are not interchangeable enums. If you import from `com.cometchat.calls.types.SessionType`, you're pulling V5; V6 uses `CallType` from the unified UIKit package.
+
+## 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()`
+- [ ] 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)
+- [ ] `CometChatIncomingCall` mounted at root (Compose: outside nav graph; Views: top-level FrameLayout)
+- [ ] **Standalone only:** ConnectionService + FCM service registered
+- [ ] **Standalone only:** PhoneAccount registered in `Application.onCreate`
+- [ ] Real device: outgoing call → audio + video two-way
+- [ ] Real device: incoming call rings on lock screen
+- [ ] Hangup releases camera + mic within 2 seconds
+- [ ] On Android 14+: ongoing-call notification visible, swipe-up doesn't kill the call
+
+## 8. Pointers
+
+- `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
+- `cometchat-android-v6-production` — token endpoints, ProGuard rules
+- `cometchat-android-v6-troubleshooting` — V6 Kotlin Views theme parent crash diagnostic

package/skills/cometchat-android-v6-calls/references/add-calls-to-existing-chat.md

@@ -0,0 +1,97 @@
+# Adding calls to an existing chat integration (Android V6 / Compose)
+
+V6 calls are **bundled** into `chatuikit-{compose,kotlin}-android:6.x` — there's no separate calls SDK to install. To turn calls on, call `.enableCalling()` on your UIKit settings.
+
+**Read first:** `cometchat-android-v6-calls/SKILL.md` — V6 architecture.
+
+---
+
+## Step 1 — Verify chat-uikit cohort
+
+```kotlin
+// app/build.gradle.kts
+dependencies {
+  implementation("com.cometchat:chatuikit-compose-android:6.+")
+  // (or chatuikit-kotlin-android for Views)
+}
+```
+
+If you're on `chatuikit-android` v5 or `calls-sdk-android` separately, this is the wrong family — see `cometchat-android-v5-calls/references/add-calls-to-existing-chat.md`.
+
+---
+
+## Step 2 — Enable calling on UIKit
+
+Find your existing UIKit init (typically in `Application.onCreate` or `MainActivity.onCreate`):
+
+```kotlin
+val uikitSettings = UIKitSettings.Builder()
+  .setAppId(APP_ID)
+  .setRegion(REGION)
+  .setAuthKey(AUTH_KEY)   // OR .subscribePresenceForAllUsers() etc.
+  .enableCalling()         // NEW — adds calls
+  .build()
+
+CometChatUIKit.init(this, uikitSettings, /* callback */)
+```
+
+That's the entire migration for V6. The bundled calls SDK initializes when chat init succeeds.
+
+---
+
+## Step 3 — Permissions + manifest
+
+Same as V5 (see V5 sister doc). V6 doesn't change permission requirements.
+
+---
+
+## Step 4 — Mount CometChatIncomingCall
+
+In Compose:
+
+```kotlin
+@Composable
+fun AppRoot() {
+  Box(modifier = Modifier.fillMaxSize()) {
+    AppContent()
+    CometChatIncomingCall()  // overlay on top — handles incoming call UI
+  }
+}
+```
+
+In Views (Kotlin XML):
+
+```xml
+<!-- activity_main.xml -->
+<FrameLayout ...>
+  <fragment android:id="@+id/main_content" .../>
+  <com.cometchat.chatuikit.calls.incomingcall.CometChatIncomingCall
+    android:layout_width="match_parent"
+    android:layout_height="match_parent"/>
+</FrameLayout>
+```
+
+---
+
+## Step 5 — FCM VoIP push
+
+Same as V5 (see `cometchat-android-v5-calls/references/server-fcm-voip.md`). V6 adds a Compose-friendly `IncomingCallActivity` pattern — see `cometchat-android-v6-calls/references/server-fcm-voip.md`.
+
+---
+
+## Verification checklist
+
+- [ ] `chatuikit-compose-android:6.+` (or `chatuikit-kotlin-android:6.+`) in app deps
+- [ ] `.enableCalling()` chained into UIKitSettings.Builder
+- [ ] Manifest permissions same as V5
+- [ ] `CometChatIncomingCall` mounted (Compose overlay or Views FrameLayout)
+- [ ] FCM token registration wired
+- [ ] Run `cometchat verify --calls` — `v6_enable_calling` should pass
+
+---
+
+## Pointers
+
+- `cometchat-android-v5-calls/references/add-calls-to-existing-chat.md` — V5 sister (separate calls SDK)
+- `cometchat-android-v6-calls/SKILL.md`
+- `cometchat-android-v6-calls/references/server-fcm-voip.md` — Compose-flavored server FCM

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

@@ -0,0 +1,91 @@
+# Call layouts on Android V6 (Compose)
+
+Same SDK API as V5; V6 adds Compose-native `SegmentedButton` for the switcher.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/android/call-layouts
+**Read first:** `cometchat-android-v5-calls/references/call-layouts.md` — full Java/Kotlin SDK API.
+
+---
+
+## ViewModel
+
+```kotlin
+class CallLayoutViewModel : ViewModel() {
+  private val _layout = MutableStateFlow(CometChatCallsConstants.LAYOUT_TILE)
+  val layout: StateFlow<String> = _layout
+
+  fun set(next: String) {
+    CometChatCalls.setLayout(next)
+    _layout.value = next
+  }
+
+  fun onSDKChanged(next: String) {
+    _layout.value = next  // already updated by kit's switcher
+  }
+}
+
+// Wire from CometChatCallsEventsListener:
+override fun onCallLayoutChanged(layout: String) {
+  Handler(Looper.getMainLooper()).post {
+    callLayoutViewModel.onSDKChanged(layout)
+  }
+}
+```
+
+---
+
+## Compose switcher (SingleChoiceSegmentedButtonRow)
+
+```kotlin
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+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",
+  )
+
+  SingleChoiceSegmentedButtonRow {
+    options.forEachIndexed { index, (value, label) ->
+      SegmentedButton(
+        selected = layout == value,
+        onClick = { viewModel.set(value) },
+        shape = SegmentedButtonDefaults.itemShape(index = index, count = options.size),
+      ) {
+        Text(label)
+      }
+    }
+  }
+}
+```
+
+---
+
+## Anti-patterns
+
+V5 sister rules apply, plus Compose-specific:
+
+1. **`collectAsState()` instead of `collectAsStateWithLifecycle()`.** State updates while paused → wasted work.
+2. **`Row` of `OutlinedButton`s instead of `SegmentedButton`.** Visually similar but missing the radio-group accessibility semantics; TalkBack announces it as 3 separate buttons.
+3. **Calling `setLayout` directly from the composable.** Move it to ViewModel — survives config changes.
+
+---
+
+## Verification checklist
+
+- [ ] `CallLayoutViewModel` exposes `StateFlow<String>`
+- [ ] `SingleChoiceSegmentedButtonRow` wraps the layout options
+- [ ] `collectAsStateWithLifecycle` (not `collectAsState`)
+- [ ] `onCallLayoutChanged` syncs the ViewModel on main thread
+- [ ] Real-device smoke: cycles all 3, survives rotation
+
+---
+
+## Pointers
+
+- `cometchat-android-v5-calls/references/call-layouts.md` — V5 sister (Views patterns)
+- `cometchat-android-v6-calls` SKILL.md
+- Canonical docs: https://www.cometchat.com/docs/calls/android/call-layouts