@cometchat/skills 4.3.0 → 4.4.1

package/skills/cometchat-flutter-v5-calls/references/raise-hand.md

@@ -9,31 +9,36 @@ Same SDK conceptual API as web/native. Flutter V5 uses GetX for state management
 
 ## SDK API
 
+Raise/lower hand are **instance methods on the `CallSession` singleton**, NOT static on `CometChatCalls` (`cometchat_calls_sdk-5.0.2` `src/call_session.dart:292,306`). Participant hand events arrive via `ParticipantEventListeners`, registered through `CallSession.getInstance()?.addParticipantEventListener(...)` (`src/call_session.dart:74`).
+
 ```dart
-import 'package:cometchat_calls_uikit/cometchat_calls_uikit.dart';
+import 'package:cometchat_calls_sdk/cometchat_calls_sdk.dart';
 
 // Local user
-CometChatCalls.raiseHand();
-CometChatCalls.lowerHand();
+CallSession.getInstance()?.raiseHand();   // call_session.dart:292
+CallSession.getInstance()?.lowerHand();   // call_session.dart:306
 
-// Listener — registered via the call event listener attached to the OngoingCall widget
-class CallListener implements CometChatCallsEventsListener {
+// Listener — implement the split ParticipantEventListeners interface
+class HandListener implements ParticipantEventListeners {
   @override
-  void onParticipantHandRaised(Participant participant) {
-    // participant.uid, participant.name
+  void onParticipantHandRaised(Participant participant) {  // participant_event_listeners.dart:30
+    // participant.uid, participant.name (both nullable)
   }
 
   @override
-  void onParticipantHandLowered(Participant participant) {
+  void onParticipantHandLowered(Participant participant) {  // :33
     // ...
   }
-  // ... other event handlers
+  // ... other ParticipantEventListeners methods (no-ops or pass-through)
 }
 
-// Settings flag
-final settings = CallSettingsBuilder()
-  ..hideRaiseHandButton = true;
-final builtSettings = settings.build();
+// Register on the session singleton (inside joinSession.onSuccess):
+CallSession.getInstance()?.addParticipantEventListener(HandListener());  // :74
+
+// Settings flag — method on the (non-deprecated) SessionSettingsBuilder.
+final settings = (SessionSettingsBuilder()
+      ..hideRaiseHandButton(true))   // session_settings.dart:215
+    .build();
 ```
 
 ---
@@ -42,7 +47,7 @@ final builtSettings = settings.build();
 
 ```dart
 import 'package:get/get.dart';
-import 'package:cometchat_calls_uikit/cometchat_calls_uikit.dart';
+import 'package:cometchat_calls_sdk/cometchat_calls_sdk.dart';
 
 class RaisedParticipant {
   final String uid;
@@ -51,35 +56,37 @@ class RaisedParticipant {
   RaisedParticipant({required this.uid, required this.name, required this.raisedAt});
 }
 
-class RaiseHandController extends GetxController implements CometChatCallsEventsListener {
+class RaiseHandController extends GetxController implements ParticipantEventListeners {
   final localRaised = false.obs;
   final raised = <RaisedParticipant>[].obs;
 
   void toggle() {
     if (localRaised.value) {
-      CometChatCalls.lowerHand();
+      CallSession.getInstance()?.lowerHand();
     } else {
-      CometChatCalls.raiseHand();
+      CallSession.getInstance()?.raiseHand();
     }
     localRaised.value = !localRaised.value;
   }
 
   @override
   void onParticipantHandRaised(Participant p) {
+    // Participant.uid / .name are nullable in 5.x.
+    final uid = p.uid ?? '';
     final entry = RaisedParticipant(
-      uid: p.uid, name: p.name, raisedAt: DateTime.now(),
+      uid: uid, name: p.name ?? uid, raisedAt: DateTime.now(),
     );
-    raised.removeWhere((r) => r.uid == p.uid);
+    raised.removeWhere((r) => r.uid == uid);
     raised.add(entry);
     raised.sort((a, b) => a.raisedAt.compareTo(b.raisedAt));
   }
 
   @override
   void onParticipantHandLowered(Participant p) {
-    raised.removeWhere((r) => r.uid == p.uid);
+    raised.removeWhere((r) => r.uid == (p.uid ?? ''));
   }
 
-  // ... implement other CometChatCallsEventsListener methods (no-ops or pass-through)
+  // ... implement other ParticipantEventListeners methods (no-ops or pass-through)
 }
 ```
 
@@ -186,25 +193,29 @@ class RaisedHandsSheet extends StatelessWidget {
 ## Wiring to the call session
 
 ```dart
+RaiseHandController? _handCtrl;
+
 @override
 void initState() {
   super.initState();
-  Get.put(RaiseHandController());
-
-  // Attach to the call session — the controller IS the listener
-  final ctrl = Get.find<RaiseHandController>();
-  CometChatCalls.addCallEventListener('raise-hand', ctrl);
+  _handCtrl = Get.put(RaiseHandController());
+  // NOTE: attach the listener inside joinSession.onSuccess (CallSession.getInstance()
+  // is null until the session exists). If this widget is mounted only after the
+  // session is live, attach here:
+  CallSession.getInstance()?.addParticipantEventListener(_handCtrl!);  // call_session.dart:74
 }
 
 @override
 void dispose() {
-  CometChatCalls.removeCallEventListener('raise-hand');
+  if (_handCtrl != null) {
+    CallSession.getInstance()?.removeParticipantEventListener(_handCtrl!);  // call_session.dart:78
+  }
   Get.delete<RaiseHandController>();
   super.dispose();
 }
 ```
 
-Use a STABLE listener ID ('raise-hand'). Changing IDs across remounts orphans listeners — duplicate events fire for each.
+The 5.x SDK identifies listeners by object identity (a `Set`), not a string ID — keep the same controller instance you registered and pass it to `removeParticipantEventListener` on dispose.
 
 ---
 
@@ -227,9 +238,9 @@ Web sister reference rules apply, plus Flutter V5-specific:
 - [ ] `Obx` wraps only reactive parts of the UI
 - [ ] `Semantics` wrapper on toggle button with `button: true, selected:, label:`
 - [ ] `SemanticsService.announce` on toggle
-- [ ] Stable listener ID for `addCallEventListener` / `removeCallEventListener`
+- [ ] Same controller instance registered via `CallSession.getInstance()?.addParticipantEventListener(ctrl)` and removed via `removeParticipantEventListener(ctrl)` on dispose
 - [ ] `Get.delete<RaiseHandController>()` in `dispose()`
-- [ ] `hideRaiseHandButton: true` in CallSettings if custom UI
+- [ ] `SessionSettingsBuilder()..hideRaiseHandButton(true)` if custom UI
 - [ ] Real-device smoke: 3 devices (mix of iOS + Android), raise from 2 → host sees both
 - [ ] TalkBack / VoiceOver announces "Hand raised" / "Hand lowered" on toggle
 

package/skills/cometchat-flutter-v5-calls/references/ringing-integration.md

@@ -10,7 +10,7 @@ Same SDK shape as web/RN. Flutter-specific deltas: GetX-controlled state, flutte
 
 ```dart
 import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
-import 'package:cometchat_calls_uikit/cometchat_calls_uikit.dart';
+import 'package:cometchat_sdk/cometchat_sdk.dart';   // Call, CallListener (Chat SDK signaling)
 
 class CallSignalingController extends GetxController implements CallListener {
   final incoming = Rx<Call?>(null);
@@ -56,27 +56,30 @@ class CallSignalingController extends GetxController implements CallListener {
   Future<void> initiate(String receiverUid, {String type = 'video'}) async {
     final call = Call(
       receiverUid: receiverUid,
-      callType: type == 'video' ? CometChatCallType.video : CometChatCallType.audio,
+      type: type == 'video' ? CometChatCallType.video : CometChatCallType.audio, // ctor param is `type`, not `callType`
       receiverType: CometChatReceiverType.user,
     );
-    final result = await CometChat.initiateCall(call: call);
-    if (result is Call) outgoing.value = result;
+    // initiateCall is void + callback: the Call comes back in onSuccess, not via await.
+    CometChat.initiateCall(call,
+      onSuccess: (Call result) => outgoing.value = result,
+      onError: (CometChatException e) => debugPrint(e.message ?? ''));
   }
 
   Future<void> accept(Call call) async {
-    final result = await CometChat.acceptCall(sessionId: call.sessionId!);
-    if (result is Call) {
-      incoming.value = null;
-      activeSessionId.value = result.sessionId;
-    }
+    // acceptCall takes the sessionID POSITIONALLY + onSuccess/onError; it returns void.
+    CometChat.acceptCall(call.sessionId!,
+      onSuccess: (Call result) {
+        incoming.value = null;
+        activeSessionId.value = result.sessionId;
+      },
+      onError: (CometChatException e) => debugPrint(e.message ?? ''));
   }
 
   Future<void> reject(Call call) async {
-    await CometChat.rejectCall(
-      sessionId: call.sessionId!,
-      status: CallStatus.rejected,
-    );
-    incoming.value = null;
+    // rejectCall: positional sessionID + status String + onSuccess/onError (void).
+    CometChat.rejectCall(call.sessionId!, CometChatCallStatus.rejected,
+      onSuccess: (Call result) => incoming.value = null,
+      onError: (CometChatException e) => debugPrint(e.message ?? ''));
   }
 
   @override

package/skills/cometchat-flutter-v5-calls/references/share-invite.md

@@ -62,9 +62,15 @@ void initDeepLinks() {
 ## SDK API
 
 ```dart
-final settings = CallSettingsBuilder()
-  ..setHideShareInviteButton(false);
+import 'package:cometchat_calls_sdk/cometchat_calls_sdk.dart';
 
+final settings = (SessionSettingsBuilder()
+      ..hideShareInviteButton(false))   // session_settings.dart:221
+    .build();
+
+// The share-invite tap arrives on ButtonClickListeners
+// (src/listener/button_click_listeners.dart:13), registered via
+// CallSession.getInstance()?.addButtonClickListener(...) (call_session.dart:90):
 @override
 void onShareInviteButtonClicked() {
   Get.find<ShareInviteController>().share(sessionId);

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

@@ -3,13 +3,14 @@ name: cometchat-flutter-v5-conversations
 description: "Use when working with CometChat Flutter UIKit v5 conversation list component. Triggers on CometChatConversations, conversation list, recent chats."
 license: "MIT"
 compatibility: "cometchat_chat_uikit ^5.2.14; cometchat_uikit_shared ^5.2.3"
-allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"
   tags: "cometchat flutter v5 conversations list recent chats"
 ---
 
+> **Ground truth:** `cometchat_chat_uikit: ^5.2` (legacy/maintenance-only; calls via raw `cometchat_calls_sdk ^5.0.2`) — pub-cache source + `ui-kit/flutter/v5`. **Official docs:** https://www.cometchat.com/docs/ui-kit/flutter/v5/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.
+
 # CometChat Flutter UIKit v5 — Conversations
 
 The `CometChatConversations` component displays a list of recent conversations.

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

@@ -3,7 +3,6 @@ name: cometchat-flutter-v5-core
 description: "Use when writing any code that uses CometChat Flutter UIKit v5 (cometchat_chat_uikit v5.2.14, cometchat_calls_uikit v5.0.15, cometchat_uikit_shared v5.2.3). Contains hard rules that prevent silent failures."
 license: "MIT"
 compatibility: "cometchat_chat_uikit ^5.2.14; cometchat_calls_uikit ^5.0.15; cometchat_uikit_shared ^5.2.3; cometchat_sdk ^4.1.2; get ^4.6.5"
-allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"
@@ -12,13 +11,15 @@ metadata:
 
 # CometChat Flutter UIKit v5 — Core Rules
 
+> **Ground truth:** `cometchat_chat_uikit: ^5.2` (GetX-based; pair with `cometchat_calls_uikit: ^5.0` / raw `cometchat_calls_sdk ^5.0.2` for calls) — the pub-cache package source + `docs/ui-kit/flutter/v5`. **Official docs:** https://www.cometchat.com/docs/ui-kit/flutter/v5/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP). V5 is legacy/maintenance-only (V6 is current); verify Dart symbols against the resolved package source.
+
 Non-negotiable constraints for all CometChat UIKit v5 code. Violating these causes silent failures or crashes.
 
 ## Key v5 Architecture Facts
 
 - State management: **GetX** (GetBuilder, GetxController, Get.put, Get.find, Get.delete)
 - Separate packages: `cometchat_chat_uikit` + `cometchat_calls_uikit` + `cometchat_uikit_shared`
-- SDK: `cometchat_sdk ^4.1.2` + `cometchat_calls_sdk ^4.2.2`
+- SDK: `cometchat_sdk ^4.1.2` + `cometchat_calls_sdk ^4.2.2` (chat-kit baseline). **For voice/video calling, do NOT use `cometchat_calls_uikit` (4.x-bound) — integrate the raw `cometchat_calls_sdk ^5.0.2` per `cometchat-flutter-v5-calls`** (the V5-canonical calls path).
 - **Imports — two barrels.** For chat-only projects: `package:cometchat_chat_uikit/cometchat_chat_uikit.dart`. For projects that also need voice/video calling: ADD `package:cometchat_calls_uikit/cometchat_calls_uikit.dart` as a SECOND import — the calls barrel re-exports shared + SDK only and does NOT re-export `cometchat_chat_uikit`. Chat widgets like `CometChatConversations`, `CometChatMessageList`, `CometChatMessageComposer` are reachable only through the chat barrel.
 - `CometChatUIKit.login(uid)` takes a **String** directly (not an object)
 - No ServiceLocator pattern — controllers are created via `Get.put()` internally
@@ -227,7 +228,7 @@ void dispose() {
 **The full recipe lives in `cometchat-flutter-v6-core` §"Visual Builder integration"** because that's where the V6-prep restructure originally landed the validated content. Both skills reference the same canonical; the V6 page carries a "V5-shaped code" warning at the top. V5 customers should follow that recipe AS-IS — the canonical IS V5-targeted.
 
 Validated 2026-05-21 against Flutter 3.38.3: `flutter build apk --debug` produces `app-debug.apk` after applying:
-- Envelope-wrapped JSON at `chat_builder/assets/sample_app/cometchat-builder-settings.json` (`{ builderId, name, settings: {...} }`)
+- Envelope-wrapped JSON at `chat_builder/assets/sample_app/cometchat-builder-settings.json`. The CLI (source of truth) writes `{ builderId, name, settings: {...} }`; the vendor canonical's own checked-in file carries only `{ builderId, settings }` (no `name`). `BuilderSettingsHelper.loadFromAsset()` reads only `builderId` + `settings` and ignores any extra top-level keys, so the CLI's extra `name` is harmless.
 - Two missing-field defaults injected pre-write (mentionAll + inAppSounds — same as Android)
 - `android.enableJetifier=true` in `android/gradle.properties` (the chat SDK pulls `com.android.support` transitively)
 - `await BuilderSettingsHelper.loadFromAsset()` in `lib/main.dart` before `runApp()`
@@ -235,4 +236,4 @@ Validated 2026-05-21 against Flutter 3.38.3: `flutter build apk --debug` produce
 
 Differences from the V6 page's recipe text:
 - V5 host code uses `StatefulWidget` with direct listener management (V6 uses BLoC pattern); both work with the embedded chat_builder package since it owns its own state.
-- V5 calls work via the standard `cometchat-flutter-v5-calls` flow — no [[project_v6_flutter_calls_partial]] navigatorKey workaround needed (that's a V6-beta-specific issue).
+- V5 calls (the standalone `cometchat-flutter-v5-calls` flow, outside the builder) don't need the [[project_v6_flutter_calls_partial]] navigatorKey workaround — that's a V6-specific incoming-call-routing requirement. **However, the Visual Builder canonical itself (V5-shaped) wires `navigatorKey: CallNavigationContext.navigatorKey` UNCONDITIONALLY in every `MaterialApp` `ChatBuilder.createApp()` builds**, regardless of whether calls are enabled — so if you mount `ChatBuilder.createApp()` (recommended) or replicate its `MaterialApp` in a host wrapper, keep that navigator key in place. Do NOT gate it behind "calls enabled". See the v6-core recipe's wrapper guidance.

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

@@ -3,13 +3,14 @@ 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: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"
   tags: "cometchat flutter v5 customization templates datasource decorator bubbles formatters"
 ---
 
+> **Ground truth:** `cometchat_chat_uikit: ^5.2` (legacy/maintenance-only; calls via raw `cometchat_calls_sdk ^5.0.2`) — pub-cache source + `ui-kit/flutter/v5`. **Official docs:** https://www.cometchat.com/docs/ui-kit/flutter/v5/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.
+
 # CometChat Flutter UIKit v5 — Customization
 
 Four tiers of customization, from simple to deep.
@@ -60,7 +61,7 @@ CometChatMessageHeader(
 
 Available slot views per component:
 - `CometChatConversations`: `subtitleView`, `listItemView`, `trailingView`, `leadingView`, `titleView`
-- `CometChatMessageHeader`: `subtitleView`, `listItemView`, `trailingView`
+- `CometChatMessageHeader`: `subtitleView`, `listItemView`, `trailingView`, `titleView`
 - `CometChatMessageList`: `headerView`, `footerView`, `loadingStateView`, `emptyStateView`, `errorStateView`
 - `CometChatUsers`: `subtitleView`, `listItemView`, `leadingView`, `titleView`, `trailingView`
 - `CometChatGroups`: `subtitleView`, `listItemView`, `leadingView`, `titleView`, `trailingView`
@@ -138,12 +139,16 @@ final settings = (UIKitSettingsBuilder()
 | Polls | `PollsExtensionDecorator` | Poll creation + voting bubble |
 | Stickers | `StickersExtensionDecorator` | Sticker keyboard + bubble |
 | Link Preview | `LinkPreviewExtensionDecorator` | URL preview cards |
-| Message Translation | `MessageTranslationExtensionDecorator` | Translate option |
+| Message Translation | `MessageExtensionTranslationDecorator` | Translate option |
 | Image Moderation | `ImageModerationExtensionDecorator` | NSFW filter |
 | Collaborative Document | `CollaborativeDocumentExtensionDecorator` | Shared doc |
-| Collaborative Whiteboard | `CollaborativeWhiteboardExtensionDecorator` | Shared whiteboard |
+| Collaborative Whiteboard | `CollaborativeWhiteBoardExtensionDecorator` | Shared whiteboard |
 | Thumbnail Generation | `ThumbnailGenerationExtensionDecorator` | Image thumbnails |
 
+> **Naming gotchas (kit-side inconsistencies)** — two decorator class names break the `[Feature]ExtensionDecorator` convention used by the other six. Use these exact spellings when subclassing or importing:
+> - `CollaborativeWhiteBoardExtensionDecorator` — capital **B** in `WhiteBoard` (matches the kit's typo; lowercase `b` will not resolve).
+> - `MessageExtensionTranslationDecorator` — token order is **inverted**; the public wrapper is `MessageTranslationExtension`, but the decorator itself uses `MessageExtensionTranslation`.
+
 ### CometChatCallingExtension
 
 The calling extension also uses this pattern:
@@ -164,7 +169,8 @@ class CometChatCallingExtension extends ExtensionsDataSource {
 
 ```dart
 CometChatMessageList(
-  templates: [
+  // ✅ APPEND with addTemplate — keeps every default bubble (text/image/video/file/…)
+  addTemplate: [
     CometChatMessageTemplate(
       type: 'custom_type',
       category: 'custom',
@@ -178,6 +184,127 @@ CometChatMessageList(
 )
 ```
 
+> **Use `addTemplate`, not `templates`, to add a type.** The `templates:` prop **replaces the entire set** — passing `templates: [myTemplate]` makes every default bubble (text, image, video, audio, file, …) stop rendering. `addTemplate:` layers your template on top of the defaults. Only reach for `templates:` when you deliberately want to redefine the whole list.
+
+> `contentView` also accepts an optional named `{AdditionalConfigurations? additionalConfigurations}` arg if your custom bubble needs access to additional config passed down from the parent.
+
+### Custom attachment options — append via a DataSourceDecorator (super), don't replace
+
+The composer's `attachmentOptions` builder returns the **whole** menu (a `ComposerActionsBuilder` — `(context, user, group, id)`), so returning `[myAction]` wipes photo/video/audio/file. The kit's own extensions add options by overriding `DataSource.getAttachmentOptions` and calling `super` first — do the same:
+
+```dart
+class MyDataSource extends DataSourceDecorator {
+  MyDataSource(DataSource ds) : super(ds);
+
+  @override
+  List<CometChatMessageComposerAction> getAttachmentOptions(
+    BuildContext context, Map<String, dynamic>? id,
+    AdditionalConfigurations? additionalConfigurations,
+  ) {
+    final actions = super.getAttachmentOptions(context, id, additionalConfigurations); // defaults
+    actions.add(CometChatMessageComposerAction(
+      id: 'location', title: 'Send Location',
+      onItemClick: (ctx, user, group) { /* pick + send (below) */ },
+    ));
+    return actions; // appended — defaults preserved
+  }
+}
+```
+
+### Sending a custom message — use the UIKit path, not the raw SDK
+
+```dart
+final message = CustomMessage(
+  receiverUid: user.uid,
+  receiverType: ReceiverTypeConstants.user,   // or .group
+  type: 'custom_type',                        // matches the template type
+  customData: {'lat': 19.07, 'lng': 72.87},
+);
+// ✅ kit path — sets muid + sender, emits ccMessageSent → list appends
+await CometChatUIKit.sendCustomMessage(message);
+// ❌ await CometChat.sendCustomMessage(message);  // recipient error + realtime replace
+```
+
+### Override an existing type's bubble
+
+To swap the content of a **built-in** type (e.g. text), **do NOT use `addTemplate:`** — a built-in collision passed via `addTemplate:` is silently dropped (the list controller backfills only *null* slots, and the default's `contentView`/`options` are already non-null; source: `chat_uikit/.../message_list/cometchat_message_list_controller.dart:571-613`). `addTemplate:` is for brand-NEW custom types only.
+
+To override a built-in, **seed the full default set, modify the matching template in place, and pass the whole list via `templates:`** (the prop that defines the list's template set — passing the complete set guarantees no other built-in bubble is dropped). `contentView`'s full signature is `(BaseMessage, BuildContext, BubbleAlignment, {AdditionalConfigurations? additionalConfigurations})`.
+
+```dart
+final templates = CometChatUIKit.getDataSource().getAllMessageTemplates();
+for (final t in templates) {
+  if (t.type == MessageTypeConstants.text &&
+      t.category == MessageCategoryConstants.message) {
+    t.contentView = (message, context, alignment, {additionalConfigurations}) {
+      return Container(
+        padding: const EdgeInsets.all(8),
+        child: Text(message is TextMessage ? message.text : ''),
+      );
+    };
+  }
+}
+
+CometChatMessageList(user: user, templates: templates) // full set → no built-in dropped
+```
+
+### Message option — add a long-press action (Forward-style)
+
+Two verified routes:
+
+**A. Per-list, via the template's `options` callback.** The template's `options` signature is `(User loggedInUser, BaseMessage messageObject, BuildContext context, Group? group, AdditionalConfigurations? additionalConfigurations)` and returns `List<CometChatMessageOption>?`. Because this overrides a **built-in** type's `options`, use the same seed-the-full-set + `templates:` pattern as the bubble override above (NOT `addTemplate:`, which would be dropped). Seed each option list from the default `getMessageOptions` to **append** rather than replace:
+
+```dart
+final templates = CometChatUIKit.getDataSource().getAllMessageTemplates();
+for (final t in templates) {
+  if (t.type == MessageTypeConstants.text &&
+      t.category == MessageCategoryConstants.message) {
+    t.options = (loggedInUser, message, context, group, additionalConfigurations) {
+      final defaults = CometChatUIKit.getDataSource().getMessageOptions(
+        loggedInUser, message, context, group, additionalConfigurations);
+      defaults.add(CometChatMessageOption(
+        id: 'forward',
+        title: 'Forward',
+        icon: const Icon(Icons.forward, size: 24),
+        onItemClick: (BaseMessage msg, CometChatMessageListControllerProtocol state) {
+          // forward msg
+        },
+      ));
+      return defaults; // appended — default options preserved
+    };
+  }
+}
+
+CometChatMessageList(user: user, templates: templates)
+```
+
+**B. App-wide, via a `DataSourceDecorator`.** Override `getMessageOptions` and call `super` first (same shape the kit's own extensions use):
+
+```dart
+class MyDataSource extends DataSourceDecorator {
+  MyDataSource(DataSource ds) : super(ds);
+
+  @override
+  List<CometChatMessageOption> getMessageOptions(
+    User loggedInUser, BaseMessage messageObject, BuildContext context,
+    Group? group, AdditionalConfigurations? additionalConfigurations,
+  ) {
+    final options = super.getMessageOptions(
+      loggedInUser, messageObject, context, group, additionalConfigurations);
+    options.add(CometChatMessageOption(
+      id: 'forward', title: 'Forward',
+      onItemClick: (msg, state) { /* forward */ },
+    ));
+    return options; // appended — defaults preserved
+  }
+}
+// register: ChatConfigurator.enable((ds) => MyDataSource(ds));
+```
+
+> `CometChatMessageOption.onItemClick` is `(BaseMessage message, CometChatMessageListControllerProtocol state)` — **not** the bare `Function()` used by `CometChatOption` (conversations/header). Don't mix the two models.
+
+Verified (v5): `CometChatMessageList.addTemplate` + `.templates` (chat_uikit/.../message_list/cometchat_message_list.dart:108,55), `CometChatMessageTemplate({required type, required category, bubbleView, headerView, contentView, footerView, bottomView, statusInfoView, threadView, replyView, options})` (shared_uikit/.../models/cometchat_message_template.dart:21; `contentView` 3-arg + `{AdditionalConfigurations?}`, `options` 5 positional), `DataSourceDecorator.getAttachmentOptions(BuildContext, Map?, AdditionalConfigurations?)` + `.getMessageOptions(User, BaseMessage, BuildContext, Group?, AdditionalConfigurations?)` (shared_uikit/.../framework/data_source_decorator.dart:47,122 — both delegate to wrapped `dataSource`, so `super.x()` is correct), `ChatConfigurator.enable(DataSource Function(DataSource))` + `CometChatUIKit.getDataSource()` (shared_uikit/.../framework/chat_configurator.dart:14, cometchat_ui_kit.dart:713), `CometChatMessageOption(id:, title:, icon:, onItemClick:(BaseMessage,CometChatMessageListControllerProtocol), messageOptionSheetStyle:)` (shared_uikit/.../models/cometchat_message_option.dart:21), `CometChatMessageComposerAction(id:, title:, icon:, style:, onItemClick:(BuildContext,User?,Group?))` (shared_uikit/.../models/cometchat_message_composer_action.dart:23), `CometChatUIKit.sendCustomMessage(CustomMessage)`, `CustomMessage(receiverUid:, receiverType:, type:, customData:)`.
+
 ## Options Menu Customization
 
 Add or replace long-press options on conversations, users, groups:
@@ -225,3 +352,7 @@ CometChatMessageHeader(
 - [ ] Text formatters consistent between MessageList and Composer
 - [ ] Extensions registered via `UIKitSettingsBuilder.extensions`
 - [ ] Custom templates specify `type` and `category`
+
+## Sound (in-app message + call sounds)
+
+The V5 UI Kit surfaces `CometChatSoundManager` for incoming/outgoing message + call sounds (mute / custom audio). **V5 is legacy/maintenance-only** — V6 is the current cohort. For call sounds see this family's `-calls` skill; verify the `CometChatSoundManager` API against the installed kit before relying on it.

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

@@ -3,13 +3,14 @@ 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: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"
   tags: "cometchat flutter v5 events listeners real-time typing receipts"
 ---
 
+> **Ground truth:** `cometchat_chat_uikit: ^5.2` (legacy/maintenance-only; calls via raw `cometchat_calls_sdk ^5.0.2`) — pub-cache source + `ui-kit/flutter/v5`. **Official docs:** https://www.cometchat.com/docs/ui-kit/flutter/v5/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.
+
 # CometChat Flutter UIKit v5 — Events
 
 Two layers: SDK listeners (low-level) and UIKit events (high-level component coordination).

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

@@ -3,13 +3,14 @@ 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: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"
   tags: "cometchat flutter v5 messages list composer header bubbles threads compact"
 ---
 
+> **Ground truth:** `cometchat_chat_uikit: ^5.2` (legacy/maintenance-only; calls via raw `cometchat_calls_sdk ^5.0.2`) — pub-cache source + `ui-kit/flutter/v5`. **Official docs:** https://www.cometchat.com/docs/ui-kit/flutter/v5/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.
+
 # CometChat Flutter UIKit v5 — Messages
 
 Components for displaying, sending, and managing messages.

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

@@ -3,13 +3,14 @@ name: cometchat-flutter-v5-production
 description: "Use when preparing a CometChat Flutter UIKit v5 app for production. Covers auth tokens, ProGuard, environment config, security hardening."
 license: "MIT"
 compatibility: "cometchat_chat_uikit ^5.2.14; cometchat_calls_uikit ^5.0.15"
-allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"
   tags: "cometchat flutter v5 production security auth tokens proguard environment"
 ---
 
+> **Ground truth:** `cometchat_chat_uikit: ^5.2` (legacy/maintenance-only; calls via raw `cometchat_calls_sdk ^5.0.2`) — pub-cache source + `ui-kit/flutter/v5`. **Official docs:** https://www.cometchat.com/docs/fundamentals/user-auth · **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.
+
 # CometChat Flutter UIKit v5 — Production
 
 Hardening a CometChat Flutter app for production deployment.
@@ -67,12 +68,14 @@ android.useAndroidX=true
 android.enableJetifier=true
 ```
 
-### minSdk 26
+### minSdk
 
 ```groovy
 // android/app/build.gradle
 defaultConfig {
-    minSdk 26  // Required by cometchat_calls_sdk
+    minSdk 24  // Matches vendor samples (sample_app + sample_app_push_notifications + calls_uikit android/build.gradle).
+               // Raw calls-sdk docs cite 26; the UI Kit wrapper relaxes to 24 for chat-only apps.
+               // Bump to 26 ONLY if your app uses calls AND fails at runtime with a min-SDK error from the calls plugin.
 }
 ```
 
@@ -180,8 +183,14 @@ CometChat.setDemoMetaInfo(jsonObject: {
 ## Logout Flow
 
 ```dart
-// 1. Unregister push tokens
-PNRegistry.unregisterPNService();
+// 1. Unregister push tokens — real SDK API:
+await CometChatNotifications.unregisterPushToken(
+  onSuccess: (_) {},
+  onError: (e) {},
+);
+// (PNRegistry.unregisterPNService() only works if you copied the v5 sample-app
+//  `extension PNRegistry on CometChatService` helper into your project — it is
+//  NOT importable from any cometchat_* package. See cometchat-flutter-v5-push.)
 
 // 2. Sign out from Firebase/Google (if applicable)
 await FirebaseAuth.instance.signOut();
@@ -199,7 +208,7 @@ await CometChatUIKit.logout(
 - [ ] Auth tokens minted server-side, not authKey in client
 - [ ] Credentials not hardcoded in source (use SharedPreferences or remote config)
 - [ ] ProGuard rules added for release builds
-- [ ] minSdk 26 set
+- [ ] minSdk 24 set (or 26 if your app uses calls AND hits min-SDK runtime errors)
 - [ ] iOS permissions in Info.plist
 - [ ] Firebase Crashlytics configured
 - [ ] Push notification provider IDs match CometChat dashboard

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

@@ -3,13 +3,14 @@ name: cometchat-flutter-v5-push
 description: "Use when implementing push notifications with CometChat Flutter UIKit v5. Covers FCM (Android), APNs (iOS), VoIP calls, token lifecycle, local notifications, and tap-to-navigate."
 license: "MIT"
 compatibility: "cometchat_chat_uikit ^5.2.14; cometchat_calls_uikit ^5.0.15; firebase_messaging; flutter_local_notifications; flutter_callkit_incoming"
-allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"
   tags: "cometchat flutter v5 push notifications fcm apns voip callkit firebase"
 ---
 
+> **Ground truth:** `cometchat_chat_uikit: ^5.2` (legacy/maintenance-only; calls via raw `cometchat_calls_sdk ^5.0.2`) — pub-cache source + `ui-kit/flutter/v5`. **Official docs:** https://www.cometchat.com/docs/notifications/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.
+
 # CometChat Flutter UIKit v5 — Push Notifications
 
 Push notification setup for Android (FCM) and iOS (APNs + VoIP).