@cometchat/skills 3.0.0 → 4.0.0

package/skills/cometchat-flutter-v5-customization/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: cometchat-flutter-v5-customization
+description: "Use when customizing CometChat Flutter UIKit v5 beyond props — custom bubbles, templates, DataSource decorators, slot views, formatters."
+license: "MIT"
+compatibility: "cometchat_chat_uikit ^5.2.14; cometchat_uikit_shared ^5.2.3"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat flutter v5 customization templates datasource decorator bubbles formatters"
+---
+
+# CometChat Flutter UIKit v5 — Customization
+
+Four tiers of customization, from simple to deep.
+
+## Tier 1: Props
+
+Pass props directly to components:
+
+```dart
+CometChatMessageList(
+  user: user,
+  hideEditMessageOption: true,
+  hideReactionOption: true,
+  receiptsVisibility: false,
+)
+```
+
+## Tier 2: Slot Views
+
+Replace specific UI sections via callback props:
+
+```dart
+CometChatConversations(
+  subtitleView: (context, conversation) {
+    final lastMessage = conversation.lastMessage;
+    if (lastMessage is TextMessage) {
+      return Text(lastMessage.text, maxLines: 1, overflow: TextOverflow.ellipsis);
+    }
+    return null; // Falls back to default
+  },
+  trailingView: (conversation) {
+    return Badge(count: conversation.unreadMessageCount);
+  },
+)
+
+CometChatMessageHeader(
+  listItemView: (group, user, context) {
+    return Column(
+      crossAxisAlignment: CrossAxisAlignment.start,
+      children: [
+        Text("Thread", style: TextStyle(fontWeight: FontWeight.bold)),
+        Text(user?.name ?? group?.name ?? ""),
+      ],
+    );
+  },
+)
+```
+
+Available slot views per component:
+- `CometChatConversations`: `subtitleView`, `listItemView`, `trailingView`, `leadingView`, `titleView`
+- `CometChatMessageHeader`: `subtitleView`, `listItemView`, `trailingView`
+- `CometChatMessageList`: `headerView`, `footerView`, `loadingStateView`, `emptyStateView`, `errorStateView`
+- `CometChatUsers`: `subtitleView`, `listItemView`, `leadingView`, `titleView`, `trailingView`
+- `CometChatGroups`: `subtitleView`, `listItemView`, `leadingView`, `titleView`, `trailingView`
+
+## Tier 3: Text Formatters
+
+Custom text formatters transform how message text is displayed:
+
+```dart
+CometChatMessageList(
+  textFormatters: [
+    CometChatEmailFormatter(),
+    CometChatPhoneNumberFormatter(),
+    CometChatUrlFormatter(),
+    CometChatMentionsFormatter(
+      user: user,
+      group: group,
+      onMentionTap: (mention, mentionedUser, {message}) {
+        // Navigate to user's chat
+      },
+    ),
+  ],
+)
+```
+
+Built-in formatters:
+- `CometChatEmailFormatter` — makes emails tappable
+- `CometChatPhoneNumberFormatter` — makes phone numbers tappable
+- `CometChatUrlFormatter` — makes URLs tappable
+- `CometChatMentionsFormatter` — handles @mentions with tap callbacks
+
+Pass the same formatters to both `CometChatMessageList` and `CometChatMessageComposer` for consistency.
+
+## Tier 4: DataSource Decorator Pattern
+
+The deepest customization level. `ChatConfigurator` uses a decorator pattern with `MessagesDataSource` as the base:
+
+```
+ChatConfigurator
+  └── DataSource (interface)
+      └── MessagesDataSource (default implementation)
+          └── ExtensionDecorator (wraps and overrides)
+```
+
+### How extensions use it
+
+Each extension (polls, stickers, link preview, etc.) has a decorator:
+
+```dart
+// Example: PollsExtensionDecorator wraps the DataSource
+class PollsExtensionDecorator extends DataSourceDecorator {
+  PollsExtensionDecorator(DataSource dataSource) : super(dataSource);
+
+  @override
+  List<CometChatMessageTemplate> getAllMessageTemplates() {
+    // Add poll template to existing templates
+    return [...super.getAllMessageTemplates(), _getPollTemplate()];
+  }
+}
+```
+
+Extensions are registered via `UIKitSettingsBuilder`:
+
+```dart
+final settings = (UIKitSettingsBuilder()
+  ..extensions = CometChatUIKitChatExtensions.getDefaultExtensions()
+  ..aiFeature = CometChatUIKitChatAIFeatures.getDefaultAiFeatures()
+).build();
+```
+
+### Available extensions
+
+| Extension | Decorator | What it adds |
+|-----------|-----------|-------------|
+| Polls | `PollsExtensionDecorator` | Poll creation + voting bubble |
+| Stickers | `StickersExtensionDecorator` | Sticker keyboard + bubble |
+| Link Preview | `LinkPreviewExtensionDecorator` | URL preview cards |
+| Message Translation | `MessageTranslationExtensionDecorator` | Translate option |
+| Image Moderation | `ImageModerationExtensionDecorator` | NSFW filter |
+| Collaborative Document | `CollaborativeDocumentExtensionDecorator` | Shared doc |
+| Collaborative Whiteboard | `CollaborativeWhiteboardExtensionDecorator` | Shared whiteboard |
+| Thumbnail Generation | `ThumbnailGenerationExtensionDecorator` | Image thumbnails |
+
+### CometChatCallingExtension
+
+The calling extension also uses this pattern:
+
+```dart
+class CometChatCallingExtension extends ExtensionsDataSource {
+  @override
+  void addExtension() {
+    ChatConfigurator.enable((dataSource) =>
+        CallingExtensionDecorator(dataSource, configuration: configuration));
+  }
+}
+```
+
+## Message Templates
+
+`CometChatMessageTemplate` defines how a message type is rendered:
+
+```dart
+CometChatMessageList(
+  templates: [
+    CometChatMessageTemplate(
+      type: 'custom_type',
+      category: 'custom',
+      contentView: (message, context, alignment) {
+        return Container(
+          child: Text('Custom bubble: ${message.id}'),
+        );
+      },
+    ),
+  ],
+)
+```
+
+## Options Menu Customization
+
+Add or replace long-press options on conversations, users, groups:
+
+```dart
+CometChatConversations(
+  // Replace all options
+  setOptions: (conversation, controller, context) {
+    return [CometChatOption(id: 'pin', title: 'Pin', onClick: () { ... })];
+  },
+  // Add to existing options
+  addOptions: (conversation, controller, context) {
+    return [CometChatOption(id: 'archive', title: 'Archive', onClick: () { ... })];
+  },
+)
+```
+
+## Header Options (Messages)
+
+```dart
+CometChatMessageHeader(
+  options: (user, group, context) {
+    return [
+      CometChatOption(
+        id: 'user-info',
+        title: 'User Info',
+        iconWidget: Icon(Icons.info_outline),
+        onClick: () { ... },
+      ),
+      CometChatOption(
+        id: 'search',
+        title: 'Search',
+        iconWidget: Icon(Icons.search),
+        onClick: () { ... },
+      ),
+    ];
+  },
+)
+```
+
+## Checklist — Customization
+
+- [ ] Start with props (Tier 1) before going deeper
+- [ ] Slot views return `null` to fall back to default rendering
+- [ ] Text formatters consistent between MessageList and Composer
+- [ ] Extensions registered via `UIKitSettingsBuilder.extensions`
+- [ ] Custom templates specify `type` and `category`

package/skills/cometchat-flutter-v5-events/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: cometchat-flutter-v5-events
+description: "Use when working with CometChat Flutter UIKit v5 event system. Triggers on CometChatMessageEvents, CometChatUserEvents, CometChatGroupEvents, CometChatCallEvents, CometChatUIEvents, listeners."
+license: "MIT"
+compatibility: "cometchat_uikit_shared ^5.2.3; cometchat_sdk ^4.1.2"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat flutter v5 events listeners real-time typing receipts"
+---
+
+# CometChat Flutter UIKit v5 — Events
+
+Two layers: SDK listeners (low-level) and UIKit events (high-level component coordination).
+
+## Event System Architecture
+
+### Layer 1: SDK Listeners (CometChat SDK)
+Raw message/call/user/group events from the network.
+
+### Layer 2: UIKit Events (CometChat UIKit)
+High-level events emitted by UIKit components for UI coordination. Use a static `Map<String, Listener>` pattern.
+
+## Listener Registration Pattern
+
+All event classes follow the same register/remove pattern:
+
+```dart
+// ✅ CORRECT — register in initState, remove in dispose
+class _MyWidgetState extends State<MyWidget> {
+  late final String _listenerId;
+
+  @override
+  void initState() {
+    super.initState();
+    _listenerId = 'my_widget_${DateTime.now().millisecondsSinceEpoch}';
+
+    // UIKit events
+    CometChatMessageEvents.addMessagesListener(_listenerId, this);
+    CometChatUIEvents.addUiListener(_listenerId, this);
+
+    // SDK listeners
+    CometChat.addMessageListener(_listenerId, this);
+    CometChat.addUserListener(_listenerId, this);
+    CometChat.addGroupListener(_listenerId, this);
+    CometChat.addCallListener(_listenerId, this);
+  }
+
+  @override
+  void dispose() {
+    CometChatMessageEvents.removeMessagesListener(_listenerId);
+    CometChatUIEvents.removeUiListener(_listenerId);
+    CometChat.removeMessageListener(_listenerId);
+    CometChat.removeUserListener(_listenerId);
+    CometChat.removeGroupListener(_listenerId);
+    CometChat.removeCallListener(_listenerId);
+    super.dispose();
+  }
+}
+```
+
+For GetxController, use `onInit()` / `onClose()` instead of `initState()` / `dispose()`.
+
+## UIKit Event Classes — Registration
+
+| Class | Register | Remove |
+|-------|----------|--------|
+| `CometChatMessageEvents` | `addMessagesListener(id, listener)` | `removeMessagesListener(id)` |
+| `CometChatUserEvents` | `addUsersListener(id, listener)` | `removeUsersListener(id)` |
+| `CometChatGroupEvents` | `addGroupsListener(id, listener)` | `removeGroupsListener(id)` |
+| `CometChatCallEvents` | `addCallEventsListener(id, listener)` | `removeCallEventsListener(id)` |
+| `CometChatUIEvents` | `addUiListener(id, listener)` | `removeUiListener(id)` |
+| `CometChatConversationEvents` | `addConversationListListener(id, listener)` | `removeConversationListListener(id)` |
+
+## SDK Listeners — Registration
+
+| Listener | Register | Remove |
+|----------|----------|--------|
+| Messages | `CometChat.addMessageListener(id, this)` | `CometChat.removeMessageListener(id)` |
+| Users (online/offline) | `CometChat.addUserListener(id, this)` | `CometChat.removeUserListener(id)` |
+| Groups | `CometChat.addGroupListener(id, this)` | `CometChat.removeGroupListener(id)` |
+| Calls | `CometChat.addCallListener(id, this)` | `CometChat.removeCallListener(id)` |
+| Connection | `CometChat.addConnectionListener(id, this)` | `CometChat.removeConnectionListener(id)` |
+
+## Key UIKit Events (commonly used)
+
+**CometChatUIEvents:**
+- `openChat(User? user, Group? group)` — request to open a chat
+
+**CometChatMessageEvents:**
+- `ccMessageSent(BaseMessage message, MessageStatus status)` — message sent
+- `ccMessageEdited(BaseMessage message, MessageEditStatus status)` — message edited
+- `ccMessageDeleted(BaseMessage message, EventStatus status)` — message deleted
+
+**CometChatUserEvents:**
+- `ccUserBlocked(User user)` / `ccUserUnblocked(User user)`
+
+**CometChatGroupEvents:**
+- `ccGroupMemberKicked`, `ccGroupMemberBanned`, `ccGroupMemberAdded`, `ccOwnershipChanged`
+
+**CometChatCallEvents:**
+- `ccOutgoingCall(Call)`, `ccCallAccepted(Call)`, `ccCallRejected(Call)`, `ccCallEnded(Call)`
+
+## UIKit Events vs SDK Listeners
+
+- **UIKit events** — react to UIKit-level actions (message sent via composer, group created via UI, user blocked via UI)
+- **SDK listeners** — raw network events (message received, user online/offline, group member joined)
+- UIKit components internally use both
+
+## Gotchas
+
+### Unique Listener IDs
+```dart
+// ❌ WRONG — hardcoded ID
+CometChat.addMessageListener('messages', this);
+
+// ✅ CORRECT — unique ID
+final id = 'messages_${DateTime.now().millisecondsSinceEpoch}';
+CometChat.addMessageListener(id, this);
+```
+
+### Always Remove in dispose()
+```dart
+// ❌ WRONG — listener leaks
+@override
+void dispose() {
+  super.dispose();
+}
+
+// ✅ CORRECT
+@override
+void dispose() {
+  CometChat.removeMessageListener(_listenerId);
+  super.dispose();
+}
+```
+
+### Never Register in build()
+```dart
+// ❌ WRONG — called every rebuild
+@override
+Widget build(BuildContext context) {
+  CometChat.addMessageListener(id, this);
+  return Container();
+}
+```
+
+## Checklist — Events
+
+- [ ] Listener ID is unique (use timestamp or hashCode)
+- [ ] Listener registered in `initState()` / `onInit()`, not `build()`
+- [ ] Listener removed in `dispose()` / `onClose()` with same ID
+- [ ] UIKit events for UI coordination, SDK listeners for raw events
+- [ ] `subscriptionType` set in UIKitSettings for presence events to work

package/skills/cometchat-flutter-v5-messages/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: cometchat-flutter-v5-messages
+description: "Use when working with CometChat Flutter UIKit v5 message components. Triggers on CometChatMessageList, CometChatMessageComposer, CometChatCompactMessageComposer, CometChatMessageHeader, threads."
+license: "MIT"
+compatibility: "cometchat_chat_uikit ^5.2.14; cometchat_uikit_shared ^5.2.3"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat flutter v5 messages list composer header bubbles threads compact"
+---
+
+# CometChat Flutter UIKit v5 — Messages
+
+Components for displaying, sending, and managing messages.
+
+## CometChatMessageList
+
+Displays messages in a conversation.
+
+### Key Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `user` | `User?` | — | User for 1-on-1 chat (one of user/group required) |
+| `group` | `Group?` | — | Group for group chat |
+| `messagesRequestBuilder` | `MessagesRequestBuilder?` | — | Custom message fetch builder |
+| `style` | `CometChatMessageListStyle?` | — | Visual styling |
+| `alignment` | `ChatAlignment` | `standard` | `standard` or `leftAligned` |
+| `onThreadRepliesClick` | `ThreadRepliesClick?` | — | Thread reply tap callback |
+| `templates` | `List<CometChatMessageTemplate>?` | — | Custom message templates |
+| `textFormatters` | `List<CometChatTextFormatter>?` | — | Custom text formatters |
+| `receiptsVisibility` | `bool` | `true` | Show read receipts |
+| `avatarVisibility` | `bool` | `true` | Show avatars |
+| `disableReactions` | `bool` | `false` | Disable reactions |
+| `disableMentions` | `bool?` | — | Disable @mentions |
+| `messageId` | `int?` | — | Scroll to specific message |
+| `startFromUnreadMessages` | `bool` | `false` | Start from unread |
+| `showMarkAsUnreadOption` | `bool` | `false` | Show mark-as-unread option |
+| `enableSmartReplies` | `bool` | `false` | Enable AI smart replies |
+| `enableConversationStarters` | `bool` | `false` | Enable conversation starters |
+| `generateConversationSummary` | `bool` | `false` | Generate AI summary |
+| `hideEditMessageOption` | `bool` | `false` | Hide edit option |
+| `hideDeleteMessageOption` | `bool` | `false` | Hide delete option |
+| `hideReplyInThreadOption` | `bool` | `false` | Hide reply-in-thread |
+| `hideThreadView` | `bool?` | — | Hide thread view entirely |
+| `hideReactionOption` | `bool` | `false` | Hide reaction option |
+| `hideTranslateMessageOption` | `bool` | `false` | Hide translate option |
+| `hideMessagePrivatelyOption` | `bool` | `false` | Hide private message option |
+| `hideMessageInfoOption` | `bool` | `false` | Hide message info |
+| `hideFlagOption` | `bool` | `false` | Hide flag/report option |
+| `loadingStateView` | `WidgetBuilder?` | — | Custom loading state |
+| `emptyStateView` | `WidgetBuilder?` | — | Custom empty state |
+| `errorStateView` | `WidgetBuilder?` | — | Custom error state |
+
+### Usage
+
+```dart
+CometChatMessageList(
+  user: user,
+  textFormatters: [
+    CometChatEmailFormatter(),
+    CometChatPhoneNumberFormatter(),
+    CometChatUrlFormatter(),
+    CometChatMentionsFormatter(user: user),
+  ],
+  receiptsVisibility: true,
+  hideReplyInThreadOption: false,
+  hideEditMessageOption: false,
+  hideDeleteMessageOption: false,
+)
+```
+
+## CometChatMessageComposer
+
+Full-featured message input with attachments, voice recording, mentions, and AI features.
+
+### Key Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `user` | `User?` | — | Target user (one of user/group required) |
+| `group` | `Group?` | — | Target group |
+| `messageComposerStyle` | `CometChatMessageComposerStyle?` | — | Visual styling |
+| `parentMessageId` | `int` | `0` | Thread parent message ID |
+| `placeholderText` | `String?` | — | Input placeholder |
+| `textFormatters` | `List<CometChatTextFormatter>?` | — | Text formatters |
+| `disableTypingEvents` | `bool` | `false` | Disable typing indicators |
+| `disableMentions` | `bool?` | — | Disable @mentions |
+| `disableMentionAll` | `bool` | `false` | Disable @all mentions |
+| `hideVoiceRecordingButton` | `bool?` | — | Hide voice recording |
+| `hideAttachmentButton` | `bool?` | — | Hide attachment button |
+| `hideSendButton` | `bool?` | — | Hide send button |
+| `hideStickersButton` | `bool?` | — | Hide stickers |
+| `hideImageAttachmentOption` | `bool?` | — | Hide image attachment |
+| `hideVideoAttachmentOption` | `bool?` | — | Hide video attachment |
+| `hideAudioAttachmentOption` | `bool?` | — | Hide audio attachment |
+| `hideFileAttachmentOption` | `bool?` | — | Hide file attachment |
+| `hidePollsOption` | `bool?` | — | Hide polls |
+| `hideCollaborativeDocumentOption` | `bool?` | — | Hide collaborative doc |
+| `hideCollaborativeWhiteboardOption` | `bool?` | — | Hide whiteboard |
+| `hideTakePhotoOption` | `bool?` | — | Hide take photo |
+| `onSendButtonTap` | `Function?` | — | Custom send handler |
+| `onError` | `OnError?` | — | Error callback |
+
+## CometChatCompactMessageComposer
+
+Compact variant with rounded pill-shaped input, inline rich text toolbar, and modern minimal aesthetic. Use it explicitly in your widget tree when you want this look — there is no global `Layout` toggle that swaps composers automatically.
+
+### Props unique to Compact (not in regular composer)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `compactMessageComposerStyle` | `CometChatCompactMessageComposerStyle?` | — | Visual styling |
+| `enableRichTextFormatting` | `bool` | `true` | Enable rich text (master switch) |
+| `showRichTextFormattingOptions` | `bool` | `true` | Show toolbar above composer |
+| `showTextSelectionMenuItems` | `bool` | `true` | Formatting in text selection menu |
+| `hideRichTextFormattingOptions` | `Set<FormatType>?` | — | Hide specific format types |
+| `richTextToolbarStyle` | `CometChatRichTextToolbarStyle?` | — | Toolbar styling |
+| `enterKeyBehavior` | `EnterKeyBehavior` | `newLine` | Enter key: `sendMessage` or `newLine` |
+
+All other props (user, group, parentMessageId, hide* options, textFormatters, etc.) are the same as `CometChatMessageComposer`.
+
+### Usage
+
+```dart
+// ✅ CORRECT — compact composer with thread support
+CometChatCompactMessageComposer(
+  user: user,
+  parentMessageId: parentMessage.id,
+  disableTypingEvents: false,
+  disableMentions: false,
+  hideVoiceRecordingButton: false,
+)
+```
+
+## CometChatMessageHeader
+
+Displays user/group info. Implements `PreferredSizeWidget` for use as `appBar`.
+
+### Key Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `user` | `User?` | User to display |
+| `group` | `Group?` | Group to display |
+| `messageHeaderStyle` | `CometChatMessageHeaderStyle?` | Visual styling |
+| `subtitleView` | `Widget? Function(Group?, User?, BuildContext)?` | Custom subtitle |
+| `listItemView` | `Widget Function(Group?, User?, BuildContext)?` | Custom list item |
+| `showBackButton` | `bool?` | Show back button (default: true) |
+| `onBack` | `VoidCallback?` | Back button callback |
+| `hideVideoCallButton` | `bool?` | Hide video call button |
+| `hideVoiceCallButton` | `bool?` | Hide voice call button |
+| `usersStatusVisibility` | `bool` | Show online status (default: true) |
+| `options` | `Function(User?, Group?, BuildContext)?` | Custom header options menu |
+
+## CometChatThreadedHeader
+
+Displays the parent message for threaded conversations.
+
+### Key Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `parentMessage` | `BaseMessage` | The parent message (required) |
+| `loggedInUser` | `User` | Current logged-in user (NON-nullable; pass `CometChatUIKit.loggedInUser!`) |
+| `template` | `CometChatMessageTemplate?` | Message template |
+| `receiptsVisibility` | `bool?` | Show receipts |
+| `height` | `double?` | Header height |
+| `width` | `double?` | Header width |
+| `messageActionView` | `Function(BaseMessage, BuildContext)?` | Builder for a custom action view in the header |
+| `style` | `CometChatThreadedHeaderStyle?` | Visual style |
+| `textFormatters` | `List<CometChatTextFormatter>?` | Custom text formatters |
+
+### Threaded Messages Pattern
+
+```dart
+Scaffold(
+  body: Column(
+    children: [
+      CometChatThreadedHeader(
+        parentMessage: parentMessage,
+        loggedInUser: CometChatUIKit.loggedInUser!,
+      ),
+      Expanded(
+        child: CometChatMessageList(
+          user: user,
+          messagesRequestBuilder: MessagesRequestBuilder()
+            ..parentMessageId = parentMessage.id,
+        ),
+      ),
+      CometChatMessageComposer(
+        user: user,
+        parentMessageId: parentMessage.id,
+      ),
+    ],
+  ),
+)
+```
+
+## Sending Messages Programmatically
+
+Use `CometChatUIKit` static methods (not `CometChat` directly) to ensure UIKit events fire:
+
+```dart
+// ✅ CORRECT
+CometChatUIKit.sendTextMessage(message, onSuccess: ..., onError: ...);
+
+// ❌ WRONG — bypasses UIKit events (ccMessageSent won't fire)
+CometChat.sendMessage(message, onSuccess: ...);
+```
+
+## Golden Path — Messages Screen
+
+```dart
+class MessagesScreen extends StatelessWidget {
+  final User? user;
+  final Group? group;
+  const MessagesScreen({super.key, this.user, this.group});
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: CometChatMessageHeader(
+        user: user,
+        group: group,
+        onBack: () => Navigator.pop(context),
+      ),
+      body: Column(
+        children: [
+          Expanded(child: CometChatMessageList(user: user, group: group)),
+          CometChatMessageComposer(user: user, group: group),
+        ],
+      ),
+    );
+  }
+}
+```
+
+## Anti-Patterns
+
+```dart
+// ❌ WRONG — passing two NON-null targets at the same time
+CometChatMessageList(user: aUser, group: aGroup) // ambiguous — kit ignores group
+// ✅ At any moment, exactly one of user/group must be non-null.
+// Passing both fields with one null (e.g. `user: user, group: null`) is fine
+// and is what the chat-builder sample app does to switch between contexts.
+
+// ❌ WRONG — using CometChat.sendMessage instead of CometChatUIKit
+CometChat.sendMessage(message, onSuccess: ...);
+```
+
+## Checklist — Messages Screen
+
+- [ ] Only one of `user` or `group` passed to each component
+- [ ] Same `user`/`group` passed to Header, List, and Composer
+- [ ] Thread replies use `parentMessageId` on both List and Composer
+- [ ] Messages sent via `CometChatUIKit.sendTextMessage()`