@cometchat/skills 4.4.1 → 5.0.0

package/skills/cometchat-onboarding/references/plan-artifact.md

@@ -0,0 +1,133 @@
+# plan-artifact — the template + the plan-completeness contract
+
+The plan artifact is onboarding's DELIVERABLE. Because an onboarding skill emits no CometChat symbols, its "completeness oracle" is not a symbol catalog — it is this **plan-completeness contract**: the fixed set of sections the plan MUST contain, so every run of onboarding produces the same complete plan shape (not a lucky partial). This mirrors how `contracts.json` fixes the floor for a UI-Kit surface; here the floor is the plan itself. The matching machine-checkable contract lives in `contracts.json` as `onboarding-plan` (kind `plan`).
+
+## The plan-completeness contract — the plan MUST contain all seven
+
+| # | Section | What it fixes | Sourced from |
+|---|---|---|---|
+| 1 | **Discovery summary** | Every beat-1 signal, each a value or explicit `null` — framework · bundler · language · package manager · auth · styling · state · routing · SSR/CSR · existing CometChat · installed UI Kit / `version_conflict` · env file + prefix | repo read (package.json / lockfile / configs / source) |
+| 2 | **Intent → capability map** | The confirmed archetype · modality · scope, TRANSLATED to CometChat capabilities, **each tagged UI Kit component or SDK method** (UI-Kit-first / SDK-fallback — flag SDK-backed features so the core wires them from the SDK docs) | beat-2 answers + `references/archetypes.md` |
+| 3 | **Numbered actions** | The scoped build steps, in order — what the core will do | archetype + scope |
+| 4 | **Files that will change** | The concrete paths/areas the build touches (additive — APPEND, never replace) | discovery + scope |
+| 5 | **Packages** | The exact package(s) to install, with major pins (the core owns exact coordinates) | modality + framework |
+| 6 | **Credential + auth strategy** | Dev Auth-Key vs prod server-minted auth token, CHOSEN from discovery (§archetypes credential heuristic) | `auth` signal |
+| 7 | **Modify-or-approve gate** | An explicit invitation to EDIT or APPROVE — nothing is written before approval | always |
+
+A plan missing any of the seven is **incomplete** — do not present it or hand off. (This is the onboarding analogue of "dropped a contract min_capability".)
+
+## The template (fill every section; keep it concrete, not generic)
+
+```md
+## CometChat integration plan
+
+### 1. What I found (discovery)
+- Framework:      <value | null>
+- Bundler:        <value | null>
+- Language:       <TypeScript | JavaScript>
+- Package mgr:    <npm | pnpm | yarn | bun | null>
+- Auth:           <nextauth | clerk | firebase | auth0 | supabase | custom | null>
+- Styling:        <tailwind | css-modules | mui | styled-components | chakra | null>
+- State:          <redux | zustand | mobx | recoil | context | null>
+- Routing:        <value | null>
+- SSR/CSR:        <ssr | csr | islands | null>
+- Existing CometChat: <yes (uikit <ver>) | no> · version_conflict: <none | detail>
+- Env file/prefix:    <.env / VITE_ | .env.local / NEXT_PUBLIC_ | … | n/a>
+
+### 2. What you want (intent → CometChat capabilities)
+- Archetype: <1:1/marketplace | support | community | full-messenger | embedded>
+- Modality:  <chat | calls | both>
+- Scope:     <smallest surface | full combined app | embedded panel>
+- Theming:   <auto/follow-OS light+dark (default) | fixed light | fixed dark> + <default tokens | match design system | brand palette | custom>
+- → Capabilities: <the archetype's capability list from archetypes.md, e.g.
+  "1:1 conversations · conversation list · message pane (send/receive + attachments) ·
+   a 'Message seller' entry button">
+
+### 3. What I'll do
+1. <install the packages>
+2. <credentials + env (dev Auth-Key OR prod token path — see §6)>
+3. <init → login → render the scoped surface>
+4. <wire the entry point into the existing app (routing/auth/state reuse)>
+5. <match the existing design system>   ← if styling detected
+6. <calls layer + permissions>          ← if modality includes calls
+7. <…scoped to the archetype; smallest correct set>
+
+### 4. Files that will change (additive — nothing replaced)
+- <path/area 1>
+- <path/area 2>
+- <env file>
+(APPEND only — your existing code is not rewritten.)
+
+### 5. Packages
+- <exact package@major> …   (the framework core owns the exact coordinates + pins)
+
+### 6. Credential + auth strategy
+- <Dev Auth-Key path — get moving now; do NOT ship the Auth Key to prod>
+  OR
+- <Prod server-minted auth token wired to <detected auth>: your backend mints a
+  per-user CometChat auth token; frontend logs in with it. Map <app user id> → CometChat UID.>
+(Credentials are fetched by the framework core at build time — it will OFFER to fetch the App ID/Region/Auth Key from the dashboard (loading the CometChat CLI on demand → `provision`) or let you paste them manually, then write the env itself; this section only states the dev-vs-prod strategy, not the fetch method.)
+
+### 7. Approve or edit
+Edit any part of this plan (change the archetype, add calling, narrow scope, switch the
+credential strategy), or approve to start. **Nothing is written until you approve.**
+```
+
+## After approval — the scoped build directive (hand-off, not part of the plan the user sees)
+On approval, hand the framework core a compact directive naming ONLY the scoped surface:
+```
+build-directive:
+  core: cometchat-<family>-core        # the framework core for the detected framework
+  archetype: 1:1/marketplace
+  modality: chat
+  scope: smallest 1:1 surface (message button → conversation ↔ message pane)
+  credentials: dev-auth-key            # from plan §6
+  touch: [src/features/chat/*, src/components/MessageSellerButton.tsx, .env]
+  also-skills: []                      # only what the plan named (calls / customization / patterns …)
+```
+The core then does credentials + build + verify. For a framework with no shipped core (React Native, Vue, Flutter, iOS, Android — NOT React or Angular, which both ship one), DO NOT emit a directive — state the not-yet-built posture and offer the plan as the hand-off spec.
+
+## Worked example (Next.js marketplace, chat only)
+
+```md
+## CometChat integration plan
+
+### 1. What I found (discovery)
+- Framework: Next.js (App Router) · Bundler: Turbopack/Webpack · Language: TypeScript
+- Package mgr: pnpm · Auth: NextAuth · Styling: Tailwind · State: Zustand
+- Routing: App Router · SSR/CSR: ssr · Existing CometChat: no · version_conflict: none
+- Env file/prefix: .env.local / NEXT_PUBLIC_
+
+### 2. What you want (intent → CometChat capabilities)
+- Archetype: 1:1/marketplace · Modality: chat · Scope: smallest 1:1 surface
+- → Capabilities: 1:1 conversations · conversation list · message pane (send/receive + attachments)
+  · unread + presence · a "Message seller" button off the listing page
+
+### 3. What I'll do
+1. Install the React UI Kit + Chat SDK (major-pinned).
+2. Credentials: prod server-minted auth token wired to NextAuth (Auth Key dev-only to start).
+3. Client-only init → login → render the scoped 1:1 surface (App Router client boundary).
+4. Add a "Message seller" button on the listing page → opens the conversation.
+5. Match the Tailwind design tokens (hand to customization).
+
+### 4. Files that will change (additive)
+- src/app/(chat)/… (a client chat route)
+- src/components/MessageSellerButton.tsx
+- src/lib/cometchat/… (init/login helpers)
+- .env.local
+(APPEND only.)
+
+### 5. Packages
+- The resolved family's `kit_package` (+ `sdk_package` / `calls_package` where the row has them),
+  read from `peers.yaml` — plus that kit's required peer deps. Never hardcode one family's packages.
+
+### 6. Credential + auth strategy
+- Prod server-minted auth token: a Next route mints a per-user CometChat auth token from the
+  NextAuth session; the client logs in with it. Map the NextAuth user id → CometChat UID.
+  Dev Auth-Key is fine locally but never shipped.
+
+### 7. Approve or edit
+Edit any part (add calling, widen to groups, change the credential path), or approve to start.
+Nothing is written until you approve.
+```
+On approval → hand off to `cometchat-<family>-core` with the scoped directive above; pull in `customization` (Tailwind match) and `patterns` (Next App-Router client boundary) because the plan named them — nothing else.

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

@@ -0,0 +1,90 @@
+<!-- family-agnostic: per-platform-by-design — this reference IS the per-family table; lint-skills GATE R
+     requires one entry per shipped family, so naming a single family here is the point, not a defect. -->
+
+# Platform specifics — what differs per platform
+
+This gate is framework-agnostic, but several of its beats have a platform-specific answer. The
+entry keeps the neutral rule; the concrete values live here. Load when you have detected the
+platform. **Every family that ships a `-core` in `peers.yaml` has a column below** — a missing
+column means beat 1 gets improvised (`lint-skills.mjs` checks this table against the shipped cores).
+
+## Detection fields (beat 1) — web
+
+| | Web (React) | Web (Angular) |
+|---|---|---|
+| project marker | `package.json` (`react`, no `react-native`/`expo`) | `package.json` (`@angular/core`) + `angular.json` |
+| dependency manager | npm/pnpm/yarn (from the lockfile) | npm/pnpm/yarn (from the lockfile) |
+| build/bundler | `bundler` · `router` · `ssr_strategy` | Angular CLI (`angular.json` builder); `router` = `@angular/router` |
+| UI framework | React | Angular standalone components (kebab-case selectors) |
+| version floor | `framework_version` | Angular 17–21 (the kit's range — `cometchat-angular-v5-core`) |
+| language | TS / JS | TS |
+| credentials file | `.env` (with the framework's env prefix) | `src/environments/environment.ts` (build-time file replacement — NOT `.env`) |
+| existing integration | `@cometchat/chat-uikit-react` in `package.json` | `@cometchat/chat-uikit-angular` in `package.json` |
+
+## Detection fields (beat 1) — mobile
+
+| | iOS (Swift) | Android (Kotlin) | React Native | Flutter |
+|---|---|---|---|---|
+| project marker | `*.xcodeproj` / `*.xcworkspace` / `Package.swift` | `settings.gradle(.kts)` + `app/build.gradle(.kts)` | `package.json` with `react-native` (+ `expo` ⇒ Expo; `app.json`, `metro.config.js`) | `pubspec.yaml` (+ `pubspec.lock`) |
+| dependency manager | **SPM**. A `Podfile` is a DETECTION signal only — CocoaPods distribution is winding down, so never integrate through it | Gradle (Kotlin DSL or Groovy; version catalog if `gradle/libs.versions.toml`) + the Cloudsmith Maven repo | npm/yarn (lockfile); Expo vs bare decides the `patterns` skill (`expo-patterns` / `bare-patterns`) | pub |
+| build/bundler | not applicable — no bundler, no SSR, no routing story | not applicable — record `android_variant` instead (below) | Metro — no bundler/SSR choice | not applicable |
+| UI framework | **UIKit or SwiftUI** — ask if ambiguous; the shipped kit is UIKit | **`android_variant`: `views` (XML Views → `kotlin-*` skills) or `compose` (Jetpack Compose → `compose-*` skills)** — read it from the compose plugin / `androidx.compose` deps; `mixed`/`unknown` ⇒ ask | React Native components | Flutter widgets |
+| version floor | `deployment_target` (the kit's floor is iOS 15.1) | `minSdk` / `compileSdk` / Kotlin / AGP — **UI Kit v6: minSdk 28, compileSdk 36, Kotlin 2.1, AGP 8.9.1**; **headless Calls SDK v5: minSdk 26** (its TRUE transitive floor — the docs overview's 24 fails the manifest merge; `cometchat-android-v5-calls-sdk`). Read the app's `minSdk` in beat 1 and put the bump in the plan | React Native ≥ 0.77 | Flutter ≥ 3.19, Dart ≥ 3.10.1 |
+| language | Swift | Kotlin (Java is the legacy cohort) | TS / JS | Dart |
+| credentials file | `Config/Secrets.xcconfig` → `Info.plist` → `Bundle.main` | `app/src/main/assets/cometchat-settings.json` (**gitignored**; read by `initFromSettings` — chat, UI Kit AND calls share the ONE file); build-time extras via `local.properties` → `BuildConfig` | `.env` | `cometchat-settings.json` — a **registered asset** in `pubspec.yaml`, not a dotenv file |
+| existing integration | `CometChatUIKitSwift` in `Package.swift` / `Podfile` | any `com.cometchat:` coordinate in `app/build.gradle(.kts)` — `chatuikit-*` (UI Kit v6), `chat-sdk-android` (headless chat), `calls-sdk-android` (headless calls) | `@cometchat/chat-uikit-react-native` in `package.json` | `cometchat_chat_uikit` in `pubspec.yaml` |
+
+There is no `env_prefix` on iOS/Android/Flutter, and no lockfile-derived package manager on
+iOS/Android — asking for either signals the gate was not really platform-aware.
+
+## Follow-the-OS theming (beat 3)
+
+Whether the kit follows the OS by itself DIFFERS per platform — do not assume the web answer:
+
+- **Web (React):** it does NOT. There is no `theme="system"`, so the core syncs `theme` ↔ the
+  `prefers-color-scheme` media query (AUDIT-004).
+- **Web (Angular):** the kit's `initFromPreference()` respects `prefers-color-scheme` and keeps its own
+  `matchMedia` listener — one call, no host observer (`cometchat-angular-v5-customization`).
+- **iOS:** it DOES, with no host code at all. The kit's components override
+  `traitCollectionDidChange` and its palette uses dynamic colours, so light/dark follows the device
+  automatically. Do not offer to "wire up" OS theming on iOS, and do not port the web recipe —
+  `prefers-color-scheme` does not exist outside a web view, and the observer is unnecessary anyway.
+- **Android:** it DEPENDS on the cohort. **Views:** it DOES with no extra code — extend
+  `CometChatTheme.DayNight` (AppCompat DayNight follows the system `uiMode`). **Compose:** it does NOT
+  by itself — the host MUST wrap the kit UI in `CometChatTheme(colorScheme = if (isSystemInDarkTheme())
+  darkColorScheme() else lightColorScheme()) { … }`; with no wrapper the kit renders its light defaults
+  and ignores the OS setting (like the React Native "supply BOTH light and dark" case below, NOT the
+  automatic iOS case). The core Compose golden path emits this wrapper when theming is "Auto — follow
+  OS"; full theming API is `cometchat-android-v6-compose-customization`.
+- **React Native:** supply BOTH `light` and `dark` to the provider; the kit then follows the OS scheme —
+  setting only `light` is the classic bug (`cometchat-react-native-customization`).
+- **Flutter:** Flutter's own `themeMode: ThemeMode.system` — nothing CometChat-specific (`cometchat-flutter-v6-customization`).
+
+## The feature menu (beat 2)
+
+The offered capabilities come from the DETECTED platform's manifest, and they are not the same
+list:
+
+- **Web (React):** `features.json` · **Web (Angular):** `features.angular-v5.json`
+- **iOS:** `features.ios-v5.json`
+- **Android:** `features.android-v6.json` (UI Kit) · `features.sdk-android-v5.json` (headless chat) ·
+  `features.android-calls-v5.json` (headless calling-first — `calling-first.md`)
+- **React Native:** `features.rn-v5.json`
+- **Flutter:** `features.flutter-v6.json`
+
+Never offer a feature the detected platform does not ship. On iOS in particular there is **no
+composite chat component** — the host composes header + list + composer and owns the list ↔ detail
+navigation, so "a chat screen" is a composition task, not a single drop-in. On Android the
+headless calls family is receive-only for screen share and has no virtual background — do not offer either.
+
+## SDK-fallback lookup
+
+Per-feature fallback resolves through the DETECTED platform's core docs-map, never React's by
+default:
+
+> **Web (React):** `cometchat-react-v7-core/references/docs-map.md`
+> **Web (Angular):** `cometchat-angular-v5-core/references/docs-map.md`
+> **iOS:** `cometchat-ios-core/references/docs-map.md`
+> **Android:** `cometchat-android-v6-core/references/docs-map.md` (UI Kit) · `cometchat-android-v5-sdk/references/docs-map.md` (headless chat) · `cometchat-android-v5-calls-sdk/references/docs-map.md` (headless calls)
+> **React Native:** `cometchat-react-native-core/references/docs-map.md`
+> **Flutter:** `cometchat-flutter-v6-core/references/docs-map.md`

package/skills/cometchat-react-native-bare-patterns/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: cometchat-react-native-bare-patterns
+description: "Bare React Native CLI wiring for the CometChat UI Kit v5 — pod install, Android manifest permissions, and the gesture-handler import that must be the first line of your entry file. Triggers: CometChat React Native CLI, pod install CometChat, RN chat crashes on Android build, gesture handler crash release build, AndroidManifest CometChat permissions."
+license: "MIT"
+compatibility: "React Native >=0.77 (CLI / bare); @cometchat/chat-uikit-react-native ^5.4.0"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "chat cometchat react-native cli bare pods gradle manifest gesture-handler"
+---
+
+> **Ground truth:** `@cometchat/chat-uikit-react-native@5` + catalog `rn-v5.json`.
+> Docs: `/ui-kit/react-native/react-native-cli-integration` · `react-native-conversation` ·
+> `react-native-tab-based-chat`.
+
+## Companion skills (read first)
+- `cometchat-react-native-core` — install, provider chain, init→login→render. Assumed, not repeated here.
+- `cometchat-react-native-expo-patterns` — the Expo equivalent. Use that one for an Expo project.
+
+## Use this skill when
+- the project has real `ios/` and `android/` directories and **no** `expo` key in `app.json`
+- "add chat to my React Native CLI app" · "Android build fails after installing CometChat"
+
+## Prerequisites & install
+
+```bash
+npm install @cometchat/chat-uikit-react-native@5 @cometchat/chat-sdk-react-native@4
+npm install @react-native-clipboard/clipboard \
+  react-native-svg react-native-video react-native-localize react-native-gesture-handler \
+  react-native-safe-area-context @react-native-async-storage/async-storage@^2.1.2 dayjs
+cd ios && pod install && cd ..
+```
+
+You own `ios/` and `android/`, so native config is edited **directly** — the opposite of Expo, where
+those directories are generated and hand-edits get overwritten.
+
+## The four native steps that are not optional
+
+### 1. `react-native-gesture-handler` must be the FIRST import of your entry file
+```js title="index.js"
+import 'react-native-gesture-handler';
+// …every other import after this
+```
+Not at the top of a screen — the **very top of `index.js`**, before anything else. Getting this wrong
+often works in debug and **crashes in release**, which is the worst possible failure shape: it passes
+local testing and breaks for users.
+
+### 2. iOS Podfile needs modular headers for two transitive pods
+`@cometchat/chat-uikit-react-native` is a **Swift** pod that depends on `SPTPersistentCache`
+and `DVAssetLoaderDelegate`, neither of which defines a module. On a static-library build —
+the React Native default — `pod install` **fails outright**:
+
+> The Swift pod `react-native-cometchat-ui-kit` depends upon `SPTPersistentCache` and
+> `DVAssetLoaderDelegate`, which do not define modules.
+
+Add these inside your target in `ios/Podfile`, then re-run `pod install`:
+
+```ruby title="ios/Podfile"
+target 'YourApp' do
+  pod 'SPTPersistentCache', :modular_headers => true
+  pod 'DVAssetLoaderDelegate', :modular_headers => true
+  # …
+end
+```
+
+Both official CometChat sample apps carry exactly these two lines. The integration docs do
+not mention them (**RN-G14**), so a first `pod install` fails with an error that names two
+pods the developer has never heard of.
+
+### 3. Android permissions in the manifest
+`android/app/src/main/AndroidManifest.xml` — `INTERNET` at minimum; the camera/audio set only if you
+add calling. Fetch the exact list from the integration page rather than copying a partial set.
+
+## Calling on bare RN
+```bash
+npm install @cometchat/calls-sdk-react-native@5
+# 6 REQUIRED peer deps — the calls SDK's declared peerDependencies. Pinned; do NOT float them.
+npm install @react-native-async-storage/async-storage@^2.1.2 react-native-background-timer@^2.4.1 \
+  react-native-performance@^5.1.2 react-native-svg@^15.12.0 react-native-url-polyfill@2.0.0 \
+  react-native-webrtc@124.0.7
+cd ios && pod install && cd ..
+```
+⚠️ `react-native-url-polyfill` + `react-native-performance` are **bundle-critical** (the UIKit
+module-scope `require()`s the calls SDK, so Metro resolves its peers even in a chat-only build). Keep
+`react-native-performance` on **5.x** (a floated `^6` breaks later `npm install` with ERESOLVE).
+`@react-native-community/netinfo` / `react-native-callstats` are NOT declared peers — do not add them.
+
+iOS permissions go in `ios/<YourApp>/Info.plist`:
+
+```xml
+<key>NSCameraUsageDescription</key>
+<string>Camera access for video calls</string>
+<key>NSMicrophoneUsageDescription</key>
+<string>Microphone access for voice/video calls</string>
+```
+
+Simulators cannot capture camera or microphone — verify calls on a real device.
+
+## After any native change — rebuild, don't reload
+Metro reload only refreshes JavaScript. A new native module, a Gradle edit or a plist change needs a
+full rebuild (`npx react-native run-ios` / `run-android`). "I installed it and nothing changed" is
+almost always a missed rebuild.
+
+## What is the same as Expo
+Everything above the native layer: providers, `init → login → render`, components, theming,
+navigation. Only install and native config differ.
+
+## Common pitfalls
+1. **`gesture-handler` imported late** — works in debug, crashes in release.
+2. **Missing the Podfile modular-headers lines** — `pod install` fails, naming two unfamiliar transitive pods.
+3. **Skipping `pod install`** after adding a package — iOS fails to link.
+4. **Reloading instead of rebuilding** after a native change.
+5. **Copying Expo's `app.json` permission block** into a bare app — it does nothing there.
+
+## Verify it works
+- `index.js` starts with the gesture-handler import.
+- iOS and Android both build clean from scratch.
+- `npm run verify:fences:rn-v5` is green.
+- On device: chat renders, gestures respond, the composer survives the keyboard. Test a **release**
+  build too — the gesture-handler ordering bug only shows there.

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

@@ -0,0 +1,200 @@
+---
+name: cometchat-react-native-calls
+description: "Voice and video calling in the CometChat React Native UI Kit v5 — the RN calls SDK, the native permissions and version floors it needs, and why installing the package is itself the enable switch. Triggers: add video calling React Native, CometChat voice call RN, incoming call screen RN, calls not ringing React Native, webrtc CometChat."
+license: "MIT"
+compatibility: "React Native >=0.77; @cometchat/chat-uikit-react-native ^5.4.0; @cometchat/calls-sdk-react-native ^5.0.4; Android minSdk 24; iOS 13.0"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "chat cometchat react-native calls voice video webrtc permissions"
+---
+
+> **Ground truth:** `@cometchat/calls-sdk-react-native@5` + catalog `rn-calls-v5.json` (58 symbols) +
+> `features.rn-v5.json` → `voice-video-calls`. Docs: `/ui-kit/react-native/calling-integration` ·
+> `call-features` · `call-buttons` · `call-logs` · `incoming-call` · `outgoing-call`.
+
+## Companion skills (read first)
+- `cometchat-react-native-core` — install, provider chain, init→login→render. Assumed, not repeated here.
+
+## Use this skill when
+- "add voice/video calling" · "incoming call screen" · "calls aren't ringing" · "call logs"
+
+## Prerequisites & install
+
+⚠️ **React Native has its OWN calls SDK.** `@cometchat/calls-sdk-javascript` is the web package and
+will not work here.
+
+```bash
+npm install @cometchat/calls-sdk-react-native@5
+# 6 REQUIRED peer deps — the SDK's declared peerDependencies. Versions are pinned; do NOT float them.
+npm install @react-native-async-storage/async-storage@^2.1.2 react-native-background-timer@^2.4.1 \
+  react-native-performance@^5.1.2 react-native-svg@^15.12.0 react-native-url-polyfill@2.0.0 \
+  react-native-webrtc@124.0.7
+# ⚠️ react-native-performance MUST stay 5.x — 6.x is published, and a floated `^6` makes every later
+#    `npm install` in the app fail with ERESOLVE. react-native-url-polyfill + react-native-performance
+#    are BUNDLE-critical: the UIKit does a module-scope require() of the calls SDK, so Metro resolves
+#    them even for a chat-only build — omit either and the bundle fails with "Unable to resolve module".
+#    (NOT react-native-community/netinfo or react-native-callstats — those are not declared peers.)
+cd ios && pod install && cd ..     # bare RN;  Expo: npx expo run:ios
+```
+
+## Enabling calls — there is no flag
+
+**Installing the package IS the switch.** The kit does a `try { require("@cometchat/calls-sdk-react-native") }`
+at startup; if it resolves, calling is enabled automatically.
+
+React's `setCallingEnabled(true)` **does not exist in this kit** — do not emit it. There is likewise **no
+opt-out on the `initFromSettings` golden path** — the `CometChatSettings` file/object has no calling field,
+and `CometChatUIKit.initFromSettings()` never reads one. `disableCalling: true` exists **only** as a field
+on the `UIKitSettings` object you pass to the legacy `CometChatUIKit.init(uiKitSettings)` — so to disable
+calling while the package stays installed you must switch to that `init()` entry point (or simply not
+install the calls SDK).
+
+Consequence worth knowing: a half-finished install (package added, pods not run) can leave calling
+"enabled" in JS while the native side is missing — which surfaces as a crash on first call rather than
+a clear error at startup.
+
+## Native floors — below these it will not build
+
+| Platform | Requirement | Where |
+|---|---|---|
+| Android | `minSdkVersion 24` | `android/app/build.gradle` |
+| iOS | `IPHONEOS_DEPLOYMENT_TARGET` 13.0 | Xcode target or a Podfile `post_install` |
+
+## Permissions — camera and microphone
+
+**Bare RN** — `ios/<App>/Info.plist`:
+```xml
+<key>NSCameraUsageDescription</key><string>Camera access for video calls</string>
+<key>NSMicrophoneUsageDescription</key><string>Microphone access for voice/video calls</string>
+```
+Android: `CAMERA` · `RECORD_AUDIO` · `MODIFY_AUDIO_SETTINGS` · `BLUETOOTH_CONNECT` (Android 12+, Bluetooth audio routing) in `AndroidManifest.xml`.
+
+**Expo** — the same values go in `app.json` (`ios.infoPlist`, `android.permissions`), then rebuild.
+Never hand-edit the generated native projects.
+
+## Components (from `catalogs/rn-v5.json`)
+
+| Component | Purpose |
+|---|---|
+| `CometChatCallButtons` | audio/video triggers — the message header shows these by default |
+| `CometChatIncomingCall` | the ring screen — **mount once above the navigator** |
+| `CometChatOutgoingCall` | the dialling screen |
+| `CometChatOngoingCall` | the in-call surface (**no React equivalent**) |
+| `CometChatCallLogs` | call history **list** |
+
+`CometChatIncomingCall` mounted inside one screen means calls only arrive while that screen is open —
+the commonest "calls don't ring" cause after a missing permission.
+
+The table above is not enough to copy — wire it:
+
+```tsx
+// App.tsx — IncomingCall sits ABOVE the navigator so a call rings on any screen.
+function App() {
+  const incomingCall = useRef<CometChat.Call | null>(null);
+  const [callReceived, setCallReceived] = useState(false);
+
+  useEffect(() => {
+    const listenerId = "APP_CALL_LISTENER";
+    CometChat.addCallListener(
+      listenerId,
+      new CometChat.CallListener({
+        onIncomingCallReceived: (call) => {
+          incomingCall.current = call;
+          setCallReceived(true);
+        },
+        onOutgoingCallRejected: () => setCallReceived(false),
+        onIncomingCallCancelled: () => setCallReceived(false),
+      }),
+    );
+    return () => CometChat.removeCallListener(listenerId);   // or it fires after unmount
+  }, []);
+
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      <NavigationContainer>{/* … */}</NavigationContainer>
+      {callReceived && incomingCall.current ? (
+        <CometChatIncomingCall
+          call={incomingCall.current}
+          onDecline={() => { incomingCall.current = null; setCallReceived(false); }}
+        />
+      ) : null}
+    </GestureHandlerRootView>
+  );
+}
+```
+
+```tsx
+// Call triggers — the message header renders these by default; mount them yourself only
+// when you build a custom header. onError is the ONLY callback: success is an event
+// (ccOutgoingCall), not a promise.
+<CometChatCallButtons user={user} group={group} onError={(e) => console.error(e)} />
+
+// Dialling screen — driven by the Call object you created.
+{call && <CometChatOutgoingCall call={call} />}
+
+// Call history list. Detail screens do NOT ship (see below).
+<CometChatCallLogs onItemPress={(log) => openCallDetail(log)} />
+```
+
+```tsx
+// The in-call surface. sessionID comes from the accepted Call; callSettingsBuilder is a
+// CometChatCalls builder, NOT a chat-SDK one.
+<CometChatOngoingCall
+  sessionID={sessionId}
+  callSettingsBuilder={callSettings}
+  onError={(e) => console.error(e)}
+/>
+```
+
+> **DOCS GAP (RN-G15 — narrowed upstream, verified 2026-09-09):** `CometChatOngoingCall` is exported by
+> the RN kit and is now **listed** on `/ui-kit/react-native/call-features` (the Components row), but it
+> still has **no dedicated props page** — only Incoming / Outgoing / Buttons / Logs get their own pages.
+> The fence above is a **STOPGAP built from the kit's own types** — replace it once a props page ships.
+> Flagged for the docs team; do not conclude the component is unavailable on RN.
+
+## Call logs: the list ships, the detail screens do not
+Kit v5 removed `CometChatCallLogDetails` / `History` / `Participants` / `Recordings`. For a custom detail
+view, fetch the history yourself with the **Calls-SDK** `CallLogRequestBuilder` — a static on
+`CometChatCalls`, reachable only from `@cometchat/calls-sdk-react-native`:
+
+```ts
+// Call history — CometChatCalls.CallLogRequestBuilder from the CALLS SDK.
+// There is NO CallLogRequestBuilder on the Chat SDK (@cometchat/chat-sdk-react-native).
+import { CometChat } from "@cometchat/chat-sdk-react-native";
+import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
+// fetchNext() REJECTS without an auth token ("`Auth Token` is required") — no fallback. Pass the
+// logged-in user's token, exactly as the kit's own CometChatCallLogs does.
+const authToken = (await CometChat.getLoggedinUser())?.getAuthToken() ?? "";
+const req = new CometChatCalls.CallLogRequestBuilder().setLimit(30).setAuthToken(authToken).build();
+const logs = await req.fetchNext();
+
+// Transcript opt-in — same builder + token. setHasTranscriptions(true) filters to transcribed calls
+// AND makes the server attach each call's transcripts to the log.
+const treq = new CometChatCalls.CallLogRequestBuilder().setLimit(30).setAuthToken(authToken).setHasTranscriptions(true).build();
+```
+
+> **RN-G9 (verified 2026-09-10 vs `@cometchat/calls-sdk-react-native@5`):** `CallLogRequestBuilder` is a
+> static on `CometChatCalls` (calls SDK) — `new CometChatCalls.CallLogRequestBuilder()`. It does **not**
+> exist on the Chat SDK: there is no `CometChat.CallLogRequestBuilder` in `@cometchat/chat-sdk-react-native`
+> (any version). Use the Calls-SDK builder for history, always with `.setAuthToken(...)` (without it `fetchNext()`
+> rejects — verified in `@cometchat/calls-sdk-react-native@5.0.5`); add `setHasTranscriptions(true)` only when you need
+> transcripts. It is reachable as a static on the module, not as a bare named import.
+
+## Verification requires a real device
+**Simulators and emulators cannot capture camera or microphone.** A green simulator run proves the
+screens render, not that a call connects. Media, permissions and ringing must be checked on hardware.
+
+## Common pitfalls
+1. **Installing the web calls SDK** — wrong package.
+2. **Emitting `setCallingEnabled(true)`** — does not exist; installation is the switch.
+3. **`CometChatIncomingCall` inside a screen** — calls only ring there.
+4. **Skipping `pod install` / rebuild** — crash on first call, not at startup.
+5. **Below the version floors** — build failure, not a runtime message.
+6. **Signing off from a simulator** — no media capture.
+
+## Verify it works
+- Every emitted symbol is in `catalogs/rn-v5.json` or `catalogs/rn-calls-v5.json`.
+- `npm run verify:fences:rn-v5` is green.
+- **On two real devices:** call connects both ways, permission prompts appear on first use, the
+  incoming screen shows while the app is on any tab, and the call log records the call.