@cometchat/skills 5.0.0 → 5.0.1

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

@@ -0,0 +1,60 @@
+---
+name: cometchat-react-v7-testing
+description: "Test a React app that embeds CometChat v7 — what to mock vs exercise for real, rendering kit components under a test provider, waiting out the async init→login gate, and a lean E2E smoke. Triggers: 'test my cometchat react app', 'mock cometchat in jest/vitest', 'unit test chat component', 'playwright test for chat', 'how do I test cometchat'."
+license: "MIT"
+compatibility: "@cometchat/chat-uikit-react ^7 (7.1.x–7.2.x verified); React 18–19; Vitest / Jest / React Testing Library / Playwright"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat react v7 testing vitest jest playwright mock rtl"
+---
+
+> **Ground truth:** `@cometchat/chat-uikit-react@7`. Component/method names come from `cometchat-react-v7-core` + its catalog; signatures are FETCHED via `cometchat-react-v7-core/references/docs-map.md`. **The UI Kit docs have no dedicated testing page** — this is the pack's own guidance (tracked DOCS GAP). Never assert against kit-internal DOM classes; they are not a public contract.
+
+## Companion skills (read first)
+- `cometchat-react-v7-core` — the init→login→render lifecycle these tests exercise.
+
+## Use this skill when
+Adding tests around a CometChat integration, or a "how do I test this" question. NOT part of a normal build — only when tests are explicitly asked for (`RULES.md` → Verification scope).
+
+## Decide what you are testing
+You are testing **your** code, not CometChat's kit. Three layers:
+- **Your logic** (token fetch, UID mapping, routing, state) → unit-test in isolation, **mock the SDK**.
+- **Your wiring** (does the surface mount after init+login, are the right props passed) → render under a test provider with the SDK mocked.
+- **The real round-trip** (send → receive) → a thin E2E against a test app, not a unit test.
+
+Do not unit-test that `CometChatMessageList` renders messages — that is the kit's own test surface.
+
+## Mock the SDK in unit tests
+Mock the two entry modules so nothing hits the network and no real login is attempted:
+```tsx
+vi.mock("@cometchat/chat-sdk-javascript", () => ({ CometChat: { getLoggedinUser: vi.fn().mockResolvedValue(null) } }));
+vi.mock("@cometchat/chat-uikit-react", async (orig) => ({
+  ...(await orig()),
+  CometChatUIKit: { initFromSettings: vi.fn().mockResolvedValue(null), getLoggedInUser: vi.fn().mockReturnValue(null), login: vi.fn().mockResolvedValue({ getUid: () => "u1" }), loginWithAuthToken: vi.fn().mockResolvedValue({ getUid: () => "u1" }), logout: vi.fn().mockResolvedValue(undefined) },
+}));
+```
+(Jest: swap `vi` for `jest`.) Now assert your own token-fetch and error handling without a backend.
+
+## Render the surface under test
+The kit surface mounts only **after** init+login resolve. Tests must await that gate, not assert synchronously:
+```tsx
+render(<App />);
+expect(await screen.findByText(/sign in|loading|chats/i)).toBeInTheDocument();
+```
+Prefer `findBy*` (async) over `getBy*`; a synchronous query runs before the init promise settles and fails intermittently. Wrap the surface in `CometChatErrorBoundary` in the app so a thrown error surfaces as a testable fallback, not an unhandled rejection.
+
+## E2E smoke (Playwright)
+One high-value path against a **real test app** (seeded users, dev Auth Key in a test-only env): load the app, sign in, assert the conversation list renders with real height and a message can be sent. Assert on **your** visible text/roles and the presence of the mounted surface — not on kit BEM classes. Keep it to the happy path plus one auth-failure path; the kit's internals are already tested upstream.
+
+## Not worth automating
+Kit component internals, exhaustive prop matrices, live calls/push (device-dependent), and pixel snapshots of kit UI (they churn across minor kit versions). Spend the budget on your token flow, UID mapping, and the init-gate wiring.
+
+## Common pitfalls
+1. **Synchronous assertions before init resolves** — flaky; use `findBy*`/`waitFor`.
+2. **Asserting on kit DOM classes** — they change across versions; assert your own markup + roles.
+3. **A real login in unit tests** — mock `CometChatUIKit`; never ship a test Auth Key to prod env files.
+4. **StrictMode double-invoke** — mocks must be idempotent (return the same resolved user), mirroring the app's in-flight guard.
+
+## Verify it works
+Unit tests pass with the SDK mocked (no network) · the surface test awaits the init gate and finds the mounted UI · the E2E smoke signs in and renders conversations against a test app · no test asserts a kit-internal class.

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

@@ -0,0 +1,47 @@
+---
+name: cometchat-react-v7-troubleshooting
+description: "Diagnose a broken CometChat React v7 integration — blank panes, a collapsed/0-height surface, empty lists, no messages, the kit's error state, events that never fire, or a version_conflict. Triggers: 'cometchat react not working', 'chat is blank', 'conversations empty', 'messages not showing react', 'something went wrong cometchat', 'cometchat react errors', 'why is my chat broken'."
+license: "MIT"
+compatibility: "@cometchat/chat-uikit-react ^7 (7.1.x–7.2.x verified); React 18–19; Vite / Next.js / CRA / React Router / Astro"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat react v7 troubleshooting debug diagnostics blank-screen version-conflict"
+---
+
+> **Ground truth:** `@cometchat/chat-uikit-react@7`. Symbols/signatures are verified against `cometchat-react-v7-core` + its catalog and FETCHED via `references/docs-map.md`; the rules referenced (init order, layout sizing, credentials) are `RULES.md`. This diagnostics catalog is cross-checked against the live `{DOCS_BASE}/ui-kit/react/troubleshooting.md` page (base + paths in `cometchat-react-v7-core/references/docs-map.md`), and adds the host-side/runtime symptoms it doesn't cover.
+
+## Companion skills (read first)
+- `cometchat-react-v7-core` — the correct init→login→render order, credentials, and the reflow-free layout the fixes below restore.
+
+## Use this skill when
+A React CometChat integration compiles but misbehaves at runtime: blank, empty, unresponsive, or throwing.
+
+## Start here — React fails on the ORDER and the BOX
+Two causes explain most "it's blank":
+1. **A kit component rendered before `init()` + `login()` resolved.** The surface must be gated on the resolved logged-in user. Rendering it eagerly (or during SSR) yields an empty/erroring pane.
+2. **The container has no height.** The kit fills its parent; a parent at `height:auto`/`0` collapses it to a sliver. This is a host CSS defect, not a kit bug (`RULES.md` → Layout / sizing).
+
+## Symptom → cause → fix
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| Blank/white, no errors | Surface rendered before init+login resolved | Gate render on the resolved user; keep `CometChatErrorBoundary` for a visible fallback |
+| Blank during SSR / `window is not defined` | A kit component imported or rendered on the server (Next.js, Astro, Remix) | Render the surface client-only — `"use client"` + `dynamic(..., { ssr:false })` (Next), `client:only` (Astro); see core `references/ssr.md` |
+| Surface ~0px / cramped top-left | Ancestor chain has no height | `html,body,#root{height:100%}` + a pinned surface (`100dvh` full-app) + panes `min-height:0`; see core `references/layout.md` |
+| "OOPS! Looks like something went wrong" | The kit's error state — a call threw (often a custom `ConversationsRequestBuilder` with no `.setLimit(n)`, or a bad Region) | Add `.setLimit(30)`; confirm Region matches the dashboard app |
+| Conversations empty | New/seeded app has no conversations yet, or scope excludes them | Send a first message; check `conversationsRequestBuilder` scope (`user`/`group`) matches intent |
+| `login()` fails "user not found" | UID does not exist in the app | Use a real UID (Dashboard → Users; fresh apps seed `cometchat-uid-1`) — never a guessed `superhero*` |
+| Nothing updates live | Missing/duplicated listeners, or StrictMode double-mount | Add listeners with a stable ID, remove on unmount; guard the init/login in-flight (`cometchat-react-v7-patterns`) |
+| Roster rows appear TWICE + ~30 "duplicate key" errors (dev only) | React **StrictMode** double-invokes effects; the roster drop-ins `CometChatUsers`/`CometChatGroups`/`CometChatGroupMembers` double-append (kit de-dupe gap; `CometChatConversations` is unaffected) | A dev-only StrictMode artifact — gone in `vite build`/prod. Do **NOT** remove StrictMode to "fix" it; verify the roster in a production build. Kit issue — report upstream |
+| Localized keys shown raw (e.g. `group_info`) | Wrong/stale i18n key or provider missing | Use the kit component / correct key; ensure `CometChatProvider` wraps the tree |
+| Works in dev, blank in prod | Wrong env prefix → Auth Key/App ID missing in the bundle | Fix the bundler prefix; grep the build (`cometchat-react-v7-production`) |
+| `version_conflict` on detect | Project on UI Kit v6 while skills target v7 | STOP and reconcile — migrate v6→v7 (`cometchat-react-v7-migration`), or stay on v6 by installing the older **v4 skills pack** (it targets the v6 UI Kit) |
+
+## When the table does not cover it
+Open the browser console + network tab: a `401` is auth (bad token/Auth Key/Region), a `402` is a plan-gated feature (e.g. Search — enable it in the dashboard), a `4xx` "no conversation yet" is benign. Then fetch the feature's page via `cometchat-react-v7-core/references/docs-map.md`. Never diagnose from `node_modules`/`.d.ts` or memory.
+
+## Verify it works
+Init+login resolve before the surface renders · the surface has real dimensions (not a sliver) · conversations render or show the kit's empty state (not the error state) · a message sends and arrives live · no raw localization keys · production build carries no Auth Key.
+
+## What NOT to do
+Do not silence the error boundary to hide a thrown call; do not hard-code a UID to dodge "user not found"; do not read kit internals to work around a missing prop — fetch the documented prop instead.

package/skills/cometchat-security/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: cometchat-security
+description: "Enterprise auth & access control for CometChat — SSO/OIDC/SAML via your own IdP, server-minted auth tokens, token revocation & session control, and role-based access (RBAC app-wide roles + group scopes). Cross-family: the server/REST side is the same everywhere; client login lands in each family's core/production skill. Triggers: 'add SSO to cometchat', 'SAML/OIDC login', 'okta/auth0/cognito with cometchat', 'role based access control', 'restrict what a user can do', 'revoke a user session', 'rotate/flush auth tokens', 'secure cometchat for enterprise', 'multi-tenant cometchat'."
+license: "MIT"
+compatibility: "CometChat REST API v3 (auth tokens · roles · users · group members). Client login via any family's UI Kit / SDK. Server: any language over HTTPS."
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat security sso saml oidc rbac roles auth-token session enterprise multi-tenant"
+---
+
+> **Ground truth:** every REST shape here is FETCHED from the live docs — `{DOCS_BASE}/rest-api/auth-tokens`, `/rest-api/roles`, `/rest-api/rbac-overview`, `/rest-api/users`, `/rest-api/group-members` (`DOCS_BASE = https://www.cometchat.com/docs`; append `.md` for the raw twin). **CometChat is NOT an identity provider** — it does not do SAML/OIDC for your end users. "SSO with CometChat" means *your* IdP authenticates the user, then *your server* mints a CometChat auth token for that user's UID. Verify signatures against the docs; never invent an endpoint.
+
+## Use this skill when
+Taking a CometChat integration through an enterprise security review: SSO with your IdP, role-based permissions, session revocation, multi-tenant isolation, or "make our chat secure/compliant to ship." Client-side login wiring itself lives in `cometchat-<family>-core` / `-production`; this skill owns the server + access-control model those depend on.
+
+## The auth model (get this right first)
+Three credentials, three homes — mixing them up is the #1 security defect:
+
+| Credential | Who holds it | Purpose |
+| --- | --- | --- |
+| **Auth Key** | client, **dev only** | quick `login(uid)` in development; can mint a session for ANY user — never ship it |
+| **Auth token** | client, per user | production login with a per-user token — the call is per family (web/Angular/Android/Flutter `loginWithAuthToken(token)`, **iOS `login(authToken:)`**, **React Native `login({ authToken })`**); tied to one UID; revocable |
+| **REST API Key** | **server only** | mint tokens, manage users/roles; full power — never in a client |
+
+Production login is always **auth token**, never the Auth Key. Detail + the per-framework client call: `cometchat-<family>-production`.
+
+## SSO / OIDC / SAML — through YOUR IdP
+CometChat rides on the identity you already have. The flow is the same whether your IdP is Okta, Auth0, Cognito, Entra ID, Google Workspace, or your own:
+
+1. The user signs in through your IdP (SAML/OIDC) — your normal app auth.
+2. Your backend, on that **authenticated session**, maps the IdP subject to a CometChat **UID** (a stable, sanitized id — see `cometchat-migrate-from-*` `toCometChatId` for the alpha-dash/≤100/lowercase rules) and, if the user is new, creates it (`POST {DOCS_BASE}/rest-api/users`, `withAuthToken: true` returns a token in the same call).
+3. Your backend mints an auth token: `POST /v3/users/{uid}/auth_tokens` with the **REST API Key** (`{DOCS_BASE}/rest-api/auth-tokens/create`).
+4. It returns the token to the client over the authenticated request; the client logs in with it via its per-family call (web/Angular/Android/Flutter `loginWithAuthToken(token)`, iOS `login(authToken:)`, React Native `login({ authToken })` — see `cometchat-<family>-production`).
+
+**The UID must come from the server session, never a request parameter.** Accepting `?uid=` lets any caller impersonate anyone — the single most common CometChat auth hole.
+
+```http
+POST https://{APP_ID}.api-{REGION}.cometchat.io/v3/users/{uid}/auth_tokens
+apikey: {REST_API_KEY}          # server-side secret
+content-type: application/json
+```
+
+## Session control & revocation
+Auth tokens **do not expire by default** and CometChat keeps a **rolling 100 per user** (oldest auto-archived). For enterprise session control:
+- **Log out one device** → `DELETE /v3/users/{uid}/auth_tokens/{authToken}`.
+- **Kill every session** (deprovisioned employee, suspected compromise) → `DELETE /v3/users/{uid}/auth_tokens` (flush all).
+- **Rotate on privilege change / password reset** → mint a fresh token, flush the rest.
+- **Short-lived sessions** → issue a token per login and flush on logout; don't reuse one token forever.
+Pages: `{DOCS_BASE}/rest-api/auth-tokens/{delete,flush}`.
+
+## Access control — RBAC (app-wide) + SBAC (per group)
+CometChat has two layers; an action must pass **both** or the API returns `ERR_PERMISSION_DENIED`:
+
+| Layer | Scope | Set via | Use it for |
+| --- | --- | --- | --- |
+| **Role (RBAC)** | whole app, one role per user | user create/update (`/rest-api/users`), roles (`/rest-api/roles`) | who may create groups, send messages, start calls, … |
+| **Scope (SBAC)** | inside one group | group membership (`/rest-api/group-members/change-scope`) | `admin` / `moderator` / `participant` within that group |
+
+- Define roles server-side via the REST **Roles** endpoint (`POST https://{APP_ID}.api-{REGION}.cometchat.io/v3/roles`; see the docs at `{DOCS_BASE}/rest-api/roles`) — each user gets exactly one; unspecified → `default`.
+- Set the fine-grained permissions per role via **RBAC** (`{DOCS_BASE}/rest-api/rbac-overview`). *(The older per-role `restrict-features` API is **deprecated** — use RBAC.)*
+- Group scopes (`admin`/`moderator`/`participant`) are the SBAC layer; change with the change-scope API.
+Model least privilege: a locked-down `default` role, elevated roles for staff/moderators, plus group scopes for in-group moderation.
+
+## Multi-tenant isolation
+- **Strongest:** one CometChat **app per tenant** (separate App ID/keys — full data isolation). Best for regulated or contractual isolation.
+- **Lighter:** one app, tenant-scoped **groups** + a tenant id in user/message **metadata**, enforced by your token server (a user only ever gets a token for their tenant's UID) + RBAC. Cheaper, but isolation is only as strong as your server checks.
+Pick per your compliance bar; document which you chose. Data residency/region selection is `cometchat-compliance`; self-hosting for full sovereignty is `cometchat-self-host`.
+
+## Common pitfalls
+1. **Auth Key shipped to the client in production** — it can log in as anyone. Grep the bundle/binary (`cometchat-<family>-production`).
+2. **Token endpoint trusting a client-supplied UID** — impersonation. Derive the UID from the server session.
+3. **"CometChat SSO" misread as CometChat being the IdP** — it isn't; integrate your IdP, then mint a token.
+4. **No revocation on offboarding** — a deprovisioned user keeps chatting until you flush their tokens.
+5. **RBAC assumed but never configured** — every user sits on `default`; define roles + permissions explicitly.
+6. **Using the deprecated `restrict-features`** instead of RBAC.
+7. **REST API Key in client or repo** — server-only; store in a secret manager.
+
+## Verify it works
+IdP login → server mints a token from the session UID → the client's per-family auth-token login succeeds (`loginWithAuthToken` / iOS `login(authToken:)` / RN `login({ authToken })`) · a tampered/`?uid=` request is rejected · flushing a user's tokens ends their sessions on every device · a `default`-role user is denied a restricted action (`ERR_PERMISSION_DENIED`) while an elevated role is allowed · no Auth Key or REST API Key anywhere in client code.

package/skills/cometchat-self-host/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: cometchat-self-host
+description: "Run CometChat on your own infrastructure — when to self-host, the deployment models (Docker Swarm, Kubernetes, air-gapped), sizing & prerequisites, and how to point your app at the self-hosted instance. CometChat's enterprise differentiator: full data sovereignty. Triggers: 'self-host cometchat', 'on-prem cometchat', 'on premise deployment', 'private cloud chat', 'air-gapped chat', 'run cometchat in our own cloud/VPC', 'data sovereignty', 'point my app at self-hosted cometchat'."
+license: "MIT"
+compatibility: "CometChat on-premise (Docker Swarm 10k–200k MAU · Kubernetes 200k+ / multi-region · air-gapped). Clients: any CometChat UI Kit / SDK pointed at your domain."
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat self-host on-prem on-premise kubernetes docker air-gapped data-sovereignty private-cloud enterprise"
+---
+
+> **Ground truth:** deployment detail is FETCHED from the live on-premise docs — `{DOCS_BASE}/on-premise-deployment/docker/overview`, `/docker/prerequisites`, `/docker/production-deployment`, `/docker/security`, `/docker/persistence-and-backup`, `/docker/configuration-reference`, `/docker/air-gapped-deployment`, and `/kubernetes/overview` (`DOCS_BASE = https://www.cometchat.com/docs`; append `.md`). On-prem is a licensed enterprise offering — **[contact CometChat sales](https://www.cometchat.com/contact-sales)** for the images, license, and support. The exact **client host-override** field is in the on-prem client/configuration docs — fetch it there; do not guess a setting name.
+
+## Use this skill when
+The customer needs the chat backend inside their own perimeter: data sovereignty, an offline/air-gapped network, a regulated industry, a residency clause the SaaS regions can't meet, or fixed-cost infrastructure instead of per-MAU SaaS pricing. Self-hosting (on-premise deployment) is a CometChat enterprise offering — position it as a differentiator, but don't assert what specific competitors do or don't offer without checking their current docs.
+
+## Why self-host (vs the SaaS regions)
+- **Data sovereignty** — all data (messages, media, backups) stays on infrastructure you control, which supports your GDPR/HIPAA/SOC 2 and residency obligations (compliance is the customer's to certify; self-hosting removes the SaaS data-location constraint). (Region selection in SaaS is `cometchat-compliance`; self-host is the stronger step.)
+- **Air-gapped / private network** — deploy with no public internet dependency (`/docker/air-gapped-deployment`).
+- **Predictable economics** — fixed infra cost, no per-user SaaS pricing.
+- **Operational control** — your monitoring, your security perimeter, direct component access.
+
+## Deployment models (pick by scale)
+| Model | Target | Use when |
+| --- | --- | --- |
+| **Docker Swarm** | ~10k–200k MAU, ~20k peak concurrent | most on-prem deployments; lower operational overhead (`/docker/overview`) |
+| **Kubernetes** | 200k+ MAU, multi-region active-active, autoscaling | large scale or multi-region (`/kubernetes/overview`) |
+| **Air-gapped** | offline / isolated networks | export images, transfer, run from a local registry (`/docker/air-gapped-deployment`) |
+
+The platform is microservices (WebSocket gateway · Chat API · Moderation · Notifications · Webhooks) over a Kafka event bus, with TiDB (distributed SQL) + MongoDB + Redis and optional S3-compatible object storage. You don't wire these by hand — the deployment scripts do — but size the hosts for them (`/docker/prerequisites`).
+
+## Prerequisites & sizing (before you deploy)
+Plan from **MAU and peak concurrent connections (PCC)**: host sizing, OS, storage volumes for the stateful services (databases, Kafka, object storage), and TLS certificates for the load balancer. The full checklist is `{DOCS_BASE}/on-premise-deployment/docker/prerequisites`; follow it rather than improvising capacity.
+
+## Deploy (the runbook is the docs, not this file)
+Deployment uses CometChat's automated scripts for consistent, zero-downtime rollouts — `{DOCS_BASE}/on-premise-deployment/docker/production-deployment`. Domains/environment values are set per `/docker/configuration-reference` (+ the domain-update guide). Do not hand-assemble the compose/stack; drive the documented scripts.
+
+## Point your app at the self-hosted instance
+Clients reach on-prem over **HTTPS + WebSocket** through your load balancer / NGINX (TLS-terminated). In the app, the CometChat init settings must target **your domain** instead of the SaaS region endpoint — the exact host/region-override field is in the on-prem client-integration + `configuration-reference` docs; **fetch it there and set it**, then keep everything else (App ID, login flow) the same. Every family's init lives in `cometchat-<family>-core`; only the host target changes for on-prem. Verify the app connects to your domain (not `*.cometchat.io`) in the network tab.
+
+## Security & operations
+- **Auth**: on-prem uses JWT-based authentication with RSA key pairs — only authorized users reach the platform (`{DOCS_BASE}/on-premise-deployment/docker/security`). Combine with the app-level access model in `cometchat-security`.
+- **Network**: keep data stores on the private overlay; expose only the load balancer; enforce TLS end-to-end.
+- **Backups & DR**: automated backups with point-in-time recovery and retention aligned to your compliance policy (`/docker/persistence-and-backup`) — this is where you own the retention lifecycle `cometchat-compliance` defers to.
+- **Monitoring**: the stack ships Prometheus + Grafana + Loki; wire alerts to your on-call.
+
+## Common pitfalls
+1. **Treating on-prem as self-serve** — it's a licensed offering; start with sales for images + license + support.
+2. **Under-sizing** — plan hosts from MAU/PCC via the prerequisites, not a guess.
+3. **Hand-writing the stack** — use the documented deployment scripts; drift breaks upgrades.
+4. **App still pointing at `*.cometchat.io`** — set the client host override to your domain, or you're on SaaS, not on-prem.
+5. **Guessing the host-override field** — fetch the exact setting from the on-prem client docs.
+6. **No TLS / exposed data stores** — terminate TLS at the LB and keep TiDB/Mongo/Redis/Kafka on the private network.
+
+## Verify it works
+The stack deploys via the documented scripts and health checks pass · the app connects to YOUR domain over HTTPS/WSS (confirmed in the network tab), logs in, sends and receives · JWT/RSA auth is enforced · data stores are private + TLS everywhere · backups run and a restore is tested · Grafana shows the services healthy.

package/test-suite/catalogs/flutter-calls-v5.json

@@ -189,7 +189,7 @@
           "video_stream_modes.dart",
           "video_stream_positions.dart"
         ],
-        "note": "All six were already in internalOnlyExcluded — never reachable from the barrel — so deleting them changed nothing here. `CallType` is the same phantom cometchat-team/cometchat-skills#183 filed on iOS."
+        "note": "All six were already in internalOnlyExcluded — never reachable from the barrel — so deleting them changed nothing here. `CallType` is the same phantom internal issue #183 filed on iOS."
       }
     }
   }

package/test-suite/scripts/lint-skills.mjs

@@ -62,14 +62,17 @@ const nestedKey = (b, k) => (b.match(new RegExp("^\\s+" + k + ":\\s*(.+)$", "m")
 // named `cometchat-<slug>` and are routed via peers.yaml's `gate:` / top-level pointers
 // (the entry router ALWAYS routes to the gate first), NOT via a peer's `skills:` list —
 // so they must be recognized here instead of failing the per-platform grammar.
-const CROSS_FAMILY_SLUGS = new Set(["a11y", "i18n", "onboarding"]);
+const CROSS_FAMILY_SLUGS = new Set(["a11y", "i18n", "onboarding", "security", "compliance", "self-host", "moderation", "audit", "analytics"]);
+// Competitor-migration skills are cross-family too (one per vendor, installed for every family):
+// `cometchat-migrate-from-<vendor>`, routed via peers.yaml `migrations:` (NAMING.md).
+const COMPETITOR_MIGRATION = /^cometchat-migrate-from-([a-z0-9]+)$/;
 
 // The gates grafted below were authored for the ANGULAR family + the shared skills. Other
 // families are maintained elsewhere; applied pack-wide they turned this repo's 15
 // pre-existing problems into 123 by firing on 40+ android/ios/flutter/rn skills. A gate we
 // wrote must not fail a family we do not own — same scoping the token and fence gates need.
 const OWNED_SKILL = (d) =>
-  /^cometchat-angular-v5-/.test(d) || d === "cometchat" || d === "cometchat-onboarding";
+  /^cometchat-angular-v5-/.test(d) || d === "cometchat" || d === "cometchat-onboarding" || COMPETITOR_MIGRATION.test(d);
 
 // Parse the capability slugs each peer routes to (peers.yaml `skills: [...]`), plus the
 // platform-neutral routing pointers (`gate:` and any bare cross-family targets).
@@ -86,6 +89,14 @@ function routedSlugs() {
   // `gate: cometchat-onboarding` (and any future bare cross-family pointer) → routed.
   const gate = (y.match(/^\s*gate:\s*(\S+)/m) || [])[1];
   if (gate) neutral.add(gate.trim());
+  // `migrations:` entries (`skill: cometchat-migrate-from-<vendor>`) → routed, platform-neutral.
+  const mig = (y.match(/^migrations:\s*\n([\s\S]*?)(?=^\S)/m) || [])[1] || "";
+  for (const m of mig.matchAll(/^\s*skill:\s*(\S+)/gm)) neutral.add(m[1].trim());
+  // `enterprise:` cross-family skills (bare `- cometchat-<slug>`) → routed, platform-neutral.
+  const ent = (y.match(/^enterprise:\s*\n([\s\S]*?)(?=^\S)/m) || [])[1] || "";
+  for (const m of ent.matchAll(/^\s*-\s*(\S+)/gm)) neutral.add(m[1].trim());
+  const cf = (y.match(/^crossFamily:\s*\n([\s\S]*?)(?=^\S)/m) || [])[1] || "";
+  for (const m of cf.matchAll(/^\s*-\s*(\S+)/gm)) neutral.add(m[1].trim());
   return { platforms, slugs, neutral };
 }
 
@@ -109,8 +120,10 @@ const PLATFORMS = ["react-native", "react", "angular", "android", "flutter", "io
 // sanctions for react-native specifically). So every correctly-named RN skill was rejected.
 // Same class as the six --family hardcodes (AUDIT-091/087): a rule written for one family.
 function classify(dir) {
-  const c = dir.match(/^cometchat-([a-z0-9]+)$/);
+  const c = dir.match(/^cometchat-([a-z0-9-]+)$/);
   if (c && CROSS_FAMILY_SLUGS.has(c[1])) return { crossFamily: true, slug: c[1] };
+  const v = dir.match(COMPETITOR_MIGRATION);
+  if (v) return { crossFamily: true, slug: `migrate-from-${v[1]}` };
   for (const p of PLATFORMS) {
     let m = dir.match(new RegExp(`^cometchat-${p}-(v\\d+)-([a-z][a-z-]*)$`));
     if (m) return { platform: p, major: m[1], slug: m[2] };
@@ -146,7 +159,7 @@ function lintSkill(dir, routed) {
     // whichever family core the plan/context names). Routed via a neutral pointer
     // (peers.yaml `gate:` / entry), not a peer's `skills:` list.
     if (!routed.neutral.has(dir)) {
-      errs.push(`cross-family skill "${dir}" not routed in peers.yaml (add it as gate: or a neutral pointer)`);
+      errs.push(`cross-family skill "${dir}" not routed in peers.yaml (add it as gate:, a neutral pointer, or a migrations: skill)`);
     }
   } else {
     // Companion block — required on every non-core per-platform skill (BUILD-ORDER DRY rule).
@@ -317,10 +330,16 @@ function gateOsThemeRecipe() {
 // reference initFromSettings, and the canonical lifecycle recipe must not use the classic init(.
 function gateInitTelemetry() {
   const errs = [];
-  const coreDirs = readdirSync(SKILLS_DIR, { withFileTypes: true })
-    .filter((d) => d.isDirectory() && d.name.endsWith("-core"))
+  const allDirs = readdirSync(SKILLS_DIR, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
     .map((d) => d.name);
-  for (const dir of coreDirs) {
+  // Skills that teach an init recipe: UI-Kit cores AND the headless / SDK-fallback skills (`-sdk`).
+  // Both must attribute via initFromSettings, never the classic builder init. The check was
+  // originally core-only, which let a `-sdk` fallback skill (cometchat-react-native-sdk) ship the
+  // classic `CometChat.init(APP_ID, settings)` in its golden path — a `-sdk` skill is exactly the
+  // SDK-fallback surface (e.g. rn-uikit-v5.sdkSkill), so it must obey the same rule. (AUDIT-084; ENG-39197.)
+  const initSkills = allDirs.filter((d) => d.endsWith("-core") || d.endsWith("-sdk"));
+  for (const dir of initSkills) {
     for (const rel of [`${dir}/references/lifecycle.md`, `${dir}/SKILL.md`]) {
       const p = join(SKILLS_DIR, rel);
       if (!existsSync(p)) continue;
@@ -334,6 +353,10 @@ function gateInitTelemetry() {
         );
       }
     }
+  }
+  // UI-Kit cores only: the baked lifecycle recipe must not default to the classic CometChatUIKit.init(.
+  const coreDirs = allDirs.filter((d) => d.endsWith("-core"));
+  for (const dir of coreDirs) {
     const lc = join(SKILLS_DIR, `${dir}/references/lifecycle.md`);
     if (existsSync(lc) && /CometChatUIKit\.init\(/.test(readFileSync(lc, "utf8"))) {
       errs.push(

package/test-suite/scripts/verify-family-agnostic.mjs

@@ -55,7 +55,11 @@ for (const rel of TOOLS) {
 const NEUTRAL = [
   ...(existsSync(join(ROOT, "bin")) ? readdirSync(join(ROOT, "bin")).filter((f) => f.endsWith(".mjs")).map((f) => `bin/${f}`) : []),
   "RULES.md",
-  ...["cometchat", "cometchat-onboarding"].flatMap((d) => {
+  // The router, the gate, and the competitor-migration skills (peers.yaml `migrations:`) are all
+  // installed for every family — each is a platform-neutral surface.
+  ...["cometchat", "cometchat-onboarding",
+    ...(existsSync(join(ROOT, "skills")) ? readdirSync(join(ROOT, "skills")).filter((d) => /^cometchat-migrate-from-[a-z0-9]+$/.test(d)) : []),
+  ].flatMap((d) => {
     const dir = join(ROOT, "skills", d);
     if (!existsSync(dir)) return [];
     const out = [`skills/${d}/SKILL.md`];

package/skills/cometchat-react-v7-core/references/i18n-rtl-a11y.md

@@ -1,22 +0,0 @@
-# i18n, RTL, accessibility (React v7)
-
-The UI Kit handles all three out of the box; careless customization breaks them.
-
-## RTL
-Reads `dir="rtl"` from the document root — components flip automatically (bubbles mirror, avatars swap, icons rotate). Test with `<html dir="rtl">`. Custom views MUST use logical properties (`margin-inline-start`, `padding-inline-end`) or they break RTL.
-
-## i18n — localization works via the provider; NEVER render a raw key
-`CometChatProvider` **auto-wires localization** (it renders `LocaleProvider` internally, `locale` prop) — the kit's ~40 built-in languages load out of the box (default `en-us`). You do NOT manually init for the default language.
-- **Non-default language:** set the `locale` prop on `CometChatProvider` (`<CometChatProvider locale="fr">`) — that's the v7 way to switch language. `init` / `setCurrentLanguage` / `getCurrentLanguage` / `addTranslation` are **INSTANCE** methods on `CometChatLocalize`, NOT statics — calling e.g. `CometChatLocalize.setCurrentLanguage(...)` is a TS2339 error. Reach the live instance with `CometChatLocalize.getSharedInstance()` (registered by `CometChatUIKit.init*` / the provider) and configure it there — `getSharedInstance()?.init({ translationsForLanguage, timezone, calendarObject, fallbackLanguage, … })`. **Don't `new CometChatLocalize(...)`**: the provider reads only the shared instance, so a constructed one isn't wired to the UI. Language stays on the `locale` prop (default `"en-us"`) — the provider applies it on mount/change, overriding an earlier `init({ language })`.
-- **Custom strings:** `CometChatLocalize.getSharedInstance()?.addTranslation(resources)` where `resources` is **nested per-language** `Record<lang, Record<key, string>>` (NOT a flat map; verified vs 7.1.0). Runtime hook: `useLocale()` → `{ getLocalizedString, language }`.
-- **`getLocalizedString(key)` returns the RAW KEY on a miss** (verified in the kit — `translate` falls back to `return key`). So a snake_case token in the UI (`group_info`, `add_members`, `delete_and_exit`, `view_members`) is a **localization failure**: a wrong/removed key, a custom language set without its translations, or — the #1 cause — **custom UI that rendered the key literally as a label.**
-- **NEVER hardcode a localization key as text.** Use the kit component (it localizes itself) or `useLocale().getLocalizedString(key)` — never `<button>group_info</button>`.
-- Don't invent keys; verify against the localization docs (`.md` twin, never the `.d.ts`). **v6→v7 changed some keys**, so a stale v6 key now misses and shows the raw string.
-
-## Accessibility
-Defaults ship: `aria-label` on icon buttons; `role="listbox"`/`option` on lists; Tab/Enter/Esc keyboard nav; focus management on thread open/close. When customizing:
-1. Icon-only button → add `aria-label="<verb>"`.
-2. List item → keep `role="option"` + `aria-selected`.
-3. Composer → keep an accessible `<label>` + `Enter`/`Shift+Enter`.
-4. Modal → trap focus, restore on close, `role="dialog"` + `aria-modal="true"` + labelled heading.
-5. Theming → verify text contrast ≥ 4.5:1. Deep custom views own their own a11y; test with a screen reader + keyboard.

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

@@ -1,28 +0,0 @@
-# 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.