@cometchat/skills 3.0.0 → 4.0.0

package/skills/cometchat-astro-patterns/SKILL.md

@@ -270,8 +270,8 @@ function ChatContent() {
           <>
             {selectedUser && <CometChatMessageHeader user={selectedUser} />}
             {selectedGroup && <CometChatMessageHeader group={selectedGroup} />}
-            {selectedUser && <CometChatMessageList user={selectedUser} />}
-            {selectedGroup && <CometChatMessageList group={selectedGroup} />}
+            {selectedUser && <CometChatMessageList user={selectedUser} hideReplyInThreadOption={true} />}
+            {selectedGroup && <CometChatMessageList group={selectedGroup} hideReplyInThreadOption={true} />}
             {selectedUser && <CometChatMessageComposer user={selectedUser} />}
             {selectedGroup && <CometChatMessageComposer group={selectedGroup} />}
           </>
@@ -352,7 +352,7 @@ function DrawerContent({ targetUserId }: { targetUserId: string }) {
     <>
       <CometChatMessageHeader user={user} />
       <div style={{ flex: 1, overflow: "hidden" }}>
-        <CometChatMessageList user={user} />
+        <CometChatMessageList user={user} hideReplyInThreadOption={true} />
       </div>
       <CometChatMessageComposer user={user} />
     </>

package/skills/cometchat-components/SKILL.md

@@ -124,6 +124,8 @@ A text input with send button, attachment options, and emoji support. Sends mess
 
 A rich-text variant of the message composer with formatting toolbar (bold, italic, code, etc.). Same props as CometChatMessageComposer.
 
+**Prefer this for new integrations.** The v6 sample app uses `CometChatCompactMessageComposer` everywhere — rich-text formatting is the modern default. Both work; reach for `CometChatMessageComposer` (the basic variant) only if you have a specific reason to skip the formatting toolbar (e.g., a stripped-down marketplace ping where plain text is the entire UX).
+
 **Key props:**
 | Prop | Type | Description |
 |---|---|---|
@@ -192,6 +194,15 @@ Full-featured dual-scope search: searches across conversations AND messages with
 
 **Works with:** CometChatConversations (replaces the list when search is active)
 
+> **Hard rule — never roll your own search.** Any request involving
+> "search", "find messages", "search conversations", or "search across
+> conversations" MUST use `<CometChatSearch>` (or `showSearchBar={true}`
+> + `onSearchBarClicked` on `CometChatConversations` to swap into
+> `<CometChatSearch>` on click). Do NOT build custom `<input type="search">`
+> bars, hand-rolled result lists, or filter UIs — they bypass the SDK's
+> pagination, highlighting, and dual-scope (conversations + messages)
+> matching that ship with the built-in component.
+
 ---
 
 ### CometChatThreadHeader

package/skills/cometchat-core/SKILL.md

@@ -140,19 +140,24 @@ Call `ensureLoggedIn()` from the provider / effect instead of `CometChatUIKit.lo
 
 When your integration code needs the current user's UID (for example, to decide which conversation to target, or to filter by sender), **always fetch it from the SDK — never hardcode a UID like `"cometchat-uid-1"`**.
 
-Two getters, for different contexts:
+Two getters, for different contexts. **Default to the sync version** — it matches the v6 sample app and works for almost all app code, because by the time UI components render, the kit's init + login flow is already complete:
 
 ```typescript
-// Async — preferred for app logic, guaranteed correct after init completes
-const me = await CometChatUIKit.getLoggedinUser();
-const myUid = me?.getUid();
-
-// Sync — use inside render paths where you already know init is done
+// ✓ Preferred — sync, returns User | null directly. Use this in app code.
 import { CometChatUIKitLoginListener } from "@cometchat/chat-uikit-react";
 const me = CometChatUIKitLoginListener.getLoggedInUser();  // note capital `I` in `InUser`
 const myUid = me?.getUid();
+
+// Fallback — async, for the bootstrap path where init may not be complete
+// (e.g., inside the provider's init effect, or before the first login resolves).
+const me = await CometChatUIKit.getLoggedinUser();
+const myUid = me?.getUid();
 ```
 
+The sync `CometChatUIKitLoginListener.getLoggedInUser()` is the right call from any component that mounts AFTER login completes — which is virtually all of them, since the dispatcher's recipes put login on a dedicated route or in the provider's init effect that gates rendering. Reach for the async `CometChatUIKit.getLoggedinUser()` only when you're inside that init effect itself.
+
+**Casing matters.** Note `getLogged**In**User` (capital `I`) on the LoginListener vs `getLogged**in**User` (lowercase `i`) on `CometChatUIKit` — both casings exist in the kit, they're different methods.
+
 Hardcoding `"cometchat-uid-1"` only works in the dev mode login call (`CometChatUIKit.login("cometchat-uid-1")`) because you're *choosing* who to log in as. Once logged in, the getters are the source of truth — useful when the logged-in user comes from production auth (a real user ID, not a test UID), or when the user logs out and logs in as someone else.
 
 ### Production mode

package/skills/cometchat-customization/references/component-catalog.md

@@ -226,7 +226,7 @@ docs MCP, just use the component listed here.
 | "click handler on item / message" | `onItemClick` / `onMessageClick` / `onBack` / `onSearchBarClicked` (prop) | |
 | "hide / disable a feature" | `disable*` boolean props on the relevant component (prop) | e.g. `disableReactions`, `disableTyping`, `disableMentions` |
 | "mentions in composer" | `CometChatMentionsFormatter` (A) | Already wired into `CometChatMessageComposer` by default |
-| "AI smart replies" / "AI assistant" | `CometChatAIAssistantChat` (A) | Requires dashboard toggle + extension |
+| "AI smart replies" / "AI assistant" | `CometChatAIAssistantChat` (A) | Requires `cometchat apply-feature smart-replies --openai-key sk-...` (one-shot via API) |
 | "top-level layout" / "home screen" | `CometChatHome/CometChatHome.tsx` (B) | The canonical three-column layout |
 | "login screen" | `CometChatLogin/` (B) | Sample app pattern |
 | "avatar" | `CometChatAvatar` (A) | Used inside many components; also usable standalone |

package/skills/cometchat-features/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cometchat-features
-description: Add features (calls, reactions, polls, file sharing, presence, etc.) to an already-integrated CometChat project. Routes to the right sub-flow based on feature type — default features (already enabled), dashboard-toggle features (extensions + AI), package-install features (calls), or component-swap features (rich text).
+description: Add features (calls, reactions, polls, file sharing, presence, etc.) to an already-integrated CometChat project. Routes to the right sub-flow based on feature type — default (already enabled), extension (API toggle), ai-feature (API toggle + OpenAI key), dashboard-only (third-party config), package-install (calls), or component-swap (rich text).
 license: "MIT"
 compatibility: "Node.js >=18; @cometchat/chat-uikit-react ^6; integration must already be applied"
 allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
@@ -19,9 +19,10 @@ metadata:
 
 This skill teaches Claude how CometChat features are structured and
 what work is actually required to enable each one. Most features require
-**zero code** — they are either already built into the UI Kit, enabled
-via a dashboard toggle, or activated by a single npm install.
-Understanding which type a feature is prevents unnecessary work.
+**zero code** — they are either already built into the UI Kit, toggled
+via the `cometchat apply-feature` CLI (which hits the dashboard API),
+or activated by a single npm install. Understanding which type a feature
+is prevents unnecessary work.
 
 ---
 
@@ -53,35 +54,48 @@ first to create the integration.
 
 ## 3. Why features fall into each type
 
-CometChat features split into 4 types based on their architecture:
-
-- **Type 1 — Default (compiled-in):** These are shipped inside the UI
-  Kit component bundle unconditionally. CometChat builds reactions,
-  typing indicators, mentions, etc. into `CometChatMessageList` and
-  `CometChatMessageComposer` at compile time. The feature is always
-  present; the only question is whether the prop that surfaces it is
-  enabled. No code or dashboard changes needed.
-
-- **Type 2 — Dashboard-toggle (backend extensions):** These are
-  backend services hosted by CometChat's infrastructure. The UI Kit
-  polls which extensions are enabled via the app's init response. When
-  you flip the dashboard toggle, the backend returns a different
-  feature flag, and the UI Kit renders the corresponding UI
-  automatically. No client code change is needed — the rendering logic
-  is already in the UI Kit, just gated on the flag.
-
-- **Type 3 — Package-install (separate SDK):** Voice/video calling
-  requires a separate WebRTC SDK (`@cometchat/calls-sdk-javascript`)
-  because it links against browser media APIs that would bloat every
-  integration if bundled unconditionally. Once installed, the UI Kit
-  detects it via dynamic import and enables the call UI.
-
-- **Type 4 — Component-swap (variant component):** Some features
-  require a different component variant because the base component has
-  a hard-coded behavior that can't be toggled via props. The CLI does
-  a safe word-boundary replace of the component name in your owned
-  files. If CometChat adds new variant components in future SDK
-  releases, they will follow this same pattern.
+CometChat features split into six types based on what work is actually
+needed to enable each one:
+
+- **default (compiled-in):** Shipped inside the UI Kit component bundle
+  unconditionally. CometChat builds reactions, typing indicators,
+  mentions, etc. into `CometChatMessageList` and `CometChatMessageComposer`
+  at compile time. The feature is always present; the only question is
+  whether the prop that surfaces it is enabled. No action needed.
+
+- **extension (backend boolean toggle):** Pure on/off backend extension.
+  The CLI's `apply-feature` command flips the toggle via the same REST
+  API the dashboard UI uses (`POST /apps/{id}/extensions`), so no
+  browser visit required. Once enabled, the UI Kit renders the matching
+  UI automatically. Examples: polls, link-preview, voice-transcription,
+  message-translation, stickers.
+
+- **ai-feature (backend AI toggle + OpenAI key):** Same API path as
+  extensions but split out because the AI feature requires an OpenAI
+  API key on the app's AI settings (`PUT /apps/{id}/ai/settings`)
+  before the toggle (`POST /apps/{id}/features/ai.{key}/enabled`)
+  succeeds. The CLI handles both calls in one invocation when given
+  `--openai-key sk-…`. Examples: smart-replies, conversation-summary,
+  conversation-starter.
+
+- **dashboard-only (third-party config):** Requires entering config
+  the user has to fetch themselves — third-party API keys (Giphy,
+  Stipop, Tenor), webhooks (Chatwoot), or multi-field choices
+  (disappearing-messages interval, message-shortcuts list). The CLI
+  cannot automate these; the skill prints the dashboard path and
+  stops.
+
+- **package-install (separate SDK):** Voice/video calling requires
+  `@cometchat/calls-sdk-javascript` because it links against browser
+  media APIs that would bloat every integration if bundled unconditionally.
+  Once installed, the UI Kit detects it via dynamic import.
+
+- **component-swap (variant component):** Replaces one UI Kit component
+  with a drop-in variant whose default behavior differs (e.g.
+  `CometChatCompactMessageComposer` enables rich text by default).
+  The CLI does a safe word-boundary replace in `state.files_owned`.
+  Requires `cometchat apply` to have run (i.e. web/RN integrations
+  only — native cohorts can't use this path).
 
 ---
 
@@ -110,15 +124,23 @@ component:
 For these: query the docs MCP for the feature's component/usage docs, show
 the user where it is in their integration. **No code changes needed.**
 
-### Type 2 — Dashboard-toggle features (~40+, no code needed)
+### Type 2a — Extensions (pure boolean, CLI-toggleable)
 
-These require flipping a toggle in the [CometChat Dashboard](https://app.cometchat.com).
-Once enabled, the UI Kit auto-integrates them. **No code changes needed.**
+These are backend extensions enabled by a single API call (`POST /apps/{id}/extensions`).
+Use the CLI — no browser visit required:
+
+```bash
+cometchat apply-feature <id>
+```
+
+For native cohorts (iOS / Android / Flutter / Angular) where there's no
+`.cometchat/state.json`, pass `--app-id` explicitly:
 
-> **Note:** The dashboard features page also shows the Type 1 features
-> (Instant Messaging, Reactions, Mentions, etc.) as always-on toggles
-> at the top. Those are already enabled — no action needed. The
-> features below are the ones that actually require toggling on.
+```bash
+cometchat apply-feature <id> --app-id <your-app-id>
+```
+
+Once enabled, the UI Kit auto-integrates them. **No code changes needed.**
 
 > **Note:** Conversation and Advanced Search has its own toggle on the
 > Features page. It is on by default but can be disabled. If a user
@@ -150,30 +172,55 @@ Email Notification, Push Notification, SMS Notification
 **Extensions — Customer Support:**
 Chatwoot, Intercom
 
-**Smart Chat Features (AI):**
-Conversation Starter, Smart Replies, Conversation Summary
-(AI features are fetched dynamically from the API — the exact list
-depends on your plan and backend configuration.)
-
-**Exact dashboard path (give this to the user verbatim):**
-
-> **For most features (User Experience, User Engagement, Collaboration, Security, AI):**
-> 1. Open https://app.cometchat.com
-> 2. Select your app
-> 3. In the left sidebar: **Chat & Messaging** → **Features**
-> 4. Find the feature and flip its **Status** toggle to ON
-> 5. Some extensions have a settings icon — click it if the feature
->    needs configuration (e.g. API keys for Giphy)
-> 6. Changes take effect immediately — refresh the chat in the browser
->
-> **For Moderation and Notification extensions:**
-> These are NOT on the Features page. Navigate to:
-> **Left sidebar → Extensions** (the separate Extensions page)
-> Find the extension and enable it there.
-
-After enabling, run `cometchat verify` to ensure the existing
-integration still passes. No code changes are needed — the UI Kit
-picks up enabled features automatically.
+### Type 2b — AI features (CLI-toggleable, OpenAI key required)
+
+`smart-replies`, `conversation-summary`, `conversation-starter`. These
+need an OpenAI API key on the app's AI settings before the toggle
+succeeds. The CLI does both calls in one invocation:
+
+```bash
+cometchat apply-feature smart-replies --openai-key sk-...
+# native:
+cometchat apply-feature smart-replies --app-id <id> --openai-key sk-...
+```
+
+After the first AI feature is enabled the key is stored on the app, so
+subsequent ai-feature applies don't need `--openai-key` repeated.
+
+Get an OpenAI key: https://platform.openai.com/api-keys
+
+### Type 2c — Dashboard-only (third-party config required)
+
+These extensions require config the user has to provide themselves
+(third-party API keys / webhooks / multi-field setup) — `apply-feature`
+returns `manual-action-required` and prints the dashboard path. The
+CLI cannot automate these:
+
+- **Third-party API keys:** Giphy, Stipop, Tenor, Intercom
+- **Webhooks:** Chatwoot
+- **Multi-field config:** Message Shortcuts (shortcut list), Disappearing Messages (interval)
+
+Manual flow for these:
+1. https://app.cometchat.com → select your app
+2. Sidebar → Extensions (or Chat & Messaging → Features for
+   Disappearing Messages)
+3. Find the extension, enter the third-party config, toggle ON
+
+### Moderation and Notification extensions
+
+Live on a separate Extensions page (not Features). Both currently
+require dashboard navigation (Phase 1 didn't cover moderation rules):
+
+- **Moderation:** Data Masking, Image Moderation, Profanity Filter,
+  Sentiment Analysis, XSS Filter, Human Moderation, Report User,
+  Slow Mode, Virus/Malware Scanner
+- **Notifications:** Email, Push, SMS
+
+> Sidebar → **Extensions** → find extension → configure + enable.
+
+After enabling any feature, run `cometchat verify` to ensure the
+existing integration still passes. No code changes are needed — the
+UI Kit picks up enabled features automatically.
 
 ### Type 3 — Package-install features (4, calls)
 
@@ -275,7 +322,14 @@ export function CustomCallUI({ targetUser }: { targetUser: CometChat.User }) {
 
 ### AI smart replies
 
-Smart replies is a dashboard-toggle feature (Type 2). After enabling it in the dashboard (Extensions → Smart Replies → Toggle on), **no code changes are required** — the `CometChatMessageComposer` automatically renders suggested replies as chips above the input when there's a recent incoming message.
+Smart replies is an `ai-feature`. Enable with one CLI call (the first time also sets the OpenAI key on the app):
+
+```bash
+cometchat apply-feature smart-replies --openai-key sk-...
+# native cohorts: add --app-id <your-app-id>
+```
+
+**No code changes are required** — the `CometChatMessageComposer` automatically renders suggested replies as chips above the input when there's a recent incoming message.
 
 For a custom UI — e.g. showing smart replies inline instead of above the composer, or only for certain conversation types — you read the extension data from the incoming message and render your own chips:
 
@@ -366,9 +420,10 @@ this skill. It's the canonical source for:
    "I need the CometChat docs MCP to walk you through this feature.
    Install it with `claude mcp add --transport http cometchat-docs
    https://www.cometchat.com/docs/mcp` and re-run."
-3. **Use the dashboard path from this skill** (Chat & Messaging →
-   Features) for all toggle features. Query the docs MCP for
-   per-feature configuration details beyond the basic toggle.
+3. **Use `cometchat apply-feature <id>` for extension and ai-feature
+   types.** The CLI is the canonical path. Only fall back to the
+   dashboard URL when the CLI returns `manual-action-required`,
+   `auth-required`, or `error`.
 4. **Canonical reference URLs** (use as starting points if the agent
    doesn't have an MCP query handy):
    - Extensions: https://www.cometchat.com/docs/ui-kit/react/extensions
@@ -437,45 +492,54 @@ the type, query the docs MCP first.
        No new components, no custom CSS, no new files.
     4. Only if no prop matches, route to the `cometchat-customization`
        skill for the full four-tier discovery.
-- **Dashboard-toggle:** prefer the CLI — it flips the toggle via the
-  same API the dashboard UI uses, so the user doesn't leave the
-  terminal:
+- **Extension / AI feature:** run `cometchat apply-feature <id>`. The
+  CLI hits the dashboard API directly using the bearer token from
+  `cometchat auth login` (stored in the OS keychain). For native
+  cohorts (iOS / Android / Flutter / Angular), pass `--app-id <id>`
+  explicitly because there's no `.cometchat/state.json`. AI features
+  also take `--openai-key sk-…` the first time:
+
   ```bash
-  npx @cometchat/skills-cli features enable <id> --json
-  # to turn it off:
-  npx @cometchat/skills-cli features disable <id> --json
+  # Web/RN (state.json present):
+  cometchat apply-feature polls
+  cometchat apply-feature smart-replies --openai-key sk-...
+
+  # Native (stateless):
+  cometchat apply-feature polls --app-id A1B2C3
+  cometchat apply-feature smart-replies --app-id A1B2C3 --openai-key sk-...
   ```
-  The CLI reads the app id from `.cometchat/config.json` and the
-  bearer token from the OS keychain (requires a prior
-  `cometchat auth login`). Response shape:
-  - `"status": "enabled"` / `"disabled"` → done. Tell the user to
-    hard-refresh (Cmd+Shift+R) the browser tab running their dev
-    server.
-  - `"status": "no-op"` → already in the desired state.
-  - `"status": "not-logged-in"` → run `cometchat auth login` first.
-  - `"status": "no-app"` → run `/cometchat` or
-    `cometchat provision setup` first so `.cometchat/config.json`
-    has the app id.
-  - `"status": "error"` → surface `next_steps` verbatim. Includes
-    the dashboard URL as a manual fallback.
-
-  **Only fall back to the dashboard walkthrough** (app.cometchat.com
-  → Chat & Messaging → Features → flip Status toggle) if the CLI
-  returns `error` or isn't available. Run
-  `cometchat features info <id>` for per-feature configuration
-  details (Giphy API keys, translation languages, etc.) beyond the
-  basic toggle.
+
+  Response shapes (`--json`):
+  - `"status": "applied"` → done. Tell the user to hard-refresh
+    (Cmd+Shift+R) the browser tab running their dev server.
+  - `"status": "already-applied"` → the feature is already enabled
+    in this integration's `state.applied_features`.
+  - `"status": "auth-required"` → run `cometchat auth login` first.
+  - `"status": "openai-key-required"` (ai-feature only) → re-run
+    with `--openai-key sk-…`.
+  - `"status": "error"` → surface `next_steps` verbatim.
+
+  **Only fall back to the dashboard** when the CLI returns `error` or
+  isn't available. Manual flow for extensions: app.cometchat.com →
+  *Chat & Messaging → Features → flip Status toggle*.
 
   **Note:** if the feature has `auto_wired_in_uikit: false` in the
   catalog (most non-default extensions), the toggle alone isn't
   enough — you also need to register the extension via
-  `UIKitSettingsBuilder.setExtensions([...])` before `init`. The
-  CLI's success output flags this; query the docs MCP for the exact
-  builder syntax.
+  `UIKitSettingsBuilder.setExtensions([...])` before `init`. Query
+  the docs MCP for the exact builder syntax.
+
+- **Dashboard-only:** the CLI returns `manual-action-required` and
+  prints the dashboard path. These need third-party config (Giphy
+  API key, Chatwoot webhook, etc.) that only the user can supply.
+  Walk them through the dashboard.
+
 - **Package-install (calls):** run `npm install @cometchat/calls-sdk-javascript`
   directly. The user opted in, that IS consent.
-- **Component-swap:** run `npx @cometchat/skills-cli apply-feature <id>`.
-  The CLI handles the swap deterministically. Do NOT hand-edit.
+
+- **Component-swap:** run `cometchat apply-feature <id>` (web/RN
+  only — needs `state.json`). The CLI handles the swap
+  deterministically. Do NOT hand-edit.
 
 ### Step 5 — Verify
 
@@ -493,17 +557,21 @@ skill for deeper triage.
 
 - Never modify a project without an existing CometChat integration.
 - Always query the docs MCP for SDK reference (do not invent function names).
-- For component-swap features, always use `cometchat apply-feature <id>` —
-  the CLI is the source of truth, never hand-edit.
+- For component-swap, extension, and ai-feature types, always use
+  `cometchat apply-feature <id>` — the CLI is the source of truth,
+  never hand-edit and never tell the user to navigate the dashboard
+  unless the CLI itself returns `manual-action-required`.
+- For ai-feature types, the OpenAI key prerequisite is the only
+  manual input — pass it as `--openai-key sk-…` the first time per
+  app.
+- For native cohorts (iOS / Android / Flutter / Angular), always
+  pass `--app-id <id>` because their projects don't write
+  `.cometchat/state.json`.
 - For package-install features (calls), the user opting in IS consent —
   run `npm install <package>` directly.
-- For dashboard-toggle features, walk the user through the dashboard
-  activation steps from `cometchat features info <id>` — the dashboard
-  flip is something only the human can do.
-- For dashboard-toggle features, always give the canonical path:
-  **app.cometchat.com → select app → Chat & Messaging → Features →
-  toggle ON.** Query the docs MCP for per-feature config details
-  (e.g. Giphy API key, Translation language settings).
+- For dashboard-only features (third-party API keys, webhooks,
+  multi-field config), walk the user through the dashboard — these
+  cannot be automated.
 - Always use `npx @cometchat/skills-cli`.
 
 ## Sources

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

@@ -0,0 +1,167 @@
+---
+name: cometchat-flutter-v5
+description: "Use when building chat with CometChat Flutter UIKit v5 (cometchat_chat_uikit v5.2.14, cometchat_calls_uikit v5.0.15). Orchestrator skill that routes to feature-specific skills."
+license: "MIT"
+compatibility: "cometchat_chat_uikit ^5.2.14; cometchat_calls_uikit ^5.0.15; cometchat_uikit_shared ^5.2.3; cometchat_sdk ^4.1.2; get ^4.6.5"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat flutter v5 chat uikit messaging conversations getx"
+---
+
+# CometChat Flutter UIKit v5 — Orchestrator
+
+Entry point skill for the CometChat UIKit v5 packages. Routes to feature skills based on context.
+
+## Project Detection
+
+Confirm the project uses CometChat UIKit v5 by checking `pubspec.yaml` for:
+
+```yaml
+dependencies:
+  cometchat_chat_uikit: ^5.2.14
+  cometchat_calls_uikit: ^5.0.15  # Optional, for calling features
+```
+
+The v5 uses **separate packages** (unlike v6 which bundles everything):
+- `cometchat_chat_uikit` — Chat UI components
+- `cometchat_calls_uikit` — Call UI components (re-exports `cometchat_uikit_shared` + `cometchat_sdk` + `cometchat_calls_sdk`; does NOT re-export `cometchat_chat_uikit`)
+- `cometchat_uikit_shared` — Shared utilities
+
+**Imports — two barrels, not one.** For chat-only apps, the chat barrel is sufficient. If you also need voice/video calls, add a SECOND import — the calls barrel does NOT re-export the chat barrel.
+
+```dart
+// Always:
+import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
+
+// Add this only if your app uses calls:
+import 'package:cometchat_calls_uikit/cometchat_calls_uikit.dart';
+```
+
+## Key v5 vs v6 Differences
+
+| Aspect | v5 | v6 |
+|--------|----|----|
+| State management | GetX (GetBuilder, GetxController) | BLoC (Bloc, Equatable) |
+| Packages | Separate (chat_uikit + calls_uikit) | Single (cometchat_chat_uikit) |
+| Controllers | `Get.put()` internally | ServiceLocator pattern |
+| SDK | `cometchat_sdk ^4.1.2` | `cometchat_sdk ^5.0.0` |
+
+## Skill Routing
+
+| User mentions | Route to skill |
+|---------------|---------------|
+| init, login, logout, UIKitSettings, setup, GetX, GetBuilder | `cometchat-flutter-v5-core` |
+| theme, colors, dark mode, styling, CometChatColorPalette, merge() | `cometchat-flutter-v5-theming` |
+| conversations, conversation list, recent chats | `cometchat-flutter-v5-conversations` |
+| messages, message list, composer, compact composer, header, keyboard, threads | `cometchat-flutter-v5-messages` |
+| users, groups, group members, contacts, CometChatChangeScope | `cometchat-flutter-v5-users-groups` |
+| calls, voice call, video call, CometChatCallButtons, incoming call, call logs | `cometchat-flutter-v5-calls` |
+| events, listeners, real-time, typing indicator, online status, receipts | `cometchat-flutter-v5-events` |
+| custom bubbles, templates, DataSource, decorator, formatters, slot views, extensions | `cometchat-flutter-v5-customization` |
+| push notifications, FCM, APNs, VoIP, token, firebase messaging, callkit | `cometchat-flutter-v5-push` |
+| auth tokens, ProGuard, release build, security, environment, production | `cometchat-flutter-v5-production` |
+| error, debug, not working, crash, fix, troubleshoot, verify | `cometchat-flutter-v5-troubleshooting` |
+
+## Architecture Overview
+
+The UIKit v5 follows a **GetX controller pattern**:
+
+```
+{component}/
+├── cometchat_{component}.dart              # StatefulWidget
+├── cometchat_{component}_controller.dart   # extends GetxController
+├── cometchat_{component}_style.dart        # ThemeExtension with merge()
+└── {component}_builder_protocol.dart       # Request builder protocol
+```
+
+## Golden Path — Minimal Chat App (v5)
+
+```dart
+import 'package:flutter/material.dart';
+import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
+// Add the calls import only if your app uses voice/video calls:
+// import 'package:cometchat_calls_uikit/cometchat_calls_uikit.dart';
+
+const String appId = 'YOUR_APP_ID';
+const String region = 'us';
+const String authKey = 'YOUR_AUTH_KEY';
+
+void main() => runApp(const MyApp());
+
+class MyApp extends StatefulWidget {
+  const MyApp({super.key});
+  @override
+  State<MyApp> createState() => _MyAppState();
+}
+
+class _MyAppState extends State<MyApp> {
+  bool _initializing = true;
+  bool _loggedIn = false;
+
+  @override
+  void initState() {
+    super.initState();
+    _initCometChat();
+  }
+
+  void _initCometChat() {
+    final settings = (UIKitSettingsBuilder()
+          ..appId = appId
+          ..region = region
+          ..authKey = authKey
+          ..subscriptionType = CometChatSubscriptionType.allUsers
+          ..callingExtension = CometChatCallingExtension())
+        .build();
+
+    CometChatUIKit.init(
+      uiKitSettings: settings,
+      onSuccess: (_) {
+        setState(() {
+          _loggedIn = CometChatUIKit.loggedInUser != null;
+          _initializing = false;
+        });
+      },
+      onError: (e) {
+        debugPrint('Init failed: ${e.message}');
+        setState(() => _initializing = false);
+      },
+    );
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      navigatorKey: CallNavigationContext.navigatorKey,
+      home: _initializing
+          ? const Scaffold(body: Center(child: CircularProgressIndicator()))
+          : _loggedIn
+              ? HomeScreen()
+              : LoginScreen(),
+    );
+  }
+}
+```
+
+Key points:
+- Always import `package:cometchat_chat_uikit/cometchat_chat_uikit.dart` for chat widgets; add `package:cometchat_calls_uikit/cometchat_calls_uikit.dart` as a second import only when using calls
+- `CometChatUIKit.login(uid)` takes a String directly
+- `CallNavigationContext.navigatorKey` set on MaterialApp
+- `CometChatCallingExtension()` set on UIKitSettingsBuilder
+- `subscriptionType` always set
+
+## Autonomous Mode
+
+- If `pubspec.yaml` has `cometchat_chat_uikit` v5.x or `cometchat_calls_uikit` v5.x → proceed without asking
+- If credentials exist in code → reuse them
+- If user says "messages screen" → generate Scaffold + Header + List + Composer
+- Always add `subscriptionType` to UIKitSettingsBuilder
+- Always use `CometChatThemeHelper` for colors, never hardcode
+- Always import from `cometchat_chat_uikit` barrel for chat widgets. Add `cometchat_calls_uikit` as a SECOND import for calls — never as a replacement (the calls barrel does not re-export chat).
+
+## Android Build Requirements
+
+- `android.useAndroidX=true` and `android.enableJetifier=true` in `gradle.properties`
+- `minSdk 26` in `android/app/build.gradle`
+- ProGuard: `-keep class com.cometchat.** { *; }`