@cometchat/skills 4.4.2 → 5.0.1

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

@@ -0,0 +1,90 @@
+# Switching users (account switch / shared device) — Calls SDK v5
+
+> **Verified live 2026-09-08** on two emulators (Pixel_10 + Pixel_8), `calls-sdk-android 5.0.4` +
+> `chat-sdk-android 5.0.5`. The docs' authentication page does NOT cover this path (DOCS-BACKLOG C13).
+
+## The trap
+
+`CometChatCalls.logout()` — **and the implicit logout inside `login(<a different uid>)`** — leaves the
+Calls SDK **de-initialized**: `CometChatCalls.isInitialized()` returns `false` afterwards. Nothing in the
+docs says so, and `login()` for the new user still reports **`onSuccess`**. The failure only surfaces one
+call later:
+
+```
+generateToken FAILED: ERROR_COMETCHAT_CALLS_SDK_INIT
+  "Please call the CometChatCalls.init() method preferably in the onCreate() method of the
+   application class before calling any other methods related to CometChatCalls"
+```
+
+That message sends you hunting for a missing `init()` in `Application.onCreate()` — which **is** there and
+**did** resolve (`Init Successful`) at process start. The real cause is the logout that happened since.
+
+**Evidence (measured, same device, same build):**
+
+| Sequence | `isInitialized()` | `generateToken` |
+|---|---|---|
+| init → login(uid-3) → generateToken *(no switch)* | `true` | **OK** → `onSessionJoined` |
+| init → login(uid-2) with uid-3 still logged in | — | **FAILS** `ERROR_COMETCHAT_CALLS_SDK_INIT` |
+| init → logout both → login(uid-2) | **`false`** before login, `false` after | **FAILS** (same error) |
+| init → logout both → **re-init** → login(uid-2) | **`true`** | **OK** → `onSessionJoined` |
+
+Logging out is not enough on its own — **the re-init is the step that fixes it.**
+
+## The sequence (BAKED)
+
+Switching from `current` to `uid` — do all four, in order, each chained off the previous callback:
+
+1. `CometChatCalls.logout(listener)` — Calls SDK
+2. `CometChat.logout(listener)` — Chat SDK (ringing only; also clears the stale chat session)
+3. `CometChatCalls.initFromSettings(context, listener)` — **re-init, and WAIT for `onSuccess`**
+4. `CometChatCalls.login(uid, authKey, listener)` (+ `CometChat.login` for ringing)
+
+```kotlin
+fun switchUser(uid: String, authKey: String, then: () -> Unit) {
+    val current = CometChatCalls.getLoggedInUser()
+    if (current == null) { loginBoth(uid, authKey, then); return }        // nobody logged in
+    if (current.uid == uid) { then(); return }                            // SAME user — nothing to do
+
+    CometChatCalls.logout(object : CometChatCalls.CallbackListener<String>() {
+        override fun onSuccess(msg: String) {
+            CometChat.logout(object : CometChat.CallbackListener<String>() {   // ringing builds only
+                override fun onSuccess(m: String) = reinitThenLogin(uid, authKey, then)
+                override fun onError(e: com.cometchat.chat.exceptions.CometChatException) =
+                    reinitThenLogin(uid, authKey, then)                   // stale chat session is non-fatal
+            })
+        }
+        override fun onError(e: CometChatException) { /* surface e.code; do NOT continue silently */ }
+    })
+}
+
+private fun reinitThenLogin(uid: String, authKey: String, then: () -> Unit) {
+    // MANDATORY: logout left isInitialized() == false. Re-init BEFORE login or generateToken
+    // will fail with the misleading ERROR_COMETCHAT_CALLS_SDK_INIT.
+    CometChatCalls.initFromSettings(context, object : CometChatCalls.CallbackListener<String>() {
+        override fun onSuccess(result: String) = loginBoth(uid, authKey, then)
+        override fun onError(e: CometChatException) { /* surface e.code */ }
+    })
+}
+```
+
+## Rules
+
+- **Never guard login with `getLoggedInUser() != null` alone.** That is the docs' snippet
+  (`if (getLoggedInUser() == null) login(...)`) and it only handles "same user". On a shared or
+  re-used device it silently places calls **as the previous user**. Branch on the **uid**:
+  `getLoggedInUser()?.uid == uid`.
+- **Leave the call first.** `CallSession.getInstance().leaveSession()` (and `CometChat.endCall` if the
+  session came from ringing) before logging out — a switch during a live session leaks it.
+- **Re-register the ringing `CallListener`** after the new login; listener IDs from the old session are
+  bound to the old user (`references/ringing.md`).
+- **Fresh installs are unaffected** — the trap needs a pre-existing session, which is exactly why it
+  survives testing on a clean emulator and then bites on a real user's device.
+
+## Upstream status
+
+- **Docs (DOCS-BACKLOG C13):** `/calls/android/authentication` documents `logout()` as "clears the local
+  session" with no mention that it also de-initializes the SDK, and its login guard covers only the
+  null case. Both need the switch path.
+- **SDK (class C):** `login(<different uid>)` reporting `onSuccess` while leaving the SDK de-initialized,
+  then failing one call later with an error naming the wrong cause, is an SDK defect (AUDIT-194).
+  Drop this workaround's re-init step if a 5.0.x ships that re-initializes on login.

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

@@ -0,0 +1,127 @@
+---
+name: cometchat-android-v5-sdk
+description: "Build chat on Android with the headless CometChat Chat SDK v5 and your OWN UI — init/login ordering, the method map, request-builder pagination, listener lifecycle, and a production-ready app surface (optimistic updates, error states, sized shell). Use when the app needs custom UI instead of the drop-in UI Kit. Triggers: 'cometchat android sdk', 'chat with my own ui android', 'headless cometchat android', 'send message with chat-sdk-android', 'cometchat message listener kotlin'."
+license: "MIT"
+compatibility: "Android minSdk >=24; Kotlin >=1.9 / AGP >=8; JVM target 11; com.cometchat:chat-sdk-android ^5 (5.0.x, verified 5.0.5); optional com.cometchat:calls-sdk-android ^5"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat android sdk v5 headless kotlin custom-ui chat-sdk"
+---
+
+> **Ground truth:** catalog `sdk-android-v5.json` (curated from the INSTALLED `com.cometchat:chat-sdk-android:5.0.5` AAR — the existence oracle) + `features.sdk-android-v5.json` + `contracts.sdk-android-v5.json` (`sdk-chat-surface` — the completeness floor). Docs: `references/docs-map.md`. ⚠️ **Android SDK v5 pages are VERSIONED** (`/sdk/android/v5/…`); the unversioned tree is v4. Verify symbols against the catalog; fetch signatures from docs; never trust memory.
+
+## Companion skills (read first)
+This skill is **self-contained** for headless builds — it does not depend on a UI Kit core. But: if the user wants ready-made chat UI, the **UI Kit is the better answer** — say so and route to `cometchat-android-v6-core` (drop-in components, far less code). Come here when they explicitly want their own UI, a non-chat surface, or backend-style usage.
+
+## Use this skill when
+"use the CometChat SDK directly", "build chat with my own UI/design system", "I don't want the UI Kit", "send/receive messages programmatically", "custom chat screen in Compose backed by CometChat".
+
+## Prerequisites & install
+```kotlin
+// settings.gradle(.kts) → dependencyResolutionManagement.repositories
+maven("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/")
+// app/build.gradle.kts
+implementation("com.cometchat:chat-sdk-android:5.0.5")     // + calls-sdk-android:5.0.4 for calling
+```
+```properties
+# gradle.properties — REQUIRED: chat-sdk-android 5.0.5 still pulls android.arch.lifecycle:extensions:1.1.1 → com.android.support:support-compat:26.1.0
+android.useAndroidX=true
+android.enableJetifier=true
+```
+- **Jetifier is not optional.** Without `android.enableJetifier=true` an AndroidX app fails `checkDebugDuplicateClasses` (`Duplicate class android.support.v4.app.INotificationSideChannel … androidx.core:core and com.android.support:support-compat:26.1.0`). Verified 2026-09-07 (removing the line reproduces it); `dependencyInsight --dependency support-compat` shows the chain. Calling (`calls-sdk-android:5.0.4`) additionally needs `minSdk 26` + the SoLoader init + a manifest `<service>` — `cometchat-android-v5-calls-sdk` Prerequisites.
+Manifest needs `android.permission.INTERNET`. Credentials live in the **gitignored** `app/src/main/assets/cometchat-settings.json` (`appId`, `region`, `credentials.authKey` dev-only). The optional `chatSDK` section carries SDK-level overrides; init succeeds without it, so omit it for a minimal build — **BUT one override is load-bearing for a required surface:**
+
+> ⚠️ **Presence is opt-in via `chatSDK.presenceSubscription` — omit it and realtime presence is silently dead.** The app-surface floor requires a presence-aware chat header + users list (`onUserOnline`/`onUserOffline`). `initFromSettings` only subscribes to presence if the asset sets `chatSDK.presenceSubscription`; **if it's absent, `onUserListener` events NEVER fire** (docs `/sdk/android/v5/user-presence`: "If none of the above methods are set, no presence will be sent"). Accepted values (verified against the AAR settings parser — bad values throw `ERR_SETTINGS_FILE_INVALID_PRESENCE_TYPE`): `ALL_USERS` · `FRIENDS` · `ROLES` (with a sibling `roles` list) · `NONE`. So whenever you wire the presence surface, ship:
+> ```json
+> { "appId": "…", "region": "…", "credentials": { "authKey": "…" },
+>   "chatSDK": { "presenceSubscription": "ALL_USERS" } }
+> ```
+> Distinguish the two presence paths: `getUser(uid).status` / the `UsersRequest` list `status` field is a **one-time snapshot** (works without the subscription); the **realtime** `onUserOnline`/`onUserOffline` transitions need the subscription above.
+
+> ⚠️ **Docs drift — `ConnectionListener`.** `/sdk/android/v5/connection-status.md` shows
+> `override fun onError(e: CometChatException)`. That does not compile: the member is
+> **`onConnectionError(e: CometChatException?)`**, and `ConnectionListener` is an **interface** —
+> `object : CometChat.ConnectionListener` with **no parentheses**, unlike `CometChat.MessageListener()`.
+> Verified against `CometChat.java:10737`.
+
+## Init & login ordering (BAKED — invariant)
+`CometChat.initFromSettings(...)` resolves → `login(...)` resolves → everything else. Any SDK call before init fails; login before init **fails silently**.
+```kotlin
+import com.cometchat.chat.core.CometChat
+import com.cometchat.chat.exceptions.CometChatException
+import com.cometchat.chat.models.User
+
+CometChat.initFromSettings(context, object : CometChat.CallbackListener<String>() {
+    override fun onSuccess(p: String) {                       // init resolved — telemetry source persisted
+        if (CometChat.getLoggedInUser() == null) {
+            // ⚠️ TWO DIFFERENT overloads — they are not interchangeable:
+            //   dev  : login(uid, authKey, listener)   ← 3 args, uid REQUIRED
+            //   prod : login(authToken, listener)      ← 2 args, NO uid (the token identifies the user)
+            // Passing a token in the 3-arg form sends it as an apiKey and fails.
+            // WHERE `authKey` COMES FROM (headless has no UI-Kit shortcut): read it back out of the
+            // same gitignored settings asset you already ship — never hardcode it, and never add a
+            // second copy in source:
+            //   val cfg = JSONObject(assets.open("cometchat-settings.json").bufferedReader().readText())
+            //   val authKey = cfg.getJSONObject("credentials").getString("authKey")
+            // Guard the read: if the asset is missing this throws BEFORE the SDK can report its own
+            // clean ERR_SETTINGS_FILE_NOT_FOUND, turning a clear error into a crash.
+            CometChat.login(uid, authKey, object : CometChat.CallbackListener<User>() {
+                override fun onSuccess(user: User) { /* unlock the app */ }
+                override fun onError(e: CometChatException) { /* surface e.code + e.message */ }
+            })
+        } else { /* session already live */ }
+    }
+    override fun onError(e: CometChatException?) { /* surface — do NOT proceed */ }
+})
+```
+`initFromSettings` reads the assets settings file and persists the integration source; the classic `CometChat.init(context, appId, AppSettings, callback)` still exists but is **not** the default (loses attribution). **Prod:** mint a per-user auth token server-side and log in with it; the Auth Key is dev-only. Re-logging a *different* user requires `logout` first.
+
+## SDK method map (BAKED closed list — catalog-verified)
+**Constants & models packages** — `com.cometchat.chat.core.*` (`CometChat`, `Call`, and the `*Request`/`*RequestBuilder` types) · `com.cometchat.chat.models.*` (`User`, `Group`, `TextMessage`, `MediaMessage`, `BaseMessage`, `TypingIndicator`) · `com.cometchat.chat.constants.CometChatConstants` (**`RECEIVER_TYPE_USER`/`RECEIVER_TYPE_GROUP` live HERE, not on `CometChat`**) · `com.cometchat.chat.exceptions.CometChatException`.
+**Auth overloads (do not conflate)** — `login(uid, authKey, listener)` for dev; `login(authToken, listener)` for production, which takes **no uid** because the server-minted token carries the identity. Getting this wrong is silent: the token goes through as an apiKey and auth fails.
+**Session** `initFromSettings` · `init` (legacy) · `login` · `logout` · `getLoggedInUser` · `getUserAuthToken` · `addLoginListener`/`LoginListener`/`removeLoginListener`
+**Messaging** `TextMessage` · `MediaMessage` · `CustomMessage` · `InteractiveMessage` · `sendMessage` · `sendMediaMessage` · `sendCustomMessage` · `sendInteractiveMessage` · `editMessage` · `deleteMessage` · `flagMessage`/`getFlagReasons` · `sendTransientMessage`/`TransientMessage` · `getMessageDetails` · `BaseMessage` · `Attachment` · `createUploadFileRequest`/`UploadFileRequest`/`UploadFileListener`
+**Fetching (always via a request builder + pagination)** `MessagesRequest.MessagesRequestBuilder` · `ConversationsRequest.ConversationsRequestBuilder` · `UsersRequest.UsersRequestBuilder` · `GroupsRequest.GroupsRequestBuilder` · `GroupMembersRequest.GroupMembersRequestBuilder` · `BannedGroupMembersRequest…` · `BlockedUsersRequest…` · `ReactionsRequest…` · `NotificationFeedRequest…`
+**Realtime listeners** `addMessageListener`/`MessageListener`/`removeMessageListener` · `addUserListener`/`UserListener`/… · `addGroupListener`/`GroupListener`/… · `addCallListener`/`CallListener`/… · `addConnectionListener`/`ConnectionListener`/… · `addAIAssistantListener`/`AIAssistantListener`/… · `addNotificationFeedListener`/`NotificationFeedListener`/…
+**Receipts & typing** `startTyping`/`endTyping`/`TypingIndicator` · `markAsDelivered`/`markAsRead`/`markAsUnread`/`markConversationAsRead` · `MessageReceipt`/`getMessageReceipts` · unread: `getUnreadMessageCount`/`…ForUser`/`…ForGroup`
+**Reactions** `addReaction`/`removeReaction`/`Reaction`/`ReactionCount`
+**Users** `getUser` · `createUser`/`updateUser`/`updateCurrentUserDetails` · `blockUsers`/`unblockUsers` · `User`
+**Groups** `createGroup`/`createGroupWithMembers` · `joinGroup`/`leaveGroup` · `updateGroup`/`deleteGroup`/`getGroup`/`getJoinedGroups` · `addMembersToGroup`/`kickGroupMember`/`banGroupMember`/`unbanGroupMember` · `updateGroupMemberScope`/`transferGroupOwnership` · `Group`/`GroupMember`
+**Conversations** `getConversation` · `deleteConversation` · `tagConversation` · `Conversation`
+**Calls** `initiateCall`/`acceptCall`/`rejectCall`/`endCall`/`startCall` · `getActiveCall`/`clearActiveCall` · `Call`/`CallSettings.CallSettingsBuilder`
+**AI** `getSmartReplies` · `getConversationStarter` · `getConversationSummary` · `askBot` · `isAIFeatureEnabled` · `AIAssistantMessage` + the `AIAssistant*Event` family
+**Push & feed** `registerTokenForPushNotification` · `CometChatNotifications` · `PushPlatforms` · `NotificationFeedItem`/`getNotificationFeedUnreadCount`
+**Connection** `getConnectionStatus` · `connect`/`disconnect`/`ping`
+Not in this map and not in the catalog ⇒ does not exist: fetch the page via `references/docs-map.md` before assuming.
+
+## Listener lifecycle (the #1 source of Android SDK bugs)
+Every `add*Listener(UNIQUE_ID, …)` **must** have a matching `remove*Listener(UNIQUE_ID)` on teardown — `onDestroy` (Activity/Fragment), `DisposableEffect`'s `onDispose` (Compose), or `onCleared` (ViewModel). Register with a stable, unique id (e.g. the screen's class name); registering the same id twice replaces silently, never removing leaks the callback and duplicates handling after rotation.
+```kotlin
+DisposableEffect(Unit) {
+    CometChat.addMessageListener(LISTENER_ID, object : CometChat.MessageListener() {
+        override fun onTextMessageReceived(message: TextMessage) { /* append to state */ }
+    })
+    onDispose { CometChat.removeMessageListener(LISTENER_ID) }
+}
+```
+Realtime arrives via listeners — **never poll**.
+
+## Least-code recipe — the production floor (contract `sdk-chat-surface`)
+Because the SDK ships no UI, a generic "build chat with the SDK" must deliver a **complete, production-ready app**, not bare bubbles. The floor (full text in `contracts.sdk-android-v5.json`, UI spec in `references/app-surface.md`):
+- **Data**: conversations + users + groups lists, each **searchable** (`setSearchKeyword` on the builder) and **paginated** via request builders (`setLimit` + fetch-next) — never one unbounded fetch. Scope the request to the product (1:1-only vs groups) instead of filtering client-side.
+- **Messaging**: send text/media, message history, **threads** via `setParentMessageId`, edit/delete/react/report — each wired to the SDK **and** reflected in the UI, with own-message gating for edit/delete.
+- **Realtime**: message/user/group/connection listeners registered and removed as above; typing indicators and receipts wired.
+- **Detail screens**: user (block/unblock) and group (add/kick/ban/scope/leave), role-gated.
+- **UX quality**: **optimistic updates** (show the message as sending immediately, reconcile in `onSuccess`, roll back + surface `CometChatException.message` in `onError`), **loading/empty/error states everywhere** (never a blank screen or `[object Object]`), a **sized shell** (`fillMaxSize`/`match_parent`, list scrolls internally, insets + IME handled), and your app's **existing design system** (Material3 theme or your tokens) — never ad-hoc inline styling.
+- **Errors**: every `CallbackListener` implements `onError` and surfaces something actionable. An empty `onError {}` is the defect this contract exists to prevent.
+
+## Deep references (load only when the task needs them)
+- `references/docs-map.md` — intent → the exact `/sdk/android/v5/<page>.md` to fetch (+ the v5-vs-v4 URL trap and the scoped LLM index).
+- `references/app-surface.md` — the own-UI production floor in detail (state model, optimistic mutations, list/pagination patterns, error/empty/loading, sizing).
+
+## Common pitfalls
+**reversed param order** — `updateGroupMemberScope(UID, GUID, scope, …)` vs `transferGroupOwnership(GUID, UID, …)` · **search-keyword casing differs per builder** — `UsersRequestBuilder.setSearchKeyword` and `ConversationsRequestBuilder.setSearchKeyword` are lowercase, but `GroupsRequestBuilder.setSearchKeyWord` has a **capital W** (SDK inconsistency; using `setSearchKeyword` on GroupsRequest is `Unresolved reference`) · **conversations search is plan-gated** — `ConversationsRequestBuilder.setSearchKeyword`/`setUnread` need the **"Conversation & Advanced Search"** feature (Advanced/Custom plan + dashboard toggle); off-plan it **silently returns the unfiltered list** (a search box that looks broken). Users/Groups search is NOT plan-gated. · passing an auth **token** into the 3-arg `login(uid, authKey, …)` (tokens use the 2-arg `login(authToken, …)`) · `CometChat.RECEIVER_TYPE_USER` (it is `CometChatConstants.RECEIVER_TYPE_USER`) · **presence never fires without `chatSDK.presenceSubscription`** in the settings asset (see Prerequisites) · importing `Call` from `chat.models` instead of `chat.core` · Any SDK call before init resolves · login before init (silent failure) · Auth Key shipped in a release build · listeners never removed (duplicate handling after rotation) · polling instead of listeners · unbounded fetches with no pagination · empty `onError` blocks · blocking the main thread waiting on callbacks · re-login without logout · using the unversioned `/sdk/android/` v4 docs · rebuilding UI the UI Kit already ships (when the user would accept drop-ins).
+
+## Verify it works
+Every symbol you emitted is in `sdk-android-v5.json` (Tier-1) and the app compiles: run `./gradlew :app:assembleDebug` in the user's app. On device: init → login succeed (logcat); the conversations/users/groups lists load and paginate; sending appears instantly and reconciles; a message from another user arrives **live** (listener, not refresh); edit/delete/react update in place; rotating the screen doesn't duplicate messages (listener lifecycle); force an error (airplane mode) → a readable error state, not a blank screen or crash. Live backend round-trip smoke for this family is **not automated yet** (parked with the Android native harness) — verify manually and say so.

package/skills/cometchat-android-v5-sdk/references/app-surface.md

@@ -0,0 +1,88 @@
+# app-surface — the production floor for an own-UI Android chat app (Chat SDK v5)
+
+The SDK ships **no UI**, so "build chat with the SDK" has no visual default — without a floor, output
+degrades to bare bubbles. This file is that floor: the deterministic minimum for a generic prompt.
+Encoded as `contracts.sdk-android-v5.json` → `sdk-chat-surface`; symbols verified against
+`catalogs/sdk-android-v5.json`. Exact signatures: `docs-map.md`.
+
+## 1. Shell & sizing
+- The chat screen **fills the window**: `Modifier.fillMaxSize()` (Compose) / `match_parent` (Views).
+- Three regions: header (who you're talking to) · **scrolling message list** · composer pinned to the
+  bottom. The LIST scrolls internally (`LazyColumn` / `RecyclerView`) — never nest it in another
+  scrollable, never let the page itself grow.
+- **Insets + IME**: `enableEdgeToEdge()` + `imePadding()`/`navigationBarsPadding()` (Compose) or
+  `windowSoftInputMode="adjustResize"` (Views), so the composer stays visible while typing and nothing
+  sits under the system bars.
+- New messages: keep the list pinned to the newest message when the user is already at the bottom;
+  don't yank the scroll position when they've scrolled up.
+
+## 2. Design system — reuse, don't invent
+Use the app's existing theme (Material3 `MaterialTheme` / your XML styles / your token set). If the app
+is brand new, establish a small token layer (colors, spacing, radii, type) and build primitives from it.
+**Never** ad-hoc inline colors and one-off dimensions scattered per screen.
+
+## 3. State model (own it explicitly)
+Per screen, a single state holder (ViewModel) exposing an immutable UI state:
+`{ items, isLoading, isPaginating, error, hasMore }` plus the input/composer state. Rules:
+- Never mutate a list in place from a callback thread — reduce into new state on the main dispatcher.
+- Keep SDK types at the edge; map to your own UI models so the UI doesn't break on SDK changes.
+- One listener registration per screen, tied to the screen's lifecycle (see §6).
+
+## 4. Lists + pagination (every list, every time)
+Build the request once, then page:
+```kotlin
+val request = MessagesRequest.MessagesRequestBuilder()
+    .setUID(uid)          // or .setGUID(guid)
+    .setLimit(30)
+    .build()
+// initial load + "load older" → request.fetchPrevious(callback)
+```
+Same builder discipline for `ConversationsRequest`, `UsersRequest`, `GroupsRequest`,
+`GroupMembersRequest`. Rules:
+- **Never** one unbounded fetch. Keep the built request instance for subsequent pages.
+- **Search** via the builder's search-keyword setter — a server-side query, not a client-side filter
+  over the page you happen to have. **Two traps, both real:**
+  - **Casing differs per builder.** `UsersRequestBuilder.setSearchKeyword` / `ConversationsRequestBuilder.setSearchKeyword` are lowercase, but `GroupsRequestBuilder.`**`setSearchKeyWord`** has a **capital W** (an SDK inconsistency). Using `setSearchKeyword` on GroupsRequest fails to compile (`Unresolved reference`).
+  - **Conversations search is PLAN-GATED.** `ConversationsRequestBuilder.setSearchKeyword` (and `setUnread`) require the **"Conversation & Advanced Search"** feature — **Advanced/Custom plan + a dashboard toggle** (Chats → Settings → General Configuration). Off-plan it **silently returns the full, unfiltered list** (no error) — the app ships a search box that looks broken. Users search and Groups search are NOT plan-gated (work on any plan). On a lower plan, gate the conversations-search UI behind a "requires Advanced plan" hint or fall back to a labelled local filter — never present an unfiltered result as a search result.
+- **Scope to the product** (`setConversationType("user")`/`"group"`) rather than filtering after the fact.
+- Guard against double-loading (`isPaginating`) and stop at the empty page (`hasMore = false`).
+
+## 5. Optimistic mutations (what makes it feel native)
+Send / edit / delete / react must update the UI **immediately**, then reconcile:
+1. Insert a local item in a `SENDING` state (key it by the message's `muid` so you can match the ack).
+2. Call the SDK.
+3. `onSuccess` → replace the temp item with the server message (`SENT`).
+4. `onError` → mark it `FAILED` with a retry affordance and surface `CometChatException.message`.
+Never block the UI waiting for a round-trip; never leave a failed item looking sent.
+
+## 6. Realtime + listener lifecycle
+Register **one** listener per screen with a stable unique id and remove it on teardown:
+- Compose: `DisposableEffect(Unit) { add…; onDispose { remove… } }`
+- Views/ViewModel: register in `onCreate`/`init`, remove in `onDestroy`/`onCleared`
+Cover: `addMessageListener` (incoming text/media), `addUserListener` (presence), `addGroupListener`
+(membership), `addConnectionListener` (offline/online banner). De-duplicate against optimistic items
+(match on message id / muid) so an echoed own-message doesn't appear twice. **Never poll.**
+- **Presence has a config prerequisite.** `addUserListener`'s `onUserOnline`/`onUserOffline` only fire if the settings asset opts in via `chatSDK.presenceSubscription` (`ALL_USERS`/`FRIENDS`/`ROLES`; absent ⇒ no presence — see SKILL.md Prerequisites). The seeded `getUser().status` / list `status` field is a snapshot and works without it; the realtime transition does not. Wiring the header/users presence surface **without** the subscription ships a header stuck on "offline".
+
+## 7. Required surfaces (a generic "build chat" delivers ALL of these)
+| Surface | Minimum |
+|---|---|
+| Conversations | list + last message + unread + searchable + delete-conversation |
+| Users / Groups | both lists, searchable, tap → open chat (join group if needed) |
+| Message screen | header (name/presence/typing) · paginated history · composer (text + media) |
+| Message actions | reply-in-thread · react · edit · delete (edit/delete gated to own messages) · report |
+| Thread | `setParentMessageId(...)`-scoped list + its own composer |
+| User detail | profile + block/unblock |
+| Group detail | members + add/kick/ban + scope change + leave, role-gated |
+| Receipts/typing | `markAsRead` on view; `startTyping`/`endTyping` wired to the input |
+
+## 8. Loading / empty / error — on every surface
+- **Loading**: skeleton or spinner sized like the content (no layout jump when it resolves).
+- **Empty**: a real message ("No conversations yet") — never a blank screen.
+- **Error**: readable text from `CometChatException.message` + a retry action. Every `CallbackListener`
+  implements `onError`; an empty `onError {}` is a defect, and connection loss must be visible.
+
+## 9. Anti-patterns (auto-fail this floor)
+Bare bubbles with no lists/actions · unbounded fetches · client-side "search" · polling for new messages ·
+listeners never removed · blank screens on empty/error · swallowed exceptions · main-thread blocking ·
+credentials in source · hand-rolled UI when the user would have accepted the UI Kit (offer it first).

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

@@ -0,0 +1,91 @@
+# docs-map — CometChat Android Chat SDK v5: 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, version?)` — replaces browsing the scoped `llms-*` index.
+- **Read the page** → `fetch_cometchat_doc_page(path)` — pass the SAME versioned `<path>` the tables below
+  list (e.g. `/sdk/android/v5/<page>`); the MCP resolves the `.md` twin and returns raw Markdown. A full
+  `https://…/docs/<path>` URL also works. (The v5-vs-v4 URL trap below still applies to the path you pass.)
+- **A whole feature/recipe** → `get_cometchat_implementation_bundle(...)` is **NON-AUTHORITATIVE** — curated STATIC recipes that can lag the live docs (verified stale vs v7: e.g. `CometChatConversationsWithMessages`, `css-variables.css`). Treat any bundle as a hint only: RECONCILE it against the `fetch_cometchat_doc_page` result + the pack's hardening; never emit bundle code verbatim.
+
+The MCP reads whatever docs environment it is pointed at (production by default; a preview when repointed),
+so it also carries the environment-swap concern below — no hardcoded host on the skill side.
+
+**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 `SDK_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.
+
+## SDK_DOCS_BASE — the fetch FALLBACK entry point (⚠️ SWAP HERE to change environments)
+```
+SDK_DOCS_BASE = https://www.cometchat.com/docs
+```
+> **⚠️ URL TRAP — the Android SDK is VERSIONED.** v5 pages live at `/sdk/android/v5/<page>`.
+> The UNVERSIONED tree `/sdk/android/<page>` is **v4** — never fetch it for a v5 build.
+> (The UI Kit is the opposite: its latest, v6, lives at the unversioned `/ui-kit/android/…`.)
+>
+> **Fetch rule:** build a URL as `SDK_DOCS_BASE` + the path shown, then append `.md`.
+> Never decompile the AAR and never answer an API from memory.
+
+## The convention
+`SDK_DOCS_BASE` + `<path>` + `.md` → raw Markdown (verbatim code + method signatures, parameters,
+listener contracts). Pages show Kotlin and Java variants where they differ — read the one the app uses.
+```
+Fetch:  {SDK_DOCS_BASE}/sdk/android/v5/send-message.md
+```
+Fallback order: `.md` twin → the same URL **without** `.md` (HTML) → **never** kit/AAR internals.
+
+## Scoped Android SDK v5 index (prefer over the global llms.txt)
+```
+{SDK_DOCS_BASE}/sdk/android/v5/llms-android-v5.md
+```
+An Android-SDK-v5-only index of every page as a `.md` link, grouped by area (Messaging · Calling ·
+Users · Groups · AI & advanced · Resources & listeners · Advanced). Use it to discover any page not
+in the table below. Global all-products index (large; last resort): `{SDK_DOCS_BASE}/llms.txt`.
+> **DOCS-GAP note:** this scoped index ships with docs branch `docs/android-llms-indexes`; until that
+> merges, the per-page `.md` twins below already work — fall back to this table.
+
+## Don't fetch the hot path — it's baked
+Install, `initFromSettings → login` ordering, the method map, and the listener add/remove discipline
+are BAKED in `cometchat-android-v5-sdk`. Fetch ONLY for exhaustive parameters, long-tail methods,
+group/user management details, calling, or edge-case listeners.
+
+## The 80% trigger table  (URL = `{SDK_DOCS_BASE}` + path, then append `.md`)
+| Intent | Path (append `.md`) |
+|---|---|
+| install / init / app settings | `/sdk/android/v5/setup` |
+| login, auth tokens, session | `/sdk/android/v5/authentication-overview` · `/sdk/android/v5/login-listeners` |
+| send a text message | `/sdk/android/v5/send-message` |
+| media / file / attachments | `/sdk/android/v5/upload-files` |
+| receive messages (listeners) | `/sdk/android/v5/receive-messages` · `/sdk/android/v5/real-time-listeners` |
+| message history / filtering / pagination | `/sdk/android/v5/additional-message-filtering` |
+| conversations list | `/sdk/android/v5/retrieve-conversations` · `/sdk/android/v5/delete-conversation` |
+| threads | `/sdk/android/v5/threaded-messages` |
+| edit / delete / flag a message | `/sdk/android/v5/edit-message` · `delete-message` · `flag-message` |
+| typing indicators | `/sdk/android/v5/typing-indicators` |
+| delivery & read receipts | `/sdk/android/v5/delivery-read-receipts` |
+| reactions | `/sdk/android/v5/reactions` |
+| mentions | `/sdk/android/v5/mentions` |
+| transient messages | `/sdk/android/v5/transient-messages` |
+| users: list / manage / block | `/sdk/android/v5/retrieve-users` · `user-management` · `block-users` |
+| presence | `/sdk/android/v5/user-presence` |
+| groups: list / create / update / join / leave / delete | `/sdk/android/v5/retrieve-groups` · `create-group` · `update-group` · `join-group` · `leave-group` · `delete-group` |
+| group members + moderation | `/sdk/android/v5/retrieve-group-members` · `group-add-members` · `group-kick-member` · `group-change-member-scope` · `transfer-group-ownership` |
+| calling | `/sdk/android/v5/calling-overview` (+ the `/calls/android/*` tree for call UI/behavior) |
+| AI moderation / agents / copilot / chatbots | `/sdk/android/v5/ai-moderation` · `ai-agents` · `ai-user-copilot-overview` · `ai-chatbots-overview` |
+| campaigns · extensions · webhooks | `/sdk/android/v5/campaigns` · `extensions-overview` · `webhooks-overview` |
+| message structure / key concepts | `/sdk/android/v5/message-structure-and-hierarchy` · `key-concepts` |
+| connection status / behaviour | `/sdk/android/v5/connection-status` · `connection-behaviour` |
+| rate limits | `/sdk/android/v5/rate-limits` |
+| Play Store publishing | `/sdk/android/v5/publishing-app-on-playstore` |
+| upgrading from v4 | `/sdk/android/v5/upgrading-from-v4` |
+| changelog | `/sdk/android/v5/changelog` |
+
+## Want ready-made UI instead?
+If the user would accept drop-in chat UI, the **Android UI Kit v6** is far less code —
+`cometchat-android-v6-core` and `{SDK_DOCS_BASE}/ui-kit/android/llms-android-v6.md`. Say so before
+hand-building a full chat UI on the SDK.
+
+## Not in the table?
+Fetch the scoped index (`{SDK_DOCS_BASE}/sdk/android/v5/llms-android-v5.md`), pick the page, fetch its
+`.md`. Never guess a path; never read AAR internals; never answer an API from memory.

package/skills/cometchat-android-v6-builder-settings/SKILL.md

@@ -1,149 +1,63 @@
 ---
 name: cometchat-android-v6-builder-settings
-description: "CometChat Android UIKit v6 UIKitSettings configuration — all builder options for SDK init, presence, calling, and host overrides"
+description: "The CometChat Android v6 settings and session API reference — the assets/cometchat-settings.json file that initFromSettings reads (appId, region, credentials, uiKit toggles), the legacy UIKitSettings builder, and the CometChatUIKit session methods (login, loginWithAuthToken, logout, getLoggedInUser, createUser). Use when configuring init options or wiring auth beyond the core golden path. Triggers: 'cometchat settings json android', 'uikitsettings builder options', 'login with auth token android', 'create a cometchat user from the app', 'enable calling in settings'."
 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, settings, builder, configuration, calling"
+  version: "1.0.0"
+  tags: "cometchat android settings uikitsettings auth v6 login authtoken"
 ---
 
-> **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:** the installed kit source `com.cometchat.uikit.core.CometChatUIKit` (6.0.5) + the live page `/ui-kit/android/methods` (init · authentication · logout · create user · message helpers). Symbols verified against catalog `android-v6.json`. Fetch exact signatures from the methods page; never guess an overload.
 
-> **Companion skills:** cometchat-android-v6-core (init/login), cometchat-android-v6-push (FCM/VoIP)
-
-## Purpose
-
-Detailed reference for `UIKitSettings.UIKitSettingsBuilder` — all configuration options for initializing the CometChat SDK, including presence subscriptions, calling features, and host overrides.
+## Companion skills (read first)
+- `cometchat-android-v6-core` — owns the DEFAULT path: `initFromSettings → login → render`, the settings file, and credential handling. Come HERE only when a task needs an option or auth variant beyond that default.
 
 ## Use this skill when
-
-- Configuring presence subscription types (all users, roles, friends)
-- Enabling calling features and configuring `CallSettingsBuilder`
-- Overriding admin or client host URLs
-- Controlling socket connection behavior
-- Understanding the full `UIKitSettingsBuilder` API
-
-## Do not use this skill when
-
-- Just doing basic init/login (use `cometchat-android-v6-core` for quick setup)
-- Working with UI components or theming
-
-## 1. UIKitSettingsBuilder — Complete API
-
-```kotlin
-import com.cometchat.uikit.core.UIKitSettings
-
-val settings = UIKitSettings.UIKitSettingsBuilder()
-
-    // Required
-    .setAppId("APP_ID")                          // CometChat App ID
-    .setRegion("us")                             // "us" or "eu"
-
-    // Authentication (dev only — use token auth in production)
-    .setAuthKey("AUTH_KEY")                      // Auth key from dashboard
-
-    // Presence subscriptions
-    .subscribePresenceForAllUsers()              // Subscribe to all users' presence
-    .subscribePresenceForRoles(listOf("admin"))  // Subscribe by roles
-    .subscribePresenceForFriends()               // Subscribe to friends' presence
-    .setRoles(listOf("admin"))                   // Override the roles list directly (advanced)
-
-    // Socket connection
-    .setAutoEstablishSocketConnection(true)      // Auto-connect (default: true)
-
-    // Calling
-    .setEnableCalling(true)                      // Auto-init CometChatCalls SDK (default: false)
-    .setCallSettingsBuilder(sessionSettingsBuilder)  // Custom call config (optional) — pass a CometChatCalls.SessionSettingsBuilder
-
-    // Host overrides (advanced — for on-premise deployments)
-    .overrideAdminHost("https://custom-admin.example.com")
-    .overrideClientHost("https://custom-client.example.com")
-
-    .build()
-```
-
-## 2. Presence Subscription Types
-
-Only one subscription type is active at a time. The last one set wins.
-
-| Method | Subscription Type | Use Case |
-|---|---|---|
-| (none) | `"NONE"` | No presence updates (default) |
-| `subscribePresenceForAllUsers()` | `"ALL_USERS"` | Small apps where you want all online statuses |
-| `subscribePresenceForRoles(roles)` | `"ROLES"` | Subscribe to specific user roles |
-| `subscribePresenceForFriends()` | `"FRIENDS"` | Social apps with friend lists |
-
-## 3. Calling Configuration
-
-When `setEnableCalling(true)` is set, `CometChatUIKit.init()` automatically initializes the CometChatCalls SDK after the Chat SDK succeeds:
-
-```kotlin
-// Basic calling setup
-val settings = UIKitSettings.UIKitSettingsBuilder()
-    .setAppId("APP_ID")
-    .setRegion("us")
-    .setAuthKey("AUTH_KEY")
-    .setEnableCalling(true)
-    .build()
-```
-
-For custom call settings:
-
-```kotlin
-import com.cometchat.calls.core.CometChatCalls
-
-// The kit stores/uses a SessionSettingsBuilder (no-arg ctor) — NOT CallSettingsBuilder.
-// setCallSettingsBuilder(Any) casts its arg to CometChatCalls.SessionSettingsBuilder
-// internally; passing a CallSettingsBuilder is silently stored as null.
-val sessionSettingsBuilder = CometChatCalls.SessionSettingsBuilder()
-    // configure via the SessionSettingsBuilder setters (see cometchat-android-v6-calls)
-
-val settings = UIKitSettings.UIKitSettingsBuilder()
-    .setAppId("APP_ID")
-    .setRegion("us")
-    .setAuthKey("AUTH_KEY")
-    .setEnableCalling(true)
-    .setCallSettingsBuilder(sessionSettingsBuilder)  // param typed Any; pass a SessionSettingsBuilder
-    .build()
-```
-
-After init, retrieve the stored builder:
-
-```kotlin
-val builder: CometChatCalls.SessionSettingsBuilder? = CometChatUIKit.getSessionSettingsBuilder()
-```
-
-## 4. Checking Initialization State
-
-```kotlin
-// Chat SDK initialized?
-CometChatUIKit.isSDKInitialized()
-
-// Calls SDK initialized? (only true if enableCalling was true AND init succeeded)
-CometChatUIKit.isCallsSDKInitialized()
-```
-
-## 5. Application-Level Init Pattern
-
-From `master-app-jetpack`, the recommended pattern separates SDK init from Calls SDK init:
-
-```kotlin
-class MyApplication : Application() {
-    fun onSDKInitialized() {
-        // Called after CometChatUIKit.init() succeeds
-        // CometChatCalls is auto-initialized if enableCalling = true
-        // Register call listeners here
-        addCallListener()
-    }
+"what can go in the settings file?", "turn on calling in the settings", "log in with a server-minted auth token instead of the auth key", "create a CometChat user from the app", "check who's logged in", "what does the UIKitSettings builder do?".
+
+## Prerequisites & install
+Same kit + init as `core`. Everything here is `com.cometchat.uikit.core` — no extra dependency.
+
+## The settings file (the DEFAULT input to `initFromSettings`)
+`app/src/main/assets/cometchat-settings.json` — **gitignored** (it carries the dev Auth Key). Read by `CometChatUIKit.initFromSettings(context, callback)`, which parses it, builds the settings, and persists `integrationSource="ai-agent"` for telemetry:
+```json
+{
+  "appId": "APP_ID",
+  "region": "REGION",
+  "credentials": { "authKey": "AUTH_KEY" },
+  "uiKit": {
+    "subscribePresenceForAllUsers": true,
+    "enableCalling": false
+  }
 }
 ```
-
-## Hard rules
-
-- NEVER set both `subscribePresenceForAllUsers()` and `subscribePresenceForRoles()` — only the last one takes effect
-- NEVER use `setAuthKey()` in production — use `loginWithAuthToken()` instead
-- `setEnableCalling(true)` requires the CometChatCalls SDK dependency in your Gradle file
-- If CometChatCalls init fails, the Chat SDK still reports success — check `isCallsSDKInitialized()` separately
-- `overrideAdminHost()` and `overrideClientHost()` are for on-premise deployments only — do not use with cloud-hosted CometChat
+- `appId` + `region` are **required** — missing either fails with `ERR_SETTINGS_INVALID`; a missing file fails with `ERR_SETTINGS_FILE_NOT_FOUND`.
+- `credentials.authKey` is **optional and dev-only** — omit it in production builds and log in with a server-minted auth token.
+- `uiKit.subscribePresenceForAllUsers` defaults to `true`.
+- `uiKit.enableCalling` defaults to `false`. Setting it `true` makes `initFromSettings` auto-initialize the **Calls SDK** — **which means the `com.cometchat:calls-sdk-android` dependency becomes MANDATORY.** Without it the app throws `NoClassDefFoundError: CometChatCalls$SessionSettingsBuilder` from `initCometChatCalls` **during `onCreate`, before any UI renders** (verified on device). The two must always change together (→ `cometchat-android-v6-calls`).
+- The Chat SDK may read an optional `chatSDK` section from the same file. It is **not required** — init succeeds without it. `/sdk/android/v5/setup.md` documents only the classic programmatic `init()` + `AppSettings`, so it will NOT tell you the section's keys; do not send the user there for them.
+
+## The legacy `UIKitSettings` builder (know it, don't default to it)
+`UIKitSettings.UIKitSettingsBuilder()` with `.setAppId(...)`, `.setRegion(...)`, `.setAuthKey(...)`, `.setEnableCalling(...)`, `.subscribePresenceForAllUsers()`, `.build()` feeds the classic `CometChatUIKit.init(context, settings, callback)` overload. **It still exists, but it is NOT the default** — it skips the integration-source telemetry that `initFromSettings` persists. Use it only when a project genuinely cannot ship an assets file (e.g. credentials arrive at runtime from your own backend); say so explicitly when you do, and keep credentials out of source either way.
+
+## Session / auth methods (`CometChatUIKit`)
+| Method | Use |
+|---|---|
+| `getLoggedInUser(): User?` | **Synchronous** guard — non-null means a session already exists; skip `login`. |
+| `login(uid, CallbackListener<User>)` | Dev/auth-key login for an **existing** user. |
+| `loginWithAuthToken(authToken, CallbackListener<User>)` | **Production** login with a server-minted per-user token. Auth Key never ships to the client. |
+| `logout(CallbackListener<String>)` | End the session. Unregister the push token BEFORE this (`cometchat-android-v6-push`). |
+| `createUser(user, CallbackListener<User>)` | Create a user from the app — **dev/prototype only**; production should mint users server-side with the REST API. |
+
+Ordering never changes: **init resolves → (guard) login resolves → chat UI**. Re-logging in a *different* user requires `logout` first. Full lifecycle detail (where to init, config changes, process death): `core/references/lifecycle.md`.
+
+## Message-helper reference (on the same docs page)
+`/ui-kit/android/methods` also documents date formatting and constructing `TextMessage` / `MediaMessage` / `CustomMessage` for programmatic sends — fetch that section rather than hand-rolling a message object; the SDK types are the Chat SDK's (`cometchat-android-v5-sdk` / `core/references/docs-map.md` → SDK section).
+
+## Common pitfalls
+Committing `cometchat-settings.json` (leaks the Auth Key) · shipping `credentials.authKey` in a release build · using the classic `init(...)` as the default (loses telemetry attribution) · calling `login` before init's `onSuccess` (fails silently) · re-logging in without `logout` · using `createUser` in production · assuming `enableCalling` alone adds calling (the Calls SDK artifact is still required) · reading `getLoggedInUser()` before init.
+
+## 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: with the settings file present, init reports success and login resolves; delete/rename the file → you get `ERR_SETTINGS_FILE_NOT_FOUND` surfaced as a readable error (not a crash); with `enableCalling: true` + the Calls artifact, call buttons appear (Views: automatic; Compose: only with `hideVoiceCallButton = false, hideVideoCallButton = false` on the header — `cometchat-android-v6-calls`); a release build contains no Auth Key (grep the merged assets). Confirm `cometchat-settings.json` is in `.gitignore`.