@cometchat/skills 4.3.0 → 4.4.0

package/skills/cometchat-android-v6-compose-components/SKILL.md

@@ -3,13 +3,14 @@ name: cometchat-android-v6-compose-components
 description: "CometChat Android UIKit v6 Jetpack Compose component catalog — all @Composable chat UI components, their parameters, styles, and usage"
 license: "MIT"
 compatibility: "Android 9.0+ (API 28); Kotlin 1.9+; com.cometchat:chatuikit-compose-android:6.x"
-allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"
   tags: "cometchat, android, compose, components, conversations, messages, users, groups, calls"
 ---
 
+> **Ground truth:** `com.cometchat:chatuikit-compose-android:6.x` component catalog (javap the AAR) + `docs/ui-kit/android/v6`. **Official docs:** https://www.cometchat.com/docs/ui-kit/android/v6/components-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.
+
 > **Companion skills:** cometchat-android-v6-kotlin-components (Views equivalent), cometchat-android-v6-compose-theming, cometchat-android-v6-compose-customization, cometchat-android-v6-compose-placement
 
 ## Purpose
@@ -31,6 +32,7 @@ Complete catalog of all Jetpack Compose components in CometChat UIKit v6. Each c
 
 ## 1. Component Catalog
 
+> ⛔ **Only the `@Composable`s in THIS catalog exist — do not invent or recall names from v4/older memory.** Before emitting any `CometChat*` composable, confirm it's listed below; if it's not here, it doesn't exist (→ "unresolved reference" compile error). **There is no all-in-one composable:** the v4-era composites `CometChatConversationsWithMessages` / `CometChatUsersWithMessages` / `CometChatGroupsWithMessages` / `CometChatMessages` and the `CometChatUI` god-component do **not** exist in v6 Android (verified against the v6 Kotlin-Views kit, which the Compose stack mirrors). Compose a two-pane experience yourself: `CometChatConversations()` (list) → on item-click, host `CometChatMessageHeader()` + `CometChatMessageList()` + `CometChatMessageComposer()` for the selected `User`/`Group`.
 
 ### 1.1 List Components
 
@@ -44,6 +46,8 @@ Complete catalog of all Jetpack Compose components in CometChat UIKit v6. Each c
 
 ### 1.2 Messaging Components
 
+> ⚠️ **There is NO combined `CometChatMessages` composable on Android Compose.** Unlike React / Flutter / Android V5 (Views), the V6 Compose surface ships the three pieces separately and you compose the chat screen manually as `CometChatMessageHeader + CometChatMessageList + CometChatMessageComposer` in a `Column` (see §2.2). Do not import `com.cometchat.uikit.compose.presentation.cometchatmessages.CometChatMessages` — that package does not exist (ENG-35698 fix).
+
 | Component | Package | Purpose |
 |---|---|---|
 | `CometChatMessageList` | `presentation.messagelist.ui` | Message list with bubbles |
@@ -74,6 +78,7 @@ Complete catalog of all Jetpack Compose components in CometChat UIKit v6. Each c
 | `CometChatImageViewerScreen` | `presentation.imageviewer.ui` | Full-screen image viewer |
 | `CometChatFlagMessageDialog` | `presentation.report` | Report/flag message |
 | `CometChatAIAssistantChatHistory` | `presentation.aiassistantchathistory.ui` | AI chat history |
+| `CometChatNotificationFeed` | `presentation.notificationfeed.ui` | Full-screen notification feed (category filter chips, timestamp grouping, rich cards, real-time updates) |
 
 ### 1.5 Shared Elements
 
@@ -93,40 +98,61 @@ The `preview/` package provides preview data, domain models, and presentation he
 
 ## 2. Basic Usage Examples
 
+> **`CometChatTheme {}` is applied ONCE at the app root, outside the `NavHost` — not per screen.** The examples below assume that root wrapper is already in place (see `cometchat-android-v6-compose-placement` §1), so individual screens do NOT re-wrap in `CometChatTheme {}`. Nesting multiple `CometChatTheme {}` wrappers is an anti-pattern.
+
 ### 2.1 Conversations List
 
 ```kotlin
 import com.cometchat.uikit.compose.presentation.conversations.ui.CometChatConversations
-import com.cometchat.uikit.compose.theme.CometChatTheme
 
 @Composable
 fun ConversationsScreen(onConversationClick: (Conversation) -> Unit) {
-    CometChatTheme {
-        CometChatConversations(
-            onItemClick = { conversation ->
-                onConversationClick(conversation)
-            }
-        )
-    }
+    CometChatConversations(
+        onItemClick = { conversation ->
+            onConversationClick(conversation)
+        }
+    )
 }
 ```
 
 ### 2.2 Message List
 
+The chat screen composes the three pieces in a `Column`. Match the kit sample app (`sample-app-compose/.../messages/MessagesScreen.kt`): wrap in a `Scaffold(contentWindowInsets = WindowInsets.statusBars)` and give the `Column` `.navigationBarsPadding().imePadding()` so the soft keyboard pushes the composer up instead of covering it. Header and Composer take `Modifier.fillMaxWidth()`; the List takes `weight(1f)`.
+
 ```kotlin
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.WindowInsets
+import androidx.compose.foundation.layout.consumeWindowInsets
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.imePadding
+import androidx.compose.foundation.layout.navigationBarsPadding
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.statusBars
+import androidx.compose.material3.Scaffold
+import androidx.compose.ui.Modifier
 import com.cometchat.uikit.compose.presentation.messagelist.ui.CometChatMessageList
 import com.cometchat.chat.models.User
 
 @Composable
 fun ChatScreen(user: User) {
-    CometChatTheme {
-        Column {
-            CometChatMessageHeader(user = user)
+    Scaffold(contentWindowInsets = WindowInsets.statusBars) { paddingValues ->
+        Column(
+            modifier = Modifier
+                .fillMaxSize()
+                .padding(paddingValues)
+                .consumeWindowInsets(paddingValues)
+                .navigationBarsPadding()
+                .imePadding()
+        ) {
+            CometChatMessageHeader(modifier = Modifier.fillMaxWidth(), user = user)
             CometChatMessageList(
                 user = user,
-                modifier = Modifier.weight(1f)
+                modifier = Modifier
+                    .fillMaxWidth()
+                    .weight(1f)
             )
-            CometChatMessageComposer(user = user)
+            CometChatMessageComposer(modifier = Modifier.fillMaxWidth(), user = user)
         }
     }
 }
@@ -137,13 +163,11 @@ fun ChatScreen(user: User) {
 ```kotlin
 @Composable
 fun UsersScreen() {
-    CometChatTheme {
-        CometChatUsers(
-            onItemClick = { user ->
-                // Navigate to chat with user
-            }
-        )
-    }
+    CometChatUsers(
+        onItemClick = { user ->
+            // Navigate to chat with user
+        }
+    )
 }
 ```
 
@@ -152,13 +176,11 @@ fun UsersScreen() {
 ```kotlin
 @Composable
 fun GroupsScreen() {
-    CometChatTheme {
-        CometChatGroups(
-            onItemClick = { group ->
-                // Navigate to group chat
-            }
-        )
-    }
+    CometChatGroups(
+        onItemClick = { group ->
+            // Navigate to group chat
+        }
+    )
 }
 ```
 
@@ -177,6 +199,7 @@ Every component has a corresponding `@Immutable data class` style in its `style/
 | `CometChatMessageHeader` | `CometChatMessageHeaderStyle` | `.default()` |
 | `CometChatCallLogs` | `CometChatCallLogsStyle` | `.default()` |
 | `CometChatThreadHeader` | `CometChatThreadHeaderStyle` | `.default()` |
+| `CometChatNotificationFeed` | `CometChatNotificationFeedStyle` | constructor (`Color.Unspecified` defaults) + `.fromTheme(overrides)` |
 
 Usage:
 
@@ -196,7 +219,7 @@ Each component creates its own ViewModel internally via factories from `chatuiki
 
 ## Hard rules
 
-- ALWAYS wrap CometChat Compose components in `CometChatTheme {}` — they depend on `CompositionLocal` theme values
+- CometChat Compose components depend on `CometChatTheme {}` `CompositionLocal` values — apply `CometChatTheme {}` ONCE at the app root (outside the `NavHost`), NOT per screen; never nest multiple `CometChatTheme {}` wrappers
 - Components create their own ViewModels internally — do NOT try to create or inject ViewModels manually
 - Style classes use `Companion.default()` factory functions — do NOT use the data class constructor directly (it requires all parameters)
 - All style defaults source from `CometChatTheme` tokens — override only what you need via named parameters

package/skills/cometchat-android-v6-compose-customization/SKILL.md

@@ -3,13 +3,14 @@ name: cometchat-android-v6-compose-customization
 description: "CometChat Android UIKit v6 Compose customization — BubbleFactory interface, slot lambdas, @Immutable style classes, and per-slot overrides"
 license: "MIT"
 compatibility: "Android 9.0+ (API 28); Kotlin 1.9+; com.cometchat:chatuikit-compose-android:6.x"
-allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"
   tags: "cometchat, android, compose, customization, bubble-factory, slots, style"
 ---
 
+> **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.
+
 > **Companion skills:** cometchat-android-v6-kotlin-customization (Views equivalent), cometchat-android-v6-compose-components, cometchat-android-v6-compose-theming, cometchat-android-v6-extensions (DataSource layer), cometchat-android-v6-events
 
 ## Purpose
@@ -135,6 +136,139 @@ override fun onDispose(message: BaseMessage) {
 }
 ```
 
+### 1.7 Custom attachment options (Scenario 3) — pass the `attachmentOptions` parameter
+
+A `BubbleFactory` only *renders* a custom type; to let users *create* one you usually add a composer attachment action. On Compose the canonical path is the **`attachmentOptions` parameter** on `CometChatMessageComposer` — a `List<CometChatMessageComposerAction>` whose contents are added **after** the built-in options.
+
+```kotlin
+CometChatMessageComposer(
+    user = user,
+    attachmentOptions = listOf(
+        CometChatMessageComposerAction(
+            id = "location",
+            title = "Send Location",
+            icon = R.drawable.ic_location,
+            onClick = OnClick { /* pick + send (see 1.8) */ }
+        )
+    )
+)
+```
+
+**Append is automatic — your list does NOT replace the defaults.** Internally the composable calls `composerViewModel.setAttachmentOptions(attachmentOptions)` (`CometChatMessageComposer.kt:431-432`), which sets only the *custom* options list (`_customAttachmentOptions`). The defaults (camera/image/video/audio/document/poll/collab-doc/collab-whiteboard) are rebuilt every time by `getDefaultAttachmentOptions(...)` and your custom options are concatenated at the end (`CometChatMessageComposerViewModel.kt:646-649`). There is no "wipe defaults" footgun here — `setAttachmentOptions` despite its name does NOT drop the built-ins.
+
+> Hide a built-in instead with the composer's `hide*Option` flags (e.g. `hidePollOption = true`), which flip the `_show*Option` visibility checked inside `getDefaultAttachmentOptions`.
+
+If you hold a `CometChatMessageComposerViewModel` directly (advanced), `addAttachmentOption(action)` appends one custom option and `setAttachmentOptions(list)` replaces the custom list — both verified at `CometChatMessageComposerViewModel.kt:657 / :666`. The built-in option IDs are constants on `CometChatMessageComposerAction` (`ID_CAMERA`, `ID_IMAGE`, `ID_VIDEO`, `ID_AUDIO`, `ID_DOCUMENT`, `ID_POLL`, `ID_COLLABORATIVE_DOCUMENT`, `ID_COLLABORATIVE_WHITEBOARD` — `CometChatMessageComposerAction.kt:42-49`).
+
+### 1.8 Sending a custom message — use the UIKit path, not the raw SDK
+
+```kotlin
+val message = CustomMessage(
+    receiverId,
+    CometChatConstants.RECEIVER_TYPE_USER,   // or RECEIVER_TYPE_GROUP
+    "location",                              // matches the BubbleFactory type
+    customData                               // org.json.JSONObject
+)
+// ✅ kit path — sets muid + sender, fires ccMessageSent → list APPENDS
+CometChatUIKit.sendCustomMessage(message, object : CometChat.CallbackListener<CustomMessage>() {
+    override fun onSuccess(p0: CustomMessage) {}
+    override fun onError(p0: CometChatException) {}
+})
+// ❌ CometChat.sendCustomMessage(...) — no muid/sender/event → recipient error + realtime replace
+```
+
+Verified (v6 core/compose): `CometChatMessageComposer(attachmentOptions = …)` param (`CometChatMessageComposer.kt:338`), `CometChatMessageComposerViewModel.addAttachmentOption / setAttachmentOptions / getDefaultAttachmentOptions` (`:657 / :666 / :547`), `CometChatUIKit.sendCustomMessage(CustomMessage, CallbackListener)` (`CometChatUIKit.kt:472`).
+
+### 1.9 Override an EXISTING type's bubble (Scenario 2)
+
+To replace the rendering of a built-in type (e.g. text or image), register a `BubbleFactory` whose `getCategory()`/`getType()` **match the built-in identifiers**. Built-in types are NOT pre-seeded as factory entries — the bubble falls back to `InternalContentRenderer` only when no factory matches a `"category_type"` key (`CometChatMessageBubble.kt:155` "Falls back to InternalContentRenderer if no factory is provided"). So a matching factory simply takes priority over the internal default.
+
+```kotlin
+import com.cometchat.chat.constants.CometChatConstants
+
+class MyTextBubbleFactory : BubbleFactory {
+    override fun getCategory(): String = CometChatConstants.CATEGORY_MESSAGE   // "message"
+    override fun getType(): String = CometChatConstants.MESSAGE_TYPE_TEXT      // "text"
+
+    override fun getContentView(
+        message: BaseMessage,
+        alignment: UIKitConstants.MessageBubbleAlignment,
+        style: CometChatMessageBubbleStyle,
+        textFormatters: List<CometChatTextFormatter>
+    ): @Composable () -> Unit = {
+        MyCustomTextContent(message as TextMessage)   // only the content area
+    }
+    // …or override getBubbleView() to replace the whole bubble (see 1.3)
+}
+
+CometChatMessageList(user = user, bubbleFactories = listOf(MyTextBubbleFactory()))
+```
+
+This is still additive at the list level: registering a `message_text` factory only overrides text bubbles; image/video/custom types keep their internal rendering. Use `getContentView()` for content-only override, `getBubbleView()` for full-bubble replacement.
+
+### 1.10 Add a long-press message option (Scenario 4 — Forward-style)
+
+`CometChatMessageList` exposes two lambda parameters for the long-press option sheet (`CometChatMessageList.kt:577-598`):
+
+| Param | Type | Semantics |
+|---|---|---|
+| `addOptions` | `((BaseMessage) -> List<CometChatMessageOption>)?` | **Append** after the defaults |
+| `options` | `((BaseMessage) -> List<CometChatMessageOption>?)?` | **Replace** all defaults (takes precedence over `addOptions`; return `null` to keep defaults) |
+| `onMessageOptionClick` | `((BaseMessage, optionId: String, optionName: String) -> Unit)?` | Click handler |
+
+Use `addOptions` for a Forward-style action so the built-in Reply/Copy/Edit/Delete survive:
+
+```kotlin
+import com.cometchat.uikit.core.domain.model.CometChatMessageOption
+
+CometChatMessageList(
+    user = user,
+    addOptions = { message ->            // ✅ appended to defaults
+        listOf(
+            CometChatMessageOption(
+                id = "forward",
+                title = "Forward",
+                icon = R.drawable.ic_forward,
+                onClick = { /* open forward picker for `message` */ }
+            )
+        )
+    }
+    // ❌ options = { listOf(forward) }   // would DROP reply/copy/edit/delete
+)
+```
+
+`CometChatMessageOption(id, title, titleColor, icon, iconTintColor, …, onClick)` is a data class at `CometChatMessageOption.kt:21`. Resolution order is verified in `CometChatMessageListViewModel.resolveMessageOptions` (`:817-827`): `setOptions` result wins if non-null, else `defaultOptions + addOptions`.
+
+### 1.11 MessageTemplate via the DataSource (docs-taught alternative to BubbleFactory)
+
+> ⚠️ **Verify before using — symbols not found in the GA v6 Compose source.** `CometChatUIKit.getDataSource()`, `getMessageTemplates()`, `CometChatMessageTemplate`, and a `templates` parameter on the Compose `CometChatMessageList` appear in the Android **docs** but are **absent from the verified `com.cometchat.uikit.compose` GA source** (they're the legacy `com.cometchat.chatuikit` v5-shaped API; the Compose list only exposes `bubbleFactories`). Treat this section as a docs reference that may not compile against your installed v6 kit — **prefer `BubbleFactory` (the confirmed v6-native path) for all new code.**
+
+The `BubbleFactory` / slot-lambda surface above is the primary v6 customization path. The Android docs also teach a **`MessageTemplate`** path through the data source ([message-template](https://www.cometchat.com/docs/ui-kit/android/v6/message-template)) — fetch the existing templates, mutate the one you want, then re-apply (append, never replace with a single-item list):
+
+```kotlin
+// 1. fetch existing templates from the data source
+val templates = CometChatUIKit.getDataSource()
+    .getMessageTemplates(additionParameter)   // pass the list's additionParameter
+    .toMutableList()
+
+// 2. mutate the template you want (or create a new one for a custom type)
+templates.find { it.type == UIKitConstants.MessageType.TEXT }
+    ?.setContentView { baseMessage, alignment ->
+        Text(text = (baseMessage as? TextMessage)?.text ?: "")
+    }
+// new custom type:
+val contact = CometChatMessageTemplate().apply {
+    setType("contact"); setCategory(UIKitConstants.MessageCategory.CUSTOM)
+    setContentView { baseMessage, _ -> /* custom composable */ }
+}
+templates.add(contact)
+
+// 3. re-apply — Compose passes the list to CometChatMessageList
+CometChatMessageList(user = user, templates = templates)
+```
+
+Compose templates expose lambda slot setters (`setContentView`, `setHeaderView`, `setFooterView`, `setBottomView`, `setStatusInfoView`, `setBubbleView`, `setOptions`) mirroring §2's slots. Prefer `BubbleFactory` for new code; use `getMessageTemplates(...)` when you want to start from the kit's defaults and tweak one type. (This overlaps the custom-message topic.)
+
 ## 2. Slot Lambda Parameters (Per-Slot Overrides)
 
 Override individual slots across ALL message types directly on `CometChatMessageList`:
@@ -270,6 +404,23 @@ CometChatMessageList(
 | No bubble replacement | `getBubbleView()` for complete replacement |
 | Theme-level styling only | Per-factory `getBubbleStyle()` |
 
+## Text formatters (inline mentions / URLs / custom tokens)
+
+Style/transform message text inline by passing `textFormatters` to the composer/list. The kit ships `CometChatMentionsFormatter` + `CometChatRichTextFormatter` (subclasses of the abstract `CometChatTextFormatter`) in `com.cometchat.uikit.compose.presentation.shared.formatters`. Default behavior (a mentions formatter) applies when you pass nothing — so to ADD a custom one, include the defaults too.
+
+```kotlin
+import com.cometchat.uikit.compose.presentation.shared.formatters.CometChatMentionsFormatter
+import com.cometchat.uikit.compose.presentation.shared.formatters.CometChatTextFormatter
+
+CometChatMessageComposer(
+    user = user,
+    textFormatters = listOf(CometChatMentionsFormatter(context) /* , YourFormatter(context) */),
+)
+// CometChatMessageList also takes textFormatters: List<CometChatTextFormatter>.
+```
+
+For a custom @/#/! token: subclass `CometChatTextFormatter(trackingCharacter)` and implement its `search()` + view hooks (see the kit's `formatters/` source + the per-platform docs).
+
 ## Hard rules
 
 - BubbleFactory is an `interface` — implement it, don't extend an abstract class
@@ -278,3 +429,7 @@ CometChatMessageList(
 - Slot lambda parameters on `CometChatMessageList` override BubbleFactory slot methods — use lambdas for cross-type overrides, factories for per-type overrides
 - Style classes must use `Companion.default()` factory — the data class constructor requires ALL parameters
 - Do NOT confuse BubbleFactory (UI rendering) with DataSource (data fetching) — they are separate layers
+
+## Sound (in-app message + call sounds)
+
+Sound is a customization sub-dimension. The UI Kit plays incoming/outgoing message + call sounds via `CometChatSoundManager` — mute it, swap custom audio, or play a specific sound. The full API + recipe lives in **`cometchat-android-v6-compose-theming`** (Sound section). Verify the access path against the installed kit before relying on it.

package/skills/cometchat-android-v6-compose-placement/SKILL.md

@@ -3,18 +3,19 @@ name: cometchat-android-v6-compose-placement
 description: "CometChat Android UIKit v6 Compose placement — setContent, Compose Navigation, Dialog, BottomSheet, and Tab patterns"
 license: "MIT"
 compatibility: "Android 9.0+ (API 28); Kotlin 1.9+; com.cometchat:chatuikit-compose-android:6.x"
-allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"
   tags: "cometchat, android, compose, navigation, placement, screens, tabs"
 ---
 
+> **Ground truth:** `com.cometchat:chatuikit-compose-android:6.x` composables + `docs/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.
+
 > **Companion skills:** cometchat-android-v6-kotlin-placement (Views equivalent), cometchat-android-v6-compose-components, cometchat-android-v6-compose-theming
 
 ## Purpose
 
-Place CometChat Compose components into app screens using Compose Navigation, Dialogs, BottomSheets, and Tab layouts. Patterns derived from `master-app-jetpack`.
+Place CometChat Compose components into app screens using Compose Navigation, Dialogs, BottomSheets, and Tab layouts. Patterns derived from `sample-app-compose`.
 
 ## Use this skill when
 
@@ -34,68 +35,154 @@ Place CometChat Compose components into app screens using Compose Navigation, Di
 class MainActivity : ComponentActivity() {
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
+        // Edge-to-edge enables drawing under the system bars; safeDrawingPadding
+        // below puts CometChat content back inside the safe area.
+        enableEdgeToEdge()
         setContent {
             CometChatTheme {
-                CometChatConversations(
-                    onItemClick = { conversation -> /* navigate */ }
-                )
+                Box(Modifier.fillMaxSize().safeDrawingPadding()) {
+                    CometChatConversations(
+                        onItemClick = { conversation -> /* navigate */ }
+                    )
+                }
             }
         }
     }
 }
 ```
 
+> ⚠️ **Always wrap CometChat composables in a `Modifier.safeDrawingPadding()` (or `systemBarsPadding()`) container when using edge-to-edge (ENG-35715).** Without it the kit's top app bar / composer is clipped under the status bar / navigation gesture area on modern Android (API 30+). The kit itself does NOT apply `WindowInsets` for you — that's the host's job. On XML host activities, the equivalent is `android:fitsSystemWindows="true"` on the root view (or per-fragment).
+
 ## 2. Compose Navigation
 
-Pattern from `master-app-jetpack/navigation/NavGraph.kt`:
+Pattern from `sample-app-compose/navigation/NavGraph.kt` + `messages/MessagesScreen.kt`.
+
+> **Carry `userId` / `groupId` on the route — NOT `conversation.conversationId`.** A `conversationId` is the conversation's own identifier, not a UID/GUID; the kit components need a `User` or `Group` object. The sample resolves the route's `userId`/`groupId` back into a `User`/`Group` on the chat screen via `CometChat.getUser(...)` / `CometChat.getGroup(...)` inside a `LaunchedEffect`. `CometChatTheme {}` is applied once at the app root (see §1), so it is NOT re-wrapped here.
 
 ```kotlin
+import androidx.navigation.NavType
 import androidx.navigation.compose.NavHost
 import androidx.navigation.compose.composable
 import androidx.navigation.compose.rememberNavController
+import androidx.navigation.navArgument
 
 @Composable
 fun AppNavigation() {
     val navController = rememberNavController()
 
-    CometChatTheme {
-        NavHost(navController = navController, startDestination = "conversations") {
+    NavHost(navController = navController, startDestination = "conversations") {
 
-            composable("conversations") {
-                CometChatConversations(
-                    onItemClick = { conversation ->
-                        // Pass conversation ID or user/group via route
-                        navController.navigate("chat/${conversation.conversationId}")
+        composable("conversations") {
+            CometChatConversations(
+                onItemClick = { conversation ->
+                    // Resolve the participant and pass the UID/GUID on the route —
+                    // NOT conversation.conversationId.
+                    when (val entity = conversation.conversationWith) {
+                        is User -> navController.navigate("chat?userId=${entity.uid}")
+                        is Group -> navController.navigate("chat?groupId=${entity.guid}")
                     }
-                )
-            }
+                }
+            )
+        }
 
-            composable("chat/{conversationId}") { backStackEntry ->
-                val conversationId = backStackEntry.arguments?.getString("conversationId")
-                // Resolve user or group from conversationId, then:
-                Column {
-                    CometChatMessageHeader(user = resolvedUser)
-                    CometChatMessageList(
-                        user = resolvedUser,
-                        modifier = Modifier.weight(1f)
-                    )
-                    CometChatMessageComposer(user = resolvedUser)
+        composable(
+            route = "chat?userId={userId}&groupId={groupId}",
+            arguments = listOf(
+                navArgument("userId") { type = NavType.StringType; nullable = true; defaultValue = null },
+                navArgument("groupId") { type = NavType.StringType; nullable = true; defaultValue = null }
+            )
+        ) { backStackEntry ->
+            val userId = backStackEntry.arguments?.getString("userId")
+            val groupId = backStackEntry.arguments?.getString("groupId")
+            ChatScreen(userId = userId, groupId = groupId, onBackPress = { navController.popBackStack() })
+        }
+
+        composable("users") {
+            CometChatUsers(
+                onItemClick = { user ->
+                    navController.navigate("chat?userId=${user.uid}")
                 }
-            }
+            )
+        }
 
-            composable("users") {
-                CometChatUsers(
-                    onItemClick = { user ->
-                        navController.navigate("chat/user_${user.uid}")
-                    }
-                )
-            }
+        composable("groups") {
+            CometChatGroups(
+                onItemClick = { group ->
+                    navController.navigate("chat?groupId=${group.guid}")
+                }
+            )
+        }
+    }
+}
+```
 
-            composable("groups") {
-                CometChatGroups(
-                    onItemClick = { group ->
-                        navController.navigate("chat/group_${group.guid}")
-                    }
+The chat screen re-fetches the `User`/`Group` from the route key, then composes the three pieces with `imePadding()` so the keyboard pushes the composer up (matches `MessagesScreen.kt`):
+
+```kotlin
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.WindowInsets
+import androidx.compose.foundation.layout.consumeWindowInsets
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.imePadding
+import androidx.compose.foundation.layout.navigationBarsPadding
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.statusBars
+import androidx.compose.material3.Scaffold
+import androidx.compose.runtime.*
+import androidx.compose.ui.Modifier
+import com.cometchat.chat.core.CometChat
+import com.cometchat.chat.exceptions.CometChatException
+import com.cometchat.chat.models.Group
+import com.cometchat.chat.models.User
+
+@Composable
+fun ChatScreen(userId: String?, groupId: String?, onBackPress: () -> Unit) {
+    var user by remember { mutableStateOf<User?>(null) }
+    var group by remember { mutableStateOf<Group?>(null) }
+
+    // Re-fetch the entity from the route key — routes carry IDs, not objects.
+    LaunchedEffect(userId, groupId) {
+        when {
+            userId != null -> CometChat.getUser(userId, object : CometChat.CallbackListener<User>() {
+                override fun onSuccess(fetched: User) { user = fetched; group = null }
+                override fun onError(e: CometChatException) {}
+            })
+            groupId != null -> CometChat.getGroup(groupId, object : CometChat.CallbackListener<Group>() {
+                override fun onSuccess(fetched: Group) { group = fetched; user = null }
+                override fun onError(e: CometChatException) {}
+            })
+        }
+    }
+
+    if (user != null || group != null) {
+        Scaffold(contentWindowInsets = WindowInsets.statusBars) { paddingValues ->
+            Column(
+                modifier = Modifier
+                    .fillMaxSize()
+                    .padding(paddingValues)
+                    .consumeWindowInsets(paddingValues)
+                    .navigationBarsPadding()
+                    .imePadding()
+            ) {
+                CometChatMessageHeader(
+                    modifier = Modifier.fillMaxWidth(),
+                    user = user,
+                    group = group,
+                    hideBackButton = false,
+                    onBackPress = onBackPress
+                )
+                CometChatMessageList(
+                    modifier = Modifier
+                        .fillMaxWidth()
+                        .weight(1f),
+                    user = user,
+                    group = group
+                )
+                CometChatMessageComposer(
+                    modifier = Modifier.fillMaxWidth(),
+                    user = user,
+                    group = group
                 )
             }
         }
@@ -190,7 +277,9 @@ CometChatOngoingCallActivity.launchOngoingCallActivity(
 
 ## 7. Incoming Call Overlay
 
-From `master-app-jetpack/Application.kt` — incoming calls are shown as an overlay using StateFlow:
+> **Note on canonical references:** the **Compose** sample app (`sample-app-compose`) ships **without** calling enabled, so it has no incoming-call wiring to copy. The only canonical Android sample that wires incoming calls is the **Kotlin-Views** `sample-app-kotlin`, which adds `CometChatIncomingCall` to a programmatic `Snackbar` host after a `CometChat.addCallListener` fires (see `cometchat-android-v6-calls`). The Compose pattern below — register the call listener, push the `Call` into a `StateFlow`, render an overlay — is the idiomatic Compose adaptation of that same flow (you wire it yourself; it is not lifted verbatim from a sample file).
+
+Incoming calls are shown as an overlay using a StateFlow you expose from the `Application` (register a `CometChat.addCallListener` that pushes incoming `Call`s into it):
 
 ```kotlin
 // In Application class
@@ -210,4 +299,4 @@ incomingCall?.let { call ->
 - ALWAYS wrap CometChat components in `CometChatTheme {}` at the top level — do not nest multiple `CometChatTheme` wrappers
 - Place `CometChatTheme {}` OUTSIDE the `NavHost` so all screens share the same theme
 - Ongoing calls MUST use `CometChatOngoingCallActivity` — they cannot be a composable screen (they need a separate Activity for PiP and lifecycle)
-- When passing User/Group objects between screens, use a cache or resolver pattern (like `master-app-jetpack/navigation/EntityCache.kt`) — do NOT serialize full objects in navigation routes
+- When navigating to a chat, carry `userId`/`groupId` on the route and re-fetch the `User`/`Group` with `CometChat.getUser`/`CometChat.getGroup` on the chat screen (see §2) — do NOT serialize full objects, and do NOT pass `conversation.conversationId` (it is not a UID/GUID)

package/skills/cometchat-android-v6-compose-theming/SKILL.md

@@ -3,13 +3,14 @@ name: cometchat-android-v6-compose-theming
 description: "CometChat Android UIKit v6 Jetpack Compose theming — CometChatTheme, CompositionLocal color schemes, typography, shapes, and dark mode"
 license: "MIT"
 compatibility: "Android 9.0+ (API 28); Kotlin 1.9+; com.cometchat:chatuikit-compose-android:6.x"
-allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"
   tags: "cometchat, android, compose, theming, colors, typography, dark-mode"
 ---
 
+> **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.
+
 > **Companion skills:** cometchat-android-v6-kotlin-theming (Views equivalent), cometchat-android-v6-compose-components, cometchat-android-v6-compose-customization
 
 ## Purpose
@@ -215,6 +216,31 @@ lightColorScheme(
 )
 ```
 
+## Localization
+
+To translate the UI, switch the active language, or override individual strings, route to the dedicated **`cometchat-i18n`** skill — the canonical cross-family localization reference. Android uses `CometChatLocalize.setLocale(context, Language.Code.<lang>)` / `getLocale(context)` (a separate method, **not** an `init` object — unlike web/RN). `cometchat-i18n` covers bundled languages, custom translations, and RTL. Docs: https://www.cometchat.com/docs/ui-kit/android/localize
+
+## Sound Manager — custom notification & call sounds
+
+Sounds are a **behavioral** customization — driven by `CometChatSoundManager`, an **instance** class that needs a `Context`. The UI Kit plays the built-in cues automatically; use this to override a cue with your own raw resource. V6 package (NOT the V5 `com.cometchat.chatuikit.*` path):
+
+```kotlin
+import com.cometchat.uikit.core.resources.soundmanager.CometChatSoundManager
+import com.cometchat.uikit.core.resources.soundmanager.Sound
+
+val soundManager = CometChatSoundManager(context)
+
+// Play a default cue — Sound enum is SCREAMING_SNAKE_CASE: INCOMING_CALL |
+//   OUTGOING_CALL | INCOMING_MESSAGE | INCOMING_MESSAGE_FROM_OTHER | OUTGOING_MESSAGE
+soundManager.play(Sound.INCOMING_CALL)
+
+// Override with your own raw resource (R.raw.*)
+soundManager.play(Sound.INCOMING_MESSAGE, R.raw.my_ping)
+
+// Stop whatever is playing
+soundManager.pause()
+```
+
 ## Hard rules
 
 - ALWAYS wrap CometChat Compose components in `CometChatTheme {}` — components will crash or look wrong without it