@cometchat/skills 4.4.1 → 5.0.0

package/skills/cometchat-android-v6-production/SKILL.md

@@ -1,190 +1,51 @@
 ---
 name: cometchat-android-v6-production
-description: "CometChat Android UIKit v6 production readiness — token auth, ProGuard/R8, security checklist, release configuration"
+description: "Ship a CometChat Android v6 app safely — server-minted auth tokens instead of the dev Auth Key, keeping credentials out of the APK, release-build and R8/ProGuard checks, user provisioning server-side, rate limits, and the Play Store publishing prerequisites. Triggers: 'is my cometchat android app production ready', 'auth token instead of auth key android', 'release build cometchat android', 'proguard cometchat', 'publish chat app play store'."
 license: "MIT"
-compatibility: "Android 9.0+ (API 28); Kotlin 1.9+; com.cometchat:chatuikit-compose-android:6.x / com.cometchat:chatuikit-kotlin-android:6.x"
+compatibility: "Android minSdk >=28; compileSdk >=36; Kotlin >=2.1; AGP >=8.9.1; JVM target 11; com.cometchat:chatuikit-kotlin-android ^6 OR com.cometchat:chatuikit-compose-android ^6 (6.0.x, verified 6.0.5); com.cometchat:chat-sdk-android ^5"
 metadata:
   author: "CometChat"
-  version: "3.0.0"
-  tags: "cometchat, android, production, security, proguard, release, auth-token"
+  version: "1.0.0"
+  tags: "cometchat android production release auth-token security v6 proguard"
 ---
 
-> **Ground truth:** `com.cometchat:chatuikit-{compose,kotlin}-android:6.x` (+ `calls-sdk-android:5.x`) — resolved AAR (javap) + `ui-kit/android/v6`. **Official docs:** https://www.cometchat.com/docs/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.
+> **Ground truth:** the installed kit source (`CometChatUIKit.loginWithAuthToken`) + `contracts.android-v6.json` (`prod-auth-token-guidance`) + the live SDK pages `/sdk/android/v5/rate-limits` and `/sdk/android/v5/publishing-app-on-playstore`. Fetch specifics from docs; never assert a limit or a ProGuard rule from memory.
 
-> **Companion skills:** cometchat-android-v6-core (init/login), cometchat-android-v6-builder-settings (UIKitSettings), cometchat-android-v6-push (FCM)
-
-## Purpose
-
-Prepare a CometChat v6 Android app for production release — switch to token-based auth, configure ProGuard/R8, apply security best practices, and optimize the release build.
+## Companion skills (read first)
+- `cometchat-android-v6-core` — install, credentials, `initFromSettings → login`, lifecycle. Assumed here, never repeated.
+- `cometchat-android-v6-builder-settings` — the settings file + auth method reference · `cometchat-android-v6-testing` — pre-release verification · `cometchat-android-v6-push` (unregister on logout).
 
 ## Use this skill when
-
-- Preparing an app for production/release
-- Switching from authKey to token-based authentication
-- Configuring ProGuard/R8 rules for CometChat
-- Reviewing security best practices
-
-## Do not use this skill when
-
-- Setting up for development (use `cometchat-android-v6-core`)
-- Debugging issues (use `cometchat-android-v6-troubleshooting`)
-
-## 1. Token-Based Authentication
-
-### 1.1 Never Ship authKey
-
-```kotlin
-// ❌ NEVER in production
-val settings = UIKitSettings.UIKitSettingsBuilder()
-    .setAppId("APP_ID")
-    .setRegion("us")
-    .setAuthKey("AUTH_KEY") // REMOVE THIS
-    .build()
-
-CometChatUIKit.login("uid", callback) // Uses authKey internally
-
-// ✅ Production pattern
-val settings = UIKitSettings.UIKitSettingsBuilder()
-    .setAppId("APP_ID")
-    .setRegion("us")
-    // No authKey
-    .build()
-
-// Get token from your backend server
-val authToken = yourServer.getAuthToken(userId)
-CometChatUIKit.loginWithAuthToken(authToken, callback)
-```
-
-### 1.2 Server-Side Token Generation
-
-Your backend generates auth tokens using the CometChat REST API:
-- Endpoint: `POST https://{appId}.api-{region}.cometchat.io/v3/users/{uid}/auth_tokens`
-- Header: `apiKey: YOUR_API_KEY` (server-side only)
-
-The auth token is then passed to the client for `loginWithAuthToken()`.
-
-## 2. ProGuard / R8 Configuration
-
-### 2.1 Consumer Rules
-
-CometChat UIKit modules include `consumer-rules.pro` that are automatically applied. Check that your app's `build.gradle.kts` has:
-
-```kotlin
-android {
-    buildTypes {
-        release {
-            isMinifyEnabled = true
-            proguardFiles(
-                getDefaultProguardFile("proguard-android-optimize.txt"),
-                "proguard-rules.pro"
-            )
-        }
-    }
-}
-```
-
-### 2.2 Additional ProGuard Rules
-
-If you encounter issues with minification, add these rules:
-
-```proguard
-# CometChat SDK
--keep class com.cometchat.chat.** { *; }
--keep class com.cometchat.calls.** { *; }
-
-# CometChat UIKit
--keep class com.cometchat.uikit.** { *; }
-
-# Gson (used for FCM DTO parsing)
--keep class com.google.gson.** { *; }
--keepattributes Signature
--keepattributes *Annotation*
-
-# Firebase
--keep class com.google.firebase.** { *; }
-```
-
-## 3. Security Checklist
-
-| Item | Status | Notes |
+"are we production ready?", "switch from the Auth Key to auth tokens", "prepare the release build", "does CometChat need ProGuard rules?", "what are the rate limits?", "anything to do before Play Store submission?".
+
+## Production golden path
+1. **Auth: server-minted tokens, never the Auth Key.** The dev flow (`login(uid, …)` backed by `credentials.authKey` in the settings file) is **development only** — the Auth Key can create/authenticate any user, so shipping it in an APK is a full compromise (APKs are trivially decompiled). Production: your backend creates the user and mints a per-user **auth token** via the CometChat REST API, your app fetches it over your own authenticated channel, then:
+   ```kotlin
+   CometChatUIKit.loginWithAuthToken(authToken, object : CometChat.CallbackListener<User>() {
+       override fun onSuccess(user: User) { /* unlock the chat UI */ }
+       override fun onError(e: CometChatException) { /* surface + retry path */ }
+   })
+   ```
+   Guard it the same way (`getLoggedInUser() != null` → skip). Token fetch failure must be a real error state, not a blank screen.
+2. **Strip credentials from the release artifact.** Omit `credentials.authKey` from `app/src/main/assets/cometchat-settings.json` in release builds (or ship a release-flavored assets file); keep the file **gitignored**. `appId`/`region` are not secrets, the Auth Key is. Verify by unzipping the APK/AAB and grepping the merged assets — do this before every release.
+3. **Provision users server-side.** `CometChatUIKit.createUser(...)` is for prototypes; production creates users through your backend + the CometChat REST API, in the same request that issues the auth token.
+4. **Log out cleanly.** Unregister the push token BEFORE `CometChatUIKit.logout(...)` (`cometchat-android-v6-push`), and clear any cached uid/token in your own storage — otherwise the next user on a shared device inherits notifications.
+5. **Release build sanity.** Build the **release** variant (not just debug) and run the app: minified/shrunk builds are where reflection-based failures appear. The kit ships its own consumer rules, so there is normally nothing to add — but **verify by running the release build**, and if a `ClassNotFoundException`/serialization failure appears, capture it and check the current kit docs before hand-writing `-keep` rules. Don't paste ProGuard rules from memory.
+6. **Rate limits & scale.** The Chat SDK has documented limits (message rates, request sizes, listener/connection behavior) — fetch `/sdk/android/v5/rate-limits.md` before building anything that sends in bulk or fans out; paginate with request builders rather than unbounded fetches.
+7. **Play Store prerequisites.** Fetch `/sdk/android/v5/publishing-app-on-playstore.md` — it covers what the SDK needs for a store submission. Also budget for: runtime permission rationale (CAMERA/RECORD_AUDIO for calls, POST_NOTIFICATIONS for push), a privacy-policy entry covering chat data, and Data-safety form answers reflecting what CometChat transmits.
+
+## Known failure modes → fix
+| Symptom | Cause | Fix |
 |---|---|---|
-| Remove `authKey` from client code | Required | Use `loginWithAuthToken()` |
-| Store `appId` securely | Recommended | Use BuildConfig or encrypted prefs |
-| Use HTTPS for all custom endpoints | Required | `overrideAdminHost` / `overrideClientHost` |
-| Validate auth tokens server-side | Required | Tokens should expire |
-| Do not log sensitive data | Required | Remove debug logs in release |
-| Enable R8/ProGuard | Recommended | Obfuscates code |
-| Pin SSL certificates | Optional | For high-security apps |
-
-## 4. Release Build Configuration
-
-```kotlin
-android {
-    compileSdk = 36
-
-    defaultConfig {
-        minSdk = 28
-        targetSdk = 36
-    }
-
-    buildTypes {
-        release {
-            isMinifyEnabled = true
-            isShrinkResources = true
-            proguardFiles(
-                getDefaultProguardFile("proguard-android-optimize.txt"),
-                "proguard-rules.pro"
-            )
-        }
-    }
-
-    compileOptions {
-        sourceCompatibility = JavaVersion.VERSION_11
-        targetCompatibility = JavaVersion.VERSION_11
-    }
-
-    kotlinOptions {
-        jvmTarget = "11"
-    }
-}
-```
-
-## 5. Dependency Management
-
-### 5.1 Compose BOM
-
-For Compose stack, use the BOM to align Compose library versions:
-
-```kotlin
-implementation(platform("androidx.compose:compose-bom:2024.x.x"))
-implementation("androidx.compose.ui:ui")
-implementation("androidx.compose.material3:material3")
-```
-
-### 5.2 Version Pinning
-
-Pin CometChat SDK versions explicitly:
-
-```kotlin
-implementation("com.cometchat:chatuikit-compose-android:6.0.+")
-// or
-implementation("com.cometchat:chatuikit-kotlin-android:6.0.+")
-```
-
-> Never pin `6.0.0-beta2` (or any `-beta` preview) in a production build — V6 went GA on 2026-05-25. The `6.0.+` dynamic pin tracks GA patches forward (ENG-35701). Pin an exact GA patch (e.g. `6.0.1`) if your release process requires reproducible builds.
-
-## 6. minSdk 28 Implications
-
-v6 requires `minSdk = 28` (Android 9.0 Pie). This means:
-- No support for Android 7.0-8.1 devices
-- Full TLS 1.3 support
-- Native BiometricPrompt API available
-- Adaptive icons required
-
-## Hard rules
-
-- NEVER ship `authKey` in production builds — it allows anyone to create users and login
-- ALWAYS use `loginWithAuthToken()` with server-generated tokens in production
-- ALWAYS test the release build with ProGuard/R8 enabled before shipping — CometChat uses reflection in some areas
-- `minSdk` must be 28 — do NOT lower it, v6 APIs depend on API 28+ features
-- Remove all `Log.d()` / debug logging in release builds — use `BuildConfig.DEBUG` guards
+| Auth works in debug, fails in release | release settings file has no `authKey` but code still uses `login(uid)` | switch the release path to `loginWithAuthToken` |
+| Auth Key found in the APK | `credentials.authKey` shipped | remove for release; rotate the key in the Dashboard |
+| Crash only in release | shrinking/obfuscation | reproduce on the release variant, read the real stack trace, then consult docs before adding keep rules |
+| Notifications reach the wrong user | token not unregistered on logout | unregister before logout |
+| Sends throttled / requests rejected | rate limits | batch + paginate; fetch the limits page |
+| Blank chat after reinstall | token fetch failed and wasn't surfaced | render an error state + retry |
+
+## Common pitfalls
+Treating the dev Auth Key path as shippable · a settings file committed to git · never building the release variant before submission · creating users from the client in production · hand-written ProGuard rules copied from an old version · unbounded message/user fetches · no error state for token-fetch failure · leaving `enableCalling`/debug logging on when the product doesn't use calls.
+
+## Verify it works
+Compile (`./gradlew :app:assembleDebug   # in YOUR app (npm run verify:fences:android-v6 is a pack-repo gate)`). Then, on a **release** build installed on a device: login uses `loginWithAuthToken` and succeeds; unzipping the artifact shows **no Auth Key**; chat, calls (if used) and push all work post-minification; logout unregisters push and a second user's session is clean; an intentionally broken token fetch shows a readable error, not a blank screen. Anything you could not verify (store review, backend token endpoint) — say so explicitly rather than claiming it.

package/skills/cometchat-android-v6-push/SKILL.md

@@ -1,315 +1,65 @@
 ---
 name: cometchat-android-v6-push
-description: "CometChat Android UIKit v6 push notifications — FCM setup, chat/call notification handling, VoIP integration, and deep-linking"
+description: "Add push notifications (FCM) to an Android v6 CometChat app — Firebase + Dashboard provider setup, the push dependency, token registration after login, token refresh, unregister on logout, manifest/service wiring, badge count and notification navigation. THIN + docs-first: fetches the notifications docs for exact payloads. Triggers: 'add push notifications android cometchat', 'fcm cometchat android', 'notifications not arriving android', 'badge count android'."
 license: "MIT"
-compatibility: "Android 9.0+ (API 28); Kotlin 1.9+; com.cometchat:chatuikit-compose-android:6.x / com.cometchat:chatuikit-kotlin-android:6.x"
+compatibility: "Android minSdk >=28; compileSdk >=36; Kotlin >=2.1; AGP >=8.9.1; JVM target 11; com.cometchat:chatuikit-kotlin-android ^6 OR com.cometchat:chatuikit-compose-android ^6 (6.0.x); com.cometchat:chat-sdk-android ^5; Firebase BoM (firebase-messaging)"
 metadata:
   author: "CometChat"
-  version: "3.0.0"
-  tags: "cometchat, android, push, fcm, firebase, voip, notifications, calls"
+  version: "1.0.0"
+  tags: "cometchat android push notifications fcm v6 firebase"
 ---
 
-> **Ground truth:** `com.cometchat:chatuikit-{compose,kotlin}-android:6.x` (+ `calls-sdk-android:5.x`) — resolved AAR (javap) + `ui-kit/android/v6`. **Official docs:** https://www.cometchat.com/docs/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.
+> **Ground truth:** `features.android-v6.json` (`push-notifications`) + the **live notifications docs** — `/notifications/android-push-notifications` is the manual (12 sections: Firebase+Dashboard prep, Gradle, manifest/services, application wiring, token registration, unregister, badge count, message/call pushes, payload customization, navigation). This skill is THIN and docs-first: it owns the ORDER and the traps; **fetch the page for exact payloads/snippets** (`core` → `references/docs-map.md`).
 
-> **Companion skills:** cometchat-android-v6-core (init/login), cometchat-android-v6-events (call events), cometchat-android-v6-builder-settings (calling config)
-
-## Purpose
-
-Set up push notifications for CometChat v6 using Firebase Cloud Messaging (FCM), handle chat and call notifications, and integrate VoIP for background call handling.
+## Companion skills (read first)
+- `cometchat-android-v6-core` — install, credentials, `initFromSettings → login`, lifecycle. Assumed here, never repeated.
+- `cometchat-android-v6-calls` — call pushes ride the same channel (ConnectionService path in the docs).
 
 ## Use this skill when
+"add push notifications", "set up FCM with CometChat", "pushes aren't arriving", "notification badge count", "open the right chat when a notification is tapped".
 
-- Adding FCM push notifications for chat messages
-- Handling incoming call notifications (foreground and background)
-- Setting up VoIP with TelecomManager for native call UI
-- Implementing deep-link navigation from notifications
-
-## Do not use this skill when
-
-- Just initializing the SDK (use `cometchat-android-v6-core`)
-- Working with UI components (use `cometchat-*-components`)
-
-## 1. FCM Setup
-
-### 1.1 Gradle Dependencies
-
-```kotlin
-// In project-level build.gradle
-plugins {
-    id("com.google.gms.google-services") version "4.4.2" apply false
-}
-
-// In app-level build.gradle.kts
-plugins {
-    id("com.google.gms.google-services")
-}
-
-dependencies {
-    implementation(platform("com.google.firebase:firebase-bom:33.x.x"))
-    implementation("com.google.firebase:firebase-messaging")
-}
-```
-
-Add `google-services.json` to your app module's root directory.
-
-### 1.2 Initialize Firebase
-
-```kotlin
-// In Application.onCreate()
-FirebaseApp.initializeApp(this)
-```
-
-### 1.3 Register / unregister the push token (the kit's ONLY public push API)
-
-This is the single load-bearing client step. `CometChatNotifications.registerPushToken(...)` binds the FCM token to the logged-in CometChat user; `unregisterPushToken(...)` clears it. The Android `PushPlatforms` constant is **`FCM_ANDROID`** (verified in `com.cometchat.chat.enums.PushPlatforms` — the only Android value). Everything in §2 onward is sample-app glue you control; *this* is the real API.
+## Feature check (the oracle first)
+`features.android-v6.json` → `push-notifications`: **`gradle-package`**, `needs_stitching: true`, `needs_dashboard: true`. So it is never "just code": it needs **(a)** a Firebase project + `google-services.json`, **(b)** an FCM **provider configured in the CometChat Dashboard** (you get a **Provider ID** — you'll need it in code), and **(c)** client wiring. Tell the user all three up front; you cannot do (a)/(b) for them.
 
+## Enablement — the ordered path
+1. **Firebase + Dashboard** — create/choose the Firebase project, add the Android app, download `google-services.json` into `app/`. In the CometChat Dashboard → Notifications, add the FCM provider (service-account credentials) and note the **Provider ID**.
+2. **Gradle** — Google services plugin + `com.google.firebase:firebase-messaging` (via the Firebase BoM) alongside your kit + `chat-sdk-android`. Exact coordinates/versions: fetch the docs page (§2) rather than pinning from memory.
+3. **Manifest + service** — the `POST_NOTIFICATIONS` runtime permission (Android 13+), your `FirebaseMessagingService` subclass registered in the manifest, and a notification channel. (docs §3, §5)
+4. **Register the token AFTER login succeeds** — never before; the token binds to the logged-in user:
 ```kotlin
-import com.cometchat.chat.core.CometChatNotifications
-import com.cometchat.chat.enums.PushPlatforms
-import com.cometchat.chat.exceptions.CometChatException
-import com.google.firebase.messaging.FirebaseMessaging
-
-// Call AFTER CometChatUIKit.login(...) resolves (a token registered before
-// login is not bound to a user). Also call from FCMService.onNewToken when a
-// session already exists (token rotation).
-fun registerPushToken() {
-    FirebaseMessaging.getInstance().token.addOnCompleteListener { task ->
-        if (!task.isSuccessful) return@addOnCompleteListener
+FirebaseMessaging.getInstance().token.addOnCompleteListener { task ->
+    if (task.isSuccessful) {
         CometChatNotifications.registerPushToken(
             task.result,
             PushPlatforms.FCM_ANDROID,
-            "YOUR_PROVIDER_ID",  // FCM Provider ID from the CometChat dashboard (§4 setup)
-            object : CometChat.CallbackListener<String>() {
-                override fun onSuccess(s: String?) { /* registered */ }
-                override fun onError(e: CometChatException) { /* log + retry */ }
+            PROVIDER_ID,                       // from the Dashboard FCM provider
+            object : CometChat.CallbackListener<String?>() {
+                override fun onSuccess(uid: String?) { /* registered */ }
+                override fun onError(e: CometChatException) { /* retry / surface */ }
             }
         )
     }
 }
-
-// Call BEFORE CometChatUIKit.logout() — otherwise the logged-out device keeps
-// receiving pushes for the previous user.
-fun unregisterPushToken(onDone: () -> Unit) {
-    CometChatNotifications.unregisterPushToken(object : CometChat.CallbackListener<String>() {
-        override fun onSuccess(s: String?) { onDone() }
-        override fun onError(e: CometChatException) { onDone() } // proceed with logout regardless
-    })
-}
-```
-
-Lifecycle: **register after login resolves** (and on `onNewToken` when a session exists), **unregister before logout**. This mirrors the verified `cometchat-android-v5-push` pattern — the registration API is identical across v5/v6 (it lives in the Chat SDK, not the UI Kit).
-
-## 2. FCMService Implementation
-
-> **Heads-up — this is a reference pattern.** The classes referenced below (`CometChatVoIP`, `CometChatVoIPConnectionService`, `FCMMessageDTO`, `FCMCallDto`, `FCMService`, `VoIPPermissionListener`, `CometChatVoIPUtils`, `FCMMessageNotificationUtils`) are NOT exported from `com.cometchat:chatuikit-{compose,kotlin}-android:6.x`. They are sample-app glue (derived from the CometChat Android push sample app — note: not present in the v6 kit clone, so treat them as a copy-in/reference pattern) — copy the relevant source files into your project, or use them as a guide for writing your own equivalents. The kit's only public push surface is `CometChatNotifications.registerPushToken(...)` / `unregisterPushToken(...)`; everything below is glue you control.
-
-Pattern from `master-app-jetpack/fcm/FCMService.kt` (sample-app code, copy into your project):
-
-```kotlin
-class FCMService : FirebaseMessagingService() {
-
-    companion object {
-        var fcmToken: String? = null
-            private set
-    }
-
-    override fun onNewToken(token: String) {
-        super.onNewToken(token)
-        fcmToken = token
-        // Store token for later use (e.g., SharedPreferences)
-    }
-
-    override fun onMessageReceived(message: RemoteMessage) {
-        super.onMessageReceived(message)
-
-        if (message.data.isEmpty()) return
-
-        val type = message.data["type"]?.lowercase()
-        when (type) {
-            "chat" -> handleChatNotification(message)
-            "call" -> handleCallNotification(message)
-        }
-    }
-}
-```
-
-### 2.1 Chat Notification Handling
-
-```kotlin
-private fun handleChatNotification(message: RemoteMessage) {
-    val fcmMessageDTO = Gson().fromJson(
-        Gson().toJson(message.data),
-        FCMMessageDTO::class.java
-    )
-
-    // Mark as delivered for read receipts (only if SDK is initialized)
-    if (CometChatUIKit.isSDKInitialized()) {
-        CometChat.markAsDelivered(
-            fcmMessageDTO.tag!!.toLong(),
-            fcmMessageDTO.sender!!,
-            fcmMessageDTO.receiverType!!,
-            fcmMessageDTO.receiver!!
-        )
-    }
-
-    // Show notification if user is NOT in the same chat
-    val isUser = fcmMessageDTO.receiverType == CometChatConstants.RECEIVER_TYPE_USER
-    val uid = if (isUser) fcmMessageDTO.sender!! else fcmMessageDTO.receiver!!
-
-    if (uid != currentOpenChatId) {
-        // Build and show notification
-        FCMMessageNotificationUtils.showNotification(
-            this, fcmMessageDTO, intent,
-            NOTIFICATION_KEY_REPLY_ACTION,
-            NotificationCompat.CATEGORY_MESSAGE
-        )
-    }
-}
-```
-
-### 2.2 Call Notification Handling
-
-```kotlin
-private fun handleCallNotification(message: RemoteMessage) {
-    val sessionId = message.data["sessionId"]
-    val callAction = message.data["callAction"]
-
-    // CRITICAL: Check if SDK is initialized
-    if (!CometChatUIKit.isSDKInitialized()) {
-        return // Cannot handle call without SDK
-    }
-
-    // Check VoIP permissions
-    if (!CometChatVoIP.hasReadPhoneStatePermission(this) ||
-        !CometChatVoIP.hasManageOwnCallsPermission(this) ||
-        !CometChatVoIP.hasAnswerPhoneCallsPermission(this)) {
-        return
-    }
-
-    // Check phone account is enabled
-    CometChatVoIP.hasEnabledPhoneAccountForVoIP(this, object : VoIPPermissionListener {
-        override fun onPermissionsGranted() {
-            handleCallFlow(message)
-        }
-        override fun onPermissionsDenied(error: CometChatVoIPError?) {
-            // Cannot show VoIP UI
-        }
-    })
-}
-```
-
-## 3. VoIP Integration
-
-### 3.1 Required Permissions
-
-```xml
-<uses-permission android:name="android.permission.READ_PHONE_STATE" />
-<uses-permission android:name="android.permission.MANAGE_OWN_CALLS" />
-<uses-permission android:name="android.permission.ANSWER_PHONE_CALLS" />
 ```
-
-### 3.2 VoIP Call Flow
-
+5. **Re-register on token refresh** — the same call inside your service's `onNewToken(token)`. **Without this, pushes stop silently after Firebase rotates the token.**
+6. **Unregister on logout — BEFORE `CometChatUIKit.logout()`**:
 ```kotlin
-private fun handleCallFlow(message: RemoteMessage) {
-    val callData = Gson().fromJson(
-        Gson().toJson(message.data),
-        FCMCallDto::class.java
-    )
-
-    // Initialize VoIP
-    CometChatVoIP.init(this, applicationInfo.loadLabel(packageManager).toString())
-
-    when (callData.callAction) {
-        "initiated" -> {
-            // Show incoming call UI (only if app is in background)
-            if (!isAppInForeground()) {
-                voipIncomingCall(callData)
-            }
-            // If foreground, UIKit's CometChatIncomingCall handles it
-        }
-        "cancelled", "unanswered" -> {
-            // End the native call UI if session matches
-            if (CometChatVoIPUtils.currentSessionId == callData.sessionId) {
-                CometChatVoIP.telecomManager?.endCall()
-            }
-        }
-    }
-}
-```
-
-### 3.3 Foreground vs Background Routing
-
-| App State | Incoming Call Handler |
-|---|---|
-| Foreground | UIKit's `CometChatIncomingCall` via SDK call listener |
-| Background | VoIP via `TelecomManager` + `CometChatVoIPConnectionService` |
-| Killed | FCM wakes app, but SDK may not be initialized — cannot handle call |
-
-### 3.4 Busy Rejection
-
-```kotlin
-private fun rejectCallWithBusyStatus(call: Call) {
-    CometChat.rejectCall(
-        call.sessionId,
-        CometChatConstants.CALL_STATUS_BUSY,
-        object : CometChat.CallbackListener<Call>() {
-            override fun onSuccess(rejectedCall: Call?) {
-                rejectedCall?.let {
-                    CometChatEvents.emitCallEvent(CometChatCallEvent.CallRejected(it))
-                }
-            }
-            override fun onError(e: CometChatException) { }
-        }
-    )
-}
-```
-
-## 4. AndroidManifest Registration
-
-```xml
-<service
-    android:name=".fcm.FCMService"
-    android:exported="false">
-    <intent-filter>
-        <action android:name="com.google.firebase.MESSAGING_EVENT" />
-    </intent-filter>
-</service>
-
-<!-- VoIP Connection Service -->
-<service
-    android:name=".voip.CometChatVoIPConnectionService"
-    android:permission="android.permission.BIND_TELECOM_CONNECTION_SERVICE"
-    android:exported="true">
-    <intent-filter>
-        <action android:name="android.telecom.ConnectionService" />
-    </intent-filter>
-</service>
-```
-
-## 5. WebSocket Connection Management
-
-From `master-app-jetpack/Application.kt` — manage WebSocket connections based on app lifecycle:
-
-```kotlin
-// When app comes to foreground
-CometChat.connect(object : CometChat.CallbackListener<String?>() {
-    override fun onSuccess(s: String?) { /* connected */ }
-    override fun onError(e: CometChatException) { /* failed */ }
-})
-
-// When app goes to background
-CometChat.disconnect(object : CometChat.CallbackListener<String?>() {
-    override fun onSuccess(s: String?) { /* disconnected */ }
-    override fun onError(e: CometChatException) { /* failed */ }
+CometChatNotifications.unregisterPushToken(object : CometChat.CallbackListener<String?>() {
+    override fun onSuccess(s: String?) { /* then log out */ }
+    override fun onError(e: CometChatException) { /* surface */ }
 })
 ```
+   Skipping this leaks notifications to the previous user on a shared device.
+7. **Handle the payload** — message pushes (§9), call pushes via ConnectionService (§10), custom text/parsing (§11), tap-to-open navigation (§12), badge count (§8, needs the Dashboard badge toggle + a badge library). Fetch these sections; don't invent payload keys.
+
+## Client token wiring — the rules that matter
+- Registration is **per logged-in user per device**: register after every successful login, unregister before every logout, re-register on refresh.
+- The **Provider ID must match** the Dashboard FCM provider — a wrong/blank ID registers fine and then delivers nothing.
+- Handle `onError` — a failed registration is the single most common cause of "no notifications", and it fails quietly if you ignore it.
+- Foreground behavior is yours: CometChat delivers the push; whether you show a notification while the chat is open is app logic.
 
-## Hard rules
+## Common pitfalls
+Registering before login (token bound to nobody) · no `onNewToken` re-registration (pushes die after rotation) · no unregister on logout · wrong/omitted Provider ID · missing `google-services.json` or the Google-services plugin · missing `POST_NOTIFICATIONS` permission on Android 13+ · no notification channel (notification silently dropped) · testing on an emulator without Play services · assuming the Dashboard provider exists — ask.
 
-- ALWAYS check `CometChatUIKit.isSDKInitialized()` before making SDK calls in FCM service — the app may have been killed
-- NEVER show VoIP incoming call UI when app is in foreground — UIKit's `CometChatIncomingCall` handles foreground calls
-- VoIP requires READ_PHONE_STATE, MANAGE_OWN_CALLS, and ANSWER_PHONE_CALLS permissions — check all three before handling calls
-- `CometChat.markAsDelivered()` requires the SDK to be initialized — skip it if not
-- For push token registration, use `CometChatNotifications.registerPushToken(...)` / `unregisterPushToken(...)` — that is the kit's only public push API. The `CometChatVoIP*` / `FCM*` classes shown above are sample-app glue (`master-app-jetpack`), not part of `chatuikit-{compose,kotlin}`
-- Always manage WebSocket connections based on app lifecycle to avoid battery drain
+## Verify it works
+Compile against the pinned kit (`./gradlew :app:assembleDebug   # in YOUR app (npm run verify:fences:android-v6 is a pack-repo gate)`). **Live delivery is a MANUAL device check — it cannot be auto-smoked** (blocked-external; be honest about this): install on a real device with Play services, log in, confirm the registration callback hit `onSuccess`, background the app, send a message from another user → the notification arrives, and tapping it opens the right chat. Then log out and confirm notifications stop. Nothing arriving ⇒ check, in order: registration `onError`, Provider ID, Dashboard provider config, `google-services.json`, notification permission/channel.