@cometchat/skills 4.4.1 → 5.0.0

package/skills/cometchat-angular-v5-troubleshooting/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: cometchat-angular-v5-troubleshooting
+description: "Diagnose a broken CometChat Angular integration — blank panes, silent no-render, empty lists, events that never fire, UI that does not update, memory leaks, install failures. Symptom to cause to fix. Triggers: 'chat not showing', 'blank screen', 'nothing renders', 'click handler not firing', 'messages not updating', 'ERESOLVE', 'cometchat not working'."
+license: "MIT"
+compatibility: "@cometchat/chat-uikit-angular ^5 (5.1.0–5.2.0 verified); Angular 17-21"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat angular troubleshooting v5 debug blank-screen silent-failure diagnostics"
+---
+
+> **Ground truth:** `@cometchat/chat-uikit-angular@5` (5.1.0–5.2.0 verified). Symptoms map to causes verified against the installed kit and the live `{DOCS_BASE}/ui-kit/angular/troubleshooting.md` page (base + paths in `cometchat-angular-v5-core/references/docs-map.md`). Every `CometChat*` symbol named here exists in the `angular-v5` catalog; a fix that requires a symbol not in the catalog is a bug in this file, not a missing export.
+
+## Companion skills (read first)
+- `cometchat-angular-v5-core` — `references/anti-patterns.md` and `references/troubleshooting.md` carry the same table in more depth.
+
+## Use this skill when
+Something is wrong and the error message is unhelpful or absent.
+
+## Start here — Angular fails SILENTLY
+Four of the five most common CometChat-Angular faults produce **no error at all**. Do not wait for a stack trace.
+
+Run these four checks in order before anything else:
+
+**1. Is the component in `imports: []`?**
+Missing → Angular treats `<cometchat-conversations>` as unknown HTML and renders nothing. No error, no warning, blank space. This is the single most common cause.
+
+**2. Does the container have height?**
+```css
+html, body { height: 100%; margin: 0; }
+```
+Plus a `100dvh` shell and `min-height: 0` on every flex column. An unsized ancestor collapses the list to 0px — markup correct, nothing visible.
+
+**3. Did `login()` resolve before render?**
+Lists render empty with no error when there is no session. Check `CometChatUIKit.getLoggedInUser()` is non-null at the moment the component mounts.
+
+**4. Is the binding name real?**
+`(ccConversationClicked)` never fires — the real output is `(itemClick)`. Angular does not warn about unknown outputs. Verified names are in `cometchat-angular-v5-components`.
+
+## Symptom → cause → fix
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Icons missing/blank across the kit | `assets` not registered in `angular.json` | add the `src/lib/assets` glob → `output: assets`; the most commonly missed step |
+| Scrolling the list scrolls the WHOLE page | shell/columns missing `overflow: hidden` | `min-height: 0` lets it shrink; `overflow: hidden` keeps the scroll inside the pane — both are required |
+| List doesn't scroll at all — bottom items unreachable | `<cometchat-conversations>`/`-users`/`-groups`/`-call-logs`/`-search`/`-message-list` has no `flex: 1; min-height: 0` of its OWN | add the `.cc-fill` class to the tag itself, not just its ancestors — the list resolves an internal `height: 100%` and does not size itself |
+| Whole surface runs past the viewport / clipped, on a **routed** page only | `<cometchat-error-boundary>` is the template root and ships **no** `:host` sizing, so a `height: 100%` shell under it resolves against nothing | add `cometchat-error-boundary { display: flex; flex-direction: column; flex: 1; min-height: 0; overflow: hidden; }` — it is styled by ELEMENT, not by a class. Symptom hides when the shell uses `100dvh` (viewport-relative), appears the moment it becomes `100%` under a routed outlet |
+| `<cometchat-call-logs>` shows "OOPS! Looks like something went wrong" | KIT BUG (5.1.0), not your code: `CallLogsService` builds `new CometChatUIKitCalls.CallLogRequestBuilder()` without awaiting the lazy calls-SDK load, so the accessor is still `null`. Zero network requests are made — it fails before fetching, and Retry does not recover | No host-side fix. Do not hand-roll around it; report it. Note `(error)` will NOT surface it — call-logs has no `error` output (it takes an `onError` INPUT) |
+| Blank space where chat should be | component not in `imports: []` | add the class to that component's `imports` |
+| Blank pane, markup correct | ancestor has no height | `html, body { height: 100% }` + `100dvh` + `min-height: 0` |
+| Lists render but always empty | rendered before `login()` resolved | init → login before bootstrap, or gate the route |
+| Click handler never fires | wrong output name | use the verified name; there is no `cc` prefix |
+| Selected row never highlights | `activeConversation` not bound | bind it to the same state as the message pane |
+| Messages arrive, UI does not update | async SDK callback doesn't repaint (Angular 21 is zoneless by default, so `NgZone.run()` won't help) | write to a signal or call `ChangeDetectorRef.markForCheck()` after the update (core `lifecycle.md`) |
+| Memory grows per route change | no teardown | `takeUntil(destroy$)` + `removeMessageListener(id)` in `ngOnDestroy` |
+| Duplicate messages after navigating | listener registered twice, never removed | register with a stable id; remove on destroy |
+| "Please wait until the previous login request ends." | concurrent `login()` | cache the in-flight promise |
+| `npm install` fails `ERESOLVE` | project on Angular 22 | peer range is `<22.0.0`; use `@angular/cli@21` |
+| Build error: path not exported by package | `@import` of the kit stylesheet | register the full `node_modules/...` path in `angular.json` |
+| Config empty at runtime | credentials in `.env` | Angular reads `environment.ts`, not `.env` |
+| Import will not compile | bare class name used | use the exported `…Component` form |
+| Header shows one chat, messages another | `[user]`/`[group]` mismatch | pass the same subject to header, list and composer |
+| Reply button does nothing | no thread surface rendered | wire a thread panel or hide the affordance |
+| Feature missing, no error | dashboard extension off | enable it for the app the credentials point at |
+| Call buttons render as empty zero-size elements | `uiKit.callsSDK` missing from `initFromSettings` | add `uiKit: { callsSDK: {} }`; installing the package does not enable calling. Check `CometChatUIKit.isCallingEnabled()` |
+| Lists show "OOPS!" on first load and Retry does nothing | first fetch raced login; ConversationsService caches the failure | bootstrap AFTER login resolves; give the user a retry that remounts the component |
+| Calls never ring | listener not at app root, or calls SDK absent | mount `<cometchat-incoming-call>` at root; install the calls SDK |
+| Calls fail on a LAN IP | `getUserMedia` needs a secure context | use HTTPS or localhost |
+| `window is not defined` | SSR running browser code | guard with `isPlatformBrowser` |
+| Dropdown clipped | ancestor `overflow: hidden` or `transform` | remove it from the chain |
+| Layout jumps when data loads | box sizes to content | pin the height so loading and loaded share one box |
+
+## Where the docs contradict this skill
+One entry above still disagrees with `{DOCS_BASE}/ui-kit/angular/overview.md`, and this skill is right because it is verified against the published package:
+- **Angular 22** — the docs list it as supported; the peer range excludes it and `npm install` hard-fails. Do not follow the docs here, and never `--force` past it.
+
+Also verify against the installed package:
+- **`@cometchat/cards-angular`** — required since 5.1.0. (The overview's peer list now lists it — corrected upstream, verified against cometchat/docs, 2026-09-09.)
+
+If a fix in this table seems to contradict a guide, check the installed package before changing course.
+
+## When the table does not cover it
+1. **Confirm the symbol is real.** The exported class name, not the docs title.
+2. **Fetch the component's docs page** (`core/references/docs-map.md`) and compare every input you pass.
+3. **Check the browser console for a CometChat error code** before assuming it is a UI problem.
+4. **Raise the log level**: `CometChatUIKit.setLogLevel(...)`.
+5. **Reduce to the golden path** from `core`. If that works, the fault is in your composition; if it does not, it is setup.
+
+## Verify it works
+A fix is done when the symptom is gone **and** you can say which of the four silent-failure causes it was. If you cannot name the cause, the fix is a coincidence and it will come back.
+
+Re-check after any fix: chat renders with real data · clicking a conversation opens it · sending a message appears immediately · a second browser receives it live · no console errors · nothing collapsed to zero height.
+
+## What NOT to do
+- Do not `--force` or `--legacy-peer-deps` past an `ERESOLVE` — you install an untested combination and the failure moves somewhere harder to find.
+- Do not add `!important` to fight the kit's styles — a token is not applying because the stylesheet is not registered.
+- Do not rebuild a component by hand because an affordance looks broken. It is nearly always a missing input or an unsized container.

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

@@ -0,0 +1,188 @@
+---
+name: cometchat-flutter-v5-sdk
+description: "Add voice & video calling to any Flutter app FROM SCRATCH with the headless CometChat Calls SDK v5 (`cometchat_calls_sdk`, pub.dev) — no UI Kit. init→login→generateCallToken→joinSession, which hands back a Flutter `Widget?` you mount in your tree; CallSession listeners, in-call actions (mute/video/layout/record/PiP/raise-hand), meet-style session rooms AND 1:1 ringing (Chat SDK signaling + Calls SDK media). Triggers: 'add calling from scratch flutter', 'standalone video call dart', 'headless calls sdk flutter', 'build my own call screen flutter', 'meeting room join by session id flutter', 'one-on-one ringing call without uikit flutter'."
+license: "MIT"
+compatibility: "Flutter >=2.5.0, Dart >=2.17.0 <4.0.0 · Android minSdk 26 (Android 8.0) · iOS 15.1. cometchat_calls_sdk ^5.0.3 — resolves to 5.0.7, which this skill is verified against. 1:1 ringing also needs cometchat_sdk v5 (>=5.0.6; the pinned harness resolves 5.0.7 — the signaling symbols are identical across both) for signaling."
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat calls sdk v5 headless voice video webrtc dart flutter calling standalone"
+---
+
+> **Ground truth:** `cometchat_calls_sdk` **5.0.7 from pub.dev** + catalog `flutter-calls-v5.json` (the closed symbol list — 59 COMPILER-VERIFIED symbols; every type below is in it). Catalog built from the PUBLISHED package; at 5.0.7 it matches the `calls-core` monorepo exactly — but **never infer that from a version string** (`references/docs-map.md` § "Upstream"). Official docs: `/calls/flutter/**` = **v5** · Docs MCP. Fetch exact `SessionSettings` fields, event names and signatures from the docs (`references/docs-map.md`) — never memory. **⚠️ The live pages carry ~56 symbols that DO NOT COMPILE, including the entire documented token flow — see "Doc corrections" below; prefer THIS skill's names over the page's.** **APPEND to the user's app — additive wiring only.** This is the HEADLESS path (no UI Kit); for the prebuilt drop-in call UI use `cometchat-flutter-v6-calls` instead.
+
+## Companion skills (read first)
+- **Standalone/headless entry** — this skill owns its own package (the Calls SDK) and has no `-core` sibling; self-contained for meet-style calling.
+- **For 1:1 RINGING only** it also drives the **Chat SDK** (`cometchat_sdk` v5) for signaling — signatures fetched via `references/docs-map.md` (§ "1:1 RINGING"). It does NOT depend on the Flutter UI Kit.
+- **Prefer the UI Kit instead?** If the app also wants chat and a prebuilt call UI, use `cometchat-flutter-v6-core` + `cometchat-flutter-v6-calls` — not this skill.
+
+## Use this skill when
+"add calling from scratch / without the UI Kit", "standalone voice/video on Flutter", "build my own call screen", "headless calls SDK", "meeting-room join by session id", "one-on-one ringing". 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-flutter-v6-calls`.
+
+## Prerequisites & install
+```yaml
+# pubspec.yaml
+dependencies:
+  cometchat_calls_sdk: ^5.0.7   # verified against 5.0.7
+```
+then `flutter pub get`.
+
+**1:1 ringing additionally needs the Chat SDK** (`cometchat_sdk` v5) for signaling.
+
+**Permissions — REQUIRED or the call dies on the first permission prompt.**
+- `android/app/src/main/AndroidManifest.xml`: `INTERNET`, `CAMERA`, `RECORD_AUDIO`, `MODIFY_AUDIO_SETTINGS`, `ACCESS_NETWORK_STATE`. On **API 23+ you must ALSO request camera + mic at runtime** — the manifest alone is not enough, and this is the single most common "the SDK is broken" report on Android.
+- `ios/Runner/Info.plist`: `NSCameraUsageDescription` + `NSMicrophoneUsageDescription`.
+- Android **`minSdkVersion 26`**, iOS **`platform :ios, '15.1'`** — the real 5.0.7 floors. **The docs say 24 and iOS 12; both fail at BUILD time.** iOS moved 13.0 → 15.1 *in 5.0.7*, so an app can break on a routine `pub upgrade`.
+
+**Credentials:** App ID · Region · Auth Key (dev only), via the CLI — `npx @cometchat/skills-cli@3 auth login` → `provision use --app-id <id> --json` (`@3` pins the CLI major that matches the v5 skills). Mint **auth tokens server-side** for production; never ship the Auth Key.
+
+## Init & login ordering (BAKED — invariant)
+Init (once, must succeed) → `CometChatCalls.login(...)` → then `generateCallToken` / `joinSession` / listeners. Nothing joins before init+login resolve. `CometChatCalls.isInitialized` is the guard.
+
+- **DEFAULT to `CometChatCalls.initFromSettings(onSuccess:, onError:)`** — the ai-agent / telemetry-attributed path (persists `integrationSource="ai-agent"`).
+
+  <!-- STOPGAP: source-derived (calls-core/calls-sdk-flutter), NOT in the public docs.
+       `initFromSettings` is `@nodoc` and ai-agent-only. DOCS-BACKLOG F4/D4 closed it WONTFIX —
+       it is to STAY hidden, so this stopgap is permanent, not pending a docs fix. -->
+  It takes **no settings argument**: it reads `cometchat-settings.json` through **`rootBundle`**, so the file must sit at the **project root** *and* be registered as a Flutter asset:
+  ```yaml
+  flutter:
+    assets:
+      - cometchat-settings.json
+  ```
+  Root keys `appId` + `region`; optional `callsSDK` → `adminHost`/`clientHost`/`callsHost`. **No Auth Key — the Calls SDK reads nothing else from this file** (the key is a `login()` argument). Registering it under `flutter: assets:` is the ONLY step; no Xcode or Gradle change, because it is read through `rootBundle`. Miss the `assets:` entry and init fails with settings-file-not-found — a quiet callback, not a crash.
+
+- **Fallback (public-doc path):**
+  ```dart
+  CallAppSettings s = (CallAppSettingBuilder()..appId = appId..region = region).build();
+  CometChatCalls.init(s, onSuccess: (String m) {}, onError: (CometChatCallsException e) {});
+  ```
+  Note the **Dart cascade** (`..appId =`) — these are **fields, not `setX()` methods**. `CallAppSettingBuilder` is singular (no `s`).
+- ⚠️ **Never do both.** A builder init AFTER `initFromSettings` re-attributes the app to `"manual"` and the ai-agent telemetry is lost.
+- **Login:** `CometChatCalls.login(uid:, authKey:, onSuccess:, onError:)` (dev) or `CometChatCalls.loginWithAuthToken(authToken:, onSuccess:, onError:)` (production). Check `await CometChatCalls.getLoggedInUser()` first — it returns `Future<User?>` and the SDK keeps the session, so logging in twice is wasted work. **Both `onSuccess` callbacks hand you a NULLABLE `User?`** — the docs dereference it unguarded; do not copy that.
+
+## Two build modes (BAKED — the router picks one)
+- **Meet-style (session room)** — Calls SDK ONLY, no Chat SDK. Everyone joining the same session id lands in the same call.
+- **1:1 ringing** — Chat SDK signals, Calls SDK carries media. Needs `cometchat_sdk` v5 as well. Fetch signatures via `references/docs-map.md` § "1:1 RINGING".
+
+## ⚠️ The Flutter fork: `joinSession` returns a WIDGET
+Every other platform mounts the call into a container you hand it. **Flutter hands the call back to
+you as a `Widget?`** and mounts nothing:
+```dart
+Widget? _callWidget;
+
+CometChatCalls.joinSession(
+  sessionId: sessionId,
+  sessionSettings: settings,
+  onSuccess: (Widget? w) => setState(() => _callWidget = w),   // ← THIS is the render step
+  onError: (CometChatCallsException e) { /* surface it */ },
+);
+
+@override
+Widget build(BuildContext c) => Scaffold(body: _callWidget ?? const CircularProgressIndicator());
+```
+An emit that ignores the `onSuccess` argument **joins the call successfully and shows nothing** — audio flows, no video, no controls. It reads as a broken SDK and it is the #1 Flutter-specific failure. There is no container parameter and no zero-bounds trap; there is only "did you put the widget in the tree".
+
+## SDK method map (BAKED closed list — from the catalog; signatures → FETCH from docs)
+- **Lifecycle:** `CometChatCalls.initFromSettings` · `CometChatCalls.init` · `CallAppSettingBuilder` → `CallAppSettings` · `CometChatCalls.isInitialized` · `login` · `loginWithAuthToken` · `logout` · `getLoggedInUser` → `User?`
+- **Session:** `CometChatCalls.generateCallToken(sessionId, …)` → `CallToken` · `joinSession(…)` → `Widget?` · `SessionSettingsBuilder` → `SessionSettings` · `SessionType`
+- **⚠️ TWO join paths, both real in 5.0.7** — pick one: `generateCallToken(sessionId)` → `joinSession(callToken:sessionSettings:)`, **or** `joinSession(sessionId:sessionSettings:)` directly.
+- **In-call actions — on `CallSession.getInstance()`, for CUSTOM controls ONLY** (the returned widget already renders them; see pitfall #1): `leaveSession` · `muteAudio`/`unMuteAudio` · `pauseVideo`/`resumeVideo` · `setLayout` · `setAudioModeType` · `switchCamera` · `raiseHand`/`lowerHand` · `startRecording`/`stopRecording` · `startScreenShare`/`stopScreenShare`/`toggleScreenShare` · `pinParticipant`/`unPinParticipant` · `muteParticipant` · `pauseParticipantVideo` · `enablePictureInPictureLayout`/`disablePictureInPictureLayout` · `enterPipMode`/`isPipSupported` · `setChatButtonUnreadCount` · `isCallSessionActive`
+  - **Toggles** (Flutter-only, no iOS analogue): `toggleMuteAudio` · `togglePauseVideo` · `toggleCameraSource` · `toggleRaiseHand`
+  - **Aliases** for the same actions: `endCallSession` · `startCallRecording`/`stopCallRecording` · `setCallLayoutType`
+  - **Settings panels:** `hideSettingsPanel` · `openCallSettingsPanel` · `openVirtualBackgroundSettingsPanel`
+  - **State getters (read, don't track):** `isAudioMuted` · `isVideoPaused` · `isHandRaised` · `isRecording` · `isScreenSharing` · `isTranscribing`
+- **Listeners (on `CallSession.getInstance()`; four are add/remove, `LayoutListeners` is a single-slot property):** `SessionStatusListeners` · `ParticipantEventListeners` · `MediaEventListeners` · `ButtonClickListeners` · `LayoutListeners`
+- **Call logs:** `CallLogRequestBuilder` (top-level; **FIELDS, no `setX()`**) → `CallLogRequest` → `fetchNext`/`fetchPrevious` → `CallLog` (+ `CallUser`/`CallGroup`/`CallEntity`)
+- **Background:** `CometChatOngoingCallService.launch()` / `.abort()` — Android foreground service, no-op on iOS
+- **Enums:** `AudioMode` (`.speaker`/`.earpiece`/`.bluetooth`) · `SessionType` · `LayoutType` (`.tile`/`.spotlight`/`.sidebar`) · `CameraFacing`
+
+> A curated highlight, **NOT the full surface**. The authoritative closed list is the **catalog** (59 symbols, each proven by a `flutter analyze` probe). A symbol is real **iff it is in the catalog** — confirm there, then fetch its signature from the page in `references/docs-map.md`.
+
+## Listener lifecycle (BAKED)
+**All five listener types are `abstract class`es you IMPLEMENT — they are NOT constructible.**
+The live docs build every one of them with named callbacks
+(`SessionStatusListeners(onSessionJoined: () {…})`); an abstract class cannot be instantiated, so
+none of those examples compile. `flutter analyze` reports `instantiate_abstract_class`.
+```dart
+class _Status extends SessionStatusListeners {
+  @override void onSessionJoined() { /* ... */ }
+  @override void onSessionTimedOut() { /* distinct from onSessionLeft — handle BOTH */ }
+  // `extends` instead of `implements` and the other four inherit their no-op bodies.
+}
+
+final _status = _Status();                                       // hoist into a FIELD
+CallSession.getInstance()?.addSessionStatusListener(_status);     // BEFORE joining
+// teardown:
+CallSession.getInstance()?.removeSessionStatusListener(_status);  // the SAME instance
+CallSession.getInstance()?.leaveSession();
+```
+- Every method already has a no-op body, so **`extends` lets you override only what you need**; `implements` obliges you to write them all.
+- **`remove*Listener` takes the object you added.** Constructing a fresh listener to remove one is a no-op that silently leaks the original — and it is what the live docs show (D4). Hoist into a field; there is no other shape in which removal works.
+- **⚠️ Registration names do NOT match the type names** — full table in `references/docs-map.md`. Two you cannot guess: `MediaEvent**Listeners**` registers via `addMediaEvent**s**Listener`, and **`LayoutListeners` has no add/remove at all** — it is a single-slot `layoutListener = l` setter, cleared with `= null`.
+- **`CallSession.getInstance()` is never actually null** — the singleton is eagerly built, so registering BEFORE `joinSession` really does attach (certified: `onSessionJoined` fires). The type is still `CallSession?`, so keep `?.`; use `isCallSessionActive()` to test for a live session.
+- **`ButtonClickListeners` callbacks fire alongside the SDK's own action and do NOT suppress it.** Reacting to `onLeaveSessionButtonClicked` must NOT also call `leaveSession()` — the SDK is already leaving; doing both double-leaves. Use it to run `CometChat.endCall(sessionId)` on the ringing path.
+- **`Participant` has TWELVE fields, all nullable:** `uid` · `name` · `avatar` · `mid` · `state` · `isJoined` · `deviceId` · `joinedAt` · `leftAt` · `totalAudioMinutes` · `totalVideoMinutes` · `totalDurationInMinutes`. **No mute/pin/hand/share flags** — the seven the docs' "Participant Object Reference" lists (`pid`/`role`/`audioMuted`/`videoPaused`/`isPinned`/`isPresenting`/`raisedHandTimestamp`) do NOT exist and do not compile (see `doc-corrections.md`); accumulate that live state from `ParticipantEventListeners`, as iOS must. Prefer `onParticipantListChanged`, which delivers the WHOLE list. (`Participants`, plural, is a `@Deprecated` typedef alias of `Participant`.)
+
+## Least-code recipe (meet-style — ORDER, not signatures)
+```dart
+// Fetch every signature/field from references/docs-map.md. This is the ORDER, which is the part that bites.
+import 'package:cometchat_calls_sdk/cometchat_calls_sdk.dart';
+
+1. CometChatCalls.initFromSettings(onSuccess:, onError:)   // ai-agent default; cometchat-settings.json as a Flutter ASSET
+2. CometChatCalls.login(uid:, authKey:, onSuccess:, onError:)   // or loginWithAuthToken in production
+3. final settings = (SessionSettingsBuilder()..setDisplayName(name)..setType(SessionType.video)).build();
+4. CallSession.getInstance()?.addSessionStatusListener(_status);   // register BEFORE joining
+5. CometChatCalls.joinSession(sessionId:, sessionSettings:, onSuccess: (Widget? w) => setState(() => _call = w), onError:)
+   //   or: generateCallToken(sessionId) -> joinSession(callToken:sessionSettings:)
+6. // return _call from build() — NOTHING renders until you do
+7. // NO control buttons needed — the returned widget ALREADY renders mute/video/leave.
+8. // teardown -> remove each listener (same instance); CallSession.getInstance()?.leaveSession()
+```
+
+## Backgrounding & call notifications → `references/platform-notes.md`
+Two things that are NOT on the join path and are easy to get wrong:
+- **Backgrounding** — Android kills a call the moment the app backgrounds unless
+  `CometChatOngoingCallService.launch()` holds a foreground service (`.abort()` on teardown).
+  **Flutter-only**; both calls are safe no-ops on iOS. The manifest permissions are not optional.
+- **Ringing a closed app** — **there is no first-party CometChat Flutter push package** (iOS has
+  one; Flutter does not), and **no symbol in this skill's catalog implements it**. It is FCM on
+  Android and APNs/PushKit/CallKit on iOS, wired by the app. Needs a dashboard push provider and a
+  **physical device**. An emit naming a `cometchat_push_notifications` Flutter package invented it.
+
+## Doc corrections (⚠️ the live pages do not compile — full table: `references/doc-corrections.md`)
+**23 classes of symbol** on `/calls/flutter/**` fail `flutter analyze` against 5.0.7. Read
+`references/doc-corrections.md` before copying off a page. The two that bite hardest:
+
+| The docs write | It does not compile — use |
+|---|---|
+| `generateToken(sessionId: …)` → `CallToken` (13 pages) | **`generateCallToken(sessionId, onSuccess:, onError:)`** → `CallToken`. `generateToken` is `@Deprecated`, takes two POSITIONAL args, and yields `GenerateToken`. **No page mentions `generateCallToken` at all** |
+| `Participant.pid` / `.role` / `.audioMuted` / `.videoPaused` / `.isPinned` / `.isPresenting` / `.raisedHandTimestamp` | **None exist.** `Participant` has 7 fields; track the rest from events |
+
+Docs PR cometchat/docs#492 fixes the first seven classes (56 → 3 analyzer errors). **Five more —
+including the abstract-listener one — were found by running `flutter analyze` over this skill's
+own harness AFTER #492 was open, and are not in it.** 12 fences on those pages parse in no shape
+and were never machine-checked, so the table is a floor, not a total.
+
+## Common pitfalls (BAKED)
+- **Forgetting to mount the returned widget (the #1 Flutter mistake)** — `joinSession` renders nothing itself. Store the `Widget?` from `onSuccess` in State and return it from `build()`.
+- **Don't duplicate the built-in call controls (the #1 mistake everywhere else).** The joined widget renders a COMPLETE call UI — mute, camera, layout, participants, leave. Do NOT add your own buttons around it. The `CallSession.getInstance()` action methods are for CUSTOM controls ONLY — reach for them **just when the user EXPLICITLY asks** to replace the defaults, and hide the built-ins first via the `..hide*Button` setters on `SessionSettingsBuilder`. To merely REACT to the built-in leave button, use `ButtonClickListeners(onLeaveSessionButtonClicked:)` — do not add a second button.
+- **Removing a listener you did not keep** — construct once into a field; `remove*Listener` matches by instance.
+- **`User` is exported by BOTH barrels** — ringing imports both SDKs; `ambiguous_import` until one hides it (`… hide User;`). No page says so.
+- **Ringing teardown needs BOTH SDKs** — `leaveSession()` ends your media, `CometChat.endCall(sessionId)` tells the peer and completes the log. Only the first, and the peer still thinks the call is live.
+- **There is no `cancelCall`** — cancel your own outgoing call with `rejectCall(sessionId, CometChatCallStatus.cancelled)`.
+- **Manifest permissions without the runtime request** — on Android 6+ the manifest alone grants nothing; request camera/mic before joining or the call is black and silent.
+- **`minSdkVersion` left at Flutter's default** — the floor is **26** (docs say 24), in `android/app/build.gradle.kts` on current Flutter, not `android/build.gradle`.
+- **iOS Simulator on Apple Silicon:** `CometChatWebRTC` excludes arm64, so the app builds x86_64 — fine on an iOS 18 simulator (Rosetta), **impossible on iOS 26+**. Device or iOS 18 sim; details in `references/platform-notes.md`.
+- **`cometchat-settings.json` not in `flutter: assets:`** — `initFromSettings` fails with settings-file-not-found. It is a *quiet* error callback, not a crash. Registering the asset is the whole job; no Xcode step.
+- **Double init** — `init` after `initFromSettings` silently re-attributes telemetry to `"manual"`.
+- **Handling `onSessionLeft` but not `onSessionTimedOut`** — idle timeout (default **300s**, `0` disables) fires a DIFFERENT callback; miss it and the user sits on a dead call screen.
+- **Emitting an API Flutter lacks** — no presentation mode, no first-party push package. Say so rather than emitting code that cannot resolve. The two PiPs are also different calls: `enablePictureInPictureLayout()` is the in-app layout, `enterPipMode()` is Android system PiP.
+- **Screen share — the control methods DO ship (docs lag them).** `CallSession.getInstance()` has real `startScreenShare()`/`stopScreenShare()`/`toggleScreenShare()` + an `isScreenSharing` getter (barrel-reachable in 5.0.7; the method channel invokes a native `startScreenShare` and web routes to `getDisplayMedia`), and `hideScreenSharingButton` defaults to **`false`** so the built-in button is visible. So an emit calling `startScreenShare()` COMPILES and dispatches — do NOT tell the user local screen share is impossible or "invented." The **`/calls/flutter/screen-sharing` DOC page still says "receive-only"** — it documents only the RECEIVE side (`onParticipantStartedScreenShare`, `participant.isPresenting`, viewing a web participant's share); the shipped local-share control API is undocumented there. Reflect the shipped methods, and note the page lags them.
+- **Joining before init+login resolve** — chain from the success callbacks.
+- **Assuming a signature** — event names, `SessionSettings` fields and action params are FETCHED from docs, never guessed.
+
+## Verify it works
+- **Tier-1 catalog:** every `cometchat_calls_sdk` symbol emitted appears in `flutter-calls-v5.json` (`node test-suite/scripts/verify-catalog.mjs --family flutter-calls-v5`).
+- **Tier-2 compile:** the emit analyzes clean against the installed `cometchat_calls_sdk` (5.0.7) with `flutter analyze` in `test-suite/harness/flutter-calls`.
+- **Tier-3 smoke:** the round-trip (init→login→generateCallToken→join→**widget-mounted**→leaveSession) via the pack's dev calls-smoke harness (internal QA, not shipped) — **certified on a physical Android device**. **Ringing runs as TWO concurrent devices**, one process per role, and only counts if both succeed on the SAME session id — see `references/docs-map.md` § "1:1 RINGING".

package/skills/cometchat-flutter-v5-sdk/references/doc-corrections.md

@@ -0,0 +1,55 @@
+# Doc corrections — Flutter Calls SDK v5
+
+Every row below is **verified against the shipped `cometchat_calls_sdk 5.0.7`**, by compiling the
+documented shape and reading the analyzer's verdict (and, for the
+ringing rows, `cometchat_sdk 5.0.6`). Where a live page under `/calls/flutter/**` disagrees with
+this file, **this file wins** — the page does not compile.
+
+| The docs write | It does not compile — use |
+|---|---|
+| `CometChatCalls.generateToken(sessionId: …)` returning a `CallToken` (the token flow on 13 pages) | **`CometChatCalls.generateCallToken(sessionId, onSuccess:, onError:)`** → `CallToken`. `generateToken` is `@Deprecated` ("auth token is now managed internally after `login()`"), takes **two positional** args, and yields **`GenerateToken`** — the pages paired the deprecated name with the replacement's callback type, so it type-errors either way. **No page mentioned `generateCallToken` at all** |
+| `CometChatCalls.SessionSettingsBuilder()` (23×, 13 pages) | **`SessionSettingsBuilder()`** — a top-level class, not a member of `CometChatCalls` |
+| `SessionStatusListener` / `MediaEventsListener` / `ParticipantEventListener` / `ButtonClickListener` / `LayoutListener` (34×, 16 pages) | **All five are PLURAL types**: `SessionStatusListeners`, `MediaEventListeners`, `ParticipantEventListeners`, `ButtonClickListeners`, `LayoutListeners`. Note `MediaEvent**Listeners**` but `addMediaEvent**s**Listener` — the type and the method pluralise differently |
+| `removeSessionStatusListener()` with no argument, next to an inline-constructed listener | **`remove*Listener(theSameInstance)`** — hoist the listener into a field first; an inline listener can never be removed |
+| `callLog.sessionID` | **`callLog.sessionId`** — lowercase `d` |
+| `CometChatConstants.RECEIVER_TYPE_USER` etc. (ringing) | **`CometChatReceiverType.user` / `CometChatCallType.video` / `CometChatCallStatus.cancelled`** — `CometChatConstants` does not exist; these live in the **Chat SDK** |
+| `onSuccess: (User user)` on `login` / `loginWithAuthToken` | **`(User? user)`** — nullable; the pages dereference it unguarded |
+| `CallSession.getInstance().x` | **`CallSession.getInstance()?.x`** — it returns `null` with no active session |
+| `setAudioMode(...)` as a `CallSession` action | **`setAudioModeType(AudioMode.speaker)`** on the session; `..setAudioMode(...)` is the **builder** setter. Same concept, two different names on two different objects |
+| `unpinParticipant(participant)` | **`unPinParticipant()`** — capital `P`, and it takes **no argument**. The other three (`muteParticipant`/`pauseParticipantVideo`/`pinParticipant`) take a `uid` **String**, not a `Participant` |
+| `CallLogRequest.CallLogRequestBuilder().setLimit(30).setSessionType("video")` (call-logs, recording, migration-guide) | **Three errors in one line.** `CallLogRequestBuilder` is **top-level** (no `CallLogRequest.` prefix); it has **no `setX()` methods at all** — public FIELDS, so cascaded *assignments*: `(CallLogRequestBuilder()..limit = 30..callType = "video").build()`; and the field is **`callType`**, not `sessionType`. Note this is the OPPOSITE shape to `SessionSettingsBuilder`, which does take cascaded setter calls |
+| `Android: Minimum API Level 24 (Android 7.0)` / `iOS: Minimum iOS 12` (overview) | **`minSdkVersion 26`** (Android 8.0) in `android/build.gradle` — wrong for every 5.0.x — and **iOS 15.1** in the 5.0.7 podspec (it was 13.0 in 5.0.6). Both documented floors are too low and both fail at BUILD time. Since the page pins `^5.0.3`, a reader resolves 5.0.7 and needs 15.1 |
+| `recording.recordingURL` and the `recordingURL` property row (recording, call-logs) | **`recordingUrl`** — lowercase `rl`. `Recordings` has exactly four fields: `rid`, `recordingUrl`, `startTime`, `endTime`, plus `duration` |
+| `Recording` / `CallStatus` / `CallCategory` / `CallDirection` as Dart types | **`Recordings`** (plural) is the type; the three enums **do not exist on Flutter** — those call-log filters take plain **Strings** (`"missed"`, `"call"`, `"incoming"`) |
+| `SessionStatusListeners(onSessionJoined: …)` and the other four, built with named callbacks (16 pages) | **All five are `abstract class`es — they cannot be constructed.** `class X extends SessionStatusListeners { @override void onSessionJoined() {…} }`, then pass an instance. Every method already defaults to a no-op. Renaming them to the plural (docs#492) fixed the NAME; the constructor-call shape is still wrong |
+| `CometChat.addCallListener(id, CallListener(onIncomingCallReceived: …))` (ringing) | **`CallListener` is a `mixin`** — also not constructible. `class X with CallListener { @override void onIncomingCallReceived(Call c) {…} }`, then pass an instance |
+| `Call(receiverID, receiverType, callType)` (ringing) | **`Call` takes NAMED required params** — `Call(receiverUid: …, receiverType: …, type: …)`. It has no positional parameters at all, and the third one is `type`, not `callType` |
+| `joinCallSession(call.sessionId!)` (ringing) | **`Call.sessionId` is `String?`** — the force-unwrap turns a signal that arrived without a session into a crash instead of a handled error |
+| `AppSettingsBuilder()..region = …` by analogy with `CallAppSettingBuilder` (ringing) | **`AppSettingsBuilder` uses chained `setX()`** — `..setRegion(…)`, `..setAutoEstablishSocketConnection(true)`. The two builders sit in the same file and take different shapes |
+| — (no doc page states it) | **`CometChatCalls.init` is a *plain* init, not the ai-agent one.** `initFromSettings` is `@nodoc` and undocumented; see the STOPGAP note above |
+| `CallSession…addLayoutListener(l)` / `removeLayoutListener(l)` (events, migration-guide) | **Neither method exists.** `CallSession` has `set layoutListener(LayoutListeners?)` + a getter — one slot, cleared with `layoutListener = null` |
+| `CometChat.initiateCall(call, timeout: 30, …)` and two parameter tables documenting it (ringing) | **There is no `timeout` parameter.** `initiateCall` takes the `Call` plus `onSuccess`/`onError`, and the repository beneath it takes only receiver/receiverType/type. The unanswered timeout is server-side; cancel early with `rejectCall(sessionId, CometChatCallStatus.cancelled)` on your own timer |
+| — (no page mentions it) | **`User` is exported by BOTH barrels.** Ringing imports `cometchat_calls_sdk` *and* `cometchat_sdk`; the file fails with `ambiguous_import` until one hides it — `import '…/cometchat_calls_sdk.dart' hide User;` |
+| `Participant.pid` / `.role` / `.audioMuted` / `.videoPaused` / `.isPinned` / `.isPresenting` / `.raisedHandTimestamp` — the "Participant Object Reference" on `actions` | **None of those seven exist.** `Participant` has TWELVE real fields, all nullable: `uid` · `name` · `avatar` · `mid` · `state` · `isJoined` · `deviceId` · `joinedAt` · `leftAt` · `totalAudioMinutes` · `totalVideoMinutes` · `totalDurationInMinutes` (source: `lib/src/model/participants.dart` 5.0.7; `Participants` plural is a `@Deprecated` typedef alias). Track live mute/pin/hand/share state from the `ParticipantEventListeners` callbacks — the same way iOS must. This skill previously repeated the docs' phantom list *and added emphasis*, then over-corrected to a WRONG "exactly seven" count — a closed list that isn't is worse than no list; the real closed list is the twelve above |
+| `region` is "`us`" or "`eu`" (setup's `CallAppSettingBuilder` table) | **`in` is also live** — a real provisioned app uses it. A reader following the table concludes their credentials are wrong |
+
+
+
+The first seven rows are fixed in docs PR cometchat/docs#492. **The five after them are NOT** —
+they were found by running `flutter analyze` over this skill's own harness, after #492 was
+already open, and the abstract-listener one is the largest single defect on the tree: #492
+renamed those five types to their real plural spelling but left every one of them being
+CONSTRUCTED, which still does not compile. Until a follow-up lands, until it merges the live `/calls/flutter/**`
+pages still carry them. **12 fences on those pages parse in no shape and were never machine-checked**,
+so treat this table as a floor, not a total — the abstract-listener class was itself found
+outside the gate. Re-check when #492 and its follow-up land.
+
+---
+
+## Drift warning
+
+The preview host is being fixed under this table. As of the last check, `session-settings` and
+`join-session` already carry the top-level `SessionSettingsBuilder()`, and `setup` already pins
+`^5.0.7` — so the occurrence counts above (`23×, 13 pages`) **overstate what is still broken**.
+The rows remain correct about what does and does not compile; treat the counts as historical.
+Re-probe a page before quoting a number from here.

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

@@ -0,0 +1,211 @@
+# docs-map — Flutter Calls SDK v5 (`/calls/flutter/**`)
+
+**Doc channel = the CometChat Docs MCP.** Use `search_cometchat_docs` / `fetch_cometchat_doc_page` /
+`get_cometchat_implementation_bundle` when they are connected — they are the intended path and they
+serve production docs for you.
+
+**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` (below).
+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 the installed Dart package at authoring
+> time for SIGNATURES (the catalog is for EXISTENCE, the docs are for signatures).
+
+## The convention — Calls v5 lives at the UNVERSIONED root `/calls/flutter/`
+`DOCS_BASE` + `<path>` + `.md` → raw Markdown (verbatim code + parameter tables).
+```
+Fetch:  {DOCS_BASE}/calls/flutter/overview.md
+```
+> **⚠️ VERSION TRAP.** The **unversioned** `/calls/flutter/**` tree IS **v5**. Legacy
+> `/sdk/flutter/<n>.0/*calling*` pages are the OLD chat-SDK calling surface — never fetch them for a v5
+> build. **Do NOT `search("default calling")`** — search surfaces that stale tree.
+> The **UI Kit** calling page (`/ui-kit/flutter/v5/calling-integration`) is a DIFFERENT product; it is
+> what this skill exists to be the alternative to.
+
+## Page catalog (25 pages)
+| Path | Use it for |
+|---|---|
+| `/calls/flutter/overview` | the init→login→generateCallToken→joinSession sequence and the component model. **⚠️ its Android/iOS floors are BOTH too low — real: minSdk 26, iOS 13.0 (15.1 from 5.0.7)** |
+| `/calls/flutter/setup` | install (the live page now pins `cometchat_calls_sdk: ^5.0.7`; older cached copies said `^5.0.3` — both resolve 5.0.7), Android manifest permissions, iOS `Info.plist`, `CallAppSettingBuilder`, `isInitialized`. **⚠️ its `region` table still says only `us`/`eu` — `in` is also live** |
+| `/calls/flutter/authentication` | **`login` / `loginWithAuthToken` / `logout` / `getLoggedInUser`** — the only page with these, and the error-code table |
+| `/calls/flutter/join-session` | **`generateCallToken` / `joinSession`** and the `Widget?` return. THE page for the Flutter fork |
+| `/calls/flutter/session-settings` | `SessionSettingsBuilder` — every setter and the whole `hide*Button` list |
+| `/calls/flutter/events` | all five listener types + every callback name and parameter. **⚠️ the page CONSTRUCTS all five; they are `abstract class`es and cannot be instantiated — take the callback NAMES from here and the shape from SKILL.md** |
+| `/calls/flutter/actions` | **every in-call `CallSession.getInstance()` action** — mute/pin/layout/audio-mode/raise-hand/PiP, the toggle+alias pairs, the settings panels, the state getters, and the `Participant` field table |
+| `/calls/flutter/ringing` | **1:1 RINGING — the WHOLE flow, both sides.** Fetch this DIRECTLY (see below) |
+| `/calls/flutter/call-logs` | `CallLog` fields + pagination. **⚠️ its builder shape is wrong three ways — see SKILL.md's corrections; the real form is `(CallLogRequestBuilder()..limit = 30).build()`** |
+| `/calls/flutter/call-layouts` | `LayoutType` values (`.tile` / `.spotlight` / `.sidebar`) and layout switching |
+| `/calls/flutter/audio-modes` | `AudioMode` values and routing |
+| `/calls/flutter/recording` | recording start/stop, `enableAutoStartRecording`, `Recordings`, prerequisites. **⚠️ nothing here covers TRANSCRIPTION, which shipped in 5.0.7 — there is no page at all; use `references/transcription.md`** |
+| `/calls/flutter/participant-management` | roster + moderation (mute / pause video / pin) |
+| `/calls/flutter/custom-participant-list` | building your own roster UI |
+| `/calls/flutter/custom-control-panel` | replacing the built-in controls — **hide first, then drive** |
+| `/calls/flutter/screen-sharing` | the RECEIVE side — the share EVENTS (`onParticipantStartedScreenShare`) and (phantom) `participant.isPresenting`. **⚠️ the page says "receive-only," but 5.0.7 ALSO ships local-share CONTROL methods on `CallSession` (`startScreenShare`/`stopScreenShare`/`toggleScreenShare`/`isScreenSharing`) that the page does NOT document** — see SKILL.md "Screen share" pitfall |
+| `/calls/flutter/raise-hand` | raise / lower / toggle hand, `isHandRaised`, remote `raisedHandTimestamp` |
+| `/calls/flutter/picture-in-picture` | **TWO kinds, pick one** — in-app PiP layout vs Android system PiP (`enterPipMode`) and its manifest flag |
+| `/calls/flutter/idle-timeout` | `setIdleTimeoutPeriod` (default **300**, `0` disables) and `onSessionTimedOut` |
+| `/calls/flutter/background-handling` | **`CometChatOngoingCallService`** — Flutter-only Android foreground service, and its manifest permissions |
+| `/calls/flutter/in-call-chat` | the chat BUTTON (`onChatButtonClicked`, `setChatButtonUnreadCount`) — the chat itself is the UI Kit |
+| `/calls/flutter/share-invite` | `onShareInviteButtonClicked` + the app-side link/deep-link work |
+| `/calls/flutter/voip-calling` | **THE page for `call-voip-push`** — the Android-FCM and iOS-APNs/CallKit paths, separately |
+| `/calls/flutter/migration-guide-v5` | v4→v5 mapping. **⚠️ its "v4" tab shows the OLD API on purpose — do not read those fences as current** |
+| `/calls/flutter/troubleshooting` | common failures |
+
+| Path | Use it for |
+|---|---|
+| `/notifications/flutter-push-notifications-android` | FCM wiring for the Android half of call notifications |
+| `/notifications/flutter-push-notifications-ios` | APNs wiring for the iOS half |
+| `/notifications/push-overview` | dashboard providers — you need one configured before any of it rings |
+
+## 1:1 RINGING — fetch the page DIRECTLY
+`/calls/flutter/ringing` carries the entire two-sided flow and it is the only page with the **Chat SDK**
+signalling signatures. Those symbols (`CometChat.initiateCall` / `addCallListener` / `CallListener` /
+`acceptCall` / `rejectCall` / `endCall` / `removeCallListener`, and the `Call` /
+`CometChatCallType` / `CometChatReceiverType` / `CometChatCallStatus` types) belong to
+**`cometchat_sdk` v5** and are deliberately ABSENT from `flutter-calls-v5.json`, which catalogs the
+Calls SDK only. Validate them against the chat SDK's own catalog, not this one.
+
+Three things the page's shape hides:
+- **`User` is declared by BOTH barrels.** `cometchat_calls_sdk` and `cometchat_sdk` each export a `User`, so a file importing both — which ringing forces — fails with `ambiguous_import` until one side hides it: `import 'package:cometchat_calls_sdk/cometchat_calls_sdk.dart' hide User;`.
+- **`CallListener` is a `mixin`, NOT a constructible class.** The page writes `CallListener(onIncomingCallReceived: …)`; a mixin has no constructor, so that does not compile. Use `class X with CallListener { @override … }` and pass an instance. Every method defaults to a no-op, so override only what you need. (Found building this skill's harness — **not** in docs#492.)
+- **There is no `cancelCall`.** Cancelling your own outgoing call is `rejectCall(sessionId, CometChatCallStatus.cancelled)`; rejecting someone else's is the same method with `.rejected`.
+
+**Verifying ringing needs TWO live clients.** One device can prove the wiring compiles and that
+`initiateCall` resolves; it can never prove the callee's `onIncomingCallReceived` fired. The harness
+runs two devices, one process per role, and only reports success when BOTH report it on the SAME
+session id — verified by the pack's dev ringing-smoke harness (internal QA, not shipped).
+
+## STOPGAP — `CometChatCalls.initFromSettings` (intentionally undocumented, ai-agent only)
+<!-- STOPGAP: source-derived from cometchat_calls_sdk 5.0.7 and its upstream in
+     calls-core/calls-sdk-flutter, NOT from a docs page. `initFromSettings` is marked `@nodoc`.
+     Tracked as DOCS-BACKLOG F4, closed WONTFIX by the UI Kit
+     owner on 2026-08-21: it is to STAY hidden. This stopgap is therefore permanent by decision,
+     not pending a docs fix. Everything else in this file comes from the pages above. -->
+```dart
+CometChatCalls.initFromSettings(
+  onSuccess: (String message) { /* ... */ },
+  onError: (CometChatCallsException e) { /* ... */ },
+);
+```
+- **No settings argument.** It reads `cometchat-settings.json` via **`rootBundle.loadString`**.
+- The file lives at the **project root** and MUST be registered as a Flutter asset:
+  ```yaml
+  flutter:
+    assets:
+      - cometchat-settings.json
+  ```
+- Shape: root `appId` (required) + `region` (required); optional `callsSDK` → `adminHost` / `clientHost` / `callsHost`. A host value of the literal string `"null"` is ignored, not applied.
+- Missing file / bad JSON / missing `appId` / missing `region` each fire **`onError` with a distinct code** — none of them throws, so a silent no-call is the symptom.
+- It sets `integrationSource = "ai-agent"`. A plain `CometChatCalls.init` afterwards overwrites that with `"manual"`.
+- **NATIVE FORK:** iOS reads the same filename from `Bundle.main` (Copy Bundle Resources); web passes settings inline with no file.
+
+## Callback shapes (VERIFIED against 5.0.7 — the SDK is INCONSISTENT, do not pattern-match)
+| API | `onSuccess` receives | Returns |
+|---|---|---|
+| `init(callAppSettings, …)` | `String` | `void` (not a Future) |
+| `initFromSettings(…)` | `String` | `Future<void>` |
+| `login(uid:, authKey:, …)` | **`User?`** (nullable) | `void` |
+| `loginWithAuthToken(authToken:, …)` | **`User?`** (nullable) | `void` |
+| `logout(…)` | `String` | `void` |
+| `generateCallToken(sessionId, …)` | `CallToken` | `void` |
+| `generateToken(sessionId, userAuthToken, …)` | `GenerateToken` — **⚠️ `@Deprecated`, two POSITIONAL args, and a DIFFERENT type from `generateCallToken`** | `void` |
+| `joinSession(sessionId:/callToken:, sessionSettings:, …)` | **`Widget?`** | `Future<void>` |
+| `getLoggedInUser()` | — | **`Future<User?>`** (await it; no callbacks) |
+
+Every `onError` receives `CometChatCallsException`. `joinSession` takes **exactly one** of
+`sessionId` or `callToken` — passing neither (or both) fails through `onError`, not by throwing.
+
+## `SessionSettingsBuilder` — every setter, and the five DEFAULT-HIDDEN buttons (5.0.7)
+
+> Presented as a CLOSED list, so it has to be complete: `startAudioMuted` and `startVideoPaused`
+> were missing from it until an isolation test caught them. A closed list that isn't makes a real
+> API look like a phantom — worse than no list. Re-probe before trusting it.
+Setters return the builder, so **either** Dart cascades (`..setType(...)`, what the docs show) **or**
+chaining works. Build with `.build()`.
+
+`setTitle` · `setDisplayName` · `setType(SessionType)` · `setLayout(LayoutType)` ·
+`setAudioMode(AudioMode)` · `setInitialCameraFacing(CameraFacing)` · `setIdleTimeoutPeriod(int)` ·
+`setCaptionLanguage(String)` · `startAudioMuted(bool)` · `startVideoPaused(bool)` ·
+`enableLowBandwidthMode(bool)` · `enableAutoStartRecording(bool)` · `enableAutoStartTranscription(bool)`
+
+`hideControlPanel` · `hideHeaderPanel` · `hideSessionTimer` · `hideLeaveSessionButton` ·
+`hideToggleAudioButton` · `hideToggleVideoButton` · `hideSwitchCameraButton` · `hideAudioModeButton` ·
+`hideChangeLayoutButton` · `hideParticipantListButton` · `hideRaiseHandButton` ·
+`hideScreenSharingButton` · `hideRecordingButton` · `hideShareInviteButton` · `hideChatButton` ·
+`hideTranscriptionButton` · `hideClosedCaptionButton`
+
+> **⚠️ FIVE buttons are HIDDEN BY DEFAULT** — `hideRecordingButton`, `hideShareInviteButton`,
+> `hideChatButton` and, new in 5.0.7, `hideTranscriptionButton` and `hideClosedCaptionButton` all
+> default to **`true`**. Wiring the matching click callback without passing `false` produces a
+> listener that can never fire, and it looks like the events are broken. `setIdleTimeoutPeriod`
+> defaults to **300**; every other `hide*` defaults to `false`.
+
+## Listener registration — the names do NOT match the types
+| Type | Add | Remove |
+|---|---|---|
+| `SessionStatusListeners` | `addSessionStatusListener(l)` | `removeSessionStatusListener(l)` |
+| `ParticipantEventListeners` | `addParticipantEventListener(l)` | `removeParticipantEventListener(l)` |
+| `MediaEventListeners` | `addMediaEvent`**`s`**`Listener(l)` | `removeMediaEvent`**`s`**`Listener(l)` |
+| `ButtonClickListeners` | `addButtonClickListener(l)` | `removeButtonClickListener(l)` |
+| `LayoutListeners` | `layoutListener = l` | `layoutListener = null` |
+
+All five are on `CallSession.getInstance()`, which is **`null` when no session is active** — use `?.`.
+`remove*` matches **by instance**, so the listener must be a retained field.
+
+> **⚠️ `LayoutListeners` is the odd one out.** `CallSession` exposes `set layoutListener(LayoutListeners?)`
+> and its getter — there is **no `addLayoutListener` / `removeLayoutListener`**, so only ONE layout
+> listener exists at a time and it is cleared by assigning `null`. The events page shows the add/remove
+> pair; those methods do not exist.
+
+> **⚠️ All five types are `abstract class`es.** `SessionStatusListeners(onSessionJoined: …)`, the
+> shape every page uses, does not compile — `flutter analyze` reports `instantiate_abstract_class`.
+> Write `class X extends SessionStatusListeners { @override … }` and pass an instance. Every method
+> already has a no-op body, so `extends` lets you override just what you need; `implements` obliges
+> you to write them all.
+
+## ⚠️ Doc corrections — VERIFIED against cometchat_calls_sdk 5.0.7
+The `Doc corrections` table in `SKILL.md` is authoritative; it lists 13 classes of symbol on the live
+pages that do not compile, including **the entire documented token flow** (`generateToken` is
+deprecated, takes positional args, and yields a different type than the pages assign it — while
+`generateCallToken`, the current API, appeared on no page at all).
+
+Fixed in docs PR **cometchat/docs#492** (56 → 3 analyzer errors across 25 pages). Until it merges the
+live pages still carry them. **12 fences on those pages parse in no shape and were never
+machine-checked**, so 3 is a floor, not a total — prefer the skill's names over the page's on any
+disagreement, and re-check this section when #492 lands.
+
+## Upstream — `calls-core/calls-sdk-flutter` (the SDK monorepo)
+
+The Flutter Calls SDK is developed in the **`calls-core` monorepo**, alongside `ios-sdk`,
+`calls-sdk-javascript`, `react-native-sdk` and the shared `calls-sdk-core`. That is where the
+`@nodoc` `initFromSettings` path above was read from, and it is the right place to check when a
+docs page and the installed package disagree.
+
+**As of 5.0.7 the published package and the monorepo dev branch (`dev-v5`, == `release-next`;
+`master-v5` merges it) are byte-identical under `lib/`.** So there is no published-vs-upstream gap
+to carry right now.
+
+> **⚠️ Never infer that from a version string.** Before 5.0.7 shipped, the published package and
+> the monorepo BOTH read `version: 5.0.6` with different contents. Re-diff the trees; do not
+> compare versions.
+
+### 5.0.6 → 5.0.7 (published 2026-09-02)
+
+**Transcription arrived as a complete feature** — and `/calls/flutter` has **no page for it**.
+The skill is the only source; see `references/transcription.md` (a labelled STOPGAP) and
+DOCS-BACKLOG **D3**. Three new barrel-exported types entered the catalog: `Transcript`,
+`TranscriptRequest`, `TranscriptRequestBuilder`.
+
+**iOS floor raised 13.0 → 15.1**, native `CometChatCallsSDK` pin 5.0.0 → 5.0.4. This is breaking
+for consumers on iOS 13/14 and can bite on a routine `pub upgrade`, because `^5.0.3` resolves to
+5.0.7. Android stayed at `minSdkVersion 26` — the docs' "24 / Android 7.0" was never right for any
+5.0.x.
+
+**Six dead enum files were deleted** (`audio_modes`, `avatar_type`, `call_type`, `mode`,
+`video_stream_modes`, `video_stream_positions`). All six were already in the catalog's
+`internalOnlyExcluded` — never reachable from the barrel — so their removal changed nothing here.
+`CallType` is the same phantom skills#183 filed on iOS.