@cometchat/skills 4.4.1 → 4.4.2

package/README.md

@@ -1,6 +1,6 @@
 # cometchat-skills
 
-**Add CometChat to any React, React Native, Angular, Android, Flutter, or iOS project through your AI coding agent.** Works with Claude Code, Cursor, Codex, VS Code Copilot, Windsurf, Cline, Kiro, and [30+ more agents](https://github.com/vercel-labs/skills).
+**Add CometChat to any React, React Native, Angular, Android, Flutter, or iOS project through your AI coding agent.** Works with Claude Code, Cursor, Codex, VS Code Copilot, Windsurf, Cline, Kiro, and [50+ more agents](https://github.com/vercel-labs/skills).
 
 v4 takes an AI-first approach: your agent has a short conversation with you to understand your project and chat requirements, then writes production-grade integration code tailored to the files you already have. One slash — `/cometchat` — works for every supported framework, on web, mobile, and native.
 
@@ -17,9 +17,9 @@ Override detection if needed:
 ```bash
 npx @cometchat/skills add --family web      # React / Next.js / React Router / Astro
 npx @cometchat/skills add --family native   # Expo / bare RN
-npx @cometchat/skills add --family angular  # Angular 12-15
-npx @cometchat/skills add --family android  # Native Android (V5 stable + V6 beta)
-npx @cometchat/skills add --family flutter  # Flutter (V5 stable + V6 beta)
+npx @cometchat/skills add --family angular  # Angular 17-21
+npx @cometchat/skills add --family android  # Native Android (V6 stable, recommended + V5 legacy)
+npx @cometchat/skills add --family flutter  # Flutter (V6 stable, recommended + V5 legacy)
 npx @cometchat/skills add --family ios      # Native iOS (V5 stable)
 npx @cometchat/skills add --family all      # install every published skill
 ```
@@ -83,7 +83,7 @@ Or add voice & video calling (new in v4.2):
 When integrating chat, the dispatcher now asks **how** you want to customize (new in v4.3):
 
 ```
-◉ Visually — drag-and-drop in browser
+◉ Visually — enable-disable in browser
 ○ In code — code-driven defaults
 ```
 
@@ -110,10 +110,10 @@ No templates, no experiences to pick — the agent writes real code that fits yo
 | Astro (React islands) | ✅ | ✅ Ringing + Session | ✅ (v4.3) |
 | Expo (managed + Expo Router) | ✅ | ✅ Ringing + Session | ✅ (v4.3) |
 | Bare React Native (CLI) | ✅ | ✅ Ringing + Session | ✅ (v4.3) |
-| Angular 12-15 | ✅ | ✅ Ringing + Session | ❌ (auto-falls back to In code) |
-| Android (V5 stable + V6 beta) | ✅ | ✅ Ringing + Session | ✅ V6 (v4.3) |
-| Flutter (V5 stable + V6 beta) | ✅ | ✅ Ringing + Session | ✅ V6 chat-only (v4.3) |
-| iOS (V5 stable) | ✅ | ✅ Ringing + Session | ⏸ Pending Xcode 26 vendor fix |
+| Angular 17-21 | ✅ | ✅ Ringing + Session | ❌ (auto-falls back to In code) |
+| Android (V6 stable, recommended + V5 legacy) | ✅ | ✅ Ringing + Session | ✅ V6 (v4.3) |
+| Flutter (V6 stable, recommended + V5 legacy) | ✅ | ✅ Ringing + Session | ✅ V6 chat-only (v4.3) |
+| iOS (V5 stable) | ✅ | ✅ Ringing + Session | ✅ (v4.4) |
 
 **Calling modes:**
 - **Ringing** — kit-driven incoming/outgoing call surfaces, system-level VoIP push (CallKit on iOS, ConnectionService on Android, web push fallback on browsers). Production-grade for 1:1 + group calls.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cometchat/skills",
-  "version": "4.4.1",
+  "version": "4.4.2",
   "publishConfig": {
     "access": "public"
   },
@@ -26,7 +26,7 @@
     "kotlin",
     "ui-kit"
   ],
-  "author": "swapnil-cometchat",
+  "author": "CometChat",
   "license": "MIT",
   "repository": {
     "type": "git",

package/skills/cometchat/SKILL.md

@@ -499,7 +499,7 @@ Field meanings (from the dashboard's signup screens):
 - **Step 3a:** if `meta.intent === "exploring"`, skip the placement-intent question and route straight to the "Just exploring" branch (one route/screen with `<CometChatConversations />` and `cometchat-uid-1` pre-logged-in).
 - **Step 3b.1 (industry tailoring):** use `last_app.industry` to layer industry-specific upsells onto the placement recommendation — moderation features for dating apps, HIPAA-aware production patterns for healthcare, link-preview for marketplaces, etc. Augment, don't replace.
 - **Step 5 explanations:** if `meta.role === "frontend"`, lead with concrete component composition + CSS examples; if `meta.role === "engineering_leader/manager"`, lead with placement architecture trade-offs (where state lives, what gets cached, how routing fits the project's pattern).
-- **Greeting:** if `meta.name` is non-null, greet by name in any user-facing message during the rest of the flow ("Got it, Swapnil — let's pick an app").
+- **Greeting:** if `meta.name` is non-null, greet by name in any user-facing message during the rest of the flow ("Got it, {name} — let's pick an app").
 
 **Failure modes — each is non-blocking; degrade to the original generic flow:**
 

package/skills/cometchat-android-v5-calls/SKILL.md

@@ -324,13 +324,15 @@ Component-level deep dives: `references/audio-controls.md`, `references/video-co
 
 When `product === "voice-video"` and there is no existing chat integration.
 
+> **Telemetry attribution (`ai-agent`).** Session mode (§4a, Calls SDK only) MUST init via `CometChatCalls.initFromSettings(context, callback)` (`com.cometchat:calls-sdk-android >= 5.0.2`, verified via `javap`) reading `app/src/main/assets/cometchat-settings.json` — it's the only reporter in a calls-only app and fires on `CometChatCalls.login`. **Additive** mode (calls added on top of a v5 chat integration) is attributed by the chat side when chat inits via `CometChatUIKit.initFromSettings` (`cometchat-android-v5-core`); the additive calls step adds a raw `CometChatCalls.init`, which the SDK suppresses in favour of the chat report. **Ringing mode (§4b)** links the raw Chat SDK for signaling — use `CometChatCalls.initFromSettings` there too so the calls side carries the flag.
+
 **Split by calling mode:**
 
 ### 4a. Standalone — Session mode (meeting-room UX, no ringing)
 
 Calls SDK ONLY. NO Chat SDK, NO ConnectionService, NO FCM-for-VoIP. Matches `calls-sdk-android-5/samples/sample-app/`. Scaffold:
 
-1. **`Application` class** — `CometChatCalls.init(...)` ONLY in `onCreate`. No `CometChat.init`, no PhoneAccount, no ConnectionService.
+1. **`Application` class** — **`CometChatCalls.initFromSettings(context, callback)`** ONLY in `onCreate`, reading the committed `app/src/main/assets/cometchat-settings.json` so the calls-only app self-reports `integrationSource = "ai-agent"` (`calls-sdk-android >= 5.0.2`; on an older SDK the method is absent — fall back to the `CallAppSettings.CallAppSettingBuilder` + `CometChatCalls.init(...)` shown in §2). No `CometChat.init`, no PhoneAccount, no ConnectionService. The report fires on `CometChatCalls.login(uid, authKey, callback)` success, so log the user in via `CometChatCalls.login` in session mode.
 2. **`JoinSessionActivity`** — UID picker + Start/Join meeting + state.
 3. **`CallActivity`** — Single-call `CometChatCalls.joinSession(sessionId, sessionSettings, container, CallbackListener)`. `SessionStatusListener` + `ButtonClickListener` registered on the `CallSession` from `onSuccess`. `CometChatOngoingCallService.launch/abort`. See `references/call-session.md`.
 4. **`AndroidManifest.xml`** — Camera + microphone permissions + `FOREGROUND_SERVICE_MICROPHONE/CAMERA` + `CometChatOngoingCallService` registration. NO ConnectionService.

package/skills/cometchat-android-v6-calls/SKILL.md

@@ -369,13 +369,15 @@ Full component-by-component catalogs live in the existing `cometchat-android-v6-
 
 When `product === "voice-video"` and there is no V6 chat integration yet.
 
+> **Telemetry attribution (`ai-agent`).** Session mode (§4a, Calls SDK only) MUST init via `CometChatCalls.initFromSettings(context, callback)` (`com.cometchat:calls-sdk-android >= 5.0.2`, verified via `javap`) reading `app/src/main/assets/cometchat-settings.json` — the only reporter in a calls-only app; fires on `CometChatCalls.login`. **Additive mode:** no calling-enable field is needed — `integrationSource = "ai-agent"` is persisted (appId-scoped) by the chat-side `CometChatUIKit.initFromSettings` (`cometchat-android-v6-core`), and the calls integration is attributed at the backend from the **calls SDK version + platform present in the `/user_sessions` node**. Enabling calls via `setEnableCalling(true)` on the builder does not affect either signal.
+
 **Split by calling mode:**
 
 ### 4a. Standalone — Session mode (meeting-room UX, no ringing)
 
 Calls SDK ONLY. NO chatuikit-android, NO ConnectionService, NO FCM-for-VoIP. Same SDK as V5 (`com.cometchat.calls-sdk-android`). Scaffold:
 
-1. **`Application` class** — `CometChatCalls.init(...)` ONLY. No chatuikit, no Chat SDK init.
+1. **`Application` class** — **`CometChatCalls.initFromSettings(context, callback)`** ONLY, reading the committed `app/src/main/assets/cometchat-settings.json` so the calls-only app self-reports `integrationSource = "ai-agent"` (`calls-sdk-android >= 5.0.2`; older SDK → fall back to `CallAppSettings.CallAppSettingBuilder` + `CometChatCalls.init(...)`). No chatuikit, no Chat SDK init. The report fires on `CometChatCalls.login` success.
 2. **`MainActivity` (Compose)** — `setContent` with `NavHost` for `/`, `/meet/{sessionId}`.
 3. **`CallRoom` composable** — `AndroidView` factory wrapping `RelativeLayout` (remember-stable), `LaunchedEffect(sessionId)` fires `CometChatCalls.joinSession(sessionId, settings, container, CallbackListener)`, `DisposableEffect` cleanup. See `references/call-session.md`.
 4. **`AndroidManifest.xml`** — Camera + microphone permissions + `FOREGROUND_SERVICE_MICROPHONE/CAMERA` + `CometChatOngoingCallService` registration. NO ConnectionService.

package/skills/cometchat-android-v6-core/SKILL.md

@@ -235,7 +235,7 @@ Initialize once in your `Application` class or splash screen — never in every
 }
 ```
 
-> Do NOT gitignore `cometchat-settings.json` — the dev-mode `authKey` it holds is no more exposed than a `BuildConfig.COMETCHAT_AUTH_KEY` value.
+> **Commit `cometchat-settings.json` — do not gitignore it** (the file is part of the integration). Its `authKey` is an **optional demo/POC credential**: a quick-start affordance so a PM or developer can see working chat *before* the backend auth-token flow is wired (that flow often waits on internal approvals). Because the file is committed to source control, treat the key as public — use a **dedicated demo CometChat app** (a committed key trips secret scanners and stays in git history; never reuse a production app's key). Switch to a server-minted `authToken` via `loginWithAuthToken()` before production, where `authKey` must not ship.
 
 **Step 2 — init in `Application.onCreate()`.** No `UIKitSettingsBuilder` — the SDK reads `app/src/main/assets/cometchat-settings.json` itself:
 

package/skills/cometchat-angular-calls/SKILL.md

@@ -54,6 +54,8 @@ await CometChatUIKit.init(settings);
 await CometChatUIKit.login("cometchat-uid-1");     // kit initializes the Calls SDK internally
 ```
 
+> **Telemetry (`ai-agent`).** Enabling calls uses `setCallingEnabled(true)` on the builder — no calling-enable field in `cometchat-settings.json` is needed. `integrationSource = "ai-agent"` is persisted (appId-scoped) by the chat-side `CometChatUIKit.initFromSettings` (`cometchat-angular-core`) and reported on chat login; the calls integration is attributed at the backend from the **calls SDK version + platform present in the `/user_sessions` node**. Both signals are already captured — nothing extra to wire here.
+
 - `setCallingEnabled(true)` is a real `UIKitSettingsBuilder` method (verified in the kit `.d.ts`). It is **off by default** — without it the call components render disabled and `CometChatUIKit.isCallingEnabled()` returns `false`.
 - After login, confirm with `CometChatUIKit.isCallingEnabled()` (static, returns `boolean`) before rendering call UI on a custom screen.
 - **Optional advanced config:** to override the Calls SDK app settings, build a `CometChatUIKitCalls.CallAppSettingsBuilder()` and pass it via `.setCallAppSettings(callAppSettings)`. `CometChatUIKitCalls` is re-exported by the UI Kit — import it from `@cometchat/chat-uikit-angular` (the kit wraps the optional `@cometchat/calls-sdk-javascript` dependency; the calls SDK itself exports `CometChatCalls`, not `CometChatUIKitCalls`):

package/skills/cometchat-angular-core/SKILL.md

@@ -123,7 +123,7 @@ CometChatUIKit.initFromSettings(cometchatSettings)
   .catch((err) => console.error("CometChat init failed:", err));
 ```
 
-- **Do NOT gitignore `cometchat-settings.json`.** The dev-mode `authKey` ships in the built bundle either way; production uses server-minted auth tokens.
+- **Commit `cometchat-settings.json` — do not gitignore it** (the file is part of the integration). Its `authKey` is an **optional demo/POC credential**: a quick-start affordance so a PM or developer can see working chat *before* the backend auth-token flow is wired (that flow often waits on internal approvals). Because the file is committed to source control, treat the key as public — use a **dedicated demo CometChat app** (a committed key trips secret scanners and stays in git history; never reuse a production app's key). Switch to a server-minted `authToken` via `loginWithAuthToken` before production, where `authKey` must not ship.
 
 ### UIKitSettingsBuilder — the init pattern (fallback — published kit; reports `manual`)
 

package/skills/cometchat-calls/SKILL.md

@@ -42,7 +42,7 @@ The chat dispatcher (`cometchat/SKILL.md`) assumes the user is adding a chat sur
 | 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 `CallAppSettings` (the dual-SDK contract) |
+| 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 |

package/skills/cometchat-core/SKILL.md

@@ -118,7 +118,7 @@ import cometchatSettings from "./cometchat-settings.json"; // adjust path to the
 await CometChatUIKit.initFromSettings(cometchatSettings);
 ```
 
-- **Do NOT gitignore `cometchat-settings.json`.** The dev-mode `authKey` it holds is no more exposed than a `VITE_COMETCHAT_AUTH_KEY=…` env value (both ship in the built bundle); production integrations migrate to server-minted auth tokens regardless.
+- **Commit `cometchat-settings.json` — do not gitignore it** (the file is part of the integration). Its `authKey` is an **optional demo/POC credential**: a quick-start affordance so a PM or developer can see working chat *before* the backend auth-token flow is wired (that flow often waits on internal approvals). Because the file is committed to source control, treat the key as public — use a **dedicated demo CometChat app** (a committed key trips secret scanners and stays in git history; never reuse a production app's key). Switch to a server-minted `authToken` via `loginWithAuthToken` before production, where `authKey` must not ship.
 - The same module-flag / `useEffect` / entry-point placement rules in the rest of this section apply unchanged — just swap `CometChatUIKit.init(settings)` for `CometChatUIKit.initFromSettings(cometchatSettings)`.
 
 ### The UIKitSettingsBuilder (fallback — UI Kit before file-based init)

package/skills/cometchat-flutter-v5-calls/SKILL.md

@@ -261,7 +261,7 @@ dependencies:
   flutter:
     sdk: flutter
   cometchat_chat_uikit: ^5.2.14         # additive mode — existing GetX chat kit (keep)
-  cometchat_calls_sdk: ^5.0.2           # DIRECT dependency — the 5.x calls SDK (raw)
+  cometchat_calls_sdk: ^5.0.4           # DIRECT dependency — 5.x calls SDK (raw); >=5.0.4 ships initFromSettings
   permission_handler: ^11.0.0           # rule 1.6
   flutter_callkit_incoming: ^2.0.0      # standalone — VoIP UI bridge
   firebase_messaging: ^14.0.0           # standalone — Android FCM
@@ -366,14 +366,16 @@ You build the call surface yourself (custom widgets) around these APIs. There ar
 
 When `product === "voice-video"` and there is no v5 chat integration.
 
+> **Telemetry attribution (`ai-agent`).** Session mode (§4a) MUST init the calls SDK via `CometChatCalls.initFromSettings(onSuccess:, onError:)` (`cometchat_calls_sdk >= 5.0.4`, verified against `lib/src/plugin/cometchatcalls.dart`) reading the `cometchat-settings.json` asset — it persists the `ai-agent` source and the report fires on `CometChatCalls.loginWithAuthToken`/`login`. **Additive** mode (raw calls SDK added to a v5 chat integration) is attributed by the chat side when chat inits via `CometChatUIKit.initFromSettings` (`cometchat-flutter-v5-core`). Pin `cometchat_calls_sdk: ^5.0.4` — the floor that ships `initFromSettings`.
+
 **Split by calling mode:**
 
 ### 4a. Standalone — Session mode (meeting-room UX, no ringing)
 
 5.x Calls SDK ONLY. The Chat SDK is present only as the source of the auth token used to log the Calls SDK in (rule 1.0). Scaffold:
 
-1. **`pubspec.yaml`** — `cometchat_calls_sdk: ^5.0.2` + `cometchat_chat_sdk` (for the auth token). No `cometchat_chat_uikit`, no `cometchat_calls_uikit`.
-2. **`lib/main.dart`** — `CometChat.init(...)` + `CometChat.login(...)`, then `CometChatCalls.init(callAppSettings, onSuccess:, onError:)` (build via `CallAppSettingBuilder()..appId=…..region=…`) + `CometChatCalls.loginWithAuthToken(authToken: ..., ...)` + `permission_handler` flow.
+1. **`pubspec.yaml`** — `cometchat_calls_sdk: ^5.0.4` (the floor that ships `initFromSettings`) + `cometchat_chat_sdk` (for the auth token). No `cometchat_chat_uikit`, no `cometchat_calls_uikit`. Declare `cometchat-settings.json` under `flutter: assets:`.
+2. **`lib/main.dart`** — `CometChat.init(...)` + `CometChat.login(...)` (Chat SDK only mints the auth token), then **`CometChatCalls.initFromSettings(onSuccess:, onError:)`** reading the committed `cometchat-settings.json` asset so the calls app self-reports `integrationSource = "ai-agent"` (on `<= 5.0.3` the method is absent — fall back to `CometChatCalls.init(callAppSettings, onSuccess:, onError:)` built via `CallAppSettingBuilder()..appId=…..region=…`) + `CometChatCalls.loginWithAuthToken(authToken: ..., ...)` (the login that fires the report) + `permission_handler` flow.
 3. **`lib/screens/call_screen.dart`** — `StatefulWidget` implementing the relevant 5.x split listeners (`SessionStatusListeners`, etc.). `CometChatCalls.joinSession(sessionId: ..., sessionSettings: SessionSettingsBuilder().build(), onSuccess:, onError:)`. Register listeners on `CallSession.getInstance()` in `onSuccess`. `CometChatOngoingCallService.launch/abort`. See `references/call-session.md`.
 4. **Native config** — Camera + microphone permissions only (no PushKit, no FCM for VoIP).
 
@@ -395,7 +397,7 @@ Dual-SDK: Chat SDK signaling + 5.x Calls SDK media. Scaffold:
 
 When chat is already integrated (existing GetX `cometchat_chat_uikit`). The skill:
 
-1. Adds **`cometchat_calls_sdk: ^5.0.2`** (raw, direct) to `pubspec.yaml` — NOT `cometchat_calls_uikit`.
+1. Adds **`cometchat_calls_sdk: ^5.0.4`** (raw, direct) to `pubspec.yaml` — NOT `cometchat_calls_uikit`.
 2. Inits + logs in the 5.x Calls SDK alongside the existing chat init/login (rules 1.0, 1.1).
 3. Sets a plain `GlobalKey<NavigatorState>` on `MaterialApp.navigatorKey` (rule 1.7).
 4. Mounts the global Chat SDK `CallListener` in the app-shell `State` (rule 1.7).

package/skills/cometchat-flutter-v6-calls/SKILL.md

@@ -320,14 +320,16 @@ Pass to `UIKitSettings.callingConfiguration` to apply globally without per-compo
 
 When `product === "voice-video"` and there is no v6 chat integration.
 
+> **Telemetry attribution (`ai-agent`).** Session mode (§4a, Calls SDK only) MUST init via `CometChatCalls.initFromSettings(onSuccess:, onError:)` (`cometchat_calls_sdk >= 5.0.4`, verified against `lib/src/plugin/cometchatcalls.dart`) reading the `cometchat-settings.json` asset — the only reporter in a calls-only app; fires on `CometChatCalls.login`. **Additive mode:** no calling-enable field is needed — `integrationSource = "ai-agent"` is persisted (appId-scoped) by the chat-side `CometChatUIKit.initFromSettings` (`cometchat-flutter-v6-core`), and the calls integration is attributed at the backend from the **calls SDK version + platform present in the `/user_sessions` node**. Enabling calls via `..enableCalls = true` + `CometChatUIKitCalls.init()` does not affect either signal.
+
 **Split by calling mode:**
 
 ### 4a. Standalone — Session mode (meeting-room UX, no ringing)
 
 Calls SDK ONLY. NO Chat SDK, NO UIKit. Same SDK as v5 (`cometchat_calls_sdk`). Scaffold:
 
-1. **`pubspec.yaml`** — `cometchat_calls_sdk: ^5.0.0` + `flutter_bloc` + `equatable` + `permission_handler` ONLY.
-2. **`lib/main.dart`** — `CometChatCalls.init((CallAppSettingBuilder()..appId = APP_ID..region = REGION).build(), onSuccess: ..., onError: ...)` (named-callback form; `CallAppSettingBuilder` exposes only `appId`/`region`/host overrides — there is NO `authKey` field. Verified `cometchat_calls_sdk-5.0.2` `src/builder/call_app_settings_request.dart` + `src/plugin/cometchatcalls.dart:172`). Permission requests. NO Chat SDK init.
+1. **`pubspec.yaml`** — `cometchat_calls_sdk: ^5.0.4` (the floor that ships `initFromSettings`) + `flutter_bloc` + `equatable` + `permission_handler`. Declare `cometchat-settings.json` under `flutter: assets:`.
+2. **`lib/main.dart`** — **`CometChatCalls.initFromSettings(onSuccess: ..., onError: ...)`** reading the committed `cometchat-settings.json` asset so the calls-only app self-reports `integrationSource = "ai-agent"` (`cometchat_calls_sdk >= 5.0.4`, verified against `src/plugin/cometchatcalls.dart`; on `<= 5.0.3` fall back to `CometChatCalls.init((CallAppSettingBuilder()..appId = APP_ID..region = REGION).build(), onSuccess:, onError:)` — `CallAppSettingBuilder` exposes only `appId`/`region`/host overrides, no `authKey`). Permission requests. NO Chat SDK init. The report fires on `CometChatCalls.login` success.
 3. **`lib/cubits/call_session_cubit.dart`** — Cubit implements `SessionStatusListeners`. `CometChatCalls.joinSession(sessionId:, sessionSettings: SessionSettingsBuilder().build(), onSuccess:, onError:)`. Renders the returned `Widget?` via `SizedBox.expand`. See `references/call-session.md`.
 4. **`lib/screens/call_room.dart`** — `BlocConsumer` for auto-pop on idle transition.
 5. **Native config** — Camera + microphone permissions only.

package/skills/cometchat-flutter-v6-core/SKILL.md

@@ -70,7 +70,7 @@ flutter:
     - cometchat-settings.json
 ```
 
-- **Do NOT gitignore `cometchat-settings.json`.** The dev-mode `authKey` it holds is no more exposed than a `--dart-define=COMETCHAT_AUTH_KEY=…` value (both ship in the built app); production integrations migrate to server-minted auth tokens regardless.
+- **Commit `cometchat-settings.json` — do not gitignore it** (the file is part of the integration). Its `authKey` is an **optional demo/POC credential**: a quick-start affordance so a PM or developer can see working chat *before* the backend auth-token flow is wired (that flow often waits on internal approvals). Because the file is committed to source control, treat the key as public — use a **dedicated demo CometChat app** (a committed key trips secret scanners and stays in git history; never reuse a production app's key). Switch to a server-minted `authToken` via `loginWithAuthToken` before production, where `authKey` must not ship.
 
 **Step 3 — init in `main()`.** No `UIKitSettingsBuilder`, no config const — the SDK reads `cometchat-settings.json` itself:
 

package/skills/cometchat-ios-calls/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: cometchat-ios-calls
-description: CometChat Calls SDK v5 integration for native iOS (Swift; SwiftUI + UIKit hosting). Covers SDK install (SPM + CocoaPods), CometChatCalls init, dual-SDK ringing (Chat SDK initiateCall + Calls SDK generateToken/startSession), CallKit + PushKit VoIP push, AVAudioSession routing, mixed-stack hosting (UIViewControllerRepresentable for SwiftUI), Info.plist permissions + Background Modes, and additive-vs-standalone modes.
+description: CometChat Calls SDK v5 integration for native iOS (Swift; SwiftUI + UIKit hosting). Covers SDK install (SPM + CocoaPods), file-based init via cometchat-settings.json (CometChatCalls.initFromSettings, ai-agent telemetry) with builder fallback, dual-SDK ringing (Chat SDK initiateCall + Calls SDK generateToken/startSession), CallKit + PushKit VoIP push, AVAudioSession routing, mixed-stack hosting (UIViewControllerRepresentable for SwiftUI), Info.plist permissions + Background Modes, and additive-vs-standalone modes.
 license: "MIT"
-compatibility: "Xcode 15+, Swift 5.9+, iOS 13+ deployment target; CometChatCallsSDK 5.x; CometChatSDK 4.x; CometChatUIKitSwift 5.x (additive mode)"
+compatibility: "Xcode 15+, Swift 5.9+, iOS 15.1+ deployment target (CometChatCallsSDK 5.0.2+; 13.0 only for <= 5.0.1); CometChatSDK 4.x; CometChatUIKitSwift 5.x (additive mode)"
 metadata:
   author: "CometChat"
-  version: "4.0.0"
+  version: "4.1.0"
   tags: "cometchat ios calls voice video webrtc swift swiftui uikit callkit pushkit avaudiosession spm cocoapods voip background-modes"
 ---
 
@@ -40,11 +40,13 @@ Production-grade voice + video calling for native iOS. Loaded by `cometchat-call
 
 ## 1. The seven hard rules — iOS specialization
 
-> ⚠️ **TOP PRIORITY (ENG-35710): Auth-token passing is the most-broken step on iOS Calls integrations.** Unlike Android / Flutter / JS, the **iOS Calls SDK 5.x has NO separate login step** — there is no `CometChatCalls.login(...)` and no `CometChatCalls.getLoggedInUser()` (those are phantom; verified absent from `CometChatCallsSDK`). Auth is supplied **per session** as the `authToken:` argument to `CometChatCalls.generateToken(authToken:sessionID:)`. Every tester who hit "calls don't work" on iOS traced back to that token: (a) the token was empty/nil → `generateToken` fails with **"auth token cannot be null"**; (b) a server-minted token expired between mint and `generateToken` (default ~30-minute TTL); (c) the client-side `apiKey` was passed instead of the user's auth token. Before scaffolding ANY iOS calls code, confirm the auth path (dev: read `CometChat.getUserAuthToken()`; production: fetch a fresh server-minted token) and feed it to `generateToken`. Mixing them is the canonical "ringing but never joins" iOS failure mode.
+> ⚠️ **TOP PRIORITY (ENG-35710): Auth-token passing is the most-broken step on iOS Calls integrations.** Unlike Android / Flutter / JS, the **iOS Calls SDK 5.x has NO separate login step** — there is no `CometChatCalls.login(...)` and no `CometChatCalls.getLoggedInUser()` (those are phantom; verified absent from `CometChatCallsSDK` — **in 5.0.1 and earlier; 5.0.2 restores them — see the §1.0 correction**). Auth is supplied **per session** as the `authToken:` argument to `CometChatCalls.generateToken(authToken:sessionID:)`. Every tester who hit "calls don't work" on iOS traced back to that token: (a) the token was empty/nil → `generateToken` fails with **"auth token cannot be null"**; (b) a server-minted token expired between mint and `generateToken` (default ~30-minute TTL); (c) the client-side `apiKey` was passed instead of the user's auth token. Before scaffolding ANY iOS calls code, confirm the auth path (dev: read `CometChat.getUserAuthToken()`; production: fetch a fresh server-minted token) and feed it to `generateToken`. Mixing them is the canonical "ringing but never joins" iOS failure mode.
 
-### 1.0 The iOS Calls SDK has NO separate login (v5)
+### 1.0 The iOS Calls SDK has NO separate login (v5) — CORRECTED for 5.0.2 (2026-07-21)
 
-Unlike the Android / Flutter / JS Calls SDKs, **`CometChatCalls` on iOS has no `login()` and no `getLoggedInUser()`** — those methods do not exist in `CometChatCallsSDK` 5.x. There is nothing to "log in" to. Once the Chat SDK session exists, you authorize each call session by passing an **auth token** to `generateToken(authToken:sessionID:)`, then `startSession(callToken:callSetting:view:)` with the returned call token (full flow in §1.1).
+> **Correction (ENG-37137, verified against the published 5.0.2 binary + live end-to-end test 2026-07-21):** the "no login" claim below is TRUE for the UI Kit-vendored calls framework and for standalone **5.0.1 and earlier**, but **standalone `CometChatCallsSDK` 5.0.2 exports `login(UID:authKey:)` / `login(UID:apiKey:)` / `login(authToken:)` / `logout()` and persists the session** (v4-compat surface restored in `calls-core`; the SDK's own sample app logs in via `LoginViewController`). This matters for two reasons: (a) after login, the `generateToken(sessionID:)` overload works without hand-passing an auth token; (b) **login success is the trigger for the ai-agent identification telemetry** (§2) — in a calls-only app that never logs in, the self-report has nothing to fire on. Dual-SDK (ringing) integrations are unaffected: the Chat SDK login remains the only login you need there.
+
+Unlike the Android / Flutter / JS Calls SDKs, **`CometChatCalls` on iOS has no `login()` and no `getLoggedInUser()`** — those methods do not exist in `CometChatCallsSDK` 5.0.1 and earlier (see correction above for 5.0.2+). There is nothing to "log in" to. Once the Chat SDK session exists, you authorize each call session by passing an **auth token** to `generateToken(authToken:sessionID:)`, then `startSession(callToken:callSetting:view:)` with the returned call token (full flow in §1.1).
 
 ```swift
 import CometChatSDK
@@ -367,7 +369,7 @@ Pin to `5.0.0..<6.0.0`. SPM resolves `CometChatSDK` automatically.
 ### CocoaPods
 
 ```ruby
-platform :ios, '13.0'
+platform :ios, '15.1'   # REQUIRED for CometChatCallsSDK 5.0.2+ — a lower platform silently resolves 5.0.1 (no initFromSettings)
 target 'YourApp' do
   use_frameworks!
   pod 'CometChatSDK',       '~> 4.0'    # signaling
@@ -382,9 +384,33 @@ post_install do |installer|
 end
 ```
 
-### Init
+### Init — file-based with `cometchat-settings.json` (recommended)
+
+> **Version requirement (ENG-37137 — Skills Telemetry).** `CometChatCalls.initFromSettings(onSuccess:onError:)` reads a bundled `cometchat-settings.json` and lets the **Calls SDK** self-report `integrationSource = "ai-agent"` to `/user_sessions`. It ships in **`CometChatCallsSDK` >= 5.0.2** (released 2026-07-20). ⚠️ **THE SILENT-DOWNGRADE TRAP: 5.0.2 raised the minimum iOS deployment target to 15.1.** If the Podfile declares `platform :ios` below 15.1, CocoaPods does NOT error — it silently resolves **5.0.1**, which has no `initFromSettings` (and self-reports version 99.0.0). After `pod install`, **verify `Podfile.lock` shows `CometChatCallsSDK (5.0.2)`** — a missing `initFromSettings` symbol at build time means you got 5.0.1. On 5.0.1/5.0.0 the method does not exist — bump the platform to 15.1 (preferred) or use the **`CallAppSettingsBuilder` fallback** below.
+
+Like the iOS UI Kit's `CometChatUIKit.initFromSettings` (see `cometchat-ios-core`), the Calls variant takes **no settings argument** — it reads the file straight from the app's main bundle, so the file must be in the target's **Copy Bundle Resources**.
 
-In SwiftUI app entry (`@main struct App.init()`) or UIKit `application(_:didFinishLaunchingWithOptions:)`:
+**Step 1 — `cometchat-settings.json`.** It is the SAME unified file the chat-side skills create. If `cometchat-ios-core` already added one, reuse it — just confirm the `callsSDK` section exists. Creating it fresh (calls-only app):
+
+```json
+{
+  "appId": "APP_ID_HERE",
+  "region": "us",
+  "credentials": {
+    "authKey": "AUTH_KEY_HERE"
+  },
+  "callsSDK": {
+    "host": null,
+    "adminHost": null,
+    "clientHost": null,
+    "callsHost": null
+  }
+}
+```
+
+`initFromSettings` reads the root `appId` / `region` and the four optional `callsSDK` host overrides; everything else in the unified schema is ignored by the Calls SDK. Add the file to the app target (*File → Add Files…* AND confirm it under *Build Phases → Copy Bundle Resources*) — `SETTINGS_FILE_NOT_FOUND` at init means it's missing from Copy Bundle Resources. Commit the file; treat any `authKey` in it as a public demo credential (same rule as `cometchat-ios-core` §2).
+
+**Step 2 — init (no builder, no args):**
 
 ```swift
 import CometChatSDK
@@ -398,19 +424,36 @@ let appSettings = AppSettings.AppSettingsBuilder()
 CometChat.init(appId: Secrets.cometchatAppID, appSettings: appSettings) { isInitialized, error in
   guard error == nil else { return }
 
-  let callAppSettings = CallAppSettingsBuilder()
-    .setAppId(Secrets.cometchatAppID)
-    .setRegion(Secrets.cometchatRegion)
-    .build()
-
-  CometChatCalls.init(callsAppSettings: callAppSettings, onSuccess: { _ in
+  // File-based init — reads cometchat-settings.json from the bundle and
+  // attributes the integration as ai-agent for /user_sessions telemetry.
+  CometChatCalls.initFromSettings(onSuccess: { _ in
     // ready — register PushKit (rule 1.2) and CXProvider (rule 1.7) here
   }, onError: { error in
-    print("CometChatCalls.init failed: \(error?.errorDescription ?? "")")
+    print("CometChatCalls init failed: \(error?.errorDescription ?? "")")
   })
 }
 ```
 
+**How the attribution works (don't fight it):** `initFromSettings` persists `integrationSource = "ai-agent"` (appId-scoped) *before* delegating to the normal init. The identification POST itself fires on `CometChatCalls.login(...)` success or on a later `init` that restores a persisted session, and is deduped via a SHA-256 hash — repeats are no-ops until the app/SDK version or integration source changes. Two consequences:
+
+- **Do NOT scaffold a raw `CallAppSettingsBuilder` init when `initFromSettings` is available** — a direct builder init re-attributes the integration as `manual`.
+- When the **Chat SDK is linked in the same app** (dual-SDK ringing mode, additive mode), the Calls SDK suppresses its own self-report — the chat side reports instead, so ALSO use the chat-side file-based init there (`CometChatUIKit.initFromSettings` — `cometchat-ios-core` §2). The calls-side `initFromSettings` is still the right init (one config file, ai-agent source persisted either way).
+
+### Init — `CallAppSettingsBuilder` (fallback — 5.0.1 and earlier)
+
+```swift
+let callAppSettings = CallAppSettingsBuilder()
+  .setAppId(Secrets.cometchatAppID)
+  .setRegion(Secrets.cometchatRegion)
+  .build()
+
+CometChatCalls.init(callsAppSettings: callAppSettings, onSuccess: { _ in
+  // ready
+}, onError: { error in
+  print("CometChatCalls.init failed: \(error?.errorDescription ?? "")")
+})
+```
+
 Credentials via `Secrets.swift` (gitignored) or `.xcconfig` Build Settings — see `cometchat-ios-core`.
 
 ---
@@ -460,7 +503,7 @@ When `product === "voice-video"` and there is no existing UI Kit.
 
 Calls SDK ONLY. NO Chat SDK, NO CallKit, NO PushKit. Matches `calls-sdk-ios-5/sample-apps/cometchat-calls-sample-app-ios/`. Scaffold:
 
-1. **App entry** — `CometChatCalls.init(callsAppSettings:)` with a `CallAppSettingsBuilder().setAppId(...).setRegion(...).build()` ONLY. No `CometChat.init`, no `CometChat.login`, no PushKit, no CallKit.
+1. **App entry** — `CometChatCalls.initFromSettings(onSuccess:onError:)` with a bundled `cometchat-settings.json` (§2) ONLY — builder init is the pre-5.0.2 fallback. No `CometChat.init`, no `CometChat.login`, no PushKit, no CallKit. Note: with no Chat SDK linked, the Calls SDK is the only telemetry reporter here, and its send triggers on `CometChatCalls.login` success / persisted-session restore — if the app has identified users, log them in via `CometChatCalls.login(UID:authKey:)` (5.0.2+, see §1.0 correction) rather than hand-passing an auth token to `generateToken`.
 2. **`JoinSessionView.swift`** — UID picker + "Start meeting" / "Join meeting" + state.
 3. **`CallView.swift` + `CallContainerView: UIViewRepresentable`** — `CometChatCalls.generateToken(authToken:sessionID:)` then `CometChatCalls.startSession(callToken:callSetting:view:)`. Coordinator conforms to `CallsEventsDelegate` (set via `CallSettingsBuilder.setDelegate`). See `references/call-session.md`.
 4. **`Info.plist` patch** — Camera + microphone permissions ONLY. No `audio` or `voip` Background Modes needed.
@@ -472,7 +515,7 @@ Calls SDK ONLY. NO Chat SDK, NO CallKit, NO PushKit. Matches `calls-sdk-ios-5/sa
 
 Dual-SDK + CallKit + PushKit. Scaffold:
 
-1. **App entry** — Chat SDK + Calls SDK init, PushKit + CallKit registration (rule 1.2, 1.7).
+1. **App entry** — Chat SDK + Calls SDK init (both file-based: `CometChat.init` per `cometchat-ios-core`, then `CometChatCalls.initFromSettings` — §2), PushKit + CallKit registration (rule 1.2, 1.7).
 2. **`CallKitProviderDelegate.swift`** — `CXProviderDelegate` implementation. Routes `CXAnswerCallAction` → `CometChatCalls.generateToken` then `startSession(callToken:callSetting:view:)`. Routes `CXEndCallAction` → `CometChatCalls.endSession()` + `AVAudioSession` cleanup (rule 1.5).
 3. **`PushRegistryDelegate.swift`** — `PKPushRegistryDelegate` listening on `.voIP`. On payload → `CXProvider.reportNewIncomingCall` immediately.
 4. **`ProfileView.swift` (SwiftUI) or `ProfileViewController.swift` (UIKit)** — Hosts call buttons next to user info. Tap → `CometChat.initiateCall`.
@@ -489,7 +532,7 @@ When `cometchat-ios` is already integrated.
 
 The kit-default additive recipe:
 1. Confirm `CometChatUIKitSwift` is present (CallsSDK is bundled — nothing extra to install).
-2. Set **`.enable(inAppIncomingCall: true)`** on the `UIKitSettings` builder at init (the one calling switch).
+2. Set **`.enable(inAppIncomingCall: true)`** on the `UIKitSettings` builder at init (the one calling switch). If the integration was scaffolded with **`CometChatUIKit.initFromSettings`** (`cometchat-ios-core` §2 — the skills default), telemetry attribution is already handled on the chat side; the vendored calls framework needs no separate init or attribution step.
 3. Add Background Modes (`voip`, `remote-notification`, `audio`) + camera/mic permissions to `Info.plist`.
 4. Drop in `CometChatCallButtons` (e.g. user-details / contact screen) — the kit also auto-renders them in `CometChatMessageHeader` when CallsSDK is present; add `CometChatCallLogs` as a tab/route.
 5. (Optional) CallKit + PushKit for background VoIP (asks user — same opt-in as Android).
@@ -505,13 +548,15 @@ Only reach for `CometChatCalls.init` + `generateToken`/`startSession` (§1.1) wh
 5. **Mixing CallKit and an in-app incoming-call screen** in standalone mode. Causes double-rings and confused state. CallKit owns standalone rings; in-app UI is additive-mode only.
 6. **Using SwiftUI `.alert` for incoming calls.** It only fires when the app is foregrounded. Use CallKit (rule 1.7).
 7. **Pinning `CometChatCallsSDK` to a `4.x`** because that's what the chat SDK is on. They version independently — Calls SDK 5.x is the current calls major.
+8. **Hand-rolling `CallAppSettingsBuilder` init when `initFromSettings` is available (5.0.2+, §2).** The raw builder init re-attributes the integration as `manual` — file-based init is the skills path; the builder is only the pre-5.0.2 fallback.
 
 ## 7. Verification checklist
 
 **Static:**
 
 - [ ] `CometChatCallsSDK` in SPM Package.resolved or Podfile.lock
-- [ ] `CometChat.init` followed by `CometChatCalls.init` in app entry
+- [ ] `CometChat.init` followed by `CometChatCalls.initFromSettings` in app entry (builder `CometChatCalls.init` only as the pre-5.0.2 fallback — §2)
+- [ ] `cometchat-settings.json` present, has the `callsSDK` section, and listed under Copy Bundle Resources
 - [ ] PushKit registry listening on `.voIP`
 - [ ] `CXProvider` configured with `CXProviderConfiguration` (app name + ringtone if any)
 - [ ] `CXProviderDelegate` implements answer + end actions

package/skills/cometchat-ios-calls/references/add-calls-to-existing-chat.md

@@ -57,11 +57,18 @@ import CometChatUIKitSwift
 CometChatUIKit.init(uikitSettings: chatSettings) { result in
   switch result {
   case .success:
-    // NEW: Calls init AFTER chat init succeeded
-    let callsSettings = CallAppSettings(appId: APP_ID, region: REGION)
-    Task {
-      try await CometChatCalls.init(with: callsSettings)
-    }
+    // NEW: Calls init AFTER chat init succeeded.
+    // File-based init (CometChatCallsSDK >= 5.0.2 — requires iOS 15.1+ deployment
+    // target or CocoaPods silently resolves 5.0.1 without this API):
+    // reads the same bundled cometchat-settings.json the chat side uses and
+    // attributes the integration as ai-agent — see cometchat-ios-calls SKILL.md §2.
+    CometChatCalls.initFromSettings(onSuccess: { _ in
+      // calls ready
+    }, onError: { error in
+      print("CometChatCalls init failed: \(error?.errorDescription ?? "")")
+    })
+    // Pre-5.0.2 fallback: CallAppSettingsBuilder().setAppId(...).setRegion(...).build()
+    // passed to CometChatCalls.init(callsAppSettings:onSuccess:onError:).
   case .onError(let error):
     print(error)
   }

package/skills/cometchat-ios-core/SKILL.md

@@ -215,7 +215,7 @@ CometChatUIKit.initFromSettings { success, error in
 ```
 
 - If init throws `cometchat-settings.json not found`, the file isn't in **Copy Bundle Resources** — add it there (adding it to the project navigator alone is not enough).
-- **Do NOT gitignore `cometchat-settings.json`.** The dev-mode `authKey` ships in the app bundle either way; production uses server-minted auth tokens.
+- **Commit `cometchat-settings.json` — do not gitignore it** (the file is part of the integration). Its `authKey` is an **optional demo/POC credential**: a quick-start affordance so a PM or developer can see working chat *before* the backend auth-token flow is wired (that flow often waits on internal approvals). Because the file is committed to source control, treat the key as public — use a **dedicated demo CometChat app** (a committed key trips secret scanners and stays in git history; never reuse a production app's key). Switch to a server-minted `authToken` via `loginWithAuthToken` before production, where `authKey` must not ship.
 
 ### UIKitSettings Builder (fallback — UI Kit before file-based init)
 

package/skills/cometchat-native-calls/SKILL.md

@@ -482,6 +482,8 @@ This semantic is the same across all CometChat kits (React, Angular, native iOS,
 
 When `product === "voice-video"` and there is no existing UI Kit.
 
+> **Telemetry attribution (`ai-agent`).** Session mode (§4a, calls SDK only) MUST init via `CometChatCalls.initFromSettings(cometchatSettings)` (`@cometchat/calls-sdk-react-native >= 5.0.3`) — the only reporter in a calls-only app; it fires on `CometChatCalls.login`. **Additive** mode is already attributed by the chat side (`cometchat-native-core` inits chat via `CometChatUIKit.initFromSettings`; with the Chat SDK linked the Calls SDK suppresses its own report). **Ringing mode (§4b)** links the raw Chat SDK for signaling only — use `CometChatCalls.initFromSettings` there too so the calls side carries the flag.
+
 **Split by calling mode — these are two different shapes:**
 
 ### 4a. Standalone — Session mode (meeting-room UX, no ringing)
@@ -575,7 +577,7 @@ Verify checks: `rn_webrtc_peers` (11-peer presence) + `no_chat_sdk_in_session_on
 
 The skill then scaffolds:
 
-1. **`cometchat/init.ts`** — `CometChatCalls.init({ appId, region, authKey })` ONLY. No `CometChat.init`, no `CometChat.login`. Pass `authKey` at init so `CometChatCalls.login(uid)` needs no second arg.
+1. **`cometchat/init.ts`** — file-based init so the calls-only app self-reports `integrationSource = "ai-agent"`. Import the committed `cometchat-settings.json` and call **`CometChatCalls.initFromSettings(cometchatSettings)`** (`@cometchat/calls-sdk-react-native >= 5.0.3`, verified against the published types; returns `Promise<{ success, error }>` — check `.success`). No `CometChat.init`, no `CometChat.login`. On an older calls SDK the method does not exist — fall back to `CometChatCalls.init({ appId, region, authKey })`. Put `authKey` in the settings file so `CometChatCalls.login(uid)` needs no second arg. **The `ai-agent` report fires on `CometChatCalls.login` success**, so a session-only app must log the user in via `CometChatCalls.login(uid)`. Do NOT hand-roll the raw `init` when `initFromSettings` is available — a bare `init` re-attributes as `manual`.
 2. **`screens/JoinSession.tsx`** — UID picker + Start/Join meeting + state machine (`inMeeting && callToken`).
 3. **`screens/CallRoom.tsx`** — Renders `<CometChatCalls.Component callToken={callToken} />` inside `SafeAreaView`. `onConnectionClosed` listener resets state. See `references/call-session.md`.
 4. **No VoIP push** — session mode is link-driven, not ringing-driven. No `react-native-callkeep`, no PushKit, no FCM data messages.

package/skills/cometchat-native-core/SKILL.md

@@ -74,7 +74,7 @@ await CometChatUIKit.initFromSettings(cometchatSettings);
 // then: CometChatUIKit.login({ uid }) — see §2
 ```
 
-- **Do NOT gitignore `cometchat-settings.json`.** The dev-mode `authKey` ships in the JS bundle either way; production integrations use server-minted auth tokens.
+- **Commit `cometchat-settings.json` — do not gitignore it** (the file is part of the integration). Its `authKey` is an **optional demo/POC credential**: a quick-start affordance so a PM or developer can see working chat *before* the backend auth-token flow is wired (that flow often waits on internal approvals). Because the file is committed to source control, treat the key as public — use a **dedicated demo CometChat app** (a committed key trips secret scanners and stays in git history; never reuse a production app's key). Switch to a server-minted `authToken` via `loginWithAuthToken` before production, where `authKey` must not ship.
 - The init-once flag + "init before first render" rules below apply unchanged — just swap the `init({...})` call for `initFromSettings(cometchatSettings)`.
 
 ### UIKitSettings — the init object (fallback — UI Kit before file-based init)

package/skills/cometchat-react-calls/SKILL.md

@@ -527,7 +527,8 @@ CometChat Calls SDK is browser-only — `window`, `MediaStream`, `RTCPeerConnect
 
 | Class / function | Purpose |
 |---|---|
-| `CometChatCalls.init({ appId, region })` | One-time init. Returns `Promise<{ success, error }>` — check `.success`. |
+| `CometChatCalls.initFromSettings(cometchatSettings)` | **Preferred one-time init** (`calls-sdk-javascript >= 5.0.3`). Reads the imported `cometchat-settings.json`, persists `integrationSource = "ai-agent"`, returns `Promise<{ success, error }>`. Use in standalone/session mode. |
+| `CometChatCalls.init({ appId, region })` | One-time init — **fallback for calls SDK < 5.0.3** (no telemetry attribution; reports `manual`). Returns `Promise<{ success, error }>` — check `.success`. |
 | `CometChatCalls.login(uid, apiKey)` | Dev-mode login. Returns the logged-in `User`. |
 | `CometChatCalls.loginWithAuthToken(authToken)` | Production login with server-minted token. |
 | `CometChatCalls.getLoggedInUser()` | Returns a plain `{ uid, name, avatar?, status?, ... }` object or `null`. Access `.uid` as a PROPERTY (not `.getUid()` — that method belongs to the Chat SDK's `User` class, which session-only code does not import). Use to guard against double-login: `if (existing && existing.uid === uid) return existing;` |
@@ -571,13 +572,15 @@ In standalone mode, you can compose just `<CometChatOngoingCall />` + `<CometCha
 
 When `product === "voice-video"` and there is no existing chat UI integration.
 
+> **Telemetry attribution (`ai-agent`).** Session mode (§4a, calls SDK only) MUST init via `CometChatCalls.initFromSettings(cometchatSettings)` (`calls-sdk-javascript >= 5.0.3`) — that's the only reporter in a calls-only app, and it fires on `CometChatCalls.login`. **Additive** mode (calls on an existing chat integration) is already attributed by the chat side — `cometchat-core` inits chat via `CometChatUIKit.initFromSettings`, and when the Chat SDK is linked the Calls SDK suppresses its own report. **Ringing mode (§4b)** links the raw Chat SDK for signaling but has no chat UI-Kit init; use `CometChatCalls.initFromSettings` there too so the calls side carries the flag.
+
 **Split by calling mode — these are two different shapes:**
 
 ### 4a. Standalone — Session mode (meeting-room UX, no ringing)
 
 Calls SDK ONLY. NO Chat SDK. Matches the upstream sample at `calls-sdk-javascript-5/sample-apps/cometchat-calls-sample-app-react/`. The skill scaffolds:
 
-1. **`cometchat/init.ts`** — `CometChatCalls.init({ appId, region, authKey })` ONLY. No `CometChat.init`, no `CometChat.login`. Pass `authKey` at init time so subsequent `CometChatCalls.login(uid)` calls need no second arg.
+1. **`cometchat/init.ts`** — file-based init so the calls-only app self-reports `integrationSource = "ai-agent"`. Import the committed `cometchat-settings.json` and call **`CometChatCalls.initFromSettings(cometchatSettings)`** — it maps the shared settings shape onto the Calls SDK and returns `Promise<{ success, error }>` (check `.success`). No `CometChat.init`, no `CometChat.login`. **Version:** `initFromSettings` ships in `@cometchat/calls-sdk-javascript >= 5.0.3` (verified against the published types); on an older calls SDK the method does not exist — fall back to `CometChatCalls.init({ appId, region, authKey })`. Pass `authKey` in the settings file so `CometChatCalls.login(uid)` needs no second arg. **Attribution:** the `ai-agent` report fires on `CometChatCalls.login` success — a session-mode app with identified users must log in via `CometChatCalls.login(uid)` (not just hand a token to `generateToken`). Do NOT hand-roll the raw `init` when `initFromSettings` is available — a bare `init` re-attributes the integration as `manual`.
 2. **`cometchat/CometChatProvider.tsx`** — Runs Calls SDK init on mount, exposes `loggedInUser` via `CometChatCalls.getLoggedInUser()`, gates children on success.
 3. **`pages/Home.tsx`** — UID picker (dev mode) + "Start meeting" (mints UUID, navigates to `/meet/:id`) + "Join meeting" (paste sessionId).
 4. **`pages/CallRoom.tsx`** — `/meet/:sessionId` route. Container is `position: fixed; width: 100vw; height: 100vh`. `CometChatCalls.joinSession(token, {}, container)` with empty settings. See `references/call-session.md` for the canonical pattern.

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 CometChat
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.