@cometchat/skills 4.4.2 → 5.0.0

package/skills/cometchat-calls/SKILL.md

@@ -1,364 +0,0 @@
----
-name: cometchat-calls
-description: Entry-point for adding CometChat Voice & Video Calling to any React, React Native, Angular, native Android, native iOS, or Flutter project. Detects the framework, picks standalone (calls-only) vs additive (calls on top of existing chat) mode, and routes to the per-family calls skill. Invoked by the top-level `cometchat` dispatcher when `product === "voice-video"` or `chat-messaging+voice-video`, and directly when the user asks for calls explicitly.
-license: "MIT"
-metadata:
-  author: "CometChat"
-  version: "4.0.0"
-  tags: "cometchat calls voice video webrtc dispatcher react react-native angular android ios flutter callkit pushkit voip"
----
-
-> **Ground truth:** the per-platform Calls SDK + `docs/calls`. **Official docs:** https://www.cometchat.com/docs/calls/javascript/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.
-
-## Use this skill when
-
-- The top-level `cometchat` dispatcher's Step 3.0 routes here because `product === "voice-video"` or `chat-messaging+voice-video`
-- The user explicitly asks for calling: *"add calls"*, *"add video calling"*, *"add voice calls"*, *"set up call screen"*, *"integrate calls SDK"*, *"add CallKit"*
-- The user is iterating on an existing chat integration and picks *"Add calling"* from the iteration menu (Step 7 of `cometchat`)
-
-This is the **entry point for every calls integration**. Do NOT invoke per-family `cometchat-{family}-calls` skills directly — this dispatcher detects the family, picks the integration mode (standalone vs additive), and routes to the right skill with the right preconditions.
-
-**Supported families:**
-
-| Family | Per-family skill | Calls SDK package | Stable today? |
-|---|---|---|---|
-| **Web** (React / Next.js / React Router / Astro) | `cometchat-react-calls` | `@cometchat/calls-sdk-javascript` | Yes |
-| **React Native** (Expo + bare) | `cometchat-native-calls` | `@cometchat/calls-sdk-react-native` | Yes |
-| **Angular** (12–15) | `cometchat-angular-calls` | `@cometchat/calls-sdk-javascript` | Yes |
-| **Android** (V5 stable) | `cometchat-android-v5-calls` | `com.cometchat:calls-sdk-android:5.x` (Cloudsmith) | Yes — production-ready |
-| **Android** (V6 GA) | `cometchat-android-v6-calls` | `chatuikit-{compose,kotlin}-android:6.0.+` **+ explicit `com.cometchat:calls-sdk-android:5.0.+` peer dep** (the "calls fold in" marketing is incomplete) | Yes — GA 2026-05-25, but ships broken OOTB: **5 required workarounds (W1–W5)**, incl. the peer dep + not using `CometChatCallButtons`. See per-family skill. |
-| **iOS** (V5 stable) | `cometchat-ios-calls` | `CometChatCallsSDK` (SPM / CocoaPods) | Yes |
-| **Flutter** (V5 stable) | `cometchat-flutter-v5-calls` (already exists) | `cometchat_calls_sdk` (Cloudsmith) | Yes |
-| **Flutter** (V6 GA) | `cometchat-flutter-v6-calls` (already exists) | Calls fold into `cometchat_chat_uikit: ^6.0.1` | Yes — GA 2026-05-25 (one explicit `MaterialApp(navigatorKey: CallNavigationContext.navigatorKey)` wiring required, see per-family skill) |
-
-> **Status:** All nine calls skills (this dispatcher + react, native, angular, ios, android-v5, android-v6, flutter-v5, flutter-v6) are authored and source-verified against each family's real SDK surface (decompiled `calls-sdk-android` AARs, `CometChatCallsSDK.swiftinterface`, `@cometchat/calls-sdk-{javascript,react-native}` `.d.ts`, and the Flutter `cometchat_calls_*` pub-cache). Android V5 ships 17 pre-authored sub-skills folded into `cometchat-android-v5-calls/references/`. Per-family caveats that are load-bearing: **Android V6 needs 5 workarounds (W1–W5)**; **Flutter V6 needs the `MaterialApp(navigatorKey: CallNavigationContext.navigatorKey)` wiring**; **iOS has no `CometChatCalls.login()`** (auth is per-session via `generateToken`).
-
-> **Clarification contract (ALL coding agents) — read `references/asking-questions.md`.** Every "ask"/"AskUserQuestion" in this skill follows that contract: on any agent without a structured-question primitive, render the question as a **numbered text list and WAIT** for a real answer (never default/infer; auto-mode doesn't authorize skipping), map by value/label not position, and accept a free-text fallback.
-
-## Why a separate calls dispatcher
-
-The chat dispatcher (`cometchat/SKILL.md`) assumes the user is adding a chat surface — its placement vocabulary, component catalog, framework skills, and verification checklist are all chat-shaped. Calls is a different surface area:
-
-| Concern | Chat dispatcher | Calls dispatcher (this skill) |
-|---|---|---|
-| Packages | `chat-uikit-*` + `chat-sdk-*` | `chat-sdk-*` + `calls-sdk-*` (no UI Kit in standalone mode) |
-| Init | Chat SDK init + login | Chat SDK init + login + Calls SDK init (the dual-SDK contract; on iOS ≥5.0.2 prefer file-based `CometChatCalls.initFromSettings` reading `cometchat-settings.json` — ai-agent telemetry attribution — over the raw `CallAppSettings` builder; see `cometchat-ios-calls` §2) |
-| Placement question | "Where does **chat** live?" | "Where does the **call trigger** live?" + "Where do call logs live?" |
-| Components | Conversations, MessageList, Composer, Users, Groups | CallButtons, IncomingCall, OutgoingCall, OngoingCall, CallLogs |
-| `IncomingCall` mount | At chat surface (rings while user is chatting) | **At app root** — always-rendering, listens app-wide |
-| VoIP push (mobile) | Optional add-on | **Mandatory** in standalone mode — calls without ringing isn't a product |
-| Background lifecycle | N/A unless calls feature added | **Required** — Android foreground service / iOS CallKit + PushKit |
-
-The two dispatchers share `cometchat-{family}-core` (init + login + env + theme tokens) but diverge on everything else.
-
-## How v4.1 calls integration works
-
-Same conversational model as the chat dispatcher — detect, gather, plan, write, verify — but with a calls lens.
-
-### Steps
-
-#### Step 1 — Detect family + mode
-
-If the user came from the top-level `cometchat` dispatcher, framework + credentials are already in `.cometchat/config.json`. **Skip detection** and read:
-
-```bash
-npx @cometchat/skills-cli config show --json
-```
-
-If invoked directly (e.g. user typed *"add calls to my app"*), run:
-
-```bash
-npx @cometchat/skills-cli detect --json
-```
-
-Same family detection as the chat dispatcher (`reactjs`, `nextjs`, `react-router`, `astro`, `expo`, `react-native`, `angular`, `android`, `flutter`, `ios`).
-
-**Pick the integration mode** by looking at the project state:
-
-| Signal | Mode | What runs |
-|---|---|---|
-| `.cometchat/state.json` exists with chat surfaces wired | **Additive** — calls layered onto existing chat | Per-family `-calls` skill in additive section. Patches the existing provider to mount `IncomingCall` at root. Adds call buttons inline on chat surfaces. Optional VoIP push. |
-| `.cometchat/state.json` does NOT exist (or has no chat surfaces) AND `product === "voice-video"` | **Standalone** — calls is the product | Per-family `-calls` skill in standalone section. No chat UI Kit. CallButtons + IncomingCall + OngoingCall + CallLogs. VoIP push **wired**, not optional. `/calls` route or platform equivalent for call logs. |
-| Neither — user wants calls but it's ambiguous | **Ask** | AskUserQuestion: *"Are you adding calling alongside an existing chat integration, or building a calling-first app?"* |
-
-#### Step 2 — Verify credentials
-
-Calls reuses Chat SDK credentials. If `.env` (web/RN), `local.properties` (Android), `Secrets.swift` (iOS), `lib/cometchat_config.dart` (Flutter), or `src/environments/environment.ts` (Angular) already has `appId` / `region` / `authKey`, **skip credential setup**.
-
-If credentials are missing, hand back to `cometchat/SKILL.md` Step 2 — credential provisioning is the same regardless of product. Do not duplicate the auth flow here.
-
-#### Step 3 — Gather calls-specific requirements
-
-##### Step 3.0 — Calling mode (Ringing vs Session) ★
-
-This is the first calls-specific question. The Calls SDK supports two fundamentally different UX shapes — pick before anything else, because the rest of Step 3 + the per-family scaffold differ.
-
-**Resolve in priority order:**
-
-**1. Infer ONLY from explicit signals.** Don't default to either mode. The user must clearly indicate one of the two flavors before you skip the prompt:
-
-| User said something like… | Mode |
-|---|---|
-| "1:1 call", "user to user call", "phone call", "ring my friend", "call a contact", "FaceTime-like", "WhatsApp-style call" | **Ringing** |
-| "group call between friends", "conference call up to N people" (small group, one initiator who rings) | **Ringing** |
-| "meeting", "Google Meet", "Zoom-like", "scheduled meeting", "join with a link", "meeting room", "conference room", "webinar", "town hall", "virtual classroom" | **Session** |
-| "huddle" (Slack-style — instant join from a channel) | **Session** |
-| **Just "calls", "calling", "integrate calls", "add calls", "set up calling", "voice/video calls"** with NO further context about ringing-vs-meeting | **AMBIGUOUS — ASK (do NOT default)** |
-| Mixed signals ("calls and meetings", "phone calls or video conferencing") | **AMBIGUOUS — ASK** |
-
-The bottom rows are the load-bearing ones. **Generic phrases like "integrate calls" or "I want calling in my app" are NOT a signal for Ringing — they're a signal that the user hasn't told you yet.** Ask.
-
-If you DO have a clear signal, confirm with one line so the user can redirect:
-> "Got it — setting up Ringing (1:1 / group calls with an incoming-call screen). If you wanted meeting-room URLs instead, say so and I'll switch."
-
-**2. Use Tier 4 use-case context if available.** Use-cases telegraph the mode:
-
-| Use case | Mode |
-|---|---|
-| Telehealth provider/patient (1:1 visit) | Ringing |
-| Marketplace buyer ↔ seller | Ringing |
-| Customer support (agent ↔ customer) | Ringing |
-| Broadcast / webinar / town hall | Session |
-| Team huddle / standup | Session |
-
-**3. Only if you can't tell** — ask. Use this prompt **verbatim** — do NOT rephrase, do NOT swap options. Option 1 is "Session"; option 2 is "Ringing":
-
-- **question:** "What kind of calling experience are you building?"
-- **header:** "Calling mode"
-- **multiSelect:** false
-- **options (display in this exact order — Session FIRST, Ringing SECOND):**
-  1. label: "Session — meeting / conference room", description: "Multiple users join the same session by ID or link. No ringing. Like Google Meet, Zoom, or a Slack huddle. Examples: scheduled meetings, webinars, team huddles, classroom calls."
-  2. label: "Ringing — 1:1 or group calls", description: "One user calls another (or a small group). Recipient's device rings; they accept or decline. Like a phone call. Examples: WhatsApp, FaceTime, in-app voice/video calls between contacts."
-
-> **Strict-order rule:** render option 1 above option 2. Do not reorder. Session-first is standardized across CometChat product surfaces.
-
-Map to mode value:
-- "Ringing" → `mode === "ringing"`
-- "Session" → `mode === "session"`
-
-This drives which per-family reference loads at Step 6:
-
-| Mode | Reference (per-family) | Reference (Android V5) |
-|---|---|---|
-| `ringing` | `cometchat-{family}-calls/references/ringing-integration.md` | `cometchat-android-v5-calls/references/ringing-integration.md` |
-| `session` | `cometchat-{family}-calls/references/call-session.md` | `cometchat-android-v5-calls/references/join-session.md` |
-
-> **Note on the kit's prebuilt UI ("Standard" mode in earlier docs):** the UI Kit's `<CometChatCallButtons />` + `<CometChatIncomingCall />` + `<CometChatOngoingCall />` are a kit-provided implementation of **Ringing**, not a third mode. If the user picks Ringing AND wants the kit's prebuilt UI (most common), the per-family scaffold uses kit components and treats the ringing reference as the architectural ground-truth. If they want custom UI on top of the chat-SDK signaling, the ringing reference is the implementation guide.
-
-> **⚠️ Group calls do NOT use the Ringing channel** (validated 2026-05-15, applies to all kits). The kit's `<CometChatCallButtons group={g}>` sends a **custom meeting message** to the group via `CometChat.sendCustomMessage` with `type: "meeting"`, NOT `CometChat.initiateCall`. Other group members receive the meeting card in `<CometChatMessageList />` (kit-based receivers) OR a `MessageListener.onCustomMessageReceived` with `category: CATEGORY_CUSTOM` + `type: "meeting"` (custom-UI receivers). The `CallListener.onIncomingCallReceived` channel only fires for 1:1 user calls. If the user wants group calls, load `references/group-calls.md` IN ADDITION TO ringing-integration.md — group has its own architecture even though customers think of it as "ringing for groups."
-
-##### Step 3.1 — Call trigger placement (where the call starts from)
-
-Different from the chat dispatcher's Step 3a archetype question. Ask placement-intent on the **calls surface**:
-
-Ask the user (preserve the structured shape — `question`/`header`/`multiSelect`/`options[].label`/`options[].description`):
-- **question:** "How should users start a call in your app?"
-- **header:** "Call trigger"
-- **multiSelect:** false
-- **options** (the option set differs by mode — show only the rows matching `mode` from Step 3.0):
-
-  **If `mode === "ringing"`** — show these:
-  1. label: "Call button on user/contact profile", description: "Voice + video buttons next to a user's name. Best for marketplaces, social, dating, healthcare."
-  2. label: "Always-on '/calls' route", description: "Dedicated calls page with a 'Start a call' picker and call history. Best for telehealth, virtual events, contact centers."
-  3. label: "Embedded in chat surface", description: "Call buttons in the chat header — voice + video next to message threads. Best for apps that already have chat. (Additive mode only.)"
-  4. label: "Floating widget", description: "Always-visible call bubble — like Zoom's floating window. Best for support / sales tools."
-
-  **If `mode === "session"`** — show these instead:
-  1. label: "Meeting link route ('/meet/:sessionId')", description: "Shareable URLs that anyone with the link can join. Best for scheduled meetings, webinars, classrooms."
-  2. label: "Channel-bound huddle", description: "Session keyed to a chat channel/group ID — anyone in the channel can join the active huddle. Best for team collab apps."
-  3. label: "Lobby / waiting-room route", description: "User lands on a waiting screen, host admits. Best for telehealth, customer support."
-  4. label: "Custom — I'll wire it myself", description: "Just give me the SDK glue. I'll decide the surface."
-
-The chosen option drives which per-family `-calls` skill section to load and what to scaffold.
-
-**Then ask about call logs separately** — call logs are usually a different surface from the trigger:
-
-- **question:** "Where should call history live?"
-- **header:** "Call logs"
-- **options:**
-  1. label: "Dedicated /calls route (or screen)", description: "Recommended — full call history, filterable, jump to caller's profile."
-  2. label: "Inside the call trigger surface", description: "Compact list under the call button. Best when call volume is low."
-  3. label: "Don't show call history", description: "Skip — calls just happen, no log surface."
-
-#### Step 4 — Detect mandatory mobile prerequisites
-
-For mobile families (`android`, `ios`, `expo`, `react-native`, `flutter`), VoIP push is **non-negotiable in standalone mode** — without it, missed calls don't ring. Detect what's already wired so the per-family `-calls` skill knows what to add and what to skip:
-
-**Android:**
-- Firebase Cloud Messaging — look for `google-services.json` in `app/` and `id("com.google.gms.google-services")` in `app/build.gradle{.kts}`
-- Service registration — look for `<service android:name=".YourFirebaseMessagingService" ...>` in `AndroidManifest.xml`
-- ConnectionService — look for `android.permission.MANAGE_OWN_CALLS` and `BIND_TELECOM_CONNECTION_SERVICE` in `AndroidManifest.xml`
-- Foreground service type — look for `<service android:foregroundServiceType="phoneCall|microphone|camera">` (Android 14+ silently crashes without `phoneCall`)
-
-**iOS:**
-- CallKit — look for `import CallKit` and a `CXProvider` configured somewhere in source
-- PushKit — look for `import PushKit` and a `PKPushRegistry` listener (VoIP push token registration)
-- Capabilities — look for `Background Modes` with `voip` + `audio` + `remote-notification` in `Info.plist` and `entitlements`
-- Microphone + camera Info.plist usage strings
-
-**React Native:**
-- `react-native-callkeep` (CallKit + ConnectionService bridge) in `package.json`
-- `@react-native-firebase/messaging` (Android) and a `PushNotificationIOS` setup
-- `react-native-voip-push-notification` for iOS VoIP push tokens
-
-**Flutter:**
-- `flutter_callkit_incoming` in `pubspec.yaml`, OR a platform-channel bridge to native CallKit/ConnectionService
-- `firebase_messaging` for FCM
-- Native `Info.plist` and `AndroidManifest.xml` entries (Flutter doesn't auto-add these)
-
-Surface what's wired and what's missing. The per-family `-calls` skill writes the missing pieces — it never assumes they're already there.
-
-#### Step 5 — Show the plan and get approval
-
-Before writing anything, show the user exactly:
-- Which packages will be installed
-- Which files will be created vs modified vs left alone
-- Where the call trigger will land (with the file path)
-- Where call logs will land (or "skipped" if option 3 above)
-- For mobile: what VoIP push artifacts will be added (FCM service, CallKit provider, foreground service registration, manifest permissions, Info.plist entries)
-- What the user must do manually that the skill can't (Android: enable FCM in Firebase console; iOS: add VoIP Services certificate to App Store Connect; Flutter: bump `minSdkVersion` if below platform floor)
-
-Wait for explicit approval. Then load the per-family `-calls` skill and run its scaffold.
-
-#### Step 6 — Hand off to the per-family skill
-
-Load the matching skill from your context:
-
-| Detected family | Skill to load |
-|---|---|
-| `reactjs` / `nextjs` / `react-router` / `astro` | `cometchat-react-calls` |
-| `expo` / `react-native` | `cometchat-native-calls` |
-| `angular` | `cometchat-angular-calls` |
-| `android` + `android_version === "v5"` | `cometchat-android-v5-calls` |
-| `android` + `android_version === "v6"` | `cometchat-android-v6-calls` |
-| `flutter` + `flutter_version === "v5"` | `cometchat-flutter-v5-calls` (existing) |
-| `flutter` + `flutter_version === "v6"` | `cometchat-flutter-v6-calls` (existing) |
-| `ios` | `cometchat-ios-calls` |
-
-Pass the gathered context: **`mode`** (`ringing` | `session` from Step 3.0), **standalone vs additive** (Step 1), **trigger placement** (Step 3.1), log placement, mobile prereqs status.
-
-The per-family skill loads the matching mode reference as its primary blueprint:
-
-| `mode` | Reference loaded inside the per-family skill |
-|---|---|
-| `ringing` (1:1 user calls) | `references/ringing-integration.md` (Android V5: same name) |
-| `session` (meeting-room URLs, no chat-side signaling) | `references/call-session.md` (Android V5: `references/join-session.md`) |
-
-**Additionally** — if `groupCalls === true` in the gathered context (the user mentioned "group calls", "team meetings", "huddles", or selected `group` as a call target in Step 3.1), **ALSO load `references/group-calls.md` from the per-family skill**. Group calls use a different signaling channel than 1:1 ringing — they broadcast a custom `"meeting"` message instead of `CometChat.initiateCall`. Loading only `ringing-integration.md` produces code that works for 1:1 but silently breaks for groups on custom-UI receivers. The `group-calls.md` reference exists for all 8 families. See the Step 3.0 disclosure above for the underlying semantic.
-
-The per-family skill writes code; this dispatcher does not.
-
-If the per-family skill isn't loaded into the agent's context (i.e. the user installed `@cometchat/skills` before v4.1 and never re-ran `npx @cometchat/skills add --family <family>`), tell the user once:
-
-> "I just installed the {family} calls skill into your workspace. Please re-run `/cometchat-calls` to continue — your config is saved in `.cometchat/config.json`, so the next run picks up at code generation without re-asking the placement questions."
-
-Same hot-reload constraint as the chat dispatcher: agents snapshot the skill set at session start and don't reload mid-session. Continuing this session would mean writing calls code from training memory — which the per-family skill explicitly forbids.
-
-#### Step 7 — Verify
-
-After the per-family skill writes code, run:
-
-```bash
-npx @cometchat/skills-cli verify --calls --json
-```
-
-(Verifier flag `--calls` is added in CLI 2.4.0 alongside this dispatcher; it checks for the dual-SDK init, IncomingCall root mount, VoIP push wiring on mobile, and the call trigger / logs placements the user picked.)
-
-If verify passes, drop the user into the iteration menu — same shape as the chat dispatcher's Step 7, with calls-specific options:
-
-- Add a feature (recording, screen sharing, PiP, in-call chat, custom UI)
-- Customize call screen / participant list / control panel
-- Set up production auth (server-minted tokens, no Auth Key in calls flow)
-- Run diagnostics
-
-## Hard rules (every per-family `-calls` skill must enforce these)
-
-These are the production-grade non-negotiables. The dispatcher checks them in Step 5's plan and the per-family skill is responsible for writing them:
-
-1. **Dual-SDK contract.** Chat SDK does `initiateCall` (sends a `MessageType.CALL`); Calls SDK does `joinSession`. They are NOT interchangeable. The Android skill leads with this — agents trained on multi-platform CometChat data will conflate `com.cometchat.chat.core.Call` with `com.cometchat.chat.models.Call` and write code that compiles but silently breaks.
-2. **VoIP push wired in standalone mode, not documented.** CallKit + PushKit (iOS), ConnectionService + FCM high-priority (Android), `react-native-callkeep` (RN), `flutter_callkit_incoming` (Flutter). Documentation isn't enough — without working push, missed calls don't ring.
-3. **Foreground / background lifecycle correct.** Android 14+ silently crashes on wrong `foregroundServiceType` for ongoing calls; iOS requires CallKit reporting for background audio. Belongs in the `-calls` skill body, not a "see also" reference.
-4. **Server-minted auth tokens for the calls path.** Production calls flows must use auth tokens, never Auth Key. The skill detects existing token endpoints (same way the chat dispatcher does) and uses `loginWithAuthToken()`.
-5. **Cleanup on hangup.** Camera-light-stays-on / mic-stays-hot is the canonical "looks fine in dev, fails review" bug. Every per-family skill includes the explicit teardown checklist.
-6. **Permissions with rationale.** Microphone, camera, screen-record (where supported), notifications. All four, all with usage strings.
-7. **`IncomingCall` mounted at app root in standalone mode.** Not at the chat surface — calls is the whole product, the listener has to be alive everywhere.
-8. **Honor "SDK only" when the user says SDK only (ENG-35711).** If the developer explicitly asks for the Calls SDK without UI Kit components — phrasing like *"pure SDK,"* *"no UI Kit components,"* *"build my own call UI,"* *"SDK-only path"* — the per-family skill MUST NOT scaffold `CometChatCallButtons`, `CometChatIncomingCall`, `CometChatOutgoingCall`, or `CometChatOngoingCall`. Use Chat SDK `CometChat.initiateCall` for signaling + Calls SDK `joinSession` (and a hand-written button/screen) for the surface. **Never silently fall back to UI Kit components** "because they're easier" — that's a documented frustration from two testers. If the developer's request can't be served without a UI Kit component, ask explicitly: *"This piece needs the kit's `<CometChatXxx>` — happy to use it, or do you want a hand-written equivalent?"* Don't decide for them.
-
-## Anti-patterns
-
-1. **Don't try to add `apply-feature calls` from this dispatcher.** That CLI command is the v4 chat-flow path — it returns the npm install command and that's it. This dispatcher does the actual integration end-to-end. If the user is in `chat-messaging+voice-video` mode, the chat flow already ran; just enter additive mode here. Never call `apply-feature calls` from inside this skill.
-2. **Don't load `cometchat-components` or `cometchat-placement` (the chat catalogs).** Those are chat-shaped. The per-family `-calls` skill has its own component list (CallButtons, IncomingCall, OutgoingCall, OngoingCall, CallLogs) and its own placement vocabulary (call trigger, log surface, root listener). Loading the chat catalogs leaks chat assumptions into calls code.
-3. **Don't ask the chat archetype question** ("Messaging app / Marketplace / SaaS / …"). That taxonomy is for *where chat lives*. Calls placement is *where the call trigger lives* + *where logs live* + *whether VoIP push is mandatory*. Different vocabulary, different recommendations.
-4. **Don't skip VoIP push in standalone mode** even if the user says "I'll add it later." Calls without ringing isn't a product. The dispatcher refuses standalone-mode scaffold without VoIP push wired (or at minimum scaffolded with a clear TODO and red-banner warning in the call screen).
-5. **Don't mix V5 and V6 cohorts** (Android, Flutter). The Calls SDK coordinates differ — V5 Android ships `calls-sdk-android` as a separate Cloudsmith dep; V6 folds calls into the unified `chatuikit-{compose,kotlin}-android` package. Same for Flutter. Read `android_version` / `flutter_version` from `.cometchat/config.json` and route to the matching cohort skill.
-
-## Ground truth references
-
-Per-family `-calls` skills cite from these sources. The dispatcher itself doesn't write code; the per-family skills do. To verify which SDK signatures the skills target, check each family's **published SDK artifact + public docs** (the source-of-truth — an earlier draft pointed at a local `~/Downloads/calls-sdk/` clone that no longer exists; use the installed/published packages instead):
-
-- **Android V5:** `com.cometchat:calls-sdk-android:5.x` (decompile the Maven AAR, or `javap` the Gradle-cached classes) + [docs](https://www.cometchat.com/docs/sdk/android/overview). The 17 sub-topics are folded into `cometchat-android-v5-calls/references/{recording,screen-sharing,picture-in-picture,background-handling,voip-calling,audio-controls,video-controls,participant-management,custom-ui,in-call-chat,call-logs,session-settings,event-listeners,join-session,ringing-integration,setup}.md`.
-- **iOS V5:** `CometChatCallsSDK` 5.x — the `.swiftinterface` inside the resolved framework (SPM `.build/artifacts/…` or CocoaPods `Pods/…`; it ships vendored inside `CometChatUIKitSwift` for additive) + [docs](https://www.cometchat.com/docs/calls/ios/overview).
-- **JavaScript (web):** `@cometchat/calls-sdk-javascript@5` — the package `.d.ts` (`node_modules/@cometchat/calls-sdk-javascript/dist/index.d.ts`) + [docs](https://www.cometchat.com/docs/calls/javascript/overview).
-- **React Native:** `@cometchat/calls-sdk-react-native@5` — the package `.d.ts` + `@cometchat/calls-lib-webrtc` (Cloudsmith) + [docs](https://www.cometchat.com/docs/calls/react-native/overview).
-- **Flutter:** `cometchat_calls_sdk` (V5: paired `cometchat_calls_uikit:^5.0`; V6: folded into `cometchat_chat_uikit:^6.0`) — the pub-cache source — plus the `cometchat-flutter-v5-calls` / `cometchat-flutter-v6-calls` skills (audited against it).
-- **Angular:** the same JS Calls SDK (`@cometchat/calls-sdk-javascript`) wrapped in Angular Inputs/Outputs — verify via `@cometchat/chat-uikit-angular` `.d.ts` + the JS SDK `.d.ts`.
-
-## Two calling modes (Ringing + Session) — and the kit's prebuilt UI for Ringing
-
-> **Naming clarification (ENG-35699 follow-up):** This section labels three rows below — "Standard", "Ringing", and "Call Session" — but **architecturally there are only TWO modes**: Ringing (signaling-driven) and Session (URL-driven). "Standard" is the **kit's prebuilt UI for Ringing** (using `<CometChatCallButtons>` + `<CometChatIncomingCall>`), not a third architectural mode. The Step 3.0 prompt above asks Ringing vs Session — that's the load-bearing decision. The Standard row is the most-common rendering choice WITHIN Ringing mode.
-
-CometChat supports two underlying calling workflows; the table below splits Ringing into "Standard (kit-prebuilt UI)" vs "Ringing (custom UI on signaling)" for routing purposes only:
-
-| Row | Underlying mode | Driver | When to use | Per-family ref |
-|---|---|---|---|---|
-| **Standard** | Ringing | UI Kit (`CometChatCallButtons` + `CometChatIncomingCall`) | 80% case — chat-driven calls with prebuilt UI | covered in per-family `SKILL.md` |
-| **Ringing (custom UI)** | Ringing | Chat SDK call entity + Calls SDK session | Custom incoming/outgoing call UI on top of CometChat signaling | `references/ringing-integration.md` |
-| **Call Session** | Session | Calls SDK `joinSession` directly (no ringing) | Meeting-room URLs, scheduled calls, conference rooms | `references/call-session.md` |
-
-Standard is the default Ringing rendering unless the user explicitly says "custom incoming call UI" (→ Ringing custom) or "meeting link / join with sessionId" (→ Call Session). The Tier 4 use-cases telegraph which mode they want — broadcast + team huddles use Call Session; telehealth + marketplace + support use Standard or Ringing custom.
-
-## Use-case integration patterns (Tier 4)
-
-If the user describes their product clearly, route to the matching use-case reference for opinionated CallSettings + UX + compliance callouts:
-
-- **Telehealth / virtual visits** → `references/use-case-telehealth.md` — provider/patient flow, two-party consent recording, waiting room, HIPAA notes
-- **Marketplace (buyer ↔ seller)** → `references/use-case-marketplace.md` — opaque UIDs, time-bounded access, anti-fraud heuristics
-- **Customer support / help desk** → `references/use-case-support.md` — agent queue, auto-record for QA, post-call CSAT
-- **Broadcast / webinar / town hall** → `references/use-case-broadcast.md` — locked SIDEBAR, mute-by-default attendees, raise-hand Q&A, RTMP bridge for 100+
-- **Team huddle / standup / collab** → `references/use-case-team.md` — TILE layout, opt-in join, recording auto-posted to channel
-
-Each use-case doc covers end-to-end flow + recommended `CallSettings` + role-based UI + verification checklist. Apply on top of the per-family `-calls` skill, don't duplicate the architecture work.
-
-## Migration playbooks
-
-For customers upgrading or layering calls on top of an existing chat install, every per-family calls skill ships:
-
-- `references/migration-v4-to-v5.md` — Calls SDK v4 → v5 (drop-in replacement; v5 APIs unlock granular event listeners + simpler init)
-- `references/add-calls-to-existing-chat.md` — additive integration on top of an existing chat surface (init order, login order, IncomingCall mounting, server push setup)
-
-Cite the right family. The web reference (`cometchat-react-calls`) is canonical for migration-v4-to-v5 — sister docs in other families add only family-specific deltas.
-
-## Server-side push templates (Tier 3)
-
-VoIP push wiring is platform-specific. Three canonical templates ship under per-family `references/`:
-
-- iOS APNs PushKit (.p8 token auth) — `cometchat-ios-calls/references/server-apns-pushkit.md`
-- Android FCM HTTP v1 (data-only, priority HIGH) — `cometchat-android-v5-calls/references/server-fcm-voip.md` (V6 sister with Compose IncomingCallActivity)
-- Web Push VAPID (best-effort browser ringing) — `cometchat-react-calls/references/server-web-push-vapid.md` (Angular sister)
-
-Hybrid platforms (RN, Flutter) ship `references/server-push-bridge.md` that routes to the right canonical by `Platform.OS` / `Platform.is{iOS,Android}`.
-
-## What this dispatcher does NOT cover
-
-- **The actual code.** Per-family `-calls` skills write the integration. This dispatcher routes.
-- **AI-Agent or BYO-Agent flows.** Different surface entirely; out of scope. The top-level `cometchat` dispatcher's Step 3.0 routes those to docs.
-- **Moderation features for calls** (recording-with-consent prompts, profanity filter on in-call chat, etc.). Same status as the chat dispatcher — moderation is dashboard-only.
-- **Call analytics dashboards** — the CometChat dashboard surfaces these, no integration work needed.
-
-## Pointer back to chat dispatcher
-
-If the user invoked `/cometchat-calls` directly but the project has no integration at all yet (no `.cometchat/config.json`, no chat surfaces), and they pick the **additive** mode by mistake, redirect:
-
-> "Looks like you don't have CometChat integrated yet. For a calling-first app, that's fine — I'll run the standalone calls flow now. If you want chat alongside, run `/cometchat` first to set up chat, then come back to add calls."
-
-Don't auto-route to `cometchat/SKILL.md` from here — it's the user's call (no pun intended) which surface is primary.

package/skills/cometchat-calls/references/use-case-broadcast.md

@@ -1,199 +0,0 @@
-# Use case — Broadcast / Webinar
-
-A presenter (or panel) addresses a large audience. Most attendees have audio + video off; a small set of presenters are visible. Q&A via raise-hand. Optional broadcast to YouTube/RTMP via server-side bridge.
-
-**Examples:** Town halls, all-hands, product launches, conference sessions.
-
-**Scale note:** CometChat Calls SDK supports up to ~50 simultaneous video streams per call (varies by plan). For 100+ broadcast use cases, consider streaming-protocol bridges (RTMP push to YouTube/Twitch) where most attendees consume via streaming, not bidirectional WebRTC.
-
----
-
-## End-to-end flow
-
-```
-1. Presenter creates a "Broadcast" group (CometChat group keyed to event ID)
-   ↓
-2. Server pre-creates the group with presenters as moderators
-   ↓
-3. Attendees join the group (group is public OR password-gated for paid events)
-   ↓
-4. Event time: presenter starts call → attendees auto-join (no incoming-call ring)
-   ↓
-5. By default: all attendees mic + camera OFF
-   Presenter has mic + camera ON
-   ↓
-6. Q&A: attendee taps "Raise hand" → presenter sees → presenter unmutes them
-   ↓
-7. Server-side: optional RTMP push streams the call to YouTube Live / Twitch / a CDN
-   ↓
-8. Presenter ends call → recording uploaded → notification + replay link sent to all attendees
-```
-
----
-
-## Recommended call settings
-
-```ts
-const settings = {
-  layout: "SIDEBAR",                     // Presenter dominant
-  hideChangeLayoutButton: true,           // Don't let attendees change
-
-  hideRecordingButton: false,             // Presenter records
-  autoStartRecording: true,        // Always record broadcasts (replay value)
-
-  hideScreenSharingButton: false,           // For slides
-
-  hideChatButton: false,                  // Q&A overflow + reactions
-  hideShareInviteButton: false,           // Encourage sharing
-
-  hideRaiseHandButton: false,             // Critical for Q&A
-
-  // Attendee-side: mic + camera off by default
-  joinWithMutedAudio: true,
-  joinWithMutedVideo: true,
-
-  idleTimeoutPeriodBeforePrompt: 86_400_000,                        // Disable idle timeout — events run long
-};
-```
-
-Presenters override `joinWithMutedAudio/Video: false` in their flow.
-
----
-
-## Roles + permissions
-
-In the CometChat group, set scopes:
-
-```ts
-// Server-side, when creating the broadcast group:
-await cometchatApi.createGroup({
-  guid: `event-${eventId}`,
-  members: [
-    { uid: presenterUid, scope: "admin" },
-    ...coPresenterUids.map((uid) => ({ uid, scope: "moderator" })),
-    // Attendees added on join (or batch-added pre-event for paid)
-  ],
-});
-```
-
-Then enforce role-based UI:
-
-```tsx
-function CallControls({ groupGuid, currentUserUid }: Props) {
-  const role = useUserRoleInGroup(groupGuid, currentUserUid);
-  const isPresenter = role === "admin" || role === "moderator";
-
-  return (
-    <div>
-      {isPresenter && <RecordingButton />}
-      {isPresenter && <ScreenShareButton />}
-      {!isPresenter && <RaiseHandButton />}
-      {/* Attendees see a stripped-down toolbar */}
-    </div>
-  );
-}
-```
-
----
-
-## Raise-hand → unmute flow
-
-```tsx
-// Presenter's view: see attendees with raised hands, tap to unmute
-function PresenterRaisedHandsList() {
-  const [raised, setRaised] = useState<RaisedHand[]>([]);
-
-  useEffect(() => {
-    CometChatCalls.addEventListener("onParticipantHandRaised", (event: RaisedHand) => {
-      setRaised((prev) => [...prev, event]);
-    });
-    CometChatCalls.addEventListener("onParticipantHandLowered", (event: RaisedHand) => {
-      setRaised((prev) => prev.filter((p) => p.uid !== event.uid));
-    });
-  }, []);
-
-  async function unmuteParticipant(uid: string) {
-    // Send a custom message asking the participant to unmute themselves
-    // (CometChat doesn't support force-unmute — privacy).
-    // There is NO CometChatCalls.lowerParticipantHand(uid) — the SDK only
-    // exposes lowerHand() for the LOCAL user. To lower someone else's hand,
-    // message them and let their client call lowerHand() (see raise-hand.md).
-    const msg = new CometChat.CustomMessage(
-      uid, CometChat.RECEIVER_TYPE.USER, "lower_hand", {},
-    );
-    await CometChat.sendCustomMessage(msg);
-    // Optimistically drop them from our local raised-hands list
-    setRaised((prev) => prev.filter((p) => p.uid !== uid));
-  }
-
-  return (
-    <ul>
-      {raised.map((p) => (
-        <li key={p.uid}>
-          {p.name}
-          <button onClick={() => unmuteParticipant(p.uid)}>Allow to speak</button>
-        </li>
-      ))}
-    </ul>
-  );
-}
-```
-
----
-
-## RTMP bridge for streaming
-
-For broadcasts beyond CometChat's WebRTC capacity, server-side RTMP push:
-
-```js
-// Server-side: when broadcast starts, spin up an RTMP bridge that joins
-// the call as a "viewer" and pushes the composited stream to YouTube Live.
-// Use a service like Daily.co's RTMP-out, AWS IVS, or roll your own with
-// FFmpeg + headless Chrome.
-//
-// CometChat does not ship an RTMP bridge — this is application infrastructure.
-async function startRtmpBridge(eventId: string, rtmpUrl: string) {
-  await rtmpBridgeService.start({
-    sessionId: eventId,
-    rtmpDestination: rtmpUrl,
-    // Bridge joins with a service-account UID
-    serviceAccountUid: `bridge-${eventId}`,
-  });
-}
-```
-
----
-
-## Anti-patterns
-
-1. **No `joinWithMutedAudio: true` for attendees.** 50 people unmuted at once = chaos.
-2. **No role differentiation.** Attendees can record / kick / share-invite → vandalism.
-3. **Same SDK call for 200+ attendees.** WebRTC degrades. Use RTMP bridge for large audiences.
-4. **No idle timeout disable.** Default 30min idle ends a 60min event mid-Q&A.
-5. **Recording broadcasted to YouTube without disclosure.** GDPR / CCPA: attendees must know they're being recorded for public distribution.
-6. **No pre-event check.** Presenter joins 5min before, mic doesn't work, panic. Have a "tech check" room they can join 30min ahead.
-
----
-
-## Verification checklist
-
-- [ ] Group created server-side with presenter as admin
-- [ ] Attendees join muted (audio + video)
-- [ ] Layout locked to SIDEBAR
-- [ ] Recording auto-on
-- [ ] Idle timeout disabled
-- [ ] Raise-hand → presenter approval flow wired
-- [ ] Role-based UI (presenter sees recording/screenshare; attendees see raise-hand)
-- [ ] RTMP bridge for 100+ attendees
-- [ ] GDPR/CCPA recording notice in attendee-facing copy
-- [ ] Tech check room available pre-event
-
----
-
-## Pointers
-
-- `cometchat-react-calls/references/raise-hand.md` — raise-hand reference
-- `cometchat-react-calls/references/recording.md` — recording reference
-- `cometchat-react-calls/references/screen-sharing.md` — for slides
-- `cometchat-react-calls/references/call-layouts.md` — SIDEBAR layout
-- `cometchat-react/SKILL.md` — group scope + admin patterns