@cometchat/skills 4.4.2 → 5.0.1

package/skills/cometchat-migrate-from-sendbird/references/feature-map.md

@@ -0,0 +1,104 @@
+# Sendbird → CometChat feature map
+
+**How to use:**
+1. For each feature the ledger shows, find its row below.
+2. Check the **CometChat id** in the TARGET family's `features.json`. Ids differ slightly per family, so match on the `id` OR the entry's `name`. Common aliases: `threaded-replies`≈`threaded-conversations`, `delivery-read-receipts`≈`read-receipts`, `typing-indicators`≈`typing-indicator`, `quoted-replies`≈`quoted-reply`, `message-search`≈`conversation-advanced-search`, `media-file-attachments`≈`media-sharing`, `users-groups`≈`group-chat`, `text-messaging`≈`instant-messaging`, `smart-reply`≈`ai-smart-replies`.
+3. **Found** → migrate, wired by the skill in *Via*.
+4. **Not found (or the id column says "none")** → search the docs at BOTH levels: the UI Kit and the Chat SDK / REST API (SKILL step 3). Documented at either → migrate; no UI Kit drop-in means build it on the SDK method in the app's own UI. Documented at neither → apply *If absent*.
+
+**Actions under *If absent*** apply only AFTER both docs searches (UI Kit and SDK) come back empty. The table's REMOVE is never a shortcut past that check, and the report's evidence must quote both queries:
+- `REMOVE` → UNSUPPORTED: remove it fully (SKILL step 6) and list it in the report.
+- `CHANGE` → keep the capability on the closest CometChat equivalent, and list the difference under "Behavior changes".
+
+**Enablement:** a feature whose `features.json` entry says `needs_dashboard`, or is an extension/AI feature, still migrates in code. Add "enable <feature> in the CometChat dashboard" to the action items. `@cometchat/skills-cli features enable` can do it after `auth login`.
+
+**Rows are grouped by area.** Columns: Sendbird feature (signals) · CometChat id · Via · If absent.
+
+### Messaging basics
+
+| Sendbird feature (signals) | CometChat id | Via | If absent |
+|---|---|---|---|
+| 1:1 + group chat (`GroupChannel`, `isDistinct`) | `core-chat-surface`, `users-groups`, `text-messaging` | core | — (always present) |
+| Channel list with unread badges, last message (`GroupChannelList`, `unreadMessageCount`) | `core-chat-surface` | core | — |
+| Edit / delete messages (`updateUserMessage`, `deleteMessage`) | `text-messaging` | core | — |
+| Typing indicators (`startTyping`, `onTypingStatusUpdated`) | `typing-indicators` | core / features | CHANGE (drop the indicator) |
+| Read + delivery receipts (`markAsRead`, `getReadMembers`, `onDeliveryReceiptUpdated`) | `delivery-read-receipts` | core / features | CHANGE |
+| Mark as unread (`markAsUnread`) | `mark-as-unread`, else the SDK's mark-as-unread call (`/sdk/<platform>/delivery-read-receipts`; needs Enhanced Messaging Status → action item) | features / SDK | REMOVE |
+| Files, images, video, multi-file (`sendFileMessage(s)`) | `media-file-attachments` | core / features | CHANGE (single file per message) |
+| Voice messages (voice recorder, `VoiceMessage`) | `voice-notes` | features | REMOVE the recorder, keep audio-file playback |
+| Threads (`parentMessageId`, `Thread`, `ThreadInfo`) | `threaded-replies` | features / placement | REMOVE the thread UI |
+| Quote reply (`ReplyType.QUOTE_REPLY`) | `quoted-replies` | features | REMOVE |
+| Reactions (`addReaction`, `onReactionUpdated`) | `reactions` | features | REMOVE |
+| Custom emoji sets for reactions (`getAllEmoji`, emoji categories) | none | docs | CHANGE (the kit's default emoji) |
+| Mentions (`mentionedUsers`, `MentionType`) | `mentions` | features | REMOVE the mention picker, keep plain text |
+| Polls (`sb.poll`, `PollCreateParams`) | `polls` | features | REMOVE |
+| Message search (`MessageSearchQuery`) | `message-search` | features / placement | REMOVE |
+| Pinned messages (`pinMessage`, `pinnedMessageIds`) | `pin-message` | features | REMOVE |
+| Scheduled messages (`createScheduledUserMessage`) | none | docs | REMOVE |
+| Forward / copy message to another channel (`copyUserMessage`) | none | docs | REMOVE |
+| Translation (`translateUserMessage`, `translationTargetLanguages`) | `message-translation` | features | REMOVE |
+| Link previews (`ogMetaData`) | `link-preview` | features | CHANGE (plain links) |
+| Disappearing messages / retention (`messageSurvivalSeconds`) | `disappearing-messages` | features | REMOVE |
+| Custom message types, `customType`, `data`, message templates | `custom-message-types` (Angular also `card-messages`) | customization / features | CHANGE (render as text + metadata) |
+| Message `metaArrays` / `data` payloads | message metadata (core SDK) | core | — |
+
+### Users and presence
+
+| Sendbird feature (signals) | CometChat id | Via | If absent |
+|---|---|---|---|
+| Presence, last seen (`connectionStatus`, `lastSeenAt`) | `user-presence` | core | CHANGE |
+| User profile: nickname, profile image, metadata (`updateCurrentUserInfo`) | user name / avatar / metadata (core SDK) | core | — |
+| Block / unblock users (`blockUser`) | `block-unblock-user` (iOS), else the core SDK block-users call | core / docs | REMOVE |
+
+### Channels and moderation
+
+| Sendbird feature (signals) | CometChat id | Via | If absent |
+|---|---|---|---|
+| Open channels (`OpenChannel`, `enter`, `OpenChannelHandler`) | `users-groups` (a **public** group) | core / components | CHANGE (members join; history persists) |
+| Join a public channel / group (`OpenChannel.enter`, join button, `addMembers`) | join a public group: `CometChatGroups` (joinable list) + the SDK's `CometChat.joinGroup(guid, type)` (`/sdk/<platform>/groups-join-leave`) | components / SDK | REMOVE |
+| Supergroups, broadcast channels (`isSuper`, `isBroadcast`) | `users-groups` | core | CHANGE (over 300 members → no receipts/typing; broadcast → admins-only posting only if the docs document a send restriction) |
+| Ephemeral channels (`isEphemeral`) | none | docs | CHANGE (messages are now stored) |
+| Channel name, cover, custom type, `data` — incl. an owner's rename / re-cover screen | group name / icon / tags / metadata; editing = the SDK's update-group call (`/sdk/<platform>/update-group`) | core / SDK | — |
+| Channel metadata (`createMetaData`) | group metadata (docs) | core / docs | CHANGE |
+| Metacounters (`createMetaCounters`, atomic increments) | none | docs | REMOVE (or CHANGE to group metadata, non-atomic — say which) |
+| Operators, roles (`addOperators`, `role`) | group member scopes: admin / moderator / participant (`users-groups`) | components / docs | CHANGE |
+| Ban / kick members, banned-members list + unban (`banUser`, `removeMember`, `BannedUserListQuery`, `unbanUser`) | group member management: the kit's members list + the SDK's banned-members request + unban (`/sdk/<platform>/group-kick-ban-members`) | components / SDK | REMOVE |
+| Mute a member, freeze a channel (`muteUser`, `freeze`) | none | docs | REMOVE |
+| Invitations with accept/decline (`invite`, `acceptInvitation`) | none (members are added directly) | docs | CHANGE (invite = add member) + REMOVE the accept/decline UI |
+| Hide / archive channel (`hide`, `unhide`) | none | docs | REMOVE |
+| Report user/message/channel (`report*`) | `report-message` / `moderation` | features | REMOVE |
+| Profanity / domain / image filters (dashboard) | `moderation` | features + dashboard | action item: recreate the rules |
+
+### Push, calls and other products
+
+| Sendbird feature (signals) | CometChat id | Via | If absent |
+|---|---|---|---|
+| Push (`registerFCMPushTokenForCurrentUser`, `registerAPNSPushTokenForCurrentUser`) | `push-notifications` | push | action item (credentials in the dashboard) |
+| Push preferences: DND, per-channel mute, trigger options, snooze | notification preferences: mute/unmute conversations, DND, schedules (`/notifications/preferences`) | push / SDK | REMOVE only what the preferences page lacks (e.g. snooze) |
+| Sendbird Calls: 1:1 `dial`, group `Room` | `voice-video-calls` | calls (or the headless calls peer) | REMOVE |
+| AI chatbot, bot users | `ai-assistant`, `ai-agents`, `smart-reply`, `conversation-summary` | features | REMOVE |
+| Sendbird Desk (tickets) | `support-integrations` | features / docs | REMOVE |
+| Sendbird Live (`@sendbird/live`) | `live-streaming` | features / docs | REMOVE |
+| Business Messaging / notification feed (`FeedChannel`, notification templates) | `notification-feed` / `campaigns` | features / docs | REMOVE |
+| Local caching / collections (`localCacheEnabled`, `*Collection`) | none | core | CHANGE (online-first; list the offline gap) |
+
+### Look and feel, server
+
+| Sendbird feature (signals) | CometChat id | Via | If absent |
+|---|---|---|---|
+| Theme, colors, dark mode (`colorSet`, `SBUTheme`, `setDefaultThemeMode`) | theming | customization | — |
+| String sets / localization (`stringSet`, `SBUStringSet`) | localization (docs) | customization | CHANGE (the kit's defaults) |
+| Webhooks (`x-sendbird-signature`) | CometChat webhooks | server (SKILL step 7) | REMOVE (and list) each event with no equivalent |
+| Platform API admin calls (bulk users, channel admin) | CometChat REST (docs) | server | REMOVE the call + list it |
+
+A feature in the ledger that has no row here: treat it like a `none` row. Check `features.json`, then the docs, then REMOVE or CHANGE, and say which in the report.
+
+## Deciding "unsupported" — the verification ladder (read before any REMOVE)
+
+**An MCP search that returns NOTHING is NOT evidence of "unsupported" — nor is the MCP being down.** An empty result (or "no dedicated page") is INCONCLUSIVE: the feature is often documented under CometChat's OWN term (a vendor "voice message recorder" is CometChat's **media recorder** / **voice notes**), folded into a broader page (a composer prop, not its own page), or just ranked out of the top hits. So when the MCP doesn't surface it, walk this ladder BEFORE any verdict:
+
+1. **Re-query with CometChat vocabulary** — component/product names; drop over-qualifiers like the version/platform.
+2. **LIVE-FETCH the likely docs page** — `fetch_cometchat_doc_page` (or a plain fetch of the docs URL + `.md`) of the family's composer / features / component page.
+3. **Cross-check the family CATALOG** (the installed component/symbol list) — if the component is there, it IS supported, migrate it.
+
+Mark **UNSUPPORTED only** when the CATALOG lacks it AND the live doc fetch (not merely an empty MCP search) also finds nothing. If it genuinely can't be checked (tooling down, network blocked), KEEP it and mark `needs-verification` — never REMOVE a feature you could not verify is absent. **Every UNSUPPORTED row needs evidence** in the report: the `features.json` result plus the exact UI Kit AND SDK docs queries you ran and what each returned. A REMOVE with no docs query is not allowed. Docs MCP not connected? Use a plain fetch (`RULES.md` → Fetch discipline).

package/skills/cometchat-migrate-from-sendbird/references/inventory.md

@@ -0,0 +1,86 @@
+<!-- family-agnostic: per-platform-by-design — this reference IS the per-platform Sendbird inventory + target-family table; one row per platform by design. -->
+# Sendbird inventory — what to find, and where it goes
+
+Search case-insensitively. Skip `node_modules/`, `Pods/`, `build/`, `.dart_tool/`, `.gradle/` and `.git/`. A package hit tells you Sendbird is present. The **import/API hits** tell you *what the app does with it*, and each one becomes a ledger row (`file:line → purpose`). The names below are the common ones, not a closed list: any identifier starting with `Sendbird`/`SendBird`/`SB` imported from a Sendbird package counts.
+
+## Target family (where each platform lands)
+| App platform (detect `framework`) | Sendbird packages you'll see | CometChat family (`peers.yaml`) | UIKit mode → | SDK mode (own UI) → |
+|---|---|---|---|---|
+| React / Next / Vite / CRA / Astro / React Router | `@sendbird/uikit-react`, `sendbird-uikit` (v2), `@sendbird/chat`, `sendbird` (v3) | `react-v7` | `cometchat-react-v7-core` + `-components`/`-placement` | the core's SDK fallback (`@cometchat/chat-sdk-javascript`, docs-map → SDK docs) |
+| Angular | `@sendbird/chat`, `sendbird` (no official Angular UIKit — usually SDK mode) | `angular-v5` | `cometchat-angular-v5-core` | the core's SDK fallback (JS Chat SDK) |
+| React Native / Expo | `@sendbird/uikit-react-native`, `@sendbird/uikit-react-native-foundation`, `@sendbird/chat`, `@sendbird/calls-react-native` | `react-native` | `cometchat-react-native-core` | `cometchat-react-native-sdk` |
+| iOS (Swift) | SPM `sendbird-chat-sdk-ios` / `sendbird-uikit-ios` / `sendbird-swiftui-ios`; pods `SendbirdChatSDK`, `SendBirdUIKit`, `SendBirdSDK` (v3), `SendBirdCalls` | `ios` | `cometchat-ios-core` (UIKit; host SwiftUI screens via a representable) | the iOS core's SDK fallback (`CometChatSDK`) |
+| Android | `com.sendbird.sdk:sendbird-chat`, `com.sendbird.sdk:uikit`, `com.sendbird.sdk:uikit-compose`, `com.sendbird.sdk:sendbird-calls`, the `repo.sendbird.com` Maven repo | `android-v6` (cohort from `android_variant`: Compose → `compose-*`, Views → `kotlin-*`) | `cometchat-android-v6-core` | `cometchat-android-v5-sdk` |
+| Flutter | `sendbird_uikit`, `sendbird_chat_sdk`, `sendbird_sdk` (v3) | `flutter-v6` | `cometchat-flutter-v6-core` | the Flutter core's SDK fallback (`cometchat_sdk`, re-exported by the kit) |
+| Calls only (no chat) | `sendbird-calls`, `@sendbird/calls-react-native`, `SendBirdCalls`, `com.sendbird.sdk:sendbird-calls` | the matching headless calls peer (`js-calls`, `react-native-calls`, `ios-calls`, `android-calls`, `flutter-calls`) | — | `cometchat-js-v5-sdk` / `cometchat-react-native-v5-sdk` / `cometchat-ios-v5-sdk` / `cometchat-android-v5-calls-sdk` / `cometchat-flutter-v5-sdk` |
+| Server (Node, Python, Go, Java, Ruby, PHP…) | HTTP to `api-<APP_ID>.sendbird.com/v3/…` with an `Api-Token` header; `sendbird-platform-sdk*` | — (REST, no UI Kit) | — | CometChat REST (`/rest-api/…`) |
+
+A platform that isn't in this table (Vue, Svelte, Unity, .NET MAUI, Unreal…) has no family in this pack → STOP (2): report only.
+
+### React Native is a native platform for the build, not a web one
+The migration is not done when Metro bundles: `cd ios && pod install` (the kit's Podfile needs the
+`modular_headers` lines the family `-core` lists, or `pod install` itself fails), then BUILD **and
+RUN** both platforms. Three failures never appear in CI — only when a person uses the app:
+
+| Trap | What you see |
+|---|---|
+| React Native >= 0.87 on iOS | the kit's composer calls `InteractionManager`, removed from RN core in 0.87 — tapping send throws (`InteractionManager has been removed from react-native core`); Android is unaffected. Shim: the family `-troubleshooting` |
+| a missing native peer | fails at MOUNT, and the error names the peer (`gesture-handler`, `svg`, `video`), never CometChat |
+| `tsc --noEmit` | reports errors from inside the kit's own shipped source (it ships raw `src/*.tsx`), so gate on the Metro bundle — see the family `-core` -> Verify it works, which also carries the run recipe for a machine where port 8081 is taken |
+
+## Grep signals
+**Manifests**: `package.json`, `pubspec.yaml`, `build.gradle(.kts)`, `settings.gradle(.kts)`, `gradle/libs.versions.toml`, `Podfile`, `Package.swift`, `*.xcodeproj/project.pbxproj`, `Package.resolved`, `requirements.txt`, `go.mod`, `Gemfile` and `composer.json` → `sendbird`.
+
+**Init / auth**:
+- v4 SDK: `SendbirdChat.init`, `.connect(`, `.disconnect(`, `authToken`/`accessToken`/`sessionToken`, `SessionHandler` (token refresh).
+- v3 SDK: `new SendBird(`, `SendBird.getInstance()`.
+- iOS: `SendbirdUI.initialize`, `SBUGlobals.currentUser`.
+- Android: `SendbirdUIKit.init`, `SendbirdUIKitAdapter`.
+
+**Providers / screens (UIKit)**:
+- React:
+  - `SendbirdProvider`, `App` (from `@sendbird/uikit-react/App`).
+  - `GroupChannelList`, `GroupChannel`, `ChannelList`, `Channel`, `ChannelSettings`.
+  - `Thread`, `MessageSearch`, `CreateChannel`, `OpenChannel`, `OpenChannelSettings`, `EditUserProfile`.
+  - `useSendbirdStateContext`, `sendbirdSelectors`.
+  - CSS `@sendbird/uikit-react/dist/index.css`.
+- React Native: `SendbirdUIKitContainer`, `createGroupChannelListFragment`, `createGroupChannelFragment`, `createGroupChannelCreateFragment`, `createGroupChannelSettingsFragment`, `useSendbirdChat`, `useConnection`, `platformServices`.
+- iOS: `SBUGroupChannelListViewController`, `SBUGroupChannelViewController`, `SBUOpenChannelViewController`, `SBUCreateChannelViewController`, `SBUMessageThreadViewController`, `SBUTheme`, `SBUStringSet`; SwiftUI `GroupChannelListView`, `GroupChannelView`.
+- Android: `ChannelListActivity`, `ChannelActivity`, `ChannelListFragment`, `ChannelFragment`, `OpenChannelFragment`, `MessageThreadFragment`, `SendbirdUIKit.setDefaultThemeMode`; Compose `ChannelListScreen`, `ChannelScreen`, `SendbirdUikitCompose`.
+- Flutter: `SendbirdUIKit.init`, `SBUGroupChannelListScreen`, `SBUGroupChannelScreen`, `SBUTheme`.
+
+**Channels**:
+- `GroupChannel`, `OpenChannel`, `FeedChannel`.
+- Creation: `createChannel`, `createChannelWithUserIds`, `GroupChannelCreateParams`, `isDistinct`, `isSuper`, `isPublic`, `isBroadcast`, `isEphemeral`, `customType`.
+- Queries: `GroupChannelListQuery`, `createMyGroupChannelListQuery`, `GroupChannelCollection`.
+
+**Messages**:
+- Send: `sendUserMessage`, `sendFileMessage`, `sendFileMessages`, `sendScheduledMessage`/`createScheduledUserMessage`.
+- Edit/delete: `updateUserMessage`, `deleteMessage`.
+- Load: `PreviousMessageListQuery`, `getMessagesByTimestamp`, `MessageCollection`.
+- Threads and replies: `parentMessageId`, `ThreadInfo`, `ReplyType`.
+- Flags: `copyUserMessage`/`copyFileMessage`, `pinMessage`, `markAsRead`, `markAsDelivered`, `markAsUnread`.
+- Extras: `addReaction`, `mentionedUsers`/`MentionType`, `translateUserMessage`/`translationTargetLanguages`, `ogMetaData`, `metaArrays`, `message.data`/`customType`.
+
+**Events**: `GroupChannelHandler`, `OpenChannelHandler`, `ChannelHandler` (v3), `ConnectionHandler`, `UserEventHandler`, `addGroupChannelHandler`/`addChannelHandler`, `onMessageReceived`, `onTypingStatusUpdated`, `onReadStatus`/`onUnreadMemberStatusUpdated`, `onDeliveryReceiptUpdated`, `onReactionUpdated`.
+
+**Users / moderation**:
+- Users: `blockUser`, `unblockUser`, `ApplicationUserListQuery`, `updateCurrentUserInfo`, `UserEventHandler`.
+- Channel moderation: `banUser`, `muteUser`, `freeze`, `addOperators`, `report` (`reportUser`/`reportMessage`/`reportChannel`).
+- Channel data: `createMetaData`, `createMetaCounters`.
+- Membership: `hide`/`unhide`, `invite`/`acceptInvitation`/`declineInvitation`, `setMyPushTriggerOption`, `setDoNotDisturb`, `setSnoozePeriod`, `setCountPreference`.
+
+**Push**: `registerFCMPushTokenForCurrentUser`, `registerAPNSPushTokenForCurrentUser`, `registerPushToken`, `SendbirdPushHelper`, `SendbirdPushHandler`, `unregisterPushToken*`. Also check the push message payload parsing: a `sendbird` key in the notification data.
+
+**Other products**:
+- Calls: `SendBirdCall`, `SendbirdCall`, `DirectCall`, `dial(`, `Room`/`RoomType`.
+- Desk: `sendbird-desk`, `SendBirdDesk`, `Ticket`.
+- Live: `@sendbird/live`.
+- AI chatbot: `bot`/`ai_agent` channel types, `AIChatBot`, `@sendbird/chat-ai-widget`.
+- Business Messaging / Notifications: `FeedChannel`, `NotificationCollection`, message templates.
+
+**Server**: `api-*.sendbird.com`, `Api-Token`, `/v3/users/*/token` (session tokens), `/v3/group_channels`, `/v3/open_channels`, and webhook handlers that verify `x-sendbird-signature`.
+
+**Env / config**: `SENDBIRD_APP_ID`, `VITE_SENDBIRD_*`, `NEXT_PUBLIC_SENDBIRD_*`, `EXPO_PUBLIC_SENDBIRD_*`, `SENDBIRD_API_TOKEN`, `SendbirdAppId` in plists/`local.properties`/`--dart-define`, and CI secrets named `SENDBIRD_*`.
+
+**Tests / mocks**: `jest.mock('@sendbird/…')`, fake `SendbirdChat`, and fixtures containing channel URLs.

package/skills/cometchat-migrate-from-sendbird/references/native-build.md

@@ -0,0 +1,10 @@
+# Native platforms (Android · iOS) — NOT done until the platform build passes
+
+Editing the code is not enough on native; a migration that "looks done" here routinely fails to build or isn't actually wired. You MUST, before declaring done:
+- **Bump the sample's build toolchain to the core skill's floors FIRST** (an old sample toolchain is the #1 native build failure). Android: set `gradle/wrapper/gradle-wrapper.properties` `distributionUrl` to **Gradle ≥ 8.11**, plus **AGP ≥ 8.9.1 · compileSdk 36 · minSdk 28 · Kotlin ≥ 2.1** (per the family `-core` skill's build floors — a stale wrapper gives the opaque `checkDebugAarMetadata` / "Gradle version" error). iOS: resolve the SPM (or pods) graph. Flutter: swap the dep in `pubspec.yaml`, then `flutter pub get`; the settings file is an **asset** — `cometchat-settings.json` at the project root AND listed under `flutter: assets:` in `pubspec.yaml`, or the build fails with "No file or variants found for asset".
+- **The wrapper file may refuse every write.** `gradle/wrapper/gradle-wrapper.properties` is a protected path: `Edit`, `Write` and a Bash `sed` against it can each be refused. Attempt it anyway, and if every route is refused, say **exactly which commands were refused** in the report instead of reporting the bump as done — a stale wrapper is the #1 Android build failure (AGP >= 8.9.1 needs Gradle >= 8.11.1), so a silent omission here costs the whole build. **Keep shell metacharacters out of the commands you run:** a `|` (even as a sed delimiter, or inside an alternation like `(bin|all)`), a `{a,b}` brace expansion, a `$(...)` substitution or a `VAR=x cmd` env prefix is parsed as shell syntax by the command-permission layer and the WHOLE command is refused, silently. Use `/` delimiters, character classes, plain literals and separate lines before concluding an edit is impossible.
+- **Confirm the kit dependency is added AND `initFromSettings` is wired** in the platform's app entry — Android `Application.onCreate`, iOS `AppDelegate`/`App`, Flutter `main`. "No kit dependency" and "no `initFromSettings` call" mean the migration is incomplete, not done.
+- **Port `toCometChatId` to the CLIENT language** (Kotlin/Swift/Dart — verbatim port in `references/concept-map.md` §IDs), in its own module (Flutter: `lib/cometchat/ids.dart`; Android: `…/cometchat/Ids.kt`; iOS: `CometChat/Ids.swift`), and **call it at login** — not only in the JS data script. **The UID is `toCometChatId(<the app's existing Sendbird user id>)`** — the `SendbirdUIKit.connect('…')` / `SendbirdChat.connect` id or the app's stored user id. The core skill's "never invent a UID / `cometchat-uid-1` for a fresh app" advice does NOT apply to a migration: the identity already exists, keep it (single-prompt contract → *Keep every identity source*).
+- **Update `LICENSE`/attribution/README** — a vendor copyright line is residue too.
+- **RUN the platform build** (`./gradlew :app:assembleDebug` · `xcodebuild … build` · `flutter analyze && flutter build web` or `flutter build apk --debug`) and fix EVERY error. A native migration is not done until its own build passes. **Then run it** (§Verify it works): Flutter → `flutter run -d web-server --web-port 8765` via the Bash tool's **background mode** (`run_in_background`), then `sleep 20` and **Read** its output file (repeat ×3) until "is available at" or an exception shows, then **stop that task** and continue. No shell loops, `&`, `$(…)` or `timeout` (denied under headless permissions; `timeout` is absent on macOS), and never park the migration on a notification (headless: that ends the run).
+- **NEVER text-replace inside `*.xcodeproj/project.pbxproj` or `*.xcscheme`.** They are structured build graphs, not manifests: a blind find-and-replace (including a residue scrub) silently breaks the build in ways the compiler cannot report. Edit only the SPM `XCRemoteSwiftPackageReference` blocks and the product-name strings you actually mean to change, and leave every `PBXFileReference`, `productReference`, Products-group child and scheme `BuildableName` intact — a product is `Foo.app` / `Foo.appex`, never bare `Foo`. **Verify after editing:** the app target still has a `productReference`, the Products group still lists it, and the scheme's `BuildableName` still ends in `.app`. If these are missing, `xcodebuild` still reports **BUILD SUCCEEDED** while Xcode's Run silently does nothing — there is no error message anywhere, so the build passing is not evidence they survived.

package/skills/cometchat-migrate-from-sendbird/references/report-template.md

@@ -0,0 +1,59 @@
+# Report template — `COMETCHAT_MIGRATION.md`
+
+Write this file at the repo root, filled from the ledger. Leave out an empty section's rows, but keep its heading with "None." so the reader knows it was checked. Then END the chat reply with sections 3 and 5 pasted in full (SKILL step 11).
+
+```markdown
+# Sendbird → CometChat migration
+
+**Branch:** cometchat-migration (created from <base>; <n> uncommitted files came along) · **Platform:** <framework> → CometChat <family label> · **Mode:** UIKit | SDK | mixed
+**Build:** ✅ passes (`<command>`) | ❌ <n> errors (listed below) · **Sendbird residue:** none | <paths>
+
+## 1. Summary
+<2–4 sentences: what the app did with Sendbird, what it does now, the headline removals.>
+
+## 2. Migrated
+| Sendbird feature | CometChat equivalent | Files |
+|---|---|---|
+| Group channels + channel list | Conversations + message pane (UI Kit) | src/chat/ChatPage.tsx, … |
+
+## 3. Removed — not available in CometChat
+| Feature | What it did | Removed from | What users lose | Evidence (features.json · `UI Kit:` docs query → result · `SDK:` docs query → result) | Closest CometChat alternative |
+|---|---|---|---|---|---|
+| Scheduled messages | "Send later" in the composer menu | src/chat/Composer.tsx, src/api/schedule.ts, route /scheduled | Can't schedule a message | absent · UI Kit: `search_cometchat_docs "<feature> react ui kit"` → no page · SDK: `search_cometchat_docs "<feature> javascript sdk"` → no page | A server job that sends through the REST API at the chosen time |
+
+### Dev/QA-only code removed (not user features)
+| Code | What it did | Removed from |
+|---|---|---|
+| <debug panel / event simulator / screenshot harness> | <…> | <paths> |
+
+## 4. Behavior changes (migrated, works differently)
+- Open channels are now public groups: members join once, and history persists.
+
+## 5. Your action items
+1. Add your CometChat credentials (App ID, Region, Auth Key for dev) to `<untracked local env file>`. Never put them in a git-tracked file; placeholders are there now.
+2. Create a REST API key and set `COMETCHAT_REST_API_KEY` on the server (the token endpoint + the data script).
+3. Import your history: see `scripts/cometchat-migration/README.md` (dry run first).
+4. **Messages older than ~6 months were NOT imported** (<n> skipped) — CometChat's default retention window (a CometChat-side limit, not Sendbird's). To bring them over, purchase Extended Storage (contact CometChat sales), then re-run the import.
+5. **Re-host media before deleting Sendbird** (<n> attachments). CometChat stores attachment URLs by reference, not the files — re-host them to your own / CometChat media storage, or images and files break once the Sendbird URLs expire.
+6. Enable in the CometChat dashboard: <extensions / AI features the migrated features need>.
+7. Push: upload FCM/APNs credentials to CometChat (see the push setup).
+8. Point your webhooks at the new receiver and pick the events.
+9. Before production: switch from Auth Key login to server-issued auth tokens (if dev login was used).
+10. Remove the Sendbird secrets from your CI and hosting env, then delete the Sendbird app after the cut-over.
+
+## 6. Defaults taken (no questions were asked)
+- <every decision made without asking, e.g. "UIKit mode: replaced Sendbird UIKit with the CometChat UI Kit", "voice-message recorder removed (no voice-notes in this family)">
+
+## 7. Verification
+- Build: `<command>` → <result>
+- Residue search: `sendbird` → <result>
+- Tests: <ran / not present / updated n tests, removed m tests of removed features>
+- Pre-existing issues (were failing before the migration): <list or none>
+```
+
+Rules for the lists:
+- Section 3's main table is for USER-facing features only. Debug panels, event simulators, doc-screenshot harnesses and demo settings go in the Dev/QA-only subsection, which needs no docs evidence. Moving a real user feature there to dodge the evidence rule is a defect.
+- Every REMOVE row names the concrete files and UI entry points it touched, AND its evidence in this exact shape — `features.json`: <result> · `UI Kit:` `search_cometchat_docs "<feature> <platform> ui kit"` → <result> · `SDK:` `search_cometchat_docs "<feature> <platform> SDK"` → <result> (plus REST/live-fetch if used). A row whose cell lacks an explicit **SDK-level** query (the literal `SDK:` label or an `/sdk/` page) is graded as unevidenced, however right the removal is. "Removed polls" alone is not enough. **The Evidence cell is MANDATORY on every row and must never be blank** — this includes narrower/partial removals (e.g. "Threads overview tab" while threaded replies stay): still cite the `features.json` + UI-Kit + SDK queries that show the specific surface has no equivalent. A row with an empty Evidence cell is an incomplete report.
+- **Section 3 is a TABLE, never prose.** Write every removal as a row of the 6-column table above — not as bullets, paragraphs or a list, however well written. A removal outside a table row is ungradeable and the section is read as an incomplete report. (An empty section is the one exception: keep the heading with "None.")
+- "Closest CometChat alternative" must be a real, documented capability (from `features.json` or the docs), or `—`. Never invent one.
+- Order the action items by what unblocks running the app first: credentials first, then data, then production hardening.

package/skills/cometchat-migrate-from-twilio/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: cometchat-migrate-from-twilio
+description: "Migrate an app from Twilio Conversations (or the deprecated Programmable Chat) to CometChat in ONE prompt, on any platform in this pack. Twilio is headless (no UI Kit), so this is client/SDK-mode: keep the app's own UI, swap the data layer to the CometChat Chat SDK (or, for a fresh chat UI, the CometChat UI Kit), rewrite the token server, remove features CometChat lacks, write a data-migration script, uninstall Twilio, verify the build, and end with a report. Triggers: 'migrate from Twilio to CometChat', 'migrate my app to CometChat' (Twilio detected), 'replace Twilio Conversations with CometChat', 'move off Twilio chat', 'twilio-conversations to cometchat', 'twilio programmable chat migration'."
+license: "MIT"
+compatibility: "FROM Twilio Conversations (`@twilio/conversations`, `twilio-conversations` iOS/Android, `twilio_conversations` Flutter) or Programmable Chat (`twilio-chat`, deprecated) → the CometChat family this pack detects. Node >=18 for the data-migration script."
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat migration twilio conversations programmable-chat competitor switch sdk data-import"
+---
+
+> **Ground truth:** the TWILIO side (what to look for) is baked in `references/inventory.md` + `references/feature-map.md` — confirm each hit by reading the user's code and, where unsure, Twilio's current Conversations docs. The COMETCHAT side is never from memory: symbols from the target family's skills + catalog, feature existence from `features.json`, signatures via `cometchat-<family>-core/references/docs-map.md` (Docs MCP first — `RULES.md` → Fetch discipline). REST pages under `DOCS_BASE = https://www.cometchat.com/docs`.
+
+## Companion skills (read first)
+- `cometchat-<family>-core` — the init → login → render (or the Chat SDK init/login) the migrated app lands on; `<family>` resolved in step 1.
+- `cometchat-security` — the server token endpoint that replaces Twilio access tokens.
+
+## Use this skill when
+"migrate my app from Twilio to CometChat", "replace Twilio Conversations", or "migrate my app to CometChat" when `npx @cometchat/skills detect --json` reports `migrate_from` vendor `twilio`. Sendbird/Stream apps → their own skills.
+
+## The single-prompt contract (read before step 1)
+The migration request IS the approval (`RULES.md` → Competitor migration). Run every step to the end in one turn: no plan/approve gate, no questions — take the documented default and record it under *Defaults taken*. Work on a `cometchat-migration` git branch; never commit/push. You DO run the data-import script — but only at the very end and only after the user hands you the credentials (step 8); that single credential prompt is the sole exception to "no questions". Removing Twilio is the requested outcome; non-Twilio code is only rewired. Only STOP if: no Twilio usage found (hand to `cometchat`), the platform has no family in this pack (deliver the inventory as the report), or the app didn't build before you started (record it, migrate anyway, label pre-existing).
+
+## Twilio is headless — so this is client/SDK mode
+Twilio Conversations ships **no UI Kit**; the app already has its **own chat UI** on the Twilio client. Default migration therefore **keeps that UI and swaps the data layer** to the CometChat **Chat SDK** (`cometchat-<family>-core` docs-map → SDK), mapping CometChat objects into the app's existing view models at the boundary. If the user instead wants CometChat's prebuilt UI, offer to replace their UI with the family UI Kit (a bigger change) — but the safe default is data-layer-only.
+
+## Migration workflow (BAKED — do every step, in order)
+Every step applies to every app: users and history exist even in a small app, so steps 4 (`toCometChatId`) and 8 (data script) are ALWAYS delivered; skip only a step whose subject truly doesn't exist (no server → step 7), listed as `skipped: <why>`.
+1. **Detect.** `npx @cometchat/skills detect --json` → framework, `existing_cometchat`, `migrate_from`. Resolve `<family>` (`peers.yaml`; per-platform targets in `references/inventory.md`). Run the app's build once and record pass/fail.
+2. **Inventory.** Grep per `references/inventory.md` (packages, `Client`/`Conversations.Client`, access-token fetch, `getConversationBySid`/`create`, `sendMessage`, `getMessages`, participants, `stateChanged`/message listeners, media, attributes, push, the token server). Record each hit `file:line → purpose`.
+3. **Feature map.** For each Twilio feature, use `references/feature-map.md`, then check the CometChat id in the family's `features.json` AND the docs (UI Kit + SDK). Present → migrate. **An empty MCP search is INCONCLUSIVE, not "unsupported":** re-query with CometChat vocabulary (e.g. "media recorder"/"voice notes", not "voice message recorder"; drop version/platform over-qualifiers), then **LIVE-FETCH** the likely docs page (`fetch_cometchat_doc_page`, or a plain fetch of the docs URL + `.md`), then cross-check the family **CATALOG** (installed component/symbol list). Mark **UNSUPPORTED only** when the CATALOG lacks it AND the live doc fetch (not merely an empty MCP search) also finds nothing (then remove + list). Never call unsupported from memory or from an empty search; if it genuinely can't be verified, KEEP it + `needs-verification`.
+4. **Install CometChat + wire init/login** per `cometchat-<family>-core`. **Identity:** the CometChat UID is the app's Twilio **identity** through one shared `toCometChatId()` (`references/concept-map.md` §IDs), used by client login, the token server, and the data script.
+5. **Replace the data layer, file by file** (`references/concept-map.md`): Twilio `Client` init/token → CometChat init/login; `Conversation` → a user or group conversation; `Participant` → group member; `Message` send/get → CometChat send/messages request; `stateChanged`/`messageAdded` listeners → CometChat listeners (removed on unmount); media → attachments; `attributes` → metadata. Keep the app's UI; map at the boundary. Remove each Twilio import as its last use goes.
+6. **Remove unsupported features FULLY** — code, UI entry points, state, deps, tests. Log each for the report.
+7. **Server side.** Replace the Twilio **access-token** endpoint (API Key/Secret + Conversations Service SID → JWT) with a CometChat auth-token endpoint (`cometchat-security`; create user if missing → `POST /v3/users/{uid}/auth_tokens`). Map Twilio webhooks (`onMessageAdded`, etc.) to CometChat webhooks; drop/list any with no equivalent. Replace other Conversations REST calls with CometChat REST, or remove + list.
+8. **Data-migration script — write it, then run the import for the user.** `scripts/cometchat-migration/` per `references/data-migration.md`: export users/conversations/participants/messages from the Twilio Conversations REST API → transform with the shared `toCometChatId()` → import via the CometChat Data Import API. When the code migration is done, tell the user the **data-import script is ready** and ask for the credentials it needs — the Twilio keys (`TWILIO_ACCOUNT_SID`, `TWILIO_API_KEY`, `TWILIO_API_SECRET`, `TWILIO_CONVERSATIONS_SERVICE_SID`) and the CometChat **App ID, Region and full-access REST API key**. (This one credential prompt is the sole exception to the no-questions contract.) The moment they provide them, **RUN the import yourself** from env vars — never write secrets into a repo file: a `--dry-run` first (show counts), then the real import, then report results. Only messages within CometChat's **6-month retention window** import — tell the user to **reach out to CometChat to import messages older than 6 months**. If they decline to share credentials, leave running it as an action item.
+9. **Uninstall Twilio** — remove every Twilio dependency (`@twilio/conversations`, `twilio-conversations`, `twilio-chat`, the server `twilio` SDK) + lockfile, env vars, native config, CI secrets. Reinstall. Update the app's own docs (README/`.env.example`) and rename `twilio*` identifiers.
+10. **Verify** (§Verify it works). Fix build errors you introduced. No live tests unless asked.
+11. **Report.** Write `COMETCHAT_MIGRATION.md` from `references/report-template.md`; END the reply with its **Removed** + **Action items** lists.
+
+## Common pitfalls
+- **Identities that CometChat rejects.** Twilio `identity` strings can hold characters CometChat UIDs can't (alpha-dash, ≤100, lowercased). Sanitize with one shared function everywhere.
+- **1:1 vs group.** A Twilio conversation with exactly two participants → a CometChat **user** conversation, not a two-person group.
+- **Optimistic send / pagination / listeners** differ — see `references/concept-map.md` behavioral gotchas; keep the app's UX identical, only the data source changes.
+- **Access token ≠ Auth Key.** Twilio's client token maps to a CometChat **auth token** (server-minted), not the Auth Key. Never ship the Auth Key.
+- **Half-removed features / left-behind listeners** — remove entry points too; remove every listener on unmount.
+- **Programmable Chat vs Conversations** — older apps use `twilio-chat` (Channel/Member/Message); the mapping is the same shape, note which the app uses.
+
+## Verify it works
+The app builds with the family's normal command · zero Twilio residue (`grep -rIiE 'twilio' .` finds only the report + data script) · every CometChat symbol exists in the catalog · every migrated feature is in `features.json`/docs; every UNSUPPORTED item is in the report with its files · client login, token server, and data script all use the same `toCometChatId()`.
+
+**RUN it and read the logs — a compile is NOT a working app (do this; don't skip).** When you're done implementing, START the app and confirm it LOADS with the chat surface rendered and NO errors in the browser console / dev-server terminal (native: platform run + logs). Fix EVERY runtime error you introduced — a `Cannot read properties of undefined` from a half-migrated reference, or an SDK enum/class read at module-load before the SDK is ready, is a migration bug (see `cometchat-<family>-troubleshooting`). If it can't be started here, SAY SO and give the user the exact run command + what to watch for — never silently skip this.

package/skills/cometchat-migrate-from-twilio/references/concept-map.md

@@ -0,0 +1,49 @@
+# Twilio Conversations → CometChat concept map
+
+Maps **roles**, not code. Take every CometChat name/signature from the target family's skills + catalog + docs (`cometchat-<family>-core/references/docs-map.md`). Platforms differ (web `on*Click`, RN `on*Press`, native init shapes); never port a snippet across families. Twilio is headless, so the default is **client/SDK mode** — keep the app's UI, swap the data layer.
+
+## IDs (do this first)
+CometChat UIDs/GUIDs are alpha-dash (`a-z 0-9 - _`), ≤100, lowercased. Twilio `identity` and `uniqueName`/`sid` are not constrained the same way. Emit ONE deterministic helper (client + server + data script share it exactly):
+```js
+export function toCometChatId(id) {
+  const raw = String(id);
+  let out = raw.toLowerCase().replace(/[^a-z0-9_-]/g, "_");
+  if (out !== raw || out.length > 100) {
+    let h = 0; for (const c of raw) h = (Math.imul(31, h) + c.codePointAt(0)) >>> 0;
+    out = `${out.slice(0, 90)}_${h.toString(36)}`;
+  }
+  return out;
+}
+```
+Port literally to Swift/Kotlin/Dart when native. Twilio `identity` → CometChat `uid`; conversation `sid`/`uniqueName` → `guid`.
+
+## Core concepts
+| Twilio Conversations | CometChat (role) | Notes |
+|---|---|---|
+| Account SID + API Key/Secret + Conversations Service SID | App ID + Region (client) + REST API Key (server) | region `us`/`eu`/`in`; keep secrets server-side |
+| `new Client(token)` / `Client.create(token)` + `stateChanged`→`initialized` | init (`initFromSettings`) then login (`loginWithAuthToken`) | init once before render; login before any data call |
+| Access token (JWT, server-minted, `updateToken` on expiry) | CometChat **auth token** (server-minted; re-login on expiry) | `cometchat-security`; not the Auth Key |
+| Conversation with 2 participants | a **user** conversation (1:1) | receiver = the other participant's uid |
+| Conversation (3+), `friendlyName`/`uniqueName` | Group (`guid = toCometChatId(uniqueName || sid)`, name = friendlyName) | private vs public per your model |
+| Participant (`identity`) | group member (uid) | `add(identity)` → add member; non-chat (SMS/WhatsApp) participants have no equivalent (feature-map) |
+| `sendMessage(body)` / `MessageBuilder.addMedia` | send text / media message | media → `data.attachments` |
+| `getMessages(...)` (paginator) | messages request builder | paging, not a local store |
+| `attributes` (JSON on conversation/message/participant/user) | metadata | carry across |
+| `client.on('messageAdded'|...)` / `conversation.on(...)` | CometChat listeners (added with an id, removed on unmount) | one place; remove on teardown |
+| `typing()` / read horizon / unread count | typing + delivery/read receipts | separate CometChat calls/events |
+| push registration id | the family's push skill | Notifications product |
+
+## Behavioral differences (keep the UX identical)
+- **Optimistic send:** if the app inserts a pending message on `sendMessage` and reconciles on the returned message/`messageAdded`, keep that: insert a local placeholder, replace it with CometChat's resolved message (roll back on reject). CometChat's `sendMessage` resolves with the sent message.
+- **Pagination:** Twilio's message paginator → CometChat's `MessagesRequestBuilder` (`setLimit(n)`, `fetchPrevious`/`fetchNext`), one builder instance per conversation for the cursor; map scroll-to-load to it.
+- **Listeners:** each Twilio `on(...)` becomes a CometChat listener with a unique id, removed on unmount/dispose — reuse the app's existing subscribe/unsubscribe points.
+- **Connection state:** Twilio `connectionStateChanged` → CometChat connection listeners; keep the app's online/offline UI wired.
+- **Client/SDK mode:** keep the app's components and screens; replace only the service/store/hook talking to Twilio, mapping CometChat objects into the app's existing view models at the boundary. The app should look and behave the same — only the data source changed. Fetch each CometChat method/shape from the SDK docs, never by analogy to the Twilio API.
+
+## Server
+| Twilio server piece | CometChat replacement |
+|---|---|
+| Access-token endpoint (`AccessToken` + `ConversationsGrant`, API Key/Secret + Service SID) | your endpoint: create user if missing → `POST /v3/users/{uid}/auth_tokens` (REST API Key, server env) — `cometchat-security` |
+| Webhooks (`onMessageAdded`, scoped/global, `X-Twilio-Signature`) | CometChat webhooks (`/rest-api/management-apis/webhooks/overview`); drop the Twilio signature check |
+| Conversations REST (create conversation/participant/message) | CometChat REST equivalents, or REMOVE + list |
+| Env `TWILIO_API_KEY`/`TWILIO_API_SECRET`/`TWILIO_CONVERSATIONS_SERVICE_SID` | `COMETCHAT_APP_ID`/`REGION`/`REST_API_KEY` (placeholders + action item) |

package/skills/cometchat-migrate-from-twilio/references/data-migration.md

@@ -0,0 +1,50 @@
+# Data migration — Twilio Conversations history → CometChat (write it; the user runs it)
+
+CometChat supports historical import (bulk, this script) and live migration (bridged, contact sales) — `/fundamentals/data-import-and-migration`. Default here = **hard switch** in a maintenance window; for zero-downtime, add the "contact CometChat sales for live migration" action item.
+
+Emit `scripts/cometchat-migration/` as its own tiny package (keeps working after Twilio is removed):
+- `package.json` (`"type":"module"`), dependency: the `twilio` server SDK pinned to the app's major.
+- `migrate.mjs` (Node ≥18, global `fetch` for CometChat), `id.mjs` (a copy of `toCometChatId`), `README.md`.
+Secrets from env (`TWILIO_ACCOUNT_SID`, `TWILIO_API_KEY`, `TWILIO_API_SECRET`, `TWILIO_CONVERSATIONS_SERVICE_SID`, `COMETCHAT_APP_ID`, `COMETCHAT_REGION`, `COMETCHAT_REST_API_KEY`), never a repo file. **The agent runs it for the user** once they provide those credentials (SKILL.md step 8): a `--dry-run` first, then the import — always from env vars, never hardcoded or committed. If the user declines to share credentials, leave running it as an action item instead.
+
+## 1. Export from Twilio (Conversations REST)
+Use the `twilio` server SDK against the Conversations Service. **Check method names against Twilio's current REST docs while writing, note diffs in the README.**
+| Data | Call | Paging |
+|---|---|---|
+| Users | `client.conversations.v1.users.list({limit})` | SDK auto-pages |
+| Conversations | `client.conversations.v1.services(SERVICE_SID).conversations.list({limit})` | SDK auto-pages |
+| Participants | `…conversations(sid).participants.list()` | per conversation |
+| Messages | `…conversations(sid).messages.list({order:'asc', limit})` | per conversation, oldest→newest |
+| Media | resolve each message's media SID → temporary content URL (Media Content Service) | per media |
+Back off on 429. Write each export to `export/*.jsonl` so a failed run resumes.
+
+## 2. Transform
+- **User:** `uid = toCometChatId(identity)`, `name = friendlyName || identity`, `avatar` from attributes if present, `metadata = { ...attributes, twilioIdentity: identity }`, `createdAt = seconds(dateCreated)`.
+- **Conversation:**
+  - exactly 2 participants → **no group**; messages become user-to-user.
+  - else: `guid = toCometChatId(uniqueName || sid)`, `name = friendlyName || sid`, `type` per your model (default `private`), `owner` = the creator/first participant uid, `metadata = { twilioSid: sid, ...attributes }`.
+- **Member:** key `${guid}_member_${uid}`, scope `participant` (elevate any admin you track), `joinedAt = seconds(dateCreated)`.
+- **Message:**
+  - `muid = message.sid`, `sender = toCometChatId(author)`, `receiverType`+`receiver`, `sentAt = Math.floor(Date.parse(dateCreated)/1000)`.
+  - text → `category:"message"`, `type:"text"`, `data.text = body`.
+  - media → one media message per media: `type` from `contentType` (`image`/`video`/`audio`/`file`), `data.attachments=[{url, name:filename, mimeType:contentType, size}]`. Twilio temporary URLs EXPIRE — re-host to your own/CometChat storage (action item).
+  - `attributes` → `data.metadata`.
+- **Seconds, not milliseconds** everywhere. **Not carried by the import API:** reactions, threads, read horizons beyond `readAt`/`deliveredAt`, typing — say so in the report.
+
+## 3. Import into CometChat (Data Import API)
+Base `https://${COMETCHAT_APP_ID}.api-${COMETCHAT_REGION}.cometchat.io/v3/data_import`, headers `apikey`, `content-type: application/json`. Fetch each page for the full payload:
+`/rest-api/data-import-apis/users/import-users` · `/groups/import-groups` · `/groups/import-group-members` · `/messages/import-messages`.
+| Order | Endpoint | Body |
+|---|---|---|
+| 1 | `/data_import/users` | `{ "users": { "<uid>": { uid, name, avatar?, metadata?, createdAt? } } }` |
+| 2 | `/data_import/groups` | `{ "groups": { "<guid>": { guid, name, type, owner, metadata?, createdAt? } } }` |
+| 3 | `/data_import/members` | `{ "members": { "<guid>_member_<uid>": { memberId, guid, uid, scope?, joinedAt? } } }` |
+| 4 | `/data_import/messages` | `{ "messages": { "<muid>": { muid, sender, receiverType, receiver, category, type, data, sentAt } } }` |
+Batch **≤50 entities/request**, **≤60 requests/min** (throttle ~1/s, retry `ERR_TOO_MANY_REQUESTS`). Per-entity `success`; log failures to `import-errors.jsonl` and continue. Idempotent on re-run. Order: users → groups → members → messages, oldest first. Print counts (exported, imported, skipped, failed).
+
+## README.md (emit it)
+1. Create a full-access REST API key in the CometChat dashboard.
+2. `cd scripts/cometchat-migration && npm install`; export the env vars.
+3. `node migrate.mjs --dry-run` (export + transform + counts, no import).
+4. `node migrate.mjs`.
+5. Spot-check in the dashboard; re-host media if Twilio URLs expired; delete `export/` (user data) and this folder after cut-over.

package/skills/cometchat-migrate-from-twilio/references/feature-map.md

@@ -0,0 +1,27 @@
+# Twilio Conversations → CometChat feature map
+
+**How to use:** for each feature the ledger shows, find its row; check the CometChat **id** in the TARGET family's `features.json` (match id OR name). Found → migrate via *Via*. Not found → search the docs at BOTH levels (UI Kit `search_cometchat_docs "<feature> <platform> ui kit"` AND SDK `"<feature> <platform> sdk"`). Documented at either → migrate (no UI Kit drop-in ≠ unsupported — build on the SDK). Documented at neither → apply *If absent*. Twilio is headless, so most of these are wired on the **CometChat Chat SDK** in the app's own UI (the *Via* names the closest UI-Kit component for the optional UI-Kit path).
+
+**Actions:** `REMOVE` → UNSUPPORTED, remove fully + list; `CHANGE` → nearest equivalent, list the difference. Never REMOVE without a docs query in both levels; a docs-tool outage is never "unsupported" (`RULES.md`).
+
+| Twilio feature (signals) | CometChat id | Via | If absent |
+|---|---|---|---|
+| Conversations client + token login (`Client`, access token) | `core-chat-surface` | core / SDK init+login | — |
+| Conversation list / subscribed conversations (`getSubscribedConversations`) | `core-chat-surface`, `users-groups` | conversations request builder / `CometChatConversations` | — |
+| 1:1 conversation (2 participants) | `text-messaging` (a **user** conversation) | core / SDK | — |
+| Group conversation (3+ participants, `friendlyName`) | `users-groups` (a group) | core / components | — |
+| Send / get / edit / delete messages (`sendMessage`, `getMessages`, `updateBody`, `remove`) | `text-messaging` | core / SDK | — |
+| Media messages (`MessageBuilder.addMedia`, `media`) | `media-file-attachments` | core / features | CHANGE (single file per message) |
+| Typing indicators (`typing()`, `typingStarted`) | `typing-indicators` | core / features | CHANGE |
+| Read horizon / unread count (`setAllMessagesRead`, `getUnreadMessagesCount`, delivery receipts) | `delivery-read-receipts` | core / features | CHANGE |
+| Participants add/remove (`add(identity)`, `removeParticipant`) | group member management | components / SDK | — |
+| Non-chat participants (SMS / WhatsApp / MMS via `addNonChatParticipant`) | none | docs | REMOVE (CometChat is in-app chat; SMS/WhatsApp bridging is a Twilio-specific product — list it) |
+| Conversation/message/participant `attributes` (JSON) | metadata (user/group/message) | core / SDK | — |
+| User profile (`User`, friendlyName, attributes, online/notifiable) | user name / avatar / metadata / presence | core | CHANGE (presence model differs) |
+| Push (registration id, FCM/APNs binding) | `push-notifications` | push | action item (credentials in dashboard) |
+| Webhooks (`onMessageAdded`, scoped/global) | CometChat webhooks | server | REMOVE + list any event with no equivalent |
+| Reactions | native? no — Twilio has no built-in reactions | `reactions` | (if the app hand-built reactions on attributes) migrate to `reactions`; else n/a |
+| Threads / replies | Twilio has no native threads | `threaded-replies` | n/a unless the app built them; then migrate |
+| Media redaction / message scheduling / delivery to SMS | none | docs | REMOVE + list |
+
+Twilio Conversations is deliberately minimal (messaging + participants + media + attributes), so most migrations are **feature-for-feature clean** with few removals — the big Twilio-only items are the **omnichannel bridges** (SMS/WhatsApp/MMS participants), which have no CometChat equivalent and are removed + listed. A feature not in this table: treat as `none` — check `features.json` + docs (both levels), then REMOVE or CHANGE, and say which.

package/skills/cometchat-migrate-from-twilio/references/inventory.md

@@ -0,0 +1,53 @@
+<!-- family-agnostic: per-platform-by-design — this reference IS the per-platform Twilio inventory + target-family table; one row per platform by design. -->
+# Twilio Conversations inventory — what to find, and where it goes
+
+Search case-insensitively. Skip `node_modules/`, `Pods/`, `build/`, `.dart_tool/`, `.gradle/`, `.git/`. "Twilio" is distinctive; match the package + class names below. Twilio Conversations is **headless** — the app has its own UI on the Twilio client, so most hits are in a data/service layer, and each becomes a ledger row (`file:line → purpose`).
+
+## Target family (where each platform lands)
+| App platform (detect `framework`) | Twilio packages you'll see | CometChat family (`peers.yaml`) | Default = client/SDK mode → | Optional (fresh UI) → |
+|---|---|---|---|---|
+| React / Next / Vite / CRA / Astro | `@twilio/conversations` (+ `twilio-chat` if legacy) | `react-v7` | the core's Chat SDK fallback (`@cometchat/chat-sdk-javascript`) | `cometchat-react-v7-core` UI Kit |
+| Angular | `@twilio/conversations` | `angular-v5` | JS Chat SDK | `cometchat-angular-v5-core` |
+| React Native / Expo | `@twilio/conversations` (RN-compatible) | `react-native` | `cometchat-react-native-sdk` | `cometchat-react-native-core` |
+| iOS (Swift) | `TwilioConversationsClient` (pod/SPM `twilio-conversations`) | `ios` | the iOS core's SDK fallback (`CometChatSDK`) | `cometchat-ios-core` |
+| Android | `com.twilio:conversations-android` | `android-v6` | `cometchat-android-v5-sdk` | `cometchat-android-v6-core` |
+| Flutter | `twilio_conversations` | `flutter-v6` | the Flutter core's SDK fallback (`cometchat_sdk`) | `cometchat-flutter-v6-core` |
+| Server (Node, Python, Go, Java, Ruby, PHP, C#) | `twilio` server SDK → Conversations REST; access-token minting | — (REST) | — | CometChat REST (`/rest-api/…`) |
+
+Because Twilio ships no UI Kit, the **default** target is client/SDK mode (keep the app's UI). Offer the UI Kit path only if the user wants CometChat's prebuilt UI. A platform not in this table → STOP: report only.
+
+## Grep signals
+**Manifests**: `package.json`, `Podfile`, `Package.swift`, `build.gradle(.kts)`, `pubspec.yaml`, `requirements.txt`, `go.mod`, `Gemfile`, `composer.json`, `*.csproj` → `twilio/conversations`, `twilio-conversations`, `twilio_conversations`, `@twilio/conversations`, `twilio-chat` (legacy Programmable Chat), `TwilioConversationsClient`, `com.twilio:conversations`.
+
+**Client / auth**:
+- JS: `Client` / `Conversations.Client`, `new Client(token)`, `Client.create(token)`, `client.updateToken(...)`, `'stateChanged'` → `'initialized'`, `'tokenAboutToExpire'` / `'tokenExpired'`.
+- iOS: `TwilioConversationsClient.conversationsClient(withToken:...)`.
+- Android: `ConversationsClient.create(...)`.
+- Flutter: `TwilioConversations.create(...)`.
+- **Access token fetch**: a call to your server for a Twilio JWT (the client never holds the API secret).
+
+**Conversations (channels)**:
+- `client.getConversationBySid` / `getConversationByUniqueName` / `createConversation` / `getSubscribedConversations`.
+- `conversation.add(...)` / `join()` / `leave()` / `delete()`, `friendlyName`, `uniqueName`, `attributes`.
+
+**Participants**:
+- `conversation.getParticipants()`, `add(identity)` / `addNonChatParticipant` (SMS/WhatsApp), `removeParticipant`, `participant.identity`.
+
+**Messages**:
+- `conversation.sendMessage(...)` (text or a `MessageBuilder` with media), `getMessages(...)`, `message.body`, `message.attributes`, `message.media` / `attachedMedia`, `updateBody`, `remove`.
+- Delivery/read: `conversation.setAllMessagesRead()`, `getUnreadMessagesCount()`, `advanceLastReadMessageIndex`, `AggregatedDeliveryReceipt` / `DetailedDeliveryReceipt`.
+- Typing: `conversation.typing()`, `'typingStarted'` / `'typingEnded'`.
+
+**Events**: `client.on('conversationAdded'|'messageAdded'|'participantJoined'|'typingStarted'|'connectionStateChanged'|...)`, `conversation.on('messageAdded'|...)`.
+
+**Media**: `message.media.getContentTemporaryUrl()`, `MessageBuilder.addMedia(...)`, `media.filename`/`contentType`/`size`.
+
+**Other**: `user`/`User` (friendlyName, attributes, online/notifiable), push (`client.setPushRegistrationId` / FCM/APNs binding), `attributes` (JSON on conversation/message/participant/user).
+
+**Legacy Programmable Chat** (`twilio-chat`, deprecated): `Channel`, `Member`, `Message`, `client.getChannelBySid` — same shapes as Conversations; map identically and note it's the legacy SDK.
+
+**Server**: `AccessToken` + `ChatGrant`/`ConversationsGrant` (API Key SID/Secret + Conversations Service SID), Conversations REST (`conversations.v1.conversations…`), webhooks (`onMessageAdded`, `onConversationAdded`, scoped/global).
+
+**Env / config**: `TWILIO_ACCOUNT_SID`, `TWILIO_API_KEY`, `TWILIO_API_SECRET`, `TWILIO_CONVERSATIONS_SERVICE_SID`, `VITE_TWILIO_*`, tokens endpoints; CI secrets `TWILIO_*`.
+
+**Tests / mocks**: `jest.mock('@twilio/conversations')`, fake `Client`/`Conversation`.

package/skills/cometchat-migrate-from-twilio/references/report-template.md

@@ -0,0 +1,52 @@
+# Report template — `COMETCHAT_MIGRATION.md`
+
+Write this at the repo root from the ledger. Keep an empty section's heading with "None." Then END the chat reply with sections 3 and 5 pasted in full (SKILL step 11).
+
+```markdown
+# Twilio Conversations → CometChat migration
+
+**Branch:** cometchat-migration (from <base>; <n> uncommitted files came along) · **Platform:** <framework> → CometChat <family label> · **Mode:** client/SDK (default) | UI Kit
+**Build:** ✅ passes (`<command>`) | ❌ <n> errors (below) · **Twilio residue:** none | <paths>
+
+## 1. Summary
+<2–4 sentences: what the app did on Twilio Conversations (headless client + own UI), what it does now (CometChat Chat SDK behind the same UI, or UI Kit), the headline removals.>
+
+## 2. Migrated
+| Twilio feature | CometChat equivalent | Files |
+|---|---|---|
+| Conversations client + access-token login | CometChat init + `loginWithAuthToken` | src/chat/client.ts, server/token.ts |
+| Conversation list / messages / participants | conversations + messages request builders + group members | src/chat/*, … |
+
+## 3. Removed — not available in CometChat
+| Feature | What it did | Removed from | What users lose | Evidence (features.json · docs query → result) | Closest CometChat alternative |
+|---|---|---|---|---|---|
+| Non-chat participants (SMS / WhatsApp / MMS) | Bridged the conversation to phone numbers via `addNonChatParticipant` | src/…, server/… | Reaching users over SMS/WhatsApp from the chat | Not in features.json · UI Kit `"sms whatsapp participant"` → no page · SDK `"non-chat participant sms"` → no page (Twilio omnichannel is vendor-specific) | — (use a separate SMS provider if still needed) |
+
+## 4. Behavior changes (migrated, works differently)
+- Presence/online model differs from Twilio's `notifiable`/`online` user flags.
+- Conversations with exactly two participants are now 1:1 user conversations, not two-person groups.
+
+## 5. Your action items
+1. Add your CometChat credentials to an untracked env file (App ID, Region, Auth Key for dev). Placeholders are there now — never commit them.
+2. Create a REST API key; set `COMETCHAT_REST_API_KEY` on the server (token endpoint + data script).
+3. Import history: `scripts/cometchat-migration/README.md` (dry run first). Re-host media — Twilio media URLs expire.
+4. Enable in the CometChat dashboard: <extensions / AI the migrated features need>.
+5. Push: upload FCM/APNs credentials to CometChat.
+6. Point webhooks at the new receiver; pick events.
+7. Before production: server-minted auth tokens (already wired if a token server existed).
+8. Remove `TWILIO_*` secrets from CI/hosting; close the Twilio Conversations service after cut-over.
+
+## 6. Defaults taken (no questions were asked)
+- <e.g. "client/SDK mode: kept the app's UI, swapped the data layer to the CometChat Chat SDK"; "skipped: <step> — <why>">
+
+## 7. Verification
+- Build: `<command>` → <result>
+- Residue search: `twilio` (case-insensitive, excl. node_modules/dist/.git) → <result>
+- Tests: <ran / none / updated n, removed m>
+- Pre-existing issues (failing before the migration): <list or none>
+```
+
+Rules for the lists:
+- Every REMOVE row names concrete files + UI entry points AND its evidence (features.json + both docs queries). Debug/QA-only code goes in a Dev/QA-only subsection, no evidence needed.
+- "Closest CometChat alternative" must be a real documented capability or `—`. Never invent one.
+- Order action items by what unblocks running the app first: credentials → data → production hardening.