@cometchat/skills 4.4.2 → 5.0.1

package/skills/cometchat-a11y/SKILL.md

@@ -1,477 +1,49 @@
 ---
 name: cometchat-a11y
-description: Accessibility (a11y) for CometChat UI Kit integrations across all families — React, React Native, Angular, Android (V5/V6), iOS, Flutter. Covers WCAG 2.1 AA targets, keyboard navigation in chat, screen reader announcements (live regions for new messages), color contrast, focus management on call screens, motion-reduction support, and the cross-family checks that catch the common production a11y bugs. Cross-family — applies wherever the agent is checking accessibility.
+description: "Keep a CometChat integration accessible — the UI Kit is designed targeting WCAG 2.1 AA with keyboard navigation (verify per component in its docs; full conformance still needs manual testing), and this skill makes sure the HOST app doesn't break that, covering contrast, focus, screen-reader context, reduced motion, RTL, and calls accessibility. Cross-family. Triggers: 'is cometchat accessible', 'WCAG / 508 / ADA compliance', 'screen reader support', 'keyboard navigation', 'a11y audit', 'accessible chat', 'contrast/focus issues in chat'."
 license: "MIT"
-compatibility: "All CometChat UI Kit families v4.x / v5.x / v6.x"
+compatibility: "CometChat UI Kits (React v7 · Angular v5 · React Native v5 · iOS v5 · Android v6 · Flutter v6). Kit components are designed targeting WCAG 2.1 AA + keyboard navigation (the Angular docs state this explicitly; other families are not individually documented, and full conformance needs manual testing / a VPAT). Host wiring is per platform."
 metadata:
   author: "CometChat"
-  version: "4.0.0"
-  tags: "cometchat a11y accessibility wcag aa keyboard screen-reader voiceover talkback aria live-region focus-management contrast prefers-reduced-motion cross-family"
----
-
-> **Ground truth:** per-platform UI Kit + `docs/fundamentals`. **Official docs:** https://www.cometchat.com/docs/fundamentals/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them.
-
-## Purpose
-
-Accessibility for CometChat integrations. Out-of-the-box, the UI Kit components are mostly accessible — the kit's own buttons, inputs, and lists ship with semantic markup. Production gaps appear in the wiring **around** the kit: custom call surfaces, navigation, focus management on screen transitions, and contrast in custom themes.
-
-Target: **WCAG 2.1 AA**. The skill writes code that meets this baseline.
-
----
-
-## The five gaps that trip integrations (any family)
-
-1. **Color contrast in custom themes.** A brand color picked for "looks nice in the brand book" may be 3.2:1 against the text — fails AA's 4.5:1 minimum.
-2. **Focus management on chat screen entry.** Tab/screen reader user lands on the chat screen but focus stays on the previous trigger button. They have to manually navigate into the message list every time.
-3. **No live region announcement for new messages.** Screen reader users don't know a new message arrived unless they navigate the message list and hear the new item.
-4. **Keyboard-only users can't navigate the conversation list.** Click handlers bound to `<div>` instead of `<button>` skip keyboard events.
-5. **Reduced-motion users see decorative animations.** Typing-indicator dots, message bubble entrance animations, transition effects — should respect `prefers-reduced-motion`.
-
-This skill addresses each one across families.
-
----
-
-## 1. Color contrast — the theme audit
-
-CometChat themes are CSS variables (web/RN) or color tokens (native/Flutter). Override a single color and you might fail AA.
-
-### Web / Angular — CSS variable contrast check
-
-```ts
-// scripts/check-contrast.ts (run in CI or as a one-shot)
-function contrastRatio(hex1: string, hex2: string): number {
-  const luminance = (hex: string) => {
-    const rgb = hex.match(/\w\w/g)!.map(c => parseInt(c, 16) / 255).map(c =>
-      c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4
-    );
-    return 0.2126 * rgb[0] + 0.7152 * rgb[1] + 0.0722 * rgb[2];
-  };
-  const l1 = luminance(hex1);
-  const l2 = luminance(hex2);
-  return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
-}
-
-// Pull the values from your CSS variables
-const fg = getComputedStyle(document.documentElement).getPropertyValue("--cometchat-text-color").trim();
-const bg = getComputedStyle(document.documentElement).getPropertyValue("--cometchat-background-color").trim();
-const ratio = contrastRatio(fg, bg);
-if (ratio < 4.5) {
-  console.warn(`Text/background contrast ${ratio.toFixed(2)}:1 fails WCAG AA (need ≥4.5:1)`);
-}
-```
-
-In CI, add this to your test suite. The skill writes a starter version into `tests/a11y/contrast.test.ts`.
-
-### React Native / native / Flutter — manual audit at theme-design time
-
-Use a contrast-checker tool (browser extensions, https://webaim.org/resources/contrastchecker/) on the theme tokens before shipping. There's no runtime DOM to audit on native.
-
-The kit's default theme tokens pass AA. Custom palettes need the audit.
-
-**Common fail:** brand purple #6750A4 against white background = 6.6:1 (passes). Same purple against `#F0F0F0` light gray = 5.7:1 (passes). Same purple against `#999999` muted gray = 2.8:1 (FAILS). Watch for muted backgrounds in dark-mode toggles, secondary buttons, and "subtle" surfaces.
-
----
-
-## 2. Focus management on chat screen entry
-
-When the user navigates to a chat screen (clicked a conversation, opened the chat tab, accepted a deep link), focus should land on a meaningful control — usually the message composer or the latest message.
-
-### React (web)
-
-```tsx
-import { useEffect, useRef } from "react";
-
-export function ChatScreen() {
-  const composerRef = useRef<HTMLElement>(null);
-
-  useEffect(() => {
-    // After mount + animations, focus the composer
-    const timer = setTimeout(() => {
-      composerRef.current?.focus();
-    }, 100);
-    return () => clearTimeout(timer);
-  }, []);
-
-  return (
-    <div>
-      <CometChatMessageHeader />
-      <CometChatMessageList />
-      <CometChatMessageComposer ref={composerRef} />
-    </div>
-  );
-}
-```
-
-The kit's `CometChatMessageComposer` is a plain function component (no `forwardRef` in v6), so passing it a `ref` is a no-op. Wrap it in a focusable container and reach the input through the DOM: `composerRef.current?.querySelector("input, [contenteditable]")?.focus()`.
-
-### React Native
-
-```tsx
-import { useRef, useEffect } from "react";
-import { findNodeHandle, AccessibilityInfo } from "react-native";
-
-export function ChatScreen() {
-  const composerRef = useRef(null);
-
-  useEffect(() => {
-    const handle = findNodeHandle(composerRef.current);
-    if (handle) {
-      AccessibilityInfo.setAccessibilityFocus(handle);
-    }
-  }, []);
-
-  return (
-    <View>
-      <CometChatMessageHeader />
-      <CometChatMessageList />
-      <CometChatMessageComposer ref={composerRef} />
-    </View>
-  );
-}
-```
-
-### Angular
-
-```ts
-@Component({...})
-export class ChatComponent implements AfterViewInit {
-  @ViewChild("composer") composer!: ElementRef;
-
-  ngAfterViewInit() {
-    setTimeout(() => this.composer.nativeElement.focus(), 100);
-  }
-}
-```
-
-### Native Android (Kotlin)
-
-```kotlin
-override fun onResume() {
-  super.onResume()
-  composerView.requestFocus()
-  composerView.sendAccessibilityEvent(AccessibilityEvent.TYPE_VIEW_FOCUSED)
-}
-```
-
-### Native iOS (Swift)
-
-```swift
-override func viewDidAppear(_ animated: Bool) {
-  super.viewDidAppear(animated)
-  UIAccessibility.post(notification: .screenChanged, argument: composerView)
-}
-```
-
-### Flutter
-
-```dart
-final FocusNode _composerFocus = FocusNode();
-
-@override
-void initState() {
-  super.initState();
-  WidgetsBinding.instance.addPostFrameCallback((_) {
-    _composerFocus.requestFocus();
-  });
-}
-
-// Then on the composer widget: focusNode: _composerFocus
-```
-
----
-
-## 3. Live region for new messages
-
-Screen reader users need an audible announcement when a new message arrives — otherwise they have to navigate to the message list and re-read it.
-
-### Web / Angular — ARIA live region
-
-```html
-<!-- A visually-hidden region that screen readers announce -->
-<div
-  aria-live="polite"
-  aria-atomic="true"
-  style="position: absolute; left: -9999px; height: 1px; width: 1px; overflow: hidden;"
-  id="message-announcer"></div>
-```
-
-```ts
-// Listen for new messages and announce
-import { CometChat } from "@cometchat/chat-sdk-javascript";
-
-const listenerId = "a11y-message-announcer";
-CometChat.addMessageListener(listenerId, new CometChat.MessageListener({
-  onTextMessageReceived: (msg: CometChat.TextMessage) => {
-    const senderName = msg.getSender().getName();
-    const text = msg.getText();
-    const region = document.getElementById("message-announcer");
-    if (region) {
-      // Clearing first ensures the same text re-announces
-      region.textContent = "";
-      setTimeout(() => {
-        region.textContent = `New message from ${senderName}: ${text}`;
-      }, 100);
-    }
-  },
-}));
-```
-
-`aria-live="polite"` waits for the user to finish speaking before announcing. Use `aria-live="assertive"` only for urgent messages (like incoming calls) — too aggressive for chat.
-
-### React Native
-
-```ts
-import { AccessibilityInfo } from "react-native";
-
-CometChat.addMessageListener(listenerId, new CometChat.MessageListener({
-  onTextMessageReceived: (msg) => {
-    const text = `New message from ${msg.getSender().getName()}: ${msg.getText()}`;
-    AccessibilityInfo.announceForAccessibility(text);
-  },
-}));
-```
-
-### Native Android / iOS / Flutter
-
-Each platform has an equivalent — Android `View.announceForAccessibility(text)`, iOS `UIAccessibility.post(notification: .announcement, argument: text)`, Flutter `SemanticsService.announce(text, TextDirection.ltr)`. Same shape; the SDK callback is the trigger.
-
----
-
-## 4. Keyboard navigation
-
-The kit's components are keyboard-accessible by default. Custom wrapping is what breaks it.
-
-### Anti-pattern — `<div onClick>` for clickable items
-
-```tsx
-// ✗ WRONG — keyboard users can't activate
-<div onClick={() => openConversation(c)}>{c.name}</div>
-
-// ✓ RIGHT — `<button>` is keyboard + screen-reader native
-<button onClick={() => openConversation(c)}>{c.name}</button>
-
-// ✓ ALSO RIGHT — div with explicit ARIA + keyboard handlers
-<div
-  role="button"
-  tabIndex={0}
-  onClick={() => openConversation(c)}
-  onKeyDown={(e) => {
-    if (e.key === "Enter" || e.key === " ") {
-      e.preventDefault();
-      openConversation(c);
-    }
-  }}
->
-  {c.name}
-</div>
-```
-
-### Skip links
-
-For long conversation lists, add a skip-to-message-composer link:
-
-```html
-<a href="#message-composer" class="skip-link">Skip to message composer</a>
-```
-
-```css
-.skip-link {
-  position: absolute;
-  left: -9999px;
-  z-index: 999;
-}
-.skip-link:focus {
-  left: 0;
-  top: 0;
-  background: white;
-  padding: 8px;
-}
-```
-
-The kit's components already include skip links where applicable; custom wrapping should preserve them.
-
-### Keyboard shortcuts
-
-For productivity apps:
-
-```ts
-useEffect(() => {
-  const handler = (e: KeyboardEvent) => {
-    // Cmd/Ctrl + K → focus search
-    if ((e.metaKey || e.ctrlKey) && e.key === "k") {
-      e.preventDefault();
-      searchRef.current?.focus();
-    }
-    // Escape → close any open thread / modal
-    if (e.key === "Escape") {
-      closeOpenThread();
-    }
-  };
-  window.addEventListener("keydown", handler);
-  return () => window.removeEventListener("keydown", handler);
-}, []);
-```
-
-Document the shortcuts in your in-app help — discoverability matters.
-
----
-
-## 5. Reduced motion
-
-Animations help most users; they cause physical discomfort or distraction for users with vestibular disorders, ADHD, or who simply prefer less movement. WCAG 2.1 AA requires honoring the OS preference.
-
-### Web / Angular — CSS
-
-```css
-@media (prefers-reduced-motion: reduce) {
-  /* Disable kit animations + your custom ones */
-  * {
-    animation-duration: 0.01ms !important;
-    animation-iteration-count: 1 !important;
-    transition-duration: 0.01ms !important;
-  }
-}
-```
-
-### React Native
-
-```ts
-import { AccessibilityInfo } from "react-native";
-
-const [reduceMotion, setReduceMotion] = useState(false);
-
-useEffect(() => {
-  AccessibilityInfo.isReduceMotionEnabled().then(setReduceMotion);
-  const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduceMotion);
-  return () => sub.remove();
-}, []);
-
-// In animations
-<Animated.View
-  style={{
-    transform: [{ scale: reduceMotion ? 1 : animatedValue }],
-  }}
-/>
-```
-
-### Native iOS
-
-```swift
-let reduceMotion = UIAccessibility.isReduceMotionEnabled
-if !reduceMotion {
-  UIView.animate(withDuration: 0.3) { ... }
-} else {
-  // Apply final state without animation
-}
-```
-
-### Native Android
-
-```kotlin
-val reduceMotion = Settings.Global.getFloat(
-  contentResolver, Settings.Global.ANIMATOR_DURATION_SCALE, 1.0f
-) == 0.0f
-```
-
-### Flutter
-
-```dart
-final reduceMotion = MediaQuery.of(context).disableAnimations;
-```
-
-The skill defaults to wrapping the typing indicator + message-bubble entrance animations in reduce-motion guards. Other kit animations need similar treatment if you've customized them.
-
----
-
-## Calls a11y
-
-Calls have specific a11y considerations beyond chat:
-
-1. **Focus on call screen entry → end-call button.** Avoids accidental hangup but ensures the user can quickly exit.
-2. **Announce incoming calls.** Live region (web/RN) or `UIAccessibility.post(.announcement)` (iOS) — "Incoming call from Alice."
-3. **Mute/end button labels.** "Mute microphone" not just "Mute" — clarify what's being toggled.
-4. **No flashing — recording indicator uses dot, not strobe.** WCAG 2.3 forbids more than 3 flashes/sec to prevent seizures.
-5. **Caption support if recording.** Production calling apps with live captioning hook in via the platform's speech-recognition API and overlay text on the call screen.
-
----
-
-## Testing — automated + manual
-
-### Web automated
-
-```bash
-npm install --save-dev @axe-core/playwright
-```
-
-```ts
-import { test, expect } from "@playwright/test";
-import AxeBuilder from "@axe-core/playwright";
-
-test("chat screen passes axe AA", async ({ page }) => {
-  await page.goto("/messages");
-  const results = await new AxeBuilder({ page }).withTags(["wcag2a", "wcag2aa"]).analyze();
-  expect(results.violations).toEqual([]);
-});
-```
-
-### Native automated
-
-iOS: Xcode → Accessibility Inspector → Audit. Android: Accessibility Scanner app on a real device.
-
-### Manual
-
-- **Keyboard-only navigation** — unplug your mouse, complete a full chat flow. Tab through every control.
-- **VoiceOver (iOS) / TalkBack (Android) / NVDA (Windows) / VoiceOver (macOS)** — listen to the kit; verify announcements make sense.
-- **Browser zoom 200%** — kit should remain usable at 200% zoom on a 1280×720 viewport (WCAG 1.4.10 reflow).
-
----
-
-## Anti-patterns
-
-1. **Custom themes without a contrast audit.** Brand colors silently fail AA.
-2. **`<div onClick>` for clickable items.** Keyboard users can't activate.
-3. **No live region for new messages.** Screen reader users miss messages.
-4. **Auto-playing video on call screen.** Some users browse with autoplay disabled — kit handles this; custom UI must too.
-5. **Focus stays on the trigger button after opening chat.** User has to manually re-navigate.
-6. **Ignoring `prefers-reduced-motion`.** Vestibular-disorder users get disoriented.
-7. **`aria-live="assertive"` for chat messages.** Interrupts the user mid-sentence; reserve for genuinely urgent (incoming call).
-8. **Skipping label specificity.** "Mute" alone is ambiguous; "Mute microphone" / "Unmute microphone" is clear.
-9. **Color-only signals.** "Read" status as just a checkmark color — add a visible text label for color-blind users.
-10. **No test coverage for a11y.** Regressions slip in. Automate the easy checks (axe-core); manual-test the rest per release.
-
----
-
-## Verification checklist
-
-**Cross-family:**
-- [ ] Custom theme passes AA contrast (4.5:1 text, 3:1 large text + UI components)
-- [ ] Focus lands on a meaningful control on chat screen entry
-- [ ] Live region / accessibility announcement on new message receive
-- [ ] No `<div onClick>` patterns — buttons are buttons
-- [ ] `prefers-reduced-motion` / `isReduceMotionEnabled` honored for animations
-- [ ] Mute/end/camera labels are specific (not just "Mute")
-- [ ] Incoming-call announcement (`assertive` live region OR platform announcement API)
-- [ ] No flashing > 3 Hz (recording dot uses fade, not strobe)
-
-**Web/Angular:**
-- [ ] axe-core / Playwright a11y test in CI; passes WCAG AA tags
-- [ ] `<html lang="...">` set to current locale (consumes `cometchat-i18n` skill output)
-- [ ] Skip-to-composer link present
-- [ ] Browser zoom 200% smoke test
-
-**Native (Android/iOS/Flutter):**
-- [ ] TalkBack / VoiceOver smoke test on a real device
-- [ ] Reduced motion preference observed (`UIAccessibility.isReduceMotionEnabled`, etc.)
-- [ ] Focus restored on screen pop (not just push)
-- [ ] Touch targets ≥ 44×44 pt (iOS) / 48×48 dp (Android) — kit defaults pass; custom UI must too
-
----
-
-## Pointers
-
-- `cometchat-i18n` — sister skill; `<html lang>` and screen-reader pronunciation of translated strings depend on locale set correctly
-- `cometchat-{family}-customization` — when customizing kit components, preserve their built-in a11y attributes
-- `cometchat-{family}-troubleshooting` — when a11y tools report issues that look kit-internal
-- WCAG 2.1 AA reference — https://www.w3.org/WAI/WCAG21/quickref/?levels=aa
-- Material Design accessibility — https://m3.material.io/foundations/accessible-design
-- Apple HIG accessibility — https://developer.apple.com/design/human-interface-guidelines/accessibility
+  version: "1.0.0"
+  tags: "cometchat a11y accessibility wcag screen-reader keyboard focus contrast rtl section508"
+---
+
+> **Ground truth:** the UI Kit components are documented as **designed targeting WCAG 2.1 Level AA** with **keyboard navigation** built in (the Angular component docs state this most explicitly; note the docs' own caveat that full conformance still requires manual testing — do not assert a blanket AA/VPAT claim to the user without it). Treat AA as the design target, not a certified guarantee. Accessibility failures in a CometChat app are almost always **host-side regressions** — global CSS, a broken focus order, a container with no accessible name, or motion that ignores the user's preference. Verify component-level a11y claims against the component's own docs page (`cometchat-<family>-components` → docs-map); this skill owns the host-side discipline the kit can't control.
+
+## Use this skill when
+An accessibility review (WCAG / Section 508 / ADA / EN 301 549), a screen-reader or keyboard complaint, or "make our chat accessible." Procurement for public-sector, education, healthcare and large enterprises requires this.
+
+## Start from what the kit gives you
+The kit ships accessible components: keyboard-operable lists/composer, focus handling, and semantics **designed targeting** AA (the design target — not a certified guarantee; see above). On web it sets ARIA roles and names itself — the conversation/user rosters render as a labelled `listbox` and manage roving focus — so don't override or strip them. Your job is to **not break it** and to make the surrounding app equally accessible. Two rules first:
+1. **Don't let global CSS leak into the `.cometchat` subtree** (web) — a global `outline:none`, a low-contrast override, a `text-align`/flex reset, or a Tailwind base can strip focus rings or break contrast the kit set correctly. Scope your resets away from the kit (`RULES.md` → CSS isolation).
+2. **Give the chat container a real, labelled home** — a sized region (a11y needs a visible, non-collapsed surface too) with an accessible name (e.g. an `aria-label`/landmark on web, an accessibility label on native) so screen-reader users can find and enter it.
+
+## The checklist (host-side)
+- **Keyboard:** every path reachable and operable by keyboard — open a conversation, type, send, open thread, close. Don't trap focus; return focus sensibly when a panel/dialog closes. Don't remove focus outlines; if you restyle them, keep a visible focus indicator.
+- **Screen reader:** the surface and its regions have accessible names; your own buttons around the kit have labels (not icon-only with no `aria-label`/accessibility label). New-message announcements: verify the kit's live-region behavior on your target reader (VoiceOver/NVDA/TalkBack) and don't suppress it with `aria-hidden` on an ancestor.
+- **Contrast:** if you theme the kit (`cometchat-<family>-customization`), keep text/UI contrast at **AA** (4.5:1 text, 3:1 large text/UI). Check both light and dark themes — a brand color that passes on light can fail on dark.
+- **Reduced motion:** honor `prefers-reduced-motion` (web) / the OS "reduce motion" setting (native) in any animation you add around the chat; don't force motion the user opted out of.
+- **Text scaling / zoom:** the surface must remain usable at 200% zoom / large Dynamic Type — don't cap font sizes or clip at large text.
+- **RTL:** direction-correct for RTL locales (pairs with `cometchat-i18n`).
+- **Targets:** your custom controls meet the minimum touch-target size; don't shrink the kit's.
+
+## Calls accessibility (if you use calling)
+- Request camera/mic with clear, user-visible prompts and reasons.
+- Provide accessible labels for call controls you add (mute, end, camera).
+- Where available, surface captions/transcription; ensure incoming-call UI is announced and keyboard/AT-operable.
+
+## Test it
+- **Automated (web):** run `axe`/Lighthouse on the chat screen — fix contrast, missing names, and ARIA misuse it flags. (Automated tools catch ~a third of issues; do the manual pass too.)
+- **Manual:** tab through the whole flow with the mouse unplugged; drive it with VoiceOver / NVDA / TalkBack; zoom to 200%; toggle reduced motion; switch to dark. Fix what breaks in YOUR wiring; if a genuine kit-component gap appears, verify against the component docs and report it (don't hand-patch kit internals).
+
+## Common pitfalls
+1. **Global CSS stripping focus rings or contrast** inside `.cometchat` — scope resets away.
+2. **Icon-only custom buttons with no label** — add accessible names.
+3. **Unlabelled, collapsed, or unreachable chat container** — size it and name it.
+4. **Animations ignoring reduced-motion.**
+5. **Contrast checked in one theme only** — check light and dark.
+6. **Assuming automated tools are enough** — they miss keyboard/reader flow; test manually.
+
+## Verify it works
+The chat flow is fully keyboard-operable with a visible focus indicator · a screen reader announces the surface, messages, and your controls · contrast passes AA in light and dark · the UI holds at 200% zoom / large type · reduced-motion is honored · RTL mirrors correctly · axe/Lighthouse on the chat screen is clean of contrast/name/ARIA errors.

package/skills/cometchat-analytics/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: cometchat-analytics
+description: "See what your chat is doing — pull usage & message metrics via REST, stream real-time events to your data/observability stack via webhooks, monitor client-side errors & the init/login path, and read push/call logs. Cross-family: metrics/webhooks are server-side; client error monitoring wires per family. Triggers: 'chat analytics', 'usage metrics', 'message volume', 'monitor cometchat', 'observability', 'send chat events to datadog/segment/bigquery', 'track delivery', 'error monitoring for chat', 'dashboards for chat'."
+license: "MIT"
+compatibility: "CometChat Metrics REST API (usage · message) · Webhooks · Notification/Call logs · on-prem Prometheus/Grafana/Loki. Client error monitoring via each family's error boundary / listeners."
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat analytics observability metrics webhooks monitoring datadog sentry dashboards"
+---
+
+> **Ground truth:** shapes are FETCHED from the live docs — `{DOCS_BASE}/rest-api/metrics/usage-metrics`, `/rest-api/metrics/message-metrics`, `/fundamentals/webhooks` (+ `/rest-api/management-apis/webhooks/overview`), `/notifications/logs`, `/rest-api/calls-apis/get-call`, and on-prem `/on-premise-deployment/docker/monitoring`. `DOCS_BASE = https://www.cometchat.com/docs`; append `.md`. Verify each metric field / event name against the docs before charting it; don't invent a metric.
+
+## Use this skill when
+You need visibility into chat: product analytics (DAU, messages, retention), an ops/observability signal (delivery, errors, latency), or feeding chat events into an existing warehouse/monitoring stack.
+
+## Three layers of visibility
+| Layer | Source | Use it for |
+| --- | --- | --- |
+| **Aggregate metrics** | Metrics REST API (usage + message) | dashboards, MAU/DAU, message volume, growth |
+| **Real-time events** | Webhooks | stream every message/user/group/call event to your pipeline |
+| **Client health** | your error monitor + the kit's error boundary/listeners | init/login failures, render errors, UX latency |
+
+## 1. Aggregate metrics (REST, server-side)
+- **Usage metrics** (`{DOCS_BASE}/rest-api/metrics/usage-metrics`) — active users and usage over time.
+- **Message metrics** (`{DOCS_BASE}/rest-api/metrics/message-metrics`) — message volume/counts.
+- **Call metrics** — per-call detail incl. participant metrics via `{DOCS_BASE}/rest-api/calls-apis/get-call`.
+Call these from a server job with the **REST API Key** (never client-side), on a schedule, into your BI tool. Fetch the exact query params + response fields from each page before building the report.
+
+## 2. Real-time events → your stack (webhooks)
+Webhooks POST an HTTPS notification to your server on message / user / group / call events (`{DOCS_BASE}/fundamentals/webhooks`; configure via `/rest-api/management-apis/webhooks/overview`). This is how you get chat into **Segment / BigQuery / Snowflake / Datadog / a data lake** in real time:
+1. Stand up an HTTPS endpoint (returns 200 to ack). Secure it with the **Basic Auth** credentials CometChat sends on every webhook request (`{DOCS_BASE}/fundamentals/webhooks` — the docs describe Basic Auth only, with no payload-signature scheme, so validate the `Authorization` header rather than looking for an HMAC signature).
+2. Subscribe to the events you need (don't fan out everything if you only need message.sent).
+3. Transform + forward to your warehouse/observability sink; make the handler idempotent and fast (queue heavy work).
+The same webhook stream doubles as a **tamper-evident audit log** for `cometchat-compliance`.
+
+## 3. Client-side error & performance monitoring (per family)
+The metrics API won't tell you a user's chat failed to load — instrument the client:
+- **Capture kit render errors** — on the React families via the error boundary's hook (React v7: `CometChatErrorBoundary` `onError`; Angular/RN have the equivalent); on iOS/Android/Flutter (no error-boundary construct) via the SDK error listeners / the kit's error-state views. Forward to Sentry/Datadog with context.
+- **Instrument the critical path** — wrap init, the token fetch, and login in spans/breadcrumbs; a spike in login failures is your earliest incident signal (often Region or token issues).
+- **Listen for connection state** — the SDK's connection/websocket listeners tell you when clients drop; count reconnects.
+- **Don't log secrets or message bodies** to your monitor — log UIDs/event types/latencies, not content (privacy + `cometchat-compliance`).
+Wire these through the resolved family's `-core`/`-production`/`-troubleshooting` skills.
+
+## 4. Delivery & call logs
+- **Push delivery logs** (`{DOCS_BASE}/notifications/logs`) — FCM/APNs/email/SMS delivery, ~14-day retention; enable when diagnosing "notifications not arriving" and export before they age out.
+- **Call logs** — the Calls REST APIs for per-call quality/participant metrics.
+
+## 5. Self-host observability
+On-prem ships **Prometheus + Grafana + Loki + Promtail** (`{DOCS_BASE}/on-premise-deployment/docker/monitoring`): service metrics, dashboards, alerts, and centralized logs — wire alerts (P95 latency, error rate, WS capacity) to your on-call. SaaS customers use the Metrics API + webhooks instead.
+
+## Common pitfalls
+1. **Metrics API called client-side** — it needs the REST API Key; server only.
+2. **Webhook handler slow or non-idempotent** — retries pile up; ack fast, queue the work, dedupe.
+3. **Charting an invented metric** — fetch the real fields from the metrics pages.
+4. **Logging message content to your monitor** — privacy/compliance risk; log metadata, not bodies.
+5. **No client error monitoring** — you'll hear about outages from users, not dashboards; wire the error boundary + login-path spans.
+6. **Relying on push logs after they age out** — export within the retention window.
+
+## Verify it works
+Usage/message metrics return real numbers into your dashboard · a test message triggers your webhook and lands in your warehouse/monitor · a forced init/login failure shows up in your error monitor with context · push/call logs are readable when needed · (on-prem) Grafana shows the services and alerts fire.