@cometchat/skills 4.1.0 → 4.2.0

package/skills/cometchat-flutter-v6-calls/SKILL.md

@@ -1,47 +1,78 @@
 ---
 name: cometchat-flutter-v6-calls
-description: >
-  Use when implementing voice calls, video calls, or call UI with CometChat Flutter UIKit v6.
-  Covers CometChatCallButtons, CometChatIncomingCall, CometChatOutgoingCall,
-  CometChatOngoingCall, CometChatCallLogs, CometChatUIKitCalls, CallingConfiguration,
-  CallButtonsBloc, IncomingCallBloc, OutgoingCallBloc, OngoingCallBloc, CallLogsBloc,
-  CallEventService, CallOperationsServiceLocator, call_operations, call_settings,
-  SessionSettingsBuilder, CallAppSettings, initiateCall, acceptCall, rejectCall,
-  endSession, startSession, generateToken, CallNavigationContext,
-  CometChatDisplayIncomingCallOverlay, native_call_kit,
-  call permissions, audio call, video call, group call, call logs, call history,
-  incoming call screen, outgoing call screen, ongoing call screen, call bubble,
-  or "add calling to my app". Also use when seeing errors like
-  "CallManager not found", "startSession null", "call token null",
-  "session already started", or call-related crashes.
+description: CometChat Calls integration for Flutter UIKit v6 (Bloc-based, beta). ⚠️ Partially working at v6.0.0-beta2 (2026-05-13) — chat + calls init OK, outgoing call API succeeds, but TWO vendor bugs block end-to-end calling: (1) MaterialApp MUST set `navigatorKey: CallNavigationContext.navigatorKey` or the outgoing-call screen never renders ("Context is not mounted for navigation" — undocumented hard requirement); (2) even with the navigatorKey wired, the outgoing-call screen does NOT transition to the in-call view when peer accepts — call goes to `ongoing` at server level but UI stays on "Calling…" indefinitely, no client-side workaround. Customers shipping calls on Flutter today must stay on V5 cohort (cometchat_calls_uikit ^5.0.+). Covers UIKitSettings calling block, CometChatUIKitCalls.init() after CometChatUIKit.init() (CALLS_INIT_AFTER_CHAT_INIT), the kit's Bloc-driven CometChatCallButtons / CometChatIncomingCall / CometChatOutgoingCall / CometChatOngoingCall / CometChatCallLogs / CometChatCallBubble widgets, CallingConfiguration, native_call_kit module (iOS CallKit + Android ConnectionService), CallOperationsServiceLocator lifecycle, FCM + PushKit VoIP push, and additive-vs-standalone modes.
 license: "MIT"
-compatibility: "cometchat_chat_uikit ^6.0.0-beta2"
-allowed-tools: "executeBash, readFile, readCode, fileSearch, listDirectory, grepSearch"
+compatibility: "Flutter >= 2.5, Dart >= 3.0; cometchat_chat_uikit ^6.0.0-beta2 (calls bundled in); minSdk 26+ on Android; iOS 13+"
+allowed-tools: "shell, file-read, file-search, file-list, ask-user"
 metadata:
   author: "CometChat"
-  version: "3.0.0"
-  tags: "cometchat flutter calls voice video calling incoming outgoing ongoing call-logs"
+  version: "4.0.0"
+  tags: "cometchat flutter v6 beta calls voice video webrtc bloc incoming outgoing ongoing call-logs callkit pushkit connectionservice fcm voip-push native-call-kit call-operations service-locator"
 ---
 
-# CometChat Flutter UIKit — Calls
+## Purpose
 
-Voice and video calling for 1:1 and group conversations. Call functionality is built into `cometchat_chat_uikit` — no separate package needed.
+Production-grade voice + video calling for Flutter UIKit v6 (beta, Bloc-based). Loaded by `cometchat-calls` when `framework === "flutter"` and `flutter_version === "v6"`. Operates in two modes:
 
-## Import
+- **Standalone** — calls is the product. Chat SDK + Calls SDK without the v6 UI Kit (rare today, since the UI Kit ships calling bundled). Custom call screens on the SDKs.
+- **Additive** — calls layered onto an existing v6 chat integration. The v6 UI Kit ships call widgets in the same package (`cometchat_chat_uikit`) — no extra dependency. The skill enables calling on `UIKitSettings`, calls `CometChatUIKitCalls.init()` in the chat-init success callback, mounts the global incoming-call overlay at app root.
+
+**Read these other skills first:**
+- `cometchat-calls` — dispatcher (modes, hard rules, anti-patterns)
+- `cometchat-flutter-v6-core` — UIKitSettings, init/login order (CHAT_INIT_BEFORE_CALLS_INIT is THE rule)
+- `cometchat-flutter-v6-events` — Bloc event streams + listener registration
+
+**V6 vs V5 difference (critical for migration):**
+- V6 — single `cometchat_chat_uikit` package (calls bundled in)
+- V5 — `cometchat_chat_uikit` + `cometchat_calls_uikit` (separate)
+- V6 uses Bloc; V5 uses GetX
+- V6 `CometChatUIKitCalls.init(appId, region)` must run AFTER `CometChatUIKit.init()` succeeds; V5 hides this via `CometChatCallingExtension`
+
+**Ground truth:**
+- SDK source — installed `cometchat_chat_uikit@6.0.0-beta2` artifacts under `~/.pub-cache/`
+- Sample app — `~/Downloads/calls-sdk/calls-sdk-flutter-5/sample-apps/` (V5 sample; V6 sample app may not exist yet — verify before citing)
+- Public docs — https://www.cometchat.com/docs/calls/flutter/overview (note: V6 docs may still reference V5 module split)
+
+---
+
+## 1. The seven hard rules — Flutter v6 specialization
+
+### 1.0 Calls SDK login is its own step (v5+)
+
+Same as v5 cohort — the v5 Calls SDK has its own auth state, separate from the Chat SDK. After `CometChat.login` succeeds, you MUST also call `CometChatCalls.login` — without it, the FIRST calls API call throws **"auth token cannot be null"**.
+
+V6's `CometChatUIKitCalls.init()` initializes the SDK but does not handle login. Login still needs to happen explicitly after the user signs in via `CometChatUIKit.login`:
 
 ```dart
-import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
-import 'package:cometchat_chat_uikit/cometchat_calls_uikit.dart';
+import 'package:cometchat_sdk/cometchat_sdk.dart';
+import 'package:cometchat_calls_sdk/cometchat_calls_sdk.dart';
+
+// After CometChatUIKit.login resolves
+CometChatCalls.login(
+  uid: uid,
+  authKey: AUTH_KEY,
+  onSuccess: (User? callUser) { /* both ready */ },
+  onError: (CometChatException e) { /* surface to user */ },
+);
+
+// Production:
+CometChatCalls.loginWithAuthToken(
+  authToken: tokenFromBackend,
+  onSuccess: (User? user) { /* … */ },
+  onError: (CometChatException e) { /* … */ },
+);
 ```
 
-The first import gives you chat components. The second gives you call-specific types.
+**Surprises:**
+- Chat SDK persists login via shared preferences. The **Calls SDK does NOT** — always check `CometChatCalls.getLoggedInUser()` on app start and re-login if it returns null.
+- Even though V6 bundles the call UI into `CometChatUIKit`, the underlying Calls SDK login is still mandatory and separate.
 
-## Rule: CALLS_INIT_AFTER_CHAT_INIT
+### 1.1 Dual-SDK contract — `CometChatUIKitCalls.init` after `CometChatUIKit.init`
 
-`CometChatUIKitCalls.init()` MUST be called after `CometChatUIKit.init()` completes. The calls SDK needs the chat SDK's auth context.
+The V6 UI Kit unifies the two SDKs but `init` order is still load-bearing:
 
 ```dart
-// ✅ CORRECT — calls init after chat init
+// ✓ RIGHT — calls init in chat init's onSuccess
 CometChatUIKit.init(
   uiKitSettings: settings,
   onSuccess: (_) {
@@ -51,141 +82,201 @@ CometChatUIKit.init(
     );
   },
 );
+```
 
-// ❌ WRONG — parallel init causes auth token null
-CometChatUIKit.init(uiKitSettings: settings);
-CometChatUIKitCalls.init(appId, region); // Race condition
+```dart
+// ✗ WRONG — parallel init causes "auth token null" intermittently
+CometChatUIKit.init(uiKitSettings: settings);   // returns immediately
+CometChatUIKitCalls.init(appId, region);         // race — chat auth not ready yet
 ```
 
-## Rule: SINGLE_CALLS_INIT
+`CometChatUIKitCalls.init()` must be called **exactly once per app lifecycle**. Re-calling it after logout + re-login causes "session already started" errors.
 
-`CometChatUIKitCalls.init()` must be called exactly once per app lifecycle. Calling it again after logout + re-login can cause "session already started" errors.
+After logout: the calls SDK session is invalidated; on next login, call `CometChatUIKitCalls.init()` again. Treat this as a "first run" of the calls subsystem.
 
-## Rule: CALLS_REINIT_AFTER_LOGOUT
+### 1.2 VoIP push — `native_call_kit` module + FCM + PushKit bridge
 
-After `CometChatUIKit.logout()`, the calls SDK session is invalidated. On the next login, `CometChatUIKitCalls.init()` must be called again.
+V6 ships a `native_call_kit` sub-module inside `cometchat_chat_uikit` that wraps CallKit (iOS) and ConnectionService (Android). The skill still wires:
 
-## Architecture
+- **`firebase_messaging`** — FCM data messages on Android
+- **iOS PushKit** — same platform-channel bridge as v5 (Flutter has no first-party PushKit plugin)
+- **`native_call_kit` API** — Dart-side handlers for incoming-call payloads → OS-level ring UI
 
-```
-call_ui/src/
-├── call_buttons/          # Voice/video call buttons (CallButtonsBloc)
-├── incoming_call/         # Incoming call screen (IncomingCallBloc)
-├── outgoing_call/         # Outgoing call screen (OutgoingCallBloc)
-├── ongoing_call/          # Active call screen — WebRTC (OngoingCallBloc)
-├── call_logs/             # Call history list (CallLogsBloc + Clean Arch)
-├── call_operations/       # Shared clean architecture (DI, use cases, repos)
-├── call_bubble/           # Call message bubble in chat
-├── call_settings/         # CometChatUIKitCalls, CallNavigationContext
-├── native_call_kit/       # iOS CallKit / Android ConnectionService
-├── utils/                 # CallUtils, CallStateService, CallPermissions
-├── call_event_service.dart  # Centralized call event handling
-└── calling_configuration.dart  # Top-level config object
+In additive mode, opt-in. In standalone, mandatory.
+
+### 1.3 Foreground service — same Android 14+ rules
+
+**⚠️ Android build prerequisite — Jetifier is mandatory.** One of the `cometchat_calls_uikit` transitive deps still pulls in the legacy `com.android.support:support-compat:26.1.0` AAR in V6. Without Jetifier, AGP fails with `Duplicate class android.support.v4.*` errors. Set in `android/gradle.properties`:
+
+```properties
+android.useAndroidX=true
+android.enableJetifier=true
 ```
 
-## Components
+Flutter 3.x scaffolds omit `enableJetifier=true` by default — the build fails on first `flutter build apk` if you skip this.
 
-### CometChatCallButtons
+Same as native Android / Flutter v5. The four FOREGROUND_SERVICE_* permissions plus MANAGE_OWN_CALLS / BIND_TELECOM_CONNECTION_SERVICE in `android/app/src/main/AndroidManifest.xml`. V6 raised Android `minSdk` to 26 (calls SDK in V6 raised the floor) — verify this is set in `android/app/build.gradle`.
 
-Voice and video call buttons. Typically placed in `CometChatMessageHeader`'s trailing view or standalone.
+### 1.4 Server-minted auth tokens
+
+`cometchat-flutter-v6-production` covers it. `CometChatUIKit.loginWithAuthToken(token)` for production, never `loginWithAuthKey(uid, authKey)`.
+
+### 1.5 Hangup cleanup — Calls + ServiceLocator + native call UI
 
 ```dart
-CometChatCallButtons(
-  user: user,           // For 1:1 calls
-  group: group,         // For group calls (meetings)
-  hideVoiceCallButton: false,
-  hideVideoCallButton: false,
-  voiceCallIcon: Icon(Icons.call),
-  videoCallIcon: Icon(Icons.videocam),
-  callButtonsStyle: CometChatCallButtonsStyle(
-    voiceCallIconColor: colorPalette.iconPrimary,
-    videoCallIconColor: colorPalette.iconPrimary,
-  ),
-  outgoingCallConfiguration: CometChatOutgoingCallConfiguration(
-    outgoingCallStyle: CometChatOutgoingCallStyle(...),
-  ),
-)
+Future<void> endCall(String sessionId) async {
+  await CometChatUIKitCalls.endSession();        // 1. end WebRTC + release tracks
+  await FlutterCallkitIncoming.endAllCalls();    // 2. clear OS-level ring UI
+  if (mounted) Navigator.of(context, rootNavigator: true).pop();  // 3. pop call screen
+}
 ```
 
-Call buttons are built into `CometChatMessageHeader` by default:
+After `CometChatUIKit.logout()`, also reset the calls service locator:
 ```dart
-CometChatMessageHeader(
-  user: user,
-  group: group,
-  hideVoiceCallButton: false,
-  hideVideoCallButton: false,
-)
+CallOperationsServiceLocator.instance.reset();
 ```
 
-### CometChatIncomingCall
+The kit's call widgets handle the basic teardown automatically; custom WebRTC surfaces must replicate this.
 
-Displays when the logged-in user receives a call. Supports accept/decline with custom views.
+### 1.6 Permissions — `permission_handler` + `CallPermissions`
+
+V6 ships an internal `CallPermissions` helper that wraps the standard permission flow:
 
 ```dart
-CometChatIncomingCall(
-  call: call,                    // Required — the active Call object
-  user: callerUser,              // Caller info for display
-  onAccept: (ctx, call) { },
-  onDecline: (ctx, call) { },
-  disableSoundForCalls: false,
-  customSoundForCalls: 'assets/ringtone.mp3',
-  incomingCallStyle: CometChatIncomingCallStyle(
-    backgroundColor: colorPalette.background3,
-    acceptButtonColor: colorPalette.success,
-    declineButtonColor: colorPalette.error,
-  ),
-  // Custom view slots
-  titleView: (ctx, call) => Text('Custom Title'),
-  subTitleView: (ctx, call) => Text('Custom Subtitle'),
-  leadingView: (ctx, call) => Icon(Icons.call),
-  trailingView: (ctx, call) => CometChatAvatar(image: user.avatar),
-)
+final granted = await CallPermissions.requestCallPermissions(callType: CallType.video);
+if (!granted) { /* surface a clear UI message */ }
 ```
 
-### CometChatOutgoingCall
+Native config (Info.plist + AndroidManifest) is identical to V5 (rule 1.6 in `cometchat-flutter-v5-calls`).
+
+### 1.7 IncomingCall mounted at app root
 
-Displays when the logged-in user initiates a call.
+V6 exposes the incoming-call overlay via `CometChatDisplayIncomingCallOverlay` mounted in `MaterialApp`'s `builder`:
 
 ```dart
-CometChatOutgoingCall(
-  call: call,
-  user: receiverUser,
-  outgoingCallStyle: CometChatOutgoingCallStyle(
-    backgroundColor: colorPalette.background1,
-  ),
-)
+MaterialApp(
+  navigatorKey: CallNavigationContext.navigatorKey,  // ⚠️ REQUIRED — see warning below
+  builder: (context, child) {
+    return Stack(
+      children: [
+        child!,
+        const CometChatDisplayIncomingCallOverlay(),
+      ],
+    );
+  },
+);
 ```
 
-### CometChatOngoingCall
+**⚠️ `navigatorKey: CallNavigationContext.navigatorKey` is REQUIRED on MaterialApp at v6.0.0-beta2.** The kit's `CometChatCallButtons` and outgoing-call flow navigate via `CallNavigationContext.navigatorKey.currentContext`. Without this line, `CometChat.initiateCall` succeeds but the outgoing-call screen never renders — kit logs `"Context is not mounted for navigation"` and silently drops the navigation. Symptom: user taps call button, peer rings, but the Flutter app shows nothing.
 
-The active call screen with WebRTC video/audio. Rendered after a call is accepted.
+Import: `import 'package:cometchat_chat_uikit/cometchat_calls_uikit.dart' show CallNavigationContext;` (use `show` to avoid a name collision with kit-exported `IncomingCallOverlay`).
 
-```dart
-CometChatOngoingCall(
-  callSettingsBuilder: sessionSettingsBuilder,
-  sessionId: call.sessionId,
-  callWorkFlow: CallWorkFlow.directCalling,
-)
+**⚠️ Outgoing → in-call screen transition is broken at v6.0.0-beta2.** When the peer accepts, the call's status moves to `ongoing` at the server level — but the kit's outgoing-call screen does NOT transition to the in-call view. Users see the "Calling…" ring spinner indefinitely while the call is actually live. Pressing the reject button fires `CometChat.rejectCall` which the server rejects with `"The call status cannot be updated from ongoing to cancelled"`. **No client-side workaround known** — vendor needs to fix the outgoing-call BLoC's `onOutgoingCallAccepted` handler to push the in-call route. Validated on 2026-05-13 against a Next.js web peer.
+
+In standalone mode, `native_call_kit` owns the OS-level ring UI; the in-app overlay only fires when the app is foregrounded.
+
+---
+
+## 2. Setup
+
+```yaml
+# pubspec.yaml
+dependencies:
+  flutter:
+    sdk: flutter
+  cometchat_chat_uikit: ^6.0.0-beta2     # calls bundled in
+  permission_handler: ^11.0.0
+  flutter_callkit_incoming: ^2.0.0       # standalone — VoIP UI bridge
+  firebase_messaging: ^14.0.0            # standalone — Android FCM
+  firebase_core: ^2.0.0
 ```
 
-### CometChatCallLogs
+If pub.dev resolution lags, use the Cloudsmith hosted pin:
+```yaml
+  cometchat_chat_uikit:
+    hosted: https://dart.cloudsmith.io/cometchat/cometchat/
+    version: ^6.0.0-beta2
+```
 
-Scrollable list of call history. Clean Architecture + BLoC with `CallLogsServiceLocator`.
+Init (additive mode):
 
 ```dart
-CometChatCallLogs(
-  onItemClick: (callLog) { /* Navigate or initiate call */ },
-  callLogsStyle: CallLogsStyle(backgroundColor: colorPalette.background1),
-)
+import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
+import 'package:cometchat_chat_uikit/cometchat_calls_uikit.dart';
+
+void main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+
+  final settings = (UIKitSettings.builder()
+    ..appId = CometChatConfig.appId
+    ..region = CometChatConfig.region
+    ..authKey = CometChatConfig.authKey
+    ..subscriptionType = CometChatSubscriptionType.allUsers)
+    .build();
+
+  CometChatUIKit.init(
+    uiKitSettings: settings,
+    onSuccess: (_) {
+      CometChatUIKitCalls.init(
+        CometChatConfig.appId,
+        CometChatConfig.region,
+        onSuccess: (_) => runApp(const MyApp()),
+        onError: (e) => runApp(MyErrorApp(e.message)),
+      );
+    },
+    onError: (e) => runApp(MyErrorApp(e.message)),
+  );
+}
+```
+
+The first import gives you chat components. The second gives you call-specific types.
+
+---
+
+## 3. Components catalog (V6 widgets — Bloc-driven)
+
+Architecture (lives inside `cometchat_chat_uikit`):
+
+```
+call_ui/src/
+├── call_buttons/          # CometChatCallButtons + CallButtonsBloc
+├── incoming_call/         # CometChatIncomingCall + IncomingCallBloc
+├── outgoing_call/         # CometChatOutgoingCall + OutgoingCallBloc
+├── ongoing_call/          # CometChatOngoingCall + OngoingCallBloc
+├── call_logs/             # CometChatCallLogs + CallLogsBloc + Clean Architecture
+├── call_operations/       # Shared DI / use cases / repositories (CallOperationsServiceLocator)
+├── call_bubble/           # CometChatCallBubble — call-event bubble in message list (auto-rendered)
+├── call_settings/         # CometChatUIKitCalls, CallNavigationContext
+├── native_call_kit/       # iOS CallKit / Android ConnectionService bridge
+├── utils/                 # CallUtils, CallStateService, CallPermissions
+├── call_event_service.dart  # Centralized call event handling
+└── calling_configuration.dart  # Top-level config object
 ```
 
-### CometChatCallBubble
+### Component reference
 
-Message bubble for call events in the message list. Automatically rendered for call-type messages.
+| Widget | Purpose | Notes |
+|---|---|---|
+| `CometChatCallButtons(user:, group:)` | Voice + video buttons | Mutually exclusive `user` / `group`. Use `group:` for group calls (meetings). |
+| `CometChatIncomingCall(call:, user:, onAccept:, onDecline:)` | In-app foreground ring UI | `onAccept`/`onDecline` are `(BuildContext, Call) -> void`. Custom view slots: `titleView`, `subTitleView`, `leadingView`, `trailingView`. |
+| `CometChatOutgoingCall(call:, user:, outgoingCallStyle:)` | Dialing UI | Auto-mounted when `initiateCall` is called via the kit. |
+| `CometChatOngoingCall(callSettingsBuilder:, sessionId:, callWorkFlow:)` | Active call view | `callWorkFlow: CallWorkFlow.directCalling` or `CallWorkFlow.defaultCalling`. Set `resizeToAvoidBottomInset: false` on host Scaffold. |
+| `CometChatCallLogs(onItemClick:, callLogsStyle:)` | Paginated history | Clean Architecture + BLoC; `CallLogsServiceLocator` is initialized automatically when the widget mounts. |
+| `CometChatCallBubble` | Call-event message bubble | Auto-rendered for call-type messages in `CometChatMessageList`. |
 
-## CallingConfiguration
+### `CometChatUIKitCalls` API
 
-Top-level configuration object bundling all call component configs:
+| Method | Purpose |
+|---|---|
+| `CometChatUIKitCalls.init(appId, region)` | Initialize calls SDK (after chat init — rule 1.1) |
+| `CometChatUIKitCalls.initiateCall(call)` | Start a call (Chat SDK initiate + Calls SDK preflight) |
+| `CometChatUIKitCalls.acceptCall(sessionId)` | Accept incoming |
+| `CometChatUIKitCalls.rejectCall(sessionId, status)` | Reject / cancel |
+| `CometChatUIKitCalls.generateToken(sessionId)` | Mint session-scoped RTC token |
+| `CometChatUIKitCalls.startSession(sessionId, settings)` | Start WebRTC |
+| `CometChatUIKitCalls.endSession()` | End and cleanup |
+
+### `CallingConfiguration` — top-level config
 
 ```dart
 CallingConfiguration(
@@ -196,138 +287,112 @@ CallingConfiguration(
 )
 ```
 
-## CometChatUIKitCalls API
+Pass to `UIKitSettings.callingConfiguration` to apply globally without per-component plumbing.
 
-| Method | Purpose |
-|--------|---------|
-| `CometChatUIKitCalls.init(appId, region)` | Initialize calls SDK |
-| `CometChatUIKitCalls.initiateCall(call)` | Start a call |
-| `CometChatUIKitCalls.acceptCall(sessionId)` | Accept incoming call |
-| `CometChatUIKitCalls.rejectCall(sessionId, status)` | Reject/cancel call |
-| `CometChatUIKitCalls.generateToken(sessionId)` | Generate call token |
-| `CometChatUIKitCalls.startSession(sessionId, settings)` | Start WebRTC session |
-| `CometChatUIKitCalls.endSession()` | End active call session |
+### Bloc events (when interacting directly — UIKit widgets handle these for you)
 
-## Call Flow — 1:1 Direct Call
+| Bloc | Events |
+|---|---|
+| `CallButtonsBloc` | `InitiateVoiceCall`, `InitiateVideoCall` |
+| `IncomingCallBloc` | `AcceptCall`, `RejectCall` |
+| `OutgoingCallBloc` | `CancelCall`, `CallAccepted(call)`, `CallRejected(call)` |
+| `OngoingCallBloc` | `StartSession(sessionId, settings)`, `EndSession` |
+| `CallLogsBloc` | `LoadCallLogs`, `LoadMoreCallLogs` |
 
-```
-Caller                              Receiver
-  |-- CometChatCallButtons tap ------->|
-  |-- initiateCall(Call) ------------->|
-  |-- CometChatOutgoingCall shown ---->|
-  |                                    |-- CometChatIncomingCall shown
-  |                                    |-- acceptCall(sessionId)
-  |<-- onOutgoingCallAccepted ---------|
-  |-- generateToken(sessionId) ------->|
-  |-- startSession(token, settings) -->|
-  |-- CometChatOngoingCall shown ----->|-- CometChatOngoingCall shown
-  |-- endSession() ------------------>|-- endSession()
-```
+`CallOperationsServiceLocator` must be initialized before using call BLoCs directly — UIKit widgets handle this automatically. After logout, call `CallOperationsServiceLocator.instance.reset()` to clean up.
 
-## Golden Path — Messages Screen with Calls
+---
 
-```dart
-Scaffold(
-  resizeToAvoidBottomInset: false,
-  appBar: CometChatMessageHeader(
-    user: user,
-    group: group,
-    onBack: () => Navigator.pop(context),
-    hideVoiceCallButton: false,
-    hideVideoCallButton: false,
-  ),
-  body: Column(
-    children: [
-      Expanded(child: CometChatMessageList(user: user, group: group)),
-      CometChatMessageComposer(user: user, group: group),
-    ],
-  ),
-)
-```
+## 4. Standalone integration
 
-## BLoC Events
-
-### CallButtonsBloc
-| Event | Purpose |
-|-------|---------|
-| `InitiateVoiceCall` | Start audio call |
-| `InitiateVideoCall` | Start video call |
-
-### IncomingCallBloc
-| Event | Purpose |
-|-------|---------|
-| `AcceptCall` | Accept the incoming call |
-| `RejectCall` | Decline the incoming call |
-
-### OutgoingCallBloc
-| Event | Purpose |
-|-------|---------|
-| `CancelCall` | Cancel the outgoing call |
-| `CallAccepted(call)` | Receiver accepted |
-| `CallRejected(call)` | Receiver rejected |
-
-### OngoingCallBloc
-| Event | Purpose |
-|-------|---------|
-| `StartSession(sessionId, settings)` | Begin WebRTC session |
-| `EndSession` | End the call |
-
-### CallLogsBloc
-| Event | Purpose |
-|-------|---------|
-| `LoadCallLogs` | Initial load |
-| `LoadMoreCallLogs` | Pagination |
-
-## Gotchas
-
-- `CometChatUIKitCalls.init()` must happen AFTER `CometChatUIKit.init()` — parallel init causes "auth token null".
-- After logout, the calls SDK session is invalidated. Re-init required on next login.
-- `startSession` on Android can return `null` with a 5-second timeout and no error feedback. Known platform issue.
-- `SessionType.audio` is ignored on Android in some SDK versions — always opens with video. Known external SDK bug.
-- Group calls use `CometChat.Group` not `CometChat.User` on `CometChatCallButtons`.
-- Incoming call handling must be global (mounted at app root level) so calls ring on every screen.
-- `CallOperationsServiceLocator` must be initialized before using call BLoCs directly. UIKit widgets handle this automatically.
-- After logout, call `CallOperationsServiceLocator.instance.reset()` to clean up.
-- On iOS, CallKit integration via `native_call_kit` shows the native call UI. Ensure `Info.plist` has the `voip` background mode.
-- On Android, the ongoing call foreground service shows a notification during active calls. Launched automatically by `startSession`.
-
-## Anti-Patterns
+When `product === "voice-video"` and there is no v6 chat integration.
 
-```dart
-// ❌ WRONG — init calls SDK before chat SDK
-CometChatUIKitCalls.init(appId, region);
-CometChatUIKit.init(uiKitSettings: settings);
+**Split by calling mode:**
 
-// ✅ CORRECT — calls init in chat init's onSuccess
-CometChatUIKit.init(
-  uiKitSettings: settings,
-  onSuccess: (_) {
-    CometChatUIKitCalls.init(appId, region);
-  },
-);
-```
+### 4a. Standalone — Session mode (meeting-room UX, no ringing)
 
-```dart
-// ❌ WRONG — not handling incoming calls globally
-CometChatIncomingCall(call: call, user: user) // Only on messages screen
+Calls SDK ONLY. NO Chat SDK, NO UIKit. Same SDK as v5 (`cometchat_calls_sdk`). Scaffold:
 
-// ✅ CORRECT — mount incoming call overlay at app root
-MaterialApp(
-  builder: (context, child) {
-    return Stack(children: [child!, /* Global incoming call listener */]);
-  },
-)
-```
+1. **`pubspec.yaml`** — `cometchat_calls_sdk: ^5.0.0` + `flutter_bloc` + `equatable` + `permission_handler` ONLY.
+2. **`lib/main.dart`** — `CometChatCalls.init(appId, region, authKey)`. Permission requests. NO Chat SDK init.
+3. **`lib/cubits/call_session_cubit.dart`** — Cubit implements `SessionStatusListeners`. `CometChatCalls.joinSession(sessionId:, sessionSettings: SessionSettingsBuilder().build(), onSuccess:, onError:)`. Renders the returned `Widget?` via `SizedBox.expand`. See `references/call-session.md`.
+4. **`lib/screens/call_room.dart`** — `BlocConsumer` for auto-pop on idle transition.
+5. **Native config** — Camera + microphone permissions only.
+
+**Why no Chat SDK / no UIKit:** session mode never touches a Chat SDK call entity. No ringing, no UIKit incoming-call overlay needed.
+
+### 4b. Standalone — Ringing mode (kit overlay + CallKit + FCM)
+
+Dual-SDK + UIKit. Scaffold:
+
+1. **`lib/main.dart`** — Chat SDK + Calls SDK init (no UIKit), permission requests, `flutter_callkit_incoming` + Firebase setup.
+2. **`lib/services/voip_service.dart`** — FCM + PushKit + `native_call_kit` bridge.
+3. **`lib/widgets/call_button.dart`** — Voice + video buttons next to a contact.
+4. **`lib/screens/ongoing_call_screen.dart`** — `CometChatCalls.joinSession(sessionId:, sessionSettings:, onSuccess:, onError:)` with Widget rendered via `SizedBox.expand`. Cubit-driven state.
+5. **`lib/screens/call_logs_screen.dart`** — `/calls` route.
+6. **`MaterialApp.builder`** — `CometChatDisplayIncomingCallOverlay` for foreground rings (rule 1.7).
+7. **Native config** — same as V5 standalone (Info.plist + AndroidManifest + Firebase config files).
 
-## Checklist
+## 5. Additive integration
 
-- [ ] `CometChatUIKitCalls.init()` called after `CometChatUIKit.init()` completes
-- [ ] Incoming call handling is global (app root level), not per-screen
-- [ ] Camera + microphone permissions handled (automatic via `CallPermissions`)
-- [ ] `resizeToAvoidBottomInset: false` on any Scaffold with call UI
-- [ ] Call buttons visible in `CometChatMessageHeader` (default) or standalone
-- [ ] After logout, calls SDK re-initialized on next login
-- [ ] Android: `minSdk = 26`, ProGuard rules for `com.cometchat.**`
-- [ ] iOS: `voip` background mode in `Info.plist` for CallKit
+When chat is already integrated. The skill:
+
+1. Confirms `cometchat_chat_uikit` is on `^6.0.0-beta2` — calls are already bundled.
+2. Patches the `CometChatUIKit.init` call to add `CometChatUIKitCalls.init` in the success callback (rule 1.1).
+3. Adds `CometChatDisplayIncomingCallOverlay` to `MaterialApp.builder` (rule 1.7).
+4. Confirms `CometChatMessageHeader` shows call buttons by default (`hideVoiceCallButton: false`, `hideVideoCallButton: false`).
+5. Optionally adds `CometChatCallLogs` as a tab/screen.
+6. VoIP push: opt-in.
+
+## 6. Anti-patterns
+
+1. **Init Calls SDK before Chat SDK.** Auth-token race; `CometChatUIKitCalls.init` must run inside `CometChatUIKit.init`'s `onSuccess`. Rule 1.1.
+2. **Calling `CometChatUIKitCalls.init` more than once per app lifecycle.** Causes "session already started". After logout-relogin, this is the first run again — but in a single session, do it exactly once.
+3. **Per-screen incoming-call handling.** `CometChatIncomingCall(call: c, user: u)` mounted on the messages screen only fires there. Mount the overlay at app root via `MaterialApp.builder` (rule 1.7).
+4. **Forgetting `resizeToAvoidBottomInset: false`** on Scaffolds with call UI — keyboard show breaks WebRTC layout.
+5. **Group calls with `user:` instead of `group:`** on `CometChatCallButtons`. Group calls require `group:`; the widget silently mismatches if both are passed.
+6. **Caching the theme in `build()`** instead of `didChangeDependencies()`. Listed in V6 components catalog as a perf rule but applies to every call surface.
+7. **Skipping `CallOperationsServiceLocator.instance.reset()` after logout.** Stale singletons leak across user sessions; calls subsystem behaves erratically on next login.
+8. **Mixing V5 and V6 widget imports.** V5's `cometchat_calls_uikit` namespace and V6's `cometchat_chat_uikit/cometchat_calls_uikit.dart` barrel re-export different classes with the same name. Pick a cohort and stay there.
+
+## 7. Verification checklist
+
+**Static:**
+
+- [ ] `cometchat_chat_uikit ^6.0.0-beta2` in pubspec.yaml (V6 bundles calls — no separate calls package)
+- [ ] `CometChatUIKitCalls.init` called inside `CometChatUIKit.init`'s `onSuccess` (rule 1.1)
+- [ ] `CometChatUIKitCalls.init` called exactly once per app lifecycle
+- [ ] `CometChatDisplayIncomingCallOverlay` mounted in `MaterialApp.builder` (rule 1.7)
+- [ ] iOS `Info.plist`: NSCameraUsageDescription + NSMicrophoneUsageDescription + UIBackgroundModes (audio + voip + remote-notification)
+- [ ] Android `minSdk = 26`, ProGuard rules `-keep class com.cometchat.** { *; }`
+- [ ] Android manifest: four FOREGROUND_SERVICE_* permissions + MANAGE_OWN_CALLS + BIND_TELECOM_CONNECTION_SERVICE
+- [ ] Hangup path: `endSession` + `FlutterCallkitIncoming.endAllCalls` + Navigator pop
+- [ ] After logout: `CallOperationsServiceLocator.instance.reset()`
+- [ ] `resizeToAvoidBottomInset: false` on call-screen Scaffolds
 - [ ] Theme cached in `didChangeDependencies()`, not `build()`
-- [ ] SDK listeners cleaned up in `dispose()`
+- [ ] **Standalone only:** `flutter_callkit_incoming` + `firebase_messaging` + iOS PushKit platform-channel bridge
+
+**Runtime (real devices, both platforms):**
+
+- [ ] iOS — terminated app, lock-screen rings on incoming call (CallKit)
+- [ ] Android — terminated app, heads-up notification rings (ConnectionService)
+- [ ] Both — outgoing call connects, two-way audio + video
+- [ ] Both — hangup releases camera + mic, no system call UI stuck
+- [ ] Logout + relogin: calls subsystem reinitializes cleanly (no "session already started")
+- [ ] Android 14+: ongoing-call notification visible, swipe-up doesn't kill the call
+- [ ] Keyboard during call doesn't break layout
+
+## 8. Pointers
+
+- `cometchat-calls` — dispatcher
+- `cometchat-flutter-v6-core` — UIKitSettings, init/login order, init guard rules
+- `cometchat-flutter-v6-events` — Bloc event streams
+- `cometchat-flutter-v6-features` — feature catalog (calls is a base capability — features layer on top)
+- `cometchat-flutter-v6-production` — server-minted tokens, ProGuard, environment config
+- `cometchat-flutter-v6-troubleshooting` — pubspec resolution, Bloc errors, theme cache, build errors
+- `cometchat-flutter-v6-migration` — V5 → V6 migration recipes (GetX → Bloc, calls package → bundled, theme API rewrite)
+
+## Known external SDK gotchas (worth surfacing in any agent message)
+
+- `startSession` on Android can return `null` with a 5-second timeout and no error feedback — known platform issue; retry once before surfacing failure.
+- `SessionType.audio` is ignored on Android in some V6 SDK builds — always opens with video. External SDK bug; track upstream.