@cometchat/skills 3.0.0 → 4.0.0

package/skills/cometchat-android-v5-testing/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: cometchat-android-v5-testing
+description: "Testing patterns for CometChat Android — JUnit + Mockito setup, mocking the SDK, Espresso UI tests, E2E with Maestro, and CI integration."
+license: "MIT"
+compatibility: "Android 7.0+; Java 8+; Kotlin 1.8+; com.cometchat:chat-uikit-android:5.x; JUnit 4 (kit sample apps); Mockito/MockK"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat android testing junit espresso maestro mockito ci"
+---
+
+> **Companion skills:** `cometchat-android-v5-core` covers init/login patterns you're testing;
+> `cometchat-android-v5-components` covers component APIs to assert against.
+
+## Purpose
+
+This skill teaches how to write and run tests against a CometChat Android integration. Covers unit tests with JUnit + Mockito/MockK, UI tests with Espresso, E2E with Maestro, and CI integration.
+
+---
+
+## Use this skill when
+
+- "Add tests for my CometChat integration"
+- "How do I mock CometChat in tests?"
+- "Set up E2E testing"
+- "CI pipeline for chat tests"
+
+## Do not use this skill when
+
+- Setting up the integration → use `cometchat-android-v5-core`
+- Diagnosing runtime issues → use `cometchat-android-v5-troubleshooting`
+
+---
+
+## 1. What to test vs what to skip
+
+**Worth testing:**
+- Custom components you wrote (custom bubbles, headers, empty states)
+- Navigation logic triggered by CometChat events (push tap → deep-link)
+- Init/login lifecycle (init before login, already-logged-in skip)
+- Production auth token refresh logic
+- User-ID mapping (your auth system → CometChat UID)
+
+**Skip:**
+- UIKit internals — that's CometChat's responsibility
+- Realtime delivery (A sends, B receives) — requires real servers, flaky
+- Presence/typing indicators — race-prone
+- Snapshot tests of CometChat components — theme changes churn them
+
+**Golden rule:** if the test fails because YOUR code changed, it's valuable. If it fails because the UIKit updated, it's churn.
+
+---
+
+## 2. Toolchain
+
+| Layer | Tool | Why |
+|---|---|---|
+| Unit tests | JUnit 4 + Mockito / MockK | Standard Android unit testing |
+| Component tests | Robolectric | Run Android component tests without emulator |
+| UI tests | Espresso | Android's native UI testing framework |
+| E2E | Maestro | Declarative YAML flows, fast, stable |
+| CI | GitHub Actions / Bitrise | Automated test runs |
+
+---
+
+## 3. Mocking the CometChat SDK
+
+**Java (Mockito):**
+```java
+@RunWith(MockitoJUnitRunner.class)
+public class ChatViewModelTest {
+    @Test
+    public void testLoginCallsInit() {
+        try (MockedStatic<CometChatUIKit> mocked = mockStatic(CometChatUIKit.class)) {
+            mocked.when(CometChatUIKit::getLoggedInUser).thenReturn(null);
+            mocked.when(CometChatUIKit::isSDKInitialized).thenReturn(true);
+
+            // Test your ViewModel or helper that calls login
+            // Verify init was called before login
+        }
+    }
+}
+```
+
+**Kotlin (MockK):**
+```kotlin
+@Test
+fun `already logged in skips login`() {
+    mockkStatic(CometChatUIKit::class)
+    every { CometChatUIKit.getLoggedInUser() } returns mockk<User>()
+
+    // Your code should skip login
+    verify(exactly = 0) { CometChatUIKit.login(any(), any()) }
+
+    unmockkAll()
+}
+```
+
+---
+
+## 4. Espresso UI tests
+
+```java
+@RunWith(AndroidJUnit4.class)
+public class MessagesActivityTest {
+    @Rule
+    public ActivityScenarioRule<MessagesActivity> rule =
+        new ActivityScenarioRule<>(MessagesActivity.class);
+
+    @Test
+    public void messageListIsDisplayed() {
+        onView(withId(R.id.messageList)).check(matches(isDisplayed()));
+    }
+
+    @Test
+    public void composerIsDisplayed() {
+        onView(withId(R.id.composer)).check(matches(isDisplayed()));
+    }
+}
+```
+
+---
+
+## 5. E2E with Maestro
+
+`.maestro/chat-happy-path.yaml`:
+```yaml
+appId: com.yourapp.android
+---
+- launchApp
+- tapOn: "Login"
+- inputText: "cometchat-uid-1"
+- tapOn: "Continue"
+- assertVisible: "Chats"
+- tapOn:
+    id: "conversations"
+    index: 0
+- assertVisible: "Type a message"
+- inputText: "Hello from Maestro"
+- tapOn:
+    id: "send_button"
+- assertVisible: "Hello from Maestro"
+```
+
+Run: `maestro test .maestro/chat-happy-path.yaml`
+
+---
+
+## 6. CI integration
+
+```yaml
+# .github/workflows/test.yml
+name: test
+on: [push, pull_request]
+jobs:
+  unit-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          java-version: 17
+          distribution: temurin
+      - run: ./gradlew test
+```
+
+---
+
+## 7. Common failure modes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `NoClassDefFoundError: CometChat` | SDK not mocked | Add Mockito/MockK mock for static methods |
+| Espresso test hangs | Async CometChat operation | Register `IdlingResource` |
+| Tests pass locally, fail on CI | Emulator not booted | Pin emulator API level in CI |
+| `IllegalStateException: not initialized` | `init()` not called in test setup | Mock `isSDKInitialized()` to return `true` |
+
+---
+
+## Hard rules
+
+- **Mock the SDK in every unit test.** Running real CometChat requires network + servers.
+- **Don't test UIKit internals.** You're responsible for YOUR code.
+- **Skip realtime tests.** They require real servers and produce flaky suites.
+- **Assert on view IDs and state, not pixels.** Theme changes churn pixel assertions.
+- **E2E runs on emulator/device, not JUnit.** Don't test real CometChat flow in unit tests.

package/skills/cometchat-android-v5-theming/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: cometchat-android-v5-theming
+description: "Customize CometChat UI to match your app's design system. Covers CometChatTheme, XML attributes, style classes, dark mode, and color system."
+license: "MIT"
+compatibility: "Android 7.0+; Java 8+; Kotlin 1.8+; com.cometchat:chat-uikit-android:5.x"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat android theming customization branding dark-mode colors styles"
+---
+
+> **Companion skills:** `cometchat-android-v5-core` covers initialization;
+> `cometchat-android-v5-components` provides the component catalog;
+> `cometchat-android-v5-customization` covers deeper component-level overrides.
+
+## Purpose
+
+This skill teaches how to theme CometChat Android UI Kit v5 to match your app's design system. CometChat uses a combination of XML theme attributes, the `CometChatTheme` static class, and per-component style resources.
+
+---
+
+## Use this skill when
+
+- Changing CometChat colors to match brand
+- Customizing fonts or typography
+- Enabling dark mode
+- Applying per-component styles
+- "How do I change the primary color?"
+- "How do I make CometChat match my app theme?"
+
+## Do not use this skill when
+
+- Writing custom message templates → use `cometchat-android-v5-customization`
+- Adding features → use `cometchat-android-v5-features`
+
+---
+
+## 1. How CometChat theming works
+
+CometChat's visual identity is driven by XML theme attributes defined in `attrs.xml` files. Every `CometChat*` component reads these attributes from the current theme. To override: define the attributes in your app's theme.
+
+### The CometChatTheme class
+
+`CometChatTheme` is a static utility class that provides programmatic access to theme colors. It reads from XML theme attributes and supports runtime overrides.
+
+**Key static methods:**
+
+| Method | Description |
+|---|---|
+| `setPrimaryColor(int)` | Override primary color at runtime |
+| `getPrimaryColor(Context)` | Get current primary color |
+| `getExtendedPrimaryColor50(Context)` through `getExtendedPrimaryColor900(Context)` | Get extended primary color shades (auto-generated from primary) |
+| `getBackgroundColor1(Context)` | Primary background color |
+| `getTextColorPrimary(Context)` | Primary text color |
+| `getTextColorSecondary(Context)` | Secondary text color |
+| `getIconTintHighlight(Context)` | Highlighted icon tint |
+| `getIconTintSecondary(Context)` | Secondary icon tint |
+
+### Setting primary color programmatically
+
+**Java:**
+```java
+CometChatTheme.setPrimaryColor(Color.parseColor("#6C63FF"));
+```
+
+**Kotlin:**
+```kotlin
+CometChatTheme.setPrimaryColor(Color.parseColor("#6C63FF"))
+```
+
+This must be called before any CometChat component is inflated. The extended color shades (50–900) are auto-generated by blending the primary color with white (light mode) or black (dark mode).
+
+---
+
+## 2. XML theme attributes
+
+Override CometChat colors in your app's `themes.xml`:
+
+```xml
+<style name="AppTheme" parent="CometChatTheme.DayNight">
+    <!-- CometChat primary color -->
+    <item name="cometchatPrimaryColor">#6C63FF</item>
+
+    <!-- Background colors -->
+    <item name="cometchatBackgroundColor1">#FFFFFF</item>
+    <item name="cometchatBackgroundColor2">#F5F5F5</item>
+
+    <!-- Text colors -->
+    <item name="cometchatTextColorPrimary">#141414</item>
+    <item name="cometchatTextColorSecondary">#727272</item>
+
+    <!-- Extended primary shades (optional — auto-generated if not set) -->
+    <item name="cometchatExtendedPrimaryColor50">#F0EEFF</item>
+    <item name="cometchatExtendedPrimaryColor100">#D9D5FF</item>
+</style>
+```
+
+---
+
+## 3. Per-component styles
+
+Each component has its own style attribute that can be overridden in your theme. The naming convention is `cometchat<ComponentName>Style`.
+
+| Component | Style attribute | Example |
+|---|---|---|
+| `CometChatConversations` | `cometchatConversationsStyle` | `@style/CustomConversationsStyle` |
+| `CometChatMessageList` | `cometchatMessageListStyle` | `@style/CustomMessageListStyle` |
+| `CometChatMessageComposer` | `cometchatMessageComposerStyle` | `@style/CustomComposerStyle` |
+| `CometChatMessageHeader` | `cometchatMessageHeaderStyle` | `@style/CustomHeaderStyle` |
+| `CometChatUsers` | `cometchatUsersStyle` | `@style/CustomUsersStyle` |
+| `CometChatGroups` | `cometchatGroupsStyle` | `@style/CustomGroupsStyle` |
+| `CometChatAvatar` | `cometchatAvatarStyle` | `@style/CustomAvatarStyle` |
+| `CometChatBadge` | `cometchatBadgeStyle` | `@style/CustomBadgeStyle` |
+| `CometChatStatusIndicator` | `cometchatStatusIndicatorStyle` | `@style/CustomStatusStyle` |
+| `CometChatMessageReceipt` | `cometchatMessageReceiptStyle` | `@style/CustomReceiptStyle` |
+
+---
+
+## 4. Programmatic styling
+
+Every component exposes setter methods for colors, text appearances, and drawables:
+
+**Java:**
+```java
+CometChatConversations conversations = findViewById(R.id.conversations);
+conversations.setBackgroundColor(Color.WHITE);
+conversations.setTitleTextColor(Color.BLACK);
+conversations.setTitleTextAppearance(R.style.MyTitleStyle);
+conversations.setSeparatorColor(Color.LTGRAY);
+conversations.setAvatarStyle(R.style.MyAvatarStyle);
+conversations.setStatusIndicatorStyle(R.style.MyStatusStyle);
+```
+
+---
+
+## 5. Dark mode
+
+CometChat respects Android's `DayNight` theme. Define separate values in `values-night/themes.xml`:
+
+```xml
+<!-- values/themes.xml (light) -->
+<style name="AppTheme" parent="CometChatTheme.DayNight">
+    <item name="cometchatPrimaryColor">#6C63FF</item>
+    <item name="cometchatBackgroundColor1">#FFFFFF</item>
+    <item name="cometchatTextColorPrimary">#141414</item>
+</style>
+
+<!-- values-night/themes.xml (dark) -->
+<style name="AppTheme" parent="CometChatTheme.DayNight">
+    <item name="cometchatPrimaryColor">#7B73FF</item>
+    <item name="cometchatBackgroundColor1">#1A1A2E</item>
+    <item name="cometchatTextColorPrimary">#E0E0E0</item>
+</style>
+```
+
+The `CometChatTheme` class auto-detects the current night mode and adjusts extended color shades accordingly.
+
+---
+
+## Hard rules
+
+- **Set primary color BEFORE inflating components.** `CometChatTheme.setPrimaryColor()` must be called before `setContentView()` or component inflation.
+- **Use XML theme attributes for global overrides.** Per-component setters are for fine-tuning.
+- **Extended primary shades are auto-generated.** Only override them if you need exact brand colors at each shade level.
+- **Dark mode uses `values-night/`.** Follow Android's standard `DayNight` theme pattern.

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

@@ -0,0 +1,73 @@
+---
+name: cometchat-android-v5-troubleshooting
+description: "Diagnose and fix problems with a CometChat Android integration. Gradle errors, runtime crashes, rendering issues, and version compatibility."
+license: "MIT"
+compatibility: "Android 7.0+; Java 8+; Kotlin 1.8+; com.cometchat:chat-uikit-android:5.x"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory, grepSearch"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat android troubleshooting fix diagnose errors crashes gradle proguard"
+---
+
+> **Companion skills:** `cometchat-android-v5-core` covers correct init/login patterns;
+> `cometchat-android-v5-production` covers ProGuard rules.
+
+## Purpose
+
+This skill teaches how to diagnose CometChat Android integration problems systematically. It covers Gradle build errors, runtime crashes, rendering issues, and version compatibility.
+
+---
+
+## Use this skill when
+
+- "CometChat isn't working"
+- "I'm getting a build error"
+- "The chat screen is blank"
+- "Messages aren't loading"
+- Gradle sync failures
+- Runtime crashes with CometChat in the stack trace
+
+## Do not use this skill when
+
+- Setting up a new integration → use `cometchat-android-v5-core`
+- Customizing appearance → use `cometchat-android-v5-theming`
+
+---
+
+## 1. Common issues
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `Could not resolve com.cometchat:chat-uikit-android` | Missing Maven repo | Add `maven { url "https://dl.cloudsmith.io/public/cometchat/cometchat/maven/" }` to repositories |
+| `Duplicate class com.cometchat.*` | Multiple CometChat versions | Check dependency tree: `./gradlew app:dependencies` |
+| Blank conversation list | Not logged in, or no conversations exist | Verify `getLoggedInUser() != null`. Send a test message from dashboard. |
+| `CometChatException: ERR - Authentication null` | `init()` not called or failed | Call `init()` before `login()`. Check `isSDKInitialized()`. |
+| `CometChatException: appIdErr` | App ID not set in UIKitSettings | Verify `setAppId()` in UIKitSettingsBuilder |
+| Components show but no data | Login succeeded but wrong region | Verify region matches dashboard: `"us"`, `"eu"`, `"in"` |
+| `ClassNotFoundException` in release build | ProGuard stripping CometChat classes | Add `-keep class com.cometchat.** { *; }` to proguard-rules.pro |
+| `UnsupportedOperationException: Failed to resolve attribute` when inflating CometChat views | App theme inherits `Theme.AppCompat.*` or `Theme.Material3.*` — the kit's attrs are resolved against Material 2 (`CometChatTheme.DayNight` itself parents on `Theme.MaterialComponents.DayNight.NoActionBar`) | Change app theme parent to `CometChatTheme.DayNight` |
+| `NetworkOnMainThreadException` | Calling CometChat sync methods on main thread | Use callbacks (all CometChat methods are async) |
+| `minSdkVersion 21` error | CometChat requires API 24+ | Set `minSdkVersion 24` in build.gradle |
+| Message list shows wrong messages | `setUser()`/`setGroup()` called with wrong object | Verify UID/GUID matches the intended conversation |
+| Calling buttons not showing | Calling SDK not added | Add `com.cometchat:calls-sdk-android:4.+` dependency |
+| `java.lang.NoSuchMethodError` | Version mismatch between UI Kit and Chat SDK | Use compatible versions — UI Kit 5.x requires Chat SDK 4.x |
+
+---
+
+## 2. Diagnostic steps
+
+1. **Check init:** `CometChatUIKit.isSDKInitialized()` — must be `true`
+2. **Check login:** `CometChatUIKit.getLoggedInUser()` — must not be `null`
+3. **Check Gradle:** `./gradlew app:dependencies | grep cometchat` — verify versions
+4. **Check manifest:** Verify `INTERNET` permission
+5. **Check region:** Must match dashboard exactly
+6. **Check logs:** Filter logcat for `CometChat` tag
+
+---
+
+## Hard rules
+
+- **Always check init + login first.** 90% of "it's not working" issues are init/login failures.
+- **Never guess at the cause.** Check logcat, check the dependency tree, check the dashboard.
+- **ProGuard is the #1 release-build issue.** Always add keep rules before the first release build.

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

@@ -0,0 +1,107 @@
+---
+name: cometchat-android-v6
+description: "Entry-point dispatcher for CometChat Android UIKit v6 — routes to the correct skill based on project stack and task"
+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"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat, android, uikit, kotlin, jetpack-compose, dispatcher"
+---
+
+> **Companion skills:** cometchat-android-v6-core, cometchat-android-v6-events, cometchat-android-v6-kotlin-components, cometchat-android-v6-compose-components, cometchat-android-v6-kotlin-theming, cometchat-android-v6-compose-theming, cometchat-android-v6-kotlin-customization, cometchat-android-v6-compose-customization, cometchat-android-v6-kotlin-placement, cometchat-android-v6-compose-placement, cometchat-android-v6-builder-settings, cometchat-android-v6-features, cometchat-android-v6-extensions, cometchat-android-v6-push, cometchat-android-v6-production, cometchat-android-v6-troubleshooting, cometchat-android-v6-testing
+
+## Purpose
+
+This is the entry-point skill for the CometChat Android UIKit v6. It detects the project's UI stack (Kotlin Views, Jetpack Compose, or both) and routes to the correct specialized skill.
+
+## Use this skill when
+
+- The user mentions "CometChat" in an Android/Kotlin project
+- The user wants to add chat, messaging, or calling features to an Android app
+- You need to determine which CometChat skill to activate
+- The user asks a general CometChat question without specifying a stack
+
+## Do not use this skill when
+
+- You already know which specific skill to use (go directly to it)
+- The project is React, React Native, iOS, Flutter, or Web (this skill is Android-only)
+
+## 1. Project Detection
+
+Detect the UI stack by inspecting the project's Gradle files:
+
+```kotlin
+// Check build.gradle.kts or build.gradle for dependencies:
+
+// Jetpack Compose stack
+implementation("com.cometchat:chatuikit-compose-android:6.x")
+
+// Kotlin Views stack
+implementation("com.cometchat:chatuikit-kotlin-android:6.x")
+
+// Core only (shared module, no UI)
+implementation("com.cometchat:chatuikit-core-android:6.x")
+```
+
+Also check for module includes in `settings.gradle`:
+- `:chatuikit-compose` → Compose stack
+- `:chatuikit-kotlin` → Kotlin Views stack
+- `:chatuikit-core` → Core module
+
+## 2. Architecture Overview
+
+v6 uses a 3-module architecture:
+
+| Module | Package | Purpose |
+|---|---|---|
+| `chatuikit-core` | `com.cometchat.uikit.core` | Shared: init, login, ViewModels, events, data layer |
+| `chatuikit-kotlin` | `com.cometchat.uikit.kotlin` | Kotlin Views UI: custom Views, RecyclerView, XML themes |
+| `chatuikit-compose` | `com.cometchat.uikit.compose` | Compose UI: @Composable functions, CompositionLocal themes |
+
+Both UI modules depend on `chatuikit-core`. The core module holds all business logic.
+
+## 3. Routing Table
+
+| User wants to... | Route to skill |
+|---|---|
+| Add CometChat to a project / Gradle setup | `cometchat-android-v6-core` |
+| Initialize the SDK / login / logout | `cometchat-android-v6-core` |
+| Configure UIKitSettings in detail | `cometchat-android-v6-builder-settings` |
+| Use a component (Kotlin Views) | `cometchat-android-v6-kotlin-components` |
+| Use a component (Jetpack Compose) | `cometchat-android-v6-compose-components` |
+| Place components in Activities/Fragments | `cometchat-android-v6-kotlin-placement` |
+| Place components in Compose screens | `cometchat-android-v6-compose-placement` |
+| Change colors/fonts (Kotlin Views) | `cometchat-android-v6-kotlin-theming` |
+| Change colors/fonts (Compose) | `cometchat-android-v6-compose-theming` |
+| Customize bubble rendering (Kotlin Views) | `cometchat-android-v6-kotlin-customization` |
+| Customize bubble rendering (Compose) | `cometchat-android-v6-compose-customization` |
+| Use AI features, reactions, polls, stickers | `cometchat-android-v6-features` |
+| Extend with custom DataSources / message types | `cometchat-android-v6-extensions` |
+| Listen to chat/call/user events | `cometchat-android-v6-events` |
+| Add push notifications / FCM / VoIP | `cometchat-android-v6-push` |
+| Prepare for production release | `cometchat-android-v6-production` |
+| Debug issues | `cometchat-android-v6-troubleshooting` |
+| Write tests | `cometchat-android-v6-testing` |
+
+## 4. Quick-Start Decision Tree
+
+1. **New project?** → `cometchat-android-v6-core` (Gradle setup + init)
+2. **Which UI stack?**
+   - Jetpack Compose → `cometchat-compose-*` skills
+   - Kotlin Views (XML layouts) → `cometchat-kotlin-*` skills
+   - Both → Use the appropriate stack-specific skill for each task
+3. **What task?**
+   - Show a component → `*-components`
+   - Style/theme → `*-theming`
+   - Customize bubbles → `*-customization`
+   - Place in navigation → `*-placement`
+
+## Hard rules
+
+- ALWAYS detect the project stack before routing to a stack-specific skill
+- NEVER mix Kotlin Views APIs with Compose APIs in the same code example
+- NEVER reference v5 Java UIKit APIs — v6 is Kotlin-only
+- When both stacks are present, ask the user which stack they're working with before proceeding
+- Route to the most specific skill possible — don't try to answer from this dispatcher skill

package/skills/cometchat-android-v6-builder-settings/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: cometchat-android-v6-builder-settings
+description: "CometChat Android UIKit v6 UIKitSettings configuration — all builder options for SDK init, presence, calling, and host overrides"
+license: "MIT"
+compatibility: "Android 9.0+ (API 28); Kotlin 1.9+; com.cometchat:chatuikit-core-android:6.x"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat, android, settings, builder, configuration, calling"
+---
+
+> **Companion skills:** cometchat-android-v6-core (init/login), cometchat-android-v6-push (FCM/VoIP)
+
+## Purpose
+
+Detailed reference for `UIKitSettings.UIKitSettingsBuilder` — all configuration options for initializing the CometChat SDK, including presence subscriptions, calling features, and host overrides.
+
+## Use this skill when
+
+- Configuring presence subscription types (all users, roles, friends)
+- Enabling calling features and configuring `CallSettingsBuilder`
+- Overriding admin or client host URLs
+- Controlling socket connection behavior
+- Understanding the full `UIKitSettingsBuilder` API
+
+## Do not use this skill when
+
+- Just doing basic init/login (use `cometchat-android-v6-core` for quick setup)
+- Working with UI components or theming
+
+## 1. UIKitSettingsBuilder — Complete API
+
+```kotlin
+import com.cometchat.uikit.core.UIKitSettings
+
+val settings = UIKitSettings.UIKitSettingsBuilder()
+
+    // Required
+    .setAppId("APP_ID")                          // CometChat App ID
+    .setRegion("us")                             // "us" or "eu"
+
+    // Authentication (dev only — use token auth in production)
+    .setAuthKey("AUTH_KEY")                      // Auth key from dashboard
+
+    // Presence subscriptions
+    .subscribePresenceForAllUsers()              // Subscribe to all users' presence
+    .subscribePresenceForRoles(listOf("admin"))  // Subscribe by roles
+    .subscribePresenceForFriends()               // Subscribe to friends' presence
+
+    // Socket connection
+    .setAutoEstablishSocketConnection(true)      // Auto-connect (default: true)
+
+    // Calling
+    .setEnableCalling(true)                      // Auto-init CometChatCalls SDK (default: false)
+    .setCallSettingsBuilder(callSettingsBuilder)  // Custom call config (optional)
+
+    // Host overrides (advanced — for on-premise deployments)
+    .overrideAdminHost("https://custom-admin.example.com")
+    .overrideClientHost("https://custom-client.example.com")
+
+    .build()
+```
+
+## 2. Presence Subscription Types
+
+Only one subscription type is active at a time. The last one set wins.
+
+| Method | Subscription Type | Use Case |
+|---|---|---|
+| (none) | `"NONE"` | No presence updates (default) |
+| `subscribePresenceForAllUsers()` | `"ALL_USERS"` | Small apps where you want all online statuses |
+| `subscribePresenceForRoles(roles)` | `"ROLES"` | Subscribe to specific user roles |
+| `subscribePresenceForFriends()` | `"FRIENDS"` | Social apps with friend lists |
+
+## 3. Calling Configuration
+
+When `setEnableCalling(true)` is set, `CometChatUIKit.init()` automatically initializes the CometChatCalls SDK after the Chat SDK succeeds:
+
+```kotlin
+// Basic calling setup
+val settings = UIKitSettings.UIKitSettingsBuilder()
+    .setAppId("APP_ID")
+    .setRegion("us")
+    .setAuthKey("AUTH_KEY")
+    .setEnableCalling(true)
+    .build()
+```
+
+For custom call settings:
+
+```kotlin
+import com.cometchat.calls.core.CometChatCalls
+
+val callSettingsBuilder = CometChatCalls.CallSettingsBuilder(context, null)
+    .setDefaultAudioMode("SPEAKER")
+    .startWithVideoMuted(true)
+
+val settings = UIKitSettings.UIKitSettingsBuilder()
+    .setAppId("APP_ID")
+    .setRegion("us")
+    .setAuthKey("AUTH_KEY")
+    .setEnableCalling(true)
+    .setCallSettingsBuilder(callSettingsBuilder)
+    .build()
+```
+
+After init, retrieve the stored builder:
+
+```kotlin
+val builder: CometChatCalls.CallSettingsBuilder? = CometChatUIKit.getCallSettingsBuilder()
+```
+
+## 4. Checking Initialization State
+
+```kotlin
+// Chat SDK initialized?
+CometChatUIKit.isSDKInitialized()
+
+// Calls SDK initialized? (only true if enableCalling was true AND init succeeded)
+CometChatUIKit.isCallsSDKInitialized()
+```
+
+## 5. Application-Level Init Pattern
+
+From `master-app-jetpack`, the recommended pattern separates SDK init from Calls SDK init:
+
+```kotlin
+class MyApplication : Application() {
+    fun onSDKInitialized() {
+        // Called after CometChatUIKit.init() succeeds
+        // CometChatCalls is auto-initialized if enableCalling = true
+        // Register call listeners here
+        addCallListener()
+    }
+}
+```
+
+## Hard rules
+
+- NEVER set both `subscribePresenceForAllUsers()` and `subscribePresenceForRoles()` — only the last one takes effect
+- NEVER use `setAuthKey()` in production — use `loginWithAuthToken()` instead
+- `setEnableCalling(true)` requires the CometChatCalls SDK dependency in your Gradle file
+- If CometChatCalls init fails, the Chat SDK still reports success — check `isCallsSDKInitialized()` separately
+- `overrideAdminHost()` and `overrideClientHost()` are for on-premise deployments only — do not use with cloud-hosted CometChat