@cometchat/skills 4.4.2 → 5.0.0

package/skills/cometchat-react-v7-core/references/lifecycle.md

@@ -0,0 +1,74 @@
+# lifecycle — init, login, provider (React v7)
+
+## Init must happen once (StrictMode double-init)
+Init is async and must complete before any `CometChat*` component renders. React 18 StrictMode runs effects twice in dev, so guard by caching the init **PROMISE — NOT a boolean**. A boolean set BEFORE `await init()` lets StrictMode's second call see `true` and return BEFORE init has actually resolved → the app renders / logs in against an un-initialized SDK and throws **"CometChatUIKit: Not initialized"** on first load (AUDIT-047). Cache the promise so every concurrent caller awaits the SAME init (mirrors the login in-flight promise below):
+```typescript
+// initFromSettings resolves to CometChat.User | null (a resumed session or null), so type the cached
+// promise as Promise<unknown> — assigning it into Promise<void> is a TS2322 error under strict TS.
+let initPromise: Promise<unknown> | null = null;
+function initCometChat(): Promise<unknown> {
+  if (!APP_ID || !REGION || !AUTH_KEY) throw new Error("CometChat credentials empty — check .env + prefix (VITE_/NEXT_PUBLIC_/PUBLIC_) and restart the dev server.");
+  if (!initPromise) {
+    // initFromSettings sets integrationSource="ai-agent" for telemetry attribution (routes the Calls SDK too) — AUDIT-084.
+    initPromise = CometChatUIKit.initFromSettings({   // cache the PROMISE (never a boolean flipped before the await)
+      appId: APP_ID, region: REGION,
+      credentials: { authKey: AUTH_KEY },                        // dev only — prod: server-minted auth token (login below)
+      chatSDK: { presenceSubscription: { type: "ALL_USERS" } },  // = subscribePresenceForAllUsers()
+    });
+  }
+  return initPromise;                              // 2nd StrictMode call awaits the SAME init → never early-returns before ready
+}
+```
+Call init in `useEffect` (Next.js/Astro/React Router SSR) or at the entry file before `createRoot` (Vite/CRA — `main.tsx` only runs in the browser). Never call init during render (infinite re-render).
+
+## Login — safe SEQUENTIALLY, not CONCURRENTLY
+Sequential: a second `login()` after the first completes returns the cached user. Concurrent: a second `login()` while the first is in-flight throws **"Please wait until the previous login request ends."** — exactly what StrictMode's double-effect triggers. Guard with a module-level in-flight promise:
+```typescript
+let loginInFlight: Promise<unknown> | null = null;
+async function ensureLoggedIn(uid: string, authToken?: string) {
+  const existing = CometChatUIKit.getLoggedInUser();   // SYNC getter, capital "In" — no await (see the note below)
+  if (existing && existing.getUid?.() === uid) return;         // same user → done
+  if (existing) await CometChatUIKit.logout();                 // switching accounts needs explicit logout
+  if (loginInFlight) { await loginInFlight; return; }          // concurrent → reuse pending promise
+  loginInFlight = authToken ? CometChatUIKit.loginWithAuthToken(authToken) : CometChatUIKit.login(uid);
+  try { await loginInFlight; } finally { loginInFlight = null; }
+}
+```
+Call `ensureLoggedIn()` from the provider/effect, not `login()` directly. A cached promise (not a boolean) lets all callers `await` the same request.
+
+## Dev-only: `ensureDevUser` — create-if-missing a sample user, then log in (a guaranteed valid session)
+For a fast dev start you can't reliably pre-check whether `cometchat-uid-1` exists (`getUser` needs a session, and you only have the Auth Key — not the REST key for a server-side lookup). So **create-if-missing then login** — one deterministic path, valid on any app (fresh/sample/empty/custom), no 5-way probe. **DEV-ONLY** — prod uses a real user + a server-minted token via `loginWithAuthToken`.
+```typescript
+import { CometChat } from "@cometchat/chat-sdk-javascript";   // for CometChat.User
+// CometChatUIKit.createUser(user) uses the Auth Key configured in init — verified vs 7.1.0.
+async function ensureDevUser(uid = "cometchat-uid-1", name = "Demo User") {
+  try {
+    const u = new CometChat.User(uid);
+    u.setName(name);
+    await CometChatUIKit.createUser(u);          // creates it if missing (dev; uses the init Auth Key)
+  } catch {
+    // already-exists is EXPECTED and fine — the user is there; fall through to login.
+  }
+  await ensureLoggedIn(uid);                      // now guaranteed to succeed
+}
+```
+
+## Get the current logged-in UID (never hardcode)
+```typescript
+import { CometChatUIKit } from "@cometchat/chat-uikit-react";
+import { CometChat } from "@cometchat/chat-sdk-javascript";
+// preferred — sync, after login completes (most app code):
+const myUid = CometChatUIKit.getLoggedInUser()?.getUid();      // UI Kit, capital "In" → CometChat.User | null (sync)
+// fallback — async, when the SDK was initialized directly / session may still be restoring:
+const myUid2 = (await CometChat.getLoggedinUser())?.getUid();  // SDK namespace, lowercase "in" → Promise<CometChat.User | null>
+```
+> Two DIFFERENT methods on two DIFFERENT owners: the **sync** getter is `CometChatUIKit.getLogged**In**User()` (UI Kit, capital "In"); the **async** getter is `CometChat.getLogged**in**User()` (SDK namespace, lowercase "in"). `CometChatUIKit` has NO async `getLoggedinUser` — that was a v6 assumption. Verified against installed 7.1.0 (`index.d.ts` line 617 + the kit's own doc note).
+
+## Production login
+Fetch a per-user token from YOUR backend (CometChat REST API with your server AUTH_TOKEN), then `await CometChatUIKit.loginWithAuthToken(token)`. Never hardcode auth keys in shipped source.
+
+## Logout
+`await CometChatUIKit.logout();` — clears the local session; call on app sign-out.
+
+## Reusable provider
+Wrap init + login + ready-gate in a `CometChatProvider` so components mount only after login resolves; keep the module-level `initPromise`/`loginInFlight` promises (cache the PROMISE, not a boolean — AUDIT-047) so StrictMode doesn't double-fire or race ahead of a not-yet-resolved init. Mount the provider at a STABLE ancestor (not remounted per route/toggle) so init/login survive navigation. (Pretty-print errors — don't `String(error)` raw; surface the code/message.)

package/skills/cometchat-react-v7-core/references/setup-credentials.md

@@ -0,0 +1,58 @@
+# setup-credentials — detect, credentials, authorize (React v7)
+
+## 1. Detect project (package / config / framework)
+- Confirm `package.json` has `react`. Identify the bundler → env prefix:
+  - **Vite** → `.env`, `import.meta.env.VITE_*`
+  - **Create React App** → `.env`, `process.env.REACT_APP_*`
+  - **Next.js** → `.env.local`, `process.env.NEXT_PUBLIC_*`
+  - **Astro (React)** → `.env`, `import.meta.env.PUBLIC_*`
+  - **React Router (Vite)** → `.env`, `VITE_*`
+- Reuse existing config: a prior `.cometchat/config.json` or already-set `*_COMETCHAT_APP_ID` → reuse, skip re-setup, don't re-provision or re-ask.
+
+## 2. version_conflict — STOP gate
+If `@cometchat/chat-uikit-react` is installed at a non-v7 major (e.g. v6), STOP. Surface it, reconcile (upgrade to v7, or load the matching-version skills), then continue. Never mix majors.
+
+## 3. Credentials — fetch from the dashboard (offer it), or paste manually
+> **The CLI is a DASHBOARD/API client only, loaded ON DEMAND (AUDIT-059).** The `@cometchat/skills-cli` tool does exactly THREE things: `auth` (dashboard login), `provision` (fetch an app's App ID/Region/Auth Key from the dashboard), and `config` (local cred state). It knows NOTHING about React/frameworks/UI Kit and does NOT write env files, detect the project, or generate code — **the SKILL owns all of that** (detection = §1 by reading the repo; env-writing = §4; codegen = the golden path). Only load the CLI when the user opts into fetching from the dashboard.
+
+> **OFFER the dashboard fetch; don't default to manual paste (AUDIT-039).** When credentials are missing, present BOTH paths and default to the fetch: *"I can fetch your App ID / Region / Auth Key by logging into your CometChat dashboard (I'll load the CometChat CLI to do it), or you can paste them manually — which do you prefer?"* **Only if the user picks the fetch do you load/run the CLI** (below); a manual paste never touches the CLI. **Never silently skip to "paste them yourself," and never end the build with a "to finish, add credentials manually" TODO.**
+
+> **The CLI.** Load it on demand with **`npx @cometchat/skills-cli@3` `<cmd>`** (public npm — no auth needed; `@3` pins the CLI major that matches the v5 skills). Below, `<cli>` = that full invocation. (Distinct from `@cometchat/skills`, which only installs these skills.)
+
+**Fetch path (user opted in).** Let each command block — do NOT background or race them.
+1. **Check auth:** `<cli> auth status --json` → `logged-in` | `logged-out`.
+2. **Log in (if logged-out):** `<cli> auth login` — opens the dashboard in the browser (device-auth), polls, stores the bearer in the OS keychain. (`auth signup` for a brand-new account.) Surface terminal errors verbatim (`ACCESS_DENIED` / `EXPIRED` / `TIMEOUT` / `ABORTED`) and stop; don't retry silently.
+3. **Pick the app — REUSE first, ASK with CURATED options, never auto-create:** if a `.cometchat/config.json` or env App ID already exists, use it and SKIP. Otherwise `<cli> provision list --json` returns the raw list — **the SKILL curates it; never dump a long table.** Present a selectable prompt of ≤4 options: the **TOP 3** apps ranked by relevance (framework match, then most-recent; name · region · App ID) **+ "Show all N apps"**; the free-text/"Other" answer = **paste an App ID/name manually**. Only on "Show all" list them all. No selectable prompts → the same as a numbered list (1–3, 4=show all, 5=manual) and WAIT. **NEVER dump all N as the primary prompt** (the 29-apps-in-a-table regression). **NEVER auto-create an app** — only on explicit request, confirming the name; zero apps → ask first.
+4. **Fetch the credentials:** `<cli> provision use --app-id "<id>" --json` (or `provision run`) authenticates and returns `{ appId, region, authKey }` for that app **and writes a framework-neutral `.cometchat/config.json`** — it does NOT write any env file and takes NO `--framework` flag (that's the skill's job, §4). The Auth Key is returned so the skill can write it into the env; treat it as a secret (never echo it back to the user).
+5. **Reuse existing:** a prior `.cometchat/config.json` or an already-set `*_COMETCHAT_APP_ID` → reuse, skip re-provision.
+
+**Manual path** (user prefers, or the CLI can't run): Dashboard → Your App → Credentials → App ID, Region (`us`/`eu`/`in`), Auth Key (**dev only**). If neither path yields them, ASK and WAIT — never proceed with placeholders.
+
+**Then the SKILL writes the env** from the config.json / returned creds — §4 (right prefix for the detected bundler) — and gitignores it. The CLI stops at "here are your credentials + a neutral config.json."
+
+**Enable dashboard-gated features** (reactions, polls, translation, AI copilot, moderation, …) — the CLI does this (it's a dashboard/API op): `<cli> features list` shows the app's extensions + enabled state; `<cli> features enable <id>` / `disable <id>` flips the toggle via the management API (reads the App ID from `.cometchat/config.json`). Or do it manually in the **Dashboard** (Extensions / AI). Either way, YOU still wire the client component/prop (see `cometchat-react-v7-features`); the CLI only flips the dashboard toggle. Fetch current dashboard steps from the feature's `docs_topic`. (AUDIT-070 restored `features`.)
+
+Production: mint a per-user **auth token** from your backend and use `loginWithAuthToken` — never ship the Auth Key to the client. The token endpoint is host code the SKILL scaffolds (or follow CometChat's docs); it is not a CLI step.
+
+## 4. Env variables (three)
+| Suffix | Required | Notes |
+|---|---|---|
+| `COMETCHAT_APP_ID` | yes | dashboard App ID |
+| `COMETCHAT_REGION` | yes | `us` / `eu` / `in` |
+| `COMETCHAT_AUTH_KEY` | dev only | replace with auth tokens in prod |
+
+Prefix per bundler (Vite `VITE_`, CRA `REACT_APP_`, Next `NEXT_PUBLIC_`, Astro `PUBLIC_`). **The SKILL writes this env file** from the credentials (fetched into `.cometchat/config.json`, or pasted) — the CLI does not. **Then ENSURE the env file is gitignored (AUDIT-048): Vite/CRA scaffolds ignore only `*.local` (NOT `.env`), so an un-ignored `.env` with the Auth Key is a committable secret — verify/append `.env` to `.gitignore` for Vite/CRA/Astro; Next's `.env.local` is gitignored by default.** Restart the dev server after editing `.env`. Fail loud if any var is empty — an empty credential surfaces later as a cryptic `ERROR_API_KEY_NOT_FOUND`.
+
+## 5. Authorize / verify
+Credentials are valid when `CometChatUIKit.initFromSettings(settings)` resolves and `login()`/`loginWithAuthToken()` succeeds for a UID that exists in the app (see §6). Auth error on init/login → most commonly a **Region mismatch**; re-check the dashboard values. Do not render until login resolves.
+
+## 6. Which user to log in as (the login UID) — do NOT invent one
+`login(uid)` authenticates as a user that **must already exist** in your CometChat app; it does **not** create one. Never hardcode a guessed UID — even the current docs sample `cometchat-uid-1` is **not guaranteed to exist in this app**. Logging in as a missing UID fails (user-not-found) and the screen stays blank.
+- **Never suggest a legacy/guessed sample UID.** Do **NOT** offer `superhero1` (or `superhero1..5`, `cc-user-*`, or any other remembered "classic sample" set) — those are NOT seeded in modern apps and only mislead the user. When you ASK, do not fabricate candidate UIDs from memory. The ONLY tentative suggestion allowed is `cometchat-uid-1..5`, and only labelled *"if this is a freshly-created app"* — never presented as a known-good login for THIS app.
+- **Use a real UID:** Dashboard → your app → **Users** tab lists every UID. A freshly created / sample app is pre-seeded with sample users (`cometchat-uid-1`…`cometchat-uid-5`). ASK the user; prefer their own answer over any suggestion.
+- **The login-UID prompt is DETERMINISTIC — ALWAYS present these SELECTABLE options, in this order (AUDIT-068/069):**
+  1. **`cometchat-uid-1` — create-if-missing then login** *(dev, recommended for a fast start)*. Wire login as **create-if-missing then login** (`ensureDevUser` in `lifecycle.md`) so it's GUARANTEED valid on ANY app (fresh/sample/empty/custom). Don't "probe uid-1→uid-5": you can't check existence before login (`getUser` needs a session; we only hold the Auth Key), so probing = up to 5 login attempts — create-if-missing is ONE deterministic call. DEV-ONLY (prod → server-minted per-user tokens).
+  2. **Paste your own UID** — for a real/custom app with existing users (Dashboard → Users); the free-text / "Other" answer. **No user is created** on this path.
+  > This is a SKILL prompt (login-UID is the skill's job) — the CLI has no part in it. Keep it consistent run-to-run: option 1 (`cometchat-uid-1`, create-if-missing) must ALWAYS be present. Never suggest `superhero1`/legacy sample UIDs.
+- **Create one (dev):** Dashboard → Users → **Add User** (set a UID, e.g. `alice`), then `login("alice")`. Programmatic creation (SDK `createUser` client-side, or the REST `POST /v3/users` with the REST API Key server-side) — fetch the exact signature/endpoint from docs; never ship the Auth Key to a client.
+- **Production:** don't hardcode a sample UID. Per real end-user, create a matching CometChat user server-side (REST API + API key, using your own id as the UID), then log in with a per-user **auth token** from your backend → `loginWithAuthToken(token)` (§3).

package/skills/cometchat-react-v7-core/references/ssr.md

@@ -0,0 +1,11 @@
+# ssr — server-side rendering safety (React v7)
+
+All UI Kit components are browser-only (they touch `window`/`document` on import). Rendering them on the server crashes. Prevent per framework:
+
+- **Next.js App Router:** `dynamic(() => import("./ChatView"), { ssr: false })` is **NOT allowed in a Server Component** (App Router build error: *"ssr: false is not allowed with next/dynamic in Server Components"*). Put the `dynamic(...)` call inside a `"use client"` module — e.g. a small `"use client"` wrapper that does the `dynamic(..., { ssr: false })` and renders it, then import that wrapper from your server page/layout. (The chat file itself must also be `"use client"`.)
+- **Next.js Pages Router:** `dynamic(() => import("../components/CometChatNoSSR"), { ssr: false })`.
+- **Astro:** `<ChatPanel client:only="react" />` — prevents render during static build.
+- **React Router v7 (SSR):** `React.lazy()` + `Suspense`, gated on a mounted flag (`useEffect(() => setMounted(true), [])`; `if (!mounted) return null`).
+- **Vite / CRA:** no SSR — import and use directly.
+
+Detail belongs to `cometchat-react-v7-patterns` (framework glue); this is the core-level safety summary.

package/skills/cometchat-react-v7-core/references/theming.md

@@ -0,0 +1,52 @@
+# theming — CSS at the core level (React v7)
+
+Import the UI Kit CSS ONCE at the app root; theme via `--cometchat-*` variables. v7 also supports a `theme` prop on `CometChatProvider` and a `useTheme` hook with `light`/`dark` + `data-theme`.
+
+```tsx
+// import once at the highest level (main.tsx / app/layout.tsx / global css)
+import "@cometchat/chat-uikit-react/styles";   // v7.1.0 CSS entry (package exports "./styles" -> dist/index.css)
+```
+The CSS-only `./styles` export has no type declaration, so on TypeScript 6 (`noUncheckedSideEffectImports` defaults ON — it's not a `strict` thing; opt-in on 5.6–5.9) that import errors with **TS2882 "Cannot find module or type declarations for side-effect import of '@cometchat/chat-uikit-react/styles'."** (verified vs TS 6.0.3). Ship this ambient declaration as a REAL file the app can copy — `src/cometchat.d.ts` (any `.d.ts` picked up by `tsconfig` `include`) — so the import type-checks (AUDIT-013):
+```typescript
+// src/cometchat.d.ts — lets TS accept the CSS-only "./styles" side-effect import (TS2882 otherwise)
+declare module "@cometchat/chat-uikit-react/styles";
+```
+```css
+/* theme-INDEPENDENT tokens (identical in light & dark) may sit on the bare class */
+.cometchat { --cometchat-font-family: "Inter", sans-serif; }
+/* theme-DEPENDENT tokens (every colour) MUST be scoped to the data-theme ATTRIBUTE,
+   NOT the bare `.cometchat` class — see the gotcha below. */
+.cometchat[data-theme="light"] { --cometchat-primary-color: #6851d6; }
+.cometchat[data-theme="dark"]  { --cometchat-primary-color: #bb86fc; }
+```
+- **Scope colour tokens to `data-theme`, not bare `.cometchat` (AUDIT-033).** The provider renders `<div data-theme="light|dark" class="cometchat">`, but several components (verified: `CometChatSearch`; also popovers/portaled surfaces) render their OWN nested `<div class="cometchat …">` **with NO `data-theme`**. A colour token on the bare `.cometchat` class therefore ALSO matches that nested wrapper and **re-pins the light value on its subtree** — so in dark mode the search (etc.) stays light while everything else goes dark. Put per-theme colours on `.cometchat[data-theme="light"]` / `.cometchat[data-theme="dark"]`: the nested wrapper matches neither and simply **inherits** the provider's theme. Use `.cometchat[data-theme="dark"]` (the SAME element) — NOT `[data-theme="dark"] .cometchat` (a descendant that matches nothing → silent no-op). To retint a kit internal per theme, use `[data-theme="dark"] .cometchat-<bem>` (the kit's own convention). Depth: `cometchat-react-v7-customization`.
+- Never target internal class names (e.g. `.cometchat-message-bubble__wrapper`) — not public API, changes between versions. Use `--cometchat-*` variables (or documented BEM classes for per-component scoping).
+- Import overrides AFTER the kit CSS.
+- **Per-surface background tokens.** Some surfaces paint an opaque background from their OWN token, so a wrapper background can't reach them — override that surface's token instead. Two common ones (verified vs 7.1.0): the message list paints `--cometchat-message-list-bg` (default `-03`, `dist/index.css:4243`) and the thread header paints `--cometchat-thread-header-background` (falls back to `-01`, `dist/index.css:12727`; not set in `:root`, so setting it directly is the clean way to tint the thread header specifically). Differentiating the thread panel from the main list uses exactly this — see the thread recipe in `cometchat-react-v7-customization` (message-list-bg is the required step; thread-header-background is an optional header-only tint).
+
+## Follow the system (OS) light/dark theme (recommended default)
+The `theme` prop is `"light" | "dark"` and **defaults to `light`** — the UI Kit does **NOT** read the OS `prefers-color-scheme` and there is **no `theme="system"`** (AUDIT-004). For a fresh integration, sync the theme to the OS by default (least surprise) with a small SSR-guarded hook, and pass it to `CometChatProvider`:
+
+```tsx
+import { useEffect, useState } from "react";
+import { CometChatProvider } from "@cometchat/chat-uikit-react";
+
+function useSystemTheme(): "light" | "dark" {
+  const read = () =>
+    typeof window !== "undefined" &&
+    window.matchMedia?.("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+  const [theme, setTheme] = useState<"light" | "dark">(read);   // SSR: renders "light", corrects on hydrate
+  useEffect(() => {
+    const mq = window.matchMedia("(prefers-color-scheme: dark)");
+    const onChange = () => setTheme(mq.matches ? "dark" : "light");
+    mq.addEventListener("change", onChange);                    // live-updates when the OS theme flips
+    return () => mq.removeEventListener("change", onChange);
+  }, []);
+  return theme;
+}
+
+// <CometChatProvider theme={useSystemTheme()}> … </CometChatProvider>
+```
+For an explicit user toggle instead of OS-follow, use `useTheme()` (`{ theme, setTheme }`). Next.js/SSR: `window.matchMedia` must stay guarded — see `references/ssr.md`.
+
+Full theming depth (token list, per-component BEM, dark mode switching): `cometchat-react-v7-customization`.

package/skills/cometchat-react-v7-core/references/troubleshooting.md

@@ -0,0 +1,28 @@
+# troubleshooting — CometChat React v7: symptom → cause → fix
+
+The fast symptom-table for a broken integration. Each row is a REAL failure mode, baked (don't fetch docs); deeper detail is cross-linked to the sibling reference.
+
+## The table
+| Symptom (what the user sees) | Root cause | Fix |
+|---|---|---|
+| **Blank / empty screen, no errors** | Component rendered BEFORE `init()`+`login()` resolved, or wrong Region / env prefix so init silently fails | Gate render on `getLoggedInUser()` (`init→login→render` is invariant); verify Region matches the Dashboard app + env prefix matches the bundler. `lifecycle.md` + `setup-credentials.md`. |
+| **`window is not defined` / `document is not defined`** | SSR — the kit touches browser globals during server render (Next RSC, Astro, React-Router) | Make the chat tree client-only: Next `"use client"` + `dynamic(…, { ssr:false })`; Astro `client:only="react"`; RR guard `typeof window`. `ssr.md`. |
+| **Chat renders as a ~0px sliver / crammed top-left** | The container has no resolved height/width — kit components are `height:100%`/flex-fill and collapse in a content-driven box (static collapse) | Content-INDEPENDENT height **and** width: full-page `100dvh`/`100%`; embedded a fixed height or sized grid/flex cell. **Columns need height + `min-height:0` too**, not just the root. `layout.md` + `anti-patterns.md` #8. |
+| **Chat is small while the list loads, then GROWS to full size** (reflow) | Box is content-driven, not pinned (ancestor chain not `height:100%`, or `min-height`/`auto`, or an unsized wrapper) — the kit fills "nothing" and grows as content arrives | Pin independent of content: `html,body,#root{height:100%;margin:0}` + `100dvh` (never `min-height`/`auto`) + `min-height:0` columns; let the kit's own `loadingView`/`emptyView` fill the pinned box. `layout.md` (AUDIT-023). |
+| **Snake_case tokens** (`group_info`, `add_members`) instead of labels | Localization key MISS — `getLocalizedString` returns the raw key; v7 namespaces sample strings under `sample_` so v6 keys miss | Map to the v7 key (`group_info`→`sample_group_info`) or the INSTANCE method `CometChatLocalize.getSharedInstance()?.addTranslation(...)`; look up the EXACT key in the kit source / docs — never guess. `i18n-rtl-a11y.md` + migration §7. |
+| **Usernames centered / conversations header keeps growing** | Host GLOBAL CSS leaking into the `.cometchat` subtree (global `text-align:center`, a centering reset, or `flex:1` on a kit ancestor — often Tailwind base) | Scope global styles away from the kit root; never override the kit's internal classes (its defaults are correct). Customize via theme vars + view slots only. `anti-patterns.md` #12. |
+| **Kit overlays (menus, emoji, call screen) clipped / mis-positioned** | A `transform`/`filter`/`backdrop-filter` on a wrapper above the kit traps its `position:fixed` overlays | Remove the transform/filter from the chat wrapper; animate `left`/`right`/width instead. `anti-patterns.md` #8/#11. |
+| **`version_conflict` on `detect`, or two kits behaving oddly** | The project declares a non-v7 kit major (v5/v6), or two cohorts at once | STOP. Reconcile: upgrade to v7 (migration skill for v6→v7), load the matching-version skills, or remove the extra cohort. Never mix majors. `RULES.md`. |
+| **`login()` fails / "user not found"** | Logging in a UID that doesn't exist (a guessed sample like `superhero1`, not seeded) | Use a UID that EXISTS: ask, or Dashboard → Users (fresh apps seed `cometchat-uid-1`…); create one if none fits. Prod → per-user auth token + `loginWithAuthToken`. `setup-credentials.md` §6. |
+| **Roster lists render every row TWICE + ~30 "duplicate key" errors** (dev only) | React **StrictMode** (default in fresh Vite) double-invokes effects; roster drop-ins `CometChatUsers`/`CometChatGroups`/`CometChatGroupMembers` double-append (kit de-dupe gap; `CometChatConversations` unaffected). Dev-only. | A StrictMode DEV artifact — gone in `vite build`/prod. Do NOT remove StrictMode to "fix" it; verify the roster in a prod build. Kit issue (report upstream). AUDIT-062/065. |
+| **`TS6133` "declared but never read" on a `CometChat` import** | The `CometChat` SDK is an ambient global — importing the namespace only for TYPE use trips `noUnusedLocals`+`verbatimModuleSyntax` (Vite React-TS) | Import only for VALUE use (`instanceof CometChat.User`, `new CometChat.*RequestBuilder`). Type-only → reference `CometChat.User`/`.Group` with NO import (resolves ambiently). `dependencies.md` (AUDIT-007). |
+| **StrictMode logs a double init / double login** (dev) | React 18 StrictMode double-invokes effects; an unguarded `init()`/`login()` runs twice | Guard with an init-once ref + a concurrent-login guard (`ensureLoggedIn`). `lifecycle.md`. |
+| **Theme ignores the OS dark/light setting** | Kit defaults to `light`, no `theme="system"` | Sync `CometChatProvider theme=` to `prefers-color-scheme` yourself. `theming.md` (AUDIT-004). |
+| **A default-on control does nothing** (search filters nothing, "Reply in Thread" no-ops) | The drop-in renders a live-looking affordance that's INERT until the host wires it (`needs_stitching`) | Wire the destination (`onSearchBarClicked`→`CometChatSearch`; `onThreadRepliesClick`→thread) OR hide it (`showSearchBar={false}`/`hideReplyInThreadOption`). Never dead-end. Features skill. |
+| **Search wired but returns nothing (HTTP 402)** | `CometChatSearch`'s server call returns `402 Payment Required` until Search is enabled on the plan/Dashboard | TELL the user: wiring alone yields nothing — enable Search in the Dashboard / upgrade. `features.json` `message-search`. |
+| **Call buttons hidden / calls never ring** | Calling not enabled, or the calls SDK isn't installed | Install `@cometchat/calls-sdk-javascript@5` (not bundled) AND turn calling ON: `uiKit:{ callsSDK:{} }` in `CometChatUIKit.initFromSettings`. Both required; groups don't ring (join model). Calls skill. |
+
+## When it's NOT in the table
+- **Prop/signature question** → fetch the component's `.md` twin via `docs-map.md`; never read `.d.ts` or answer from memory.
+- **A feature renders empty** → the extension likely isn't enabled in the Dashboard (features skill "Verify it works").
+- **Still stuck** → check the console + network tab (a `4xx` on a CometChat endpoint = auth/plan/config, not a code bug), confirm App ID/Region/Auth Key in the env, and re-verify the detected framework/bundler + prefix by reading the project.

package/skills/cometchat-react-v7-customization/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: cometchat-react-v7-customization
+description: "Theme and brand the React v7 UI Kit — light/dark mode, CSS custom-property design tokens, per-component style overrides. Triggers: 'change chat colors', 'dark mode chat', 'match my brand', 'customize cometchat theme', 'override message list styles'."
+license: "MIT"
+compatibility: "React >=18; @cometchat/chat-uikit-react ^7 (7.1.x, verified 7.1.0)"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat react customization theming css-variables v7"
+---
+
+> **Ground truth:** `@cometchat/chat-uikit-react@7`. Theming mechanism below is from the live v7 theming docs (see core `references/docs-map.md` → `/ui-kit/react/theming`). Status: **catalog-verified vs installed 7.1.0 (exports-only web-v7.json).** Fetch the full `--cometchat-*` token list from the theming **`.md` twin** (`{DOCS_BASE}/ui-kit/react/theming.md`, via `docs-map.md`) — do NOT bake it.
+
+## Companion skills (read first)
+- `cometchat-react-v7-core` — install, provider, `init→login→render`. This skill ASSUMES it.
+
+## Use this skill when
+Branding/theming: colors, fonts, light/dark mode, or per-component style overrides.
+
+## Prerequisites & install
+Covered by core. No new package.
+
+## Customization mechanism (BAKED — v7)
+- **Design tokens = CSS custom properties**, all prefixed `--cometchat-*`, scoped to the `.cometchat` wrapper.
+- **Light/dark:** built-in `light` (default) and `dark`, selected via the `theme` prop on `CometChatProvider` and the `data-theme` attribute on the wrapper. Runtime switching via the `useTheme` hook.
+- **Follow the OS theme:** the `theme` prop is `"light" | "dark"` only and defaults to `light` — there is **no `theme="system"`** and the kit does NOT read `prefers-color-scheme` (AUDIT-004). To follow the system light/dark setting, sync the `theme` prop to `window.matchMedia("(prefers-color-scheme: dark)")` (with a `change` listener, SSR-guarded). Recommended as the default for a fresh integration. Full recipe: `cometchat-react-v7-core/references/theming.md`.
+- **Import order:** import your overrides AFTER the UI Kit styles (import UI Kit CSS ONCE at root).
+
+```tsx
+import { CometChatProvider, useTheme } from "@cometchat/chat-uikit-react";
+import "./cometchat-overrides.css";   // AFTER the kit styles
+
+<CometChatProvider theme="dark"><>{/* your chat UI */}</></CometChatProvider>
+```
+```css
+.cometchat { --cometchat-font-family: "Inter", sans-serif; }             /* theme-INDEPENDENT tokens only */
+.cometchat[data-theme="light"] { --cometchat-primary-color: #e91e63; }   /* per-theme COLOURS → data-theme attr */
+.cometchat[data-theme="dark"]  { --cometchat-primary-color: #bb86fc; }
+.cometchat-message-list { /* BEM class to scope tokens per component */ }
+```
+> **Per-theme COLOURS go on the `data-theme` element — NOT the bare `.cometchat` class (AUDIT-033).** `CometChatProvider` renders one wrapper `<div data-theme="light|dark" class="cometchat">` (compiled bundle: `jsx("div",{ "data-theme": internalTheme, className: "cometchat" })`), and the kit defines its tokens on `[data-theme=light]` / `[data-theme=dark]`. **But several components render their OWN nested `<div class="cometchat …">` with NO `data-theme`** — verified for `CometChatSearch` (also popovers / portaled surfaces). So a colour on the bare `.cometchat` class ALSO lands on that nested wrapper and **re-pins the base (light) value there**: in dark mode the search stays light while everything else goes dark. Scope per-theme colours to `.cometchat[data-theme="light"]` / `.cometchat[data-theme="dark"]` so the nested wrapper matches neither and **inherits** the provider's theme. Keep only theme-independent tokens (font-family, radii) on bare `.cometchat`. (Earlier docs claimed `[data-theme="dark"] .cometchat` matches nothing — that's wrong: it DOES match those nested wrappers. It's still not the right selector for brand tokens; use the `.cometchat[data-theme]` form above.) To retint a kit INTERNAL per theme, use the kit's own pattern — `[data-theme="dark"] .cometchat-message-list { … }`.
+
+## What's swappable
+- Global tokens on `.cometchat` (primary color, fonts, radii, spacing — fetch the full token names from the theming `.md` twin).
+- Per-theme overrides via `[data-theme="..."]`.
+- Per-component scoping via BEM classes (`.cometchat-conversations`, `.cometchat-message-list`, …).
+- Exact token names/defaults: fetch the theming `.md` twin (`{DOCS_BASE}/ui-kit/react/theming.md`, via core `references/docs-map.md`) — do NOT bake the token table.
+
+### Differentiating a nested surface — an opaque sub-surface needs its OWN var override (BAKED — verified vs 7.1.0)
+**Rule (general).** A kit sub-surface that paints an OPAQUE background does NOT inherit a wrapper's background — its own opaque paint covers whatever the wrapper set. To differentiate a nested surface you MUST override THAT surface's own background CSS variable (scoped on an ancestor — it cascades into the variable, no internal-class override needed), not just set a background on the wrapper.
+
+**The thread panel is the canonical case.** Verified in the 7.1.0 CSS: `.cometchat-message-list` paints `background: var(--cometchat-message-list-bg)` (default `var(--cometchat-background-color-03)`); `.cometchat-thread-header` and `.cometchat-message-composer` paint their own opaque `var(--cometchat-background-color-01)`. So the thread's message list renders `-03` — the SAME shade as the main list, and different from its own header/composer — and a background on the thread wrapper alone can't fix it (the list covers it). **Override the list's own token on the thread wrapper:**
+```css
+/* the div you wrap CometChatThreadHeader + thread CometChatMessageList + CometChatMessageComposer in */
+.cc-thread-panel {
+  --cometchat-message-list-bg: var(--cometchat-background-color-01); /* matches the thread header/composer; differs from the main list's -03 */
+  border-left: 1px solid var(--cometchat-border-color-default, #e8e8e8); /* optional divider from the main pane (-default = neutral-300 = #e8e8e8 light / #383838 dark) */
+}
+```
+`--cometchat-background-color-01` is `#ffffff` (light) / `#141414` (dark) and `-03` is `#f5f5f5` (light) / `#272727` (dark) — so the override visibly separates the thread list from the main list in BOTH themes while matching the thread header/composer. Same trick for any per-surface background: scope the surface's OWN token on the wrapper, never override the kit's internal `.cometchat-*` element classes (`core/references/anti-patterns.md` #7/#12/#16).
+
+> **Tinting the thread HEADER specifically — use its dedicated token.** `.cometchat-thread-header` paints `background: var(--cometchat-thread-header-background, var(--cometchat-background-color-01, #fff))` (verified vs 7.1.0 — `dist/index.css:12727`; the token is NOT defined in `:root`, only referenced with that fallback chain). So if you want to give the thread HEADER its own tint (a different shade from the list/composer, e.g. a subtly darker panel header), set `--cometchat-thread-header-background` directly on the thread wrapper — cleaner and more targeted than leaning on the `-01` fallback:
+> ```css
+> .cc-thread-panel {
+>   --cometchat-message-list-bg: var(--cometchat-background-color-01);  /* REQUIRED — repaints the thread LIST (opaque, covers the wrapper) */
+>   --cometchat-thread-header-background: var(--cometchat-background-color-02);  /* OPTIONAL — tints ONLY the thread header, independent of the list */
+> }
+> ```
+> The `--cometchat-message-list-bg` override above is still **required** — the header token only paints the header; it does not touch the opaque message list. Use `--cometchat-thread-header-background` only when you want the header a *different* shade from the list; if you want them to match, the header already inherits `-01` and needs no override.
+
+## Structural customization — view slots & composition (beyond tokens)
+Theming changes how it LOOKS (tokens); changing WHAT renders is **view slots** + composition, not CSS. Every list/message component exposes view-slot props to inject custom UI **IN** the component (never as a sibling on top): e.g. Conversations `headerView` / `searchView`; MessageHeader `trailingView` / `auxiliaryButtonView`; MessageList `headerView` / `footerView`; Composer `auxiliaryButtonView` / `headerView`. Baked slot map: `cometchat-react-v7-core/references/component-props.md`. For the exhaustive per-component slot list, fetch the component's `.md` twin (`core/references/docs-map.md`) — do NOT read `.d.ts`. (Custom message **bubbles** are a separate capability — the message **plugin** architecture; see `cometchat-react-v7-features` + `COVERAGE.md`.)
+
+## Common pitfalls (BAKED)
+- Importing UI Kit CSS more than once, or overrides BEFORE the kit styles (specificity lost). Hardcoding hex in components instead of tokens. Assuming v6 theme classes — v7 uses `--cometchat-*` tokens + `data-theme`; fetch current names.
+- **Writing a per-theme override as `[data-theme="dark"] .cometchat { … }` — it matches NOTHING and silently no-ops.** The provider puts `data-theme` and `class="cometchat"` on the SAME div, so there is no `.cometchat` nested inside a `[data-theme]` ancestor. Use `.cometchat[data-theme="dark"]` (same element) for brand tokens, or `[data-theme="dark"] .cometchat-<bem>` (ancestor + kit-internal descendant, the kit's own pattern) to retint an internal. (Verified vs 7.1.0.)
+- **Hand-write brand/per-theme overrides — do NOT put per-theme tokens (colors, background, font) on bare `:root` (AUDIT-049/057).** A background or font pinned on `:root` has LOWER specificity than the kit's own `.cometchat[data-theme]` tokens, so it either loses (font silently doesn't apply) or forces the light value even in dark mode (breaks the OS-follow default, AUDIT-004/033). Scope every per-theme token to `.cometchat[data-theme="light"]` / `.cometchat[data-theme="dark"]` (theme-independent tokens like radii can stay on bare `.cometchat`). Theming is the SKILL's job — hand-write the scoped CSS (there is no CLI codegen for it).
+- **Setting a background on a WRAPPER to differentiate a nested surface, and expecting it to show.** An opaque kit sub-surface (the message list paints its own `--cometchat-message-list-bg`) covers the wrapper background — the wrapper bg only shows through non-opaque children. To differentiate the sub-surface, override THAT surface's own token (above), never the wrapper alone and never its internal `.cometchat-*` class. This is why the thread message-list keeps looking undifferentiated from the main list even after a thread-wrapper background is set (AUDIT-020/024).
+- **Assuming the kit follows the OS theme — it doesn't.** `theme` defaults to `light` and there's no `theme="system"`; a plain integration ignores the user's OS dark-mode setting. Sync to `prefers-color-scheme` if OS-follow is wanted (AUDIT-004).
+
+## Verify it works
+Your theme / `--cometchat-*` overrides apply in the running app (colors, light/dark), and the kit CSS is imported once at the app root.
+
+**Close (after it builds):** end with the shared 3-option selectable menu and WAIT for the pick — **① add another feature** (suggest a few not-yet-wired) · **② customize theming** (further tweaks) · **③ test it manually** (stop; let the user check). Tailor suggestions to what's not yet done. Same contract as the `cometchat-react-v7-core` close (`RULES.md` §19).

package/skills/cometchat-react-v7-features/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: cometchat-react-v7-features
+description: "Enable a specific CometChat feature in a React v7 app — reactions, polls, stickers, mentions, translation, link preview, smart replies and other AI, calls, push notifications, moderation. Looks the feature up in the features.json oracle, then wires enablement. Triggers: 'add reactions', 'enable polls', 'turn on smart replies', 'enable message translation', 'add voice/video calling'."
+license: "MIT"
+compatibility: "React >=18; @cometchat/chat-uikit-react ^7 (7.1.x, verified 7.1.0)"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat react features extensions ai calls push moderation v7"
+---
+
+> **Ground truth:** the feature existence oracle is `features.json` (pack root). A feature a user asks for MUST be an `id` there — if it's not listed, it does not exist; do not invent it. Exact enablement steps + current dashboard nav + config keys: FETCH from the feature's `docs_topic` (docs flag dashboard paths as fragile). UI component names come from the `web-v7` catalog. Status: **oracle curated from live docs 2026-07-29; entries marked VERIFY need confirming before shipping enablement steps.**
+
+## Companion skills (read first)
+- `cometchat-react-v7-core` — install, credentials, `init→login→render`, provider. This skill ASSUMES it.
+- `cometchat-react-v7-components` — the component catalog features render through.
+
+## Use this skill when
+The user wants to turn ON a specific capability: "add reactions", "enable polls", "turn on smart replies", "add push notifications", "enable message translation", "add calling", "add moderation".
+
+## Prerequisites & install
+Core setup done (credentials + init/login). Most features add no package; `voice-video-calls` needs the separate calls package.
+
+## Enable a feature (BODY — the oracle-driven flow)
+1. **Look it up in `features.json`.** Match the request to a feature `id`. Not listed → tell the user it isn't an available feature (don't invent one).
+2. **Branch on `category` + `enablement`:**
+   - `default` / `auto` → the SDK-side capability is on, but **check `needs_stitching` first**. If `needs_stitching: true`, the drop-in renders a default-ON affordance that is INERT/partial until the host wires it — you MUST either stitch it (callback + companion panel/component) or hide it; never leave it dead-ending (see the "Default-on affordances" pitfall). Otherwise nothing to enable — point at the `ui_components` if they want to surface/customize it.
+   - `extension` + `dashboard-extension` → enable the extension, then wire the client. **Two ways to enable: (a) via the CLI — `npx @cometchat/skills-cli@3 features enable <id>` flips the dashboard toggle via the API (reads the App ID from `.cometchat/config.json`; `features list` shows current state); OR (b) manually in the CometChat Dashboard → Extensions.** Offer the CLI (faster), fall back to the dashboard. The CLI only flips the toggle — YOU still wire the client component/prop. FETCH the current dashboard steps from `docs_topic` — do not bake the path.
+   - `ai` → enable via **dashboard-toggle** (AI User Copilot) AND wire the code prop — NOT zero-code (AUDIT-009). The toggle can be flipped by the CLI too — `@cometchat/skills-cli@3 features enable <id>` (an AI feature may first need an OpenAI key set on the app; the CLI reports that). Then wire the props: The copilot props DEFAULT TO OFF, so nothing appears until you set them: smart-reply → `showSmartReplies` on `CometChatMessageList` (default false; renders in the list FOOTER, not the composer); conversation-starter → `showConversationStarters` on `CometChatMessageList` (default false); conversation-summary → `showConversationSummaryButton` + `onSummaryClick` on `CometChatMessageHeader` (default false). These are `needs_stitching:true`. Only `ai-assistant` renders a distinct component (`CometChatAIAssistantChat`). Plan-gating is often 'unknown' — verify, don't assert.
+   - `package-install` (calls) → install the separate calls package (FETCH the exact coordinate/version from `docs_topic`), then wire the `ui_components`.
+   - **No UI Kit component (SDK-backed feature)** → the capability exists in the SDK but the UI Kit ships NO component for it (AI agents, campaigns, advanced/AI moderation, bots, webhooks, transient messages). Wire it from the **JavaScript Chat SDK** directly — look the exact method up in `cometchat-react-v7-core/references/docs-map.md` → **SDK docs** (the `llms.txt` index → the feature's page → its **AI-Integration-Quick-Reference accordion** for the method signatures; e.g. AI agents → `CometChat.addAIAssistantListener(...)`). This is the UI-Kit-first / SDK-fallback rule (`RULES.md`) — don't skip the feature and don't hand-roll what the SDK already exposes.
+   - `dashboard-only` (moderation) → configured ENTIRELY in the dashboard; emit **ZERO moderation UI code (AUDIT-078)**. Its `ui_components` (`CometChatModerationView` / `CometChatFlagMessageDialog`) are **AUTO-RENDERED / INTERNAL**, NOT host-wired: the kit auto-shows the moderation **footer** for blocked/pending messages (`CometChatMessageList hideModerationView` defaults false = shown), and the message list already ships a **built-in "Report message" option** that opens the flag dialog internally. So do **NOT** hand-roll a custom Report option (plugin `getOptions`) and do **NOT** mount `CometChatFlagMessageDialog` yourself — that duplicates the built-in. The only work is in the **Dashboard**: set up the Rules Engine (auto block/flag on send) + turn ON **Report Message / Report User**; the kit then surfaces everything with no code. (Rules Engine is not a classic extension → the CLI can't toggle it; give the user the dashboard steps.)
+3. **Wire the UI** using only the feature's `ui_components` (they exist in the `web-v7` catalog); fetch exact props from each component's `.md` twin (`cometchat-react-v7-core/references/docs-map.md`). **If the feature is a whole TASK with an end-to-end guide (check the docs-map "Task guides (recipes)" section — e.g. group chat, search, threads, new-chat, message-privately, block/unblock), BUILD FROM the guide and COMPARE your implementation against it for completeness — then apply the hardening deltas on top (docs-maximal; docs-map). No matching guide? → wire the `ui_components` the normal way (above) + fetch props; the guide is an enhancement, not required.**
+4. **Respect VERIFY notes** — any entry noting VERIFY (or an `ai`/`e2e-encryption`/`moderation` entry) must be confirmed against live docs for plan-gating and exact slugs before you emit steps.
+
+## Advanced / extensibility recipes (curated — verified against installed 7.1.x types)
+
+### Custom message types → the message-plugin architecture
+v7 replaces v6's `CometChatMessageTemplate` with **plugins**. A custom message type is an object implementing `CometChatMessagePlugin` (`id`, `messageTypes`, `messageCategories`, `renderBubble`), registered on the provider. The `plugins` prop is MERGED with `defaultPlugins` internally — pass ONLY your extras; use `removePlugins` to override a built-in type.
+```tsx
+import { CometChatProvider } from "@cometchat/chat-uikit-react";
+import type { CometChatMessagePlugin } from "@cometchat/chat-uikit-react";
+
+const productCardPlugin: CometChatMessagePlugin = {
+  id: "product-card",
+  messageTypes: ["product_card"],      // your custom SDK message type
+  messageCategories: ["custom"],
+  renderBubble: (message) => <div className="product-card">{message.getSender().getName()}</div>,
+};
+
+<CometChatProvider plugins={[productCardPlugin]}>
+  <div>{/* your chat UI */}</div>
+</CometChatProvider>
+```
+> `CometChatProvider` REQUIRES `children`. Optional plugin-interface hooks: `getOptions`, `getLastMessagePreview`, `renderHeaderView`/`renderFooterView`, `getTextFormatters`. This is provider-level config — there's no standalone screen to render.
+
+### Text formatters / rich text
+The default text plugin already applies **@mentions, URLs, and markdown**. Add CUSTOM formatting by subclassing the abstract `CometChatTextFormatter` (`id` + `getRegex()` + `format()`) and passing it via the `textFormatters` prop on `CometChatMessageComposer` (input) and the bubble components — it is **NOT** a prop on `CometChatMessageList`. The built-in formatters (`CometChatMentionsFormatter`, `CometChatUrlFormatter`, `CometChatMarkdownFormatter`, `CometChatRichTextFormatter`) have **no-arg constructors**.
+```tsx
+import { CometChatMessageComposer, CometChatTextFormatter } from "@cometchat/chat-uikit-react";
+
+class HashtagFormatter extends CometChatTextFormatter {
+  readonly id = "hashtag-formatter";
+  getRegex() { return /#(\w+)/g; }
+  format(text: string) { return text.replace(this.getRegex(), '<span class="hashtag">#$1</span>'); }
+}
+
+<CometChatMessageComposer textFormatters={[new HashtagFormatter()]} />
+```
+> **The message LIST ignores these props** — its text bubbles use the text plugin's `getTextFormatters()` (default markdown + mentions + URL). To format hashtags in the list too, override that method via the provider: `plugins={[{ ...CometChatTextPlugin, getTextFormatters: () => [new CometChatMarkdownFormatter(), new CometChatMentionsFormatter(), new CometChatUrlFormatter(), new HashtagFormatter()] }]}` (provider plugins precede the defaults, so it wins; verified vs 7.1.0).
+> **RTE toolbar ≠ `textFormatters` (AUDIT-051).** The **rich-text editor TOOLBAR** (bold/italic/underline/lists/links buttons in the composer) is a SEPARATE feature: toggle it with the `enableRichTextEditor` PROP on `CometChatMessageComposer` — `<CometChatMessageComposer enableRichTextEditor />` — a prop, NOT a component swap. (There is **no** `CometChatCompactMessageComposer` in v7 — that was a v6 phantom.) `textFormatters` above is for CUSTOM inline formatters (hashtags, @mentions, custom markup); they're orthogonal and can be used together. (There is no CLI shortcut — the skill sets the `enableRichTextEditor` prop directly.)
+
+### Calls / push operational depth
+**Calls now has its own skill — `cometchat-react-v7-calls`.** For "add voice/video calling", route there: it bakes the install (`@cometchat/calls-sdk-javascript@5`, not bundled), the calling-on switch (`uiKit:{callsSDK:{}}` on `CometChatUIKit.initFromSettings` — the `initFromSettings` equivalent of the classic `setCallingEnabled(true)`), the root `CometChatIncomingCall` wiring, 1:1-rings-vs-group-joins, and the gotchas (idle-timeout in **ms**, zero-dimension call surface, Next.js SSR + webpack fallback, no group-ring, HTTPS/`getUserMedia`).
+**Push notifications → the `cometchat-react-v7-push` skill** (thin + docs-first: it fetches CometChat's notifications docs and bakes the hardening deltas + SDK symbols). Route "add push" there — do NOT re-derive push here (single source).
+
+## Common pitfalls (BAKED)
+- **Default-on affordances that need stitching** (`features.json` `needs_stitching: true`). Some drop-ins render a live-looking control BY DEFAULT that no-ops until the host wires it — do NOT treat these as "already on, nothing to do":
+  - `CometChatConversations` search bar (`showSearchBar` default `true`) only client-side-filters already-loaded conversation names — it is NOT real search. Wire `onSearchBarClicked` → open `CometChatSearch`, or hide it with `showSearchBar={false}`. (Real search may also need a Dashboard toggle — VERIFY.)
+  - `CometChatMessageList` thread-reply indicator / "Reply in Thread" no-ops until `onThreadRepliesClick` opens a thread panel (`CometChatThreadHeader` + `CometChatMessageList parentMessageId` + `CometChatMessageComposer parentMessageId`) — wire it or hide with `hideReplyInThreadOption`.
+  - Rule: never emit a default-on affordance that dead-ends. Either wire the destination or hide the trigger.
+- Emitting a feature/component below its `contracts.json` minimum (e.g. group details without ban/kick/scope) — always cover the full min_capabilities (deterministic minimum, same every prompt).
+- Claiming a feature that isn't in `features.json` (phantom feature) — the #1 hallucination here.
+- Emitting a baked dashboard nav path — it rots; FETCH it.
+- Rendering a feature's UI component without enabling its extension first (renders empty/no-ops).
+- **Hand-rolling moderation UI (AUDIT-078).** Moderation is dashboard-only AND auto-surfaced: the kit renders the moderation footer for blocked/pending messages and the message list already ships a built-in "Report message" option (which opens the flag dialog internally). Do NOT add a custom Report option (plugin `getOptions`) or mount `CometChatModerationView`/`CometChatFlagMessageDialog` yourself — that duplicates the built-in. Emit ZERO moderation UI code; the only work is the Dashboard Rules Engine + Report Message/User toggles.
+- Assuming an AI/E2EE feature is available on every plan — it's plan-gated; verify.
+
+## Verify it works
+The enabled feature actually works in the running app (reactions appear, a poll sends, smart replies show, etc.) and any Dashboard toggle it needs is ON. If it renders empty, the extension/feature likely isn't enabled in the CometChat Dashboard.
+
+**Close (after it builds):** end with the shared 3-option selectable menu and WAIT for the pick — **① add another feature** (suggest a few not-yet-wired) · **② customize theming** · **③ test it manually** (stop; let the user check). Same contract as the `cometchat-react-v7-core` close (`RULES.md` §19).

package/skills/cometchat-react-v7-migration/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: cometchat-react-v7-migration
+description: "Upgrade a React app from CometChat UI Kit v6 → v7 (`@cometchat/chat-uikit-react` ^6 → ^7). Reads the repo's CometChat usage, applies the breaking-change map (deps, symbol renames, RxJS events → `useCometChatEvents`, DataSource → plugins, templates → plugins, theme prop, calling), fetches the prop-by-prop guide, and verifies the build. Triggers: 'upgrade my v6 uikit to v7', 'migrate cometchat react v6 to v7', 'upgrade @cometchat/chat-uikit-react to v7', 'cometchat v6 to v7', 'bump cometchat uikit'."
+license: "MIT"
+compatibility: "React >=18 <21; FROM @cometchat/chat-uikit-react ^6 → ^7 (7.1.x, verified 7.1.0); @cometchat/chat-sdk-javascript ^4.1.13 (peer); dompurify ^3.3.1 required (install explicitly); rxjs removed"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat react migration upgrade v6 v7 uikit"
+---
+
+> **Ground truth:** migrates a React app **FROM `@cometchat/chat-uikit-react@6` TO `@7`**. v7 target symbols are catalog-verified vs installed 7.1.0; the v6→v7 breaking-change map is BAKED in `references/migration-guide.md` (distilled from the official migration docs + a real v6.5.4→v7.1.0 export diff). The exhaustive prop-by-prop table is FETCHED from the docs migration `.md` twins. **APPEND/transform the user's code — never wipe it; work on a branch and confirm before bulk edits** (`RULES.md`).
+
+## Companion skills (read first)
+- `cometchat-react-v7-core` — the v7 init/login/render + `CometChatProvider` the migrated app lands on. This skill ASSUMES it.
+- `cometchat-react-v7-components` — the v7 component catalog (the target names).
+
+## Use this skill when
+"upgrade my v6 UI Kit to v7", "migrate CometChat React v6→v7", "bump `@cometchat/chat-uikit-react` to v7". Precondition: the project currently has `@cometchat/chat-uikit-react@6`.
+
+## Migration workflow (BAKED)
+1. **Detect the starting point.** Confirm `package.json` has `@cometchat/chat-uikit-react@6` (already `@7` → STOP, nothing to migrate). Note the bundler (Vite/Next/CRA/React-Router/Astro → env prefix, per `cometchat-react-v7-patterns`) and whether the app uses calls / `rxjs` events / `DataSource` / message templates. **Work on a branch; transform in place, never delete the user's code.**
+2. **Update dependencies.** `npm install @cometchat/chat-uikit-react@7 @cometchat/chat-sdk-javascript@^4.1.13 dompurify@^3.3.1` then `npm uninstall rxjs` (v7 drops rxjs; **`dompurify` is required** — the kit imports it at runtime; install it explicitly per the official docs, even though it's in the kit's `dependencies`). If the app uses calling, bump the Calls SDK to the v7 major: `npm install @cometchat/calls-sdk-javascript@5` (v7 pins `^5.x` — verified; it is NOT the same major as the v6-era build). Enabling calling also moves: on the mandated `initFromSettings` path use `uiKit:{callsSDK:{}}` (not the classic `setCallingEnabled(true)`).
+3. **Scan the repo for v6 usage.** Grep for the removed/renamed symbols + patterns from `references/migration-guide.md`: `CometChatDocumentBubble`, `CometChatCompactMessageComposer`, `CometChatUrlsFormatter`, `CometChatTextHighlightFormatter`, any `*Events` (`CometChatMessageEvents`/`CometChatGroupEvents`/`CometChatCallEvents`/`CometChatUserEvents`/`CometChatConversationEvents`/`CometChatUIEvents`), `DataSource`/`DataSourceDecorator`/`ChatConfigurator`, `CometChatMessageTemplate` / `templates` prop, `textFormatters` prop **on `CometChatMessageList`/`CometChatConversations`** (gone from the lists in v7 — `textFormatters` itself is NOT removed; see pitfalls), `hideError`/`disableLoadingState` props, `data-theme` attribute, **localization** (`getLocalizedString(...)`, `CometChatLocalize`, unprefixed i18n keys like `group_info` that v7 moved under `sample_` — §7), `CometChatUIKitLoginListener`, and the removed standalone components (`CometChatEmojiKeyboard`/`CometChatMediaRecorder`/`CometChatToast`/`CometChatListItem`/`CometChatNotificationBadge`). Produce the concrete change list.
+4. **Apply the breaking-change map** (`references/migration-guide.md`): symbol renames, RxJS `*Events` → the `useCometChatEvents` hook, `DataSource`/`ChatConfigurator` → `CometChatMessagePlugin` + the `plugins` prop, `templates` prop → plugins (`textFormatters` is NOT removed — relocate it, see pitfalls), `data-theme` → the `theme` prop, calling → `uiKit:{callsSDK:{}}` on `initFromSettings` (step 2), **localization → the v7 method + map v6 keys to the bundled `sample_*` keys (or register via the INSTANCE method `CometChatLocalize.getSharedInstance()?.addTranslation(...)` — NOT a static) — see `migration-guide.md` §7; look up the EXACT key in the uikit source (`resources/<lang>/translation.json`) / docs / GitHub, never guess**. For any component's exact prop change NOT in the baked map, FETCH the prop-by-prop table via `cometchat-react-v7-core/references/docs-map.md` → `migration-property-changes`.
+5. **Wrap the chat tree in `CometChatProvider`** if it isn't already (v7 requires it above the components; init/login stay imperative and unchanged).
+6. **Verify.** Build/typecheck passes; NO v6 symbols remain (grep the removed names); the app renders inside `CometChatProvider`; migrated events/plugins/calling work. Reuse `cometchat-react-v7-core` "Verify it works".
+
+## Common pitfalls (BAKED)
+- **Leftover `rxjs` event subscriptions** — v6 `*Events.<x>.subscribe()` do NOT fire in v7; convert every one to `useCometChatEvents((event) => …)` (SDK + UI events share one bus). Publish via `usePublishEvent()`.
+- **Forgetting `CometChatProvider`** — v7 components read it; symptom = context/"not initialized" errors even though init ran.
+- **`CometChatMessageTemplate` / `templates` props** — removed from components; move custom message rendering to a `CometChatMessagePlugin` passed via `plugins`. **`textFormatters` is NOT removed** — it stays a prop in v7 (verified vs 7.1.0) on `CometChatMessageComposer`, the bubble components (Text/Image/Video/Audio/File/…), `CometChatSearch` and `CometChatMessageInformation`, but it is GONE from `CometChatMessageList`/`CometChatConversations`. Keep it as a prop on those components. The list's bubbles take formatters from the text plugin's `getTextFormatters()`, so to keep a v6 list-level formatter, override that one method — `plugins={[{ ...CometChatTextPlugin, getTextFormatters: () => [/* defaults + yours */] }]}` (provider plugins precede the defaults, so it wins).
+- **Dependency drift** — missing the new `dompurify` peer dep, or leftover `rxjs`, breaks the build; do both halves of step 2.
+- **Calling silently off** — v7 needs calling turned on in the init settings (`uiKit: { callsSDK: {} }` via `CometChatUIKit.initFromSettings`; or the classic `.setCallingEnabled(true)` on `UIKitSettingsBuilder`) — not a provider prop; without it, call buttons hide and the Calls SDK never loads.
+- **Bubble routing** — the message list now defaults to the multi-attachment bubbles (`CometChatImageBubble`→`CometChatImagesBubble`, singular `CometChatFileBubble` still ships); code that imported singular bubble names for the list default may need the plural.
+- **Don't mass-remove `hideError`** — it's removed from list components but **retained on `CometChatMessageComposer`**; `textFormatters` likewise still exists on the message-bubble components. Scope the removals; don't blanket-strip.
+
+## Verify it works
+Build/typecheck is green; a repo-wide grep finds NO removed v6 symbols (`CometChatDocumentBubble`, `CometChatCompactMessageComposer`, `*Events`, `DataSource`, `DataSourceDecorator`, `ChatConfigurator`, `CometChatMessageTemplate`, `CometChatUIKitLoginListener`); the app renders inside `CometChatProvider`; and any migrated events / plugins / calling work. Full prop-by-prop reference: fetch `migration-property-changes` via `cometchat-react-v7-core/references/docs-map.md`.