@cometchat/skills 4.4.2 → 5.0.1

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

@@ -0,0 +1,108 @@
+# Stream → 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: Stream feature (signals) · CometChat id · Via · If absent.
+
+### Messaging basics
+
+| Stream feature (signals) | CometChat id | Via | If absent |
+|---|---|---|---|
+| Messaging / team / commerce / gaming channels (`client.channel(type, id)`) | `core-chat-surface`, `users-groups`, `text-messaging` | core | — (always present) |
+| Channel list with unread counts, last message (`ChannelList`, `countUnread`) | `core-chat-surface` | core | — |
+| Edit / delete messages (`updateMessage`, `deleteMessage`) | `text-messaging` | core | — |
+| Typing indicators (`keystroke`, `typing.start`) | `typing-indicators` | core / features | CHANGE (drop the indicator) |
+| Read state / receipts (`markRead`, `message.read`, `read` array) | `delivery-read-receipts` | core / features | CHANGE |
+| Mark as unread (`markUnread`) | `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 |
+| Image / file / video attachments (`sendImage`, `sendFile`, `attachments`) | `media-file-attachments` | core / features | CHANGE (single file per message) |
+| Voice recordings (`voiceRecording` attachment, audio recorder) | `voice-notes` | features | REMOVE the recorder, keep audio-file playback |
+| Threads (`parent_id`, `<Thread>`) | `threaded-replies` | features / placement | REMOVE the thread UI |
+| "Also send to channel" (`show_in_channel`) | none | docs | CHANGE (the reply stays in the thread) |
+| Threads overview list (`ThreadList`, `queryThreads`) | none | docs | REMOVE |
+| Quoted replies (`quoted_message_id`) | `quoted-replies` | features | REMOVE |
+| Reactions (`sendReaction`) | `reactions` | features | REMOVE |
+| Cumulative reaction scores ("claps", `score`), custom reaction types | none | docs | CHANGE (one reaction per emoji per user) |
+| Mentions (`mentioned_users`) | `mentions` | features | REMOVE the mention picker, keep plain text |
+| Polls (`createPoll`, `castPollVote`, `poll_id`) | `polls` | features | REMOVE |
+| Message search (`client.search`, `ChannelSearch`/`SearchBar`) | `message-search` | features / placement | REMOVE |
+| Pinned messages (`pinMessage`, `pinned_messages`) | `pin-message` | features | REMOVE |
+| Message reminders / save for later (`createReminder`) | `reminders` / `save-message` | features | REMOVE |
+| Silent / system messages (`silent: true`, `type: "system"`) | none | docs | CHANGE (sent as normal / action messages) |
+| Drafts (`createDraft`, composer drafts) | none | docs | REMOVE the server-side drafts |
+| Translation (`translateMessage`, auto-translation) | `message-translation` | features | REMOVE |
+| Link previews / URL enrichment (`og_scrape_url`) | `link-preview` | features | CHANGE (plain links) |
+| Giphy (`/giphy`, giphy attachments) | `gifs` | features | REMOVE |
+| Custom slash commands (`commands`, custom command webhook) | none | docs | REMOVE |
+| Location sharing, live location (`SharedLocation`, `startLiveLocationSharing`) | none | docs | REMOVE |
+| Custom attachments / `extraData` on messages | `custom-message-types` (Angular also `card-messages`) + message metadata | customization / features | CHANGE (render as text + metadata) |
+
+### Users and presence
+
+| Stream feature (signals) | CometChat id | Via | If absent |
+|---|---|---|---|
+| Presence, last active (`online`, `last_active`, `user.presence.changed`) | `user-presence` | core | CHANGE |
+| User custom fields (`extraData`, `image`, `name`) | user name / avatar / metadata (core SDK) | core | — |
+| Block users (`blockUser`) | `block-unblock-user` (iOS), else the core SDK block-users call | core / docs | REMOVE |
+| Mute users (`muteUser`) | none (check the notification-preferences docs; muting a 1:1 conversation is covered by mute conversations) | docs | REMOVE |
+
+### Channels and moderation
+
+| Stream feature (signals) | CometChat id | Via | If absent |
+|---|---|---|---|
+| Livestream channels (`livestream` type, large audiences) | `users-groups` (a **public** group) | core | CHANGE (over 300 members → no receipts/typing) |
+| Join a public/preview channel (channel preview + Join button, `addMembers`, `channel.watch`) | join a public group: `CometChatGroups` (joinable list) + the SDK's `CometChat.joinGroup(guid, type)` (`/sdk/<platform>/groups-join-leave`) | components / SDK | REMOVE |
+| Member-based 1:1 channels (`!members-…`, 2 members) | a **user** conversation | core | — |
+| Channel name, image, custom fields (`channel.data`, `extraData`) — incl. editing them | group name / icon / metadata; editing = the SDK's update-group call (`/sdk/<platform>/update-group`) | core / SDK | — |
+| Channel roles, permissions, grants (`channel_role`, custom roles) | group scopes admin / moderator / participant (+ CometChat roles, docs) | components / docs | CHANGE |
+| Ban / remove members, banned list + unban (`banUser`, `removeMembers`, `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 |
+| Shadow ban (`shadowBan`) | none | docs | REMOVE |
+| Freeze channel, slow mode (`frozen`, `enableSlowMode`) | none | docs | REMOVE |
+| Invites with accept/reject (`inviteMembers`, `acceptInvite`) | none (members are added directly) | docs | CHANGE (invite = add member) + REMOVE the accept/reject UI |
+| Mute a channel per user (`channel.mute`) | notification preferences: mute conversations (`/notifications/preferences`) | push / SDK | REMOVE |
+| Hide / pin / archive a channel per user (`hide`, `pin`, `archive`) | none | docs | REMOVE |
+| Truncate channel (`truncate`) | none (check the delete-conversation docs) | docs | REMOVE |
+| Flag / report (`flagMessage`, `flagUser`) | `report-message` / `moderation` | features | REMOVE |
+| AutoMod, blocklists, review queue (dashboard) | `moderation` | features + dashboard | action item: recreate the rules |
+
+### Push, calls and other products
+
+| Stream feature (signals) | CometChat id | Via | If absent |
+|---|---|---|---|
+| Push devices (`addDevice(token, 'firebase' / 'apn')`, push templates) | `push-notifications` | push | action item (credentials in the dashboard) |
+| Push preferences (`setPushPreferences`, per-channel) | notification preferences: mute conversations, DND, schedules (`/notifications/preferences`) | push / SDK | REMOVE only what the preferences page lacks |
+| Stream Video calls, ringing (`StreamCall`, `call.ring`) | `voice-video-calls` | calls (or the headless calls peer) | REMOVE |
+| Video livestream, audio rooms (Stream Video) | `live-streaming` | features / docs | REMOVE |
+| **Activity Feeds** (`getstream`, `@stream-io/feeds-*`, `feed(`, `addActivity`, follows) | none | — | **REMOVE** (no CometChat equivalent) |
+| AI assistant (`ai_indicator`, Stream AI components) | `ai-assistant`, `ai-agents`, `smart-reply`, `conversation-summary` | features | REMOVE |
+| Offline storage (`@op-engineering/op-sqlite`, `stream_chat_persistence`, `StreamOfflinePluginFactory`, the local DB) | none | core | CHANGE (online-first; list the offline gap) |
+
+### Look and feel, server
+
+| Stream feature (signals) | CometChat id | Via | If absent |
+|---|---|---|---|
+| Theme, CSS variables (`--str-chat__*`), `StreamChatTheme`, `ChatTheme`, `Appearance` | theming | customization | — |
+| i18n (`Streami18n`, `StreamI18nService`, `stream_chat_localizations`) | localization (docs) | customization | CHANGE (the kit's defaults) |
+| Webhooks (`verifyWebhook`, `x-signature`) | CometChat webhooks | server (SKILL step 7) | REMOVE (and list) each event with no equivalent |
+| Before-message-send hook, SQS/SNS delivery | none (check the moderation / webhook docs) | server / docs | REMOVE |
+
+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-getstream/references/inventory.md

@@ -0,0 +1,82 @@
+<!-- family-agnostic: per-platform-by-design — this reference IS the per-platform Stream inventory + target-family table; one row per platform by design. -->
+# Stream (GetStream) inventory — what to find, and where it goes
+
+Search case-insensitively. Skip `node_modules/`, `Pods/`, `build/`, `.dart_tool/`, `.gradle/` and `.git/`. "Stream" is also a common English word, so match the **package and type names below**, never the bare word `stream`. A package hit tells you Stream is present. The **import/API hits** tell you *what the app does with it*, and each one becomes a ledger row (`file:line → purpose`).
+
+## Target family (where each platform lands)
+| App platform (detect `framework`) | Stream packages you'll see | CometChat family (`peers.yaml`) | UI SDK mode → | Client mode (own UI) → |
+|---|---|---|---|---|
+| React / Next / Vite / CRA / Astro / React Router | `stream-chat-react`, `stream-chat`, `@stream-io/stream-chat-css`, `@stream-io/video-react-sdk` | `react-v7` | `cometchat-react-v7-core` + `-components`/`-placement` | the core's SDK fallback (`@cometchat/chat-sdk-javascript`, docs-map → SDK docs) |
+| Angular | `stream-chat-angular`, `stream-chat`, `@ngx-translate/core` (Stream i18n) | `angular-v5` | `cometchat-angular-v5-core` | the core's SDK fallback (JS Chat SDK) |
+| React Native / Expo | `stream-chat-react-native`, `stream-chat-expo`, `stream-chat`, `@stream-io/video-react-native-sdk` | `react-native` | `cometchat-react-native-core` | `cometchat-react-native-sdk` |
+| iOS (Swift) | SPM `stream-chat-swift` (`StreamChat`, `StreamChatUI`), `stream-chat-swiftui` (`StreamChatSwiftUI`), `stream-video-swift`; pods `StreamChat`, `StreamChatUI`, `StreamChatSwiftUI` | `ios` | `cometchat-ios-core` (UIKit; host SwiftUI screens via a representable) | the iOS core's SDK fallback (`CometChatSDK`) |
+| Android | `io.getstream:stream-chat-android-client`, `-offline`, `-state`, `-ui-components` (Views), `-compose`, `io.getstream:stream-video-android-*` | `android-v6` (cohort from `android_variant`: Compose → `compose-*`, Views → `kotlin-*`) | `cometchat-android-v6-core` | `cometchat-android-v5-sdk` |
+| Flutter | `stream_chat_flutter`, `stream_chat_flutter_core`, `stream_chat`, `stream_chat_persistence`, `stream_chat_localizations`, `stream_video_flutter` | `flutter-v6` | `cometchat-flutter-v6-core` | the Flutter core's SDK fallback (`cometchat_sdk`, re-exported by the kit) |
+| Video only (no chat) | `@stream-io/video-react-sdk`, `@stream-io/video-client`, `@stream-io/video-react-native-sdk`, `stream-video-swift`, `io.getstream:stream-video-android-*`, `stream_video_flutter` | 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 | `stream-chat` (Node, with the API secret), `@stream-io/node-sdk`, Python `stream-chat`/`getstream`, `stream-chat-go`, `stream-chat-ruby`, `get-stream/stream-chat` (PHP), `io.getstream:stream-chat-java`, `stream-chat-net` | — (REST, no UI Kit) | — | CometChat REST (`/rest-api/…`) |
+
+A platform that isn't in this table (Vue, Svelte, Unity, .NET MAUI…) 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)`, `gradle/libs.versions.toml`, `Podfile`, `Package.swift`, `*.xcodeproj/project.pbxproj`, `Package.resolved`, `requirements.txt`, `go.mod`, `Gemfile`, `composer.json` → `stream-chat`, `stream_chat`, `@stream-io/`, `io.getstream`, `GetStream/stream-`, `getstream` (also the Feeds package).
+
+**Client / auth**:
+- JS: `StreamChat.getInstance(`, `new StreamChat(`, `useCreateChatClient`, `connectUser(`, `disconnectUser`, `devToken(`, `tokenProvider`, `createToken(` (server).
+- iOS: `ChatClient(config:`, `ChatClientConfig`.
+- Android: `ChatClient.Builder`, `StreamOfflinePluginFactory`, `StreamStatePluginFactory`.
+- Flutter: `StreamChatClient(`.
+- Angular: `ChatClientService.init`.
+
+**UI components**:
+- React: `<Chat`, `<ChannelList`, `<Channel`, `<Window`, `<ChannelHeader`, `<MessageList`, `<VirtualizedMessageList`, `<MessageInput`, `<Thread`, `<ThreadList`, `<ChannelSearch`/`<SearchBar`.
+  - Hooks: `useChatContext`, `useChannelStateContext`, `useMessageContext`.
+  - CSS: `stream-chat-react/dist/css/…`, `@stream-io/stream-chat-css`.
+- Angular: `StreamChatModule`, `StreamAutocompleteTextareaModule`, `ChannelService`, `StreamI18nService`, `<stream-channel-list>`, `<stream-channel>`, `<stream-message-list>`, `<stream-message-input>`, `<stream-thread>`.
+- React Native: `OverlayProvider`, `Chat`, `ChannelList`, `Channel`, `MessageList`, `MessageInput`, `Thread`, `ImageGallery`.
+- iOS: `ChatChannelListVC`, `ChatChannelVC`, `ChatThreadVC`, `Components.default`, `Appearance.default`; SwiftUI `StreamChat(chatClient:)`, `ChatChannelListView`, `ChatChannelView`, `ViewFactory`.
+- Android Views: `ChannelListView`, `MessageListView`, `MessageComposerView`, `MessageListHeaderView`, `ChannelListViewModel`, `bindView`, `ChannelListActivity`, `MessageListActivity`.
+- Android Compose: `ChatTheme`, `ChannelsScreen`, `MessagesScreen`, `MessagesViewModelFactory`.
+- Flutter: `StreamChat(`, `StreamChannel(`, `StreamChannelListView`, `StreamChannelListController`, `StreamChannelHeader`, `StreamMessageListView`, `StreamMessageInput`, `StreamChatTheme`.
+
+**Channels**:
+- Handles: `client.channel('<type>', …)`, `channel.watch()`, `queryChannels(`, `cid`, channel types (`messaging`, `team`, `livestream`, `commerce`, `gaming`, custom).
+- Members: `members:` (member-based distinct channels → `!members-` IDs), `addMembers`, `removeMembers`, `addModerators`.
+- Invites: `inviteMembers`, `acceptInvite`.
+- State: `channel.update`/`updatePartial`, `hide`, `show`, `truncate`, `freeze`/`frozen`, `enableSlowMode`, `mute`/`unmute`, `pin`/`archive`.
+
+**Messages**:
+- Send/edit/delete: `sendMessage(`, `updateMessage`, `partialUpdateMessage`, `deleteMessage`.
+- Reply types: `parent_id`, `show_in_channel`, `quoted_message_id`.
+- Reactions: `sendReaction`/`deleteReaction`.
+- Mentions: `mentioned_users`.
+- Uploads: `sendImage`/`sendFile`, `attachments` (`image`, `file`, `video`, `audio`, `voiceRecording`, `giphy`, custom types).
+- Flags: `pinMessage`, `silent`, `markRead`/`markUnread`, `translateMessage`.
+- Extras: polls (`createPoll`, `castPollVote`), reminders (`createReminder`), drafts (`createDraft`), location (`SharedLocation`, `startLiveLocationSharing`), `extraData`/custom fields.
+
+**Events**: `client.on(`, `channel.on(`, `message.new`, `typing.start`/`typing.stop`, `message.read`, `notification.message_new`, `user.presence.changed`, `connection.changed`, `channel.updated`, `member.added`.
+
+**Moderation**: `banUser`, `shadowBan`, `muteUser`, `blockUser`, `flagMessage`/`flagUser`, blocklists, AutoMod config, roles/grants, `channel_role`.
+
+**Push**: `addDevice(`, `removeDevice(`, `PushProvider`, `firebase`/`apn` provider names, `setPushPreferences`, `getstream` keys in the notification payload handlers.
+
+**Other Stream products**:
+- Video: `StreamVideoClient`, `StreamCall`, `useCall`, `call.join`/`call.ring`, `SpeakerLayout`, `CallControls`.
+- **Activity Feeds**: npm `getstream`, `@stream-io/feeds-client`/`@stream-io/feeds-react-sdk`, `client.feed(`, `addActivity`, `follow(`, Python `stream`/`getstream` feeds.
+- AI: `ai_indicator`, `@stream-io/chat-react-ai`.
+
+**Server**: `createToken(`, `upsertUser(s)`, `deleteUser(s)`, `exportChannels`, `verifyWebhook(`, the `x-signature` header, `before_message_send_hook_url`, custom command URLs, SQS/SNS config.
+
+**Env / config**: `STREAM_API_KEY`, `STREAM_API_SECRET`, `STREAM_KEY`, `VITE_STREAM_*`, `NEXT_PUBLIC_STREAM_*`, `EXPO_PUBLIC_STREAM_*`, `REACT_APP_STREAM_*`, keys in plists/`local.properties`/`--dart-define`, and CI secrets named `STREAM_*`.
+
+**Tests / mocks**: `jest.mock('stream-chat…')`, `generateChannel`/`generateUser` test utilities, `getTestClient`.

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

@@ -0,0 +1,9 @@
+# Native platforms (Android · iOS · Flutter) — NOT done until the platform build passes
+
+Before declaring done:
+- **Toolchain first:** bump the sample to the family `-core`'s build floors (Android Gradle/AGP/compileSdk/Kotlin; iOS resolve SPM/pods; Flutter swap the dep in `pubspec.yaml` → `flutter pub get`).
+- **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 rather than reporting the bump as done — a stale wrapper is the #1 Android build failure (AGP >= 8.9.1 needs Gradle >= 8.11.1). Beyond `&`/`$(…)`/`timeout`, a `|` (even as a sed delimiter or inside an alternation like `(bin|all)`), a `{a,b}` brace expansion and a `VAR=x cmd` env prefix are refused the same way, silently — use `/` delimiters, character classes, plain literals and separate lines before concluding an edit is impossible.
+- **Kit dep added AND `initFromSettings` wired** in the app entry (`Application.onCreate` · `AppDelegate`/`App` · Flutter `main`). Flutter's `cometchat-settings.json` is an **asset**: project root AND under `flutter: assets:` in `pubspec.yaml`, or the build fails ("No file or variants found for asset").
+- **`toCometChatId` in the CLIENT language** (verbatim Dart port in `references/concept-map.md` §IDs; Kotlin/Swift likewise), own module (`lib/cometchat/ids.dart` · `…/cometchat/Ids.kt` · `CometChat/Ids.swift`), **called at login**. **The UID is `toCometChatId(<the app's existing Stream user id>)`** — the `User(id: …)`/`connectUser`/token-provider id it already has. The core's "fresh app → `cometchat-uid-1`" advice does NOT apply to a migration: the identity exists, keep it.
+- **`LICENSE`/README attribution** is residue too.
+- **RUN the platform build** (`./gradlew :app:assembleDebug` · `xcodebuild … build` · `flutter analyze && flutter build web`), fix EVERY error, then **run it**: 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 headless; no `timeout` on macOS); never park on a notification (headless: that ends the run).

package/skills/cometchat-migrate-from-getstream/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
+# Stream (GetStream) → CometChat migration
+
+**Branch:** cometchat-migration (created from <base>; <n> uncommitted files came along) · **Platform:** <framework> → CometChat <family label> · **Mode:** UI SDK | client | mixed
+**Build:** ✅ passes (`<command>`) | ❌ <n> errors (listed below) · **Stream residue:** none | <paths>
+
+## 1. Summary
+<2–4 sentences: what the app did with Stream (Chat / Video / Feeds), what it does now, the headline removals.>
+
+## 2. Migrated
+| Stream feature | CometChat equivalent | Files |
+|---|---|---|
+| ChannelList + Channel/Window | 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 |
+|---|---|---|---|---|---|
+| Activity feed | Home timeline + follow buttons | src/feed/*, src/components/FollowButton.tsx, route /feed, server/feed.ts | The social feed | absent · UI Kit: `search_cometchat_docs "<feature> react ui kit"` → no page · SDK: `search_cometchat_docs "<feature> javascript sdk"` → no page | — |
+
+### 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)
+- Livestream channels are now public groups; over 300 members, receipts and typing are off.
+
+## 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, the same for any source — not a Stream property). To bring them over, purchase Extended Storage (contact CometChat sales), then re-run the import.
+5. **Re-host media before deleting Stream** (<n> attachments). CometChat stores attachment URLs by reference, not the files, and Stream CDN URLs expire — re-host them to your own / CometChat media storage, or images and files break.
+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 `devToken` was used).
+10. Remove `STREAM_*` secrets from your CI and hosting env, then delete the Stream app after the cut-over.
+
+## 6. Defaults taken (no questions were asked)
+- <every decision made without asking, e.g. "UI SDK mode: replaced stream-chat-react with the CometChat UI Kit", "kept react-native-reanimated (used by other screens)">
+
+## 7. Verification
+- Build: `<command>` → <result>
+- Residue search: `stream-chat|stream_chat|@stream-io|getstream|StreamChat|StreamVideo` → <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 feeds" 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-sendbird/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: cometchat-migrate-from-sendbird
+description: "Migrate an app from Sendbird to CometChat end-to-end in ONE prompt, on any platform in this pack (React, Angular, React Native/Expo, iOS, Android, Flutter). Inventories every Sendbird usage (Chat SDK v3/v4, UIKit, Calls, Desk, push, server Platform API, webhooks), swaps each supported feature for its CometChat equivalent, REMOVES features CometChat has no equivalent for (code, UI, deps), writes a data-migration script for users/groups/history, uninstalls Sendbird, verifies the build, and ends with a report listing what was migrated, what was removed and what you still need to do. Triggers: 'migrate my app from Sendbird to CometChat', 'migrate my app to CometChat' (Sendbird detected), 'replace Sendbird with CometChat', 'switch from Sendbird', 'move off Sendbird', 'sendbird to cometchat', 'port my Sendbird chat to CometChat'."
+license: "MIT"
+compatibility: "FROM Sendbird Chat SDK v3 (`sendbird`) / v4 (`@sendbird/chat`, SendbirdChatSDK, com.sendbird.sdk, sendbird_chat_sdk), Sendbird UIKit (React, React Native, iOS UIKit/SwiftUI, Android Views/Compose, Flutter), Sendbird Calls → TO the CometChat family this pack detects (peers.yaml): React UI Kit v7, Angular v5, React Native v5, iOS v5, Android v6, Flutter v6, plus the headless Chat/Calls SDKs. Node >=18 for the data-migration script."
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat migration sendbird competitor switch replace port uikit sdk calls data-import"
+---
+
+> **Ground truth:** the SENDBIRD side (what to look for) is baked in `references/inventory.md` + `references/feature-map.md` — confirm each hit by reading the user's code. The COMETCHAT side is never from memory: symbols come from the target family's skills + catalog, feature existence from that family's `features.json`, signatures from the docs via the family's `-core/references/docs-map.md` (Docs MCP first — `RULES.md` → Fetch discipline). REST pages live under `DOCS_BASE` = `https://www.cometchat.com/docs`.
+
+## Companion skills (read first)
+- `cometchat-<family>-core` — the init → login → render the migrated app lands on. `<family>` is resolved in step 1; this skill ASSUMES that core and never restates its code.
+- `cometchat-<family>-components` / `-features` / `-calls` / `-push` / `-customization` — pulled in only for the Sendbird features the inventory finds.
+
+## Use this skill when
+The user asks to move an app off Sendbird: "migrate my app from Sendbird to CometChat", "replace Sendbird", "switch to CometChat", or "migrate my app to CometChat" when `npx @cometchat/skills detect --json` reports `migrate_from` with vendor `sendbird`. Stream/GetStream apps → `cometchat-migrate-from-getstream`. An app with BOTH vendors: run both skills, one after the other, into one report.
+
+## The single-prompt contract (read before step 1)
+The migration request IS the approval (`RULES.md` → Competitor migration). Run every step below to the end in this one turn:
+- **Do not stop to ask.** No onboarding plan/approve gate, no clarification questions. Where a companion skill would ask, take the default written here, and record it under *Defaults taken* in the report.
+- **Safety net instead of questions:** in a git repo, first `git switch -c cometchat-migration` (carries any uncommitted work along; mention that in the report). Never commit, push, or rewrite history. No git → proceed and say so in the report.
+- **Removing Sendbird is the requested outcome** — `RULES.md`'s append-never-replace does not protect Sendbird code. It still protects everything else: touch non-chat code only to rewire it.
+- **Credentials: never ask, never provision.** Reuse `.cometchat/config.json` or existing CometChat env values if present; otherwise write the family's env/settings file with clearly-named placeholders so the build still compiles, and make "add your CometChat credentials" action item #1. **Never write a real key into a git-tracked file:** check `git ls-files <file>` first. If the file is tracked, put real values in the untracked local variant the framework reads (Vite/Next `.env.local`, Android `local.properties`, …) and keep placeholders in the tracked file. Adding a tracked file to `.gitignore` does NOT untrack it. The server's REST API key only ever goes into an untracked file or the hosting env.
+- **Only three STOPs:** (1) no Sendbird usage found → say so and hand to `cometchat`; (2) the app's platform has no family in this pack (Vue, Unity, .NET, …) → deliver the inventory + feature map as the report, change nothing; (3) the build was already failing before you started → record the pre-existing errors, migrate anyway, and label them as pre-existing.
+
+## Migration workflow (BAKED — do every step, in order)
+Every step applies to every app, however small: a 3-file sample still has vendor users and history, so steps 4 (`toCometChatId`) and 8 (data script) are ALWAYS delivered. Only a step whose subject truly doesn't exist (no server → step 7) may be skipped, and it's listed under *Defaults taken* as `skipped: <why>`. A silent skip is a failed migration.
+1. **Detect.** `npx @cometchat/skills detect --json` → `framework`, `android_variant`, `existing_cometchat`, `migrate_from`. Resolve `<family>` exactly like the router (`peers.yaml` `dir_prefix`; per-platform targets in `references/inventory.md` §Target family). Monorepo: migrate every package that uses Sendbird, including the server. `existing_cometchat: true` + Sendbird still present = a half-finished migration: resume it, don't redo it. Read `.cometchat/config.json` if it exists: its `appId`/`region`/`authKey` are THE credentials. Write them into the family's untracked env/settings file (single-prompt contract), never ask. Before editing anything, run the app's build once and record whether it passed.
+2. **Inventory — the usage ledger.** Grep per `references/inventory.md` (packages, imports, init/connect, UIKit components, handlers, collections, push registration, Calls, Desk, env vars, server Platform API calls, webhooks, tests/mocks). Record every hit as `file:line → what it does`. Classify the app: **UIKit mode** (Sendbird UIKit renders the chat) → the family's CometChat UI Kit replaces it; **SDK mode** (own UI on the Sendbird Chat SDK) → KEEP the app's UI and port its data layer to the family's CometChat Chat SDK; **mixed** → both.
+3. **Feature map.** For every Sendbird feature the ledger shows, look up its row in `references/feature-map.md`, then check the listed CometChat id in the TARGET family's `features.json`. Present → **migrate**. Absent → check BOTH levels — UI Kit (`search_cometchat_docs "<feature> <platform> ui kit"`) AND Chat SDK/REST (`… SDK`); documented at either → migrate (**no UI Kit drop-in is NOT unsupported**), built with the SDK method in the app's own UI (`RULES.md` → UI Kit first, SDK fallback). Mark **UNSUPPORTED only** when NEITHER has it — and **an empty MCP search is NOT proof**: follow the verification ladder (re-query with CometChat vocabulary → live-fetch the likely docs page → cross-check the family CATALOG) in `references/feature-map.md` §Deciding unsupported, before any REMOVE. Never call a feature unsupported from memory or invent an API; if it truly can't be verified, KEEP it as `needs-verification`. **Every UNSUPPORTED row needs evidence in the report** — the `features.json` result + the exact UI Kit AND SDK queries you ran.
+4. **Install CometChat and wire the core** per `cometchat-<family>-core` (its install, `initFromSettings`, login gate, render order, env file). **Identity:** the CometChat UID is the app's existing Sendbird user ID passed through ONE shared `toCometChatId()` (`references/concept-map.md` §IDs) — used by the client login, the server token endpoint, AND the data script, so all three agree. Login: the app minted Sendbird session/access tokens on a server → migrate that endpoint (step 7) and use the auth-token login; the app connected with only a user ID → Auth Key login (dev only) + an action item to switch to tokens before production. **Keep every identity source, in the same order:** whatever decides the current user today (URL params, env vars like `VITE_USER_ID`, the auth provider, a stored ID, a demo fallback) still decides it after the migration. Only the Sendbird-token-derived path becomes the CometChat auth token. Dropping one silently logs a configured deployment in as someone else. **NEVER replace a seeded identity with a placeholder.** If the app ships a concrete default user (`default_user_id`/`USER_ID`/a demo fallback in strings, env or constants), that exact value STAYS — pass it through `toCometChatId()`, do not overwrite it with `cometchat-uid-1`, `Cometchat User 1` or any `YOUR_*` stand-in. The core skill's placeholder UID is for an app that has NO identity yet; an app being migrated always has one. Getting this wrong is silent: the build passes, the app launches, and every migrated user signs in as a stranger with an empty inbox while the data script imported their history under their real id. Before you finish, diff every identity default you touched against its pre-migration value and confirm it is unchanged. **Returning users:** the app already persists who is signed in (localStorage, keychain, prefs, a cookie) from the vendor era. Gate the chat on CometChat's logged-in user, NOT that cached ID. On start, a stored ID with no CometChat session → run the same login path before rendering any CometChat component; if that fails → the sign-in screen. Otherwise every user who was signed in before the upgrade lands on a broken chat. **No UI Kit family for this app?** A headless / vanilla-JS app that draws its own UI on SendbirdChat / `sendbird` (no framework the pack ships a UI Kit for) has no `-core` to wire — do NOT stop. Install the CometChat **Chat SDK** for the platform (web → `@cometchat/chat-sdk-javascript`) and migrate the data layer straight onto it, taking every method from the SDK docs (`/sdk/<platform>/*`). Keep the app's own UI; there is no UI Kit to install. This is client/SDK mode with no framework core — the concept map's SDK/client-mode section still applies.
+5. **Replace usage, file by file,** using `references/concept-map.md`: Sendbird init/connect → CometChat init/login; channel list → conversations; group channel / 1:1 distinct channel → group / user conversation; handlers → listeners (remove them on unmount); message send/receive/edit/delete/threads → the core + `-features` skill; UIKit screens → the family's components (`-components`/`-placement`); theme/string sets → `-customization`; Calls → `-calls` (or the headless calls peer); push → `-push`. Remove each Sendbird import as you replace its last use. **Both modes fetch from docs only:** UI Kit component props AND SDK method signatures come from the live docs (the family `core`'s `docs-map.md`), verified against the catalog — never written from memory or ported from the vendor's API shape.
+6. **Remove unsupported features FULLY.** For each UNSUPPORTED row: delete the feature's code path, its UI entry points (buttons, menu items, routes, screens, settings toggles), state/stores, types, hooks, assets, tests, env vars, server endpoints and dependencies — no dead buttons, no commented-out blocks, no feature flags left on. Keep the surrounding screen working. Log each one for the report: feature · what it did · files changed · what users lose · the closest CometChat alternative (if any).
+7. **Server side.** Replace Sendbird session/access-token minting with a CometChat auth-token endpoint (REST: create the user if missing, then create an auth token — `/rest-api/auth-tokens`, REST API key from server env only). Map Sendbird webhooks to CometChat webhooks (`/rest-api/management-apis/webhooks/overview`); drop or list any event with no equivalent. Replace other Platform API calls with CometChat REST, or remove + list them (step 6).
+8. **Data migration script — write it, then run the import for the user.** Generate `scripts/cometchat-migration/` per `references/data-migration.md`: export users, channels, members and messages from the Sendbird Platform API → transform with the same `toCometChatId()` → import through 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 source keys (`SENDBIRD_APP_ID`, `SENDBIRD_API_TOKEN`) and the CometChat **App ID, Region and full-access REST API key**. (Asking for these is the ONE question the single-prompt contract allows; everything else still takes the documented default.) As soon as the user provides them, **RUN the import yourself** from env vars — never write the secrets into a repo file: a `--dry-run` first (show the users / groups / members / messages counts), then the real import, then report what landed and what failed. 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 the user does not share credentials, leave running the script as an action item.
+9. **Uninstall Sendbird.** Remove every Sendbird dependency (package.json + regenerate the lockfile, Podfile/SPM, Gradle dependency AND the Sendbird Maven repo, pubspec), CSS imports, fonts/icons, env vars, native config, and CI secrets references. Re-run the package manager install. **On iOS/SPM the ROOT manifest counts too**: a vendored-SDK repo declares the vendor in its own `Package.swift`/`*.podspec` at the repo root, not just in the app's `.xcodeproj` — remove the dependency there AND delete any vendored `Framework/*.xcframework`, or the vendor package is still declared after every call site is gone. Update the app's OWN docs (README, setup/deploy guides, `.env.example`): setup steps, env var names and screenshots captions that describe Sendbird now describe CometChat. Rename Sendbird-named identifiers (`sendbirdUserId` → `userId`).
+10. **Verify** (§Verify it works). Fix every build error you introduced. Don't run live tests unless asked (`RULES.md` → Verification scope).
+11. **Report.** Write `COMETCHAT_MIGRATION.md` at the repo root from `references/report-template.md`, then END your reply with its two lists pasted in full: **Removed — not available in CometChat** and **Your action items**. This final list is the deliverable the user asked for; never skip it, even if nothing was removed (say "none").
+
+## Common pitfalls
+- **Accessibility is never a "missing feature".** Sendbird-provided skip links, focus management, live regions and keyboard shortcuts are plain HTML/ARIA/host code. Re-create them in the app against the new CometChat layout, and never list them as Removed. Losing them is a regression, not an honest removal.
+- **The provider swap moves wrapper elements.** `CometChatProvider` (and, on web, `CometChatErrorBoundary`) render wrapper elements exactly where the vendor's provider sat. If they now wrap the app's own shell/header, each wrapper needs a height in the chain, or the chat renders at 0px while the build passes. Follow the core's layout reference, and check the chain from the root element down to the conversation list.
+- **IDs that CometChat rejects or merges.** UIDs/GUIDs are alpha-dash (`a-z 0-9 - _`), max 100 characters, and lowercased. Sendbird IDs can contain `@`, `.`, spaces or uppercase. Sanitize with one deterministic function and use it everywhere, or users log in to empty inboxes.
+- **1:1 chats are not groups.** A distinct Sendbird group channel with exactly two members becomes a CometChat *user* conversation (`receiverType: user`), not a two-person group.
+- **Large channels.** CometChat sends receipts and typing indicators only in groups up to 300 members (100,000 without them). Supergroups over 300 keep chatting but lose receipts: list that as a behavior change.
+- **Leftover handlers.** Every Sendbird `ChannelHandler`/`GroupChannelHandler`/`ConnectionHandler` needs a CometChat listener that is also removed on unmount/dispose. Missing removals cause duplicate messages.
+- **Half-removed features.** Deleting the API call but leaving the button (or the route) is a dead end (`RULES.md` → Default-on affordances). Remove the entry point too.
+- **Collections/local cache.** Sendbird `GroupChannelCollection`/`MessageCollection` gave offline cache and auto-sync. Port them to the CometChat request builders + listeners and note the behavior change. Don't re-invent a cache.
+- **Never delete non-Sendbird code** that just shares a file with Sendbird code. Rewire it.
+
+## Native platforms (Android · iOS) — NOT done until the platform build passes
+Native builds (Android/iOS/Flutter) have extra REQUIRED steps beyond editing code — bump the sample toolchain to the `-core` build floors, add the kit dep AND wire `initFromSettings` in the app entry, port `toCometChatId` to the client language, edit `.pbxproj`/`.xcscheme` as structured build graphs (never a text scrub), and RUN the platform build. **A native migration is NOT done until you have followed `references/native-build.md` in full** — open it and work through every step; it is mandatory, not optional.
+
+## Verify it works
+- The app builds/type-checks with the family's normal command (the core skill's "Verify it works"). **On native, this means actually running the platform build above — not just visual inspection.**
+- **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: web → the dev server (or build + preview), open it, watch the **browser console** + the dev-server terminal; native → the platform run + logcat / Xcode console / `flutter` logs. Fix EVERY runtime error you introduced before declaring done — 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, not the user's problem (hand off to `cometchat-<family>-troubleshooting` for symptom → fix). If the app genuinely can't be started here (no dev env / needs a device), SAY SO and give the user the exact run command + what to watch for — never silently skip this.
+- **Zero Sendbird residue — run exactly this, over ALL file types (docs included):** `grep -rIilE 'sendbird' . --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=dist --exclude-dir=build --exclude-dir=.claude --exclude-dir=Pods --exclude-dir=.dart_tool --exclude-dir=.gradle | grep -vE 'COMETCHAT_MIGRATION.md|scripts/cometchat-migration'` → must print nothing (repeated `--exclude-dir=` flags on purpose: a `{a,b}` brace list is rejected by the coding agent's command-permission parser, so the check silently never runs). The ONE allowed mention is a single provenance comment above `toCometChatId()`; code identifiers, README lines and env names are residue, not "expected". **This includes a "migrated from <vendor>" line in the README or any doc you write** — a provenance note reads as helpful and is still residue; the migration report is where that belongs, and it is already exempt. Rewrite the app's own README so it describes CometChat, naming the vendor nowhere. The same goes for every other doc the repo ships — `CHANGELOG.md`, `docs/`, `changelogs/`, a vendored SDK's own release notes: if a file is not the migration report, it must not name the vendor. Delete the ones that document the vendor's product rather than your app. **Clearing residue out of `project.pbxproj` / `*.xcscheme` is a structured edit, never a text scrub** — remove the vendor's SPM package reference and its build-phase entries as whole blocks, and keep the project's own product and target structure (see the native block above).
+- `scripts/cometchat-migration/migrate.mjs` + `README.md` exist — **even for a demo/sample app with no data of its own** (the script is a deliverable for the user's real data, not for this checkout; step 8 is never skipped).
+- Every CometChat symbol you emitted exists in the family catalog. Every migrated feature is in `features.json` or the docs. Every UNSUPPORTED item is in the report's Removed list with its files.
+- The server token endpoint, the client login and the data script all call the same `toCometChatId()`.
+- **Runtime shape, statically checked:** every element from the root to the conversation list has a height (wrappers included). A user who was signed in before the migration is logged in to CometChat again before the chat renders. No real secret sits in a git-tracked file (`git ls-files` each file you wrote credentials to).

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

@@ -0,0 +1,99 @@
+# Sendbird → CometChat concept map
+
+This maps **roles**, not code. For every CometChat call, component and prop, take the exact name and signature from the target family's skill (`cometchat-<family>-core` / `-components` / `-features`), its catalog, and the docs (`-core/references/docs-map.md`). The platforms differ: web callbacks are `on*Click`, React Native's are `on*Press`, and Android/iOS/Flutter use their own init shapes. Never port a snippet from one family to another.
+
+## IDs (do this first — everything else depends on it)
+CometChat UIDs and GUIDs are **alpha-dash only** (`a-z`, `0-9`, `-`, `_`), **max 100 characters**, and **lowercased automatically** (`/articles/properties-and-constraints`). Sendbird user IDs and channel URLs are not. Emit ONE deterministic helper per language the repo uses (client, server, and the data script share its logic exactly):
+
+```js
+// toCometChatId — the single source of truth for Sendbird ID → CometChat UID/GUID.
+// Deterministic: the same input always yields the same ID, on every platform and in the data script.
+export function toCometChatId(id) {
+  const raw = String(id);
+  let out = raw.toLowerCase().replace(/[^a-z0-9_-]/g, "_");
+  // Changed or too long → add a short stable hash of the ORIGINAL, so "A.b" and "a_b" never merge.
+  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;
+}
+```
+
+```dart
+// lib/cometchat/ids.dart — the SAME rule as the JS helper (same 32-bit hash, same base-36 suffix); output-identical.
+String toCometChatId(String id) {
+  final raw = id;
+  var out = raw.toLowerCase().replaceAll(RegExp(r'[^a-z0-9_-]'), '_');
+  if (out != raw || out.length > 100) {
+    var h = 0;
+    for (final c in raw.runes) { h = ((31 * h) + c) & 0xFFFFFFFF; }
+    out = '${out.substring(0, out.length > 90 ? 90 : out.length)}_${h.toRadixString(36)}';
+  }
+  return out;
+}
+```
+
+The Dart port above is verbatim; port to Swift/Kotlin the same way: same steps, same 32-bit hash, same base-36 suffix. An ID that is already valid passes through unchanged, so most apps see no difference.
+
+## Core concepts
+| Sendbird | CometChat (role) | Notes |
+|---|---|---|
+| Application ID | App ID + Region | Region comes from the dashboard (`us`/`eu`/`in`). Both go in the family's env/settings file. |
+| `SendbirdChat.init` / `new SendBird()` / `SendbirdUIKit.init` / `SendbirdUI.initialize` | the family's `initFromSettings` (UI Kit) or the Chat SDK's init | Per core skill. Init once, before any login or render. |
+| `connect(userId, accessToken/sessionToken)` | the auth-token login, with a token from YOUR server | Production path. |
+| `connect(userId)` with no token | the Auth Key login | Dev only (`RULES.md` → Credentials). Action item: move to tokens. |
+| `SessionHandler` (token refresh) | re-login with a fresh auth token when the SDK reports an expired or invalid session | Fetch the token lifecycle docs. |
+| `disconnect()` | logout | Call on sign-out, and clean up listeners. |
+| User (`userId`, `nickname`, `profileUrl`, `metadata`) | User (`uid` = `toCometChatId(userId)`, name, avatar, metadata) | Users must EXIST before login. The server endpoint creates them on first login; the data script imports the rest. |
+| GroupChannel, **distinct, exactly 2 members** | a **user** conversation (1:1) | Receiver = the other member's UID. Never a 2-person group. |
+| GroupChannel (other) / supergroup | Group (`guid` = `toCometChatId(channel_url)`) | Private → `private`. `isPublic` → `public`. A password flow → `password`. |
+| OpenChannel | a **public** Group | Users join it. There's no "enter/exit"-only presence. |
+| Channel list query / `GroupChannelCollection` | the conversations list (UI Kit) or the conversations request builder (SDK) | |
+| `PreviousMessageListQuery` / `MessageCollection` | the message list (UI Kit) or the messages request builder (SDK) | Paging, not a local cache. |
+| UserMessage / FileMessage / AdminMessage | text message / media message / (admin → an action or a custom message; usually dropped) | |
+| `customType`, `data`, `metaArrays` | custom message type + message metadata | |
+| `parentMessageId` (thread) | the parent message ID on the reply | Threads feature row. |
+| `GroupChannelHandler`, `ConnectionHandler`, `UserEventHandler` | message / group / user / connection listeners | Add on mount, REMOVE on unmount/dispose (by listener ID). |
+| Operators | group scope `admin` / `moderator` | |
+| Push token registration | the family's push skill (Notifications product) | |
+
+## UIKit screen map (UIKit mode)
+| Sendbird UIKit screen (any platform) | CometChat UI Kit role | Where |
+|---|---|---|
+| `App` / all-in-one chat | the production-ready core surface (conversation list ↔ message pane) | `-core` golden path |
+| Channel list (`GroupChannelList`, `ChannelList`, `SBUGroupChannelListViewController`, `ChannelListFragment`/`ChannelListScreen`, `createGroupChannelListFragment`, `SBUGroupChannelListScreen`) | Conversations | `-components` |
+| Channel (`GroupChannel`, `Channel`, `SBUGroupChannelViewController`, `ChannelFragment`/`ChannelScreen`, `createGroupChannelFragment`, `SBUGroupChannelScreen`) | message header + message list + message composer | `-core` / `-components` |
+| Channel settings / members | group details + group members | `-placement` (details panel) / `-components` |
+| Create channel | the users picker + group creation | `-components` |
+| Thread | the thread header + threaded message list | `-features` (`threaded-replies`) |
+| Message search | Search | `-features` (`message-search`) |
+| Open channel screen | the message pane on a public group | `-core` |
+| Edit profile | no kit screen → keep the app's UI and call the SDK's update-current-user method | docs |
+
+On React v7 these are `CometChatConversations`, `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer`, `CometChatThreadHeader`, `CometChatSearch`, `CometChatUsers`, `CometChatGroups` and `CometChatGroupMembers`. Other families: take the names from their `-components` skill.
+
+**Routing and navigation:** keep the app's routes and URLs. Swap only what renders inside them. A Sendbird route param like `/chat/:channelUrl` becomes `toCometChatId(channelUrl)`, so deep links and bookmarks keep working after the data import.
+
+**Styling:** delete the Sendbird CSS import and any Sendbird theme providers. Re-apply the brand through the family's `-customization` skill (colors, fonts, dark mode). Follow-the-OS theming is a core obligation (`RULES.md`).
+
+## Behavioral differences to handle (sdk-mode gotchas)
+Keeping the app's own UI means matching the vendor's runtime BEHAVIOR, not just method names. The app should look and behave the same after migration — only the data source changed. Watch these:
+- **Optimistic send / local echo.** Sendbird's `send` GroupChannel.sendUserMessage returns a pending message immediately (local echo), then a second callback confirms it; the message appears instantly, then updates on confirm. CometChat's `CometChat.sendMessage()` resolves with the sent message on success and rejects on failure — there's no separate pending object. To keep the instant-echo UX, insert a local placeholder yourself on submit and replace it with the resolved message (or roll it back on reject). Don't drop the echo and make sends feel laggy.
+- **Pagination.** Sendbird pages with PreviousMessageListQuery / MessageCollection. CometChat uses `new CometChat.MessagesRequestBuilder().setUID/setGUID(...).setLimit(n).build()` and `.fetchPrevious()` (older) / `.fetchNext()` (newer), holding ONE builder instance per conversation for the cursor. Map the app's scroll-to-load to the same builder; a fresh builder per page re-fetches from the top.
+- **Listener lifecycle.** Each GroupChannelHandler becomes a CometChat listener added with a unique ID and REMOVED on unmount/dispose. Reuse the app's existing subscribe/unsubscribe points; a listener added on every render without removal duplicates messages.
+- **Delivered/read + typing.** These are separate `CometChat` calls and listener events, not fields on the message object. Wire them where the app read the vendor's equivalents.
+- **Fetch every method + shape from the SDK docs** (`/sdk/<platform>/*`) and verify against the catalog — never port the vendor's signature by analogy.
+
+## SDK mode (the app draws its own UI)
+Keep every component and screen. Replace only the data layer (the service/store/hook that talks to Sendbird): each method calls the CometChat Chat SDK equivalent, and each handler becomes a listener. Keep the app's own model types. Map CometChat objects into them at the boundary, so the UI code doesn't change. **Every CometChat SDK method, its signature, its listener class and its parameter shapes come from the live docs — never from memory and never from the vendor's API by analogy.** For each data-layer call, open the family's SDK docs (`cometchat-<family>-core/references/docs-map.md` → SDK section, or the `-sdk` skill where one ships), fetch the exact method (e.g. `CometChat.getConversationList` via `new CometChat.ConversationsRequestBuilder()`, `CometChat.sendMessage`, `CometChat.addMessageListener`), and verify it against the family catalog before you emit it. A `<vendor>`-method-to-CometChat-method guess that you did not fetch is a defect, even if it compiles. Look up the method list in the family's SDK docs (docs-map → SDK section; React Native: `cometchat-react-native-sdk/references/method-map.md`; Android: `cometchat-android-v5-sdk`).
+
+## Server
+| Sendbird server piece | CometChat replacement |
+|---|---|
+| Session/access-token endpoint (`POST /v3/users/{id}/token`, or `issue_access_token` on user create) | Your endpoint: create the user if missing (`POST /v3/users`), then `POST /v3/users/{uid}/auth_tokens`. Uses the **REST API key**, server env only, never shipped to clients (`/rest-api/auth-tokens`). |
+| Webhook receiver (`x-sendbird-signature`) | A CometChat webhook receiver with the events mapped (`/rest-api/management-apis/webhooks/overview`). Delete the Sendbird signature check. |
+| User sync on sign-up (Platform API create/update user) | CometChat REST create/update user (docs), called with the same `toCometChatId()` |
+| Moderation / admin scripts | CometChat REST equivalents, or REMOVE + list them |
+| Env: `SENDBIRD_API_TOKEN` | `COMETCHAT_APP_ID`, `COMETCHAT_REGION`, `COMETCHAT_REST_API_KEY` (placeholders + an action item) |

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

@@ -0,0 +1,74 @@
+# Data migration — Sendbird history → CometChat (write it; the user runs it)
+
+CometChat supports two approaches (`/fundamentals/data-import-and-migration`):
+- **Historical import:** bulk-load users, groups, members and messages before go-live. It uses the Data Import REST API, and this script does it.
+- **Live migration:** both systems bridged during a gradual rollout. This needs CometChat's team, so if the app can't have a cut-over window, add the action item "contact CometChat sales for live migration".
+
+Emit `scripts/cometchat-migration/` with:
+- `migrate.mjs`: Node ≥18, no dependencies, uses global `fetch`.
+- `README.md`: how to run it.
+- `id.mjs`: a copy of `toCometChatId()` from `concept-map.md`. It must be byte-identical in logic to the one the app and server use.
+
+The script reads its secrets from env (`SENDBIRD_APP_ID`, `SENDBIRD_API_TOKEN`, `COMETCHAT_APP_ID`, `COMETCHAT_REGION`, `COMETCHAT_REST_API_KEY`), never from a file in the repo. **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 into a repo file, and never committed. If the user declines to share credentials, leave running it as an action item instead.
+
+## 1. Export from Sendbird (Platform API)
+Base `https://api-${SENDBIRD_APP_ID}.sendbird.com/v3`, with header `Api-Token: ${SENDBIRD_API_TOKEN}`. These endpoints and their paging parameters are from Sendbird's Platform API. **Check each one against Sendbird's current Platform API reference while writing the script, and note any difference in the README.**
+
+| Data | Endpoint | Paging |
+|---|---|---|
+| Users | `GET /users?limit=100` | `next` token → `&token=` |
+| Group channels | `GET /group_channels?limit=100&show_empty=true&show_member=true` | `next` token |
+| Channel members | `GET /group_channels/{channel_url}/members?limit=100` | `next` token |
+| Messages | `GET /group_channels/{channel_url}/messages?message_ts=<ms>&prev_limit=0&next_limit=200&include=false&with_sorted_meta_array=true` | advance `message_ts` past the last `created_at` |
+| Open channels (+ messages) | `GET /open_channels?limit=100`, `GET /open_channels/{channel_url}/messages?…` | same |
+
+Honor Sendbird's rate limits (back off on HTTP 429). Write each export to `export/*.jsonl` so a failed run can resume without re-exporting.
+
+## 2. Transform
+- **User:** `uid = toCometChatId(user_id)`, `name = nickname || user_id`, `avatar = profile_url` (must be a URL), `metadata = { ...metadata, sendbirdUserId: user_id }`, `createdAt = seconds(created_at)` when present.
+- **Channel:**
+  - Distinct with exactly 2 members → **no group**; its messages become user-to-user messages.
+  - Otherwise: `guid = toCometChatId(channel_url)`, `name = name || "Group"`, `icon = cover_url`, `type = is_public ? "public" : "private"`, `owner` = the creator's `uid` (else the first operator), `metadata = { sendbirdChannelUrl: channel_url, customType: custom_type, data }`, `tags = custom_type ? [custom_type] : []`.
+- **Member:** the key is `${guid}_member_${uid}`. Operators get `scope: "admin"`, everyone else `"participant"`. Banned members get `isBanned: true`.
+- **Message:**
+  - `muid = String(message_id)`, `sender = toCometChatId(user.user_id)`, `receiverType` + `receiver` (the other member's uid for a 1:1 channel, else the guid), `sentAt = Math.floor(created_at / 1000)`.
+  - `MESG` → `category:"message"`, `type:"text"`, `data.text = message`.
+  - `FILE` → `type` from the MIME prefix (`image/` → `image`, `video/` → `video`, `audio/` → `audio`, else `file`), `data.attachments = [{ url, name, mimeType, extension, size }]`. **CometChat stores the attachment URL by REFERENCE — it does not copy or re-host the file** (verified against the Data Import API). So the file survives only while the source URL does: re-host every attachment to your own / CometChat media storage **before decommissioning Sendbird**, or images and files break. List re-hosting as an action item.
+  - `ADMM` (admin messages, e.g. "X joined"): import as a `category:"message", type:"text"` message from a system/admin UID so the history reads the same (don't silently drop it); if the app rendered them specially, note it as a behavior change. Count them in the summary.
+  - `custom_type` / `data` / `sorted_metaarray` → `data.metadata`.
+  - Mentions → rewrite each mention in the text to `<@uid:UID>` and fill `mentionedUserDetails`.
+- **Filter out messages CometChat will reject BEFORE sending — each one, left in a batch, aborts the whole request with HTTP 500 (`ERR_EXCEPTION`) after the good rows have already imported:**
+  - **Older than retention (~6 months):** CometChat retains messages about **6 months** by default and the Data Import API rejects any message whose `sentAt` predates that window (`"Messages older than 6 months cannot be imported"`). This is a **destination limit** — it is the SAME for every source (Sendbird / Stream / Twilio) because it is enforced on the CometChat side, not the vendor's. Compute `cutoff = now − 6 months`, DROP older messages, count them, and add the action item: *"N messages predate CometChat's 6-month retention window and were not migrated — purchase Extended Storage (contact CometChat sales), then re-run to include them."* (`/fundamentals/data-import-and-migration`; retention: CometChat Help Center → Data Retention.)
+  - **Empty text:** a `type:"text"` message whose `data.text` is empty/whitespace is rejected (`ERR_EMPTY_MESSAGE_TEXT`) — skip it. This also catches body-less `ADMM`/system lines.
+- **Seconds, not milliseconds:** every CometChat timestamp here is a 10-digit UNIX time.
+- **Not carried by the import API:** thread parent links, reactions, poll votes, pins, per-user read state beyond `readAt`/`deliveredAt`. Replies import as ordinary messages. 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`, with headers `apikey: ${COMETCHAT_REST_API_KEY}` and `content-type: application/json`. Fetch each page for the full payload before writing that call:
+- `/rest-api/data-import-apis/users/import-users`
+- `/rest-api/data-import-apis/groups/import-groups`
+- `/rest-api/data-import-apis/groups/import-group-members`
+- `/rest-api/data-import-apis/messages/import-messages`
+
+| Order | Endpoint | Body shape |
+|---|---|---|
+| 1 | `POST /data_import/users` | `{ "users": { "<uid>": { uid, name, avatar?, metadata?, createdAt? } } }` |
+| 2 | `POST /data_import/groups` | `{ "groups": { "<guid>": { guid, name, type, owner, icon?, metadata?, tags?, createdAt? } } }` |
+| 3 | `POST /data_import/members` | `{ "members": { "<guid>_member_<uid>": { memberId, guid, uid, scope?, isBanned?, joinedAt? } } }` |
+| 4 | `POST /data_import/messages` | `{ "messages": { "<muid>": { muid, sender, receiverType, receiver, category, type, data, sentAt, deliveredAt?, readAt? } } }` |
+
+- **Batching:** at most **50 entities per request** and **60 requests per minute**. Throttle to about one request per second, and retry `ERR_TOO_MANY_REQUESTS` with backoff.
+- **Read PER-ROW results, not the HTTP status.** The response body reports `success` (true/false) per key under `data` — count those, not the status code. A request can even return **HTTP 500 (`ERR_EXCEPTION`) while having imported its rows**, so on any non-2xx do NOT assume nothing landed: re-run (idempotency makes that safe) and rely on the per-row / already-exists signal below.
+- **Treat "already exists" as success, not failure.** On a re-run — or after a 500 that actually landed — rows come back as `ERR_UID_ALREADY_EXISTS` / `ERR_GUID_ALREADY_EXISTS` / `ERR_ALREADY_JOINED` / `ERR_IMPORT_MUID_ALREADY_EXISTS`. These mean the row is present. Log only genuine failures to `import-errors.jsonl` and carry on; never abort the whole run for one bad row.
+- **Idempotency:** re-running with the same uid/guid/muid is safe (overwrite / already-exists).
+- **Order matters:** users → groups → members → messages, oldest messages first.
+
+Finish by printing counts: exported, imported, converted (admin→text), skipped (deleted / beyond the 6-month retention window / empty), failed (with a pointer to the error file).
+
+## README.md for the script (emit it)
+1. Create a **REST API key** (full access) in the CometChat dashboard.
+2. Export the five env vars.
+3. Dry run: `node scripts/cometchat-migration/migrate.mjs --dry-run`. This exports and transforms, then prints counts without importing.
+4. Import: `node scripts/cometchat-migration/migrate.mjs`.
+5. Spot-check a few conversations in the dashboard, then point production at the new build.
+6. Delete the export files. They hold user data.