@cometchat/skills 4.4.2 → 5.0.1

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

@@ -0,0 +1,206 @@
+---
+name: cometchat-android-v5-calls-sdk
+description: "Add voice & video calling to any Android app FROM SCRATCH with the headless CometChat Calls SDK v5 (`com.cometchat:calls-sdk-android:5.0.4`) — no UI Kit. Kotlin: initFromSettings→login→generateToken→joinSession into a RelativeLayout, lifecycle-bound listeners, meet-style session rooms AND 1:1 ringing (Chat SDK v5 signaling + Calls SDK media), call logs, layouts, audio modes, recording, PiP, background service. Triggers: 'add calling from scratch android', 'standalone video call kotlin', 'headless calls sdk android', 'build my own call UI android', 'meeting room join by session id android', 'one-on-one ringing call without uikit android'."
+license: "MIT"
+compatibility: "Android minSdk >=26 (TRUE transitive floor of calls-sdk-android 5.0.x — react-native-svg declares 26; docs now agree); compileSdk >=35 (androidx.core 1.15.0 fails checkDebugAarMetadata at 34; match your androidx); Kotlin >=1.9 / AGP >=8; JVM target 11; com.cometchat:calls-sdk-android ^5 (5.0.x, verified 5.0.4). 1:1 ringing also needs com.cometchat:chat-sdk-android ^5 (5.0.5) for signaling. Kotlin (XML Views or Compose host via AndroidView)."
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat calls sdk v5 headless voice video android kotlin calling standalone"
+---
+
+> **Ground truth:** `com.cometchat:calls-sdk-android:5.0.4` + catalog `android-calls-v5.json` (the CLOSED list, `javap`-verified on the installed AAR). Docs: `/calls/android/**` = **v5** · Docs MCP. Fetch builder options, callback lists and filters from the docs (`references/docs-map.md`) — never memory. ⚠️ Where docs and AAR disagree, **the AAR wins** (drift list in `references/pitfalls.md`). **APPEND to the user's app — additive wiring only** (`RULES.md`). HEADLESS path (no UI Kit); for the prebuilt call UI use `cometchat-android-v6-calls`.
+
+## Companion skills (read first)
+- **Standalone/headless entry** — owns its own artifact (the Calls SDK), no `-core` sibling.
+- **1:1 RINGING only** also drives the **Chat SDK** (`com.cometchat:chat-sdk-android:5.0.5`) for signaling — `references/ringing.md`; deeper Chat-SDK usage: `cometchat-android-v5-sdk`.
+- **Prefer the UI Kit?** Chat + a prebuilt call UI ⇒ `cometchat-android-v6-core` + `cometchat-android-v6-calls`, not this skill.
+
+## Use this skill when
+"add calling from scratch / without the UI Kit", "standalone voice/video on Android", "build my own call screen", "headless calls SDK", "meeting room join by session id", "one-on-one ringing call". Precondition: the caller chose the **from-scratch / standalone** path (prebuilt call UI ⇒ see Companion skills).
+
+## Prerequisites & install
+```kotlin
+// settings.gradle(.kts) → dependencyResolutionManagement.repositories
+maven("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/")
+// app/build.gradle.kts
+implementation("com.cometchat:calls-sdk-android:5.0.4")    // meet-style needs ONLY this (+ the two RN lines below)
+implementation("com.cometchat:chat-sdk-android:5.0.5")     // + this for 1:1 RINGING (signaling)
+implementation("com.facebook.react:react-android:0.77.2")  // the SDK's embedded RN runtime — see "SoLoader" below
+implementation("com.facebook.soloader:soloader:0.12.1")    // (versions = what calls-sdk-android 5.0.4 pulls)
+```
+```properties
+# gradle.properties — REQUIRED for the 1:1 RINGING path (chat-sdk-android 5.0.5 still pulls android.arch.lifecycle:extensions:1.1.1 → support-compat 26.1.0)
+android.useAndroidX=true
+android.enableJetifier=true
+org.gradle.jvmargs=-Xmx4096m   # REQUIRED: Jetifier transforms the embedded react-android AAR — the AS-default -Xmx2048m OOMs (AUDIT-225)
+```
+```xml
+<!-- AndroidManifest.xml, inside <application> — REQUIRED for background handling: the AAR declares NO <service> -->
+<service android:name="com.cometchat.calls.services.CometChatOngoingCallService"
+    android:exported="false"
+    android:foregroundServiceType="camera|microphone|mediaPlayback" />
+```
+> Full error-text evidence for the four build gates below (minSdk, `<service>`, Jetifier, heap): **`references/build-truth.md`.**
+- **minSdk 26 — the manifest merge is the floor.** `calls-sdk-android:5.0.4` pulls `react-native-svg` at `minSdkVersion 26`; a 24/25 app fails `process*MainManifest`. Docs now agree (AUDIT-229) — raise `minSdk` first.
+- **The `<service>` above is REQUIRED.** The 5.0.4 AAR merges permissions only; without YOUR declaration `CometChatOngoingCallService.launch(activity)` fails **silently** (call dies on Home). Docs ship the `<service>` block (corrected upstream, verified 2026-09-09).
+- **Jetifier (ringing only).** Without `android.enableJetifier=true`, an AndroidX app + `chat-sdk-android` fails `checkDebugDuplicateClasses`. Meet-style needs none.
+- **⚠️ Gradle heap `-Xmx4096m` (MANDATORY — the FIRST build OOMs, meet-style too, AUDIT-225).** The AS-default `-Xmx2048m` OOMs Jetifier transforming the embedded `react-android` AAR; the `gradle.properties` line above fixes it.
+- **⚠️ SoLoader (MANDATORY on 5.0.x; a REQUIRED skill step — the SDK doesn't self-init on the `joinSession` path).** The call surface is an embedded React Native 0.77; without the merged-mapping init `joinSession` **crashes the process** (`UnsatisfiedLinkError: … "libhermes_executor.so" not found`). Add ONCE, first in `Application.onCreate()` (hence the two RN artifacts on YOUR compile classpath):
+  ```kotlin
+  import com.cometchat.calls.core.CometChatCalls
+  import com.facebook.react.soloader.OpenSourceMergedSoMapping
+  import com.facebook.soloader.SoLoader
+
+  SoLoader.init(this, OpenSourceMergedSoMapping)   // Application.onCreate(), BEFORE CometChatCalls.initFromSettings — idempotent
+  ```
+- **Manifest:** the AAR merges the call permissions (INTERNET, CAMERA, RECORD_AUDIO, FOREGROUND_SERVICE_*, POST_NOTIFICATIONS, …) — but NOT the `<service>` above. Java 11 `compileOptions`.
+- **Runtime permissions are YOURS to request** (API 23+): `CAMERA` + `RECORD_AUDIO` (video) / `RECORD_AUDIO` (voice) **before** `joinSession`. Denied ⇒ tell the user; never join silently muted.
+- **Credentials:** App ID · Region · Auth Key (dev only) live in the **gitignored** `app/src/main/assets/cometchat-settings.json` (same file the chat core uses; shape → `references/docs-map.md` § DOCS-GAP). Fetch via the CLI — `npx @cometchat/skills-cli@3 auth login` → `provision use --app-id <id> --json` (`@3` pins the CLI major that matches the v5 skills) — or paste from Dashboard → Credentials. Mint **auth tokens server-side** for production; never ship the Auth Key.
+
+## Init & login ordering (BAKED — invariant)
+`CometChatCalls.initFromSettings(context, listener)` resolves (`onSuccess`) → `CometChatCalls.login(uid, authKey, …)` (dev) **or** `login(authToken, …)` (prod) resolves → then `generateToken` / `joinSession` / listeners. Nothing joins before init+login resolve; before init every call fails with `ERROR_COMETCHAT_CALLS_SDK_INIT`.
+- **DEFAULT to `initFromSettings`** — the ai-agent/telemetry-attributed path (`integrationSource="ai-agent"`, parallel to `CometChat.initFromSettings`; RULES §5, AUDIT-175). It reads `assets/cometchat-settings.json` (`appId`, `region`, optional `callsSDK` hosts). **Intentionally undocumented** (`@nodoc`); the documented `CometChatCalls.init(context, CallAppSettings.CallAppSettingBuilder(...).build(), listener)` is the FALLBACK only.
+- **`authKey`** is read back out of the same asset (`credentials.authKey`) — never a second copy. Skip `login` only when `getLoggedInUser()?.uid == uid` — a DIFFERENT uid ⇒ **logout → RE-INIT → login** (`references/user-switch.md`); `!= null` alone calls as the PREVIOUS user. Init ONCE, in `Application.onCreate()`.
+```kotlin
+import com.cometchat.calls.core.CometChatCalls
+import com.cometchat.calls.exceptions.CometChatException
+import com.cometchat.calls.model.CallUser
+import org.json.JSONObject
+
+// Call from Application.onCreate(); it re-enters itself after a user-switch logout.
+fun initThenLogin(uid: String) {
+    CometChatCalls.initFromSettings(this, object : CometChatCalls.CallbackListener<String>() {   // telemetry default; init(context, CallAppSettings, …) is the doc fallback
+        override fun onSuccess(result: String) {
+            val current = CometChatCalls.getLoggedInUser()
+            if (current?.uid == uid) return                                    // SAME user — already logged in
+            if (current != null) {                                             // DIFFERENT user — NOT `!= null` → login (that calls as the PREVIOUS user)
+                CometChatCalls.logout(object : CometChatCalls.CallbackListener<String>() {
+                    // logout leaves isInitialized()==false → RE-INIT before login (ringing: CometChat.logout too — references/user-switch.md)
+                    override fun onSuccess(msg: String) = initThenLogin(uid)
+                    override fun onError(e: CometChatException) { /* surface e.code — never continue as the old user */ }
+                })
+                return
+            }
+            // dev: login(uid, authKey, l) — authKey from the SAME asset; prod: login(authToken, l), token minted server-side.
+            val authKey = JSONObject(assets.open("cometchat-settings.json").bufferedReader().readText())
+                .getJSONObject("credentials").getString("authKey")
+            CometChatCalls.login(uid, authKey, object : CometChatCalls.CallbackListener<CallUser>() {
+                override fun onSuccess(callUser: CallUser) { /* unlock calling */ }
+                override fun onError(e: CometChatException) { /* surface e.code + e.message */ }
+            })
+        }
+        override fun onError(e: CometChatException) { /* ERROR_SETTINGS_FILE_NOT_FOUND ⇒ the asset is missing */ }
+    })
+}
+initThenLogin(uid)
+```
+
+## Two build modes (BAKED — the router picks one)
+- **Meet-style (session room)** — Calls SDK ONLY: `generateToken(sessionId)` → `joinSession(token, sessionSettings, relativeLayout, …)` (or the `joinSession(sessionId, …)` overload); everyone on the same `sessionId` shares the call. No ringing.
+- **1:1 ringing** — Chat SDK signals, Calls SDK carries media (§ 1:1 ringing below — FOREGROUND-only without VoIP push).
+
+## SDK method map (BAKED closed list — from the catalog; signatures → FETCH from docs)
+- **Lifecycle (`CometChatCalls` statics):** `initFromSettings` · `init` · `isInitialized` · `login(uid, authKey, l)` / `login(authToken, l)` · `logout` · `getLoggedInUser` · `getUserAuthToken`
+- **Session:** `generateToken(sessionId, l)` → `GenerateToken.token` · `joinSession(token | sessionId, SessionSettings, RelativeLayout, l)` → `CallSession` (`startSession`/`CallSettingsBuilder` = **v4 path, do not use**) · builder `CometChatCalls.SessionSettingsBuilder()` (`setSessionType`/`setLayout`/`setAudioMode`/…, full list in the reference).
+- **Active call (`CallSession.getInstance()`):** `isSessionActive` · `leaveSession` · lifecycle-bound listeners (`addSessionStatusListener(owner, …)` + siblings) · `clearAllListeners`.
+- **Also (full enumeration → `references/method-map.md`):** In-call actions (CUSTOM controls only) · Call logs (`CallLogRequest`) · Transcription & closed captions (v5.0.4+, plan-gated) · Background (`CometChatOngoingCallService`) · Constants/enums (`SessionType`/`LayoutType`/`AudioMode`/`CometChatCallsConstants.*`).
+> A **curated highlight, NOT the full surface** — the AUTHORITATIVE closed list is the **`android-calls-v5.json` catalog** (also transcription/streaming, `CometChatCallsEventsListener`, the v4-era `CallSettingsBuilder`). A symbol is real **iff it's in the catalog**; then fetch its page via `references/docs-map.md`. **Full method map: `references/method-map.md`.**
+
+## Listener lifecycle (BAKED)
+Every `CallSession` listener takes a **`LifecycleOwner`** and is removed with it — register from `joinSession`'s `onSuccess` with the Activity/Fragment as owner; no manual remove (`clearAllListeners()` for hard resets). Still yours by hand: `CallSession.getInstance().leaveSession()` on teardown, and for ringing `CometChat.removeCallListener(ID)`.
+
+## Least-code recipe (meet-style, Kotlin Activity)
+```kotlin
+import android.Manifest
+import android.os.Bundle
+import android.view.ViewGroup
+import android.widget.RelativeLayout
+import androidx.activity.result.contract.ActivityResultContracts
+import androidx.appcompat.app.AppCompatActivity
+import com.cometchat.calls.core.CallSession
+import com.cometchat.calls.core.CometChatCalls
+import com.cometchat.calls.exceptions.CometChatException
+import com.cometchat.calls.listeners.SessionStatusListener
+import com.cometchat.calls.model.GenerateToken
+import com.cometchat.calls.model.LayoutType
+import com.cometchat.calls.model.SessionType
+
+class MeetCallActivity : AppCompatActivity() {           // init + login already resolved (Application)
+    private lateinit var callContainer: RelativeLayout
+    private val permissions = registerForActivityResult(ActivityResultContracts.RequestMultiplePermissions()) { granted ->
+        if (granted.values.all { it }) joinRoom(intent.getStringExtra("SESSION_ID") ?: "team-room")
+        else finish()                                     // tell the user — a call without mic/camera cannot start
+    }
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        // The SDK renders its ENTIRE call UI into this view — a RelativeLayout with REAL size. No external controls.
+        callContainer = RelativeLayout(this).apply {
+            layoutParams = ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT)
+        }
+        setContentView(callContainer)
+        permissions.launch(arrayOf(Manifest.permission.CAMERA, Manifest.permission.RECORD_AUDIO))
+    }
+
+    private fun joinRoom(sessionId: String) {
+        val sessionSettings = CometChatCalls.SessionSettingsBuilder()      // fetch more options from /calls/android/session-settings
+            .setSessionType(SessionType.VIDEO)                              // ⚠️ setSessionType — the docs' setType() does not exist here
+            .setLayout(LayoutType.TILE)
+            .setDisplayName("Me")
+            .setIdleTimeoutPeriod(120)                                      // alone for 2 min ⇒ onSessionTimedOut
+            .build()
+        CometChatCalls.generateToken(sessionId, object : CometChatCalls.CallbackListener<GenerateToken>() {
+            override fun onSuccess(token: GenerateToken) {
+                CometChatCalls.joinSession(token, sessionSettings, callContainer, object : CometChatCalls.CallbackListener<CallSession>() {
+                    override fun onSuccess(callSession: CallSession) {
+                        // Listeners are LIFECYCLE-BOUND (owner = this Activity) — register here, after join.
+                        callSession.addSessionStatusListener(this@MeetCallActivity, object : SessionStatusListener() {
+                            override fun onSessionLeft() { finish() }
+                            override fun onSessionTimedOut() { finish() }
+                            override fun onConnectionClosed() { finish() }
+                        })
+                    }
+                    override fun onError(e: CometChatException) { /* show e.code + e.message, then finish() */ }
+                })
+            }
+            override fun onError(e: CometChatException) { /* ERROR_AUTH_TOKEN ⇒ not logged in; show it */ }
+        })
+    }
+
+    override fun onDestroy() {
+        if (CallSession.getInstance().isSessionActive) CallSession.getInstance().leaveSession()   // never leak a live session
+        // If you called CometChatOngoingCallService.launch(...), ALSO CometChatOngoingCallService.abort(this) here —
+        // onSessionLeft is NOT delivered on Activity destroy (BACK), so callback-only abort leaks the FGS (AUDIT-227).
+        super.onDestroy()
+    }
+}
+```
+Compose host: the same code inside `AndroidView(factory = { RelativeLayout(it) })` filling `Modifier.fillMaxSize()`; declare the Activity with `configChanges` (Rotation pitfall, `references/pitfalls.md`).
+
+## 1:1 ringing (Chat SDK signaling + Calls SDK media)
+Register the `CallListener` **once, globally** (`Application.onCreate`, after `CometChat.initFromSettings` + `CometChat.login` — the `cometchat-android-v5-sdk` recipe) so the callee rings from any screen **of a FOREGROUND app**. Full recipe (both roles, Kotlin) + the ringing prerequisites: **`references/ringing.md`** — `initiateCall` → peer `onIncomingCallReceived` → `acceptCall`/`rejectCall` → `joinSession(call.sessionId)` on BOTH sides → hang-up = `leaveSession` **and** `CometChat.endCall`.
+- **Foreground-only (verified live).** In auto socket mode the Chat SDK **drops its WebSocket the instant the app is backgrounded** — a backgrounded callee never gets `onIncomingCallReceived` and a backgrounded caller never gets `onOutgoingCallAccepted` (not replayed on return). Background / killed-app ringing = the VoIP push path (`/calls/android/voip-calling`). Never promise it from this recipe. Full evidence + the caller-side reconcile (dismiss on timeout, `onResume` re-check): **`references/ringing.md`.**
+
+## Common pitfalls (BAKED)
+> One-liners here; **full evidence + reasoning for every one — see `references/pitfalls.md`.** minSdk-26 floor + missing `<service>` are in Prerequisites (evidence: `references/build-truth.md`).
+- **Don't duplicate the built-in call controls (the #1 mistake).** `joinSession` renders a COMPLETE call UI (mute, camera, switch, audio mode, layout, participants, raise hand, recording, invite, timer, red leave) into your `RelativeLayout` — no custom control row unless the ask is "replace the controls" (then `hideControlPanel(true)` FIRST).
+- **Docs ≠ AAR (verified vs 5.0.4):** `setType`→`setSessionType` · `unMuteAudio`→`unmuteAudio` · `unPinParticipant`→`unpinParticipant` · `pinParticipant(uid)`→`(uid, pid)` · `MediaEventsListener.onScreenShareStarted/Stopped` don't exist (they're on `ParticipantEventListener`) · `raiseHand`/`setLayout`/`startRecording` are no-ops. Per-page notes: `references/docs-map.md`.
+- **Wrong container** — `joinSession` needs a real-sized `RelativeLayout`; `wrap_content`/zero size renders invisibly (`ERROR_CALLING_VIEW_REF_NULL` if null).
+- **`joinSession` crashes `libhermes_executor.so not found`** — SoLoader merged-mapping init missing; see Prerequisites § SoLoader.
+- **Joining before init+login resolve** — `ERROR_COMETCHAT_CALLS_SDK_INIT` / `ERROR_AUTH_TOKEN`; chain off the callbacks.
+- **`ERROR_COMETCHAT_CALLS_SDK_INIT` after a user switch is MISLEADING** (AUDIT-194) — re-init between logout and login: `references/user-switch.md`.
+- **No runtime permissions** — the call joins with a dead mic/camera; request `CAMERA` + `RECORD_AUDIO` first.
+- **Listeners registered before join** — register in `joinSession`'s `onSuccess` with a `LifecycleOwner`.
+- **Hang-up on one SDK only (ringing)** — `leaveSession` without `CometChat.endCall` leaves the peer in-call; do both.
+- **Android can't START screen share** (receive-only), and has **no virtual-background page** — don't promise either.
+- **Rotation / Home kill the call** — `configChanges` (+ `supportsPictureInPicture`); keep alive with `CometChatOngoingCallService.launch(activity)` (needs the `<service>`).
+- **Ongoing-call service LEAKS if you only `.abort` in `onSessionLeft` (AUDIT-227)** — also `CometChatOngoingCallService.abort(this)` in `onDestroy`; abort on EVERY teardown path.
+- **No-op in-call actions (5.0.4 SDK bug, AUDIT-187):** `raiseHand`/`lowerHand`, mid-call `setLayout`, `startRecording`/`stopRecording` — no effect/callback/error; prefer the SDK's own buttons.
+- **Backgrounded apps do not ring and do not hear the accept** — foreground only; VoIP push for the rest (§ 1:1 ringing).
+- **Mixing majors** — Calls SDK is **5.x** (`joinSession`); `startSession`/`CallSettingsBuilder` + `/calls/v4/android` are the OLD tree.
+
+## Verify it works
+- **Tier-1 catalog:** every emitted symbol is in `android-calls-v5.json` (`node test-suite/scripts/verify-catalog.mjs`).
+- **Tier-2 fences:** the Kotlin compiles against the installed `calls-sdk-android:5.0.4` (`npm run verify:fences:android-v6`); your app builds at `minSdk 26` (the manifest merge is the floor check).
+- **Tier-3 device:** `./gradlew :app:assembleDebug` (at `minSdk 26`), then on an emulator/device: grant mic+camera → `joinSession` shows the SDK call surface with its own controls → a second device on the same `sessionId` appears as a tile → Home shows the ongoing-call notification (the `<service>` works) → leave ends cleanly (`onSessionLeft`). Ringing: two devices/users, BOTH apps FOREGROUND — accept joins both, hang-up ends both; then background the callee and confirm your outgoing UI times out cleanly (no callback comes). The pack's reviewer proves the round-trip via `CallsSmokeTests`.

package/skills/cometchat-android-v5-calls-sdk/references/build-truth.md

@@ -0,0 +1,63 @@
+# Build-truth prerequisites — the evidence behind `SKILL.md` § Prerequisites (calls-sdk-android 5.0.4)
+
+> Every floor and manifest line in `SKILL.md` was MEASURED on a real build/run (2026-09-07, emulator-5554, AGP 8.9.1,
+> Gradle 8.11.1, Kotlin 2.1.20), not copied from the docs (`RULES.md` §2 build-truth). This file keeps the full error
+> texts so a failing build is searchable; `SKILL.md` keeps the one-liners.
+
+## minSdk 26 — the manifest merge decides (AUDIT-183 · DOCS-BACKLOG C11)
+- `/calls/android/overview` says "Minimum SDK: API Level 24". A 24 app fails at `:app:processDebugMainManifest`:
+  `uses-sdk:minSdkVersion 24 cannot be smaller than version 26 declared in library
+  [com.facebook.react:react-native-svg:15.11.2-cometchat-21164567]` — pulled transitively by `calls-sdk-android:5.0.4`.
+- Fix: `minSdk = 26` in `app/build.gradle(.kts)`. Verified: BUILD SUCCESSFUL, resolved `calls-sdk-android 5.0.4`,
+  `react-android 0.77.2`, `soloader 0.12.1`.
+
+## `<service>` for `CometChatOngoingCallService` — the AAR declares none (AUDIT-184 · DOCS-BACKLOG C12)
+- The 5.0.4 AAR `AndroidManifest.xml` carries permissions only (`INTERNET`, `CAMERA`, `RECORD_AUDIO`,
+  `MODIFY_AUDIO_SETTINGS`, `BLUETOOTH`, `FOREGROUND_SERVICE`, `FOREGROUND_SERVICE_MEDIA_PLAYBACK|MICROPHONE|CAMERA`,
+  `POST_NOTIFICATIONS`). `/calls/android/background-handling` says "add the required permissions and service
+  declaration" but its XML block has NO `<service>` element.
+- Without it `CometChatOngoingCallService.launch(activity)` in `onSessionJoined` logs
+  `ActivityManager: Unable to start service Intent { cmp=<app>/com.cometchat.calls.services.CometChatOngoingCallService } : not found`
+  — no exception, no callback, no foreground service, no ongoing notification; the call is unprotected on Home.
+- Fix (inside `<application>`):
+  ```xml
+  <service android:name="com.cometchat.calls.services.CometChatOngoingCallService"
+      android:exported="false"
+      android:foregroundServiceType="camera|microphone|mediaPlayback" />
+  ```
+  `foregroundServiceType` matches what the SDK passes to `startForeground(id, n, 194)` on API 34+
+  (`javap`: `194 = camera|microphone|mediaPlayback`). Verified live: `dumpsys activity services` →
+  `ServiceRecord{… CometChatOngoingCallService} isForeground=true types=0xC2` + the ongoing notification on channel
+  `CometChat_Call_Ongoing_Conference` (category call, ONGOING|NO_CLEAR); ActivityManager "Background started FGS: Allowed".
+
+## Jetifier for the ringing path (`chat-sdk-android`) (AUDIT-185)
+- `chat-sdk-android:5.0.5 → android.arch.lifecycle:extensions:1.1.1 → com.android.support:support-compat/support-fragment
+  26.1.0` (`./gradlew :app:dependencyInsight --dependency support-compat`). An AndroidX app then fails
+  `checkDebugDuplicateClasses`: `Duplicate class android.support.v4.app.INotificationSideChannel … found in modules
+  androidx.core:core:1.15.0 and com.android.support:support-compat:26.1.0` (×10).
+- Fix: `gradle.properties` → `android.useAndroidX=true` + `android.enableJetifier=true` (or an `exclude` of
+  `android.arch.lifecycle`). Verified: removing the line reproduces the failure; with it, chat-sdk 5.0.5 + calls-sdk 5.0.4
+  build together. Meet-style (Calls SDK only) does not need it.
+
+## SoLoader merged mapping (AUDIT-179 · DOCS-BACKLOG C10)
+- The SDK's call surface is an embedded React Native 0.77.2 whose merged `libreactnative.so` resolves `hermes_executor`
+  only through `SoLoader.init(ctx, OpenSourceMergedSoMapping)`; the published 5.0.4 classes never call it. First
+  `joinSession` → `UnsatisfiedLinkError: dlopen failed: library "libhermes_executor.so" not found` (process dies).
+- Fix: `SoLoader.init(this, OpenSourceMergedSoMapping)` first in `Application.onCreate()` with
+  `com.facebook.react:react-android:0.77.2` + `com.facebook.soloader:soloader:0.12.1` on the compile classpath.
+
+## How to re-measure on the next SDK bump
+`./gradlew :app:processDebugMainManifest` at the claimed `minSdk` (floor) · unzip the AAR and read its
+`AndroidManifest.xml` (undeclared components) · `dependencyInsight --dependency support-compat` (legacy transitives) ·
+join a session, press Home, `dumpsys activity services` (the service is real) · two clients for peer-visible actions.
+
+## Gradle heap `-Xmx4096m` — Jetifier OOMs the AS default (AUDIT-225)
+- A brand-new project ships `org.gradle.jvmargs=-Xmx2048m`. Jetifier transforming the embedded
+  `react-android:0.77.2` AAR (pulled by `calls-sdk-android` for the RN call surface) exceeds 2 GB →
+  the FIRST `assembleDebug` fails: `Failed to transform react-android-0.77.2-debug.aar
+  (com.facebook.react:react-android:0.77.2) … Execution failed for JetifyTransform … Java heap space`.
+- Applies to the MEET-STYLE path too (the RN AAR is on the classpath regardless of ringing). This is
+  NOT a docs bug — no docs page ships a from-scratch Gradle file — so the skill carries it.
+- Fix: `org.gradle.jvmargs=-Xmx4096m` in `gradle.properties` (the pack's own harness uses this;
+  `android.nonTransitiveRClass=true` also helps). Verified: `-Xmx2048m` reproduces the OOM,
+  `-Xmx4096m` builds. compileSdk floor is 35 (androidx.core 1.15.0 fails `checkDebugAarMetadata` at 34, AUDIT-226).

package/skills/cometchat-android-v5-calls-sdk/references/docs-map.md

@@ -0,0 +1,119 @@
+# docs-map — CometChat Calls SDK v5 (Android, headless): intent → the exact docs page to fetch
+
+## Reaching docs — PREFER the CometChat docs MCP; fetch is the fallback
+The canonical doc channel is the **first-party CometChat docs MCP** — tools `search_cometchat_docs`,
+`fetch_cometchat_doc_page`, and `get_cometchat_implementation_bundle`. **If those tools are connected,
+use them instead of a raw web fetch:**
+- **Find the page** → `search_cometchat_docs(query)` — e.g. `search_cometchat_docs("calls android join session")`.
+- **Read the page** → `fetch_cometchat_doc_page(path)` — pass the SAME `<path>` the tables below list; the MCP
+  resolves the `.md` twin and returns raw Markdown (read the **Kotlin** tab). A full `https://…/<path>` URL also works.
+- **A whole feature/recipe** → `get_cometchat_implementation_bundle(...)` is **NON-AUTHORITATIVE** — curated
+  STATIC recipes that can lag the live docs. Treat any bundle as a hint only: RECONCILE it against the
+  `fetch_cometchat_doc_page` result + the catalog; never emit bundle code verbatim.
+
+**If the MCP tools are NOT connected:** add it (`claude mcp add --transport http cometchat-docs https://mcp.cometchat.com/mcp`, or reinstall/enable the plugin) and retry; only if it still will not connect, fall back to a plain fetch via `DOCS_BASE` (defined next).
+Either way the `<path>` catalog in this file is the source of truth for WHICH page — MCP-vs-fetch is only HOW.
+
+## DOCS_BASE — the fetch FALLBACK entry point (⚠️ SWAP HERE to change environments)
+```
+DOCS_BASE = https://www.cometchat.com/docs
+```
+> Production docs (`https://www.cometchat.com/docs`). **Fetch rule:** build a URL as `DOCS_BASE` + the path shown,
+> then append `.md`. Never hardcode a host anywhere else; never decompile the AAR for signatures (the pack's
+> catalog already did — `android-calls-v5.json` is the closed list).
+
+## The convention — Calls v5 lives at the UNVERSIONED root `/calls/android/`
+```
+Fetch:  {DOCS_BASE}/calls/android/overview.md
+```
+> **⚠️ VERSION TRAP.** The **unversioned** `/calls/android/**` tree IS **v5** (matches the installed
+> `calls-sdk-android:5.0.x`). `/calls/v4/android/**` is the OLD v4 SDK (`startSession` / `CallSettingsBuilder`) —
+> never fetch it for a v5 build. The UI-Kit calling pages (`/ui-kit/android/calling-integration`, `call-buttons`,
+> `incoming-call`…) belong to `cometchat-android-v6-calls`, not this skill.
+> **⚠️ MISSING PAGES return the docs HOME page, not a 404**: `/calls/android/permissions` and
+> `/calls/android/virtual-background` do NOT exist — a fetched page whose first heading is `# Home` is a miss.
+
+## Scoped index (prefer over the global llms.txt)
+```
+{DOCS_BASE}/llms.txt
+```
+Use it to discover any page not listed below (search for `/calls/android/`).
+
+## Path catalog — intent → page (all under `/calls/android/`)
+| Intent | Path |
+|---|---|
+| SDK overview · architecture · call-flow · feature cards | `/calls/android/overview` — now correctly states minSdk **26** (`react-native-svg` transitive floor), matching the manifest merge (DOCS-BACKLOG C11 RESOLVED, AUDIT-229) |
+| Install (Gradle repo + dependency) · manifest permissions · `init` · **SoLoader Step 4** | `/calls/android/setup` — now states minSdk 26 AND documents the SoLoader `OpenSourceMergedSoMapping` init (C10 RESOLVED); documents ONLY `init(context, CallAppSettings, l)`, the skills' `initFromSettings` default is the DOCS-GAP note below. ⚠️ Its `compileOptions` shows Java **8**; the skill uses JVM 11 (both compile). NO `<service>` (C12) and NO from-scratch Gradle heap line (`-Xmx4096m`, AUDIT-225) — those stay skill-owned |
+| Login (uid + API key dev / auth token prod) · `getLoggedInUser` · `logout` · error codes | `/calls/android/authentication` |
+| `generateToken` + `joinSession` (meet-style) · container setup · error codes | `/calls/android/join-session` — ⚠️ its `SessionSettingsBuilder().setType(...)` is `setSessionType(...)` in the AAR |
+| **1:1 RINGING** — `initiateCall` · `CallListener` · accept/reject/cancel · join · **end call on BOTH SDKs** | `/calls/android/ringing` — ⚠️ FOREGROUND-only in auto socket mode (`/sdk/android/v5/connection-behaviour`: backgrounded ⇒ WebSocket dropped, no incoming/accept callbacks, no replay); background ringing = `/calls/android/voip-calling`; recipe + caller-side reconcile in `references/ringing.md` |
+| `SessionSettingsBuilder` — every option (`setSessionType`, `setLayout`, `setAudioMode`, `hide*Button`, `hideControlPanel`, `setIdleTimeoutPeriod`, `enableAutoStartRecording`, `setInitialCameraFacing`, …) | `/calls/android/session-settings` |
+| Listeners (`SessionStatus` / `ParticipantEvent` / `MediaEvents` / `ButtonClick` / `Layout`) — full callback lists | `/calls/android/events` — ⚠️ `MediaEventsListener` has NO `onScreenShareStarted/Stopped`; screen-share callbacks are on `ParticipantEventListener` |
+| In-call actions on `CallSession` (mute/pause/switch camera/layout/audio mode/record/raise hand/pin/leave) | `/calls/android/actions` — ⚠️ `unMuteAudio`/`unPinParticipant` are `unmuteAudio`/`unpinParticipant`; `pinParticipant` takes `(uid, pid)` |
+| Call layouts (TILE / SIDEBAR / SPOTLIGHT) + `LayoutListener` | `/calls/android/call-layouts` — `SessionSettingsBuilder.setLayout` at join works; ⚠️ `CallSession.setLayout()` mid-call was a NO-OP in 5.0.4 (no `onCallLayoutChanged`) |
+| Audio modes (SPEAKER / EARPIECE / BLUETOOTH / HEADPHONES) | `/calls/android/audio-modes` |
+| Recording (start/stop, auto-start, indicators, recordings on `CallLog`) | `/calls/android/recording` — ⚠️ `startRecording()` from code gave no callback and no error in 5.0.4; recording is plan-gated ("must be enabled for your app") with NO error signal on refusal |
+| **Transcription & closed captions** (auto-start, manual `startTranscription`/`stopTranscription`, `hideTranscriptionButton`/`hideClosedCaptionButton`/`setCaptionLanguage`, retrieve via `TranscriptRequest`) | `/calls/android/transcription` — **v5.0.4+**; PLAN-GATED ("must be enabled for your app"). `TranscriptRequest.TranscriptRequestBuilder().setSessionId(REQUIRED).setLimit(n).build()` → `fetchNext`/`fetchPrevious` → `List<Transcript>`; `Transcript.transcriptUrl` is a pointer to a downloadable JSON (download it yourself). A session with no transcript delivers an **empty list, not an error** (verified live, AUDIT-228) |
+| Call logs (`CallLogRequest.CallLogRequestBuilder` + filters + pagination + recordings) | `/calls/android/call-logs` |
+| Participant management (mute / pause video / pin / `Participant` fields) | `/calls/android/participant-management` |
+| Screen sharing — **receive-only on Android** (web initiates) | `/calls/android/screen-sharing` |
+| Raise hand | `/calls/android/raise-hand` — ⚠️ `CallSession.raiseHand()`/`lowerHand()` from code were a NO-OP in 5.0.4 (no `onParticipantHandRaised`, no error) — the surface's own button works (SKILL.md pitfalls) |
+| Idle timeout (`setIdleTimeoutPeriod`, `onSessionTimedOut`) | `/calls/android/idle-timeout` |
+| Share invite (`hideShareInviteButton(false)` + `onShareInviteButtonClicked` → share sheet; deep links) | `/calls/android/share-invite` |
+| Picture-in-picture (Activity PiP + `enablePictureInPictureLayout`) | `/calls/android/picture-in-picture` |
+| Background handling (`CometChatOngoingCallService.launch/abort`, `OngoingNotification`) | `/calls/android/background-handling` — the AAR declares no `<service>`, so without YOUR `<service android:name="com.cometchat.calls.services.CometChatOngoingCallService" android:exported="false" android:foregroundServiceType="camera|microphone|mediaPlayback"/>` `launch()` fails silently (SKILL.md Prerequisites). ⚠️ The docs manifest block now ships this exact `<service>` (corrected upstream, verified 2026-09-09) · its "Complete Example" uses a `RelativeLayout` container matching the real `joinSession(sessionId, SessionSettings, RelativeLayout, l)` signature |
+| Custom control panel (`hideControlPanel(true)` + your buttons → `CallSession` actions) — **explicit request only** | `/calls/android/custom-control-panel` |
+| VoIP push / receiving calls when the app is killed | `/calls/android/voip-calling` — pair with `cometchat-android-v6-push` posture: docs-first, delivery is a manual device check |
+
+## DOCS-GAP — `initFromSettings` is NOT on the live docs (bake it here)
+> **Referenced by `SKILL.md` (Init & login ordering).** `/calls/android/setup` documents ONLY
+> `CometChatCalls.init(context, CallAppSettings, listener)` — it does **not** document
+> `CometChatCalls.initFromSettings(context, CallbackListener<String>)`, even though the method is real and shipped
+> (`javap` of the installed 5.0.4 AAR: `public static void initFromSettings(Context, CallbackListener<String>)`).
+> It reads **`app/src/main/assets/cometchat-settings.json`** — the SAME gitignored file `CometChat.initFromSettings` /
+> `CometChatUIKit.initFromSettings` read, so one asset serves chat AND calls:
+> ```json
+> {
+>   "appId": "APP_ID",
+>   "region": "us",
+>   "credentials": { "authKey": "AUTH_KEY" },
+>   "callsSDK": { "host": null, "adminHost": null, "clientHost": null, "callsHost": null },
+>   "chatSDK": {},
+>   "uiKit": {}
+> }
+> ```
+> `appId` + `region` are REQUIRED (`ERROR_SETTINGS_FILE_MISSING_APPID` / `…_MISSING_REGION`); a missing asset is
+> `ERROR_SETTINGS_FILE_NOT_FOUND`; the `callsSDK` block is optional host overrides (on-prem). The skills
+> **DEFAULT to `initFromSettings`** — the **ai-agent-only telemetry init** (persists `integrationSource="ai-agent"`),
+> **INTENTIONALLY undocumented** (`@nodoc`, same posture as `CometChatUIKit.initFromSettings` — DOCS-BACKLOG F4 / C1),
+> which is WHY the shape is baked here. The publicly-documented `init(...)` is the FALLBACK only. Do NOT tell a
+> user to "fetch the shape from `/calls/android/setup`": that page does not carry it. `authKey` for the dev
+> `login(uid, authKey, l)` is read back out of `credentials.authKey` of this same asset (never a second copy).
+
+## 1:1 RINGING (meet-style needs none of this) — the signaling layer is the CHAT SDK
+Meet-style (session-id "join a room") uses ONLY the Calls SDK (`generateToken` → `joinSession`). But
+**one-on-one ringing** (call a specific user, they get an incoming prompt, accept/reject) combines the
+**Chat SDK** (`com.cometchat:chat-sdk-android:5.0.5`, `com.cometchat.chat.*`) for signaling + the Calls SDK for media.
+
+**The COMPLETE, CURRENT recipe is ONE page — fetch it directly:**
+```
+fetch_cometchat_doc_page("/calls/android/ringing")
+```
+That page (v5, Kotlin) carries the WHOLE flow, both sides: `CometChat.initiateCall(Call(uid, RECEIVER_TYPE_USER,
+CALL_TYPE_VIDEO), l)` (+ `(call, timeoutSec, l)`) → `CometChat.addCallListener(ID, object : CometChat.CallListener()
+{ onIncomingCallReceived / onOutgoingCallAccepted / onOutgoingCallRejected / onIncomingCallCancelled /
+onCallEndedMessageReceived })` → `CometChat.acceptCall(sessionId, l)` / `rejectCall(sessionId, CALL_STATUS_REJECTED |
+CALL_STATUS_CANCELLED, l)` → `CometChatCalls.joinSession(call.sessionId, …)` on BOTH sides → hang-up =
+`CallSession.getInstance().leaveSession()` **and** `CometChat.endCall(sessionId, l)` (the peer's
+`onCallEndedMessageReceived` then leaves too; without `endCall` the log is incomplete).
+> **Chat SDK init + login come first** — `CometChat.initFromSettings(context, l)` → `CometChat.login(uid, authKey, l)`
+> (the `cometchat-android-v5-sdk` recipe; same settings asset). `Call` is **`com.cometchat.chat.core.Call`**
+> (NOT `chat.models`). `CometChatException` exists in BOTH SDKs (`com.cometchat.chat.exceptions` /
+> `com.cometchat.calls.exceptions`) — alias one when a file imports both.
+> **Do NOT reach for `search_cometchat_docs("default calling")`** — search surfaces the STALE `/sdk/android/3.0/`
+> chat-SDK pages (`startCall` / `CallSettingsBuilder`, the v4 media path). `/calls/android/ringing` is the
+> canonical v5 source; reconcile any Chat-SDK symbol against `sdk-android-v5.json` before emitting.
+
+> **⚠️ Testing 1:1 ringing needs TWO live clients** — two devices/emulators, two different users, each logged in
+> with the global `CallListener` registered **and the app in the FOREGROUND** (auto socket mode drops the WebSocket in background). The caller always shows ringing locally; that proves nothing about
+> the callee. This is a two-client protocol, not a bug.

package/skills/cometchat-android-v5-calls-sdk/references/method-map.md

@@ -0,0 +1,53 @@
+# SDK method map — full curated highlight (calls-sdk-android 5.0.4, headless)
+
+> `SKILL.md` § SDK method map keeps the spine (Lifecycle · Session · Active call + the catalog note);
+> this file carries the full per-category enumeration. The **AUTHORITATIVE** closed list is still the
+> **`android-calls-v5.json` catalog** (also transcription/streaming, `CometChatCallsEventsListener`, the
+> v4-era `CallSettingsBuilder`). A symbol is real **iff it's in the catalog**; then fetch its page via
+> `references/docs-map.md`. Signatures → FETCH from docs, never memory.
+
+## Lifecycle (`CometChatCalls` statics)
+`initFromSettings` · `init` · `isInitialized` · `login(uid, authKey, l)` / `login(authToken, l)` · `logout` ·
+`getLoggedInUser` · `getUserAuthToken`
+
+## Session
+- `generateToken(sessionId, l)` → `GenerateToken.token`
+- `joinSession(token | sessionId, SessionSettings, RelativeLayout, l)` → `CallSession`
+  (`startSession`/`CallSettingsBuilder` = **v4 path, do not use**)
+- `CometChatCalls.SessionSettingsBuilder()`: `setSessionType(SessionType.VIDEO|VOICE)` ·
+  `setLayout(LayoutType.TILE|SIDEBAR|SPOTLIGHT)` · `setDisplayName` · `setTitle` · `setAudioMode(AudioMode.*)` ·
+  `setIdleTimeoutPeriod(sec)` · `startAudioMuted`/`startVideoPaused` · `setInitialCameraFacing` ·
+  `enableAutoStartRecording` · `hideControlPanel`/`hideHeaderPanel`/`hide<Button>`
+  (full list: `/calls/android/session-settings`)
+
+## Active call (`CallSession.getInstance()`)
+`isSessionActive` · `leaveSession` · lifecycle-bound listeners `addSessionStatusListener(owner, …)` /
+`addParticipantEventListener` / `addMediaEventsListener` / `addButtonClickListener` / `addLayoutListener` ·
+`clearAllListeners`
+
+## In-call actions
+⚠️ **CUSTOM controls ONLY; the joined surface already renders them** (pitfall #1; `hideControlPanel(true)` first):
+`muteAudio`/`unmuteAudio` · `pauseVideo`/`resumeVideo` · `switchCamera` · `setAudioMode` · `muteParticipant(uid)` ·
+`pauseParticipantVideo(uid)` · `pinParticipant(uid, pid)`/`unpinParticipant()` ·
+`enablePictureInPictureLayout`/`disablePictureInPictureLayout` · ⚠️ `setLayout` · `startRecording`/`stopRecording` ·
+`raiseHand`/`lowerHand` — real symbols, **no-ops in 5.0.4** (see `references/pitfalls.md`).
+
+## Call logs
+`CallLogRequest.CallLogRequestBuilder().setLimit(n)…build()` → `fetchNext(l)` / `fetchPrevious(l)` →
+`List<CallLog>` (`getRecordings()` → `Recording.recordingURL`).
+
+## Transcription & closed captions (v5.0.4+; PLAN-GATED)
+- builder: `enableAutoStartTranscription`/`hideTranscriptionButton`/`hideClosedCaptionButton`/`setCaptionLanguage`
+- mid-call: `CallSession…startTranscription()`/`stopTranscription()`
+- retrieve: `TranscriptRequest.TranscriptRequestBuilder().setSessionId(sid)…build()` → `fetchNext` →
+  `List<Transcript>` (`.transcriptUrl` = downloadable JSON; empty≠error). Full row: `references/docs-map.md`.
+
+## Background
+`CometChatOngoingCallService.launch(activity)` / `.abort(activity)` (foreground service + ongoing notification;
+`OngoingNotification.buildOngoingConferenceNotification(n)` to brand it) — **`.abort` on EVERY teardown path incl.
+`onDestroy`, not only `onSessionLeft`** (BACK destroys the owner before the callback → FGS + notification leak,
+AUDIT-227; see the Rotation pitfall in `references/pitfalls.md`).
+
+## Constants/enums
+`SessionType` · `LayoutType` · `AudioMode` · `CameraFacing` · `CometChatCallsConstants.CALL_STATUS_*` /
+`CALL_TYPE_*` / `RECEIVER_TYPE_*`

package/skills/cometchat-android-v5-calls-sdk/references/pitfalls.md

@@ -0,0 +1,72 @@
+# Common pitfalls — full detail (calls-sdk-android 5.0.4, headless)
+
+> The one-liners live in `SKILL.md` § Common pitfalls; this file keeps the FULL evidence and reasoning
+> so a symptom is searchable. minSdk-26 floor and the missing `<service>` are covered in
+> `SKILL.md` § Prerequisites (evidence in `references/build-truth.md`).
+
+## Don't duplicate the built-in call controls (the #1 mistake)
+`joinSession` renders a COMPLETE call UI — mute, camera, switch camera, audio mode, layout, participants,
+raise hand, recording, share invite, timer and the red leave button — into your `RelativeLayout`. Do **NOT**
+add your own control row; the custom-control-panel page is for an explicit "replace the controls" ask
+(then `hideControlPanel(true)` FIRST).
+
+## Docs ≠ AAR (verified vs 5.0.4 — the compiler and the device are right)
+Per-page notes are in `references/docs-map.md`. Confirmed drifts:
+- `setType(...)` → **`setSessionType`**
+- `unMuteAudio` → **`unmuteAudio`**
+- `unPinParticipant` → **`unpinParticipant`**
+- `pinParticipant(uid)` → **`(uid, pid)`**
+- `MediaEventsListener.onScreenShareStarted/Stopped` **do not exist** (screen-share events are on `ParticipantEventListener`)
+- background-handling's named-arg `joinSession(view=FrameLayout, context=…)` **does not exist**
+- `raiseHand`/`setLayout`/`startRecording` **no-ops** (see below).
+
+The docs now state minSdk 26 + document SoLoader (AUDIT-229).
+
+## Wrong container
+`joinSession` needs a `RelativeLayout`; `wrap_content` or zero size renders the call invisibly
+(`ERROR_CALLING_VIEW_REF_NULL` if null).
+
+## `joinSession` crashes with `libhermes_executor.so not found`
+The SoLoader merged-mapping init is missing; see `SKILL.md` § Prerequisites § SoLoader.
+
+## Joining before init+login resolve
+`ERROR_COMETCHAT_CALLS_SDK_INIT` / `ERROR_AUTH_TOKEN`; always chain off the callbacks.
+
+## `ERROR_COMETCHAT_CALLS_SDK_INIT` after a user switch is MISLEADING (AUDIT-194)
+`logout()` — and the implicit one inside `login(<other uid>)` — leaves `isInitialized()==false` though `login`
+reports `onSuccess`; `generateToken` then fails naming the wrong cause. **Re-init between logout and login:**
+`references/user-switch.md`.
+
+## No runtime permissions
+The call joins with a dead mic/camera; request `CAMERA` + `RECORD_AUDIO` first (the AAR only DECLARES them).
+
+## Listeners registered before join
+No live session yet; register in `joinSession`'s `onSuccess` with a `LifecycleOwner`.
+
+## Hang-up on one SDK only (ringing)
+`leaveSession` without `CometChat.endCall` leaves the peer in-call and the log incomplete; do both.
+
+## Android can't START screen share (receive-only)
+And has **no virtual-background page** — don't promise either.
+
+## Rotation / Home kill the call
+Add `configChanges` (+ `supportsPictureInPicture` for PiP); keep it alive with
+`CometChatOngoingCallService.launch(activity)` in `onSessionJoined` — **needs the `<service>` from Prerequisites**
+(else `launch` fails silently); PiP = `enterPictureInPictureMode` + `enablePictureInPictureLayout`.
+
+## Ongoing-call service LEAKS if you only `.abort` in `onSessionLeft` (AUDIT-227, verified live)
+BACK destroys the Activity → `onSessionLeft` is **not delivered** to the destroyed `LifecycleOwner`, so `.abort`
+never fires and the FGS + ongoing notification survive with NO call. **Also `CometChatOngoingCallService.abort(this)`
+in `onDestroy`** (idempotent) — abort on EVERY teardown path.
+
+## No-op in-call actions (5.0.4, live two-participant test — SDK bug, AUDIT-187)
+`raiseHand`/`lowerHand`, `setLayout(...)` mid-call and `startRecording`/`stopRecording` produce **no effect,
+no callback and no error**, while `muteAudio`/`pauseVideo`/`switchCamera` on the same path work. Prefer the SDK's
+OWN buttons for these; recording may also be **plan-gated with NO error signal** — confirm via
+`CallLog.getRecordings()`. STOPGAP: drop when a fixed 5.0.x ships.
+
+## Backgrounded apps do not ring and do not hear the accept
+Auto socket mode drops the WebSocket — foreground only; VoIP push for the rest (§ 1:1 ringing).
+
+## Mixing majors
+The Calls SDK is **5.x** (`joinSession`); `startSession`/`CallSettingsBuilder` and `/calls/v4/android` are the OLD tree.

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

@@ -0,0 +1,92 @@
+# 1:1 ringing — the recipe (Chat SDK v5 signaling + Calls SDK v5 media)
+
+> Loaded from `SKILL.md` § 1:1 ringing. Symbols: `sdk-android-v5.json` (Chat SDK) + `android-calls-v5.json` (Calls SDK).
+> Signatures: `references/docs-map.md` § "1:1 RINGING" → `/calls/android/ringing`. Verified live 2026-09-07
+> (calls-sdk 5.0.4 + chat-sdk 5.0.5, two processes on one emulator — both roles).
+
+## Prerequisites (on top of the meet-style ones)
+- `implementation("com.cometchat:chat-sdk-android:5.0.5")` **+ `android.enableJetifier=true`** (with
+  `android.useAndroidX=true`) in `gradle.properties` — `chat-sdk-android:5.0.5` still pulls
+  `android.arch.lifecycle:extensions:1.1.1 → com.android.support:support-compat:26.1.0`; without Jetifier an AndroidX
+  app fails `checkDebugDuplicateClasses` (`Duplicate class android.support.v4.app.INotificationSideChannel …`).
+- Chat SDK init + login FIRST — `CometChat.initFromSettings(context, l)` → `CometChat.login(uid, authKey, l)` (the
+  `cometchat-android-v5-sdk` recipe; same settings asset), THEN the Calls SDK init/login, THEN register the listener.
+  A Calls-SDK login does NOT log the Chat SDK in — check `CometChat.getLoggedInUser()` separately
+  (`initiateCall` on a chat-logged-out process fails `ERROR_USER_NOT_LOGGED_IN`).
+
+## ⚠️ Foreground-only — the caveat the docs page does not state (verified live)
+In the default **auto** socket mode the Chat SDK **disconnects its WebSocket the moment the app is backgrounded**
+(`/sdk/android/v5/connection-behaviour`: "App in background — immediately disconnected"). Consequences, all reproduced:
+- a **backgrounded CALLEE never receives `onIncomingCallReceived`** — the caller gets `onOutgoingCallRejected` when the
+  `initiateCall` timeout (default 45 s) expires;
+- a **backgrounded CALLER never receives `onOutgoingCallAccepted`**, and it is **NOT replayed** on return to the
+  foreground — an un-reconciled caller sits on "Calling…" forever.
+So "rings from any screen" means **any screen of a FOREGROUND app**. Background / killed-app ringing is the **VoIP push
+path** — `/calls/android/voip-calling` (FCM + `ConnectionService`; docs-first, real device, class-E in the pack's
+harness) — offer it explicitly instead of promising background ringing. **Manual** socket mode + `CometChat.ping()`
+within every 30 s keeps the socket alive only while the process is alive (same docs page) — not a substitute for VoIP.
+
+## Caller-side reconcile (bake it into YOUR outgoing UI)
+1. Start a timer when `initiateCall` succeeds, equal to the timeout you passed (`initiateCall(call, timeoutSec, l)`;
+   default 45 s). No `onOutgoingCallAccepted` / `onOutgoingCallRejected` by then ⇒ treat as **unanswered**: dismiss the
+   outgoing UI and cancel with `CometChat.rejectCall(sessionId, CometChatConstants.CALL_STATUS_CANCELLED, l)` so the
+   callee's prompt and the call log close cleanly.
+2. On `onResume` after the app was backgrounded mid-ring, re-check the call state (`CometChat.getActiveCall()` in the
+   Chat SDK method map) and either `joinSession(call.sessionId)` or dismiss — never rely on a replayed callback.
+3. On the callee, `onIncomingCallCancelled` dismisses the prompt; a prompt still showing after the caller's timeout is a
+   sign the listener was registered on a screen that was destroyed — register it ONCE in `Application`.
+
+## The recipe (both roles)
+`joinMedia` = the meet-style `joinRoom` in `SKILL.md`, with the call's `sessionId`, on BOTH sides.
+```kotlin
+import com.cometchat.calls.core.CallSession
+import com.cometchat.chat.constants.CometChatConstants
+import com.cometchat.chat.core.Call
+import com.cometchat.chat.core.CometChat
+import com.cometchat.chat.exceptions.CometChatException
+
+object RingingSignaling {
+    private const val LISTENER_ID = "app-call-listener"
+
+    fun register(onIncoming: (Call) -> Unit, joinMedia: (sessionId: String) -> Unit, dismiss: () -> Unit) {
+        CometChat.addCallListener(LISTENER_ID, object : CometChat.CallListener() {
+            override fun onIncomingCallReceived(call: Call) = onIncoming(call)            // show YOUR incoming UI
+            override fun onOutgoingCallAccepted(call: Call) = joinMedia(call.sessionId)  // caller joins the same session
+            override fun onOutgoingCallRejected(call: Call) = dismiss()
+            override fun onIncomingCallCancelled(call: Call) = dismiss()
+            override fun onCallEndedMessageReceived(call: Call) { CallSession.getInstance().leaveSession(); dismiss() }
+        })
+    }
+    fun unregister() = CometChat.removeCallListener(LISTENER_ID)                          // teardown
+
+    fun call(peerUid: String, onRinging: (Call) -> Unit) {                                // caller
+        val call = Call(peerUid, CometChatConstants.RECEIVER_TYPE_USER, CometChatConstants.CALL_TYPE_VIDEO)
+        CometChat.initiateCall(call, object : CometChat.CallbackListener<Call>() {        // (call, timeoutSec, l) overload exists
+            override fun onSuccess(outgoing: Call) = onRinging(outgoing)                   // show YOUR outgoing UI
+            override fun onError(e: CometChatException) { /* e.code + e.message */ }
+        })
+    }
+    fun accept(sessionId: String, joinMedia: (String) -> Unit) {                          // callee
+        CometChat.acceptCall(sessionId, object : CometChat.CallbackListener<Call>() {
+            override fun onSuccess(call: Call) = joinMedia(call.sessionId)
+            override fun onError(e: CometChatException) { /* e.code + e.message */ }
+        })
+    }
+    fun reject(sessionId: String) {                                                       // callee (caller cancels with CALL_STATUS_CANCELLED)
+        CometChat.rejectCall(sessionId, CometChatConstants.CALL_STATUS_REJECTED, object : CometChat.CallbackListener<Call>() {
+            override fun onSuccess(call: Call) {}
+            override fun onError(e: CometChatException) { /* e.code + e.message */ }
+        })
+    }
+    fun hangUp(sessionId: String) {                                                       // either side — BOTH SDKs
+        CallSession.getInstance().leaveSession()                                          // Calls SDK: leave media
+        CometChat.endCall(sessionId, object : CometChat.CallbackListener<Call>() {        // Chat SDK: peer gets onCallEndedMessageReceived + the log completes
+            override fun onSuccess(call: Call) {}
+            override fun onError(e: CometChatException) { /* e.code + e.message */ }
+        })
+    }
+}
+```
+> **Testing ringing needs TWO live clients and two users**, each logged in (Chat SDK AND Calls SDK) with the listener
+> registered and the app in the FOREGROUND — the caller's ringing UI alone proves nothing. Two processes on one emulator
+> (two `applicationId`s / build types) work when a second device is unavailable.