docs(android-uikit): reframe thread subscription coverage

docs.json

@@ -1856,13 +1856,13 @@
                             "pages": [
                               "ui-kit/android/guide-overview",
                               "ui-kit/android/guide-threaded-messages",
-                              "ui-kit/android/guide-thread-subscription",
                               "ui-kit/android/guide-pin-and-save-messages",
                               "ui-kit/android/guide-block-unblock-user",
                               "ui-kit/android/guide-new-chat",
                               "ui-kit/android/guide-message-privately",
                               "ui-kit/android/guide-call-log-details",
                               "ui-kit/android/guide-group-chat",
+                              "ui-kit/android/guide-text-color",
                               "ui-kit/android/custom-text-formatter-guide",
                               "ui-kit/android/mentions-formatter-guide",
                               "ui-kit/android/shortcut-formatter-guide",
@@ -6939,6 +6939,10 @@
     }
   },
   "redirects": [
+    {
+      "source": "/ui-kit/android/guide-thread-subscription",
+      "destination": "/ui-kit/android/guide-threaded-messages#thread-subscription"
+    },
     {
       "source": "/sdk/flutter/group-kick-member",
       "destination": "/sdk/flutter/group-kick-ban-members"

ui-kit/android/conversations.mdx

@@ -1,9 +1,9 @@
 ---
 title: "Conversations"
 description: "Scrollable list of recent one-on-one and group conversations for the logged-in user."
 ---
 
 `CometChatConversations` renders a scrollable list of recent conversations with real-time updates for new messages, typing indicators, read receipts, and user presence.
 
 <Frame>
   <img src="/images/f2c77c5b-Conversation-ac41cc6650fbb941c64f389aee910dbc.png" />
@@ -165,6 +165,15 @@
 | With tags | `.setTags(listOf("vip")).withTags(true)` |
 | Filter by user tags | `.withUserAndGroupTags(true).setUserTags(listOf("premium"))` |
 | Filter by group tags | `.withUserAndGroupTags(true).setGroupTags(listOf("support"))` |
+| Pinned conversations only | `.setPinnedBy("system,me")` |
+
+The default list already arrives pin-ordered, so `setPinnedBy` is only for a **dedicated pinned list** — `"me"` for the user's own pins, `"system"` for admin/global pins, `"system,me"` for both. See [Pin A Conversation (SDK)](/sdk/android/v5/pin-conversation).
+
+```kotlin lines
+conversations.setConversationsRequestBuilder(
+    ConversationsRequest.ConversationsRequestBuilder().setPinnedBy("system,me")
+)
+```
 
 <Warning>
 Pass the builder object, not the result of `.build()`. The component calls `.build()` internally. Default page size is 30 with infinite scroll.
@@ -419,6 +428,40 @@
 
 ---
 
+## Pinning Conversations
+
+A pinned conversation sits at the top of the list and holds that position even as new messages arrive in other chats. The pin is **private to the logged-in user** — nobody else sees it — and it syncs to that user's other devices.
+
+When the feature is enabled for your app, the long-press menu includes **Pin conversation** / **Unpin conversation** with no wiring needed: pinning applies immediately with a toast, unpinning asks for confirmation first, and a pinned row shows a pin indicator next to its timestamp.
+
+<Warning>
+**Pin Conversation needs a server flag that is not seeded.** It requires `features.ux.conversations.pinned.enabled`, which ships enabled in no plan and must be mapped per app. Until then the option never renders, and a direct SDK call rejects with `ERR_FEATURE_NOT_ACCESSIBLE`. The UI Kit reads that flag itself at login and on every reconnect — there is no app code to write. Read it yourself with `CometChatUIKit.isPinConversationEnabled()` when you need to gate your own entry point.
+</Warning>
+
+`setPinConversationOptionVisibility(View.GONE)` hides the option on one particular list. It is **ANDed** with the Dashboard flag, so the option renders only when both allow it.
+
+```kotlin lines
+conversations.setPinConversationOptionVisibility(View.GONE)
+```
+
+### Reading pin state
+
+```kotlin lines
+val isPinned = conversation.isPinned              // pinnedAt > 0
+
+// An admin/global pin. A user cannot unpin one of these,
+// so hide or disable the unpin control.
+val isSystemPinned = conversation.isSystemPinned  // pinnedBy == "app_system"
+```
+
+<Note>
+The conversation list arrives **already pin-ordered** from the server — admin pins first, then the user's own, then everything else — and each row carries its pin attributes. You do not need a separate fetch to render a pinned section. To render a pinned-**only** list, use the `setPinnedBy` filter shown in [Filtering Conversations](#filtering-conversations).
+</Note>
+
+For pins made elsewhere, the Chat SDK exposes `CometChat.ConversationListener` with `onConversationPinned` / `onConversationUnpinned`. See [Pin A Conversation (SDK)](/sdk/android/v5/pin-conversation) for those callbacks, the pin methods, and the per-user pin limit underneath.
+
+---
+
 ## Functionality
 
 | Method (Kotlin XML) | Compose Parameter | Description |
@@ -709,18 +752,6 @@
 </Tab>
 </Tabs>
 
-### Built-in Pin Conversation Option
-
-When the Pin Conversation feature is enabled for your app (`CometChatUIKit.isPinConversationEnabled()`), the long-press menu automatically includes **Pin conversation** / **Unpin conversation** — no wiring needed. Pinning applies immediately with a toast; unpinning asks for confirmation first. Pinned conversations display a pin indicator next to the timestamp and stay at the **top of the list**, holding their position even as new messages arrive in other chats. Hide the option with `setPinConversationOptionVisibility(View.GONE)`.
-
-To render a pinned-only list, pass a request builder with the pinned filter — see [Pin A Conversation (SDK)](/sdk/android/v5/pin-conversation):
-
-```kotlin lines
-conversations.setConversationsRequestBuilder(
-    ConversationsRequest.ConversationsRequestBuilder().setPinnedBy("system,me")
-)
-```
-
 ---
 
 ## Common Patterns

ui-kit/android/core-features.mdx

@@ -7,7 +7,7 @@
 
 | Field | Value |
 | --- | --- |
 | Packages | `com.cometchat:chatuikit-kotlin-android` (Kotlin XML Views), `com.cometchat:chatuikit-compose-android` (Jetpack Compose) |
 | Required setup | `CometChatUIKit.init()` then `CometChatUIKit.login()` — must complete before rendering any component |
 | Core features | Instant Messaging, Media Sharing, Read Receipts, Mark as Unread, Typing Indicator, User Presence, Reactions, Mentions, Rich Text Formatting, Quoted Reply, Search, Threaded Conversations, Moderation, Report Message, Group Chat |
 | Key components | `CometChatConversations`, `CometChatMessageList`, `CometChatMessageComposer`, `CometChatMessageHeader`, `CometChatUsers`, `CometChatGroups`, `CometChatGroupMembers`, `CometChatMessageInformation`, `CometChatThreadHeader` |
@@ -169,6 +169,7 @@
 | --- | --- |
 | [CometChatMessageComposer](/ui-kit/android/message-composer) | Provides a built-in rich text editor with formatting toolbar and text selection menu items for bold, italic, strikethrough, code, links, lists, blockquotes, and code blocks. |
 | [CometChatMessageList](/ui-kit/android/message-list) | Renders formatted messages with the appropriate styling automatically applied, ensuring that rich text formatting is displayed exactly as intended by the sender. |
+
 ## Threaded Conversations
 
 Respond directly to a specific message, keeping conversations organized.
@@ -183,16 +184,16 @@
 | [CometChatMessageComposer](/ui-kit/android/message-composer) | Allows composing messages within a thread. |
 | [CometChatMessageList](/ui-kit/android/message-list) | Displays threaded messages in context. |
 
-## Thread Subscription
+### Thread Subscription
 
-Let users subscribe to or unsubscribe from a thread to control whether its replies notify them. Opt-in feature — enable it with `UIKitSettings.setEnableThreadSubscription(true)`.
+Let users subscribe to or unsubscribe from a thread to control whether its replies notify them. Enabled by default — remove a surface with `setThreadSubscriptionOptionVisibility(View.GONE)` or `setThreadSubscriptionVisibility(View.GONE)`.
 
 | Component | Role |
 | --- | --- |
 | [CometChatMessageList](/ui-kit/android/message-list) | Provides the Subscribe to thread / Unsubscribe from thread option in the message action sheet. |
 | [CometChatThreadHeader](/ui-kit/android/threaded-messages-header) | Shows the subscription bell on the thread view. |
 
-See the [Thread Subscription guide](/ui-kit/android/guide-thread-subscription) for setup and behavior.
+See [Threaded Messages → Thread Subscription](/ui-kit/android/guide-threaded-messages#thread-subscription) for setup and behavior.
 
 ## Quoted Replies
 

ui-kit/android/custom-text-formatter-guide.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Custom Text Formatter"
-sidebarTitle: "Custom Text Formatter"
+sidebarTitle: "Text Formatter Base Class"
 description: "Extend CometChatTextFormatter to build custom inline text patterns with tracking characters and suggestion lists."
 ---
 
@@ -9,7 +9,7 @@
 | Field | Value |
 | --- | --- |
 | Packages | `com.cometchat:chatuikit-kotlin` · `com.cometchat:chatuikit-jetpack` |
 | Key class | `CometChatTextFormatter` (abstract base class for custom formatters) |
 | Required setup | `CometChatUIKit.init()` then `CometChatUIKit.login("UID")` |
 | Purpose | Extend to create custom inline text patterns with tracking characters, suggestion lists, and span formatting |
 | Features | Tracking character activation, suggestion list, span formatting per context (composer, bubbles, conversations), pre-send hooks |
@@ -18,7 +18,7 @@
 
 </Accordion>
 
 `CometChatTextFormatter` is an abstract class for formatting text in the message composer and message bubbles. Extend it to build custom formatters — hashtags, shortcuts, or any pattern triggered by a tracking character.
 
 | Capability | Description |
 | --- | --- |
@@ -46,7 +46,7 @@
 </Tab>
 <Tab title="Jetpack Compose">
 ```kotlin lines
 // Same class — formatters are shared between both modules
 class HashTagFormatter : CometChatTextFormatter('#') {
     private val suggestions: MutableList<SuggestionItem> = ArrayList()
 }
@@ -110,7 +110,7 @@
 ```kotlin lines
 import com.cometchat.uikit.core.CometChatUIKit
 
 val textFormatters = CometChatUIKit.getDataSource().getTextFormatters(this, messageComposer.additionParameter)
 textFormatters.add(HashTagFormatter())
 messageComposer.setTextFormatters(textFormatters)
 ```

ui-kit/android/events.mdx

@@ -8,7 +8,7 @@
 | Field | Value |
 | --- | --- |
 | Kotlin (XML Views) | `com.cometchat:chatuikit-kotlin-android` |
 | Jetpack Compose | `com.cometchat:chatuikit-compose-android` |
 | Import | `com.cometchat.uikit.core.events.CometChatEvents` |
 | Event flows | `CometChatEvents.messageEvents`, `CometChatEvents.callEvents`, `CometChatEvents.conversationEvents`, `CometChatEvents.groupEvents`, `CometChatEvents.userEvents`, `CometChatEvents.uiEvents` |
 | Pattern | Kotlin `SharedFlow` with sealed class event types — collect in `viewModelScope` or `lifecycleScope` |
@@ -74,14 +74,14 @@
 | `MessageEvent.MessagePinned(message)` | Triggered when a message is pinned. |
 | `MessageEvent.MessageUnpinned(message)` | Triggered when a message is unpinned. |
 | `MessageEvent.MessageSaved(message)` | Triggered when the logged-in user saves a message. |
 | `MessageEvent.MessageUnsaved(message)` | Triggered when the logged-in user unsaves a message. |
 
 **Collecting events:**
 
 <Tabs>
 <Tab title="Kotlin (XML Views)">
 ```kotlin
 // In an Activity or Fragment — use lifecycleScope
 lifecycleScope.launch {
     CometChatEvents.messageEvents.collect { event ->
         when (event) {
@@ -164,7 +164,7 @@
 
 ### Thread Events
 
 `CometChatEvents.threadEvents` emits `CometChatThreadEvent` instances when the logged-in user subscribes to or unsubscribes from a message thread, so every surface showing a subscription control can stay in sync without a refetch.
 
 Every event on this bus is published by the UI Kit itself — the Chat SDK has no thread listener, and a `subscribeToThread()` / `unsubscribeFromThread()` callback *is* the acknowledgement. Because surfaces do not share message instances, a handler should update its own state **and** stamp the flag onto the message objects it holds with `BaseMessage.setThreadSubscribed()`.
 
@@ -190,7 +190,7 @@
 }
 ```
 
-See the [Thread Subscription guide](/ui-kit/android/guide-thread-subscription) for the feature end to end.
+See [Threaded Messages → Thread Subscription](/ui-kit/android/guide-threaded-messages#thread-subscription) for the feature end to end.
 
 ### Call Events
 
@@ -552,7 +552,7 @@
 </Tab>
 </Tabs>
 
 > **About `CardActionClicked`:** The UI Kit renders card bubbles automatically (`CometChatCardBubble`) and emits this event when a user taps an action inside one — so a single subscriber handles every card action across your app. `event.message` is a `CardMessage` for standalone [card messages](/sdk/android/v5/send-message#card-message) and an `AIAssistantMessage` for cards embedded in AI agent replies. `event.actionEvent` is typed `Any`; import and cast it to `com.cometchat.cards.actions.CometChatCardActionEvent` to read its `action`, `elementId`, and `cardJson`.
 
 ---
 
@@ -560,8 +560,8 @@
 
 Since `SharedFlow` collection is coroutine-based, lifecycle management is handled automatically:
 
 - In XML Views, use `lifecycleScope.launch` — the coroutine is cancelled when the lifecycle owner is destroyed.
 - In Jetpack Compose, use `LaunchedEffect` — the coroutine is cancelled when the composable leaves the composition.
 
 No manual `removeListener` calls are needed, unlike the old static listener pattern.
 

ui-kit/android/guide-overview.mdx

@@ -16,7 +16,7 @@
 
 </Accordion>
 
 > This page indexes focused, task‑oriented feature guides for the Android UI Kit. Each guide shows how to implement a specific capability end‑to‑end using UIKit components. Guides include both **Kotlin (XML Views)** and **Jetpack Compose** examples where applicable.
 
 ## When to Use These Guides
 
@@ -27,7 +27,7 @@
 | Module | Description |
 |:-------|:------------|
 | `chatuikit-kotlin` | Traditional XML-based Views for use with Activities and Fragments. |
 | `chatuikit-jetpack` | Jetpack Compose components for declarative UI. |
 
 ## Guide Directory
 
@@ -41,7 +41,8 @@
 | [Threaded Messages](/ui-kit/android/guide-threaded-messages) | Threaded replies: open parent message context, list replies, compose with parent linkage. |
 | [Search Messages](/ui-kit/android/guide-search-messages) | Full-text message search across conversations with result routing and navigation. |
 | [AI Agent](/ui-kit/android/guide-ai-agent) | Build an AI-powered agent that responds to user messages using CometChat's AI features. |
-| [Custom Text Formatter](/ui-kit/android/custom-text-formatter-guide) | Extend `CometChatTextFormatter` to build custom inline text patterns with tracking characters and suggestion lists. |
+| [Custom Text Formatter](/ui-kit/android/guide-text-color) | Add a color button to the composer toolbar that colors selected text, rendered in the sent message. |
+| [Text Formatter Base Class](/ui-kit/android/custom-text-formatter-guide) | Extend `CometChatTextFormatter` to build custom inline text patterns with tracking characters and suggestion lists. |
 | [Mentions Formatter](/ui-kit/android/mentions-formatter-guide) | Format @mentions with styled tokens, suggestion lists, and click handling. |
 | [ShortCut Formatter](/ui-kit/android/shortcut-formatter-guide) | Add shortcut text expansion to the message composer via the message-shortcuts extension. |