@cometchat/skills 4.4.2 → 5.0.1

package/skills/cometchat-android-v6-core/references/setup-credentials.md

@@ -0,0 +1,105 @@
+# setup-credentials — detect, credentials, authorize (Android v6)
+
+> Ground truth: `ui-kit/android/getting-started-kotlin.md` + `getting-started-jetpack.md` + installed `chatuikit-core-android` 6.0.5 `CometChatUIKit.initFromSettings` + catalog `android-v6.json`, verified 2026-08-20.
+
+## 1. Detect project (gradle / cohort)
+- Confirm it's an Android project: `settings.gradle` or `settings.gradle.kts` exists (plus an app module with `build.gradle(.kts)`).
+- **Cohort** (decides which ONE kit artifact to install — never both):
+  - **Compose** → the app module's `build.gradle(.kts)` mentions `androidx.compose` or `buildFeatures { compose = true }` (or the `kotlin.compose` plugin) → `com.cometchat:chatuikit-compose-android:6.0.5`
+  - **Views** → otherwise (XML layouts / `viewBinding`) → `com.cometchat:chatuikit-kotlin-android:6.0.5`
+- Get the cohort from `npx @cometchat/skills detect --json` (`android_variant`, per RULES.md) or by
+  reading the gradle files yourself. Confirm against the gradle file if ambiguous (a hybrid app hosting Compose in Views counts as Compose only if chat screens will be composables; ASK if unclear).
+- Kit prerequisites (both cohorts): API 28+ target samples; `jvmTarget "11"`; Views additionally `viewBinding = true`, Compose `compose = true`.
+
+## 2. Config reuse — don't re-ask
+A prior `.cometchat/config.json` (written by the CometChat CLI), an existing `app/src/main/assets/cometchat-settings.json`, or `COMETCHAT_*` entries in `local.properties` → reuse them, skip re-setup, don't re-provision or re-ask.
+
+## 3. version_conflict — STOP gate
+If ANY module declares a non-v6 CometChat UI Kit — `com.cometchat:chat-uikit-android` at 5.x/4.x (the old artifact name), or a mixed 5.x `chatuikit-*` — STOP. Surface it, reconcile (upgrade to v6 via `upgrading-from-v5`, or load matching-version skills), then continue. Never mix majors, and never install both `chatuikit-kotlin-android` and `chatuikit-compose-android` in one app (duplicate classes + doubled resources).
+
+## 4. Env — the PRIMARY credential file is `assets/cometchat-settings.json` (read by `initFromSettings`)
+The skill writes the app's credentials into a **gitignored** `app/src/main/assets/cometchat-settings.json` — the file `CometChatUIKit.initFromSettings(context, callback)` reads (it also persists `integrationSource="ai-agent"` for telemetry; `lifecycle.md`):
+```json
+{
+  "appId": "your_app_id",
+  "region": "us",
+  "credentials": { "authKey": "your_auth_key" },
+  "uiKit": { "subscribePresenceForAllUsers": true, "enableCalling": false }
+}
+```
+- `appId` + `region` are REQUIRED (`ERR_SETTINGS_INVALID` otherwise); a missing file fails init with `ERR_SETTINGS_FILE_NOT_FOUND`.
+- `credentials.authKey` is **dev only** — for prod builds OMIT it (login uses a server-minted auth token; `appId`/`region` are not secrets).
+- `uiKit.enableCalling: true` auto-inits the Calls SDK (see `cometchat-android-v6-calls`); default false.
+- **Gitignore it** — append `app/src/main/assets/cometchat-settings.json` to `.gitignore` (it carries the dev Auth Key) and never echo the key back to the user.
+
+**Build-time extras only — `local.properties` → `BuildConfig`.** For non-credential values the app CODE reads at build time (e.g. a default demo UID), use the standard Android pattern (this is NOT the init credential path):
+```properties
+# local.properties (gitignored by Android Studio — verify)
+COMETCHAT_DEMO_UID=cometchat-uid-1
+```
+```kotlin
+// app module build.gradle.kts
+import java.util.Properties
+val localProps = Properties().apply {
+    val f = rootProject.file("local.properties")
+    if (f.exists()) f.inputStream().use { load(it) }
+}
+android {
+    buildFeatures { buildConfig = true }   // required for buildConfigField to emit
+    defaultConfig {
+        buildConfigField("String", "COMETCHAT_DEMO_UID",
+            "\"${localProps.getProperty("COMETCHAT_DEMO_UID", "")}\"")
+    }
+}
+```
+Groovy variant, briefly: `def p = new Properties(); rootProject.file('local.properties').withInputStream { p.load(it) }` then `buildConfigField 'String', 'COMETCHAT_DEMO_UID', "\"${p.getProperty('COMETCHAT_DEMO_UID', '')}\""` inside `defaultConfig` (+ `buildFeatures { buildConfig true }`). Code reads `BuildConfig.COMETCHAT_DEMO_UID` — never a hardcoded literal.
+
+## 5. Credentials — fetch from the dashboard (offer it), or paste manually
+> **The CLI is a DASHBOARD/API client only, loaded ON DEMAND.** It does `auth` (dashboard login), `provision` (fetch App ID/Region/Auth Key), and `config` (local cred state). It knows NOTHING about Gradle/Android and does NOT write the settings JSON or any gradle file — **the SKILL owns detection (§1) and env-writing (§4).**
+
+> **OFFER the dashboard fetch; don't default to manual paste.** When credentials are missing, present BOTH paths and default to the fetch: *"I can fetch your App ID / Region / Auth Key by logging into your CometChat dashboard (I'll load the CometChat CLI to do it), or you can paste them manually — which do you prefer?"* Never silently skip to "paste them yourself," and never end the build with an "add credentials manually" TODO.
+
+**The CLI:** `<cli>` = `npx @cometchat/skills-cli@3` (public npm — no auth needed; `@3` pins the CLI major that matches the v5 skills).
+
+**Fetch path (user opted in).** Let each command block — don't background or race them.
+1. `<cli> auth status --json` → `logged-in` | `logged-out`.
+2. If logged-out: `<cli> auth login` — opens the dashboard (device-auth), polls, stores the bearer in the OS keychain. Surface errors verbatim (`ACCESS_DENIED`/`EXPIRED`/`TIMEOUT`/`ABORTED`) and stop.
+3. Pick the app — REUSE first, ASK with CURATED options, never auto-create: `<cli> provision list --json`, then present at most 4 selectable options — the top 3 most relevant apps (name · region · App ID) + "Show all N apps"; free-text = "I'll paste an App ID manually". NEVER dump all N apps; NEVER create an app unasked (zero apps → ask before creating).
+4. `<cli> provision use --app-id "<id>" --json` → returns `{ appId, region, authKey }` and writes a framework-neutral `.cometchat/config.json`. It does NOT write the settings JSON — that's §4, the skill's job. Treat the Auth Key as a secret.
+
+**Manual path** (user prefers, or the CLI can't run): Dashboard → Your App → Credentials → App ID, Region (`us`/`eu`/`in`), Auth Key (**dev only**). If neither path yields them, ASK and WAIT — never proceed with placeholders.
+
+**Then the SKILL writes `assets/cometchat-settings.json` (§4)** from the config.json / returned creds and gitignores it. The CLI stops at "here are your credentials." Dashboard-gated features (`<cli> features list` / `features enable <id>`) work the same way — the CLI flips the dashboard toggle; you still wire the client component.
+
+## 6. Authorize / verify
+Credentials are valid when `CometChatUIKit.initFromSettings(...)` hits `onSuccess` and `CometChatUIKit.login(uid, ...)` succeeds for a UID that exists (§7). `ERR_SETTINGS_FILE_NOT_FOUND` → the assets JSON is missing; `ERR_SETTINGS_INVALID` → `appId`/`region` missing in it; other auth errors → most commonly a **Region mismatch**. Do not render chat UI until login resolves (`lifecycle.md`).
+
+## 7. Which user to log in as (the login UID) — do NOT invent one
+`login(uid, callback)` authenticates a user that **must already exist** in your CometChat app; it does **not** create one. Logging in a missing UID fails (`ERR_UID_NOT_FOUND`) and the screen stays blank.
+- **Never suggest a legacy/guessed sample UID** (`superhero1`, `cc-user-*`, etc. are NOT seeded in modern apps). The ONLY tentative suggestion is `cometchat-uid-1..5`, labelled *"if this is a freshly-created app"* — fresh apps are pre-seeded with `cometchat-uid-1`…`cometchat-uid-5` (the docs samples log in as `cometchat-uid-1`).
+- **Use a real UID:** Dashboard → your app → **Users** tab lists every UID. ASK the user; prefer their answer over any suggestion.
+- **Create one (dev):** Dashboard → Users → Add User, or `CometChatUIKit.createUser(user, callback)` (uses the init Auth Key; dev only) — fetch exact shapes from docs if you need programmatic creation.
+- **Production:** never the Auth Key, never a hardcoded UID. Per real end-user, create a matching CometChat user server-side (REST API + API key), mint a per-user **auth token** from your backend, and log in with `CometChatUIKit.loginWithAuthToken(authToken, callback)` (`lifecycle.md`).
+
+## §1a — Cohort selection (the first decision, and the least reversible)
+
+Score STRUCTURAL signals, not a loose `/compose/` text match (it matches "composer", the kit's
+own artifact name), and read BOTH
+Groovy and Kotlin DSL (`build.gradle` **and** `build.gradle.kts` — an earlier version read only the
+Groovy names and returned `framework: null` for every Kotlin-DSL project).
+
+| `android_variant` | Signals that produced it | Action |
+|---|---|---|
+| `compose` | `buildFeatures { compose = true }`, `org.jetbrains.kotlin.plugin.compose`, `androidx.compose.*`, `compose-bom` — and no Views signal | Use **Compose** (`…-compose-*`). Do not ask; do not offer Views. Emitting XML into a Compose app is a defect. |
+| `views` | `viewBinding`/`dataBinding` enabled, or `app/src/main/res/layout/` exists — and no Compose signal | Use **Views** (`…-kotlin-*`). |
+| `mixed` | both sets present — typically an app mid-migration | **ASK and WAIT.** Say what you found: "your app has both Compose and XML screens — the chat screens can be either." Never pick silently. |
+| `unknown` | neither (new/empty project) | **ASK and WAIT**, with a recommendation: Compose for greenfield, Views if the team's existing screens are XML. |
+
+`android_cohort_signals: { composeHits, viewsHits }` is returned so you can SHOW the evidence
+("I detected Compose: compose plugin + compose-bom, no XML layouts").
+
+**Existing CometChat install.** When `existing_cometchat` is true, detect also returns
+`installed_uikit`, `android_uikit_major` and `version_conflict`. A v4/v5 `chat-uikit-android` is a
+**STOP**: adding v6 beside it produces duplicate-class build failures. Tell the user which version
+they are on and offer the upgrade (`cometchat-android-v6-migration`) BEFORE any new feature work.
+Only when the tree is clean (or already v6) do you proceed to credentials.

package/skills/cometchat-android-v6-core/references/troubleshooting.md

@@ -0,0 +1,36 @@
+# troubleshooting — CometChat Android v6: symptom → cause → fix
+
+> Ground truth: `ui-kit/android/troubleshooting.md` (docs rows) + `getting-started-*` Warnings + installed 6.0.5 `CometChatUIKit.kt` error codes, verified 2026-08-20.
+
+The fast symptom-table for a broken integration. Each row is a REAL failure mode — fix in the app; don't fetch docs for these. Deeper detail is cross-linked to the sibling reference. For anything not here → the docs page `{DOCS_BASE}/ui-kit/android/troubleshooting.md` (`docs-map.md`).
+
+## The table
+| Symptom (what the user sees) | Root cause | Fix |
+|---|---|---|
+| **Build fails: `Could not find com.cometchat:chatuikit-...`** | The CometChat Maven repository is missing — the kit isn't on mavenCentral | Add `maven("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/")` to `settings.gradle(.kts)` `dependencyResolutionManagement.repositories`, then re-sync. |
+| **`Duplicate class android.support.v4.*` — on a CLEAN, single-cohort app** | NOT a version conflict. `com.cometchat:chat-sdk-android` still pulls a pre-AndroidX transitive: `android.arch.lifecycle:extensions:1.1.1` → `com.android.support:support-compat:26.1.0`, which collides with `androidx.core:core`. | Set BOTH in `gradle.properties`: `android.useAndroidX=true` and `android.enableJetifier=true`. Verified on a clean app 2026-08-24 (removing the line reproduces the failure). The review harness carries the same pair. |
+| **`Duplicate class org.jetbrains.annotations.*` at dexing** | `io.noties:prism4j` pulls `annotations-java5:17`, colliding with `annotations:23` from AndroidX/Kotlin | `configurations.all { exclude(group = "org.jetbrains", module = "annotations-java5") }` — see core's install block. |
+| **`Dependency 'androidx.core:core:1.18.0' requires Android Gradle plugin 8.9.1 or higher`** | AGP floor understated as 8.9 | AGP **8.9.1**. |
+| **`kotlin-stdlib … metadata is 2.2.0, expected version is 2.0.0` / `Internal compiler error`** | Kotlin floor understated as 2.0 | Kotlin **2.1+** (2.0.21 fails; the review harness builds on 2.1.20). |
+| **Duplicate class / resource merge errors; or two kit majors in the tree** | version_conflict — both cohort artifacts installed, or a v5 `chat-uikit-android` alongside v6 `chatuikit-*` | STOP and reconcile: keep ONE cohort (`chatuikit-kotlin-android` OR `chatuikit-compose-android`) and ONE major; v5→v6 goes through `upgrading-from-v5`. See `setup-credentials.md` §3. |
+| **Init `onError` / `init()` fails silently** | Wrong App ID or Region (or empty values written to the settings JSON) | Re-check Dashboard → Credentials; Region must match (`us`/`eu`/`in`) — an auth error on init is most commonly a Region mismatch. See `setup-credentials.md` §6. |
+| **Init `onError: ERR_SETTINGS_FILE_NOT_FOUND`** | `app/src/main/assets/cometchat-settings.json` is missing (it's gitignored — fresh clones don't have it) | Re-create the settings JSON from the dashboard creds (`setup-credentials.md` §4/§5). |
+| **Init `onError: ERR_SETTINGS_INVALID`** | `appId` or `region` missing/empty in `cometchat-settings.json` | Fill both required root keys; they are not secrets and must always be present. |
+| **Login `onError: ERR_UID_NOT_FOUND` / "UID not found"** | The UID doesn't exist in this CometChat app (hardcoded/guessed sample) | Use a UID that EXISTS: Dashboard → Users (fresh apps seed `cometchat-uid-1…5`), create one there, or `CometChatUIKit.createUser` (dev). See `setup-credentials.md` §7. |
+| **Login does nothing — no success, no error** | `login()` called before `init()` resolved — the docs Warning: it "will fail silently" | Call `login` only inside init's `onSuccess`; the init→login→render order is invariant. See `lifecycle.md`. |
+| **Blank / stuck splash or gate screen** | The gate never unlocks: an `onError` was swallowed (wrong Region, missing settings file, bad UID), so neither navigation nor an error message fires | Surface every `onError` (`e.message`) on the gate UI; check logcat for the CometChatException. See `lifecycle.md` "Surfacing CometChatException". |
+| **Blank screen after login / component stuck on loading** | A `CometChat*` component rendered before init+login resolved, or (message screen) no `User`/`Group` was set on it | Gate rendering on both callbacks; pass the selected `conversationWith` entity to header/list/composer — the list shows only its loading indicator without one (docs Warning). See `component-props.md`. |
+| **Conversations list renders but is EMPTY** | Fresh app with no conversations yet — or credentials point at a different app than expected | Seed data: log in as another seeded user (`cometchat-uid-2`) on a second device/emulator and send a message; or verify the App ID matches the dashboard app you're looking at. An `onEmpty` fire with valid creds is data, not a bug. |
+| **Composer hidden under the keyboard** | Window doesn't resize for the IME | Views: `android:windowSoftInputMode="adjustResize"` on the chat Activity; Compose: `imePadding()` on the message column. See `layout.md` invariant 3. |
+| **Header/composer under the status/nav bars** | `enableEdgeToEdge()` without inset handling | `Scaffold(contentWindowInsets = WindowInsets.statusBars)` + `navigationBarsPadding()` (Compose) / inset padding on the root (Views). See `layout.md` invariant 2. |
+| **Chat surface is a ~0dp sliver or grows into place** | `wrap_content`/unbounded height on a list-shaped component | `match_parent`/`fillMaxSize()`; message list `0dp`+`layout_weight="1"` / `weight(1f)`. See `layout.md` invariants 1/5. |
+| **Messages don't arrive in real time** (only on refresh/reopen) | Your own SDK listener never registered or removed too early (drop-ins manage their own) — or no network connection so the socket is down | Register `CometChat.addMessageListener(listenerId, ...)` in the screen's active lifecycle and remove it in the matching teardown — not before; verify connectivity (the SDK reconnects automatically). See `anti-patterns.md` #6. |
+| **Tapping "Reply in thread" does nothing** | `onThreadRepliesClick` not wired (navigation is the host's job) | Wire it to a thread screen (`CometChatThreadHeader` + parent-scoped list + composer via `parentMessageId`), or hide the option. See `component-props.md`. |
+| **Network/"cleartext" errors; init callback never fires** | `android.permission.INTERNET` missing from the manifest (or network blocked) | Add `<uses-permission android:name="android.permission.INTERNET" />` (+ `ACCESS_NETWORK_STATE`) to `AndroidManifest.xml` — the docs guide requires both; then re-check Region. |
+| **`setOnItemClick` not firing** | Selection mode set to `MULTIPLE` consumes item clicks | Set selection mode `NONE` for standard click behavior (docs troubleshooting row). |
+| **Release build crashes / kit classes missing** | R8/ProGuard stripped CometChat classes | Add `-keep class com.cometchat.** { *; }` to `proguard-rules.pro` (docs troubleshooting row). |
+
+## When it's NOT in the table
+- **Any param/signature question** → fetch the component's `.md` twin via `docs-map.md`; never answer from memory.
+- **A feature renders empty** (stickers/polls/AI) → the extension likely isn't enabled in the Dashboard (see `cometchat-android-v6-features`).
+- **Still stuck** → logcat first: a `CometChatException` code beats guessing (4xx = auth/plan/config, not a code bug); confirm the settings JSON values, the cohort artifact, and that the docs' `minSdk`/`jvmTarget` prerequisites hold; then the docs troubleshooting page for the long tail (theming, calling, localization, sound).

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

@@ -1,215 +1,77 @@
 ---
 name: cometchat-android-v6-events
-description: "CometChat Android UIKit v6 event system — SharedFlow-based reactive event bus for messages, calls, users, groups, conversations, and UI events"
+description: "React to what the CometChat Android v6 UI Kit is doing — the CometChatEvents SharedFlow bus (message, call, conversation, group, user and UI events), how to collect it in Compose vs XML Views with correct lifecycle scoping, and when to use UI-Kit events versus Chat SDK listeners. Triggers: 'listen for message sent android cometchat', 'cometchat events android', 'know when a call is accepted', 'react when a group is created', 'sdk listener vs uikit event'."
 license: "MIT"
-compatibility: "Android 9.0+ (API 28); Kotlin 1.9+; com.cometchat:chatuikit-core-android:6.x"
+compatibility: "Android minSdk >=28; compileSdk >=36; Kotlin >=2.1; AGP >=8.9.1; JVM target 11; com.cometchat:chatuikit-kotlin-android ^6 OR com.cometchat:chatuikit-compose-android ^6 (6.0.x, verified 6.0.5); com.cometchat:chat-sdk-android ^5"
 metadata:
   author: "CometChat"
-  version: "3.0.0"
-  tags: "cometchat, android, events, sharedflow, kotlin-flow, reactive"
+  version: "1.0.0"
+  tags: "cometchat android events v6 sharedflow lifecycle compose views"
 ---
 
-> **Ground truth:** `com.cometchat:chatuikit-{compose,kotlin}-android:6.x` (+ `calls-sdk-android:5.x`) — resolved AAR (javap) + `ui-kit/android/v6`. **Official docs:** https://www.cometchat.com/docs/ui-kit/android/v6/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.
+> **Ground truth:** catalog `android-v6.json` + the live pages `events` (the API reference) and `customization-events`. `CometChatEvents` lives in `chatuikit-core-android` (`com.cometchat.uikit.core.events.CometChatEvents`). Verify symbols against the catalog; fetch the exact sealed-class members from the docs page — the event lists below are a MAP, the page is the manual.
 
-> **Companion skills:** cometchat-android-v6-core (init/login), cometchat-android-v6-kotlin-customization, cometchat-android-v6-compose-customization
-
-## Purpose
-
-Subscribe to and emit CometChat events using the v6 Kotlin SharedFlow-based event bus. This replaces the v5 Java listener interface pattern with a reactive, type-safe system built on `kotlinx.coroutines.flow.SharedFlow`.
+## Companion skills (read first)
+- `cometchat-android-v6-core` — install, credentials, `initFromSettings → login → render`, the fetch map. Assumed here, never repeated.
+- `cometchat-android-v6-{kotlin,compose}-customization` — click/selection callbacks on a single component (usually the simpler answer than the global bus).
 
 ## Use this skill when
+"tell me when a message is sent/edited/deleted", "run code when a call is accepted", "update my own badge when a conversation changes", "hook into group/member changes", "what's the difference between an SDK listener and a UI Kit event?".
 
-- Listening for message sent/received/edited/deleted events
-- Listening for call accepted/rejected/ended events
-- Listening for user or group membership changes
-- Listening for conversation updates
-- Listening for UI events (custom UI position events)
-- Emitting custom events to trigger UI updates
-
-## Do not use this skill when
-
-- Setting up the SDK (use `cometchat-android-v6-core`)
-- Working with CometChat SDK-level listeners (`CometChat.addMessageListener`) — those are separate from UIKit events
-
-## 1. Event Bus Architecture
-
-`CometChatEvents` is a singleton object in `com.cometchat.uikit.core.events` that manages 6 event flows:
-
-```kotlin
-import com.cometchat.uikit.core.events.CometChatEvents
-
-// 6 event flows — all are SharedFlow<T>
-CometChatEvents.messageEvents       // SharedFlow<CometChatMessageEvent>
-CometChatEvents.callEvents          // SharedFlow<CometChatCallEvent>
-CometChatEvents.userEvents          // SharedFlow<CometChatUserEvent>
-CometChatEvents.groupEvents         // SharedFlow<CometChatGroupEvent>
-CometChatEvents.conversationEvents  // SharedFlow<CometChatConversationEvent>
-CometChatEvents.uiEvents            // SharedFlow<CometChatUIEvent>
-```
+## Prerequisites & install
+Same kit + init as `core`. `CometChatEvents` ships in `chatuikit-core-android` (already a transitive dependency of both cohort artifacts) — nothing to add.
 
-Each flow uses:
-- `replay = 0` — no replay of past events to new subscribers
-- `BufferOverflow.DROP_OLDEST` — drops oldest events when buffer is full
-- Buffer capacities: messages=64, groups=32, users/conversations/ui=16, calls=8
+## The event bus (BAKED map — fetch the page for each sealed class's members)
+All events come from the **`CometChatEvents` singleton**; each domain exposes a **`SharedFlow`** of a sealed class:
 
-## 2. Subscribing to Events
+| Flow | Sealed class | What it covers |
+|---|---|---|
+| `CometChatEvents.messageEvents` | `CometChatMessageEvent` | sent · edited · deleted · read · live reaction · interactive/card/form/scheduler received |
+| `CometChatEvents.callEvents` | `CometChatCallEvent` | call initiated · accepted · rejected · ended |
+| `CometChatEvents.conversationEvents` | `CometChatConversationEvent` | conversation deleted · updated |
+| `CometChatEvents.groupEvents` | `CometChatGroupEvent` | group created/deleted · member changes |
+| `CometChatEvents.userEvents` | `CometChatUserEvent` | user blocked · unblocked |
+| `CometChatEvents.uiEvents` | `CometChatUIEvent` | panel visibility · active-chat changes |
 
-### 2.1 In a ViewModel or CoroutineScope
+Member shapes are **prefixed too** and the message ones repeat the domain: `CometChatMessageEvent.MessageSent(message, status)` (status `IN_PROGRESS`/`SUCCESS`/`ERROR`) · `MessageEdited` · `MessageDeleted` · `MessageRead` · `TextMessageReceived` · `TypingStarted` · `ReactionAdded`. There is no `.Sent` — it is `.MessageSent`. Import the sealed class from `com.cometchat.uikit.core.events`. Full list: fetch `/ui-kit/android/customization-events.md` (NOT `events.md`, which still teaches the old un-prefixed shape).
 
+## Subscribing per cohort (lifecycle is the whole point)
+**Kotlin XML Views** — collect in `lifecycleScope`; the coroutine is cancelled when the lifecycle owner is destroyed:
 ```kotlin
-import com.cometchat.uikit.core.events.*
+import androidx.lifecycle.lifecycleScope       // in an Activity/Fragment
 import kotlinx.coroutines.launch
+import com.cometchat.uikit.core.events.CometChatEvents
+import com.cometchat.uikit.core.events.CometChatMessageEvent
 
-// In a ViewModel
-viewModelScope.launch {
+lifecycleScope.launch {
     CometChatEvents.messageEvents.collect { event ->
         when (event) {
-            is CometChatMessageEvent.MessageSent -> {
-                val message = event.message
-                val status = event.status // IN_PROGRESS, SUCCESS, or ERROR
-            }
-            is CometChatMessageEvent.MessageEdited -> {
-                val editedMessage = event.message
-            }
-            is CometChatMessageEvent.MessageDeleted -> {
-                val deletedMessage = event.message
-            }
-            // handle other message events...
-            else -> {}
+            is CometChatMessageEvent.MessageSent -> { /* event.message, event.status */ }
+            is CometChatMessageEvent.MessageDeleted -> { /* event.message */ }
+            else -> Unit
         }
     }
 }
 ```
-
-### 2.2 In Jetpack Compose
-
+**Jetpack Compose** — collect in `LaunchedEffect`; cancelled when the composable leaves composition:
 ```kotlin
-import androidx.compose.runtime.LaunchedEffect
-import com.cometchat.uikit.core.events.*
-
-@Composable
-fun ChatScreen() {
-    LaunchedEffect(Unit) {
-        CometChatEvents.callEvents.collect { event ->
-            when (event) {
-                is CometChatCallEvent.CallAccepted -> {
-                    // Navigate to ongoing call screen
-                }
-                is CometChatCallEvent.CallRejected -> {
-                    // Dismiss call UI
-                }
-                else -> {}
-            }
-        }
-    }
-}
-```
-
-### 2.3 In an Activity or Application class
-
-```kotlin
-private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main)
-
-override fun onCreate(savedInstanceState: Bundle?) {
-    super.onCreate(savedInstanceState)
-    
-    scope.launch {
-        CometChatEvents.callEvents.collect { event ->
-            when (event) {
-                is CometChatCallEvent.CallAccepted -> { /* ... */ }
-                is CometChatCallEvent.CallRejected -> { /* ... */ }
-                else -> {}
-            }
-        }
-    }
-}
-
-override fun onDestroy() {
-    super.onDestroy()
-    scope.cancel() // Always cancel to avoid leaks
+LaunchedEffect(Unit) {
+    CometChatEvents.messageEvents.collect { event -> /* when (event) { … } */ }
 }
 ```
+> **No manual removal needed.** Unlike the old static-listener pattern, `SharedFlow` collection is scoped — do NOT invent an `addListener`/`removeListener` pair for `CometChatEvents`. Just don't collect outside a lifecycle-aware scope (a bare `GlobalScope.launch` IS a leak).
 
-## 3. Emitting Events
-
-```kotlin
-// Emit a message event
-CometChatEvents.emitMessageEvent(
-    CometChatMessageEvent.MessageSent(message, MessageStatus.SUCCESS)
-)
-
-// Emit a call event
-CometChatEvents.emitCallEvent(
-    CometChatCallEvent.CallRejected(call)
-)
-
-// Emit a user event
-CometChatEvents.emitUserEvent(event)
-
-// Emit a group event
-CometChatEvents.emitGroupEvent(event)
-
-// Emit a conversation event
-CometChatEvents.emitConversationEvent(event)
-
-// Emit a UI event
-CometChatEvents.emitUIEvent(event)
-```
-
-All emit functions are thread-safe — they launch on `Dispatchers.Default` internally.
-
-## 4. Event Types Reference
-
-### 4.1 CometChatMessageEvent (sealed class)
-
-| Event | Properties | When emitted |
+## UI-Kit events vs Chat SDK listeners (pick the right bus)
+| | **UI-Kit events** (`CometChatEvents.*`) | **Chat SDK listeners** (`CometChat.add*Listener`) |
 |---|---|---|
-| `MessageSent` | `message: BaseMessage`, `status: MessageStatus` | Text/media/custom message sent (IN_PROGRESS → SUCCESS or ERROR) |
-| `MessageEdited` | `message: BaseMessage` | Message edited |
-| `MessageDeleted` | `message: BaseMessage` | Message deleted |
-
-`MessageStatus` enum: `IN_PROGRESS`, `SUCCESS`, `ERROR`
-
-### 4.2 CometChatCallEvent (sealed class)
-
-| Event | Properties | When emitted |
-|---|---|---|
-| `CallAccepted` | `call: Call` | Incoming call accepted |
-| `CallRejected` | `call: Call` | Call rejected |
-| `CallEnded` | `call: Call` | Call ended |
-| `OutgoingCall` | `call: Call` | Outgoing call initiated |
-
-### 4.3 CometChatUserEvent (sealed class)
-
-User-related events (block, unblock, etc.)
-
-### 4.4 CometChatGroupEvent (sealed class)
-
-Group membership events (member added, removed, scope changed, etc.)
-
-### 4.5 CometChatConversationEvent (sealed class)
-
-Conversation-level events (conversation deleted, etc.)
-
-### 4.6 CometChatUIEvent (sealed class)
-
-UI-level events including `CustomUIPosition` for custom view positioning.
-
-## 5. Migration from v5
-
-| v5 Pattern | v6 Pattern |
-|---|---|
-| `CometChatMessageEvents.addListener(id, listener)` | `CometChatEvents.messageEvents.collect { }` |
-| `CometChatCallEvents.addListener(id, listener)` | `CometChatEvents.callEvents.collect { }` |
-| `listener.onTextMessageSent(message)` | `is CometChatMessageEvent.MessageSent` |
-| `removeListener(id)` | Cancel the coroutine scope |
-| Java interface callbacks | Kotlin sealed class + when expression |
+| Source | UI Kit components (what the UI just did) | the CometChat server (what arrived) |
+| Direction | component → component | server → client |
+| Registration | `.collect {}` in a lifecycle scope | `add*Listener(ID, …)` + **`remove*Listener(ID)` on teardown** |
+| Use for | "the user sent/edited a message", "a call was accepted", panel/active-chat changes | incoming messages, presence, typing, connection status, incoming calls |
+**Both are needed for a full app.** If you're reacting to something the server pushed while your UI didn't do it, that's an SDK listener (→ `core/references/docs-map.md` SDK section, or `cometchat-android-v5-sdk`) — and SDK listeners DO require explicit removal in `onDestroy`/`onDispose`/`onCleared`.
 
-## Hard rules
+## Common pitfalls
+Collecting on a non-lifecycle scope (leak) · inventing `CometChatEvents.addListener`/`removeListener` (doesn't exist — it's a flow) · using a UI-Kit event to detect *incoming* messages (use an SDK message listener) · registering an SDK listener and never removing it · a `when` without an `else` branch breaking on a new sealed member · re-collecting the same flow in several places and double-handling · guessing a sealed-class case name instead of fetching the events page.
 
-- NEVER collect flows on `Dispatchers.Default` for UI updates — switch to `Dispatchers.Main` or use `viewModelScope` / `lifecycleScope`
-- ALWAYS cancel coroutine scopes when the component is destroyed to avoid memory leaks
-- Events are emitted on `Dispatchers.Default` — the subscriber is responsible for thread switching
-- Buffer overflow uses `DROP_OLDEST` — high-frequency events may be dropped if the subscriber is slow
-- Do NOT confuse UIKit events (`CometChatEvents`) with SDK-level listeners (`CometChat.addMessageListener`) — they are separate systems
-- `CometChatUIKit.sendTextMessage()` / `sendMediaMessage()` / `sendCustomMessage()` automatically emit message events — do not double-emit
+## Verify it works
+Compile against the pinned kit (`./gradlew :app:assembleDebug   # in YOUR app (npm run verify:fences:android-v6 is a pack-repo gate)`). On device: trigger the action (send/edit/delete a message, accept a call) and confirm your handler runs exactly once; rotate the screen / navigate away and back — no duplicate handling and no crash (proves the scope is right); for any SDK listener you added, confirm the matching remove runs on teardown.