@cometchat/skills 4.3.0 → 4.4.0

package/skills/cometchat/references/asking-questions.md

@@ -0,0 +1,48 @@
+# Clarification contract (all coding agents)
+
+Every place a CometChat skill says **"ask the user"**, **"render an `AskUserQuestion`"**, **"MUST ask"**, or **"NON-NEGOTIABLE prompt"** means: **follow this contract.** It is **model-agnostic** — it works on Claude Code, Codex, Cursor, Gemini CLI, OpenAI coding agents, Windsurf, and any future agent. `AskUserQuestion` is merely Claude Code's name for step 1; every agent has an equivalent, and if it doesn't, the text fallback below is mandatory.
+
+## The contract
+
+1. **RENDER a structured choice.**
+   - If your runtime has a native structured-question primitive (Claude Code: `AskUserQuestion`; others may differ), use it.
+   - **If it does not, render a numbered text list** — a one-line header, the question, then each option on its own numbered line — and ask the user to reply with a number or the option text. Never skip the prompt just because you lack a GUI primitive.
+
+2. **WAIT for a real answer. Do NOT proceed on a guess.**
+   - Do not pick a default, do not infer the answer from the repo, the project name, or "what's most common."
+   - **Auto / YOLO / "moving fast for the demo" / approval-mode does NOT authorize skipping a user-facing decision.** Those modes govern *tool and shell approvals*, not product choices. Surface the prompt regardless of approval mode.
+
+3. **MAP the answer by VALUE / LABEL — never by ordinal position.**
+   - The user may reply with the option text, a number, or free text. Resolve it to the option's *meaning*, not "they typed 1 so it's the first option."
+   - This matters because different agents render options in different orders; matching on position silently corrupts the choice.
+
+4. **ACCEPT a free-text fallback.**
+   - If the answer isn't one of the listed options (a different `uid`, region, app name, framework version…), treat it as a valid custom value — do not loop re-prompting the same list.
+
+5. **ONE decision per prompt** unless the choices are genuinely independent. Don't bundle unrelated decisions (e.g. framework + uid + region) into a single question.
+
+6. **SELF-VERIFY before moving on.** Confirm you have an explicit answer for every *required* prompt of the current step. If you are running **headless / non-interactive** (no stdin, CI, cron), do **not** guess — STOP and emit the exact question + options so a human can answer, then resume.
+
+## Canonical text rendering (for agents without a structured primitive)
+
+```
+❓ <one-line question>   (reply with the number or the text)
+  1) <Option label> — <short description>
+  2) <Option label> — <short description>
+  3) <Option label> — <short description>
+  Or type your own answer.
+```
+
+Wait for the reply. Resolve it to an option by label/text (or accept a custom value). Then continue.
+
+## Prompts in the CometChat skills that MUST follow this contract
+
+These are load-bearing — skipping them silently picks defaults the user never saw, which corrupts downstream routing or ships broken code:
+
+- **Greenfield framework choice** (when `detect` returns no framework) — never scaffold a framework the user didn't choose.
+- **Android version** (V5 vs V6) and **Flutter version** (V5 vs V6) when the project is greenfield — these route to *different* SDKs; guessing wrong emits unusable code.
+- **Android/Flutter surface** (Compose vs Kotlin Views; which screen) when both are present.
+- **Dev-mode login UID** — never hardcode `cometchat-uid-1`; ask which test user. A default UID flagged as a Bot in the dashboard fails auth with an opaque error.
+- **Sign-up flow choices** — product, role, intent, app name, region, industry. These mirror the dashboard browser flow and drive downstream recommendations.
+- **Calling mode** (default UI calling vs session-mode vs raw SDK), **chat-only vs chat+calls**, and **custom-UI vs UI-Kit** when the journey forks.
+- **Existing-integration decisions** — when a competing chat SDK, existing Firebase/push, or an existing auth system is detected (see the dispatcher's pre-flight scan), ask how to proceed rather than clobbering.

package/skills/cometchat-a11y/SKILL.md

@@ -3,13 +3,14 @@ name: cometchat-a11y
 description: Accessibility (a11y) for CometChat UI Kit integrations across all families — React, React Native, Angular, Android (V5/V6), iOS, Flutter. Covers WCAG 2.1 AA targets, keyboard navigation in chat, screen reader announcements (live regions for new messages), color contrast, focus management on call screens, motion-reduction support, and the cross-family checks that catch the common production a11y bugs. Cross-family — applies wherever the agent is checking accessibility.
 license: "MIT"
 compatibility: "All CometChat UI Kit families v4.x / v5.x / v6.x"
-allowed-tools: "shell, file-read, file-search, file-list, ask-user"
 metadata:
   author: "CometChat"
   version: "4.0.0"
   tags: "cometchat a11y accessibility wcag aa keyboard screen-reader voiceover talkback aria live-region focus-management contrast prefers-reduced-motion cross-family"
 ---
 
+> **Ground truth:** per-platform UI Kit + `docs/fundamentals`. **Official docs:** https://www.cometchat.com/docs/fundamentals/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them.
+
 ## Purpose
 
 Accessibility for CometChat integrations. Out-of-the-box, the UI Kit components are mostly accessible — the kit's own buttons, inputs, and lists ship with semantic markup. Production gaps appear in the wiring **around** the kit: custom call surfaces, navigation, focus management on screen transitions, and contrast in custom themes.
@@ -101,7 +102,7 @@ export function ChatScreen() {
 }
 ```
 
-The kit's `CometChatMessageComposer` accepts a forwarded ref in v6; if not, query for the input via `composerRef.current?.querySelector("input, [contenteditable]")?.focus()`.
+The kit's `CometChatMessageComposer` is a plain function component (no `forwardRef` in v6), so passing it a `ref` is a no-op. Wrap it in a focusable container and reach the input through the DOM: `composerRef.current?.querySelector("input, [contenteditable]")?.focus()`.
 
 ### React Native
 

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

@@ -3,13 +3,14 @@ name: cometchat-android-v5
 description: "Entry-point dispatcher for CometChat Android UI Kit v5. Detects project setup, understands what the dev is building, and routes to the right sub-skills."
 license: "MIT"
 compatibility: "Android 7.0+; Java 8+; Kotlin 1.8+; com.cometchat:chat-uikit-android:5.x"
-allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"
   tags: "chat cometchat android dispatcher entry-point integration"
 ---
 
+> **Ground truth:** `com.cometchat:chat-uikit-android:5.x` (legacy/maintenance-only; +`calls-sdk-android:5.x`) — resolved AAR (javap) + `ui-kit/android`. **Official docs:** https://www.cometchat.com/docs/ui-kit/android/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them.
+
 ## Purpose
 
 This is the entry-point skill for CometChat Android UI Kit v5. It helps you understand what the developer is building, detects their project setup, and routes to the correct sub-skill for the task at hand.

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

@@ -3,7 +3,6 @@ name: cometchat-android-v5-calls
 description: CometChat Calls SDK v5 integration for native Android (V5 stable, Java + Kotlin Views). Covers SDK setup (Cloudsmith Maven, CallAppSettings, init), the dual-SDK ringing pattern (Chat SDK initiateCall + Calls SDK joinSession), session settings, event listeners, call logs, recording, screen sharing, picture-in-picture, foreground service for ongoing calls, VoIP push via FCM + ConnectionService, audio/video/participant controls, custom UI, and in-call chat. Use in standalone mode (calls is the product) or additive mode (calls layered on top of an existing CometChat Android v5 chat integration).
 license: "MIT"
 compatibility: "Android Studio Hedgehog+, JDK 17, Gradle 8+, AGP 8+, minSdk 26+, compileSdk 35; com.cometchat:calls-sdk-android:5.x; com.cometchat:chat-sdk-android:4.x (when ringing)"
-allowed-tools: "shell, file-read, file-search, file-list, ask-user"
 metadata:
   author: "CometChat"
   version: "4.0.0"
@@ -22,9 +21,9 @@ Production-grade voice + video calling for native Android v5. Loaded by the `com
 - `cometchat-android-v5-core` — Chat SDK init, login order, `local.properties` + `BuildConfig` credential conventions, Application class wiring
 
 **Ground truth:**
-- SDK source — `~/Downloads/calls-sdk/calls-sdk-android-5/sdk/`
-- Sample app — `~/Downloads/calls-sdk/calls-sdk-android-5/samples/`
-- Pre-authored topic docs — `references/` in this skill (16 docs, ~2300 lines, audited against `calls-sdk-android@5.0.0-beta.2`)
+- SDK source — `calls-sdk-android-5/sdk/`
+- Sample app — `calls-sdk-android-5/samples/`
+- Pre-authored topic docs — `references/` in this skill (16 docs, ~2300 lines, audited against `calls-sdk-android@5.0.x` (v5 GA))
 - Public docs — https://www.cometchat.com/docs/calls/android/overview
 
 ---
@@ -94,7 +93,7 @@ This trapped a real smoke run. The chat skill's `loginAfter` pattern doesn't tra
 The Chat SDK initiates ringing (`CometChat.initiateCall(...)`); the Calls SDK runs the WebRTC session (`CometChatCalls.joinSession(...)`). They are NOT interchangeable, and there are **two `Call` classes** with the same simple name:
 
 - **`com.cometchat.chat.core.Call`** — Chat SDK. Used by `initiateCall`, `acceptCall`, `rejectCall`. Carries `sessionId`, `receiver`, `receiverType`, `callType`. **This is the one you almost always want.**
-- **`com.cometchat.chat.models.Call`** — Chat SDK message model. Returned in conversation/message-list contexts. Different shape; rarely the right import in calls code.
+- **There is only ONE `Call` class: `com.cometchat.chat.core.Call`** (it extends `BaseMessage`, so it surfaces in conversation/message-list contexts too). There is **no** `com.cometchat.chat.models.Call` — do not import that path (it does not exist).
 
 ```kotlin
 // ✓ RIGHT — initiate ringing
@@ -114,14 +113,17 @@ CometChat.initiateCall(outgoing, object : CometChat.CallbackListener<Call>() {
 // ✓ RIGHT — join the WebRTC session after the receiver accepts
 import com.cometchat.calls.core.CometChatCalls
 import com.cometchat.calls.core.CallSession
-import com.cometchat.calls.types.SessionType
+import com.cometchat.calls.model.SessionType
 
 // SessionSettingsBuilder is a NESTED class on CometChatCalls — access it via
 // CometChatCalls.SessionSettingsBuilder, NOT a top-level import.
 // `import com.cometchat.calls.core.SessionSettingsBuilder` fails: no such class.
+// Audio vs video is set via setSessionType(SessionType.VOICE | SessionType.VIDEO).
+// There is NO setIsAudioOnly() method on SessionSettingsBuilder — earlier
+// drafts of this skill cited it; that was wrong. Confirmed against
+// calls-sdk-android 5.0.x (ENG-35698 fix).
 val settings = CometChatCalls.SessionSettingsBuilder()
-  .setSessionType(SessionType.VIDEO)
-  .setIsAudioOnly(false)
+  .setSessionType(SessionType.VIDEO)   // or SessionType.VOICE for audio-only
   .build()
 
 // 4-arg signature: sessionId (or token), settings, RelativeLayout container, callback.
@@ -136,7 +138,7 @@ CometChatCalls.joinSession(sessionId, settings, callContainer,
 
 ```kotlin
 // ✗ WRONG — wrong Call class
-import com.cometchat.chat.models.Call  // message-model Call, not the core Call
+import com.cometchat.chat.core.Call  // the ONLY Call class (extends BaseMessage)
 val c = Call(...)  // compile-time errors on shape; or worse, runtime ambiguity
 ```
 
@@ -161,7 +163,7 @@ Android 14+ silently terminates ongoing-call foreground services that don't decl
 ```xml
 <!-- AndroidManifest.xml -->
 <service
-    android:name="com.cometchat.calls.service.CometChatOngoingCallService"
+    android:name="com.cometchat.calls.services.CometChatOngoingCallService"
     android:foregroundServiceType="phoneCall|microphone|camera"
     android:exported="false" />
 ```
@@ -188,7 +190,13 @@ Required teardown when ending a call:
 
 ```kotlin
 override fun onCallEnded(call: CallSession) {
-  CallSession.getInstance().leaveSession()          // 1. End the Calls SDK session (endSession() doesn't exist on Android)
+  // 1. End the Calls SDK session. Canonical v5 teardown is the CallSession
+  //    INSTANCE method leaveSession(), guarded by isSessionActive — exactly
+  //    what both calls-sdk-android sample apps use and what the v4→v5 migration
+  //    guide maps the old static CometChatCalls.endSession() to. Matches this
+  //    skill's references/call-session.md.
+  val session = CallSession.getInstance()
+  if (session.isSessionActive) session.leaveSession()
   callContainer?.removeAllViews()                   // 2. Detach the WebRTC view
   audioManager?.mode = AudioManager.MODE_NORMAL     // 3. Release audio routing
   audioManager?.abandonAudioFocusRequest(focusReq)  // 4. Abandon audio focus
@@ -269,8 +277,13 @@ class App : Application() {
       .build()
     CometChat.init(this, BuildConfig.COMETCHAT_APP_ID, appSettings, /* callback */)
 
-    // 2. Calls SDK init — must come after Chat SDK init
-    val callAppSettings = CallAppSettingsBuilder()
+    // 2. Calls SDK init — must come after Chat SDK init.
+    //
+    // The builder is the NESTED CallAppSettings.CallAppSettingBuilder
+    // (note: singular "Setting", not plural). It is NOT a top-level
+    // CallAppSettingsBuilder class — earlier drafts of this skill cited
+    // that wrong name; verified against calls-sdk-android 5.0.x (ENG-35698).
+    val callAppSettings = CallAppSettings.CallAppSettingBuilder()
       .setAppId(BuildConfig.COMETCHAT_APP_ID)
       .setRegion(BuildConfig.COMETCHAT_REGION)
       .build()
@@ -291,14 +304,15 @@ The Calls SDK ships these primitives. Names are stable across v5.x:
 
 | Class / type | Purpose | Where it lives |
 |---|---|---|
-| `CometChatCalls` | Top-level facade — init, joinSession, endSession, generateToken | `com.cometchat.calls.core` |
-| `CallAppSettingsBuilder` | Init-time config (appId, region, host) | `com.cometchat.calls.core` |
+| `CometChatCalls` | Top-level facade — init, joinSession, generateToken (session teardown is the instance method `CallSession.leaveSession()`, not a static here) | `com.cometchat.calls.core` |
+| `CallAppSettings.CallAppSettingBuilder` | Init-time config (appId, region, host) — **nested** class, singular "Setting" (NOT `CallAppSettingsBuilder`) | `com.cometchat.calls.core` |
+| `GenerateToken` | Wrapper returned by `CometChatCalls.generateToken` — extract the JWT via `.token` (NOT a raw `String`) | `com.cometchat.calls.model` |
 | `CometChatCalls.SessionSettingsBuilder` | Per-session config (layout, type, hide buttons, audio mode, recording) — **nested class**, access as `CometChatCalls.SessionSettingsBuilder()` |
-| `CometChatOngoingCallService` | Foreground service for active calls | `com.cometchat.calls.service` |
-| `SessionType` | `VOICE` / `VIDEO` (NOT "AUDIO") | `com.cometchat.calls.types` |
-| `LayoutType` | `TILE` / `SIDEBAR` / `SPOTLIGHT` | `com.cometchat.calls.types` |
+| `CometChatOngoingCallService` | Foreground service for active calls | `com.cometchat.calls.services` |
+| `SessionType` | `VOICE` / `VIDEO` (NOT "AUDIO") | `com.cometchat.calls.model` |
+| `LayoutType` | `TILE` / `SIDEBAR` / `SPOTLIGHT` | `com.cometchat.calls.model` |
 | `CallLogRequest.CallLogRequestBuilder` | Paginated call history fetcher | `com.cometchat.calls.core` |
-| `CometChatCallsEventsListener` | Lifecycle + media + participant + button-click | `com.cometchat.calls.listeners` |
+| `SessionStatusListener` / `ParticipantEventListener` / `MediaEventsListener` / `ButtonClickListener` / `LayoutListener` | The **five** v5 call-event listeners — register each on the `CallSession` instance (`callSession.addSessionStatusListener(...)` etc.). v5 split the old monolithic `CometChatCallsEventsListener` into these. See `references/event-listeners.md`. | `com.cometchat.calls.listeners` |
 
 In additive mode, `chatuikit-android`'s `CometChatMessageHeader` already exposes call buttons — see `cometchat-android-v5-components` for the kit-side view.
 
@@ -314,7 +328,7 @@ When `product === "voice-video"` and there is no existing chat integration.
 
 ### 4a. Standalone — Session mode (meeting-room UX, no ringing)
 
-Calls SDK ONLY. NO Chat SDK, NO ConnectionService, NO FCM-for-VoIP. Matches `~/Downloads/calls-sdk/calls-sdk-android-5/samples/sample-app/`. Scaffold:
+Calls SDK ONLY. NO Chat SDK, NO ConnectionService, NO FCM-for-VoIP. Matches `calls-sdk-android-5/samples/sample-app/`. Scaffold:
 
 1. **`Application` class** — `CometChatCalls.init(...)` ONLY in `onCreate`. No `CometChat.init`, no PhoneAccount, no ConnectionService.
 2. **`JoinSessionActivity`** — UID picker + Start/Join meeting + state.
@@ -357,7 +371,7 @@ Important: do NOT re-add `chat-sdk-android` or `chatuikit-android` to `build.gra
 
 ## 6. Anti-patterns
 
-1. **Calling `CometChatCalls.joinSession()` with the wrong `Call` import.** Compile errors are obvious; the dangerous case is when an agent imports `com.cometchat.chat.models.Call` and casts it. Cross-reference rule 1.1.
+1. **Calling `CometChatCalls.joinSession()` with the wrong `Call` import.** Compile errors are obvious; the dangerous case is inventing a non-existent `com.cometchat.chat.models.Call` import — the only Call class is `com.cometchat.chat.core.Call`. Cross-reference rule 1.1.
 
 2. **Hardcoding `SessionType.AUDIO`.** No such constant exists. The voice path is `SessionType.VOICE`. Listed here because it's the most common cargo-culted mistake — the iOS SDK uses "audio" terminology.
 
@@ -387,7 +401,7 @@ After scaffolding, verify (the skill writes Espresso-style smoke tests where pos
 - [ ] All three `FOREGROUND_SERVICE_*` Android 14+ permissions in `AndroidManifest.xml`
 - [ ] `CometChatOngoingCallService` with `foregroundServiceType="phoneCall|microphone|camera"`
 - [ ] Call listener registration uses a stable string ID
-- [ ] Hangup path includes `endSession()` + `removeAllViews()` + audio-focus abandon + service stop + finish (rule 1.5)
+- [ ] Hangup path includes `CallSession.getInstance().leaveSession()` (guarded by `isSessionActive`) + `removeAllViews()` + audio-focus abandon + service stop + finish (rule 1.5)
 - [ ] **Standalone only:** `ConnectionService` subclass + `PhoneAccount` registration + FCM `MessagingService` for incoming-call data messages
 - [ ] **Standalone only:** Call listener registered in `Application.onCreate`, not an activity
 

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

@@ -46,7 +46,7 @@ Each skill has a `description` field in its YAML frontmatter that lists trigger
 
 ## Compatibility
 
-- CometChat Calls SDK v5 (5.0.0-beta.2+)
+- CometChat Calls SDK v5 (5.0.+ GA)
 - CometChat Chat SDK v4 (4.0.+) — required for ringing and VoIP
 - Kotlin, Java 17
 - Gradle KTS, compileSdk 35, minSdk 26

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

@@ -96,10 +96,12 @@ After your existing login flow:
 ```kotlin
 CometChat.login(uid, authKey, object : CometChat.CallbackListener<User>() {
   override fun onSuccess(user: User) {
-    val authToken = user.authToken
-    CometChatCalls.login(authToken, object : CometChatCalls.CallbackListener<User>() {
-      override fun onSuccess(user: User) { /* calls SDK ready */ }
-      override fun onError(e: CometChatException) {}
+    // Calls SDK login uses the SAME uid + authKey (the chat `User` has no
+    // `authToken` accessor — if you need a token it's the static
+    // `CometChat.getUserAuthToken()`). Callback type is CallUser, not User.
+    CometChatCalls.login(uid, authKey, object : CometChatCalls.CallbackListener<CallUser>() {
+      override fun onSuccess(callUser: CallUser) { /* calls SDK ready */ }
+      override fun onError(e: com.cometchat.calls.exceptions.CometChatException) {}
     })
   }
   override fun onError(e: CometChatException) {}
@@ -163,7 +165,7 @@ Register in manifest:
 
 ```kotlin
 fun endCall(sessionId: String) {
-  CometChatCalls.leaveSession()
+  CometChatCalls.endSession()  // static teardown (there is NO static CometChatCalls.leaveSession() — leaveSession is instance-only on CallSession.getInstance())
   CometChat.endCall(sessionId, object : CometChat.CallbackListener<Call>() { /* ... */ })
   // ConnectionService disconnect
   activeConnection?.setDisconnected(DisconnectCause(DisconnectCause.LOCAL))

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

@@ -26,7 +26,7 @@ import com.cometchat.calls.listeners.MediaEventsListener
 val callSession = CallSession.getInstance()
 
 callSession.muteAudio()    // mute microphone
-callSession.unMuteAudio()  // unmute microphone
+callSession.unmuteAudio()  // unmute microphone
 ```
 
 ### Switch Audio Output
@@ -61,10 +61,10 @@ callSession.addMediaEventsListener(this, object : MediaEventsListener() {
     override fun onVideoResumed() {}
     override fun onRecordingStarted() {}
     override fun onRecordingStopped() {}
-    override fun onScreenShareStarted() {}
-    override fun onScreenShareStopped() {}
     override fun onCameraFacingChanged(facing: CameraFacing) {}
 })
+// Screen-share is observed via ParticipantEventListener.onParticipantStartedScreenShare /
+// onParticipantStoppedScreenShare — NOT MediaEventsListener.
 ```
 
 ### Initial Audio Settings (Pre-Session)
@@ -80,7 +80,7 @@ val sessionSettings = CometChatCalls.SessionSettingsBuilder()
 
 ## Gotchas
 
-- `muteAudio()` / `unMuteAudio()` only work during an active session
+- `muteAudio()` / `unmuteAudio()` only work during an active session
 - Audio mode changes trigger `onAudioModeChanged()` on `MediaEventsListener`
 - `AudioMode` enum: `SPEAKER`, `EARPIECE`, `BLUETOOTH`, `HEADPHONES`
 - For voice calls, default to `AudioMode.EARPIECE`; for video calls, default to `AudioMode.SPEAKER`

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

@@ -10,27 +10,29 @@ Same three layouts (TILE/SIDEBAR/SPOTLIGHT). Android V5 uses Java/Kotlin builder
 ## SDK API
 
 ```kotlin
-import com.cometchat.calls.constants.CometChatCallsConstants
-import com.cometchat.calls.core.CallSettingsBuilder
 import com.cometchat.calls.core.CometChatCalls
-
-val settings = CallSettingsBuilder(activity)
-  .setSessionType(CometChatCallsConstants.SESSION_TYPE_VIDEO)
-  .setLayout(CometChatCallsConstants.LAYOUT_TILE)        // _TILE | _SIDEBAR | _SPOTLIGHT
-  .setHideChangeLayoutButton(false)
+import com.cometchat.calls.listeners.LayoutListener
+import com.cometchat.calls.model.SessionType
+import com.cometchat.calls.model.LayoutType
+
+val settings = CometChatCalls.SessionSettingsBuilder()
+  .setSessionType(SessionType.VIDEO)
+  .setLayout(LayoutType.TILE)        // TILE | SIDEBAR | SPOTLIGHT
+  .hideChangeLayoutButton(false)
   .build()
 
-// Mid-call switch
-CometChatCalls.setLayout(CometChatCallsConstants.LAYOUT_SPOTLIGHT)
-
-// Listen
-val callsEventListener = object : CometChatCallsEventsListener {
-  override fun onCallLayoutChanged(layout: String) {
+// There is no static mid-call setter in v5. Layout is set at join via
+// SessionSettingsBuilder.setLayout(...); to change it mid-call, re-join the
+// session with a new SessionSettingsBuilder. Layout CHANGES are observed
+// via LayoutListener.onCallLayoutChanged(layoutType) — register on the
+// CallSession instance returned from joinSession's onSuccess callback.
+callSession.addLayoutListener(this, object : LayoutListener() {
+  override fun onCallLayoutChanged(layoutType: LayoutType) {
     activity.runOnUiThread {
       // Update segmented button state
     }
   }
-}
+})
 ```
 
 ---
@@ -72,21 +74,27 @@ binding.layoutToggle.addOnButtonCheckedListener { _, checkedId, isChecked ->
   if (!isChecked) return@addOnButtonCheckedListener
 
   val layout = when (checkedId) {
-    R.id.layoutTile -> CometChatCallsConstants.LAYOUT_TILE
-    R.id.layoutSidebar -> CometChatCallsConstants.LAYOUT_SIDEBAR
-    R.id.layoutSpotlight -> CometChatCallsConstants.LAYOUT_SPOTLIGHT
+    R.id.layoutTile -> LayoutType.TILE
+    R.id.layoutSidebar -> LayoutType.SIDEBAR
+    R.id.layoutSpotlight -> LayoutType.SPOTLIGHT
     else -> return@addOnButtonCheckedListener
   }
-  CometChatCalls.setLayout(layout)
+  // v5 has no static mid-call setter — re-join the session with new settings
+  // to apply the chosen layout.
+  val settings = CometChatCalls.SessionSettingsBuilder()
+    .setSessionType(SessionType.VIDEO)
+    .setLayout(layout)
+    .build()
+  // CometChatCalls.joinSession(sessionId, callToken, settings, ...) — see join-session.md
 }
 
-// Sync from kit's switcher
-override fun onCallLayoutChanged(layout: String) {
+// Sync from kit's switcher — observed via LayoutListener.onCallLayoutChanged
+override fun onCallLayoutChanged(layoutType: LayoutType) {
   runOnUiThread {
-    val id = when (layout) {
-      CometChatCallsConstants.LAYOUT_TILE -> R.id.layoutTile
-      CometChatCallsConstants.LAYOUT_SIDEBAR -> R.id.layoutSidebar
-      CometChatCallsConstants.LAYOUT_SPOTLIGHT -> R.id.layoutSpotlight
+    val id = when (layoutType) {
+      LayoutType.TILE -> R.id.layoutTile
+      LayoutType.SIDEBAR -> R.id.layoutSidebar
+      LayoutType.SPOTLIGHT -> R.id.layoutSpotlight
       else -> return@runOnUiThread
     }
     binding.layoutToggle.check(id)
@@ -108,7 +116,7 @@ Web sister rules apply, plus Android-specific:
 
 ## Verification checklist
 
-- [ ] Initial layout via `setLayout` on builder
+- [ ] Initial layout via `setLayout(LayoutType.X)` on `SessionSettingsBuilder`
 - [ ] `MaterialButtonToggleGroup` with `singleSelection="true"`
 - [ ] `addOnButtonCheckedListener` guards on `isChecked`
 - [ ] `onCallLayoutChanged` updates toggle group on UI thread

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

@@ -1,6 +1,6 @@
 # Call session — joinSession with no ringing (Android V5 / Views)
 
-Server-generated sessionId, both parties enter it. Customer-validated against `~/Downloads/calls-sdk/calls-sdk-android-5/samples/sample-app/src/main/kotlin/com/cometchat/samplecalls/ui/activity/CallActivity.kt`.
+Server-generated sessionId, both parties enter it. Customer-validated against `calls-sdk-android-5/samples/sample-app/src/main/kotlin/com/cometchat/samplecalls/ui/activity/CallActivity.kt`.
 
 **Read first:** `cometchat-react-calls/references/call-session.md` — cross-platform architecture (sessionId strategies, server-side authorization). Then come back here for the Android shape.
 
@@ -270,5 +270,5 @@ See `cometchat-android-v5-calls/references/share-invite.md` for full deep-link c
 - `cometchat-react-calls/references/call-session.md` — cross-platform architecture
 - `cometchat-android-v5-calls/SKILL.md` — Android V5 architecture
 - `cometchat-android-v5-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-v5-calls/references/custom-ui.md

@@ -46,7 +46,7 @@ var isAudioMuted = false
 var isVideoPaused = false
 
 btnMute.setOnClickListener {
-    if (isAudioMuted) callSession.unMuteAudio() else callSession.muteAudio()
+    if (isAudioMuted) callSession.unmuteAudio() else callSession.muteAudio()
 }
 btnVideo.setOnClickListener {
     if (isVideoPaused) callSession.resumeVideo() else callSession.pauseVideo()
@@ -98,8 +98,8 @@ callSession.addParticipantEventListener(this, object : ParticipantEventListener(
 adapter.onMuteClick = { participant -> callSession.muteParticipant(participant.uid) }
 adapter.onPauseVideoClick = { participant -> callSession.pauseParticipantVideo(participant.uid) }
 adapter.onPinClick = { participant ->
-    if (participant.isPinned) callSession.unPinParticipant()
-    else callSession.pinParticipant(participant.uid)
+    if (participant.isPinned) callSession.unpinParticipant()
+    else callSession.pinParticipant(participant.uid)  // per official docs (calls/android/participant-management)
 }
 ```
 
@@ -124,13 +124,13 @@ callSession.addLayoutListener(this, object : LayoutListener() {
 
 | Action | Method |
 |--------|--------|
-| Mute/unmute audio | `muteAudio()`, `unMuteAudio()` |
+| Mute/unmute audio | `muteAudio()`, `unmuteAudio()` |
 | Pause/resume video | `pauseVideo()`, `resumeVideo()` |
 | Switch camera | `switchCamera()` |
 | Change audio output | `setAudioMode(AudioMode)` |
 | Change layout | `setLayout(LayoutType)` |
 | Start/stop recording | `startRecording()`, `stopRecording()` |
-| Pin/unpin participant | `pinParticipant(uid)`, `unPinParticipant()` |
+| Pin/unpin participant | `pinParticipant(uid)`, `unpinParticipant()` |
 | Mute participant | `muteParticipant(uid)` |
 | Pause participant video | `pauseParticipantVideo(uid)` |
 | Leave session | `leaveSession()` |

package/skills/cometchat-android-v5-calls/references/event-listeners.md

@@ -73,11 +73,11 @@ callSession.addMediaEventsListener(this, object : MediaEventsListener() {
     override fun onVideoResumed() {}
     override fun onRecordingStarted() {}
     override fun onRecordingStopped() {}
-    override fun onScreenShareStarted() {}
-    override fun onScreenShareStopped() {}
     override fun onAudioModeChanged(audioMode: AudioMode) {}
     override fun onCameraFacingChanged(facing: CameraFacing) {}
 })
+// Screen-share is observed on ParticipantEventListener (onParticipantStartedScreenShare /
+// onParticipantStoppedScreenShare above) — NOT MediaEventsListener.
 ```
 
 ### 4. ButtonClickListener

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

@@ -1,6 +1,6 @@
 # Idle timeout on Android V5
 
-SDK API: SessionSettingsBuilder setters + listener event. ViewModel + StateFlow pattern (cf. `references/raise-hand.md`). Material AlertDialog or BottomSheet for the prompt.
+SDK API: SessionSettingsBuilder setter + listener event. ViewModel + StateFlow pattern (cf. `references/raise-hand.md`). Material AlertDialog or BottomSheet for the prompt.
 
 **Canonical docs:** https://www.cometchat.com/docs/calls/android/idle-timeout
 **Read first:** `cometchat-react-calls/references/idle-timeout.md` — settings + archetype timeouts.
@@ -10,26 +10,32 @@ SDK API: SessionSettingsBuilder setters + listener event. ViewModel + StateFlow
 ## SDK API
 
 ```kotlin
-import com.cometchat.calls.core.SessionSettingsBuilder
-import com.cometchat.calls.core.SessionType
+import com.cometchat.calls.core.CometChatCalls
+import com.cometchat.calls.model.SessionType
 
-val settings = SessionSettingsBuilder(context, callContainer)
+val settings = CometChatCalls.SessionSettingsBuilder()
   .setSessionType(SessionType.VIDEO)
-  .setIdleTimeoutPeriodBeforePrompt(60_000)
-  .setIdleTimeoutPeriodAfterPrompt(120_000)
+  .setIdleTimeoutPeriod(60)   // SECONDS (= 60s). single setter — no before/after-prompt pair. default 300
   .build()
 ```
 
-Listener — implement on `CometChatCallsEventsListener`:
+> **⚠ Unit footgun — Android takes SECONDS, not milliseconds.** `setIdleTimeoutPeriod(int)` is in **seconds** (default `300` = 5 min; docs: calls/android/idle-timeout). This differs from the **web / React Native / Angular** Calls SDK, whose `SessionSettings.idleTimeoutPeriodBeforePrompt/AfterPrompt` are in **milliseconds**. Copying a web value like `60000` here sets a ~16.7-hour timeout, not 60 seconds. Use `60` for one minute.
+
+Listener — `onSessionTimedOut()` lives on `SessionStatusListener` in v5.
+Register on the `CallSession` instance from `joinSession`'s `onSuccess`:
 
 ```kotlin
-override fun onSessionTimedOut() {
-  // Runs on background thread — dispatch to main
-  runOnUiThread {
-    Toast.makeText(this, "Call ended due to inactivity", Toast.LENGTH_LONG).show()
-    finish()  // or NavController.popBackStack()
+import com.cometchat.calls.listeners.SessionStatusListener
+
+callSession.addSessionStatusListener(this, object : SessionStatusListener() {
+  override fun onSessionTimedOut() {
+    // Runs on background thread — dispatch to main
+    runOnUiThread {
+      Toast.makeText(this@CallActivity, "Call ended due to inactivity", Toast.LENGTH_LONG).show()
+      finish()  // or NavController.popBackStack()
+    }
   }
-}
+})
 ```
 
 ---
@@ -95,7 +101,7 @@ Web sister rules + Android-specific:
 
 ## Verification checklist
 
-- [ ] SessionSettingsBuilder sets both idle periods
+- [ ] SessionSettingsBuilder sets the idle period via `setIdleTimeoutPeriod(...)`
 - [ ] `onSessionTimedOut` dispatches to main thread (`runOnUiThread` or coroutine)
 - [ ] Dialog uses `setCancelable(false)`
 - [ ] Listener attached in `onCreate`/`onResume`, detached in matching teardown

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

@@ -16,7 +16,7 @@ Add real-time text messaging during calls. Uses a CometChat Group (GUID = sessio
 - Dependencies:
   ```kotlin
   implementation("com.cometchat:chat-sdk-android:4.0.+")
-  implementation("com.cometchat:calls-sdk-android:5.0.0-beta.2")
+  implementation("com.cometchat:calls-sdk-android:5.0.+")
   implementation("com.cometchat:chat-uikit-android:4.+")
   ```