@cometchat/skills 4.4.2 → 5.0.0

package/skills/cometchat-android-v6-core/references/anti-patterns.md

@@ -0,0 +1,31 @@
+# anti-patterns — real bugs, do NOT do these (Android v6)
+
+> Ground truth: `ui-kit/android/getting-started-kotlin.md` / `getting-started-jetpack.md` (order Warnings), `troubleshooting.md` (docs), `conversation-message-view.md`, installed 6.0.5 kit source; verified 2026-08-20. Each entry: name → symptom → why → fix.
+
+1. **Hardcoded credentials in source.** *Symptom:* App ID/Auth Key string literals in a Kotlin file (the docs' `"APP_ID"` placeholders copied verbatim), key visible in git/APK. *Why:* credentials in code get committed and shipped; rotating them means a code change. *Fix:* the gitignored `assets/cometchat-settings.json` read by `initFromSettings` (`setup-credentials.md` §4); build-time extras via `local.properties` → `BuildConfig`.
+
+2. **Classic `init()` instead of `initFromSettings`.** *Symptom:* works, but integration telemetry attribution is lost. *Why:* only `CometChatUIKit.initFromSettings(context, callback)` persists `integrationSource="ai-agent"` (and auto-inits the Calls SDK from `uiKit.enableCalling`). *Fix:* always init via `initFromSettings` + the settings JSON; use `init(context, UIKitSettings, callback)` only on an explicit user request for programmatic settings (`lifecycle.md`).
+
+3. **`cometchat-settings.json` committed to git / Auth Key left in a release build.** *Symptom:* the dev Auth Key is in the repo history or shipped inside the APK's assets. *Why:* the Auth Key authenticates ANY UID — a leaked key is full account takeover of your chat app. *Fix:* gitignore `app/src/main/assets/cometchat-settings.json`; prod builds OMIT `credentials.authKey` and log in with a server-minted auth token (`loginWithAuthToken`).
+
+4. **Login before init resolves.** *Symptom:* login "fails silently" — no user, no obvious error, blank chat. *Why:* the docs Warning is explicit: *"`init()` must resolve before you call `login()`. Calling `login()` before init completes will fail silently."* *Fix:* call `login` ONLY inside init's `onSuccess` (`lifecycle.md`).
+
+5. **Rendering chat before init/login resolve.** *Symptom:* blank screen or a component stuck on its loading state, no data. *Why:* every `CometChat*` component assumes an initialized SDK + a logged-in user; docs: "Breaking this order = blank screen." *Fix:* the gate — render/navigate only after BOTH callbacks succeed; surface `onError` on the gate instead of proceeding.
+
+6. **Leaked listeners.** *Symptom:* duplicate real-time handling, callbacks firing into destroyed screens, memory leaks/crashes after back navigation. *Why:* an SDK `CometChat.addMessageListener(listenerId, ...)` (or a `CometChatEvents` flow collected in a scope that outlives the screen) registered in a lifecycle but never removed keeps the screen alive. *Fix:* pair every add with a remove in the matching teardown — `removeMessageListener(listenerId)` in `onPause`/`onDestroy` (Views) or a `DisposableEffect`/`lifecycleScope` collection that dies with the composable. (The drop-in components manage their OWN listeners — this applies to listeners YOU add.)
+
+7. **`wrap_content` collapse of the chat surface.** *Symptom:* a ~0dp sliver, or a list that grows into place as content loads. *Why:* list-shaped components fill their parent; a content-driven box gives them nothing to fill. *Fix:* `match_parent`/`0dp`+constraints / `fillMaxSize()`; message list at `0dp`+`layout_weight="1"` / `weight(1f)` (`layout.md` invariant 1/5).
+
+8. **Composer hidden under the keyboard.** *Symptom:* typing opens the IME over the input; the user can't see what they type. *Why:* the window doesn't resize for the IME. *Fix:* Views → `android:windowSoftInputMode="adjustResize"` on the chat Activity; Compose → `Modifier.imePadding()` on the column holding the composer (`layout.md` invariant 3).
+
+9. **Composer/header under the system bars.** *Symptom:* header text behind the status bar, send button behind the gesture/nav bar. *Why:* the docs call `enableEdgeToEdge()` — after that the app owns the insets, and unpadded content slides under the bars. *Fix:* `Scaffold(contentWindowInsets = WindowInsets.statusBars)` + `navigationBarsPadding()` (Compose) / root inset padding (Views) — or don't go edge-to-edge (`layout.md` invariant 2).
+
+10. **Dead thread affordance.** *Symptom:* tapping "Reply in thread" / a thread indicator does nothing. *Why:* the list renders the thread affordance by default, but navigation is the host's job — unwired `onThreadRepliesClick` dead-ends. *Fix:* wire `setOnThreadRepliesClick { message -> }` / `onThreadRepliesClick =` to a thread screen (`CometChatThreadHeader` + parent-scoped list + composer), or explicitly hide the option (`setReplyInThreadOptionVisibility(View.GONE)`). Same rule for the conversations search icon (`onSearchClick` → `CometChatSearch` or hide).
+
+11. **Mixing cohorts or mixing majors.** *Symptom:* duplicate class / resource-merge build errors, or two inconsistent chat UIs. *Why:* `chatuikit-kotlin-android` + `chatuikit-compose-android` in one app collide; a v5 `chat-uikit-android` alongside v6 `chatuikit-*` is a version_conflict. *Fix:* ONE cohort artifact, ONE major — the §3 STOP gate (`setup-credentials.md`).
+
+12. **Missing Cloudsmith maven repo.** *Symptom:* `Could not find com.cometchat:chatuikit-...` at sync/build. *Why:* the kit is not on mavenCentral. *Fix:* add `maven("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/")` to `settings.gradle(.kts)` `dependencyResolutionManagement.repositories`.
+
+13. **Treating same-user re-login as an error path (or switching users without logout).** *Symptom:* defensive re-login code, or a login error when switching accounts. *Why:* re-`login` with the SAME uid is safe (the kit returns the cached user via `onSuccess`, verified in 6.0.5), but logging in a DIFFERENT uid over an existing session errors. *Fix:* the guard — `getLoggedInUser()` same-uid → skip; different uid → `logout` first, login in its `onSuccess` (`lifecycle.md`).
+
+14. **Blocking the main thread waiting for callbacks.** *Symptom:* ANR, frozen splash, or a latch that never releases. *Why:* init/login callbacks are async and delivered on the main thread — `runBlocking`/`CountDownLatch.await()` on main deadlocks or janks. *Fix:* drive UI state from the callbacks (state flag / navigation in `onSuccess`), never wait synchronously.

package/skills/cometchat-android-v6-core/references/component-props.md

@@ -0,0 +1,168 @@
+# component-props — BAKED stable signatures for the Android v6 drop-ins
+
+> Ground truth: `ui-kit/android/conversations.md`, `message-header.md`, `message-list.md`, `message-composer.md` (+ `threaded-messages-header.md`, `search.md`, `conversation-message-view.md` for wiring), extracted from the pages' code fences per cohort and cross-checked against installed 6.0.5 kit source, verified 2026-08-20.
+
+The high-value, STABLE hooks for the 4 core drop-ins — baked so the golden path needs no
+fetch. Both cohorts use the SAME component names; **Compose = named params on the
+composable, Views = `set*` setters on the view** (XML tag = the fully-qualified class name,
+package `com.cometchat.uikit.kotlin.presentation.<component>.ui.<Name>`). Exhaustive/rare
+params still come from the page's `.md` twin (`docs-map.md`); anything below marked
+**FETCH** is not baked.
+
+## THE RULE — custom UI goes in the component's OWN slot, never stacked on top
+A custom header row, banner, or action button belongs in the component's view slot (tables
+below). Don't render it as a sibling above/beside the component.
+
+---
+
+## CometChatConversations
+**XML tag:** `<com.cometchat.uikit.kotlin.presentation.conversations.ui.CometChatConversations />` (size it `match_parent`).
+**Callbacks** (Views setter ⇄ Compose param — same lambda shape):
+- `setOnItemClick { conversation -> }` ⇄ `onItemClick = { conversation -> }` — the primary navigation hook (replaces built-in behavior).
+- `setOnSearchClick { }` ⇄ `onSearchClick = { }` — the toolbar search icon; wire to a `CometChatSearch` screen or hide the search affordance.
+- `setOnBackPress { }` ⇄ `onBackPress = { }` — toolbar back button.
+- `setOnItemLongClick { conversation -> }` ⇄ `onItemLongClick` · `setOnError { exception -> }` ⇄ `onError` · `setOnLoad { conversations -> }` ⇄ `onLoad` · `setOnEmpty { }` ⇄ `onEmpty` · `setOnSelection { selected -> }` ⇄ `onSelection` (with `setSelectionMode(UIKitConstants.SelectionMode.MULTIPLE)` ⇄ `selectionMode =`).
+**Functionality:** `setTitle("Chats")` ⇄ `title =` · `setToolbarVisibility(View.GONE)` ⇄ `hideToolbar = true` · `setSearchBoxVisibility(View.GONE)` ⇄ `hideSearchBox = true` · `setBackIconVisibility(View.VISIBLE)` ⇄ `hideBackIcon = false` (back icon hidden by default in Compose) · `setDisableSoundForMessages(true)` ⇄ `disableSoundForMessages = true`.
+
+**The request-builder scoping hook** (exact names from `conversations.md`):
+- Views: `conversations.setConversationsRequestBuilder(builder)`
+- Compose: `conversationsRequestBuilder = builder`
+```kotlin
+ConversationsRequest.ConversationsRequestBuilder()
+    .setConversationType(CometChatConstants.CONVERSATION_TYPE_USER)   // 1:1-only; _GROUP for groups-only
+    .setLimit(20)
+```
+**Pass the builder object, not `.build()`** — the component calls `.build()` internally
+(docs Warning; default page size 30, infinite scroll). A DM-only ask → `CONVERSATION_TYPE_USER`
+(hides seeded groups); groups-only → `CONVERSATION_TYPE_GROUP`; an unscoped "add chat" → omit the builder.
+
+**The selection flows into the message screen via `conversationWith`:**
+```kotlin
+onItemClick = { conversation ->
+    when (val entity = conversation.conversationWith) {   // User OR Group
+        is User -> navigateToUserChat(entity)
+        is Group -> navigateToGroupChat(entity)
+    }
+}
+```
+The SAME `User`/`Group` is then handed to header + list + composer (below). Views cohort
+passes it through Intent extras (`intent.putExtra("user", entity)` — the guide's pattern);
+Compose holds it in state / a nav route.
+
+## CometChatMessageHeader
+**XML tag:** `<com.cometchat.uikit.kotlin.presentation.messageheader.ui.CometChatMessageHeader />` (height `wrap_content`/`56dp`).
+**Target (required):** `setUser(user)` ⇄ `user =` OR `setGroup(group)` ⇄ `group =`.
+**Callbacks:** `setOnBackPress { }` ⇄ `onBackPress = { }` (REQUIRED on phones — pop back to the list) · `setOnError { exception -> }` ⇄ `onError`.
+**Functionality:** `setBackButtonVisibility(View.VISIBLE)` ⇄ `hideBackButton = false`. Presence/typing/member-count update automatically (SDK events handled internally).
+
+## CometChatMessageList
+**XML tag:** `<com.cometchat.uikit.kotlin.presentation.messagelist.ui.CometChatMessageList />` (`0dp` + `layout_weight="1"` between header and composer — `layout.md`).
+**Target (required):** `setUser(user)` ⇄ `user =` OR `setGroup(group)` ⇄ `group =` — without one the list shows only its loading indicator (docs Warning).
+**Callbacks:**
+- `setOnThreadRepliesClick { message -> }` ⇄ `onThreadRepliesClick = { message -> }` — receives the parent `BaseMessage`; navigate to the thread screen (default-on; hide only on explicit opt-out via `setReplyInThreadOptionVisibility(View.GONE)` / Compose hide-option param — FETCH the Compose name from `message-list.md` if needed).
+  ⚠️ **Signature note:** the installed 6.0.5 kit takes a single `BaseMessage` in BOTH cohorts (`fun setOnThreadRepliesClick(callback: ((BaseMessage) -> Unit)?)`); the docs page's `{ context, baseMessage, template -> }` fence is stale — bake the single-arg shape.
+- `setOnError { exception -> }` ⇄ `onError` · `setOnLoad { messages -> }` ⇄ `onLoad` · `setOnEmpty { }` ⇄ `onEmpty`.
+**Functionality:** `setMessagesRequestBuilder(MessagesRequest.MessagesRequestBuilder()...)` ⇄ `messagesRequestBuilder =` (same pass-the-builder-not-`.build()` rule) · `setStartFromUnreadMessages(true)` ⇄ `startFromUnreadMessages = true` · `setEnableMultipleAttachments(true)` ⇄ `enableMultipleAttachments = true` (default true).
+**Thread mode:** `setParentMessageId(id)` (Views, `Long`) ⇄ `parentMessageId = message.id` (Compose, default `-1` = main conversation) — a parent-scoped list for the thread screen. ⚠️ The `guide-threaded-messages.md` Views fence calls `messageList.setParentMessage(it.id)` — that setter doesn't exist on the list; the real one is `setParentMessageId` (verified in kit source + master app).
+
+## CometChatMessageComposer
+**XML tag:** `<com.cometchat.uikit.kotlin.presentation.messagecomposer.ui.CometChatMessageComposer />` (height `wrap_content`; create it in the Activity's `onCreate` — it registers an `ActivityResultLauncher` for permissions, docs Warning).
+**Target (required):** `setUser(user)` ⇄ `user =` OR `setGroup(group)` ⇄ `group =`.
+**Works with no extra wiring** for plain send/attachments/voice/emoji.
+**Callbacks (intercept-only):**
+- Compose: `onSendButtonClick = { context, baseMessage -> }` (docs + source agree) · `onError = { ... }` — ⚠️ the Compose source takes `(CometChatException) -> Unit` (one arg); the docs fence shows `{ context, exception -> }` — prefer the one-arg shape, verify on compile.
+- Views: ⚠️ installed 6.0.5 source is `setOnSendButtonClick(callback: (String) -> Unit)` (the typed text), NOT the docs' `{ context, baseMessage -> }` — treat the Views intercept as **FETCH/verify-on-compile**; for the golden path you don't wire it at all.
+**Thread mode:** `setParentMessageId(id)` ⇄ `parentMessageId = message.id` — replies land in the thread.
+
+## The thread screen (how the pieces compose — from `guide-threaded-messages.md` + `threaded-messages-header.md`)
+Takes BOTH the conversation target AND the parent message: `CometChatThreadHeader` —
+`setParentMessage(parentMessage)` ⇄ `parentMessage =` (a `BaseMessage`; display-only, no
+callbacks) — above a parent-scoped `CometChatMessageList` + `CometChatMessageComposer`
+(same `user`/`group` + `parentMessageId = parentMessage.id` on both).
+
+## CometChatSearch (the `onSearchClick` destination)
+Views `setOnBackPressListener { }` ⇄ Compose `onBackPress = { }` — you opened it, you close
+it (round-trip). Scope to one conversation with `setUid("...")`/`setGuid("...")` ⇄
+`uid =`/`guid =`; global search = neither. Full params: FETCH `search.md`.
+
+---
+
+## Slot / custom-view map (where custom UI goes)
+| Component | Views setter | Compose param | Region |
+|---|---|---|---|
+| Conversations | `setLeadingView(ConversationsViewHolderListener)` / `setTitleView(...)` / `setSubtitleView(...)` / `setTrailingView(...)` | `leadingView = { conversation, typingIndicator -> }` / `titleView` / `subtitleView` / `trailingView` | per-row sections |
+| Conversations | `setLoadingView(v)` / `setEmptyView(v)` / `setErrorView(v)` | `loadingView = { }` / `emptyView = { }` / `errorView = { onRetry -> }` | list states |
+| Conversations | `setOverflowMenu(view)` · `setOptions { ctx, conv -> }` / `setAddOptions { ctx, conv -> }` | `overflowMenu = { }` · `options = { ctx, conv -> }` / `addOptions` | toolbar menu · long-press menu (`CometChatPopupMenu.MenuItem`) |
+| MessageHeader | `setLeadingView(MessageHeaderViewHolderListener)` / `setSubtitleView(...)` / `setTrailingView(...)` / `setItemView(...)` | `leadingView = { user, group -> }` / `subtitleView` / `trailingView` / `itemView` (replaces whole header) | avatar · status line · right-side actions · whole row |
+| MessageList | `setHeaderView(view)` / `setFooterView(view)` · state views as above | `headerView = { }` / `footerView = { }` · state views | banner above / below the scroll |
+| MessageList | `set*ViewProvider(BubbleViewProvider)` (leading/header/reply/content/bottom/statusInfo/thread/footer) · `setBubbleFactories(list)` | per-bubble slot params `leadingView/headerView/.../footerView = { message, alignment -> }` · `bubbleFactories =` | inside every bubble / per message type — depth: FETCH `message-list.md` |
+| MessageComposer | `setHeaderView(view)` / `setSendButtonView(view)` / `setAuxiliaryButtonView(view)` / `setAttachmentOptions(list)` | `headerView = { }` / `sendButtonView = { }` / `auxiliaryButtonView = { }` / `attachmentOptions = listOf(CometChatMessageComposerAction(...))` | above input · send button · sticker/AI area · attach sheet |
+
+> Overriding `setAuxiliaryButtonView` REPLACES the sticker/AI buttons entirely — in 6.0.5 there is
+> **no accessor to re-fetch the defaults**: `CometChatUIKit.getDataSource()` and
+> `getAuxiliaryOption(...)` do **not** exist (the v4-era `ChatConfigurator.getDataSource()` /
+> `getAuxiliaryOptions()` slot architecture was removed — verified against chatuikit-core/kotlin 6.0.5).
+> If you must keep the defaults, add them into your custom view yourself; otherwise don't override the
+> whole auxiliary slot. (Styling and ViewModel injection: FETCH the page.)
+
+---
+
+## Import paths (verified against 6.0.5)
+
+Views components live at `com.cometchat.uikit.kotlin.presentation.<area>.ui.<Component>` —
+`conversations.ui.CometChatConversations`, `messagelist.ui.CometChatMessageList`,
+`search.ui.CometChatSearch`, `threadheader.ui.CometChatThreadHeader`, `users.ui.CometChatUsers`,
+`groups.ui.CometChatGroups`, `calllogs.ui.CometChatCallLogs`,
+`notificationfeed.ui.CometChatNotificationFeed`.
+
+**The three calling components have NO `.ui` segment** (verified against 6.0.5) — inferring the
+pattern gives `Unresolved reference 'ui'`:
+
+| Component | Import |
+|---|---|
+| `CometChatIncomingCall` | `…presentation.incomingcall.CometChatIncomingCall` |
+| `CometChatOutgoingCall` | `…presentation.outgoingcall.CometChatOutgoingCall` |
+| `CometChatCallButtons` | `…presentation.callbuttons.CometChatCallButtons` |
+
+SDK types the golden path also emits (not UI-Kit components, and not under `presentation`):
+
+| Type | Import |
+|---|---|
+| `AppEntity` (the `User`/`Group` supertype the search + conversation taps switch on) | `com.cometchat.chat.models.AppEntity` |
+| `CometChatConstants` (`RECEIVER_TYPE_*`, `GROUP_TYPE_*`, `CATEGORY_*`) | `com.cometchat.chat.constants.CometChatConstants` |
+
+Formatters are not under `presentation` at all: `com.cometchat.uikit.kotlin.shared.formatters.*`
+(`CometChatTextFormatter`, `CometChatMentionsFormatter`, `CometChatRichTextFormatter`). `SearchScope`
+is `com.cometchat.uikit.core.constants.SearchScope`. Compose swaps `kotlin` for `compose`.
+
+---
+
+## Callback shapes (Views, verified vs 6.0.5)
+
+| Component | Views setter | Shape |
+|---|---|---|
+| `CometChatConversations` | `setOnItemClick` | `(Conversation) -> Unit` |
+| `CometChatConversations` | `setOnSearchClick` | `() -> Unit` |
+| `CometChatMessageHeader` | `setOnBackPress` | `() -> Unit` |
+| `CometChatMessageList` | `setOnThreadRepliesClick` | `((BaseMessage) -> Unit)?` — **ONE arg** |
+| `CometChatMessageList` / `Composer` | `setParentMessageId` | `(Long)` |
+| `CometChatThreadHeader` | `setParentMessage` | `(BaseMessage)` |
+| `CometChatSearch` | `setOnConversationClick` | `((Conversation) -> Unit)?` — **ONE arg** |
+| `CometChatSearch` | `setOnMessageClick` | `((BaseMessage) -> Unit)?` — **ONE arg** |
+| `CometChatSearch` | `setSearchIn` | `(List<SearchScope>)` — import `com.cometchat.uikit.core.constants.SearchScope` |
+| `CometChatMessageHeader` | `setOnNewChatClick` | `(() -> Unit)` — **on the HEADER, not `CometChatConversations`**; a list-first app owns its own new-chat entry (tab/FAB) → `CometChatUsers` + `CometChatGroups` |
+| all four | `setUser` / `setGroup` | `(User)` / `(Group)` |
+
+---
+
+## Component / API map (BAKED closed list — from `catalogs/android-v6.json`)
+Session: `CometChatUIKit`, `UIKitSettings` (`com.cometchat.uikit.core`).
+Core surface: `CometChatConversations` · `CometChatMessageHeader` · `CometChatMessageList` · `CometChatMessageComposer` · `CometChatThreadHeader` · `CometChatSearch`.
+Grow set (on request): `CometChatUsers` · `CometChatGroups` · `CometChatGroupMembers` · `CometChatCallLogs` · `CometChatIncomingCall` · `CometChatNotificationFeed` · `CometChatAIAssistantChatHistory`.
+Namespaces: Views `com.cometchat.uikit.kotlin.presentation.<area>.ui.*` · Compose `com.cometchat.uikit.compose.presentation.<area>.ui.*`.
+**Not in the catalog ⇒ does not exist.** v6 ships **no combined shell** — `CometChatConversationsWithMessages`/`CometChatUI` are v4-era names. `CometChatMessageTemplate` is documented but **absent from 6.0.5** — verify before use. Full catalog: `cometchat-android-v6-{kotlin,compose}-components`.
+
+> ⚠️ **Docs drift — trust the reference table, not the docs.** `guide-threaded-messages` (Views tab) shows a **3-arg**
+> `setOnThreadRepliesClick { context, baseMessage, template -> }` and `messageList.setParentMessage(id)`.
+> Neither exists in 6.0.5: the callback takes **one** `BaseMessage`, and the list setter is
+> **`setParentMessageId(Long)`**. Logged internally.

package/skills/cometchat-android-v6-core/references/docs-map.md

@@ -0,0 +1,153 @@
+# docs-map — CometChat Android v6: 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 `<path>` the tables below list
+  (the conversations page path for your platform); the MCP resolves the `.md` twin and returns raw Markdown.
+  A full `https://…/docs/<path>` URL also works.
+- **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 `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`). The Android v6 UI Kit tree lives at the UNVERSIONED root: `/ui-kit/android/<page>`
+> (v5 is `/ui-kit/android/v5/...` — do not fetch it for a v6 build).
+> **Fetch rule:** always build a URL as `DOCS_BASE` + the path shown, then append `.md`.
+> Never hardcode a host anywhere else; never decompile the AAR or read kit source for signatures.
+
+## The convention
+`DOCS_BASE` + `<path>` + `.md` → raw Markdown (verbatim code +, on many pages, an "AI Integration
+Quick Reference" accordion). **Every component page carries a `Kotlin (XML Views)` tab AND a
+`Jetpack Compose` tab — read the tab for YOUR cohort** (the same `CometChat*` names, different wiring).
+```
+Fetch:  {DOCS_BASE}/ui-kit/android/conversations.md
+```
+Fallback order: `.md` twin → if it 404s, the same URL **without** `.md` (HTML) → **never** kit source.
+
+## Scoped Android v6 index (prefer over the global llms.txt)
+```
+{DOCS_BASE}/ui-kit/android/llms-android-v6.md
+```
+An Android-v6-only index of every page as a `.md` link — use it to discover any page not in the
+table below. Global all-products index (large; last resort): `{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 the table + the global `llms.txt`.
+
+## SDK docs — the FALLBACK reference (a feature the UI Kit has NO component for)
+The rule of the pack: **for every feature, first check whether the UI Kit has a component/param for it
+(this file's table + `component-props.md` + the catalog). If it does — USE it. If it does NOT** (e.g.
+AI agent events, transient messages, webhooks, low-level presence/connection, unread counts, granular
+group management) **— drop to the Android Chat SDK and call it directly** (the SDK is already installed
+under the UI Kit; init/login already use it). Look the method up in the SDK docs — never guess:
+```
+SDK_DOCS_BASE = https://www.cometchat.com/docs
+```
+- **SDK index (scoped — PREFER this):** `{SDK_DOCS_BASE}/sdk/android/v5/llms-android-v5.md` — an
+  **Android-SDK-v5-only** routing index grouped by area (Messaging · Calling · Users · Groups · AI &
+  advanced · Resources & listeners · Advanced). Start here to find the feature's page. Do NOT use the
+  site-wide `{SDK_DOCS_BASE}/llms.txt` except as a last resort. Same DOCS-GAP note as above.
+- **⚠️ URL trap:** Android SDK v5 pages are VERSIONED — `{SDK_DOCS_BASE}/sdk/android/v5/<page>` then
+  append `.md`. The unversioned `/sdk/android/<page>` tree is **v4** — never fetch it for a v5 build.
+- **Example:** flag a message → `{SDK_DOCS_BASE}/sdk/android/v5/flag-message.md` →
+  `CometChat.flagMessage(...)`, `CometChat.getFlagReasons(...)`.
+> Never hand-roll a feature that exists in the UI Kit OR the SDK, and never guess an SDK method —
+> look it up in the SDK index → the page.
+
+## Don't fetch the hot path — it's baked
+Install, `init → login → render`, and the core drop-in callbacks for "add chat" are BAKED in
+`cometchat-android-v6-core`. Fetch ONLY for exhaustive params/attrs / long-tail components /
+theming tokens / feature enablement.
+
+## The 80% trigger table  (URL = `{DOCS_BASE}` + path, then append `.md`)
+| Intent | Path (append `.md`) |
+|---|---|
+| setup / init / login (XML Views) | `/ui-kit/android/getting-started-kotlin` |
+| setup / init / login (Compose) | `/ui-kit/android/getting-started-jetpack` |
+| pick a chat experience / recipes | `/ui-kit/android/getting-started` · `one-to-one-chat` · `tab-based-chat` · `conversation-message-view` |
+| conversation list (full params) | `/ui-kit/android/conversations` |
+| message list | `/ui-kit/android/message-list` |
+| message composer | `/ui-kit/android/message-composer` |
+| message header | `/ui-kit/android/message-header` |
+| users / groups / group members | `/ui-kit/android/users` · `groups` · `group-members` |
+| threads | `/ui-kit/android/threaded-messages-header` |
+| message search | `/ui-kit/android/search` |
+| message templates / custom types | `/ui-kit/android/message-template` (⚠️ verify symbols vs catalog — see core map) |
+| voice/video call buttons | `/ui-kit/android/call-buttons` |
+| incoming / outgoing call UI | `/ui-kit/android/incoming-call` · `outgoing-call` |
+| call logs | `/ui-kit/android/call-logs` |
+| calls setup / enable calling | `/ui-kit/android/calling-integration` · `call-features` · Calls SDK: `/calls/android/setup` |
+| AI features (starter/replies/summary) | `/ui-kit/android/ai-features` |
+| AI agent chat / assistant history | `/ui-kit/android/guide-ai-agent` · `/ui-kit/android/ai-assistant-chat-history` |
+| notification feed | `/ui-kit/android/notification-feed` |
+| push setup (FCM) | `/notifications/push-overview` |
+| extensions (stickers/polls/translation…) | `/ui-kit/android/extensions` — **client half only**; see the enablement table below |
+| theming / colors / styling | `/ui-kit/android/theme-introduction` · `color-resources` · `component-styling` · `message-bubble-styling` |
+| customization (slots/styles/events/formatters…) | `/ui-kit/android/customization-overview` (+ the specific `customization-*` page) |
+| localization / sounds | `/ui-kit/android/localize` · `sound-manager` |
+| methods / events reference | `/ui-kit/android/methods` · `/ui-kit/android/events` |
+| full component list | `/ui-kit/android/components-overview` |
+| troubleshooting | `/ui-kit/android/troubleshooting` |
+| v5→v6 migration / upgrade | `/ui-kit/android/upgrading-from-v5` |
+
+## Enablement — the half that is NOT in `ui-kit/android`
+Most "add <feature>" asks have a **dashboard/extension prerequisite**. The component renders and
+nothing happens until it is switched on, so a skill that only wires the client has not finished the
+job. These pages live OUTSIDE the UI-Kit tree — say the prerequisite out loud to the user, and fetch
+the page when you need the exact steps.
+
+| Intent | Enablement page (append `.md`) |
+|---|---|
+| any extension — first stop | `/fundamentals/extensions-overview` |
+| polls · stickers | `/fundamentals/polls` · `/fundamentals/stickers` |
+| collaborative whiteboard / document | `/fundamentals/collaborative-whiteboard` · `/fundamentals/collaborative-document` |
+| link preview · thumbnail generation | `/fundamentals/link-preview` · `/fundamentals/thumbnail-generation` |
+| message translation | `/fundamentals/message-translation` |
+| smart replies · conversation starter · summary | `/fundamentals/ai-user-copilot/smart-replies` · `conversation-starter` · `conversation-summary` (overview: `/fundamentals/ai-user-copilot/overview`) |
+| AI agents | `/ai-agents` |
+| profanity filter / moderation | `/fundamentals/moderation-extensions` · `/moderation/overview` · `/moderation/getting-started` · `/moderation/rules-management` |
+| push notifications (Android) | `/notifications/push-overview` · **`/notifications/android-push-notifications`** · `/notifications/badge-count` |
+| campaigns / announcements | `/campaigns/campaigns` · `/campaigns/templates` · `/campaigns/channels` |
+| auth keys, roles, permissions | `/fundamentals/user-auth` · `/fundamentals/user-roles-and-permissions` |
+| server-side webhooks | `/fundamentals/webhooks-overview` · `/calls/webhooks` |
+
+> Both scoped LLM indexes now carry this same routing, so either door reaches it:
+> `{DOCS_BASE}/ui-kit/android/llms-android-v6.md` and
+> `{SDK_DOCS_BASE}/sdk/android/v5/llms-android-v5.md`.
+
+## Task guides (recipes) — for a whole FEATURE, BUILD FROM the guide + COMPARE against it (docs-maximal)
+For a TASK/feature ask (a whole capability, not just one component's params), the docs ship **full
+end-to-end guides**. **Discover them from the scoped llms index's "Task guides (recipes)" section**
+(`{DOCS_BASE}/ui-kit/android/llms-android-v6.md`) — the index is the source of truth (new guides appear
+there; do NOT bake this list). At time of writing it lists: `guide-overview` · `guide-threaded-messages` ·
+`guide-block-unblock-user` · `guide-new-chat` · `guide-message-privately` · `guide-call-log-details` ·
+`guide-group-chat` · `guide-search-messages` · `guide-ai-agent` · `custom-text-formatter-guide` ·
+`mentions-formatter-guide` · `shortcut-formatter-guide`.
+**Use the matching guide TWO ways — prefer it over baked recipe prose wherever a guide exists:**
+1. **As the implementation SOURCE** — fetch `{DOCS_BASE}/ui-kit/android/<guide>.md` (your cohort's tab)
+   and build the feature from the official recipe. **Adapt it ADDITIVELY** into the user's app (reuse
+   their navigation/theme/auth; never drop in the guide's standalone shell).
+2. **As a COMPLETENESS + CORRECTNESS check** — after you emit, DIFF your implementation against the
+   guide: every component, param, step, and affordance covered? Fill any gap.
+> **Then apply the baked HARDENING DELTAS on top — the guide is the BASELINE, not the whole truth:**
+> credentials via `local.properties`→`BuildConfig` (guides hardcode placeholders); the init→login gate
+> with failures surfaced; thread screens take the conversation target AND the parent message id;
+> IME/insets sizing (`references/layout.md`); wire-or-hide every default-on affordance; listener
+> teardown in the matching lifecycle. Build from the guide, then correct with these.
+
+**No matching guide in the index? → continue EXACTLY as before** — build from the pack's baked
+golden path + `component-props.md` and fetch each component's `.md` twin for exact params. **The guide
+is an ENHANCEMENT when present, never a hard dependency.**
+
+## Not in the table?
+Fetch the scoped index (`{DOCS_BASE}/ui-kit/android/llms-android-v6.md`), pick the page, fetch its `.md`.
+Never guess a path; never read kit source; never answer params from memory.

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

@@ -0,0 +1,112 @@
+# layout — the reflow-free chat surface (the ONE mobile sizing standard, Android v6)
+
+> Ground truth: `ui-kit/android/conversation-message-view.md` (both tabs, snippets verbatim) + `getting-started-*` (`enableEdgeToEdge`), cross-checked against the kit's sample-app manifests (`windowSoftInputMode="adjustResize"`), verified 2026-08-20.
+
+The single source of truth for how a CometChat surface is SIZED on Android so it renders
+full-size from the first frame, stays clear of system bars and the keyboard, and never
+reflows. `core`, `placement`, and `calls` POINT here — change the rule once, here.
+
+> **The kit is NOT the problem.** Every UI Kit component fills its parent by design and
+> ships its OWN loading/empty/error state. A chat surface that collapses, hides the
+> composer under the keyboard, or slides under the status bar is a HOST layout defect.
+
+## The five invariants (a correct surface satisfies ALL)
+
+**(1) Fill the parent — never `wrap_content` for the chat surface.**
+The conversations screen and the message screen each own their window: Views →
+`match_parent` (in a constraint layout, `0dp` + constraints, as the docs guide does);
+Compose → `Modifier.fillMaxSize()`. `wrap_content` on a list-shaped component collapses to
+~0dp before content loads and grows into place after — both broken. The composer/header
+are the exception: they are bars — `wrap_content` height (Views) / intrinsic height
+(Compose) by design.
+
+**(2) Edge-to-edge WITH insets.** The docs call `enableEdgeToEdge()` in every Activity
+`onCreate` — once you do, YOU own the status/nav-bar insets, or the header renders under
+the status bar and the composer under the gesture bar. Compose: the guide's exact recipe —
+```kotlin
+Scaffold(contentWindowInsets = WindowInsets.statusBars) { paddingValues ->
+    Column(
+        modifier = Modifier
+            .fillMaxSize()
+            .padding(paddingValues)
+            .consumeWindowInsets(paddingValues)
+            .navigationBarsPadding()
+            .imePadding()
+    ) { /* header / list / composer */ }
+}
+```
+Views: apply insets to the root (e.g. `ViewCompat.setOnApplyWindowInsetsListener` padding
+the root with `systemBars()` insets), or skip `enableEdgeToEdge()` entirely and let the
+system fit the window — never edge-to-edge WITHOUT inset handling.
+
+**(3) IME/keyboard-aware — the composer stays visible while typing.**
+- **Views:** the chat Activity needs `android:windowSoftInputMode="adjustResize"` in
+  `AndroidManifest.xml` (the kit's own sample apps set it on every chat activity). Without
+  it the keyboard overlays the composer.
+- **Compose:** `Modifier.imePadding()` on the column that holds the composer (guide recipe
+  above) — and make sure inset consumption (`consumeWindowInsets`) precedes it so padding
+  isn't applied twice. `adjustResize` in the manifest also helps Compose apps on older
+  inset paths; the samples set both.
+
+**(4) Loading states render INSIDE the full-size surface — no placeholder→chat jump.**
+The components ship their own loading/empty/error states and render them within the sized
+surface. Mount the sized surface immediately after the gate unlocks and let each component
+show its own state — do NOT swap a small "Loading…" layout for the chat layout (that IS
+the reflow). The only gate ABOVE the surface is init/login (`lifecycle.md`), and the docs'
+gate renders its spinner `fillMaxSize`, so even that swap is full-size → full-size.
+
+**(5) List scroll containment — the message list scrolls internally.**
+`CometChatMessageList` (and `CometChatConversations`) contain their own scrolling.
+- **Views:** never nest them in a `ScrollView`/`NestedScrollView`; in the vertical
+  `LinearLayout` the list takes `layout_height="0dp"` + `layout_weight="1"` between the
+  header and composer bars (docs guide, verbatim below).
+- **Compose:** never place them inside a `verticalScroll` or another `LazyColumn`
+  (nested unbounded-height measurement crashes/collapses); give the list `weight(1f)`
+  in the `Column` so it gets a bounded height and scrolls inside it.
+
+## The message-screen recipe (docs guide, verbatim shapes)
+
+**Views — `activity_message.xml`:**
+```xml
+<LinearLayout android:layout_width="match_parent" android:layout_height="match_parent"
+    android:orientation="vertical">
+    <com.cometchat.uikit.kotlin.presentation.messageheader.ui.CometChatMessageHeader
+        android:id="@+id/message_header"
+        android:layout_width="match_parent" android:layout_height="wrap_content" />
+    <com.cometchat.uikit.kotlin.presentation.messagelist.ui.CometChatMessageList
+        android:id="@+id/message_list"
+        android:layout_width="match_parent" android:layout_height="0dp"
+        android:layout_weight="1" />
+    <com.cometchat.uikit.kotlin.presentation.messagecomposer.ui.CometChatMessageComposer
+        android:id="@+id/message_composer"
+        android:layout_width="match_parent" android:layout_height="wrap_content" />
+</LinearLayout>
+```
+plus manifest: `<activity android:name=".MessageActivity" android:windowSoftInputMode="adjustResize" />`.
+
+**Compose — `MessageScreen`:** the Scaffold recipe in invariant (2) with, inside the Column:
+```kotlin
+CometChatMessageHeader(modifier = Modifier.fillMaxWidth(), user = user, group = group,
+    hideBackButton = false, onBackPress = onBack)
+CometChatMessageList(modifier = Modifier.fillMaxWidth().weight(1f), user = user, group = group)
+CometChatMessageComposer(modifier = Modifier.fillMaxWidth(), user = user, group = group)
+```
+
+The conversations screen is the same standard, one component:
+Views full-bleed `CometChatConversations` at `match_parent`/`0dp`+constraints; Compose
+`CometChatConversations(modifier = Modifier.fillMaxSize(), ...)`.
+
+> ⚠️ **The list and search routes need insets too, not just the message route.** `fillMaxSize()` under `enableEdgeToEdge()` draws the title under the status-bar clock (verified on device). Wrap every full-screen route in `Scaffold(contentWindowInsets = WindowInsets.statusBars)` — the same recipe this file reserves for the message screen. Skipping it here contradicts layout invariant (2): never edge-to-edge WITHOUT inset handling.
+
+## Embedded (not full-screen)
+Same invariants against the embedding cell: give the chat region a bounded height (a sized
+fragment container / a `weight`ed cell / a fixed `Modifier.height(...)`) — never
+`wrap_content`/unbounded — and keep (3)–(5) unchanged. Bottom-nav/tab shells: size the tab
+content pane, not the component (`cometchat-android-v6-{kotlin,compose}-placement`).
+
+## Verify (advisory, human check)
+Full-size from the first frame (the kit's own loading state fills the screen, no small box
+that grows); header below the status bar and composer above the gesture/nav bar with
+edge-to-edge on; open the keyboard → the composer rides above it and the list shrinks (no
+overlay); the message list scrolls internally with header/composer pinned; rotate → no
+collapse, no re-init (`lifecycle.md`).

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

@@ -0,0 +1,75 @@
+# lifecycle — init once, login guard, logout (Android v6)
+
+> Ground truth: installed `chatuikit-core-android` 6.0.5 `CometChatUIKit.kt` (`initFromSettings`/`login`/`loginWithAuthToken`/`logout`/`getLoggedInUser`/`isSDKInitialized`) + `ui-kit/android/getting-started-kotlin.md` / `getting-started-jetpack.md` (gate pattern), verified 2026-08-20.
+
+## Init once — via `initFromSettings`, and where it lives
+The canonical init is **`CometChatUIKit.initFromSettings(context, callback)`** — it reads the gitignored `app/src/main/assets/cometchat-settings.json` (`setup-credentials.md` §4), persists `integrationSource="ai-agent"` for telemetry attribution, and auto-inits the Calls SDK when `uiKit.enableCalling` is true. A classic `init(context, UIKitSettings, callback)` overload also exists on `CometChatUIKit`, but **do not use it as the default — it loses the telemetry attribution** (AUDIT-084); reach for it only when a user explicitly needs programmatic settings.
+
+Init is async; **nothing CometChat renders until `onSuccess` fires** (docs Warning: *"`init()` must resolve before you call `login()`. Calling `login()` before init completes will fail silently."*). Two valid placements:
+
+- **Gate Activity (RECOMMENDED — the docs getting-started pattern):** the launcher/splash Activity runs `initFromSettings → login` and only then navigates to (Views) / renders (Compose) the chat UI. Failures surface on the gate screen instead of a blank chat.
+- **Application.onCreate:** fine for init alone, but you still need a ready-gate before any `CometChat*` UI renders, and login usually depends on app auth state — so you end up building the gate anyway. Use it only when every screen needs CometChat from frame 1.
+
+**Do NOT re-init per Activity/screen.** Init once per process. If a later entry point can't be sure init ran (deep link, notification tap, process death restoring a back stack), guard with `CometChatUIKit.isSDKInitialized()` — if false, route through the gate rather than sprinkling init calls through the app.
+
+## The exact init shape (both cohorts — same code)
+```kotlin
+import com.cometchat.chat.core.CometChat
+import com.cometchat.chat.exceptions.CometChatException
+import com.cometchat.chat.models.User
+import com.cometchat.uikit.core.CometChatUIKit
+
+// Reads app/src/main/assets/cometchat-settings.json (appId, region, credentials.authKey,
+// uiKit.subscribePresenceForAllUsers/enableCalling) and persists integrationSource="ai-agent".
+CometChatUIKit.initFromSettings(this, object : CometChat.CallbackListener<String>() {
+    override fun onSuccess(s: String) { loginUser() }             // init resolved — ONLY now login
+    override fun onError(e: CometChatException?) {
+        // SURFACE it — show e?.message on the gate screen; do NOT proceed to chat.
+        // ERR_SETTINGS_FILE_NOT_FOUND → the assets JSON is missing; ERR_SETTINGS_INVALID → appId/region missing.
+    }
+})
+```
+(Compose cohort: hold `isReady`/`error` in `mutableStateOf` and let `setContent` render error → spinner → `ChatApp()` — the getting-started-jetpack gate; Views cohort: `startActivity` to the conversations screen only from login's `onSuccess`, as getting-started-kotlin does.)
+
+## Login guard — skip if logged in; logout before switching users
+```kotlin
+private fun loginUser() {
+    val existing = CometChatUIKit.getLoggedInUser()          // sync; null if nobody logged in
+    if (existing != null && existing.uid == uid) { unlockChatUi(); return }   // same user → done
+    // DIFFERENT user still logged in → logout FIRST, then login in its onSuccess
+    CometChatUIKit.login(uid, object : CometChat.CallbackListener<User>() {
+        override fun onSuccess(user: User) { unlockChatUi() }
+        override fun onError(e: CometChatException) { /* surface e.message — e.g. ERR_UID_NOT_FOUND */ }
+    })
+}
+```
+- **Same UID re-login is safe:** the kit short-circuits and returns the cached user via `onSuccess` (verified in 6.0.5 source) — but the guard keeps intent obvious and skips a needless call.
+- **Different UID while logged in:** call `CometChatUIKit.logout(...)` and only login in its `onSuccess` — logging in over an existing session errors.
+- The UID comes from the user / dashboard (`setup-credentials.md` §7) — never hardcoded in shipped code.
+
+## Production login — auth token, not Auth Key
+Mint a per-user token server-side (CometChat REST API), then:
+```kotlin
+CometChatUIKit.loginWithAuthToken(authToken, object : CometChat.CallbackListener<User>() {
+    override fun onSuccess(user: User) { unlockChatUi() }
+    override fun onError(e: CometChatException) { /* surface */ }
+})
+```
+Prod builds OMIT `credentials.authKey` from `cometchat-settings.json` (`appId`/`region` stay — they're not secrets). Never ship the Auth Key in a release build (docs Warning on both getting-started pages).
+
+## Logout
+```kotlin
+CometChatUIKit.logout(object : CometChat.CallbackListener<String>() {
+    override fun onSuccess(s: String) { /* route to your sign-in screen */ }
+    override fun onError(e: CometChatException?) { /* surface */ }
+})
+```
+Call on app sign-out (it also clears the calls session when calling is enabled). After logout, the next chat entry must pass back through the gate.
+
+## Process death & configuration changes
+- **Config change (rotation/theme):** the SDK is a process-level singleton — the Activity recreates, init/login state survives. Do NOT re-run init in every `onCreate` unconditionally; the gate + `isSDKInitialized()` / `getLoggedInUser()` guards make re-entry a no-op.
+- **Process death:** Android may recreate a deep Activity with the process cold. Any Activity that hosts `CometChat*` views must tolerate this: check `CometChatUIKit.isSDKInitialized()` (and `getLoggedInUser() != null`) in `onCreate`; if not ready, bounce to the gate (which re-inits and re-logs-in via the guards) instead of rendering a dead chat surface.
+- **Login session persists** across launches on the device — on warm starts `getLoggedInUser()` is non-null and the gate skips straight past login.
+
+## Surfacing CometChatException — never swallow
+Every callback's `onError` hands you a `CometChatException` — log it AND show the user something actionable (`e.message`; wrong Region, a missing settings file, and a missing UID are the three most common). A swallowed `onError` is the #1 cause of "blank screen, no errors" (`troubleshooting.md`). Do not block the main thread waiting for callbacks (no latches/`runBlocking`) — they already arrive on the main thread; drive UI state from them.