@cometchat/skills 4.4.1 → 5.0.0

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

@@ -1,270 +1,86 @@
 ---
 name: cometchat-android-v6-troubleshooting
-description: "CometChat Android UIKit v6 troubleshooting — diagnostic table, common issues, and fixes for both Kotlin Views and Compose stacks"
+description: "Diagnose a broken CometChat Android v6 integration — dependency and version conflicts, init/login failures, blank or stuck screens, empty lists, missing realtime updates, keyboard/inset layout bugs, release-only crashes, permission and push problems — with a symptom → cause → fix path and what evidence to collect before escalating. Triggers: 'cometchat android not working', 'could not find com.cometchat', 'chat screen is blank android', 'messages not arriving in real time android', 'composer hidden by keyboard'."
 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.1"
-  tags: "cometchat, android, troubleshooting, debugging, errors, issues"
+  version: "1.0.0"
+  tags: "cometchat android troubleshooting v6 diagnostics errors debugging"
 ---
 
-> **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/ui-kit/android/v6/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:** catalog `android-v6.json` + the kit's real error codes (`ERR_SETTINGS_FILE_NOT_FOUND`, `ERR_SETTINGS_INVALID`, `CometChatException.code/message`) + the live page `/ui-kit/android/troubleshooting`. This skill goes DEEPER than `core/references/troubleshooting.md` (the quick table) — read that first for the common four; come here for the full path and for escalation.
 
-> **Companion skills:** cometchat-android-v6-core (init/login), cometchat-android-v6-compose-theming, cometchat-android-v6-kotlin-theming, cometchat-android-v6-push
-
-## Purpose
-
-Diagnose and fix common issues with CometChat Android UIKit v6 across both Kotlin Views and Jetpack Compose stacks.
+## Companion skills (read first)
+- `cometchat-android-v6-core` — install, credentials, `initFromSettings → login → render`, **`references/troubleshooting.md`** (the first-stop table), `references/anti-patterns.md`, `references/layout.md`. Assumed here, never repeated.
 
 ## Use this skill when
+"it doesn't work", "the build fails", "the chat screen is blank/stuck", "messages don't arrive until I reopen", "the composer is under the keyboard", "it works in debug but crashes in release", "calls/push don't work" — and you need a systematic path, not a guess.
 
-- Encountering errors during SDK initialization or login
-- Components not rendering or displaying incorrectly
-- Push notifications not working
-- Call features not functioning
-- Build or dependency issues
-
-## Do not use this skill when
-
-- Setting up a new project (use `cometchat-android-v6-core`)
-- Looking for component APIs (use `cometchat-*-components`)
+## Diagnostics entry — run these three, in order, before theorizing
+1. **Does it BUILD?** `./gradlew :app:assembleDebug`. Dependency-resolution and duplicate-class failures are config, not code.
+2. **What does LOGCAT say at startup?** Filter for `CometChat`. You are looking for exactly two things: init's `onSuccess`/`onError`, then login's `onSuccess`/`onError`. **Almost every "nothing works" report is one of these two failing and being swallowed** — if your callbacks don't log `e.code` + `e.message`, fix that first; an empty `onError {}` is the bug.
+3. **What's the SESSION state?** `CometChatUIKit.getLoggedInUser()` — null after a "successful" login means login didn't actually complete.
 
-## 1. Diagnostic Table
-
-| Symptom | Likely Cause | Fix |
+## Symptom → root cause → fix
+**Build / dependencies**
+| Symptom | Cause | Fix |
 |---|---|---|
-| `Authentication null` error on init | `UIKitSettings` not configured | Ensure `setAppId()` and `setRegion()` are called on builder |
-| `APP ID null` error on init | Missing app ID | Call `setAppId("YOUR_APP_ID")` on `UIKitSettingsBuilder` |
-| Login fails with auth error | Invalid authKey or UID | Verify authKey from CometChat dashboard; check UID exists |
-| Components show no data | SDK not initialized or user not logged in | Check `CometChatUIKit.isSDKInitialized()` and `getLoggedInUser()` |
-| Compose components crash | Missing `CometChatTheme {}` wrapper | Wrap all CometChat composables in `CometChatTheme {}` |
-| Views theme colors wrong | XML attrs not set | Inherit Activity theme from `CometChatTheme.DayNight` (see `-kotlin-placement`); for brand colors override `cometchat*` attrs in the Activity theme or call `CometChatTheme.setPrimaryColor(...)` |
-| `IllegalArgumentException: The style on this component requires your app theme to be Theme.MaterialComponents (or a descendant)` at `MaterialCardView.<init>` (typically from `CometChatConversations.<init>`) | Activity theme parent is `Theme.AppCompat.*` or `android:Theme.*` | Switch `themes.xml` parent to `CometChatTheme.DayNight` (NOT `Theme.MaterialComponents.*.Bridge` — Bridge drops Material widget defaults and triggers the `MaterialButton` crash below) |
-| `UnsupportedOperationException: Failed to resolve attribute at index N` at `MaterialButton.<init>` (during inflate of kit-internal layout) | Activity theme is `Theme.MaterialComponents.*` (or `.Bridge`) but missing `cometchat*` attrs | Switch `themes.xml` parent to `CometChatTheme.DayNight` — the kit's own theme supplies every `cometchat*` attr its internal layouts reference |
-| Dark mode not applied (Compose) | Using `lightColorScheme()` always | Use `if (isSystemInDarkTheme()) darkColorScheme() else lightColorScheme()` |
-| Dark mode not applied (Views) | Theme cache stale | Call `CometChatTheme.clearCache()` on configuration change |
-| Messages not loading | User/Group not set on component | Call `setUser(user)` or pass `user` parameter before display |
-| Push notifications not received | Missing `google-services.json` | Add file to app module root; verify Firebase project config |
-| FCM token not registered | `onNewToken()` not called | Manually request token with `FirebaseMessaging.getInstance().token` |
-| Call notifications not showing | VoIP permissions missing | Request READ_PHONE_STATE, MANAGE_OWN_CALLS, ANSWER_PHONE_CALLS |
-| Calls SDK not initialized | `enableCalling` not set | Set `setEnableCalling(true)` on `UIKitSettingsBuilder` |
-| `CometChatCalls` class not found | Missing calls SDK dependency | Add `com.cometchat:calls-sdk-android` to dependencies |
-| Calls broken on `chatuikit:6.0.0` (call button targets wrong user, in-call screen blank, etc.) | Known v6.0.0 calls defects — `CometChatCallButtons` captures the first-rendered user globally + 4 related bugs | Apply the **5 documented workarounds (W1–W5)** in `cometchat-android-v6-calls` (§"Five required workarounds"). The kit ships broken for calls at 6.0.0 but works end-to-end with W1–W5 (validated on device). Don't hand-patch blind — use that section. |
-| Build fails with duplicate classes | Conflicting annotation libs | Add `exclude(group = "org.jetbrains", module = "annotations-java5")` to configurations |
-| `compileSdk` error | SDK too low | Set `compileSdk = 36` |
-| `minSdk` error | API level too low | Set `minSdk = 28` — v6 requires Android 9.0+ |
-| Compose preview crashes | Missing preview data | Use the `preview/` package helpers for `@Preview` composables |
-| WebSocket disconnects in background | No lifecycle management | Call `CometChat.connect()` on foreground, `disconnect()` on background |
-| Recomposition issues | Unstable state in composables | Ensure state is hoisted properly; use `remember` and `derivedStateOf` |
-| BubbleFactory not applied | Wrong factory key | Verify `getCategory()` and `getType()` match the message's category and type |
-| Style not applied (Compose) | Using constructor instead of `default()` | Use `StyleClass.default(param = value)` not `StyleClass(...)` |
-
-## 2. Initialization Issues
-
-### 2.1 Verify SDK State
-
-```kotlin
-// Check initialization
-Log.d("CometChat", "SDK initialized: ${CometChatUIKit.isSDKInitialized()}")
-Log.d("CometChat", "Calls SDK initialized: ${CometChatUIKit.isCallsSDKInitialized()}")
-Log.d("CometChat", "Logged in user: ${CometChatUIKit.getLoggedInUser()?.uid}")
-```
-
-### 2.2 Common Init Sequence Issues
-
-```kotlin
-// ❌ Wrong: init in every Activity
-class ChatActivity : AppCompatActivity() {
-    override fun onCreate(savedInstanceState: Bundle?) {
-        CometChatUIKit.init(this, settings, callback) // DON'T DO THIS
-    }
-}
-
-// ✅ Correct: init once in Application or splash
-class MyApp : Application() {
-    override fun onCreate() {
-        super.onCreate()
-        CometChatUIKit.init(this, settings, callback)
-    }
-}
-```
-
-## 3. Compose-Specific Issues
-
-### 3.1 Missing Theme Wrapper
-
-```kotlin
-// ❌ Crash: CompositionLocal not provided
-setContent {
-    CometChatConversations() // Will crash or look wrong
-}
-
-// ✅ Correct
-setContent {
-    CometChatTheme {
-        CometChatConversations()
-    }
-}
-```
-
-### 3.2 Nested Theme Wrappers
-
-```kotlin
-// ❌ Unnecessary nesting
-CometChatTheme {
-    NavHost(...) {
-        composable("chat") {
-            CometChatTheme { // Don't nest
-                CometChatMessageList(user = user)
-            }
-        }
-    }
-}
-
-// ✅ Single wrapper at top level
-CometChatTheme {
-    NavHost(...) {
-        composable("chat") {
-            CometChatMessageList(user = user)
-        }
-    }
-}
-```
-
-## 4. Views-Specific Issues
-
-### 4.1 Theme Attributes Not Resolving
-
-```kotlin
-// If colors are all 0/transparent, the XML attrs aren't set
-// Fix: Set programmatically
-CometChatTheme.setPrimaryColor(Color.parseColor("#6851D6"))
-// Or add attrs to your Activity's theme in styles.xml
-```
-
-### 4.2 RecyclerView Scroll Issues
-
-If message list doesn't scroll properly, ensure the layout gives it flexible height:
-
-```xml
-<!-- ✅ Use layout_weight for flexible height -->
-<CometChatMessageList
-    android:layout_width="match_parent"
-    android:layout_height="0dp"
-    android:layout_weight="1" />
-```
-
-## 5. Push Notification Issues
-
-### 5.0 No notifications shown on Android 13+ (API 33+)
-
-- **Symptom**: FCM messages arrive (visible in logcat) but no system notification appears on Android 13+.
-- **Cause**: `POST_NOTIFICATIONS` is a **runtime** permission on API 33+ — declaring it in the manifest isn't enough.
-- **Fix**: Declare `<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>` AND request it at runtime (`ActivityCompat.requestPermissions(...)` / the Activity Result API) before you expect notifications. Below API 33 it's granted implicitly.
-
-### 5.1 SDK Not Initialized in FCM Service
-
-```kotlin
-// When app is killed and FCM wakes it, SDK may not be initialized
-override fun onMessageReceived(message: RemoteMessage) {
-    if (!CometChatUIKit.isSDKInitialized()) {
-        // Cannot handle message — show basic notification or skip
-        return
-    }
-    // Safe to proceed
-}
-```
-
-### 5.2 VoIP Permission Check
-
-> ⚠️ **`CometChatVoIP` is NOT a v6 kit/SDK API.** It exists only as an app-local helper in the **V5** sample app; the v6 sample even asserts it must not be referenced (`PreservationPropertyTest.kt:78`). Check the permissions directly with `ContextCompat.checkSelfPermission` (or copy the V5 helper into your project if you want its convenience wrappers):
-
-```kotlin
-import androidx.core.content.ContextCompat
-import android.content.pm.PackageManager
-import android.Manifest
-
-// All three permissions are required for VoIP calling
-fun hasVoipPermissions(context: Context): Boolean {
-    val needed = listOf(
-        Manifest.permission.READ_PHONE_STATE,
-        Manifest.permission.MANAGE_OWN_CALLS,
-        Manifest.permission.ANSWER_PHONE_CALLS,
-    )
-    return needed.all {
-        ContextCompat.checkSelfPermission(context, it) == PackageManager.PERMISSION_GRANTED
-    }
-}
-```
-
-## 6. Dependency Conflicts
-
-### 6.1 Jetbrains Annotations Conflict
-
-```kotlin
-// In build.gradle.kts
-configurations.all {
-    exclude(group = "org.jetbrains", module = "annotations-java5")
-}
-```
-
-### 6.2 Maven Repository Missing
-
-```kotlin
-// In settings.gradle
-repositories {
-    maven { url = uri("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/") }
-}
-```
-
-## 7. Release-build Issues (R8 / ProGuard)
-
-### 7.1 `ClassNotFoundException` on release builds
-
-**Symptom:** App works in debug, crashes on release with `java.lang.ClassNotFoundException: com.cometchat.uikit.compose...` (or `kotlin...` package). R8 has stripped kit classes that look unused via reflection.
-
-**Fix:** Add to `app/proguard-rules.pro`:
-
-```proguard
-# Keep all CometChat UIKit and chat-sdk classes
--keep class com.cometchat.** { *; }
--keepclassmembers class com.cometchat.** { *; }
--dontwarn com.cometchat.**
-```
-
-If you use the calls SDK, also add:
-
-```proguard
--keep class io.dyte.** { *; }
--dontwarn io.dyte.**
-```
-
-### 7.2 `BuildConfig` field missing in release
-
-**Symptom:** `BuildConfig.COMETCHAT_APP_ID` resolves to empty string in release. Caused by `local.properties` not being copied during CI builds.
-
-**Fix:** Provide credentials via Gradle properties from CI environment vars instead of relying on `local.properties`:
-
-```kotlin
-// app/build.gradle.kts
-android {
-    defaultConfig {
-        buildConfigField(
-            "String", "COMETCHAT_APP_ID",
-            "\"${project.findProperty("cometchat.appId") ?: System.getenv("COMETCHAT_APP_ID") ?: ""}\""
-        )
-        // …same for region + authKey
-    }
-}
-```
+| `Could not find com.cometchat:chatuikit-…` | CometChat Maven repo missing | add `maven("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/")` to `settings.gradle(.kts)` `dependencyResolutionManagement.repositories` |
+| **`sendMessage` returns `onSuccess` but the message NEVER arrives** (receiver connected, listener registered) | a Dashboard **moderation rule blocked it server-side** — the send genuinely succeeded, so no client error is raised. The UI Kit surfaces "Your message was blocked due to moderation policies"; a headless build sees nothing at all | Dashboard → **Moderation** → check rules/lists. Do NOT chase INTERNET permission or connection status — both are healthy in this case |
+| `Duplicate class android.support.v4.*` (jetifier off) **or** `contains AndroidX dependencies, but the 'android.useAndroidX' property is not enabled` (useAndroidX off) — on a **clean, single-cohort** app | NOT a version conflict. `chat-sdk-android` pulls a pre-AndroidX transitive (`android.arch.lifecycle:extensions` → `com.android.support:support-compat:26.1.0`) that collides with `androidx.core` | set BOTH in `gradle.properties`: `android.useAndroidX=true` + `android.enableJetifier=true` (verified on a clean app; removing either reproduces it) |
+| `Duplicate class org.jetbrains.annotations.*` at dexing | `io.noties:prism4j` pulls `annotations-java5:17` vs `annotations:23` | `configurations.all { exclude(group = "org.jetbrains", module = "annotations-java5") }` |
+| **`Execution failed for JetifyTransform: react-android-*.aar`** at `checkDebugAarMetadata` — appears only AFTER adding **calling** | `calls-sdk-android` 5.0.x bundles a React-Native stack (`react-android`/`hermes`/`react-native-webrtc`) that Jetifier can't transform, and `core` mandates `android.enableJetifier=true` for the Chat SDK's pre-AndroidX transitive — so the two collide the moment calling is added | add to `gradle.properties`: `android.jetifier.ignorelist=react-android,hermes-android,react-native-webrtc` (they're already AndroidX). See `cometchat-android-v6-calls` |
+| `requires Android Gradle plugin 8.9.1 or higher` | AGP floor is **8.9.1**, not 8.9 | bump AGP |
+| `kotlin-stdlib … metadata is 2.2.0, expected 2.0.0` / internal compiler error | Kotlin floor is **2.1+**; 2.0.21 fails | bump Kotlin |
+| Duplicate class / conflicting versions | **version_conflict**: a v4/v5 `chat-uikit-android` alongside v6 `chatuikit-*` | remove the old artifact — never mix majors; migrate via `cometchat-android-v6-migration` |
+| Odd theme/duplicate UI, two kits resolve | both cohorts (`chatuikit-kotlin-android` AND `chatuikit-compose-android`) in one module | pick ONE cohort |
+| `Unsupported class file major version` / Kotlin errors | JVM target mismatch | JVM 11: `compileOptions` + `kotlin { compilerOptions { jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11) } }` (fully-qualified — a mid-file `import` breaks a `.kts`; the `kotlinOptions{}` DSL is deprecated/removed on Kotlin 2.2+) |
+
+**Init / login**
+| Symptom | Cause | Fix |
+|---|---|---|
+| `ERR_SETTINGS_FILE_NOT_FOUND` | no `app/src/main/assets/cometchat-settings.json` | create it (`core` §4); confirm it's in `assets/`, not `res/` |
+| `ERR_SETTINGS_INVALID` | `appId` or `region` missing/empty in that JSON | fill both |
+| init `onError` about app/auth | wrong **Region** (most common) or wrong App ID | match the Dashboard exactly (`us`/`eu`/`in`) |
+| login `onError` ERR_UID_NOT_FOUND | the UID doesn't exist in this app | use a real user from Dashboard → Users (fresh apps seed `cometchat-uid-1…`), or create it server-side |
+| login "fails silently" / nothing happens | **login called before init resolved** (docs warning) | call login only inside init's `onSuccess` |
+| login error on an already-logged-in user | re-login without logout | guard with `getLoggedInUser() != null`; to switch users, `logout` first |
+| Auth works debug, fails release | release build has no Auth Key but still uses `login(uid)` | use `loginWithAuthToken` (→ `cometchat-android-v6-production`) |
+
+**Blank / empty / stuck UI**
+| Symptom | Cause | Fix |
+|---|---|---|
+| Splash never advances | the gate never unlocks because an `onError` is swallowed | log + render errors; never leave `onError` empty |
+| Chat screen blank/white | UI rendered before login resolved | gate the UI on login success |
+| Component renders as a sliver / crammed | `wrap_content` or an unsized parent — the kit fills its parent | `match_parent`/`0dp`+weight (Views) or `fillMaxSize()`/`weight(1f)` (Compose) — `core/references/layout.md` |
+| Conversation list empty | fresh app with no conversations, or wrong credentials/region | seed a conversation from another user or the Dashboard; re-check App ID/region |
+| List scrolls oddly / doesn't load more | `CometChatMessageList` nested in another scrollable | never nest it in a ScrollView/`verticalScroll` Column |
+
+**Realtime / features**
+| Symptom | Cause | Fix |
+|---|---|---|
+| Messages only appear after reopening | listener not registered, or removed too early | register in the right lifecycle; remove only on teardown (`cometchat-android-v6-events`) |
+| Nothing realtime at all | no internet permission, or connection down | `android.permission.INTERNET` in the manifest; check connection status (SDK `getConnectionStatus`/`addConnectionListener`) |
+| A feature doesn't appear | Dashboard toggle off, or session started before enabling | enable in Dashboard for THIS app, then re-login (`cometchat-android-v6-extensions`) |
+| Thread replies never send | thread list/composer missing the `user`/`group` target (parent id alone isn't enough) | pass BOTH the conversation target and the parent message id |
+| Tapping an affordance does nothing | default-on affordance not wired (thread/search) | wire the destination or hide it |
+
+**Layout / platform**
+| Symptom | Cause | Fix |
+|---|---|---|
+| Composer hidden by the keyboard | no IME handling | `windowSoftInputMode="adjustResize"` (Views) / `imePadding()` (Compose) |
+| Header/composer under the status or nav bar | edge-to-edge without insets | `enableEdgeToEdge()` + inset padding (`core/references/layout.md`) |
+| Crash only in release | shrinking/obfuscation | reproduce on the release variant, read the real trace, then check docs before adding keep rules |
+| Camera/mic fails on a call | runtime permissions not granted | request CAMERA/RECORD_AUDIO (`cometchat-android-v6-calls`) |
+| Push never arrives | registration failed / no `onNewToken` / wrong Provider ID | `cometchat-android-v6-push` verify path |
+| Crash: lifecycle-related on a kit view | host isn't a lifecycle-aware Activity | use `AppCompatActivity`/`ComponentActivity`/`FragmentActivity` |
 
-In CI (e.g. GitHub Actions), set `COMETCHAT_APP_ID` etc. as repository secrets, not as files.
+## Escalating to CometChat support — bring this
+Kit **cohort + exact version** (`chatuikit-compose-android` / `chatuikit-kotlin-android` 6.0.x) and `chat-sdk-android` version · App ID + **region** (never the Auth Key) · the **full `CometChatException`** (`code` AND `message`) from init/login/the failing call · a minimal repro (which component, which screen) · logcat around the failure · device/API level · whether it reproduces in debug and release. Confirm first that it isn't a version_conflict, a Region mismatch, or a swallowed `onError` — those three cover most reports.
 
-## Hard rules
+## Common pitfalls (of debugging itself)
+Empty `onError` blocks · assuming the kit is broken when the container is unsized · changing several things at once · testing against a Dashboard app you didn't verify · treating a debug-only symptom as release-safe (or vice versa) · asking support before capturing the exception code.
 
-- ALWAYS check `isSDKInitialized()` before making SDK calls in background services (FCM, VoIP)
-- ALWAYS wrap Compose components in `CometChatTheme {}` — this is the #1 cause of Compose rendering issues
-- Call `CometChatTheme.clearCache()` in Views when the theme changes dynamically
-- Do NOT lower `minSdk` below 28 or `compileSdk` below 36
-- When reporting bugs, include: SDK version, stack (Compose/Views), Android API level, and the full stack trace
+## Verify it works
+After the fix: rebuild, watch logcat for init `onSuccess` → login `onSuccess`, and re-run the original repro. Then re-check the surrounding invariants — surface fills its parent, keyboard/insets fine, thread and search round-trip, realtime arrives without reopening, and (if touched) the release variant still runs. Confirm the fix's cause was the one you claimed; if you changed several things, revert the unnecessary ones.

package/skills/cometchat-angular-v5-calls/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: cometchat-angular-v5-calls
+description: "Add voice and video calling to an Angular CometChat app — install the calls SDK, mount the incoming-call listener at app root, call buttons in the message header, and call logs. Triggers: 'add voice calling', 'add video calls', 'enable calling', 'show call history', 'incoming call not ringing'."
+license: "MIT"
+compatibility: "@cometchat/chat-uikit-angular ^5 (5.1.0–5.2.0 verified) + @cometchat/calls-sdk-javascript ^5.0.3; Angular 17-21"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat angular calls v5 voice video calling webrtc call-logs"
+---
+
+> **Ground truth:** calling UI ships INSIDE `@cometchat/chat-uikit-angular@5` — there is no separate calls-UI package — but the WebRTC engine is a SEPARATE, NOT-bundled peer: `@cometchat/calls-sdk-javascript@^5.0.3` (major 5, distinct from the chat SDK's v4). Every `CometChat*` symbol below exists in the `angular-v5` catalog. Exhaustive inputs/outputs and advanced call surfaces are FETCHED, not baked — `{DOCS_BASE}/ui-kit/angular/call-features.md`, the per-component pages (`/components/cometchat-incoming-call`, `-call-buttons`, `-call-logs`, `-outgoing-call`), and `/guides/call-log-details`; base + paths in `cometchat-angular-v5-core/references/docs-map.md`. **APPEND to the user's app — additive wiring only** (`RULES.md`).
+
+## Companion skills (read first)
+- `cometchat-angular-v5-core` — install, credentials, `init→login→render`. Assumed.
+- `cometchat-angular-v5-placement` — where the incoming-call listener mounts.
+
+## Use this skill when
+Adding voice/video calling, or diagnosing calls that never ring.
+
+## Prerequisites & install — calls needs a second package
+```bash
+npm install @cometchat/calls-sdk-javascript@^5
+```
+It is an **optional peer** of the UI Kit (`^5.0.3`), so it is not installed by default. Without it the call components are inert and `CometChatUIKit.isCallingEnabled()` returns false.
+
+Calling must also be enabled for the app in the dashboard. Code alone is not enough.
+
+## ⚠️ Installing the package is NOT what turns calling on
+`core` inits with `initFromSettings`, and on that path the kit derives calling from the settings object:
+
+```ts
+// verified in the shipped 5.1.0 bundle
+const callingEnabled = !!settings.uiKit?.['callsSDK'];
+if (callingEnabled) builder.setCallingEnabled(true);
+```
+
+So you must declare a **`uiKit.callsSDK` block** or calling stays off no matter what you installed:
+
+```ts
+CometChatUIKit.initFromSettings({
+  appId, region,
+  credentials: { authKey },
+  chatSDK: { presenceSubscription: { type: 'ALL_USERS' } },
+  uiKit: { callsSDK: {} },          // ← REQUIRED for calling on the initFromSettings path
+});
+```
+
+**Symptom if you miss it:** `<cometchat-call-buttons>` renders as a **zero-size empty element** and the message header shows no call buttons. Nothing errors, nothing logs, and the package is installed — so it reads as a layout or CSS bug. `CometChatUIKit.isCallingEnabled()` returns `false`; check that first.
+
+> The docs' builder path uses `.setCallingEnabled(true)` on `UIKitSettingsBuilder` instead. Both are correct for their own init — see `cometchat-angular-v5-core/references/lifecycle.md`. Do not mix them.
+
+## The four things, in order
+1. **Install the calls SDK** (above).
+2. **Mount `<cometchat-incoming-call>` at APP ROOT** — not in the chat page.
+3. **Add call buttons** — the message header renders them by default.
+4. **Optionally add call logs.**
+
+Step 2 is the one that goes wrong.
+
+## Incoming calls — app root, not the chat route
+```html
+<!-- app.component.html -->
+<cometchat-incoming-call
+  (callAccepted)="onAccepted($event)"
+  (callDeclined)="onDeclined($event)"
+  (error)="onError($event)">
+</cometchat-incoming-call>
+<router-outlet></router-outlet>
+```
+Mounted inside the chat page it unmounts the moment the user navigates elsewhere, so calls stop ringing anywhere except that one route. It looks like the calls SDK is broken; it is a placement bug.
+
+Remember `CometChatIncomingCallComponent` in the root component's `imports: []`.
+
+## Call buttons
+`<cometchat-message-header>` renders voice and video buttons itself — **check the running app before adding your own.** Suppress with `[hideVoiceCallButton]="true"` / `[hideVideoCallButton]="true"`.
+
+The default is not hardcoded: the header reads `COMETCHAT_GLOBAL_CONFIG` and tracks whether you set the input explicitly, so an app-wide config can hide the buttons even though nothing on the component says so. If they are missing, check the global config before concluding the header does not render them — and if they are present, do not add `<cometchat-call-buttons>` alongside or you get two sets.
+
+Standalone, elsewhere in your UI:
+```html
+<cometchat-call-buttons [user]="activeUser()" [group]="activeGroup()" (error)="onError($event)"></cometchat-call-buttons>
+```
+
+Both call components must be in the consuming component's `imports: []` — omitted, they
+render nothing and never ring. Mount `<cometchat-incoming-call>` at the **app root**, not
+inside a route, or it stops ringing the moment the user navigates away:
+
+```ts
+import { Component, inject, computed } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import {
+  ChatStateService,
+  CometChatCallButtonsComponent,
+  CometChatIncomingCallComponent,
+  CometChatUIKitCalls,
+} from '@cometchat/chat-uikit-angular';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [CommonModule, CometChatCallButtonsComponent, CometChatIncomingCallComponent],
+  template: `
+    <cometchat-incoming-call (callAccepted)="onAccepted($event)"></cometchat-incoming-call>
+    <cometchat-call-buttons [user]="activeUser()" [group]="activeGroup()"></cometchat-call-buttons>
+  `,
+})
+export class AppRootComponent {
+  private readonly chatState = inject(ChatStateService);
+  readonly activeUser = computed(() => this.chatState.activeUser() ?? undefined);
+  readonly activeGroup = computed(() => this.chatState.activeGroup() ?? undefined);
+  // CometChatUIKitCalls is the calls-SDK accessor the kit exposes; it is null until the
+  // SDK has loaded, so never touch it during construction.
+  readonly calls = CometChatUIKitCalls;
+  onAccepted(_call: unknown) { /* route to your ongoing-call screen */ }
+}
+```
+
+## Ongoing and outgoing
+The kit drives these once a call is accepted. Outputs, if you need to react:
+
+| Component | Outputs |
+| --- | --- |
+| `<cometchat-incoming-call>` | `callAccepted` `callDeclined` `error` |
+| `<cometchat-outgoing-call>` | `callCanceled` `error` |
+| `<cometchat-ongoing-call>` | `callEnded` `error` |
+| `<cometchat-call-buttons>` | `error` |
+| `<cometchat-call-logs>` | `itemClick` `callButtonClicked` |
+| `<cometchat-call-bubble>` | `buttonClick` |
+
+`<cometchat-ongoing-call>` takes `[sessionID]` and optionally `[callSettingsBuilder]` / `[isAudioOnly]`. Do not build your own call screen — WebRTC state, permissions and teardown are handled.
+
+## Call history
+> ⚠️ **`<cometchat-call-logs>` HARD-CRASHES if it mounts before the Calls SDK has loaded.**
+> Its `ngOnInit` synchronously runs `new CometChatUIKitCalls.CallLogRequestBuilder()`, but
+> `CometChatUIKitCalls` is `null` until the lazily-loaded Calls SDK resolves — so on a fresh
+> `initFromSettings` app the tab renders an **"OOPS! / Retry"** error state and logs
+> `[CometChatCallLogs] Error: TypeError: Cannot read properties of null (reading 'CallLogRequestBuilder')`.
+> **Retry does NOT recover it.** This is the same "`CometChatUIKitCalls` is null until the SDK
+> has loaded, so never touch it during construction" trap as the standalone accessor above — it
+> just bites INSIDE the kit's own component. **GATE the call-logs surface on the calls-SDK namespace
+> ACTUALLY being populated — not on `callingReady` alone.** Verified live (AUDIT-163):
+> `CometChatUIKit.callingReady` defaults to a **pre-resolved** `Promise.resolve()`, and even after
+> `initCalling()` runs the lazily-loaded `CometChatUIKitCalls` namespace can still be `null` (e.g. the
+> calls chunk never loaded) — so a `callingReady`-ONLY gate STILL crashes. Await `callingReady`, THEN
+> confirm `CometChatUIKitCalls` is non-null before mounting:
+```ts
+// component
+import { CometChatUIKit, CometChatUIKitCalls } from '@cometchat/chat-uikit-angular';
+readonly callsReady = signal(false);
+constructor() {
+  CometChatUIKit.callingReady
+    .then(() => this.callsReady.set(!!CometChatUIKitCalls))   // namespace must be populated, not just "ready"
+    .catch(() => this.callsReady.set(false));
+}
+```
+```html
+<!-- Do NOT mount <cometchat-call-logs> unguarded — it NPEs on CometChatUIKitCalls being null. -->
+<cometchat-call-logs *ngIf="callsReady()" (itemClick)="openCall($event)"></cometchat-call-logs>
+<div *ngIf="!callsReady()">Loading call history…</div>
+```
+> **STOPGAP** (remove once the kit component awaits `getCometChatCalls()` / null-guards
+> `CometChatUIKitCalls` itself — filed as a UIKit bug; the docs page also omits this prerequisite —
+> DOCS-BACKLOG). `isCallingEnabled()` is the sync settings check; **`callingReady` + a `CometChatUIKitCalls`
+> null-check** is what actually guards the mount (`callingReady` alone is NOT enough — proven live).
+
+Also available: `CallLogsService` for headless querying, and `guides/call-log-details` for a detail view.
+
+## Environment requirements
+- **HTTPS or localhost.** `getUserMedia` is blocked on plain HTTP, so calls fail on a LAN IP over http.
+- Microphone/camera permission is a **user-gesture** prompt — trigger it from a click, never on load.
+- `CometChatUIKit.callingReady` is a promise that resolves once calling is initialised; `isCallingEnabled()` is the synchronous check.
+
+## Common pitfalls
+1. **Listener in the chat page** → calls ring only on that route.
+2. **`uiKit.callsSDK` missing from `initFromSettings`** → calling silently off; call buttons render as zero-size empty elements. Installing the package is not enough.
+3. **Calls SDK not installed** → components inert, no error.
+4. **Calling not enabled in the dashboard** → code correct, nothing happens.
+5. **Plain HTTP** → `getUserMedia` blocked.
+6. **Duplicate call buttons** → the header already renders them.
+7. **Hand-rolled call screen** → loses WebRTC teardown; use `<cometchat-ongoing-call>`.
+8. **No zero-height container** — the ongoing-call surface needs real dimensions like any other component.
+
+## Verify it works
+Two browsers, two users, HTTPS or localhost · caller sees outgoing UI, callee's device rings **from any route** · accepting connects audio/video both ways · ending returns both to chat · the call appears in call logs · no console errors.
+
+## Explain what you built (REQUIRED close)
+Tell the developer what changed, naming the files: calling — the packages added, that `uiKit: { callsSDK: {} }` is what switches it on, and where `<cometchat-incoming-call>` is mounted. Flag anything dev-only as dev-only, and say what you did **not** touch — this is additive.
+
+**Then offer these THREE options as a SELECTABLE choice and WAIT for the pick — never auto-continue (`RULES.md` §19):**
+1. **Add another feature** → call-log details, or another grow-set feature from `features.angular-v5.json`. **Never offer an `auto` entry** (reactions, mentions, receipts, typing, media) — those are core in v5 and already on.
+2. **Customize theming** → `cometchat-angular-v5-customization`.
+3. **Test it manually** → do nothing further; hand back so the user runs it.