@cometchat/skills 5.0.0 → 5.0.1

package/.claude-plugin/marketplace.json

@@ -13,7 +13,7 @@
       "skills": "./skills",
       "strict": true,
       "description": "UI Kit skills for integrating CometChat across React v7, Angular v5, React Native v5, Android v6 (Kotlin/Compose), iOS v5 (Swift/UIKit, SPM) and Flutter v6. The /cometchat dispatcher detects your project — web (React on Vite/Next/CRA, or Angular) or mobile (React Native/Expo, Android, iOS, Flutter) — and routes to task-shaped skills (core, components, placement, customization, features, calls, push, migration; plus platform patterns). Headless Calls SDK skills cover calling without a UI Kit. Run `/cometchat add chat to my app` to start. Thin entry with progressive disclosure. Backed by a deterministic CLI and a CI-gated verification pipeline: every skill is checked against its pinned kit (symbol catalog + compile fence), and several families also pass a live simulator/emulator smoke (per-family status in peers.yaml).",
-      "version": "5.0.0",
+      "version": "5.0.1",
       "author": {
         "name": "CometChat"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://code.claude.com/schemas/plugin.json",
   "name": "cometchat-skills",
-  "version": "5.0.0",
+  "version": "5.0.1",
   "description": "CometChat AI-coding skills — add real-time chat, voice/video calling and push to your app via your AI coding agent, across React v7, Angular v5, React Native v5, Android v6 (Kotlin/Compose), iOS v5 (Swift/UIKit, SPM) and Flutter v6. Ships the first-party CometChat Docs MCP so skills read always-current docs automatically; falls back to a guided MCP add, then to a direct docs fetch.",
   "author": {
     "name": "CometChat",

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+# v5.0.1
+
+## New
+- **Migrate from another chat provider in one prompt.** Added **Sendbird → CometChat** and **Stream (GetStream) → CometChat** migration skills, installed for every platform. From a single "migrate my app to CometChat" prompt they inventory the app, replace each supported feature with its CometChat equivalent, remove the features CometChat has no equivalent for (and list them), rewire the token server and webhooks, and write a data-migration script for users, groups and message history — then run the import for you once the app migration is done and you provide credentials (dry-run first, then import).
+- The data-migration script works within CometChat's [Data Import](https://www.cometchat.com/docs/rest-api/data-import) limits (batch size and rate) and the ~6-month message-retention window (reach out to CometChat to import older history).
+
+---
+
 # v5.0.0
 
 ## New

package/MIGRATING.md

@@ -0,0 +1,187 @@
+# Migrating from Sendbird or Stream (GetStream) to CometChat
+
+This guide takes an existing chat app built on **Sendbird** or **Stream Chat** and moves it to
+**CometChat** — in a single prompt to your AI coding agent. The agent does the whole job: it finds
+every place your app uses the old vendor, swaps each supported feature for its CometChat equivalent,
+removes the few features CometChat has no equivalent for, rewrites your token server and webhooks,
+writes a script to import your users and message history, uninstalls the vendor, and checks the build.
+
+It works whether your app uses the vendor's **UI Kit** (their prebuilt chat components) or their
+**SDK / low-level client** (your own UI on their client) — or a mix of both. Every CometChat API it
+writes is fetched from the live CometChat docs, never guessed.
+
+Supported app platforms: **React, Angular, React Native / Expo, iOS, Android, Flutter.**
+
+---
+
+## Before you start (prerequisites)
+
+1. **A CometChat account and app.** Sign up free at [app.cometchat.com](https://app.cometchat.com)
+   and create an app. From **Dashboard → your app**, note the **App ID**, **Region**, and **Auth Key**
+   (under *Credentials*). For importing history you'll also create a **REST API key** (full access) —
+   see step 6.
+   - Create your CometChat app yourself. The migration never creates one for you.
+2. **Node.js 18 or newer** (for `npx` and the data-import script).
+3. **Your app builds today**, on the vendor, with your normal build command. Migrating an app that
+   doesn't build first only hides which errors were yours.
+4. **A clean git working tree.** The agent works on a new `cometchat-migration` branch and never
+   commits — but start from a clean state so the diff is easy to review.
+5. **Your AI coding agent** with the CometChat skills installed (next step). Claude Code is the
+   default; Cursor, Copilot, Windsurf, Cline, Continue, Gemini, Kiro, Replit and others are supported.
+
+---
+
+## Step 1 — Install the CometChat skills into your project
+
+From your project root:
+
+```bash
+npx @cometchat/skills add
+```
+
+That installs the skills for Claude Code and connects the CometChat Docs MCP. For another agent, pass
+`--ide` (for example `--ide cursor`); run `npx @cometchat/skills add --help` for the full list. Commit
+the installed skill files if you want your whole team to share them.
+
+> The skills that do the migration — `cometchat-migrate-from-sendbird` and
+> `cometchat-migrate-from-getstream` — are installed for every platform, so you don't pick one; the
+> agent selects the right one from what your project uses.
+
+## Step 2 — (Optional) fetch your credentials without copy-paste
+
+You can paste your App ID / Region / Auth Key by hand later, or let the credentials CLI fetch them:
+
+```bash
+npx @cometchat/skills-cli@3 auth login       # opens the dashboard in your browser
+npx @cometchat/skills-cli@3 provision run     # writes .cometchat/config.json (git-ignored, owner-only)
+```
+
+The migration reuses `.cometchat/config.json` if it's there, so this saves a step. Skip it if you'd
+rather paste.
+
+## Step 3 — Ask your agent to migrate
+
+Open your project in your agent and say:
+
+```
+migrate my app to CometChat
+```
+
+That's the whole instruction. You don't name the vendor — the agent detects Sendbird or Stream from
+your dependencies. It then runs end-to-end **without stopping to ask you questions**, taking sensible
+defaults and recording each one in the report at the end.
+
+You can also be explicit: *"migrate my app from Sendbird to CometChat"* /
+*"replace Stream Chat with CometChat"*.
+
+### What the agent does, in order
+
+1. **Detects** your framework and which vendor you're on, and creates a `cometchat-migration` git branch.
+2. **Inventories** every use of the vendor: UI Kit screens, SDK/client calls, event handlers, calls,
+   push, the token server, webhooks, env vars and tests.
+3. **Maps each feature** to CometChat, checking the CometChat docs at both levels — the **UI Kit** and
+   the **Chat SDK / REST API**. A feature with a UI Kit component is wired with that component; a
+   feature with only an SDK method is built on that method in your own UI. Every API is taken from the
+   live docs.
+4. **Installs CometChat** and wires init → login → render, keeping your own screens and routes.
+5. **Replaces usage file by file** — UI Kit components for UI-Kit apps, CometChat SDK calls for
+   client-mode apps, or both for a mixed app.
+6. **Removes, in full,** any feature CometChat genuinely doesn't offer (code, buttons, routes,
+   dependencies) — no dead ends left behind.
+7. **Rewrites the server side** — your token endpoint mints CometChat auth tokens; your webhooks map
+   to CometChat webhooks.
+8. **Writes a data-migration script** (`scripts/cometchat-migration/`) for your users, groups and
+   history, then — once the app migration is done — asks for your credentials and **runs the import
+   for you** (dry-run first, then import). If you don't share credentials, it's left for you to run.
+9. **Uninstalls the vendor** and re-runs your package manager.
+10. **Verifies the build** and writes `COMETCHAT_MIGRATION.md`.
+
+## Step 4 — Read the report
+
+At the repo root you'll find **`COMETCHAT_MIGRATION.md`**, and the agent ends its reply with its two
+key lists:
+
+- **Removed — not available in CometChat.** Each row names the feature, the files it touched, what
+  users lose, and the closest CometChat alternative. Review these — this is where you decide whether to
+  rebuild anything a different way or drop it.
+- **Your action items.** The remaining manual steps (below), in order.
+
+## Step 5 — Add your credentials and run it
+
+If you didn't do step 2, put your credentials in the env file the report names (for React that's an
+untracked `.env.local` with `VITE_COMETCHAT_APP_ID` / `VITE_COMETCHAT_REGION` /
+`VITE_COMETCHAT_AUTH_KEY`), then start the app:
+
+```bash
+npm run dev
+```
+
+Sign in as one of **your own** users — the UID your server's `toCometChatId()` produces for them,
+created in Dashboard → **Users** or by the import in Step 6. (A fresh app also seeds sample users such
+as `cometchat-uid-1`; they're fine for a quick smoke test, but never hardcode one — production login is
+your server-minted auth token.) You should see your conversations and be able to send a message.
+
+## Step 6 — Import your existing users and history
+
+Once the app migration is done, the agent asks for your credentials and runs `scripts/cometchat-migration/` for you (dry-run first, then import). If you didn't share credentials at the time, run it yourself:
+
+1. In the CometChat Dashboard, create a **REST API key** with full access.
+2. Read `scripts/cometchat-migration/README.md`, set the environment variables it lists (your vendor
+   export credentials + your CometChat App ID / Region / REST API key).
+3. **Dry-run first**, then import:
+   ```bash
+   node scripts/cometchat-migration/migrate.mjs --dry-run
+   node scripts/cometchat-migration/migrate.mjs
+   ```
+4. Spot-check a few conversations in the app, then delete the export files (they hold user data).
+
+The import uses CometChat's [Data Import API](https://www.cometchat.com/docs/rest-api/data-import) and
+respects its limits (50 records per request, 60 requests per minute). Re-running it is safe.
+
+**Choose a cut-over strategy:**
+- **Hard switch (default here)** — export from the old vendor, import into CometChat, deploy. Simplest; do it in a maintenance window so no messages are sent mid-copy. The generated script does this.
+- **Zero-downtime live migration** — keep both systems in sync while users roll onto the new build gradually. This bridges the two providers and is set up with CometChat's team: [contact sales](https://www.cometchat.com/contact-sales). Pick this if you can't take a window.
+See [Data Import and Migration](https://www.cometchat.com/docs/fundamentals/data-import-and-migration) for both.
+
+## Step 7 — Go to production
+
+- Enable in the CometChat Dashboard any features the report lists (extensions, AI, Search, etc.).
+- For push, upload your FCM / APNs credentials to CometChat.
+- Point your webhooks at the new receiver and pick the events.
+- **Switch login from the dev Auth Key to server-minted auth tokens.** The Auth Key is for development
+  only; in production your server mints a per-user token
+  ([auth tokens](https://www.cometchat.com/docs/rest-api/auth-tokens)) and the client logs in with
+  `loginWithAuthToken()`. The agent leaves this as an action item and, where your app already had a
+  token server, wires it for you.
+- Remove the old vendor's secrets from your CI and hosting, and deactivate the vendor app after the
+  cut-over.
+
+---
+
+## What migrates, and what doesn't
+
+**Migrated** (fetched from the CometChat docs): 1:1 and group chat, conversation list, send / edit /
+delete, typing indicators, read/delivery receipts, attachments, threads, reactions, mentions, polls,
+message search, translation, link previews, presence, group membership and moderation, calls, and push
+— wherever CometChat offers them for your platform.
+
+**Removed** (no CometChat equivalent, examples): scheduled messages, atomic channel counters, custom
+slash commands, arbitrary location sharing, Stream Activity Feeds, and vendor-only dev/QA tooling.
+Every removal is listed in the report with its files and the closest alternative.
+
+**Changed** (works differently): open/livestream channels become public groups; very large groups
+(over 300 members) don't send receipts or typing indicators; a fresh group appears in the list after
+its first message.
+
+---
+
+## Notes
+
+- **One CometChat app for dev, one for production** is the recommended setup; migrate against dev
+  first.
+- **Identity is preserved.** Your existing user IDs are converted to valid CometChat UIDs by one shared
+  rule used by the client, the server and the import script, so logins and imported history line up.
+- **Nothing is destroyed.** The agent works on a branch and never force-deletes non-vendor code; your
+  vendor code is what it removes, by design.
+- If no Sendbird or Stream usage is found, the agent says so and points you at
+  `npx @cometchat/skills add` for a fresh integration instead.

package/README.md

@@ -31,6 +31,24 @@ add chat to my app
 
 The `cometchat` dispatcher routes to `cometchat-onboarding` (discover → understand → plan → approve), then hands a scoped build directive to that platform's `-core` skill, pulling in the others as the approved plan needs them (components, placement, theming, features, calls, push). Iterate afterward — *"add reactions" · "switch to dark mode" · "add a details side panel" · "switch to server-minted auth tokens"* (production auth — server-minted `loginWithAuthToken` — is covered inside each family's `-core` credentials/lifecycle guidance, and by the dedicated `-production` skill where one exists).
 
+### Migrating from Sendbird or Stream (GetStream)
+
+```
+migrate my app to CometChat
+```
+
+In a project that uses Sendbird or Stream Chat, this one prompt runs the whole migration, with no plan/approve round-trip. `detect` spots the vendor (`migrate_from`), and `cometchat-migrate-from-sendbird` / `cometchat-migrate-from-getstream` then:
+- works on a `cometchat-migration` git branch;
+- replaces every supported feature with its CometChat equivalent on your platform's UI Kit or SDK;
+- **fully removes** the features CometChat doesn't have (code, UI entry points, dependencies);
+- rewires your server's token endpoint and webhooks;
+- writes a data-migration script for users, groups and message history and runs it for you once you provide the credentials (after the app migration is done);
+- uninstalls the vendor and checks that the build passes.
+
+It ends with `COMETCHAT_MIGRATION.md` and prints two lists: what was removed, and what you still need to do (credentials, dashboard toggles, running the import).
+
+**Full step-by-step guide (prerequisites, install, run, data import, go-live):** [MIGRATING.md](MIGRATING.md).
+
 ## Credentials (dashboard CLI)
 
 A separate, dashboard-only CLI fetches your App ID / Region / Auth Key so you don't paste them by hand:
@@ -44,7 +62,7 @@ The CLI is dashboard/API-only (`auth · provision · config · features`) — it
 
 ## What's in the pack
 
-A thin `cometchat` router + a `cometchat-onboarding` journey, then a **full skill set per platform**. Every UI-Kit family ships `core` (install · credentials · init→login→render · the golden-path chat surface) plus, as the platform needs them, `components · placement · customization · features · calls · push · migration` and platform extras (`patterns`, `production`, `testing`, `troubleshooting`, `events`, the Android `compose-*` / `kotlin-*` cohorts):
+A thin `cometchat` router + a `cometchat-onboarding` journey + two competitor-migration skills (`cometchat-migrate-from-sendbird`, `cometchat-migrate-from-getstream`, installed for every platform), then a **full skill set per platform**. Every UI-Kit family ships `core` (install · credentials · init→login→render · the golden-path chat surface) plus, as the platform needs them, `components · placement · customization · features · calls · push · migration` and platform extras (`patterns`, `production`, `testing`, `troubleshooting`, `events`, the Android `compose-*` / `kotlin-*` cohorts):
 
 | Family | UI Kit package | Consumption |
 |---|---|---|

package/RULES.md

@@ -4,7 +4,7 @@
 #  which governs how skills are AUTHORED. Keep them in sync when a rule changes.)
 
 ## Code safety
-- APPEND, never REPLACE the user's code. Additive diffs only. Never delete a competing SDK's files/deps without an explicit, waited-for confirmation.
+- APPEND, never REPLACE the user's code. Additive diffs only. Never delete a competing SDK's files/deps without an explicit, waited-for confirmation. (An explicit request to migrate off that SDK IS that confirmation — see § Competitor migration.)
 - No speculative scaffolding; reuse the developer's existing primitives; golden-path defaults over prop sprawl.
 
 ## Platform / package integrity
@@ -105,6 +105,17 @@
 - Reuse the built-in back affordance, don't hand-roll it: `CometChatMessageHeader` ships `hideBackButton` (default `false`) + `onBack()`. On mobile wire `onBack` to clear the selection (pop to the list); on wide set `hideBackButton` (the list is always present).
 - Web recipe: drive the visible pane from selection state + `window.matchMedia("(max-width: 768px)")` (SSR-guarded, with a `change` listener). Panes need explicit height; never transition them with `transform` on a chat wrapper (clips the kit's `position:fixed` overlays — animate `right`/`left`/width). Native (RN/Flutter): stack navigation, one screen per route. Depth + recipe live in your platform's `placement` skill.
 
+## Competitor migration (Sendbird / Stream) — the one-prompt exception
+- "Migrate my app to CometChat / from Sendbird / from Stream (GetStream)" routes to `cometchat-migrate-from-sendbird` / `cometchat-migrate-from-getstream` (detect reports the vendor as `migrate_from`). That request is the user's explicit, up-front approval for the WHOLE migration, so, only inside those skills:
+  - Removing the vendor's code, UI, dependencies and config is the requested outcome, not a violation of append-never-replace. Non-vendor code is still never deleted, only rewired.
+  - Every ask-and-wait point in a companion skill takes its documented default and is listed under "Defaults taken" in the migration report. The clarification contract is suspended for that run; nothing else is.
+  - A feature CometChat has no equivalent for (not in the family's `features.json` AND not in the docs) is REMOVED fully — code, entry points, state, deps — never left as a dead button. Every removal is listed in the final report.
+- A docs lookup that fails because of TOOLING (Docs MCP down, network blocked) is never evidence a feature is unsupported: follow the 3-tier docs ladder, and if still unverifiable, KEEP the feature and flag it — never remove on a tool outage.
+- **The app's OWN name is residue you must not silently rewrite.** A vendor-named project keeps matching the zero-residue grep after a complete migration: the Xcode project/scheme/workspace and Podfile target, the Android package directory and Gradle `namespace`/`applicationId`, the bundle id. Rename what is safe (the JS module name in `app.json` with its `AppDelegate`/`MainActivity` counterparts, the display name, the launch screen) and REPORT the rest as an action item with exact paths — renaming a project, package or bundle id changes the app's identity (signing, store listing, upgrade path) and is the user's call. Never claim zero residue while those files still match: name them and say why they were left.
+- **Renaming a vendor-named storage key signs every existing user out.** `<vendor>@credential` -> `app@credential` collides with "returning users are logged in before the chat renders": the app boots, finds nothing under the new key, and shows the sign-in screen to people who were already signed in. Keep the old key, or read it once as a fallback and migrate the value across — and say which under Behavior changes in the report.
+- Unchanged even here: never provision a CometChat app (use placeholders + an action item); never print secrets; never commit or push (work on a `cometchat-migration` branch); `version_conflict` still stops the build.
+- **Data-migration script:** write it during the migration, but run it ONLY after the app migration is complete AND the user hands over the credentials it needs (the source keys + the CometChat App ID / Region / full-access REST API key). Ask for those credentials once the app is migrated — that credential prompt is the one question the single-prompt contract allows — then run it from env vars (never hardcoded, never committed). If the user declines to share credentials, leave running it as an action item.
+
 ## The CLI is a dashboard/API client only (loaded on demand)
 - **Env-writing and codegen are the SKILL's job** — done by reading your repo and emitting code, never a CLI command. **Detection** is `npx @cometchat/skills detect --json` (the skills pack's offline probe: framework, UI Kit + `version_conflict`, `existing_cometchat` = a CometChat UI Kit/SDK dependency is present), topped up by the skill's own repo read. The dashboard CLI (`@cometchat/skills-cli`, loaded on demand) does DASHBOARD/API operations only: `auth` (dashboard login) + `provision` (fetch an app's App ID/Region/Auth Key) + `config` + **`features`** (enable/disable dashboard **extensions + AI** for an app — `features list`/`enable <id>`/`disable <id>`). It writes no code and knows no framework (see your platform's `core` skill -> `references/setup-credentials.md`). For a feature: the CLI `features enable <id>` flips the DASHBOARD toggle; the SKILL wires the component/prop in code. Installing/refreshing the skill files is the separate `@cometchat/skills add`.
 

package/bin/cometchat-skills.mjs

@@ -424,6 +424,9 @@ function detect() {
         "this looks like a Swift server/CLI package. If it IS an iOS app, pass --family ios.";
     }
   }
+  // Competitor SDKs (Sendbird / Stream) → the cross-family migration skill that replaces them.
+  // null when none — additive, so existing consumers of detect --json are unaffected.
+  result.migrate_from = detectMigrations();
   return result;
 }
 
@@ -455,7 +458,100 @@ function peers() {
     list[i].features = (block.match(/features:\s*(\S+\.json)/) || [])[1];
     list[i].contracts = (block.match(/contracts:\s*(\S+\.json)/) || [])[1];
   });
-  return { entry, peers: list };
+  const gate = (y.match(/^gate:\s*(\S+)/m) || [])[1] || "cometchat-onboarding";
+  const entSec = (y.match(/^enterprise:\s*\n([\s\S]*?)(?=^\S)/m) || [])[1] || "";
+  const enterprise = [...entSec.matchAll(/^\s*-\s*(\S+)/gm)].map((m) => m[1].trim());
+  const cfSec = (y.match(/^crossFamily:\s*\n([\s\S]*?)(?=^\S)/m) || [])[1] || "";
+  const crossFamily = [...cfSec.matchAll(/^\s*-\s*(\S+)/gm)].map((m) => m[1].trim());
+  return { entry, gate, peers: list, migrations: migrationsFrom(y), enterprise, crossFamily };
+}
+
+// `migrations:` (peers.yaml, above `peers:`): one cross-family competitor-migration skill per
+// vendor + the dependency patterns `detect` reports as `migrate_from`. Patterns are single-quoted
+// YAML scalars, so backslashes arrive literally and go straight into RegExp.
+function migrationsFrom(y) {
+  const sec = (y.match(/^migrations:\s*\n([\s\S]*?)(?=^\S)/m) || [])[1] || "";
+  return sec.split(/^\s*-\s*vendor:/m).slice(1).map((block) => {
+    const vendor = (block.match(/^\s*(\S+)/) || [])[1];
+    const q = (k) => (block.match(new RegExp(`^\\s*${k}:\\s*'([^']*)'`, "m")) || [])[1] || null;
+    const label = (block.match(/label:\s*"([^"]+)"/) || [])[1] || vendor;
+    const skill = (block.match(/skill:\s*(\S+)/) || [])[1];
+    return { vendor, label, skill, npm: q("npm"), pub: q("pub"), gradle: q("gradle"), ios: q("ios") };
+  }).filter((m) => m.vendor && m.skill);
+}
+
+// Platform-NEUTRAL skills: installed for every family (entry router, onboarding gate, and the
+// competitor-migration skills). One list, read from peers.yaml, so `add`, the orienting router
+// and the family filter never disagree about what is shared.
+function neutralSkillDirs() {
+  const p = peers();
+  return new Set([p.entry || "cometchat", p.gate, ...(p.migrations || []).map((m) => m.skill), ...(p.enterprise || []), ...(p.crossFamily || [])].filter(Boolean));
+}
+
+// Workspace package dirs for a monorepo: npm/yarn `workspaces` + pnpm-workspace.yaml. A monorepo
+// keeps the vendor dependency in apps/<x>/package.json, not the root. Globs are scanned one level
+// only (`apps/*`; `apps/**` is treated the same, so a package nested deeper isn't found); `!`
+// exclusions are honored; the result is capped.
+function workspaceDirs() {
+  const pkg = readJSON(join(CWD, "package.json")) || {};
+  const ws = Array.isArray(pkg.workspaces) ? pkg.workspaces : (pkg.workspaces && pkg.workspaces.packages) || [];
+  let pnpm = "";
+  try { pnpm = readFileSync(join(CWD, "pnpm-workspace.yaml"), "utf8"); } catch { /* none */ }
+  const patterns = [...ws, ...[...pnpm.matchAll(/^\s*-\s*['"]?([^'"\n#]+?)['"]?\s*$/gm)].map((m) => m[1])];
+  const excluded = patterns.filter((g) => g.startsWith("!")).map((g) => g.slice(1).replace(/\/\*{1,2}$/, ""));
+  const dirs = [];
+  for (const g of patterns) {
+    if (g.startsWith("!")) continue;
+    const m = g.match(/^(.*?)\/\*{1,2}$/);
+    if (!m) { dirs.push(g); continue; }
+    try {
+      for (const d of readdirSync(join(CWD, m[1]), { withFileTypes: true }))
+        if (d.isDirectory() && d.name !== "node_modules") dirs.push(`${m[1]}/${d.name}`);
+    } catch { /* missing dir */ }
+  }
+  const kept = dirs.filter((d) => !excluded.some((x) => d === x || d.startsWith(`${x}/`)));
+  return [...new Set(kept)].slice(0, 50);
+}
+
+// Competitor SDKs present in THIS project (→ the migration skill to run). Reads dependency
+// manifests only — names, not code — so it stays offline and cheap, like the rest of detect.
+function detectMigrations() {
+  const read = (rel) => { try { return readFileSync(join(CWD, rel), "utf8"); } catch { return ""; } };
+  const depsOf = (p) => Object.keys({ ...((p && p.dependencies) || {}), ...((p && p.devDependencies) || {}) });
+  // Root package.json + every workspace package (monorepo): the vendor dep may live in apps/<x>.
+  const npmSources = [["package.json", readJSON(join(CWD, "package.json"))],
+    ...workspaceDirs().map((d) => [`${d}/package.json`, readJSON(join(CWD, d, "package.json"))])]
+    .map(([where, p]) => [where, depsOf(p)]);
+  const pub = read("pubspec.yaml");
+  const pubDeps = [...pub.matchAll(/^\s+([a-z0-9_]+):/gm)].map((m) => m[1]);
+  const gradle = ["app/build.gradle", "app/build.gradle.kts", "build.gradle", "build.gradle.kts",
+    "settings.gradle", "settings.gradle.kts", "gradle/libs.versions.toml"].map(read).join("\n");
+  let entries = [];
+  try { entries = readdirSync(CWD); } catch { /* unreadable cwd */ }
+  const xcode = entries.filter((f) => f.endsWith(".xcodeproj") || f.endsWith(".xcworkspace"));
+  const ios = [read("Podfile"), read("Package.swift"), read("Package.resolved"),
+    ...xcode.flatMap((x) => [read(`${x}/project.pbxproj`),
+      read(`${x}/project.xcworkspace/xcshareddata/swiftpm/Package.resolved`),
+      read(`${x}/xcshareddata/swiftpm/Package.resolved`)])].join("\n");
+  const found = [];
+  for (const m of peers().migrations || []) {
+    const evidence = new Set();
+    const names = (pattern, list, where) => {
+      if (!pattern) return;
+      const re = new RegExp(pattern, "i");
+      for (const d of list) if (re.test(d)) evidence.add(`${where}:${d}`);
+    };
+    const text = (pattern, src, where) => {
+      if (!pattern || !src) return;
+      for (const hit of src.matchAll(new RegExp(pattern, "gi"))) evidence.add(`${where}:${hit[0].toLowerCase()}`);
+    };
+    for (const [where, deps] of npmSources) names(m.npm, deps, where);
+    names(m.pub, pubDeps, "pubspec.yaml");
+    text(m.gradle, gradle, "gradle");
+    text(m.ios, ios, "ios");
+    if (evidence.size) found.push({ vendor: m.vendor, label: m.label, skill: m.skill, evidence: [...evidence].slice(0, 8) });
+  }
+  return found.length ? found : null;
 }
 
 function shippedSkillDirs() {
@@ -483,6 +579,9 @@ function cmdDetect() {
     if (sig.length) console.log(`repo signals:     ${sig.map(([k, v]) => `${k}=${v}`).join("  ")}`);
     if (r.version_conflict) console.log(`⚠️  version_conflict: ${r.version_conflict.detail}  → STOP & reconcile (RULES §3)`);
     if (r.hint) console.log(`hint:             ${r.hint}`);
+    for (const m of r.migrate_from || []) {
+      console.log(`migrate from:     ${m.label} (${m.evidence.join(", ")}) → skill ${m.skill}`);
+    }
   });
 }
 
@@ -555,7 +654,7 @@ function sharedRootDirs() {
   return SHARED_ROOT_DIRS.filter((d) => existsSync(join(PACK_ROOT, d)));
 }
 
-// Only THIS project's family (+ the two platform-neutral skills) is installed.
+// Only THIS project's family (+ the platform-neutral skills: router, gate, competitor migrations) is installed.
 // Installing every family let a React skill out-match its RN twin: React's
 // features triggers are unqualified ('add polls'), RN's say "React Native", so an
 // RN user asking "add polls" matched the WRONG framework's skill (AUDIT-101).
@@ -565,7 +664,7 @@ function sharedRootDirs() {
 function familySkillDirs(fam) {
   const all = shippedSkillDirs();
   if (!fam || !fam.dirPrefix) return all;
-  const neutral = new Set([peers().entry || "cometchat", "cometchat-onboarding"]);
+  const neutral = neutralSkillDirs();
   return all.filter((d) => neutral.has(d) || d.startsWith(fam.dirPrefix));
 }
 
@@ -800,7 +899,7 @@ function generateOrientingMd(reg, dirs, refBase, fam) {
   const kit = (fam && fam.kit_package) || "";
   // Scope the table to THIS family + the platform-neutral router/gate. Listing
   // every family's skills is what let an RN agent read React rows (AUDIT-101).
-  const shared = new Set([entry, "cometchat-onboarding"]);
+  const shared = neutralSkillDirs();
   const scoped = (fam && fam.dirPrefix)
     ? dirs.filter((d) => shared.has(d) || d.startsWith(fam.dirPrefix))
     : dirs;
@@ -821,8 +920,9 @@ function generateOrientingMd(reg, dirs, refBase, fam) {
   md += `## Start here\n\n`;
   md += `1. **Detect** — \`npx @cometchat/skills detect --json\` (framework, installed UI Kit, version_conflict). If \`version_conflict\` is non-null, STOP and reconcile before touching code.\n`;
   md += `2. **Already integrated?** If \`detect\` says \`existing_cometchat: true\`, this is a TASK, not an integration — go **straight** to the matching skill in the table above and skip onboarding. "Change my avatar", "add a logout button", "add polls", "restyle the bubble" are all tasks. Do NOT re-run the plan/approve journey, and do NOT fall back to reading \`node_modules\` when the phrasing is not an exact match — pick the closest row and open it.\n`;
-  md += `3. **Route** — open \`${refBase}/${entry}/SKILL.md\` (the dispatcher); it points to the right task skill for the request.\n`;
-  md += `4. **Follow the skill** — it carries the exact init→login→render, the component props, and the verify steps.\n\n`;
+  md += `3. **Migrating off Sendbird or Stream?** If the user asks to migrate/switch/replace and \`detect\` reports \`migrate_from\` (or the user names the vendor), open that entry's \`skill\` from the table — it runs the whole migration in one pass (no onboarding) and ends with the list of removed features.\n`;
+  md += `4. **Route** — open \`${refBase}/${entry}/SKILL.md\` (the dispatcher); it points to the right task skill for the request.\n`;
+  md += `5. **Follow the skill** — it carries the exact init→login→render, the component props, and the verify steps.\n\n`;
 
   md += `## Hard rules (full text in \`${refBase}/RULES.md\`)\n\n`;
   md += `- **APPEND, never replace** the user's code — additive diffs; confirm before bulk edits.\n`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cometchat/skills",
-  "version": "5.0.0",
+  "version": "5.0.1",
   "workspaces": [
     "packages/*"
   ],
@@ -17,6 +17,9 @@
   },
   "//verify:fences": "Tier-2 fences (verify:fences:web-v7, verify:fences:angular-v5) are in verify:ci but deliberately NOT in default verify: each needs its pinned kit installed in test-suite/typecheck/<family> (git-ignored, not shipped, no postinstall) and hard-exits code 2 when absent — so promoting them into verify would break verify in a clean checkout. Setup: npm run verify:fences:<family>:setup. Rationale + owner CI-cost decision: test-suite/README.md (AUDIT-030).",
   "scripts": {
+    "sync:plugin-version": "node scripts/sync-plugin-version.mjs",
+    "version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin/plugin.json .claude-plugin/marketplace.json",
+    "verify:plugin-manifest": "node test-suite/scripts/verify-plugin-manifest.mjs",
     "lint:skills": "node test-suite/scripts/lint-skills.mjs",
     "verify:catalog": "node test-suite/scripts/verify-catalog.mjs --family web-v7 && node test-suite/scripts/verify-catalog.mjs --family angular-v5",
     "verify:catalog:strict": "node test-suite/scripts/verify-catalog.mjs --family web-v7 --strict-drift && node test-suite/scripts/verify-catalog.mjs --family angular-v5 --strict-drift",
@@ -34,7 +37,7 @@
     "verify:tokens": "node test-suite/scripts/measure-tokens.mjs --all --tolerance 10",
     "verify": "npm run lint:skills && npm run verify:catalog:selftest && npm run verify:family && npm run verify:detection && npm run verify:docs-base && npm run verify:fences:contract && npm run verify:oracle:angular-v5 && npm run verify:catalog && npm run verify:registry && npm run verify:tokens && npm run verify:predicate && npm run verify:catalog:flutter-v6 && npm run verify:registry:flutter-v6",
     "verify:catalog:sync": "node test-suite/scripts/verify-catalog-sync.mjs",
-    "verify:ci": "npm run lint:skills && npm run verify:catalog:selftest && npm run verify:catalog:sync && npm run verify:family && npm run verify:detection && npm run verify:docs-base:strict && npm run verify:fences:contract && npm run verify:oracle:angular-v5 && npm run verify:catalog:strict && npm run verify:registry && npm run verify:fences:web-v7 && npm run verify:fences:angular-v5 && npm run verify:templates:angular-v5 && npm run verify:goldenpath:angular-v5 && npm run verify:tokens && npm run verify:predicate && npm run verify:catalog:flutter-v6 && npm run verify:registry:flutter-v6",
+    "verify:ci": "npm run lint:skills && npm run verify:catalog:selftest && npm run verify:catalog:sync && npm run verify:family && npm run verify:detection && npm run verify:docs-base:strict && npm run verify:fences:contract && npm run verify:oracle:angular-v5 && npm run verify:catalog:strict && npm run verify:registry && npm run verify:fences:web-v7 && npm run verify:fences:angular-v5 && npm run verify:templates:angular-v5 && npm run verify:goldenpath:angular-v5 && npm run verify:tokens && npm run verify:predicate && npm run verify:catalog:flutter-v6 && npm run verify:registry:flutter-v6 && npm run verify:plugin-manifest",
     "catalog:refresh": "node test-suite/scripts/catalog-refresh.mjs",
     "catalog:check": "node test-suite/scripts/catalog-refresh.mjs --check",
     "registry:build": "node test-suite/scripts/build-registry.mjs",
@@ -66,7 +69,8 @@
     "verify:goldenpath:angular-v5": "node test-suite/scripts/verify-golden-path.mjs --family angular-v5",
     "verify:catalog:selftest": "node test-suite/fixtures/catalog-extractor/selftest.mjs",
     "verify:swift-api:ios-v5:setup": "node test-suite/scripts/ios-resolve-interfaces.mjs --out test-suite/typecheck/ios-v5/.interfaces",
-    "verify:swift-api:ios-v5": "node test-suite/scripts/verify-swift-docs-api.mjs --interface test-suite/typecheck/ios-v5/.interfaces/CometChatUIKitSwift.swiftinterface --interface test-suite/typecheck/ios-v5/.interfaces/CometChatSDK.swiftinterface --interface test-suite/typecheck/ios-v5/.interfaces/CometChatCallsSDK.swiftinterface --docs skills/cometchat-ios-core --docs skills/cometchat-ios-components --docs skills/cometchat-ios-placement --docs skills/cometchat-ios-customization --docs skills/cometchat-ios-features --docs skills/cometchat-ios-calls --docs skills/cometchat-ios-push --docs skills/cometchat-ios-migration"
+    "verify:swift-api:ios-v5": "node test-suite/scripts/verify-swift-docs-api.mjs --interface test-suite/typecheck/ios-v5/.interfaces/CometChatUIKitSwift.swiftinterface --interface test-suite/typecheck/ios-v5/.interfaces/CometChatSDK.swiftinterface --interface test-suite/typecheck/ios-v5/.interfaces/CometChatCallsSDK.swiftinterface --docs skills/cometchat-ios-core --docs skills/cometchat-ios-components --docs skills/cometchat-ios-placement --docs skills/cometchat-ios-customization --docs skills/cometchat-ios-features --docs skills/cometchat-ios-calls --docs skills/cometchat-ios-push --docs skills/cometchat-ios-migration",
+    "verify:m9:ios-v5:selftest": "node test-suite/fixtures/ios-v5/m9-swift-extractor-selftest.mjs"
   },
   "keywords": [
     "cometchat",
@@ -104,6 +108,7 @@
   },
   "files": [
     "CHANGELOG.md",
+    "MIGRATING.md",
     "bin",
     ".claude-plugin",
     "skills",

package/peers.yaml

@@ -8,6 +8,49 @@ gate: cometchat-onboarding
 groups:
   web: [react, angular, js]
   mobile: [ios, react-native, android, flutter]
+# COMPETITOR MIGRATION — cross-family skills (one per vendor, installed for EVERY family, like the
+# gate). "Migrate my app to CometChat / from <vendor>" routes STRAIGHT to the vendor's skill: it runs
+# the whole migration in one prompt (no onboarding gate) and lands on the detected family's core.
+# `npx @cometchat/skills detect --json` reports `migrate_from` from these patterns — case-insensitive
+# regexes over dependency NAMES (npm/pub) or manifest TEXT (gradle/ios: build files, Podfile,
+# Package.swift, pbxproj, Package.resolved). Kept ABOVE `peers:` so no peer block parser sees them.
+migrations:
+  - vendor: sendbird
+    label: "Sendbird"
+    skill: cometchat-migrate-from-sendbird
+    npm: '^(@sendbird/|sendbird)'
+    pub: '^sendbird_'
+    gradle: 'com\.sendbird[\w.:-]*'
+    ios: 'sendbird/sendbird-(uikit|chat-sdk|calls)-ios|Sendbird(UIKit|ChatSDK|Calls)|SendBird(UIKit|Calls|SDK)'
+  - vendor: twilio
+    label: "Twilio Conversations"
+    skill: cometchat-migrate-from-twilio
+    npm: '^(@twilio/conversations|twilio-conversations|twilio-chat)$'
+    pub: '^twilio_conversations'
+    gradle: 'com\.twilio:conversations[\w-]*'
+    ios: 'TwilioConversationsClient|twilio-conversations|pod\s+.TwilioConversations'
+  - vendor: getstream
+    label: "Stream (GetStream)"
+    skill: cometchat-migrate-from-getstream
+    npm: '^(stream-chat|@stream-io/stream-chat)'
+    pub: '^stream_chat'
+    gradle: 'io\.getstream:stream-chat[\w-]*'
+    ios: 'getstream/stream-chat-swift|pod\s+.StreamChat'
+# Cross-family skills — authored once, installed for EVERY family (like the gate + migrations); client
+# wiring delegates to the resolved family's core/production skill. `crossFamily:` = accessibility,
+# localization, audit and analytics.
+crossFamily:
+  - cometchat-a11y
+  - cometchat-i18n
+  - cometchat-audit
+  - cometchat-analytics
+# Cross-family ENTERPRISE skills — server/REST/dashboard-side concerns, the same across platforms;
+# installed for every family and routed as neutral pointers (not a peer's `skills:` list).
+enterprise:
+  - cometchat-security
+  - cometchat-compliance
+  - cometchat-self-host
+  - cometchat-moderation
 peers:
   - platform: react
     label: "React v7 UI Kit"
@@ -29,7 +72,7 @@ peers:
     # SHIPPED skills. calls + push + migration are in this pack. push is a THIN, docs-first skill
     # (fetches the notifications docs; its live gate is blocked-external — can't auto-smoke push).
     # The headless JS SDK is NOT a separate skill (its methods are the per-feature fallback inside core).
-    skills: [core, components, placement, customization, patterns, features, calls, push, migration]
+    skills: [core, components, placement, customization, patterns, features, calls, push, migration, production, testing, troubleshooting]
     install_policy: on-demand
     verified: true   # Tier-1 catalog (exports-only web-v7.json) verified vs installed 7.1.0; Tier-2/3 via the demo app build + live smoke
   - platform: angular
@@ -281,9 +324,9 @@ peers:
     # SHIPPED skills. Deliberately NO composite/all-in-one component exists in v5, so `core` teaches
     # the host-composed chat screen (IOS-DOCS-001). `patterns` is omitted: iOS has no Vite/Next/CRA
     # equivalent to consolidate. `migration` covers the documented v4 -> v5 upgrade.
-    skills: [core, components, placement, customization, features, calls, push, migration]
+    skills: [core, components, placement, customization, features, calls, push, migration, production, testing, troubleshooting]
     install_policy: on-demand
-    verified: true   # Tier-1 catalog (ios-v5.json, .swiftinterface-derived) verified vs the published 5.1.19 xcframework (sha256 matches the public Package.swift); Tier-3 = the native harness (xcodebuild + XCUITest on a simulator)
+    verified: true   # Tier-1 catalog (ios-v5.json, .swiftinterface-derived) derived from the 5.1.x xcframework; skills pin exactly CometChatUIKitSwift 5.1.22 (see cometchat-ios-core/references/install.md — 5.1.19 was a packaging regression routed around). Refresh the catalog against 5.1.22 if the two ever diverge. Tier-3 = the native harness (xcodebuild + XCUITest on a simulator)
 
   # ── mobile / Flutter UI Kit v6 ────────────────────────────────────────────────
   # Onboarded via the factory's ADD-FRAMEWORK runbook. Detection: `npx @cometchat/skills detect`

package/registry/android-calls-v5.json

@@ -25,6 +25,16 @@
       "version": "1.1.0",
       "role": "router"
     },
+    {
+      "name": "cometchat-a11y",
+      "version": "1.0.0",
+      "role": "skill"
+    },
+    {
+      "name": "cometchat-analytics",
+      "version": "1.0.0",
+      "role": "skill"
+    },
     {
       "name": "cometchat-android-v5-calls-sdk",
       "version": "1.0.0",
@@ -35,20 +45,50 @@
       "version": "1.0.0",
       "role": "skill"
     },
+    {
+      "name": "cometchat-audit",
+      "version": "1.0.0",
+      "role": "skill"
+    },
+    {
+      "name": "cometchat-compliance",
+      "version": "1.0.0",
+      "role": "skill"
+    },
     {
       "name": "cometchat-flutter-v5-sdk",
       "version": "1.0.0",
       "role": "skill"
     },
+    {
+      "name": "cometchat-i18n",
+      "version": "1.0.0",
+      "role": "skill"
+    },
     {
       "name": "cometchat-js-v5-sdk",
       "version": "1.0.0",
       "role": "skill"
     },
+    {
+      "name": "cometchat-moderation",
+      "version": "1.0.0",
+      "role": "skill"
+    },
     {
       "name": "cometchat-onboarding",
       "version": "1.0.0",
       "role": "skill"
+    },
+    {
+      "name": "cometchat-security",
+      "version": "1.0.0",
+      "role": "skill"
+    },
+    {
+      "name": "cometchat-self-host",
+      "version": "1.0.0",
+      "role": "skill"
     }
   ]
 }