@cometchat/skills 4.4.2 → 5.0.0

package/skills/cometchat-js-v5-sdk/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: cometchat-js-v5-sdk
+description: "Add voice & video calling to any web app FROM SCRATCH with the headless CometChat Calls SDK v5 (`@cometchat/calls-sdk-javascript@5`) — no prebuilt UI Kit. init→login→generateToken→joinSession, event listeners, in-call actions (mute/video/screen-share/record/layout), meet-style session rooms AND 1:1 ringing (Chat SDK signaling + Calls SDK media). Triggers: 'add calling from scratch', 'standalone video call', 'headless calls sdk', 'build my own call UI', 'meeting room join by session id', 'one-on-one ringing call without uikit'."
+license: "MIT"
+compatibility: "Modern WebRTC browser (Chrome 72+/Firefox 68+/Safari 12.1+/Edge 79+); HTTPS (or localhost) for getUserMedia; @cometchat/calls-sdk-javascript@^5 (5.0.5). 1:1 ringing also needs @cometchat/chat-sdk-javascript@^4 for signaling. Framework-agnostic (vanilla JS core; React/Vue/Angular/Next recipes)."
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat calls sdk v5 headless voice video webrtc javascript calling standalone"
+---
+
+> **Ground truth:** `@cometchat/calls-sdk-javascript@5` + catalog `web-calls-v5.json` (the closed symbol list — every `CometChatCalls.*` below exists in it). Official docs: `/calls/javascript/**` = **v5** · Docs MCP. Fetch exact `SessionSettings` fields, event names, and action-method signatures from the docs (`references/docs-map.md`) — never memory. **APPEND to the user's app — additive wiring only** (`RULES.md`). This is the HEADLESS path (no UI Kit); for the prebuilt drop-in call UI use `cometchat-react-v7-calls` instead.
+
+## Companion skills (read first)
+- **Standalone/headless entry** — this skill owns its own package (the Calls SDK) and has no `-core` sibling; it is self-contained for meet-style calling.
+- **For 1:1 RINGING only** it also drives the **Chat SDK** (`@cometchat/chat-sdk-javascript@4`) for call signaling — signatures fetched from docs via `references/docs-map.md` (§ "1:1 RINGING"). It does NOT depend on the React UI Kit.
+- **Prefer the UI Kit instead?** If the app also wants chat and a prebuilt call UI, use `cometchat-react-v7-core` + `cometchat-react-v7-calls` — not this skill.
+
+## Use this skill when
+"add calling from scratch / without the UI Kit", "standalone voice/video", "build my own call screen", "headless calls SDK", "meeting-room join by session id", "one-on-one ringing call". Precondition: the caller chose the **from-scratch / standalone** path (the "add calling" router asks this). If they want the prebuilt call UI, route to `cometchat-react-v7-calls`.
+
+## Prerequisites & install
+```bash
+npm install @cometchat/calls-sdk-javascript@5
+```
+- **1:1 ringing** additionally needs the Chat SDK for signaling:
+  ```bash
+  npm install @cometchat/chat-sdk-javascript@4
+  ```
+- Credentials/env: App ID · Region · Auth Key (dev only). To fetch from the dashboard, load the CLI on demand — `npx @cometchat/skills-cli@3 auth login` → `provision use --app-id <id> --json` (writes `.cometchat/config.json`; `@3` pins the CLI major that matches the v5 skills). Or paste manually from Dashboard → Credentials. Mint **auth tokens server-side** for production; never ship the Auth Key. HTTPS (or `localhost`) is required for camera/mic (`getUserMedia`).
+
+## Init & login ordering (BAKED — invariant)
+`CometChatCalls.init(...)` (once, resolve first) → `CometChatCalls.login(uid, authKey)` **or** `loginWithAuthToken(token)` → then `generateToken` / `joinSession` / listeners. Nothing renders/joins before init+login resolve.
+- **DEFAULT to `CometChatCalls.initFromSettings(settings)`** — the ai-agent / telemetry-attributed path (persists `integrationSource="ai-agent"`), parallel to how the chat core inits via `CometChatUIKit.initFromSettings` / `CometChat.initFromSettings` (RULES §5). It is **INTENTIONALLY undocumented** — ai-agent-only (`@nodoc`, same posture as `CometChatUIKit.initFromSettings` — DOCS-BACKLOG F4/C1) — so the settings-object shape is **baked in `references/docs-map.md`**; pass it **INLINE** (no physical `cometchat-settings.json` file required), never fetched from `/calls/javascript/setup`. The publicly-documented **`CometChatCalls.init({ appId, region })` is the FALLBACK only** (a non-skills / doc-following context).
+- Coexisting with the Chat SDK / UI Kit? Their `login()` can re-init the Calls SDK with only appId/region and wipe custom hosts — re-run your calls init after their login, before `CometChatCalls.login`.
+
+## Two build modes (BAKED — the router picks one)
+- **Meet-style (session room)** — Calls SDK ONLY. Everyone who joins the same `sessionId` lands in the same call: `generateToken(sessionId)` → `joinSession(token, sessionSettings, containerEl)`. No ringing. This is the `/calls/javascript/react-integration` flow.
+- **1:1 ringing** — Chat SDK signals, Calls SDK carries media: `CometChat.initiateCall` → peer `CallListener.onIncomingCallReceived` → `acceptCall`/`rejectCall` → `CometChatCalls.generateToken(call.getSessionId())` → `joinSession(...)`. Fetch Chat-SDK signatures via `references/docs-map.md` § "1:1 RINGING".
+
+## SDK method map (BAKED closed list — from the catalog; signatures → FETCH from docs)
+- **Lifecycle:** `CometChatCalls.init` · `CometChatCalls.initFromSettings` · `CometChatCalls.login` · `CometChatCalls.loginWithAuthToken` · `CometChatCalls.logout` · `CometChatCalls.getLoggedInUser` · `CometChatCalls.isUserLoggedIn`
+- **Session:** `CometChatCalls.generateToken` · `CometChatCalls.joinSession` · `CometChatCalls.leaveSession` (`startSession` is **deprecated** → use `joinSession`)
+- **Events:** `CometChatCalls.addEventListener(eventName, cb, { signal? }) → unsubscribe()` (event names: FETCH the full list from `/calls/javascript/events`)
+- **In-call actions** — ⚠️ **for CUSTOM controls ONLY; the default `joinSession` UI already renders all of these** (see the first pitfall). Only reach for them when the user EXPLICITLY asks to replace the built-in controls: `muteAudio`/`unmuteAudio`/`toggleAudio` · `pauseVideo`/`resumeVideo`/`toggleVideo` · `setLayout` · `startRecording`/`stopRecording` · `startScreenSharing`/`stopScreenSharing` · `raiseHand`/`lowerHand` · `switchCamera` · `pinParticipant`/`unpinParticipant` · `showParticipantList`/`hideParticipantList`
+- **Devices:** `getAudioInputDevices` · `getAudioOutputDevices` · `getVideoInputDevices` · `getCurrent*Device`
+- **Call logs:** `CometChatCalls.CallLogRequestBuilder` → `fetchNext()` (paginated; shape → docs)
+- **Constants:** `CometChatCalls.constants.LAYOUT` (`TILE`/`SIDEBAR`/`SPOTLIGHT`) · `.TYPE` (`VOICE`/`VIDEO`) · `.CAMERA_FACING`
+> This map is a **curated highlight, NOT the full surface** — the AUTHORITATIVE closed list is the **`web-calls-v5.json` catalog** (83 symbols; it also carries `toggleHand`/`toggleParticipantList`/`endSessionForAll`/`muteParticipant`/`pauseParticipantVideo`/`setChatButtonUnreadCount`/`switchToVideoCall`, device setters (`setAudioInputDevice`…), the virtual-background methods, `startStreaming`/`stopStreaming` (**RTMP live-streaming** — with `streamUrl`/`streamKey`/`hideStreamingButton` in `SessionSettings`; neither the SKILL map above nor the `/calls/javascript/actions` doc foregrounds it, but it is real), `startTranscription`/`stopTranscription` (v5.0.5 — see `/calls/javascript/transcription`), and `TranscriptRequestBuilder`, among others). A symbol is real **iff it's in the catalog** — confirm THERE (not just this map), then fetch its exact signature/params from the docs page in `references/docs-map.md`.
+
+## Listener lifecycle (BAKED)
+`addEventListener` RETURNS an unsubscribe function — collect them and call every one on teardown (React: in the effect cleanup), and `CometChatCalls.leaveSession()` on unmount. Register listeners BEFORE `joinSession`. Never leak. You can also pass an `AbortSignal` via the `{ signal }` option for bulk teardown.
+
+## Least-code recipe (meet-style, framework-agnostic)
+```ts
+// STRICT-TS-CLEAN: type the settings with the EXPORTED SessionSettings, narrow region.
+import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
+import type { SessionSettings } from "@cometchat/calls-sdk-javascript"; // exported; SessionType/Layout are NOT
+
+1. await CometChatCalls.initFromSettings({ appId, region: region as "us"|"eu"|"in", credentials: { authKey: AUTH_KEY }, callsSDK: {}, chatSDK: {}, uiKit: {} }) // ai-agent telemetry default (integrationSource="ai-agent"); init({appId,region}) is the public-doc fallback
+2. await CometChatCalls.login(uid, AUTH_KEY)               // or loginWithAuthToken(token)
+3. const { token } = await CometChatCalls.generateToken(sessionId)
+4. const unsub = CometChatCalls.addEventListener("onSessionLeft", () => cleanup())
+5. const callSettings: SessionSettings = { sessionType: "VIDEO", layout: "TILE" } // annotate → literals narrow
+   await CometChatCalls.joinSession(token, callSettings, containerEl)
+6. // NO control buttons needed — joinSession's UI ALREADY renders mute/video/screen-share/raise-hand/leave.
+7. // teardown → unsub(); CometChatCalls.leaveSession()
+```
+The `containerEl` MUST have real dimensions — the SDK renders its call surface into it. Fetch the full `SessionSettings` field list from `/calls/javascript/session-settings`. (In plain JS drop the annotations; the doc pages show that JS form.)
+
+## Framework notes (same SDK, per-framework glue)
+The recipe above is framework-agnostic; the only per-framework part is WHERE you register listeners / mount the container / tear down. Verified live on React and Angular.
+- **React:** provider or component — init via `CometChatCalls.initFromSettings(...)` (the telemetry-attributed default — `integrationSource="ai-agent"`; `init({appId,region})` is the public-doc fallback), then register listeners + `joinSession` in a `useEffect`; teardown in the effect cleanup (call every unsubscribe + `leaveSession`). Recipe: `/calls/javascript/react-integration`.
+- **Angular:** a **DI service** wrapping `CometChatCalls` (init via `CometChatCalls.initFromSettings(...)` — the telemetry-attributed default (`integrationSource="ai-agent"`; `init({appId,region})` is the public-doc fallback) → login, `generateToken`, typed `joinSession`, `leaveSession`; expose readiness via an RxJS `BehaviorSubject`) + a component with a **sized `@ViewChild('callContainer') ElementRef`** container; register listeners BEFORE `joinSession`; teardown in **`ngOnDestroy`** (unsubscribe all + `leaveSession`). Recipe: `/calls/javascript/angular-integration` — but ⚠️ THREE things to override:
+  - **(a)** its example wires external Mute/Video/Leave buttons — **IGNORE them** (pitfall #1: `joinSession`'s UI already has the controls);
+  - **(b)** it targets legacy `@NgModule`/`app.module.ts` — a modern `ng new` is **standalone** (`bootstrapApplication` + `app.config.ts`, class `App`), so use the standalone variant;
+  - **(c) ⚠️ NgZone / change detection (the silent dead-state).** CometChat SDK callbacks — event listeners AND the `login`/`generateToken`/`joinSession` promise resolutions — fire OUTSIDE Angular's zone, so any component state you set inside them **won't trigger change detection** (symptom: readiness/call buttons *silently never enable*, even though the SDK succeeded). Fix: drive the template off your `BehaviorSubject` via the **`async` pipe**, AND/OR wrap state writes in **`this.zone.run(() => …)`** (inject `NgZone`) or call `ChangeDetectorRef.detectChanges()`. Not optional — the app looks broken without it.
+
+## Common pitfalls (BAKED)
+- **Don't duplicate the built-in call controls (the #1 mistake).** `joinSession` renders a COMPLETE call UI — mute, camera on/off, screen-share, raise-hand, participant list, layout switch, and the red leave/end button are ALL built into the surface it mounts in `containerEl`. Do **NOT** add your own Mute / Start-video / Share-screen / Leave buttons around the container: they are redundant, duplicate the SDK's own controls, and drift out of sync with the real call state. The `muteAudio`/`pauseVideo`/`leaveSession`/… methods are for CUSTOM controls ONLY — reach for them **just when the user EXPLICITLY asks** to replace the default controls (and hide the built-in ones first via `SessionSettings` — `hideControlPanel` for the whole bar, or per-button flags like `hideToggleAudioButton`/`hideRaiseHandButton`/`hideChatButton`; the canonical recipe is `/calls/javascript/custom-control-panel`, fields on `/calls/javascript/session-settings`). Default = render the call surface and stop.
+- **Zero-dimension container** — `joinSession` mounts into `containerEl`; if it has `height:0` the call renders invisibly. Give it explicit size (e.g. `height: 500px` / `100dvh`).
+- **HTTP (not HTTPS)** — `getUserMedia` needs a secure context; camera/mic silently fail off `localhost`.
+- **Joining before init+login resolve** — `generateToken`/`joinSession` reject; always `await` init then login first.
+- **Leaked listeners / no `leaveSession`** — every `addEventListener` unsubscribe must run on teardown; call `leaveSession()` on unmount.
+- **`startSession` is deprecated** — use `joinSession`; don't pass the old `CallSettings` builder where a plain `SessionSettings` object is expected.
+- **Host wipe on coexisting Chat-SDK login** — re-init the Calls SDK after the Chat SDK/UI Kit logs in (see Init ordering).
+- **version_conflict** — the Calls SDK is **major 5**, distinct from the Chat SDK's v4; do not "upgrade" the Chat SDK to a non-existent v7.
+- **Assuming a signature** — event names, `SessionSettings` fields, and action params are FETCHED from docs, never guessed.
+- **1:1 ringing: `CometChat.Call` used only as a TYPE trips `TS6133`** — in strict TS, importing `CometChat` and referencing `CometChat.Call` in type positions only (never as a value) fails with `'CometChat' is declared but its value is never read`. Import the **concrete type** instead: `import { CometChat } from "@cometchat/chat-sdk-javascript"` for the VALUES you call (`initiateCall`/`acceptCall`/`addCallListener`) and `import type { Call } from "@cometchat/chat-sdk-javascript"` for the type. (Same class as the `SessionSettings`/`CometChatCalls` strict-TS trap.)
+- **Strict-TS widening (the doc's bare-object form doesn't compile as-is)** — the doc pages pass `joinSession(token, { sessionType: "VIDEO", layout: "TILE" }, el)` and `init({ appId, region })` as plain JS. In a strict-TS app (the stock Vite `react-ts` template: `strict` + `verbatimModuleSyntax` + `noUnusedLocals`) those literals WIDEN to `string` and fail `tsc` (TS2345 vs `SessionSettings`; TS2322 for `region`). Fix: `import type { SessionSettings }` (it's exported; `SessionType`/`Layout` are NOT) and annotate the settings object — `const s: SessionSettings = {…}` (or `satisfies SessionSettings`) — and narrow `region` to `"us"|"eu"|"in"`.
+
+## Verify it works
+- **Tier-1 catalog:** every `CometChatCalls.*` symbol emitted appears in `web-calls-v5.json` (`node test-suite/scripts/verify-catalog.mjs --family web-calls-v5`).
+- **Tier-2 fences:** the emit type-checks against the installed `@cometchat/calls-sdk-javascript@5` `.d.ts`.
+- **Tier-3b headless smoke:** `node test-suite/scripts/sdk-smoke.mjs --family web-calls-v5 [--live|--dry]` runs init→login→generateToken→(join wiring)→listener-teardown. Media/`joinSession` needs a real WebRTC/DOM context, so the node smoke covers the token+listener round-trip (`--dry` proves wiring without a backend); the actual call render is verified in a browser harness. Flag "dry-mock only, not live-certified" honestly where true.

package/skills/cometchat-js-v5-sdk/references/docs-map.md

@@ -0,0 +1,114 @@
+# docs-map — CometChat Calls SDK v5 (JavaScript, headless): intent → the exact docs page to fetch
+
+## Reaching docs — PREFER the CometChat docs MCP; fetch is the fallback
+The canonical doc channel is the **first-party CometChat docs MCP** — tools `search_cometchat_docs`,
+`fetch_cometchat_doc_page`, and `get_cometchat_implementation_bundle`. **If those tools are connected,
+use them instead of a raw web fetch:**
+- **Find the page** → `search_cometchat_docs(query)` — e.g. `search_cometchat_docs("calls javascript join session")`.
+- **Read the page** → `fetch_cometchat_doc_page(path)` — pass the SAME `<path>` the tables below list; the MCP
+  resolves the `.md` twin and returns raw Markdown. A full `https://…/<path>` URL also works.
+- **A whole feature/recipe** → `get_cometchat_implementation_bundle(...)` is **NON-AUTHORITATIVE** — curated
+  STATIC recipes that can lag the live docs. Treat any bundle as a hint only: RECONCILE it against the
+  `fetch_cometchat_doc_page` result + the catalog; never emit bundle code verbatim.
+
+The MCP reads whatever docs environment it is pointed at (production by default; a preview when repointed),
+so it also carries the environment-swap concern below — no hardcoded host on the skill side.
+
+**If the MCP tools are NOT connected:** add it (`claude mcp add --transport http cometchat-docs https://mcp.cometchat.com/mcp`, or reinstall/enable the plugin) and retry; only if it still will not connect, fall back to a plain fetch via `DOCS_BASE` (defined next).
+Either way the `<path>` catalog in this file is the source of truth for WHICH page — MCP-vs-fetch is only HOW.
+
+## DOCS_BASE — the fetch FALLBACK entry point (⚠️ SWAP HERE to change environments)
+```
+DOCS_BASE = https://www.cometchat.com/docs
+```
+> Production docs (`https://www.cometchat.com/docs`). **Fetch rule:** build a URL as `DOCS_BASE` + the path shown,
+> then append `.md`. Never hardcode a host anywhere else; never read `node_modules`/`.d.ts`.
+
+## The convention — Calls v5 lives at the UNVERSIONED root `/calls/javascript/`
+`DOCS_BASE` + `<path>` + `.md` → raw Markdown (verbatim code + prop/parameter tables).
+```
+Fetch:  {DOCS_BASE}/calls/javascript/overview.md
+```
+> **⚠️ VERSION TRAP.** The **unversioned** `/calls/javascript/**` tree IS **v5** (matches the installed
+> `@cometchat/calls-sdk-javascript@5`). The `/calls/v4/**` tree is the OLD v4 SDK — never fetch it for a v5
+> build. Legacy `/sdk/javascript/<n>.0/calling-*` pages are older still. When in doubt, prefer the page whose
+> body says "Calls SDK v5".
+
+## Scoped index (prefer over the global llms.txt)
+```
+{DOCS_BASE}/llms.txt
+```
+Use it to discover any page not listed below (search for `/calls/javascript/`).
+
+## Path catalog — intent → page (all under `/calls/javascript/`)
+| Intent | Path |
+|---|---|
+| SDK overview · architecture · call-flow | `/calls/javascript/overview` |
+| Install + `init` / `initFromSettings` | `/calls/javascript/setup` |
+| Login / auth-token / user mgmt | `/calls/javascript/authentication` |
+| `generateToken` + `joinSession` (meet-style) | `/calls/javascript/join-session` |
+| **1:1 RINGING** — initiate · incoming-call listener + **incoming/outgoing call-screen UI** · accept/reject/cancel · then `generateToken`/`joinSession` | `/calls/javascript/ringing` |
+| Session settings (the `SessionSettings` object) | `/calls/javascript/session-settings` |
+| Events (`addEventListener` — full event list) | `/calls/javascript/events` |
+| In-call actions (mute/pause/leave/layout/record…) | `/calls/javascript/actions` |
+| **Custom control panel** — replace the built-in controls: hide the whole panel (`hideControlPanel`) OR hide INDIVIDUAL buttons, then drive your own UI off the action methods + keep it in sync via events | `/calls/javascript/custom-control-panel` — the canonical recipe for `SKILL.md` pitfall #1's "user EXPLICITLY wants custom controls" path. Carries the per-button hide flags the session-settings page doesn't foreground: `hideRaiseHandButton` · `hideShareInviteButton` · `hideParticipantListButton` · `hideChatButton` (plus `hideLeaveSessionButton`/`hideToggleAudioButton`/`hideToggleVideoButton`/`hideScreenSharingButton`/`hideRecordingButton`/`hideChangeLayoutButton`/`hideVirtualBackgroundButton`) — all real in the installed `.d.ts`. |
+| Call layouts (TILE / SIDEBAR / SPOTLIGHT) | `/calls/javascript/call-layouts` |
+| Participant management (pin / mute / list) | `/calls/javascript/participant-management` |
+| Recording | `/calls/javascript/recording` |
+| Screen sharing | `/calls/javascript/screen-sharing` |
+| Virtual background | `/calls/javascript/virtual-background` |
+| Raise hand | `/calls/javascript/raise-hand` |
+| Idle timeout | `/calls/javascript/idle-timeout` |
+| Share invite | `/calls/javascript/share-invite` |
+| Call logs (`CallLogRequestBuilder`) | `/calls/javascript/call-logs` — ⚠️ **the live example OMITS the REQUIRED `.setAuthToken(token)` — copying it verbatim BREAKS AT RUNTIME.** The page now DOES document the client-SDK `CallLogRequestBuilder` (added in v5.0.5, in its "Transcripts" section) — but its snippet is `new CometChatCalls.CallLogRequestBuilder().setLimit(30).setHasTranscriptions(true).build()` with **no `setAuthToken`**, and the builder does **NOT** implicitly use the logged-in user's token: `fetchNext()` then throws `{ code: "NOT_ENOUGH_PARAMETERS", message: "`Auth Token` is required to use the fetchNext() method." }` (verified live vs installed `@cometchat/calls-sdk-javascript@5.0.5`, explorer `web-calls-v5`). **EMIT THE BAKED RECIPE, not the doc snippet:** `new CometChatCalls.CallLogRequestBuilder().setLimit(n).setAuthToken(CometChatCalls.getUserAuthToken()).build().fetchNext()` → `Promise<CallLog[]>` (paginated; read `getSessionID`/`getType`/`getStatus`/`getTotalDuration`/`getInitiatedAt`/…). `setAuthToken` is REQUIRED; pass the logged-in user's token from `CometChatCalls.getUserAuthToken()`. Use the SDK builder for an in-app call-log list; don't send the user to the REST API. (Docs bug tracked in `DOCS-BACKLOG.md`; this baked recipe stays authoritative over the doc snippet until it's fixed.) |
+| **React** integration (provider + call screen) | `/calls/javascript/react-integration` |
+| Vue / Angular / Next.js / Ionic integration | `/calls/javascript/{vue,angular,nextjs,ionic}-integration` |
+
+## DOCS-GAP — `initFromSettings` shape is NOT on the live docs (bake it here)
+> **Referenced by `SKILL.md` (Init & login ordering).** The `/calls/javascript/setup` page documents ONLY
+> `init({ appId, region })` — it does **not** document `CometChatCalls.initFromSettings(...)`, even though the
+> method is real and shipped (installed `@cometchat/calls-sdk-javascript@5` `.d.ts`). Until the docs add it,
+> the `initFromSettings` argument shape (the non-exported `CometChatSettings` interface — real in the
+> installed `.d.ts`, so absent from the exports-only catalog) is baked here so the skill is not a dead-end:
+> ```ts
+> await CometChatCalls.initFromSettings({
+>   appId: "APP_ID",
+>   region: "us",                         // 'us' | 'eu' | 'in'
+>   credentials: { authKey: "AUTH_KEY" }, // dev-only auth key
+>   callsSDK: { adminHost: null, clientHost: null, host: null },
+>   chatSDK: {},                          // Record<string, unknown>
+>   uiKit: {},                            // Record<string, unknown>
+> });
+> ```
+> The skills **DEFAULT to `CometChatCalls.initFromSettings(settings)`** — pass the settings object **INLINE**
+> (no physical `cometchat-settings.json` file needed). It is the **ai-agent-only telemetry init**
+> (persists `integrationSource="ai-agent"`), **INTENTIONALLY undocumented** (`@nodoc`, same posture as
+> `CometChatUIKit.initFromSettings` — DOCS-BACKLOG F4), which is WHY the shape is baked here. The
+> publicly-documented **`init({ appId, region })` is the FALLBACK only** (a non-skills / doc-following
+> context). Do NOT tell a user to "fetch the shape from `/calls/javascript/setup`": that page does not carry
+> it. (Explorer `web-calls-v5`, AUDIT-169.)
+
+## 1:1 RINGING (meet-style needs none of this) — the signaling layer is the CHAT SDK
+Meet-style (session-id "join a room") uses ONLY the Calls SDK (`generateToken` → `joinSession`). But
+**one-on-one ringing** (call a specific user, they get an incoming-call prompt, accept/reject) combines the
+**Chat SDK** (`@cometchat/chat-sdk-javascript`) for signaling + the Calls SDK for media.
+
+**The COMPLETE, CURRENT recipe is ONE page — fetch it directly:**
+```
+fetch_cometchat_doc_page("/calls/javascript/ringing")
+```
+That page (v5, JS) carries the WHOLE flow, both sides: `CometChat.initiateCall(call, timeout?)` →
+`CometChat.addCallListener({ onIncomingCallReceived → show an incoming-call screen, onOutgoingCallAccepted, onOutgoingCallRejected, onIncomingCallCancelled })`
+→ `CometChat.acceptCall(sessionId)` / `rejectCall(sessionId, status)` / cancel → `CometChatCalls.generateToken(sessionId)`
+→ `CometChatCalls.joinSession(...)` → `leaveSession()` + `CometChat.endCall(sessionId)`. It even includes an
+**incoming-call UI example** and an **outgoing-call UI example**.
+> **Do NOT reach for `search_cometchat_docs("default calling")`** — search surfaces the STALE
+> `/sdk/javascript/3.0/` chat-SDK pages, which end on the deprecated `startSession()` (not `joinSession`) and
+> show no incoming-call UI. `/calls/javascript/ringing` is the canonical v5 source of truth; reconcile any
+> Chat-SDK symbol against the Chat SDK catalog before emitting.
+
+> **⚠️ Testing 1:1 ringing needs TWO live clients** — different users, in **isolated browser sessions**. CometChat
+> stores the logged-in user in `localStorage`, which is SHARED across tabs of the same browser, so two tabs
+> both become the same user and the callee never rings. Use two different browsers (or one normal + one
+> incognito window), each logged in as a different user with the CallListener active. The caller always shows
+> ringing locally; that proves nothing about the callee. This is a two-client protocol, not a bug.

package/skills/cometchat-onboarding/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: cometchat-onboarding
+description: "The shared FRONT DOOR for adding CometChat to ANY app — a consultative, enterprise-grade DISCOVER → UNDERSTAND → PLAN journey that ALWAYS runs first, before any framework core. Detects the whole repo, runs a features + design-system conversation (core chat/threads/groups/media/calls/search/…; a preset theme, match your design system, or build one), maps each feature to its UI Kit component (or the SDK method where the UI Kit has none — UI-Kit-first, SDK-fallback), shares a full integration PLAN, then hands a scoped build directive to the framework core on approval — final output is production-ready. Triggers: 'add cometchat', 'add chat', 'add chat to my app', 'add calling', 'integrate cometchat', 'build a chat feature'."
+license: "MIT"
+compatibility: "Framework-agnostic (React/Next/Angular/Vue/RN/Flutter/Android/iOS/… — degrades gracefully when a signal is absent). Emits NO CometChat components — output is a plan artifact + a scoped directive to a framework core skill."
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat onboarding journey discover understand plan front-door router-gate agnostic intent"
+---
+
+> **Ground truth:** this skill runs FIRST for every "add CometChat" request and produces NO integration code — its only outputs are (1) the shared **plan artifact** and (2) a **scoped build directive** to the framework core. Repo facts come from `npx @cometchat/skills detect --json` (the authority) + **READING THE REPO** for the rest — NEVER memory, never the dashboard CLI (AUDIT-059). The archetype→capability map and plan template are in `references/` (loaded on demand). Credentials + implementation belong to the framework core (`cometchat-<family>-core`, family resolved from `peers.yaml`). Draw the boundary at PLAN.
+
+<!-- onboarding is a platform-NEUTRAL journey skill (like the cross-family a11y/i18n): no per-platform Companion block. Its "companion" is whatever framework core the plan names on hand-off. -->
+
+## Use this skill when
+Any first-contact "add CometChat" intent, on ANY stack: "add chat", "add cometchat", "add chat to my app", "add voice/video calling", "integrate cometchat". The router (`cometchat`) ALWAYS routes here FIRST — a mandatory gate. It runs before ANY framework core so the developer gets discover → understand → plan before a line is written. (An *upgrade* request — "upgrade my v6 UI Kit to v7" — is reconciliation, not onboarding; the router sends that straight to migration. And a re-entry on an already-integrated repo short-circuits: see §Re-entry.)
+
+## What this skill does — and only this (the four beats)
+Run the four beats in order, as a CONSULTATIVE conversation (senior-engineer tone: recommend with a reason, surface trade-offs, never a blank form). Nothing is written to the user's code in ANY beat — the first write happens only AFTER beat 4's approval, inside the framework core. The final output is PRODUCTION-READY (the core's contract guarantees it).
+
+> **The build model — UI Kit first, SDK per-feature fallback (NO "which approach?" question).** A renderable app on a platform with a shipped UI Kit ALWAYS gets the **UI Kit** as its UI layer (fastest path to a production-ready surface). There is NO "UI Kit vs SDK" architecture choice to make. Instead, PER FEATURE: if the UI Kit has a component/prop for it → **use the component**; if it does NOT → call the platform's **Chat SDK** method directly (already installed under the UI Kit — init/login use it). The SDK is the FALLBACK for what the UI Kit doesn't expose (AI agents, campaigns, advanced/AI moderation, transient messages, bots, webhooks, …), looked up in the detected family's core `references/docs-map.md` → SDK docs (`references/platforms.md`). The ONLY exception: a backend/no-DOM/non-renderable context has no UI layer — there the SDK is the whole build; say so honestly.
+
+### 1. DETECT everything (environment + the WHOLE current repo)
+Run the detect probe (above), then **READ THE REPO** for the rest (on web: `package.json` deps/scripts, the lockfile, framework config files and source; on iOS: `*.xcodeproj`/`*.xcworkspace`, `Package.swift`, a `Podfile` as a signal only — `references/platforms.md`). Capture, framework-agnostically, degrading gracefully when a signal is absent (record it `null`, never guess):
+- **Framework & build:** `framework` · `framework_version` · `bundler` · `router` · `ssr_strategy` (ssr/csr/islands) · `env_prefix` (VITE_/NEXT_PUBLIC_/…) · `package_manager` (from the lockfile) · `language` (TS/JS) · `project_name` (plus mobile version fields for expo/RN/android/flutter). **Non-web platforms have different fields** — iOS, Android, React Native and Flutter each have a column in `references/platforms.md`.
+- **App integration state:** **installed UI Kit + `version_conflict`** (a major other than the family's target — React v7, Angular v5, RN v5, iOS v5, Android v6, Flutter v6; `peers.yaml`) · **existing CometChat integration** · **credential presence** (an existing `.cometchat/config.json` or `*_COMETCHAT_APP_ID` env).
+- **App architecture (infer from source, `null` when absent):** **auth system** (nextauth / clerk / firebase / auth0 / supabase / custom) · **styling / design system** (tailwind / css-modules / mui / styled-components / chakra) · **state management** (redux / zustand / mobx / recoil / context).
+> **`version_conflict` STOP still applies HERE.** If detection shows a UI Kit major other than the family's target for an *add* request, STOP and surface it in the plan (reconcile first — `RULES.md`); do not hand off a build over a mixed-major repo. If CometChat is already wired for THIS major → **Re-entry** (below).
+> **A signal being absent is DATA, not a blocker.** Missing auth ⇒ recommend the dev Auth-Key path + a note to add prod auth later; missing framework ⇒ record it and (per §Non-React) state the platform's core isn't built yet. Never fabricate a signal, never stall on one.
+
+### 2. UNDERSTAND — the features + design conversation (each question WITH a recommended default from the repo)
+A SHORT, consultative Q&A (clarification contract: ask **and wait**); every question carries a repo-inferred recommendation so the developer confirms rather than composes:
+1. **Archetype / shape** — `1:1`/marketplace · `support` · `community`/groups · `full-messenger` · `embedded`. Infer from routes (seller/product → `1:1`; `/support` → `support`; `/community`/`/groups` → `community`). "Detected `<signal>` → recommend `<archetype>` — keep or change?"
+2. **Features** — WHICH capabilities (from the detected platform's manifest — `features.json` react-v7 / `features.angular-v5.json` angular-v5 / `features.ios-v5.json` iOS / … — grouped; naming only one hands the wrong menu to every other family): **Core chat** (1:1 + groups, messages, **threads**, media/attachments, typing, receipts, **reactions, mentions** — the last two are ON BY DEFAULT in v7 core, NOT extensions to enable — AUDIT-077) is the recommended default and always included; then offer the add-ons — **voice/video calls · search · polls/stickers · translation · push notifications · AI/smart-replies · moderation · AI agents**. Do NOT list `reactions`/`mentions` as add-ons (they're core), and never offer a `deprecated:true` feature (email-replies · e2e-encryption · live-streaming). **First SUBTRACT what's already present (AUDIT-043)** — `detect`/existing-integration for wired features, and ASK which dashboard-gated extensions are already enabled (the CLI can't read per-app enabled-state); don't re-offer an already-on feature like translation. Ask "core chat + which of these?" Don't ask about individual components/props (the core decides those). **Each chosen feature maps to a UI Kit component where one exists, or an SDK method where it doesn't** (AI agents · campaigns · advanced/AI moderation · bots · webhooks · transient messages → SDK) — the plan's **Feature coverage** section records which, so nothing is silently dropped or hand-rolled.
+3. **Design / theming** — HOW it should look. Present the light/dark MODE and the palette, and **ALWAYS include the AUTO option**: **(a)** **Auto — follow the device's light/dark (OS) setting** — the RECOMMENDED default for a fresh app (whether the kit follows the OS BY ITSELF differs per platform — **iOS does, with no host code, so do not offer to wire it there; web does not** — `references/platforms.md`, AUDIT-004), **(b)** a fixed **light** preset, **(c)** a fixed **dark** preset, **(d)** **match your existing design system** (recommended when discovery detected Tailwind/MUI/Chakra/a token theme — reuse it), **(e)** a **brand palette** (your colors as the platform's theme tokens — CSS custom properties on web, `UIColor`/`dynamicColor` on iOS), or **(f)** a **custom design system**. All map to the UI Kit's theme tokens / `customization`. Recommend from the detected `styling` signal: none → **auto + default tokens**; a design system detected → **auto + match**. **Omitting the auto / follow-system option is a defect (AUDIT-042) — the kit supports it and it's the pack's fresh-app default; never present a light-only menu.**
+4. **Scope / placement** — smallest surface that satisfies the archetype (default) vs. the full combined app; full-page · embedded · sidebar · popup. Default to the SMALLEST reasonable production-ready surface, never the kitchen sink.
+The archetype → capability translation is in `references/archetypes.md`; the feature menu is the DETECTED platform's manifest (`references/platforms.md`) — never offer a feature that platform does not ship. Recommend, don't interrogate.
+
+### 3. PLAN — share the FULL plan artifact BEFORE anything is written
+Assemble and present the **plan artifact** — the concrete deliverable of this skill. It MUST contain every section of the plan-completeness contract (template + contract in `references/plan-artifact.md`):
+1. **What I found** — the beat-1 discovery summary — the fields that APPLY to the detected platform (web: framework/bundler/router/SSR/pkg-mgr/env-prefix; iOS: deployment target/dependency manager/UI framework/Xcode project), plus language, auth, styling, existing-CometChat — each value or `null`. Do not report a field the platform does not have.
+2. **What you want (feature coverage)** — the confirmed intent (archetype · **features** · **design/theming** · scope) translated to **CometChat capabilities** (intent→capability map from `references/archetypes.md`; features from `features.json`), **each tagged UI Kit component or SDK method** — the UI-Kit-first / SDK-fallback split. Flag the SDK-backed ones (AI agents · campaigns · advanced moderation · bots · …) so the core wires them from the SDK docs; nothing is silently dropped or hand-rolled.
+3. **What I'll do** — a NUMBERED action list (the scoped build steps, in order).
+4. **Files that will change** — the concrete paths/areas the build will touch (additive — APPEND, never replace).
+5. **Packages** — the exact package(s) the plan installs (named, with major pins; the core owns the exact coordinates).
+6. **Credential + auth strategy** — dev **Auth Key** vs prod **server-minted auth token**, CHOSEN from discovery (a real auth system detected ⇒ recommend the prod token path wired to it; none ⇒ dev Auth-Key path + a note to harden for prod). State it; do NOT fetch credentials here. **Say in the plan that the core will OFFER to fetch App ID/Region/Auth Key from the dashboard (loading the CometChat CLI on demand → `provision`) or let the user paste them — so the fetch step isn't dropped on hand-off and never degrades into a "paste them yourself" TODO (AUDIT-039).**
+7. **The modify-or-approve gate** — explicitly invite the user to EDIT the plan or approve it. Nothing is written before approval.
+
+### 4. MODIFY or START — edit the plan, else hand a SCOPED directive to the core
+- The user may **edit** any part of the plan (change the archetype, add/drop a feature, narrow scope, switch the credential strategy) → re-render the plan and re-present the gate. Loop until they approve.
+- On **approval**, emit a **scoped build directive** and hand off:
+  - **Framework detected** → resolve `<family>` from `peers.yaml` (React web → `react-v7`; Angular → `angular-v5`; iOS → `ios`; React Native/Expo → `react-native`; Android → `android-v6`, reading `android_variant` from gradle files for cohort; Flutter → `flutter-v6`) and hand off to `cometchat-<family>-core` with the scoped surface (archetype + features + theming + scope + credential strategy + affected files), pulling in ONLY the additional SHIPPED skills the plan names (theming → `customization`, framework glue → `patterns`, features → `features`, voice/video → `calls`, **push → `cometchat-<family>-push`** (thin, docs-first), v6→v7 upgrade → `migration`). The core builds **UI Kit first** and, for any **SDK-backed feature** the plan flagged (AI agents · campaigns · advanced moderation · …), wires the **SDK method** looked up in `cometchat-<family>-core/references/docs-map.md` → SDK docs. The core owns detect-reuse, credentials, and the production-ready build. **Android extra:** cohort-split skills (`android_variant`: `views` → `kotlin-*`, `compose` → `compose-*`) pick `{kotlin,compose}-{components,placement,customization}`; cohort-neutral skills (`features`, `calls`, `push`, `production`, `testing`, `troubleshooting`, `builder-settings`, `events`, `extensions`, `migration`). Credentials → `app/src/main/assets/cometchat-settings.json` (gitignored), not `.env`.
+  - **A framework with no shipped core detected** → still deliver the full discover→understand→plan, then state clearly that **that platform's implementation core isn't built yet** (framework-ready posture; see §Not in this pack). Do not fake an implementation.
+> **Scoped, not the kitchen sink.** The directive names the SMALLEST surface the approved plan calls for (e.g. "1:1 chat surface for the marketplace, dev Auth-Key, touch `src/features/chat/*`"), so the core builds that — not every component.
+
+## Calling-FIRST intent — the "add calling" decision tree
+When the PRIMARY first-contact intent is **calling** ("add calling / voice-video / a video call" as the GOAL, not "add chat" that includes calls), run the **`references/calling-first.md`** decision tree instead of defaulting to the UI-Kit path — calling is the ONE intent where an approach choice is legitimate (standalone build-your-own-UI calling is a real product; a CHAT build still gets NO approach question). In brief: detect the UI Kit → offer **prebuilt** (`cometchat-<family>-calls`) vs **standalone from scratch**; if no UI Kit, ask *"chat too, or calling only?"*; for from-scratch, ask **one-on-one (ringing) vs meet-style**, then hand off to the platform's headless Calls SDK v5 skill (**`cometchat-js-v5-sdk`** web, **`cometchat-ios-v5-sdk`** iOS, **`cometchat-android-v5-calls-sdk`** Android, **`cometchat-react-native-v5-sdk`** React Native, **`cometchat-flutter-v5-sdk`** Flutter — resolved from `peers.yaml`, not a literal; not installed? `npx @cometchat/skills add --family <platform>-calls` adds it alongside) with the mode. Still run beats 1–3 + a short plan before hand-off.
+
+## The hand-off boundary (REUSE the core; do NOT fork it)
+This skill does **discover + understand + plan**. The framework core does **credentials + implement + verify**. The line is BEAT 4's approval:
+- Onboarding OWNS: whole-repo discovery, intent elicitation with recommendations, the plan artifact, the modify/approve gate, the scoped directive.
+- The core OWNS (do NOT restate or fork here): credential fetch/provision + env write (`references/setup-credentials.md`), init→login→render, component/prop selection, the production-ready build. It REUSES this discovery (re-reads the same signals + any `.cometchat` config, skips re-setup) — one detection approach, two consumers.
+
+## Re-entry (already-integrated repo)
+If beat-1 discovery shows CometChat already wired for the current major (`existing_cometchat: true`, no `version_conflict`), do NOT re-run the full journey. Summarize what's already integrated, ask what the user wants to ADD or CHANGE, and route that incremental ask straight to the framework core (or the calls/features/customization skill it names) — onboarding is the FIRST-contact front door, not a gate on every subsequent change.
+
+## Not in this pack — missing skills & not-yet-built cores (graceful-degrade posture)
+**The rule: only hand off to a core/skill that SHIPS in this pack** — present under `skills/` and declared in `peers.yaml`. Never route to an uninstalled skill and never pretend it's there; run beats 1–3 in full, produce the plan artifact, and in beat 4 be honest and offer the nearest shipped alternative. **React, Angular, iOS, React Native, Android and Flutter all ship FULL sets** (`cometchat-<family>-core` + `-calls` · `-push` · `-migration` · …), plus the headless `cometchat-android-v5-sdk` (Android Chat SDK) and the from-scratch calling skills `cometchat-js-v5-sdk` (web) / `cometchat-ios-v5-sdk` (iOS) / `cometchat-android-v5-calls-sdk` (Android). Only apply this posture where a capability has genuinely NO shipped skill, or the platform has no `peers.yaml` peer (Vue today) — then deliver the plan as the hand-off spec and say the implementation skill isn't built yet. Never silently pretend React, and never decline a family that ships. **Per-platform routing table + how to word an honest decline: `references/not-in-this-pack.md`.**
+
+## Common pitfalls
+- **Writing code in beats 1–3.** The first write is post-approval, in the core. Onboarding that scaffolds before the plan is approved has skipped its own gate.
+- **Asking "UI Kit or SDK?"** There is NO approach choice (calling-first excepted) — the UI Kit is always the UI layer, the SDK the per-feature FALLBACK inside the same build. Don't ask; map each feature to its component, or its SDK method where none exists.
+- **Hand-rolling a feature that already exists.** Never build custom UI/logic for something the UI Kit has a component for, OR the SDK has a method for. Check the UI Kit first (`component-props.md` / catalog), then the SDK docs (`docs-map.md`). Hand-roll ONLY when neither has it.
+- **Declining a family that ships.** calls + **push** + migration ARE installed on every family — route to them normally (`cometchat-<family>-calls` / `-push` / `-migration`). Apply the **§Not in this pack** posture ONLY where no skill ships, and never route an unknown platform to React by default.
+- **Asking blank questions, or skipping features/design.** Beat 2 must cover archetype · WHICH features · HOW it looks (**auto/follow-OS [default]** · fixed light/dark · match design system · brand · custom) · scope, each WITH a repo-inferred recommendation. A bare "which archetype?" is under-delivery; omitting **auto/follow-OS** is a defect (AUDIT-042).
+- **Forking the credential/detect flow.** Do NOT re-implement credentials or detection here — plan them, then let the core execute (the hand-off boundary above).
+- **Over-scoping the directive.** Hand off the smallest surface the plan names, not the whole combined app (that's a later grow-on-request in the core).
+- **Stalling on a missing signal.** Absent auth/framework/styling is recorded `null` and flows into a recommendation — never a blocker. (`version_conflict` on an *add* IS a STOP; a missing signal is not.)
+
+## Verify before done (this skill's "done" = a good plan + a clean hand-off, NOT a running app)
+Onboarding is complete when: (1) beat-1 discovery ran and every signal is captured or explicitly `null`; (2) every intent question (archetype · **features** · **design/theming** · scope) was asked WITH a repo-inferred recommendation and answered; (3) the plan artifact was presented containing ALL plan-completeness sections incl. **Feature coverage** (UI Kit component vs SDK method per feature) (`references/plan-artifact.md`); (4) the user approved (or edited → re-approved); (5) EITHER a scoped directive was handed to a SHIPPED core (`cometchat-<family>-core`), OR — where no skill ships for the platform/capability — the **§Not in this pack** posture was stated (honest + plan-as-spec + shipped alternative), never a hand-off to an uninstalled skill. This skill does NOT build, test, or run the app — the chosen core does the build (production-ready per its contract); testing is advisory/human unless the user asks (`RULES.md`).
+
+## Deep references (load ONLY when the beat needs them — keeps this file thin)
+- `references/archetypes.md` — the archetype → CometChat-capability map (1:1/marketplace · support · community · full-messenger · embedded) + the repo-signal → recommended-default heuristics for beat 2, and the intent→capability translation for the plan's "what you want".
+- `references/plan-artifact.md` — the plan-artifact TEMPLATE (fill-in) + the **plan-completeness contract** (the seven sections the plan MUST contain) + a worked example.
+- `references/calling-first.md` — the "add calling" decision tree (UI-Kit-present → prebuilt vs scratch; no-UI-Kit → chat-too? ; scratch → one-on-one vs meet → hand off per platform: web `cometchat-js-v5-sdk`, iOS `cometchat-ios-v5-sdk`, Android `cometchat-android-v5-calls-sdk`, React Native `cometchat-react-native-v5-sdk`). Load when the primary intent is calling.
+- `references/not-in-this-pack.md` — the graceful-degrade posture in full: the per-platform table of which skills SHIP (so a shipped family is never declined) + how to word an honest decline. Load in beat 4 when a needed skill may not exist.
+- `references/platforms.md` — the per-platform beat-1 signal columns (web · iOS · Android · React Native · Flutter) + the platform feature manifests.

package/skills/cometchat-onboarding/references/archetypes.md

@@ -0,0 +1,51 @@
+# archetypes — intent → CometChat capability map + repo-signal → recommended default
+
+This is the translation layer for beats 2 and 3: it turns a **product archetype** into **CometChat capabilities** (the plan's "what you want"), and it turns **beat-1 repo signals** into the **recommended default** each intent question carries (the "make it easy + recommend" requirement). Capabilities named here are conceptual (chat surface / 1:1 / groups / calls / search / threads) — the framework core maps each to its own components on hand-off; onboarding does not name UI-Kit symbols.
+
+## The five archetypes → capabilities
+
+| Archetype | Product shape | CometChat capabilities (the plan's intent→capability) | Default modality | Default scope |
+|---|---|---|---|---|
+| **1:1 / marketplace** | Buyers ↔ sellers, requester ↔ provider — a "message this person" entry point off a profile/listing | 1:1 conversations · a conversation list · a message pane (send/receive, attachments) · unread + presence · a "Message <X>" entry button wired to open the conversation | chat | smallest 1:1 surface (a message button → a conversation ↔ message pane), NOT the full app |
+| **support** | Customers ↔ support agents; often a launcher/widget in a corner, sometimes ticket-scoped | 1:1 (customer↔agent) conversations · a message pane · often **embedded** placement (a launcher/popup, not a full page) · optionally calls for escalation · agent-side may want a conversation list | chat | an embedded/widget support surface |
+| **community / groups** | Members talk inside communities, channels, or rooms | **groups** · group conversations · group members + management/moderation · a message pane · often a groups/channels list · optionally group calls | chat | a groups + group-message surface |
+| **full messenger** | A complete standalone chat app (the "everything" experience) | the whole combined experience: conversations + users/groups tabs · message pane · threads · search · calls · the full grow-target | both | the full combined app (the core's grow target) |
+| **embedded** | Chat lives INSIDE an existing screen/flow, not as its own page (a side panel, drawer, or inline widget) | a scoped chat surface constrained to a container (a fixed-size panel/drawer), 1:1 or group as the host flow needs; minimal chrome | chat | a placement-constrained embedded surface |
+
+> **Modality overlay.** Any archetype can be `chat` / `calls` / `both`. "Add calling" or a repo already using CometChat chat → recommend `calls`/`both`. Calls layer: 1:1 voice/video and/or group calls, incoming-call handling, and (on native) the platform permission config — the framework core + its calls skill own the details.
+
+## Repo-signal → recommended default (beat 2 — infer, then let the user confirm)
+
+Each question's recommendation comes from what beat-1 detected. Phrase every one as **"detected <signal> → recommend <default> — keep or change?"** — never a blank ask.
+
+**Archetype (from routing/domain signals):**
+- Marketplace/e-commerce signals — routes or dirs like `/products`, `/listings`, `/sellers`, `/checkout`; a product/seller/vendor model → **1:1 / marketplace**.
+- Support/helpdesk signals — `/support`, `/help`, `/contact`, `/agent`, a tickets model, a widget/launcher pattern → **support** (embedded placement).
+- Community/social signals — `/community`, `/groups`, `/channels`, `/rooms`, `/feed`, a groups/members model → **community / groups**.
+- A greenfield/standalone app, or an explicit "build a chat app" → **full messenger**.
+- Chat is clearly a secondary feature bolted onto an existing screen (dashboard/app shell with no obvious chat page) → **embedded**.
+- No decisive signal → recommend the SMALLEST reasonable default (**1:1**) and say so; the user confirms or changes. (Do not stall — smallest-reasonable-default + flag, per `RULES.md` clarification only where genuinely blocking.)
+
+**Modality:**
+- Trigger was "add calling"/"add voice/video" → **calls** (or **both** if chat isn't present yet).
+- Repo already has CometChat chat wired → **calls** (adding to existing).
+- Otherwise → **chat**.
+
+**Scope:**
+- Default to the **smallest surface** that satisfies the archetype (the core's production-ready core surface for 1:1/support/community; a placement-constrained surface for embedded).
+- Recommend the **full combined app** ONLY for **full messenger** or an explicit "the whole chat app" ask.
+
+**Credential + auth strategy (feeds plan section 6):**
+- A real auth system detected (`auth` ∈ nextauth/clerk/firebase/auth0/supabase/custom) → recommend the **prod server-minted auth-token** path, wired to that system (map the app's user id → the CometChat UID); note the dev Auth-Key is fine to start but must not ship.
+- No auth detected (`auth: null`) → recommend the **dev Auth-Key** path to get moving, with an explicit note to add prod token auth before production.
+- The framework core executes whichever is chosen (its `references/setup-credentials.md`); onboarding only decides + states it.
+
+**Placement / SSR hints (feeds plan sections 3–4):**
+- `styling` (tailwind/mui/…) → note "match the existing design system" as a plan step (hand to customization on build).
+- **Theme MODE default = AUTO (follow the OS light/dark setting).** For a fresh app (no `styling` detected), recommend **auto** — the core syncs `theme` ↔ `prefers-color-scheme` (the kit ships light+dark but does NOT auto-follow the OS on its own; pack default per AUDIT-004). ALWAYS offer the auto/follow-system option in the design question — never a light-only or fixed-preset-only menu (AUDIT-042). Mode (auto/light/dark) and palette (default tokens / match design system / brand / custom) are independent — auto can pair with any palette.
+- `ssr: ssr`/`islands` (Next App Router, Astro) → flag the client-boundary work in the plan (the chat surface is client-side; the core's patterns skill owns the directive).
+- `state` (redux/zustand/context) → note where the "current conversation / logged-in CometChat user" state should live so it fits the app's existing store, not a new one.
+
+## Notes
+- These are **recommendations**, not decisions — the user confirms or overrides every one at the beat-4 gate.
+- Onboarding names capabilities and archetypes; the **framework core** names components. Keep that split so this file stays platform-neutral and doesn't rot with UI-Kit changes.

package/skills/cometchat-onboarding/references/calling-first.md

@@ -0,0 +1,77 @@
+# calling-first.md — the "add calling" decision tree
+
+Load this when the PRIMARY, explicit first-contact intent is **calling** — the user opens with "add calling / add voice-video / add a video call to my app" as the GOAL, not "add chat" that merely includes calls. Standalone, build-your-own-UI calling (a video-only app, a meeting room, an embedded call widget with no chat surface) is a legitimate product, so **calling is the one intent where onboarding offers an approach choice**. (A CHAT build still gets NO approach question — the "Asking 'UI Kit or SDK?'" pitfall stands for chat.)
+
+Run it as a consultative Q&A (clarification contract: ask **and wait** at each branch). Still run beats 1–3 (whole-repo discovery + a short plan naming the mode + packages + credential strategy) BEFORE the hand-off — this tree replaces the archetype/approach question for calling-first intent; it does not skip the plan.
+
+## Step 1 — detect the UI Kit (beat 1)
+Is a CometChat UI Kit installed? Web/RN: `@cometchat/chat-uikit-*` in `package.json`. **iOS: the `ios` row's `kit_package` (`peers.yaml`) in `Package.swift`/`Podfile`, or an `*.xcodeproj`/`*.xcworkspace` that resolves it.** Android: `com.cometchat:chatuikit-*` in the gradle files. Flutter: `cometchat_chat_uikit` in `pubspec.yaml`.
+
+## Step 2 — branch on that
+- **UI Kit IS installed** → ask:
+  > *"Your UI Kit already ships a prebuilt calling UI (incoming-call surface, call buttons, ongoing-call). Use that, or build a standalone calling feature from scratch with no prebuilt UI?"*
+  - **prebuilt** → hand off to `cometchat-<family>-calls` (e.g. `cometchat-react-v7-calls`, **`cometchat-ios-calls`** on iOS). It rides the SAME init/login — enable calling on the existing UIKit settings (`uiKit.callsSDK`). Done.
+  - **from scratch** → Step 3.
+- **UI Kit is NOT installed** → ask:
+  > *"We also ship UI Kits with a prebuilt calling UI. Do you need CHAT as well, or only calling? If you'll want chat too, the UI Kit gives you both with a prebuilt call UI; if it's calling-only, we can build it from scratch."*
+  - **chat too / wants prebuilt** → the normal UI-Kit journey (`cometchat-<family>-core` + `calls`).
+  - **calling only / from scratch** → Step 3.
+
+## Step 3 — from-scratch / standalone calling → ask the call SHAPE
+> *"One-on-one (ringing — call a specific user, they get an incoming prompt to accept/reject) or meet-style (a session room anyone joins by id)?"*
+
+### Step 3b — ringing on MOBILE ⇒ ask DELIVERY too (ask **and wait**; never assume)
+Answered **one-on-one ringing** on a mobile platform (Android/iOS/Flutter/React-Native)? Ask this BEFORE
+the plan — it is an architecture fork, not a later add-on:
+> *"Do calls need to ring when the app is in the background or closed — the way WhatsApp does? Or is
+> in-app ringing enough (both people have the app open)?"*
+
+- **In-app / foreground only** → the ringing recipe (`initiateCall` / `CallListener` / `acceptCall`).
+  **Say the limit out loud in the plan:** in auto socket mode the Chat SDK drops its WebSocket the moment
+  the app is backgrounded, so a backgrounded callee never rings and the caller just times out (~45 s) —
+  verified live on two devices. It is NOT replayed when they return.
+- **Background / killed-app ringing** → that is **VoIP push**, a separate build, and a **real device**
+  either way (neither emulators nor the iOS Simulator can prove it).
+  *Android:* an FCM project + `FirebaseMessagingService`, `PhoneAccount` registration, a
+  `ConnectionService` — `/calls/android/voip-calling`, docs-first, paired with the platform's `push` skill.
+  *iOS:* the separate `CometChatPushNotifications` package (an APNs **VoIP** provider in the dashboard,
+  Background Modes → Voice over IP, and a device — APNs never delivers a VoIP push to the Simulator). The
+  SDK owns `PKPushRegistryDelegate` and `CXProviderDelegate`; writing either yourself fights it for the
+  same callbacks. Certified on device via `cometchat-ios-v5-sdk`.
+  Name it as its own plan item with its own prerequisites — do not fold it into the ringing recipe and do
+  not promise it from that recipe.
+
+**Why this is asked, not assumed.** "One-on-one ringing" reads as *WhatsApp* to most people, and the
+foreground-only build passes every casual test (both apps open during development) before failing in the
+user's real world. A user who wanted VoIP and got the ringing recipe does not find out until their
+callee's phone stays silent. Web/JS has no VoIP-push equivalent — skip 3b there.
+
+## Step 4 — resolve the headless skill FROM THE DETECTED PLATFORM
+The headless calls skill is **per-platform** — resolve it from `peers.yaml` (the peer whose `consumption: sdk` and whose `kit_package` is a `calls-sdk-*`), never from a literal. Today's live headless-calls peers:
+
+| Detected platform | Peer | Skill | Calls package | Ringing also needs |
+|---|---|---|---|---|
+| web / JS | `js-calls` | `cometchat-js-v5-sdk` | `@cometchat/calls-sdk-javascript@5` | `@cometchat/chat-sdk-javascript@4` |
+| React Native | `react-native-calls` | `cometchat-react-native-v5-sdk` | `@cometchat/calls-sdk-react-native@5` | `@cometchat/chat-sdk-react-native@4` |
+| iOS | `ios-calls` | `cometchat-ios-v5-sdk` | `CometChatCallsSDK` | the Chat SDK for signaling |
+| Android | `android-calls` | `cometchat-android-v5-calls-sdk` | `com.cometchat:calls-sdk-android` | the Chat SDK for signaling |
+| Flutter | `flutter-calls` | `cometchat-flutter-v5-sdk` | `cometchat_calls_sdk: ^5.0.7` | `cometchat_sdk` v5 |
+
+**Is that skill installed?** `add` installs ONE family per run — a UI-Kit install carries only that family's skills, so the headless calls skill may not be in the project's skills folder yet. If it isn't, install it before the hand-off — it is added ALONGSIDE the existing UI Kit skills (nothing is removed):
+`npx @cometchat/skills add --family <js-calls|react-native-calls|ios-calls|android-calls|flutter-calls>` (same `--ide` you installed with). Never hand off to a skill that is not present.
+
+> ⚠️ **The JOIN STEP IS NOT PORTABLE — do not copy it across platforms.** Web joins with `joinSession(token, sessionSettings, containerEl)` into a sized **DOM element**. React Native has **no `joinSession` at all**: you join by RENDERING `<CometChatCalls.Component callToken sessionSettings />` inside a flex-sized `View`. Flutter is a third shape again — `joinSession` RETURNS a `Widget?` and mounts nothing, so the app must place it in the widget tree; an agent that ports another platform's snippet produces a call that joins successfully and renders a blank screen. Name the mode and let the platform's own skill own the recipe.
+
+Then hand off to the resolved skill with the chosen mode named in the directive:
+- **meet-style** → Calls SDK only (`generateToken` → the platform's join step). No Chat SDK.
+- **one-on-one ringing** → Calls SDK media + **Chat SDK signaling** (`initiateCall` / `CallListener` / `acceptCall`) — note the platform's extra chat-SDK dependency from the table in the plan, and carry the Step-3b delivery answer through.
+
+## Hand-off directive shape
+`"standalone <meet-style|one-on-one ringing> calling via cometchat-js-v5-sdk, <session-room|ring-a-user> surface, dev Auth-Key, package(s): @cometchat/calls-sdk-javascript@5[ + @cometchat/chat-sdk-javascript@4 for ringing], touch <paths>"`. Android: `"standalone <meet-style|one-on-one ringing> calling via cometchat-android-v5-calls-sdk, <session-room|ring-a-user> surface, <in-app ringing (foreground-only)|+ VoIP push for background/killed>, dev Auth-Key in assets/cometchat-settings.json, package(s): com.cometchat:calls-sdk-android:5.0.+[ + com.cometchat:chat-sdk-android:5.0.+ for ringing], touch <paths>"`. The headless skill owns install, init→login→generateToken→joinSession, listeners, and teardown. **A ringing directive on mobile MUST carry the Step 3b delivery answer** — without it the recipe silently defaults to foreground-only and the user learns the limit after the build.
+
+**iOS:** `"standalone <meet-style|one-on-one ringing> calling via cometchat-ios-v5-sdk, <session-room|ring-a-user> surface, <in-app ringing (foreground-only)|+ VoIP push for background/killed>, dev Auth-Key, package(s): CometChatCallsSDK@5 via SPM (github.com/cometchat/calls-sdk-ios)[ + CometChatSDK@4 for ringing][ + CometChatPushNotifications@1 for VoIP], Info.plist camera+mic usage strings, touch <paths>"`. The headless iOS skill owns install, init->login->join, listeners and teardown.
+
+**Flutter:** `"standalone <meet-style|one-on-one ringing> calling via cometchat-flutter-v5-sdk, <session-room|ring-a-user> surface, <in-app ringing (foreground-only)|+ push for background/killed>, dev Auth-Key in cometchat-settings.json (a registered Flutter ASSET — commit a placeholder with no real key so a fresh clone builds; real keys supplied locally / generated in CI, per `cometchat-flutter-v6-core`), package(s): cometchat_calls_sdk: ^5.0.7[ + cometchat_sdk v5 for ringing], minSdk 26 / iOS 15.1, touch <paths>"`. Three Flutter-specific things the directive must not lose:
+- the token API is **`generateCallToken`**, not `generateToken` — the latter is deprecated and the live docs still show it.
+- ⚠️ **do not carry another platform's calling snippet across.** Flutter's `joinSession` returns a `Widget?` and mounts nothing; the app places it in the widget tree. An agent that pattern-matches the container-based platforms produces a call that joins and renders a blank screen.
+- for Step 3b, Flutter has **no first-party CometChat push package** — background ringing is FCM on Android and APNs/CallKit on iOS, wired by the app. Say so rather than promising a package that does not exist.

package/skills/cometchat-onboarding/references/not-in-this-pack.md

@@ -0,0 +1,8 @@
+# Not in this pack — missing skills & not-yet-built cores
+
+The graceful-degrade posture, in full. The entry keeps the one-line rule; this is the detail,
+including exactly which skills ship per platform and how to word an honest decline.
+
+**The rule: only hand off to a core/skill that SHIPS in this pack** — present under `skills/` and declared in `peers.yaml`. When a needed skill is NOT installed, never route to it and never pretend it's there; run beats 1–3 in full, produce the plan artifact, and in beat 4 be honest and offer the nearest shipped alternative. Two cases:
+- **Shipped skills to route to (by platform — NEVER decline what IS shipped; `peers.yaml` is the authority):** **React** (`react-v7`): calling → `cometchat-react-v7-calls`; push → `cometchat-react-v7-push` (docs-first — honestly note live delivery needs a device check); migration → `cometchat-react-v7-migration`. **Angular** (`angular-v5`): the full set incl. `-calls`, `-push`, `-migration`. **iOS** (`ios`): `cometchat-ios-core` + `-calls`/`-push`/`-migration`. **React Native** (`react-native`): calling → `cometchat-react-native-calls`; push → `cometchat-react-native-push`; migration → `cometchat-react-native-migration`. **Android** (`android-v6`): `cometchat-android-v6-core` + the cohort-split `{kotlin,compose}-*` skills, `-calls` (prebuilt call UI), `-push` (FCM), `-migration`; **headless Chat SDK** → `cometchat-android-v5-sdk`; **headless calling from scratch (meet-style or 1:1 ringing, no UI Kit)** → `cometchat-android-v5-calls-sdk` (via `calling-first.md`). **Flutter** (`flutter-v6`): `cometchat-flutter-v6-core` + `-calls`/`-push`/`-migration`. Web headless calling from scratch → `cometchat-js-v5-sdk`. The headless **JS Chat SDK** is not a separate skill, but its methods ARE the per-feature fallback used INSIDE the UI-Kit build (`docs-map.md` → SDK docs). Only apply the "not in this pack" posture for a capability with genuinely NO shipped skill (see §Not in this pack) — push is now shipped on every family, so route to it.
+- **Not-yet-built core (no matching `peers.yaml` peer — Vue today; a plain-JS chat UI is likewise SDK-only):** still deliver the plan; state that CometChat DOES support that platform but its implementation skill isn't built in this pack yet; offer the plan as the hand-off spec (or for a manual integration following CometChat's docs). Never silently pretend React. **Never put a shipped family on this list** — a literal agent will decline the user (this file once listed Android/RN/Flutter/Angular after they had shipped; `lint-skills.mjs` now checks the list against the shipped `-core` dirs).