@cometchat/skills 4.4.2 → 5.0.1

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

@@ -0,0 +1,53 @@
+---
+name: cometchat-react-v7-push
+description: "Add web push notifications to a React app with the CometChat v7 SDK — FCM via Firebase, registered through CometChatNotifications, with the Dashboard FCM provider as the sender. THIN + docs-first: the full setup is FETCHED from CometChat's notifications docs; this skill bakes only the hardening deltas + the token lifecycle. Triggers: 'add push notifications', 'web push', 'FCM push', 'notify on new message when app closed', 'cometchat push react'."
+license: "MIT"
+compatibility: "React >=18; @cometchat/chat-uikit-react ^7 (7.1.x); @cometchat/chat-sdk-javascript ^4.1.9 (ships CometChatNotifications); firebase ^10.3.1 (FCM web SDK)"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat react push notifications fcm firebase web v7"
+---
+
+> **Ground truth — DOCS-FIRST.** Push is an EXTERNAL integration (Firebase/FCM + a service worker + a Dashboard FCM provider), not a UI Kit component. The full, current setup lives in **CometChat's notifications docs — FETCH them, don't bake a recipe here**: via `cometchat-react-v7-core/references/docs-map.md` → `/notifications/push-overview` · `/notifications/web-push-notifications` · `/notifications/preferences`. This skill is THIN: it points you at those docs as the SOURCE and bakes ONLY the hardening deltas + the exact SDK symbols (verified vs installed `@cometchat/chat-sdk-javascript`). **Symbols are baked; the step-by-step is fetched.**
+
+## Companion skills (read first)
+- `cometchat-react-v7-core` — install, credentials, `init→login→render`. This skill ASSUMES it (push registers AFTER login, on the SAME SDK).
+
+## Use this skill when
+"add push notifications", "web push", "notify me on a new message when the app is closed", "FCM push". For a NON-web platform (Android/iOS/RN/Flutter) push differs — that's not this skill.
+
+## Build it — FETCH the docs, then apply the deltas
+1. **FETCH the setup from the docs** (source of truth): `{DOCS_BASE}/notifications/web-push-notifications.md` (+ `push-overview.md`) via `docs-map.md`. Follow its Firebase project + FCM setup, the `firebase-messaging-sw.js` service worker, and the client registration flow. **Build FROM the docs; if the docs are wrong/missing a detail, that's a DOCS gap — flag it (RULES §20), don't bake a permanent workaround.**
+2. **Dashboard prerequisite:** set up the **FCM provider in the CometChat Dashboard** (it is the SENDER). Self-hosted VAPID / a custom webhook is NOT the v7 web path. Confirm this is done or push delivers nothing.
+3. **Install:** `npm i firebase@^10.3.1` (the FCM web SDK). `CometChatNotifications` ships with the already-installed `@cometchat/chat-sdk-javascript` — no extra CometChat package.
+
+## Baked SDK symbols (verified vs installed 7.1.x SDK — do NOT guess these)
+```ts
+import { CometChat, CometChatNotifications } from "@cometchat/chat-sdk-javascript";
+// Register AFTER login, with the FCM token you got from firebase getToken():
+await CometChatNotifications.registerPushToken(
+  fcmToken,                                    // string — from firebase messaging getToken({ vapidKey })
+  CometChatNotifications.PushPlatforms.FCM_WEB,   // enum member
+  providerId                                   // optional — your Dashboard FCM provider id
+);
+// On logout (before CometChatUIKit.logout()):
+await CometChatNotifications.unregisterPushToken();
+```
+> Signature (installed source): `registerPushToken(pushToken: string, platform: PushPlatforms, providerId?: string)` · `unregisterPushToken()`. Fetch anything beyond these from the notifications docs.
+
+## Hardening deltas (BAKED — the things the docs tend to under-emphasize)
+- **Service-worker placement is per-bundler.** `firebase-messaging-sw.js` must be served from the ORIGIN ROOT: **Vite / CRA → `public/firebase-messaging-sw.js`** (copied to the web root); **Next.js → `public/firebase-messaging-sw.js`** (App or Pages router); **Astro → `public/firebase-messaging-sw.js`**. A SW under `src/` or a hashed asset path will NOT register. HTTPS (or `localhost`) is required.
+- **Request permission ON A USER GESTURE, not on load.** Call `Notification.requestPermission()` from a click/tap (a browser blocks/annoys otherwise). Only call `getToken()` after permission is `granted`.
+- **Token lifecycle = tie it to login/logout.** `registerPushToken(...)` AFTER `CometChatUIKit.login()` resolves; `unregisterPushToken()` BEFORE `CometChatUIKit.logout()`. Re-register on token refresh (`onTokenRefresh`/`getToken` again). Skipping unregister on logout leaks notifications to the wrong user.
+- **iOS web push is PWA-only.** On iOS/iPadOS, web push works ONLY in an **installed PWA** (Add to Home Screen) on **iOS 16.4+** — not in a normal Safari tab. Tell the user; don't promise Safari-tab push on iOS.
+- **The Dashboard FCM provider is the sender.** No self-hosted VAPID server / webhook for v7 web — configure the provider in the Dashboard (step 2).
+
+## Common pitfalls (BAKED)
+- SW not at the origin root → registration silently fails, no push. · Requesting permission on load → blocked/denied. · Forgetting `unregisterPushToken()` on logout → cross-user leakage. · Expecting Safari-tab push on iOS. · No Dashboard FCM provider → nothing delivers even with correct client code.
+
+## Verify it works (honest — push can't be auto-smoked)
+Static verification only: the SDK symbols resolve + the app compiles + the SW registers (check the browser Application → Service Workers). **Live delivery is a manual, device-dependent check** (real HTTPS origin + a registered SW + the Dashboard FCM provider + `granted` permission → send a message with the app backgrounded). This is the one skill whose live gate is inherently **blocked-external** — do NOT claim delivery works from a build alone.
+
+## 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-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/README.md

@@ -0,0 +1,70 @@
+# test-suite — the pack's safety net (deterministic verification)
+
+This is the **safety-net layer** of the pack (brain = `skills/`, hands = `bin/` CLI,
+materials = catalog/features/contracts/registry, safety-net = this). Every gate here
+is machine-computed and runs in CI (`.github/workflows/verify.yml`) so a bad skill
+**cannot merge** — verification is no longer local/on-demand.
+
+Scope today: **React v7 UI Kit** (`web-v7`). The scripts are family-agnostic (they
+read `peers.yaml` + the catalog), so when the skill-creator stands up a new family it
+gets its own `verify:fences:<family>` wiring by copying the `web-v7` typecheck project.
+
+## The gates (cheapest → most expensive)
+
+| Tier | Script | What it proves | Network? |
+|---|---|---|---|
+| **0 — lint** | `scripts/lint-skills.mjs` | frontmatter + dir/name parity + companion block + peers.yaml routing + router present | no |
+| **1 — catalog** | `scripts/verify-catalog.mjs` | every `CometChat*` symbol in a code fence exists in `catalogs/web-v7.json` (anti-hallucination); shipped catalog matches the reviewer's G0 oracle (drift guard) | no |
+| **2 — fences** | `scripts/typecheck-fences.mjs` | every `@cometchat`-importing fence compiles against the **pinned** kit (`typecheck/web-v7/`) — catches method/signature/import drift | installs pinned kit |
+| **3 — smoke** | reviewer `tools/run-feature.mjs` + `smoke-runner.mjs` | the emitted component renders & works in a live headless browser | needs creds |
+| **done** | reviewer `tools/predicate.mjs` | the recorded review is complete (`GLOBAL_DONE`) — release gate | no |
+
+## Run locally
+
+```bash
+npm run verify                 # Tier-0 + Tier-1 + predicate (fast, no network — run anywhere)
+npm run lint:skills            # Tier-0 only
+npm run verify:catalog         # Tier-1 only
+npm run verify:fences:web-v7   # Tier-2 — needs the pinned kit: npm --prefix test-suite/typecheck/web-v7 ci
+npm run verify:ci              # everything Tier-0..2 + predicate (what CI runs)
+npm run catalog:refresh        # regenerate catalogs/web-v7.json from the installed kit (oracle refresh)
+```
+
+## Catalog = single source of truth
+
+`catalogs/web-v7.json` (405 public symbols, exports-only) is the shipped Tier-1
+oracle. `catalog:refresh` regenerates it from the installed kit via the skill-creator's
+`build-catalog.mjs`. `verify-catalog.mjs` fails if it drifts from the reviewer's copy
+at `.claude/skills/cometchat-skill-reviewer/tools/catalog/web-v7.json` — keep both in
+sync by re-running the refresh (this is the AUDIT-008/012 failure mode, gated).
+
+## Keeping the Tier-2 pins honest
+
+`typecheck/web-v7/package.json` pins the kit majors. They MUST track
+`peers.yaml` (web-v7) and `cometchat-react-app/package.json`. The scheduled
+`catalog-refresh.yml` workflow re-derives the catalog on a cadence so the oracle
+can't rot against new SDK minors.
+
+## Why Tier-2 fences is in `verify:ci` but NOT default `verify` (AUDIT-030)
+
+Deliberate. `verify:fences:web-v7` type-checks against the **real pinned kit**, so it
+needs `typecheck/web-v7/node_modules/@cometchat` present. That is **not** installed by a
+plain root `npm install`: the fixture's `node_modules` is git-ignored, is not in the
+published `files` allowlist (only its `package.json` + `tsconfig.json` ship), and there is
+no `postinstall`/`prepare` hook. CI installs it as a **separate explicit step** right
+before the gate (`.github/workflows/test.yml`: `npm --prefix test-suite/typecheck/web-v7
+install` → `npm run verify:fences:web-v7`).
+
+If the kit is absent, `typecheck-fences.mjs` **hard-exits code 2** (`typecheck-fences.mjs`
+~L46). So promoting it into default `verify` would make `verify` **fail in every clean
+checkout** that hasn't run the extra fixture install — breaking the "fast, no network, run
+anywhere" contract of `verify` above. To keep that contract, fences stays in `verify:ci`
+(where CI guarantees the install) and the default `verify` stays install-free.
+
+**Owner CI-cost decision (open):** if you WANT the TS6133/kit-drift class caught locally in
+default `verify` too, the price is making the fixture install part of `verify` (either an
+`npm --prefix test-suite/typecheck/web-v7 ci` prestep, a root `postinstall` that installs
+it, or vendoring the kit) — i.e. `verify` gains a network/install cost and is no longer
+"run anywhere offline". That is a product/CI trade-off, not a safe silent change, so it is
+left to the owner. To run fences locally today: `npm --prefix test-suite/typecheck/web-v7
+ci && npm run verify:fences:web-v7` (or just `npm run verify:ci`).