@cometchat/skills 4.2.1 → 4.4.0

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

@@ -3,13 +3,14 @@ name: cometchat-android-v6-kotlin-components
 description: "CometChat Android UIKit v6 Kotlin Views component catalog — all custom View chat UI components, their properties, styles, and usage"
 license: "MIT"
 compatibility: "Android 9.0+ (API 28); Kotlin 1.9+; com.cometchat:chatuikit-kotlin-android:6.x"
-allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.1"
   tags: "cometchat, android, kotlin-views, components, conversations, messages, users, groups, calls"
 ---
 
+> **Ground truth:** `com.cometchat:chatuikit-kotlin-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-compose-components (Compose equivalent), cometchat-android-v6-kotlin-theming, cometchat-android-v6-kotlin-customization, cometchat-android-v6-kotlin-placement
 
 ## Purpose
@@ -31,6 +32,8 @@ Complete catalog of all Kotlin Views components in CometChat UIKit v6. Each comp
 
 ## 1. Component Catalog
 
+> ⛔ **Only the components in THIS catalog exist — do not invent or recall names from v4/older memory.** Before emitting any `CometChat*` view, confirm it's listed below; if it's not here, it doesn't exist (→ "unresolved reference" compile error). **There is no all-in-one component:** the v4-era composites `CometChatConversationsWithMessages` / `CometChatUsersWithMessages` / `CometChatGroupsWithMessages` / `CometChatMessages` and the `CometChatUI` god-view are **absent in the v6 Kotlin-Views kit** (verified against the published `chatuikit-kotlin-android:6.0.1` AAR — the only top-level `CometChat*` views are `CometChatConversations`, `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer`, `CometChatMessageInformation`, `CometChatUsers`, `CometChatGroups`). Compose a two-pane experience yourself: `CometChatConversations` (list) → on item-click, host `CometChatMessageHeader` + `CometChatMessageList` + `CometChatMessageComposer` for the selected `User`/`Group`.
+
 ### 1.1 List Components
 
 | Component | Package | Type | Purpose |
@@ -43,6 +46,8 @@ Complete catalog of all Kotlin Views components in CometChat UIKit v6. Each comp
 
 ### 1.2 Messaging Components
 
+> ⚠️ **There is NO combined `CometChatMessages` View on Android v6 Kotlin-Views either.** Like the Compose surface, v6 Kotlin-Views ships the pieces separately — compose the chat screen manually as `CometChatMessageHeader + CometChatMessageList + CometChatMessageComposer` (see §2.4). No `com.cometchat.uikit.kotlin.presentation.cometchatmessages.CometChatMessages` exists on either surface.
+
 | Component | Package | Type | Purpose |
 |---|---|---|---|
 | `CometChatMessageList` | `presentation.messagelist.ui` | View | Message list with bubbles |
@@ -70,6 +75,8 @@ Complete catalog of all Kotlin Views components in CometChat UIKit v6. Each comp
 | `CometChatEmojiKeyboard` | `presentation.emojikeyboard.ui` | View | Emoji picker |
 | `CometChatStickerKeyboard` | `presentation.stickerkeyboard.ui` | View | Sticker picker |
 | `CometChatFlagMessageDialog` | `presentation.report` | Dialog | Report/flag message |
+| `CometChatAIAssistantChatHistory` | `presentation.aiassistantchathistory.ui` | View | AI chat history (extends `MaterialCardView`) |
+| `CometChatNotificationFeed` | `presentation.notificationfeed.ui` | View | Full-screen notification feed (category filter chips, timestamp grouping, rich cards, real-time updates) — extends `FrameLayout` |
 
 ### 1.5 Shared Elements
 
@@ -182,6 +189,8 @@ Every component has a corresponding style class in its `style/` subpackage:
 | `CometChatMessageHeader` | `CometChatMessageHeaderStyle` |
 | `CometChatCallLogs` | `CometChatCallLogsStyle` |
 | `CometChatThreadHeader` | `CometChatThreadHeaderStyle` |
+| `CometChatNotificationFeed` | `CometChatNotificationFeedStyle` (`@ColorInt` Int props; `.default()` factory; `setStyle(style)`) |
+| `CometChatAIAssistantChatHistory` | `CometChatAIAssistantChatHistoryStyle` (`.default(context)`) |
 
 Style classes resolve defaults from XML theme attributes and `CometChatTheme` singleton.
 
@@ -189,6 +198,27 @@ Style classes resolve defaults from XML theme attributes and `CometChatTheme` si
 
 Each component creates its own ViewModel internally via factories from `chatuikit-core`. ViewModels are shared with the Compose stack — the same `CometChatConversationsViewModel` powers both `CometChatConversations` (View) and `CometChatConversations` (@Composable).
 
+## 5. Custom State Views (empty / error / loading)
+
+The list/data components expose three setters to replace the built-in empty, error, and loading states with your own `View`:
+
+```kotlin
+fun setEmptyView(view: View?)
+fun setErrorView(view: View?)
+fun setLoadingView(view: View?)
+```
+
+Verified present on `CometChatConversations`, `CometChatUsers`, `CometChatGroups`, `CometChatGroupMembers`, `CometChatCallLogs`, and `CometChatSearch` (e.g. `CometChatConversations.kt:1045/1052/1059`, `CometChatUsers.kt:735/742/749`). Pass `null` to fall back to the default state view.
+
+```kotlin
+val users = findViewById<CometChatUsers>(R.id.users)
+users.setEmptyView(layoutInflater.inflate(R.layout.my_empty_state, null))
+users.setErrorView(layoutInflater.inflate(R.layout.my_error_state, null))
+users.setLoadingView(layoutInflater.inflate(R.layout.my_loading_state, null))
+```
+
+> `CometChatMessageList` does NOT expose these `set*View` state setters — customize its empty/error/loading states through styling/bubble customization instead (see `cometchat-android-v6-kotlin-customization`). `CometChatNotificationFeed` instead takes its own programmatic empty/error/loading rendering internally (see §1.4).
+
 ## Hard rules
 
 - Activity theme MUST inherit from `CometChatTheme.DayNight` (or `.Light` / `.Dark`) — `Theme.AppCompat.*`, `Theme.MaterialComponents.*.Bridge`, plain `Theme.MaterialComponents.*`, and `Theme.Material3.*` all crash at component inflation. See `cometchat-android-v6-kotlin-placement` "Activity theme" section.

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

@@ -3,13 +3,14 @@ name: cometchat-android-v6-kotlin-customization
 description: "CometChat Android UIKit v6 Kotlin Views customization — BubbleFactory abstract class, BubbleViewProvider, style classes, and per-slot overrides"
 license: "MIT"
 compatibility: "Android 9.0+ (API 28); Kotlin 1.9+; com.cometchat:chatuikit-kotlin-android:6.x"
-allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"
   tags: "cometchat, android, kotlin-views, customization, bubble-factory, bubble-view-provider, 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-compose-customization (Compose equivalent), cometchat-android-v6-kotlin-components, cometchat-android-v6-kotlin-theming, cometchat-android-v6-extensions (DataSource layer), cometchat-android-v6-events
 
 ## Purpose
@@ -156,6 +157,157 @@ val key = BubbleFactory.getFactoryKey(message) // "category_type" or "deleted"
 val key = BubbleFactory.getKey("custom", "location") // "custom_location"
 ```
 
+### 1.8 Registering a factory is already additive — built-ins are NOT in the map
+
+`CometChatMessageList` exposes exactly two factory APIs (`CometChatMessageList.kt:3376 / :3395`):
+
+- `setBubbleFactories(factories: List<BubbleFactory>)` — sets the custom factory map
+- `getBubbleFactories(): Map<String, BubbleFactory>` — returns an immutable copy
+
+There is **NO** settable `bubbleFactories` property and **NO** `removeBubbleFactory(...)` on `CometChatMessageList` (`removeBubbleFactory` exists only on the internal `MessageAdapter`, `MessageAdapter.kt:1534` — not public API).
+
+`setBubbleFactories` does NOT wipe built-in bubbles, because **built-in types are never stored as factory entries.** The adapter starts with an empty factory map (`MessageAdapter.kt:153` "The adapter starts with an empty bubbleFactories map"); when a message's `"category_type"` key has no factory, the bubble falls back to `InternalContentRenderer`. So passing only your custom factories is correct and safe:
+
+```kotlin
+messageList.setBubbleFactories(listOf(
+    LocationBubbleFactory(),     // custom_location
+    PaymentBubbleFactory()       // custom_payment
+))
+// text/image/video/etc. still render via InternalContentRenderer — untouched
+```
+
+`setBubbleFactories` replaces the *custom* factory set, so include every custom factory you want active in the single list. `BubbleFactory.getKey(category, type)` and `BubbleFactory.getFactoryKey(message)` (companion, `BubbleFactory.kt:441 / :425`) are still available if you need the key string.
+
+### 1.9 Custom attachment options (Scenario 3)
+
+`CometChatMessageComposer` exposes `addAttachmentOption(action)` (append one) and `setAttachmentOptions(list)` (set the custom list) — `CometChatMessageComposer.kt:4951 / :4930`, both delegate to the shared `CometChatMessageComposerViewModel`.
+
+**Neither call drops the built-in options.** Both touch 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 the custom ones are appended at the end (`CometChatMessageComposerViewModel.kt:646-649`). So `setAttachmentOptions(listOf(location))` keeps the defaults too — it just replaces any *previously-set custom* options. Use `addAttachmentOption` to add one without disturbing other custom options:
+
+```kotlin
+val location = CometChatMessageComposerAction(
+    id = "location",
+    title = "Send Location",
+    icon = R.drawable.ic_location,
+    onClick = OnClick { /* pick + send (see 1.10) */ }
+)
+messageComposer.addAttachmentOption(location)        // appends one custom option
+// setAttachmentOptions(listOf(location)) also keeps camera/image/etc. — it only resets the custom list
+```
+
+> To hide a built-in option, use the composer visibility setters (e.g. `setPollOptionVisibility(View.GONE)`), which flip the `_show*Option` flags `getDefaultAttachmentOptions` checks. The built-in IDs are constants on `CometChatMessageComposerAction` (`ID_CAMERA`…`ID_COLLABORATIVE_WHITEBOARD`, `CometChatMessageComposerAction.kt:42-49`).
+
+### 1.10 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 Kotlin Views): `CometChatMessageList.setBubbleFactories(List) / getBubbleFactories(): Map` (`CometChatMessageList.kt:3376 / :3395`), `CometChatMessageComposer.addAttachmentOption / setAttachmentOptions` (`:4951 / :4930`), `CometChatUIKit.sendCustomMessage(CustomMessage, CallbackListener)` (`CometChatUIKit.kt:472`). Note: `messageList.bubbleFactories = …` (property) and `CometChatMessageList.removeBubbleFactory(...)` are NOT public — do not use.
+
+### 1.11 Override an EXISTING type's bubble (Scenario 2)
+
+To replace a built-in type's rendering, subclass `BubbleFactory` with `getCategory()`/`getType()` set to the built-in identifiers, then register it. As in §1.8, built-ins are not factory entries — a matching factory simply takes priority over `InternalContentRenderer`.
+
+```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 createContentView(context: Context): View = MyTextContentView(context)
+
+    override fun bindContentView(
+        view: View,
+        message: BaseMessage,
+        alignment: UIKitConstants.MessageBubbleAlignment,
+        holder: RecyclerView.ViewHolder?,
+        position: Int
+    ) {
+        (view as MyTextContentView).bind(message as TextMessage)
+    }
+    // …or override createBubbleView()/bindBubbleView() (see 1.3) to replace the whole bubble
+}
+
+messageList.setBubbleFactories(listOf(MyTextBubbleFactory()))
+```
+
+Only `message_text` is overridden; other types keep their internal rendering.
+
+### 1.12 Add a long-press message option (Scenario 4 — Forward-style)
+
+`CometChatMessageList` resolves the long-press option sheet through the shared view model. Two public setters control it (`CometChatMessageList.kt:3697 / :3709`):
+
+- `setOptions(callback: (BaseMessage) -> List<CometChatMessageOption>?)` — **replaces** defaults when the callback returns non-null (return `null` to keep them); takes precedence over `addOptions`.
+- `addOptions(callback: (BaseMessage) -> List<CometChatMessageOption>)` — **appends** after the defaults; invoked only when `setOptions` is unset or returns `null`.
+
+Use `addOptions` so the built-in Reply/Copy/Edit/Delete survive:
+
+```kotlin
+import com.cometchat.uikit.core.domain.model.CometChatMessageOption
+
+messageList.addOptions { message ->          // ✅ appended to defaults
+    listOf(
+        CometChatMessageOption(
+            id = "forward",
+            title = "Forward",
+            icon = R.drawable.ic_forward,
+            onClick = { /* open forward picker for `message` */ }
+        )
+    )
+}
+// ❌ messageList.setOptions { listOf(forward) }   // would DROP reply/copy/edit/delete
+```
+
+For the click handler use `setMessageOptionClickListener(MessageOptionClickListener)` (`CometChatMessageList.kt:3671`). Resolution order verified in `CometChatMessageListViewModel.resolveMessageOptions` (`:817-827`): `setOptions` non-null wins, else `defaultOptions + addOptions`. `CometChatMessageOption(id, title, …, onClick)` is a data class at `CometChatMessageOption.kt:21`.
+
+### 1.13 MessageTemplate via the DataSource (docs-taught alternative to BubbleFactory)
+
+> ⚠️ **Verify before using — symbols not found in the GA v6 Kotlin-Views source.** `CometChatUIKit.getDataSource()`, `getMessageTemplates()`, `CometChatMessageTemplate`, `setTemplates(...)`, and `MessagesViewHolderListener` appear in the Android **docs** but are **absent from the verified `com.cometchat.uikit.kotlin` / `chatuikit-core` GA source** (they're the legacy `com.cometchat.chatuikit` v5-shaped API). Treat this section as a docs reference that may not compile against your installed v6 kit — **prefer `BubbleFactory` / `BubbleViewProvider` (the confirmed v6-native path) for all new code.**
+
+The `BubbleFactory` / `BubbleViewProvider` 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 via the `MessagesViewHolderListener` create/bind pair, then re-apply with `setTemplates(...)` (append, never replace with a single-item list):
+
+```kotlin
+// 1. fetch existing templates from the data source
+val templates = CometChatUIKit.getDataSource()
+    .getMessageTemplates(messageList.additionParameter)
+    .toMutableList()
+
+// 2. mutate the matched template (or build a new one for a custom type)
+templates.find { it.type == UIKitConstants.MessageType.TEXT }
+    ?.setContentView(object : MessagesViewHolderListener() {
+        override fun createView(context: Context, bubble: CometChatMessageBubble,
+            alignment: UIKitConstants.MessageBubbleAlignment): View =
+            LayoutInflater.from(context).inflate(R.layout.your_custom_layout, null)
+        override fun bindView(context: Context, view: View, message: BaseMessage,
+            alignment: UIKitConstants.MessageBubbleAlignment,
+            viewHolder: RecyclerView.ViewHolder, list: List<BaseMessage>, i: Int) { /* bind */ }
+    })
+// new custom type:
+val contact = CometChatMessageTemplate().apply {
+    setType("contact"); setCategory(UIKitConstants.MessageCategory.CUSTOM)
+    setContentView(/* MessagesViewHolderListener */)
+}
+templates.add(contact)
+
+// 3. re-apply — Views uses setTemplates(...)
+messageList.setTemplates(templates)
+```
+
+Views templates expose listener-based slot setters (`setContentView`, `setHeaderView`, `setFooterView`, `setBottomView`, `setStatusInfoView`, `setBubbleView`, `setOptions`) mirroring §1.4's slots. Prefer `BubbleFactory` for new code; use `getMessageTemplates(...)` + `setTemplates(...)` when you want to start from the kit's defaults and tweak one type. (This overlaps the custom-message topic.)
+
 ## 2. BubbleViewProvider (Per-Slot Overrides)
 
 `BubbleViewProvider` is a simpler interface for overriding individual slots across ALL message types.
@@ -257,6 +409,21 @@ messageList.setStyle(style)
 | No bubble replacement | `createBubbleView()` for complete replacement |
 | Theme-level styling only | Per-factory `getBubbleStyle()` |
 
+## Text formatters (inline mentions / URLs / custom tokens)
+
+Style/transform message text inline via `setTextFormatters(...)` on the composer and message list. The kit ships `CometChatMentionsFormatter` + `CometChatRichTextFormatter` (subclasses of the abstract `CometChatTextFormatter`) in `com.cometchat.uikit.kotlin.shared.formatters`. To ADD a custom one, include the defaults too (a bare list replaces them).
+
+```kotlin
+import com.cometchat.uikit.kotlin.shared.formatters.CometChatMentionsFormatter
+import com.cometchat.uikit.kotlin.shared.formatters.CometChatTextFormatter
+
+val formatters = listOf<CometChatTextFormatter>(CometChatMentionsFormatter(context) /* , YourFormatter(context) */)
+composer.setTextFormatters(formatters)      // fun setTextFormatters(List<CometChatTextFormatter>?)
+messageList.setTextFormatters(formatters)
+```
+
+For a custom @/#/! token: subclass `CometChatTextFormatter(trackingCharacter)` and implement its `search()` + view hooks (the kit's `shared/formatters/README.md` shows the mentions example: `setMentionLimit` / `setMentionsType` / `setOnMentionClick` / `setMentionStyle`).
+
 ## Hard rules
 
 - BubbleFactory is an `abstract class` — extend it with `BubbleFactory()`
@@ -266,3 +433,7 @@ messageList.setStyle(style)
 - For per-type content customization, use BubbleFactory. For cross-type slot overrides, use BubbleViewProvider
 - `onViewRecycled()` is critical for cleaning up image loads, animations, or media playback
 - 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-kotlin-theming`** (Sound section). Verify the access path against the installed kit before relying on it.

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

@@ -3,18 +3,19 @@ name: cometchat-android-v6-kotlin-placement
 description: "CometChat Android UIKit v6 Kotlin Views placement — Activity, Fragment, BottomSheet, Tab, and Intent navigation patterns"
 license: "MIT"
 compatibility: "Android 9.0+ (API 28); Kotlin 1.9+; com.cometchat:chatuikit-kotlin-android:6.x"
-allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.1"
   tags: "cometchat, android, kotlin-views, placement, activity, fragment, navigation, tabs"
 ---
 
+> **Ground truth:** `com.cometchat:chatuikit-kotlin-android:6.x` Views + `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-compose-placement (Compose equivalent), cometchat-android-v6-kotlin-components, cometchat-android-v6-kotlin-theming
 
 ## Purpose
 
-Place CometChat Kotlin Views components into Activities, Fragments, BottomSheets, and Tab layouts. Patterns derived from `master-app-kotlin`.
+Place CometChat Kotlin Views components into Activities, Fragments, BottomSheets, and Tab layouts. Patterns derived from `sample-app-kotlin`.
 
 ## Use this skill when
 
@@ -50,7 +51,7 @@ class ConversationsActivity : AppCompatActivity() {
 
 ### 1.2 Messages Activity
 
-Pattern from `master-app-kotlin/appflow/MessagesActivity.kt`:
+Pattern from `sample-app-kotlin/.../ui/messages/MessagesActivity.kt`:
 
 ```kotlin
 class MessagesActivity : AppCompatActivity() {
@@ -58,10 +59,21 @@ class MessagesActivity : AppCompatActivity() {
         super.onCreate(savedInstanceState)
         setContentView(R.layout.activity_messages)
 
+        // Pad the root for the status/navigation bars (root has fitsSystemWindows="true").
+        ViewCompat.setOnApplyWindowInsetsListener(findViewById(R.id.parent_view)) { view, insets ->
+            val systemBars = insets.getInsets(WindowInsetsCompat.Type.systemBars())
+            view.setPadding(systemBars.left, systemBars.top, systemBars.right, 0)
+            insets
+        }
+
         val header = findViewById<CometChatMessageHeader>(R.id.messageHeader)
         val messageList = findViewById<CometChatMessageList>(R.id.messageList)
         val composer = findViewById<CometChatMessageComposer>(R.id.messageComposer)
 
+        // Show + wire the back button (the kit does not finish the Activity for you).
+        header.setBackButtonVisibility(View.VISIBLE)
+        header.setOnBackPress { finish() }
+
         // Set user or group
         header.setUser(user)
         messageList.setUser(user)
@@ -75,13 +87,16 @@ class MessagesActivity : AppCompatActivity() {
 }
 ```
 
-XML layout:
+XML layout — the root carries `android:fitsSystemWindows="true"` (so the inset listener above receives system-bar insets) and `?attr/cometchatBackgroundColor1`:
 
 ```xml
 <?xml version="1.0" encoding="utf-8"?>
 <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:id="@+id/parent_view"
     android:layout_width="match_parent"
     android:layout_height="match_parent"
+    android:background="?attr/cometchatBackgroundColor1"
+    android:fitsSystemWindows="true"
     android:orientation="vertical">
 
     <com.cometchat.uikit.kotlin.presentation.messageheader.ui.CometChatMessageHeader
@@ -192,7 +207,7 @@ dialog.show()
 
 ## 6. App Flow Pattern
 
-From `master-app-kotlin/appflow/DefaultComponentAppFlowActivity.kt` — a single Activity hosts the full chat flow with Fragment transactions:
+Pattern from `sample-app-kotlin/.../ui/home/HomeActivity.kt` — a single Activity hosts the chat flow via Fragment transactions:
 
 ```kotlin
 class AppFlowActivity : AppCompatActivity() {

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

@@ -3,13 +3,14 @@ name: cometchat-android-v6-kotlin-theming
 description: "CometChat Android UIKit v6 Kotlin Views theming — CometChatTheme singleton, XML attributes, programmatic overrides, typography, and dark mode"
 license: "MIT"
 compatibility: "Android 9.0+ (API 28); Kotlin 1.9+; com.cometchat:chatuikit-kotlin-android:6.x"
-allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"
   tags: "cometchat, android, kotlin-views, theming, xml-attrs, 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-compose-theming (Compose equivalent), cometchat-android-v6-kotlin-components, cometchat-android-v6-kotlin-customization
 
 ## Purpose
@@ -47,10 +48,14 @@ CometChatTheme.setErrorColor(Color.RED)
 
 ## 2. XML Theme Attributes
 
-Define theme colors in your app's `styles.xml` or `themes.xml`:
+> **The app/activity theme MUST extend `CometChatTheme.DayNight` (required — components crash without it).** The kit ships `CometChatTheme.DayNight` (parent `Theme.MaterialComponents.DayNight.NoActionBar`), which defines every `cometchat*` theme attribute the component layouts reference. Parenting a plain `Theme.MaterialComponents` / `Theme.Material3` / `Theme.AppCompat` instead leaves those attrs unresolved and the **first component inflate crashes** — e.g. `CometChatConversations` (which inflates a `MaterialButton`/`MaterialCardView`) throws `java.lang.UnsupportedOperationException: Failed to resolve attribute …` or `IllegalArgumentException: requires your app theme to be Theme.MaterialComponents`. Set it in `AndroidManifest.xml` via `android:theme="@style/AppTheme"` (or `android:theme="@style/CometChatTheme.DayNight"` directly). Verified by building + running on-device, 2026-06-11.
+
+Define theme colors in your app's `styles.xml` or `themes.xml`, parenting the kit theme:
 
 ```xml
-<style name="AppTheme" parent="Theme.MaterialComponents.DayNight">
+<!-- parent MUST be CometChatTheme.DayNight (or a descendant) -->
+<style name="AppTheme" parent="CometChatTheme.DayNight">
+    <!-- Override only what you want; the parent supplies all defaults. -->
     <!-- Primary -->
     <item name="cometchatPrimaryColor">#6851D6</item>
 
@@ -129,7 +134,7 @@ Extended primary colors auto-generate by blending primary with white (day) or bl
 
 All follow the same pattern: `get{Token}(ctx)` / `set{Token}(color)` / `cometchat{Token}` XML attr. Defaults fall back to neutral scale values if not explicitly set.
 
-Border color aliases: `getBorderColorLight()` = `getStrokeColorLight()`, etc.
+Border color aliases: `getBorderColorLight()` = `getStrokeColorLight()`, `getBorderColorDefault()` = `getStrokeColorDefault()`, `getBorderColorDark()` = `getStrokeColorDark()`. Note: `StrokeColor` also has a `Highlight` variant (`getStrokeColorHighlight()`); there is **no** `getBorderColorHighlight()`.
 
 ## 4. Typography
 
@@ -138,7 +143,8 @@ Border color aliases: `getBorderColorLight()` = `getStrokeColorLight()`, etc.
 val titleBold: Int = CometChatTheme.getTextAppearanceTitleBold(context)
 val bodyRegular: Int = CometChatTheme.getTextAppearanceBodyRegular(context)
 val heading1Medium: Int = CometChatTheme.getTextAppearanceHeading1Medium(context)
-// ... all combinations: Title, Heading1-4, Body, Caption1-2, Button, Link × Regular/Medium/Bold
+// ... combinations: Title, Heading1-4, Body, Caption1-2, Button each have Regular/Medium/Bold.
+// Link is the exception — only getTextAppearanceLinkRegular(context) exists (no Medium/Bold).
 
 // Get font resource IDs
 val regularFont: Int = CometChatTheme.getFontRegular(context)
@@ -193,6 +199,31 @@ val black: Int = CometChatTheme.getColorBlack(context)
 val transparent: Int = CometChatTheme.getColorTransparent(context)
 ```
 
+## 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 pass a valid `Context` to getter methods — they resolve XML attributes from the theme