@cometchat/skills 3.0.0 → 3.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CometChat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,15 +1,23 @@
 # cometchat-skills
 
-**Add CometChat to any React project through your AI coding agent.** Works with Claude Code, Cursor, Codex, VS Code Copilot, Windsurf, Cline, Kiro, and [30+ more agents](https://github.com/vercel-labs/skills).
+**Add CometChat to any React or React Native project through your AI coding agent.** Works with Claude Code, Cursor, Codex, VS Code Copilot, Windsurf, Cline, Kiro, and [30+ more agents](https://github.com/vercel-labs/skills).
 
-v3 takes an AI-first approach: your agent has a short conversation with you to understand your project and chat requirements, then writes production-grade integration code tailored to the files you already have.
+v3 takes an AI-first approach: your agent has a short conversation with you to understand your project and chat requirements, then writes production-grade integration code tailored to the files you already have. One slash — `/cometchat` — works for every supported framework, web or React Native.
 
 ## Install
 
+**Web (React, Next.js, React Router, Astro):**
 ```bash
 npx @cometchat/skills add
 ```
 
+**React Native (Expo, bare RN):**
+```bash
+npx @cometchat/skills-native add
+```
+
+Both packages ship the same `cometchat` dispatcher — install whichever matches your project, or both for a monorepo with web + native.
+
 Supported IDEs: Claude Code (default), Cursor, Kiro, VS Code Copilot. Use `--ide <name>` to target a specific one, or `--ide all`.
 
 Then in your IDE:
@@ -20,12 +28,12 @@ Then in your IDE:
 
 ## What happens
 
-1. **Detects** your framework (React / Next.js / React Router / Astro), router, env prefix, existing auth system
+1. **Detects** your framework (React / Next.js / React Router / Astro / Expo / bare React Native), router, env prefix, existing auth system
 2. **Onboards** you to CometChat in the terminal — no browser round-trip. Signup, login, app creation all via the CLI.
-3. **Asks** what you're building (marketplace, SaaS, messaging, support, social, or just exploring) and **where** chat should live in your project — it reads your routes, nav, and components before proposing a placement
+3. **Asks** what you're building (marketplace, SaaS, messaging, support, social, or just exploring) and **where** chat should live in your project — it reads your routes/screens, nav, and components before proposing a placement that fits (route+drawer for web, stack/tab/modal/bottom-sheet for RN)
 4. **Shows the plan** — exactly which files it will create, which it will modify, and which it will not touch — and waits for your approval
-5. **Writes** the provider, integration components, and route/trigger wiring
-6. **Saves** `.env` with the correct framework prefix (`VITE_` / `NEXT_PUBLIC_` / `PUBLIC_`) and records your choices in `.cometchat/config.json`
+5. **Writes** the provider, integration components, and route/screen/trigger wiring
+6. **Saves** `.env` with the correct framework prefix (`VITE_` / `NEXT_PUBLIC_` / `PUBLIC_` / `EXPO_PUBLIC_` / bare for `react-native`) and records your choices in `.cometchat/config.json`
 
 No templates, no experiences to pick — the agent writes real code that fits your app.
 
@@ -33,11 +41,12 @@ No templates, no experiences to pick — the agent writes real code that fits yo
 
 | Framework | Status |
 |---|---|
-| React.js / Vite / CRA | ✅ |
-| Next.js (App Router + Pages Router) | ✅ |
-| React Router v6 / v7 | ✅ |
-| Astro (React islands) | ✅ |
-| React Native | 🔜 Coming soon |
+| React.js / Vite / CRA | ✅ (`@cometchat/skills`) |
+| Next.js (App Router + Pages Router) | ✅ (`@cometchat/skills`) |
+| React Router v6 / v7 | ✅ (`@cometchat/skills`) |
+| Astro (React islands) | ✅ (`@cometchat/skills`) |
+| Expo (managed + Expo Router) | ✅ (`@cometchat/skills-native`) |
+| Bare React Native (CLI) | ✅ (`@cometchat/skills-native`) |
 | Flutter | 🔜 Coming soon |
 | Android / iOS | 🔜 Coming soon |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cometchat/skills",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "publishConfig": {
     "access": "public"
   },
@@ -20,21 +20,22 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/cometchat/cometchat-skills.git"
+    "url": "git+https://github.com/cometchat/cometchat-skills.git"
   },
   "homepage": "https://github.com/cometchat/cometchat-skills#readme",
   "bugs": {
     "url": "https://github.com/cometchat/cometchat-skills/issues"
   },
   "bin": {
-    "cometchat-skills": "./bin/install.js"
+    "cometchat-skills": "bin/install.js"
   },
   "files": [
     "bin/",
-    "skills/"
+    "skills/",
+    "!skills/cometchat-native-*/"
   ],
   "engines": {
-    "node": ">=16"
+    "node": ">=18"
   },
   "scripts": {
     "setup": "node bin/install.js add",

package/skills/cometchat/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: cometchat
-description: Entry-point for CometChat integration. Guides a multi-step interactive conversation to understand the project, gather requirements, and write production-quality integration code.
+description: Entry-point for CometChat integration in any React project — web (React/Next.js/React Router/Astro) and React Native (Expo/bare). Detects the framework, gathers requirements through an interactive conversation, and writes production-quality integration code.
 license: "MIT"
 allowed-tools: "executeBash, readFile, fileSearch, listDirectory, AskUserQuestion"
 metadata:
   author: "CometChat"
   version: "3.0.0"
-  tags: "cometchat dispatcher entry react chat"
+  tags: "cometchat dispatcher entry react nextjs react-router astro expo react-native chat"
 ---
 
 ## Use this skill when
@@ -15,10 +15,20 @@ The user wants to add CometChat to any kind of project. Trigger phrases:
 
 - `/cometchat`
 - "add cometchat", "integrate cometchat", "add chat to my app"
-- "add messaging", "add chat ui"
+- "add messaging", "add chat ui", "add in-app chat"
 
-This is the **entry point**. Do not invoke framework-specific skills
-directly — this dispatcher will route to the right ones.
+This is the **entry point for every framework**. Do NOT invoke
+framework-specific skills directly — this dispatcher detects the
+framework first and routes to the right ones.
+
+**Supported frameworks:**
+
+| Family | Frameworks |
+|---|---|
+| **Web** | React (Vite/CRA), Next.js, React Router v6/v7, Astro |
+| **React Native** | Expo (managed + Expo Router), bare RN CLI |
+
+The web family loads `@cometchat/chat-uikit-react` + `@cometchat/chat-sdk-javascript`. The RN family loads `@cometchat/chat-uikit-react-native` + `@cometchat/chat-sdk-react-native`. The dispatcher decides which set after Step 1's detection.
 
 ## How v3 works
 
@@ -27,11 +37,11 @@ the framework and dump code. You have a conversation with the developer
 to understand their project, their use case, and exactly where chat
 should go — THEN you write code that fits.
 
-The pattern skills teach you:
-- `cometchat-core` — initialization, login, CSS, env vars, provider pattern
-- `cometchat-components` — every component name, props, composition patterns
-- `cometchat-placement` — WHERE to put chat (route, modal, drawer, embed, widget)
-- `cometchat-{framework}-patterns` — framework-specific integration patterns
+Pattern skills (loaded from your context, not via `Skill()`):
+- `cometchat-core` (web) / `cometchat-native-core` (RN) — init, login, provider chain, env vars, anti-patterns
+- `cometchat-components` (web) / `cometchat-native-components` (RN) — component catalog, props, composition
+- `cometchat-placement` (web) / `cometchat-native-placement` (RN) — WHERE to put chat
+- One per-framework skill (`cometchat-{react,nextjs,react-router,astro}-patterns` or `cometchat-native-{expo,bare}-patterns`) — framework-specific details
 
 **Key principle: ask, don't assume.** Every piece of information you need
 from the user should be asked explicitly. Don't guess the route path,
@@ -56,24 +66,61 @@ If no config, run detection:
 npx @cometchat/skills-cli detect --json
 ```
 
-**Then read the project yourself — this is critical:**
+The JSON output includes `framework` (one of `reactjs`, `nextjs`, `react-router`, `astro`, `expo`, `react-native`, or `null`), framework-specific fields (`router`, `expo_mode`, `react_native_version`, `env_prefix`), and a `compatibility.supported` flag. If `supported` is `false`, stop and surface the warnings.
+
+**Then read the project yourself — this is critical.**
+
+**For web frameworks (`reactjs`, `nextjs`, `react-router`, `astro`):**
 - `package.json` — name, dependencies, scripts
 - The source directory structure — list all directories under `src/` or `app/`
-- Find the router: look for `createBrowserRouter`, `app/` directory, `pages/`,
-  `react-router.config.ts`, `astro.config.*`
+- Find the router: `createBrowserRouter`, `app/` directory, `pages/`, `react-router.config.ts`, `astro.config.*`
 - Find the layout: `App.tsx`, `layout.tsx`, `root.tsx`, `Layout.astro`
-- Find the nav: look for components with "nav", "header", "sidebar" in name
+- Find the nav: components with "nav", "header", "sidebar" in name
 - Find existing pages/routes: list them so you can reference them later
 
+**For React Native (`expo`, `react-native`):**
+- `package.json` — name, RN version, all dependencies, scripts
+- Entry file — `index.js` or `App.{tsx,jsx}` or `app/_layout.tsx` (Expo Router)
+- Navigation — look for `@react-navigation/native`, `@react-navigation/stack`, `@react-navigation/bottom-tabs`, or `expo-router`
+- Existing screens — list all files under `screens/`, `src/screens/`, `app/`, or wherever routes live
+- Existing nav structure — read the root navigator to see stack vs tab vs drawer layout
+
 Store this mental map — you'll use it throughout the conversation.
 
-If `compatibility.supported` is `false`, stop and surface the warnings.
+**Compatibility baselines (the CLI enforces these):**
+- Web: react@<18 → upgrade required; nextjs@<13 → warning; astro@<4 → warning
+- RN: react-native@<0.70 → upgrade required; expo@<49 → upgrade required
+
+#### Pattern skills not installed?
+
+The dispatcher routes to either web pattern skills (`cometchat-{core,components,placement,*-patterns}`) or RN pattern skills (`cometchat-native-{core,components,placement,*-patterns}`) based on the detected framework. If the matching set isn't loaded in your context — i.e. the user installed only one of `@cometchat/skills` (web) or `@cometchat/skills-native` (RN) and the framework doesn't match — stop and tell them which package to install:
+
+**If `framework` is `expo` or `react-native` AND `cometchat-native-core` is NOT loaded:**
+> "This is a React Native / Expo project, but the React Native pattern
+> skills aren't installed in this workspace. Install them with:
+> ```
+> npx @cometchat/skills-native add
+> ```
+> then run `/cometchat` again."
+
+**If `framework` is `reactjs`, `nextjs`, `react-router`, or `astro` AND `cometchat-core` is NOT loaded:**
+> "This is a {framework} project, but the web pattern skills aren't
+> installed in this workspace. Install them with:
+> ```
+> npx @cometchat/skills add
+> ```
+> then run `/cometchat` again."
+
+To check, attempt to read `cometchat-core/SKILL.md` (web) or `cometchat-native-core/SKILL.md` (RN) from your loaded skills context. If the read fails, the package isn't installed.
+
+Do NOT attempt to write web UI Kit code into an RN project (CSS imports + `<a href>` + `document.*` will fail at runtime) or RN UI Kit code into a web project (`react-native-gesture-handler`, `@gorhom/bottom-sheet`, native bubble components have no browser equivalents).
 
 ### Step 2 — Set up credentials (onboarding)
 
 **CRITICAL: All onboarding happens via CLI commands. NEVER send the user
-to a browser or dashboard. The CLI handles signup, login, app creation,
-and credential writing — all from the terminal.**
+to a browser or dashboard for credential copy-pasting. The CLI handles
+signup, login, app creation, and credential writing — all from the
+terminal — for every framework.**
 
 If config has `appId` set, verify credentials are in `.env` and skip to Step 3.
 
@@ -107,12 +154,10 @@ This command:
 1. Generates a short-lived session via the CLI auth API.
 2. Opens `https://app.cometchat.com/login?sessionId=<hex>` in the user's default browser.
 3. Polls the auth API every 5 seconds for up to 15 minutes.
-4. When the user finishes signing in (email+password, Google, or GitHub — whatever their account uses), the dashboard marks the session authenticated. The next poll receives the bearer token and stores it in the OS keychain.
+4. When the user finishes signing in, the dashboard marks the session authenticated. The next poll receives the bearer token and stores it in the OS keychain.
 5. Prints `✓ Logged in as <email> (backend: keychain-macos).`
 
-Let the CLI block — do NOT background it, do NOT race it with other
-prompts. The user completes sign-in in the browser tab; the terminal
-waits.
+Let the CLI block — do NOT background it, do NOT race it with other prompts.
 
 Terminal error handling (surface verbatim, stop, do not retry silently):
 - `ACCESS_DENIED` — user clicked Deny in the dashboard.
@@ -120,15 +165,9 @@ Terminal error handling (surface verbatim, stop, do not retry silently):
 - `TIMEOUT` — max polls exhausted before user authorized.
 - `ABORTED` — user Ctrl-C'd the CLI.
 - `NETWORK` — couldn't reach the auth host.
-- `ALREADY_AUTHENTICATED` — this session was already consumed. Re-run
-  `auth login` to mint a fresh session.
-
-After success, verify:
-```bash
-npx @cometchat/skills-cli auth status --json
-```
+- `ALREADY_AUTHENTICATED` — this session was already consumed. Re-run `auth login` to mint a fresh session.
 
-If `status` is `"logged-in"`, proceed to **Step 2c**.
+After success, verify via `auth status --json` and proceed to **Step 2c**.
 
 #### Step 2b — Sign up (new account, browser flow)
 
@@ -136,26 +175,11 @@ If `status` is `"logged-in"`, proceed to **Step 2c**.
 npx @cometchat/skills-cli auth signup
 ```
 
-Same polling flow as Step 2a, but the CLI opens
-`https://app.cometchat.com/signup?sessionId=<hex>`. The browser
-handles everything — email, name, password, verification email, role,
-industry. The CLI never sees any of those values. When the user
-finishes signup in the browser, the next poll stores the bearer token
-in the OS keychain and the CLI prints `✓ Logged in as <email>`.
-
-No role / name / verification-code questions in the chat. The dashboard
-owns that flow now; skipping it keeps the user's password and verification
-code out of the transcript.
-
-Error codes match Step 2a (ACCESS_DENIED, EXPIRED, TIMEOUT, ABORTED,
-NETWORK, ALREADY_AUTHENTICATED). Surface verbatim and stop.
+Same polling flow as Step 2a, but the CLI opens the signup URL. The browser handles email, name, password, verification email, role, industry. The CLI never sees any of those values.
 
-After success, verify:
-```bash
-npx @cometchat/skills-cli auth status --json
-```
+No role / name / verification-code questions in the chat. The dashboard owns that flow now; skipping it keeps the user's password and verification code out of the transcript.
 
-If `status` is `"logged-in"`, proceed to **Step 2c**.
+Error codes match Step 2a. After success, verify via `auth status --json` and proceed to **Step 2c**.
 
 #### Step 2c — Pick or create an app
 
@@ -171,28 +195,20 @@ npx @cometchat/skills-cli provision list --json
 >
 > Which one should I use, or should I create a new one?"
 
-**For an existing app**, fetch credentials and wire everything in one call
-(pass `--framework` from Step 1 detection — one of `reactjs`, `nextjs`,
-`react-router`, `astro`):
+**For an existing app**, fetch credentials and wire everything in one call. Pass `--framework` from Step 1 detection (one of `reactjs`, `nextjs`, `react-router`, `astro`, `expo`, `react-native`):
 ```bash
 npx @cometchat/skills-cli provision setup \
   --app-id "<selected-appId>" --framework "<framework>" --json
 ```
 
-This creates/updates `.env` with the correct prefix AND writes
-`.cometchat/config.json` in one step. Output is compact:
-`{ appId, region, framework, envFile, configPath }` — no authKey echoed
-back, no multi-command chain. Skip ahead to "Tell the user" below.
+This creates/updates the env file with the correct prefix AND writes `.cometchat/config.json` in one step. Output is compact: `{ appId, region, framework, envFile, configPath }` — no authKey echoed back.
 
 **If no apps exist** (or user wants new), collect:
 1. App name — suggest `<project-name>-chat` from package.json `name`
-2. Region — use `AskUserQuestion`:
+2. Region — `AskUserQuestion`:
    - **question:** "Which region for your CometChat app?"
    - **header:** "Region"
-   - **options:**
-     1. label: "US", description: "United States (recommended)"
-     2. label: "EU", description: "Europe"
-     3. label: "India", description: "India"
+   - **options:** US (recommended), EU, India
 
    **Region key mapping** (CLI expects lowercase):
    | Label | `--region` value |
@@ -200,18 +216,12 @@ back, no multi-command chain. Skip ahead to "Tell the user" below.
    | US | `us` |
    | EU | `eu` |
    | India | `in` |
-3. Industry — use `AskUserQuestion`:
-   - **question:** "What's your app's industry?"
-   - **header:** "Industry"
-   - **options:**
-     1. label: "SaaS / Business", description: ""
-     2. label: "Marketplace", description: ""
-     3. label: "Social / Community", description: ""
-     4. label: "Other", description: ""
+3. Industry — `AskUserQuestion`:
+   - **options:** SaaS / Business, Marketplace, Social / Community, Other (or finer-grained from the table below)
 
 **Industry key mapping:**
 
-| Label | --industry value |
+| Label | `--industry` value |
 |---|---|
 | SaaS / Business | `saas_businesses` |
 | Marketplace | `online_marketplaces` |
@@ -225,30 +235,16 @@ back, no multi-command chain. Skip ahead to "Tell the user" below.
 | On-demand Services | `on_demand_services` |
 | Other | `other` |
 
-**Confirm before creating:**
-> "I'll create a CometChat app:
-> - Name: test-cometchat-vite-chat
-> - Region: US
-> - Industry: SaaS / Business
->
-> Go ahead?"
-
-Then create the app AND wire `.env` AND save config in one step. Pass
-`--framework` from Step 1 detection (one of `reactjs`, `nextjs`,
-`react-router`, `astro`):
+**Confirm before creating, then:**
 ```bash
 npx @cometchat/skills-cli provision setup \
   --name "<name>" --region "<region>" --industry "<industry_key>" \
   --framework "<framework>" --json
 ```
 
-Output is compact: `{ appId, region, framework, envFile, configPath }`.
-The authKey is written to the env file but is NOT echoed to stdout, so
-credentials don't appear multiple times in the transcript. This replaces
-the old `provision create` → `provision use` → `config init` chain.
+The authKey is written to the env file but is NOT echoed to stdout, so credentials don't appear multiple times in the transcript.
 
-Tell the user: "Your CometChat account and app are ready. Credentials
-saved to `.env`. Let's set up the integration."
+Tell the user: "Your CometChat account and app are ready. Credentials saved to `<envFile>`. Let's set up the integration."
 
 #### Step 2d — Paste keys manually
 
@@ -260,19 +256,37 @@ Tell the user which env vars to set based on the detected framework:
 | nextjs | `.env.local` | `NEXT_PUBLIC_COMETCHAT_APP_ID`, `NEXT_PUBLIC_COMETCHAT_REGION`, `NEXT_PUBLIC_COMETCHAT_AUTH_KEY` |
 | react-router | `.env` | `VITE_COMETCHAT_APP_ID`, `VITE_COMETCHAT_REGION`, `VITE_COMETCHAT_AUTH_KEY` |
 | astro | `.env` | `PUBLIC_COMETCHAT_APP_ID`, `PUBLIC_COMETCHAT_REGION`, `PUBLIC_COMETCHAT_AUTH_KEY` |
+| expo (managed + Expo Router) | `.env` | `EXPO_PUBLIC_COMETCHAT_APP_ID`, `EXPO_PUBLIC_COMETCHAT_REGION`, `EXPO_PUBLIC_COMETCHAT_AUTH_KEY` |
+| react-native (bare CLI) | `.env` | `COMETCHAT_APP_ID`, `COMETCHAT_REGION`, `COMETCHAT_AUTH_KEY` (paired with `react-native-dotenv`) |
 
 > "Grab your credentials from https://app.cometchat.com → Your App →
 > API & Auth Keys. Create the env file above and tell me when done."
 
+**Bare RN extra step.** Bare RN doesn't ship a public-env-prefix convention — pair the env file with `react-native-dotenv`:
+```bash
+npm install --save-dev react-native-dotenv
+```
+and add the plugin to `babel.config.js`:
+```js
+module.exports = {
+  presets: ["module:@react-native/babel-preset"],
+  plugins: [["module:react-native-dotenv"]],
+};
+```
+Then `import { COMETCHAT_APP_ID, COMETCHAT_REGION, COMETCHAT_AUTH_KEY } from "@env";` in the provider.
+
 After they confirm, verify:
 ```bash
 npx @cometchat/skills-cli config init --json
 ```
 
+#### Never log the Auth Key
+
+After writing credentials, don't echo the Auth Key back in the transcript. Confirm as `✓ Wrote <PREFIX>COMETCHAT_AUTH_KEY (hidden)`.
+
 ### Step 3 — Interactive requirements gathering
 
-This is the core of v3. A multi-step conversation that gathers everything
-you need before writing a single line of code.
+This is the core of v3. A multi-step conversation that gathers everything you need before writing a single line of code.
 
 #### 3a. "What are you building?"
 
@@ -283,19 +297,20 @@ Otherwise, use `AskUserQuestion`:
 - **header:** "Your app"
 - **multiSelect:** false
 - **options:**
-  1. label: "Messaging app", description: "Chat is the main feature — like Slack, Discord, or WhatsApp."
-  2. label: "Marketplace or platform", description: "Buyers and sellers communicate — like Airbnb, eBay, or Fiverr."
-  3. label: "SaaS or dashboard", description: "Team chat or support chat inside a product — like Notion or Intercom."
-  4. label: "Social or community", description: "User profiles with messaging — like a dating app or forum."
+  1. label: "Messaging app", description: "Chat is the main feature — like Slack, Discord, WhatsApp, or Telegram."
+  2. label: "Marketplace or platform", description: "Buyers and sellers communicate — like Airbnb, eBay, OfferUp, or Depop."
+  3. label: "SaaS or productivity", description: "Team chat or support chat inside a product — like Notion, Intercom, or Linear."
+  4. label: "Social or community", description: "User profiles with messaging — like a dating app or community forum."
   5. label: "Support or helpdesk", description: "Customer-to-agent communication."
   6. label: "Just exploring", description: "Quick demo — fastest path to see chat working."
 
-**If "Just exploring":** skip the rest of Step 3. Use `cometchat apply`
-demo mode in Step 5.
+**If "Just exploring":** skip the rest of Step 3 and scaffold the minimal integration in Step 5 — one route/screen showing `<CometChatConversations />` with `cometchat-uid-1` pre-logged-in.
 
 #### 3b. Show what you recommend and why
 
-Based on the intent, present the recommendation:
+The recommendation table differs by family because the placement vocabulary is different (web has routes/drawers/widgets; RN has screens/tabs/sheets):
+
+**Web family (reactjs, nextjs, react-router, astro):**
 
 | Intent | What you'll set up |
 |---|---|
@@ -305,18 +320,25 @@ Based on the intent, present the recommendation:
 | **Social / community** | A full messenger page with tabs: Chats, Calls, Users, Groups. |
 | **Support** | A floating widget bubble in the bottom-right corner. |
 
-When explaining, reference the ASCII art from `cometchat-placement`
-("Visual reference — experience layouts") so the user can visualize it.
+**React Native family (expo, react-native):**
+
+| Intent | What you'll set up |
+|---|---|
+| **Messaging app** | A dedicated "Messages" bottom tab. Conversations list → tap a conversation → message thread. |
+| **Marketplace** | A "Chat with seller" button on the product screen that opens a modal with the message thread. Plus an "Inbox" stack screen for all conversations. |
+| **SaaS / productivity** | A "Chat" stack screen accessible from the nav or a header button. Optionally a bottom sheet for quick replies. |
+| **Social / community** | A "Messages" bottom tab with conversations list + message thread. Plus a "Message" button on user profile screens that opens a modal. |
+| **Support** | A modal triggered from a "Help" or "Support" button in the header or settings. |
+
+When explaining, reference the ASCII diagrams from `cometchat-placement` (web) or `cometchat-native-placement` (RN) so the user can visualize.
 
-Ask: "Does this sound right, or do you want a different approach?"
-Let them override.
+Ask: "Does this sound right, or do you want a different approach?" Let them override.
 
 #### 3c. Ask where things should go
 
-**Show the user their actual project structure** — list the pages/routes
-you found in Step 1. Then ask placement-specific questions:
+**Show the user their actual project structure** — list the pages/routes/screens you found in Step 1. Then ask placement-specific questions appropriate to the family.
 
-**For Route placement (messaging, social):**
+**Web — Route placement (messaging, social):**
 > "I found these pages in your project:
 >   - /  (home)
 >   - /about
@@ -325,59 +347,88 @@ you found in Step 1. Then ask placement-specific questions:
 >
 > Where should the messages page live?"
 
-Default suggestion: `/messages`. Let user type a custom path.
+Default: `/messages`. Let user type a custom path.
 
-**For Drawer placement (marketplace):**
+**Web — Drawer placement (marketplace):**
 > "Which page should have the 'Chat' button that opens the drawer?
-> I found these pages:
->   - app/products/[id]/page.tsx
->   - app/listings/page.tsx
->   - app/profile/[id]/page.tsx
->
-> Which one?"
+> I found these pages: ..."
 
-After they pick, read that page file. Look for existing buttons,
-actions, or interactive elements. Ask:
-> "I see a 'Contact Seller' button in ProductDetail.tsx at line 45.
-> Should I wire the chat drawer to that button, or add a new one?"
+Read the picked page. Look for existing buttons, actions, or interactive elements. Ask whether to wire to the existing button or add a new one.
 
-**For Modal placement (SaaS):**
+**Web — Modal placement (SaaS):**
 > "Where should the 'Open chat' button go? I found these components
-> that look like navigation:
->   - src/components/Navbar.tsx
->   - src/components/Sidebar.tsx
->
-> Which one should have the chat trigger?"
+> that look like navigation: ..."
 
-**For Widget placement (support):**
+**Web — Widget placement (support):**
 > "Should the widget appear on all pages, or only specific ones?"
 
-**For combinations (marketplace = drawer + route):**
-Ask both questions in sequence. The drawer and route are separate
-components wired into separate places.
+**RN — Bottom tab placement (messaging, social):**
+> "I found these bottom tabs in your navigator at App.tsx:
+>   - Home
+>   - Profile
+>   - Settings
+>
+> Where should the 'Messages' tab go? (At the end, or pick a position.)"
+
+**RN — Stack screen placement (saas, marketplace inbox):**
+> "I found these stack screens in your root navigator: ...
+>
+> What should I call the chat screen? Default: MessagesScreen."
+
+**RN — Modal placement (marketplace, support):**
+> "Which screen should have the 'Chat' button that opens the modal?
+> I found these screens: ..."
+
+Read the picked screen. Look for existing buttons. Ask whether to wire to it or add a new one.
+
+**RN — BottomSheet placement (quick reply, support):**
+> "Bottom sheets slide up from below. Should the sheet be:
+>   1. Draggable (user can dismiss by swiping down) — uses @gorhom/bottom-sheet
+>   2. Fixed overlay — uses CometChat's built-in CometChatBottomSheet
+>
+> Which one?"
+
+**Combinations** (marketplace = drawer/modal + inbox): ask both questions in sequence — they're separate components wired into separate places.
+
+**Expo Router projects** — adapt screen names to file paths:
+- Stack screen → `app/messages.tsx` (or the path the user picks)
+- Bottom tab → file under `app/(tabs)/messages.tsx` + update `app/(tabs)/_layout.tsx`
+- Modal → `app/(modals)/chat.tsx` with `presentation: "modal"` in the parent `_layout.tsx`
 
 #### 3d. Detect and ask about authentication
 
-Read the project's `package.json` and source files. Look for auth:
+Read the project's `package.json` and source files. Look for auth.
 
+**Web auth libraries:**
 - `next-auth` / `@auth/core` → NextAuth
 - `@clerk/nextjs` / `@clerk/clerk-react` → Clerk
 - `@supabase/supabase-js` + auth usage → Supabase Auth
 - `firebase` / `firebase/auth` → Firebase Auth
 - `passport` → Passport.js
 - `jsonwebtoken` / `jose` → Custom JWT
-- None detected → no auth
+
+**RN auth libraries:**
+- `firebase` / `@react-native-firebase/auth` → Firebase Auth
+- `@clerk/clerk-expo` / `@clerk/clerk-react-native` → Clerk
+- `@supabase/supabase-js` + auth usage → Supabase Auth
+- `react-native-auth0` → Auth0
+- `aws-amplify` + auth module → AWS Cognito
+- `@react-native-google-signin/google-signin` → Google Sign-In (usually paired with something above)
+- `expo-auth-session` / `expo-secure-store` → Expo Auth Session (custom)
+
+**None detected** → no auth.
 
 Report what you found and ask:
 
 If auth detected:
-> "I see you're using [NextAuth / Clerk / etc.]. Here's how CometChat
-> will work with it:
+> "I see you're using [NextAuth / Firebase Auth / etc.]. Here's how
+> CometChat will work with it:
 >
 > - **Development (now):** I'll use CometChat's Auth Key for quick
->   testing with pre-seeded users (cometchat-uid-1, uid-2, etc.)
-> - **Production (later):** Your server will call CometChat's REST API
->   to generate per-user auth tokens. I can set this up now or later.
+>   testing with pre-seeded users (cometchat-uid-1 through uid-5).
+> - **Production (later):** Your server will mint per-user auth tokens
+>   via the CometChat REST API. I can set this up now or later
+>   (see `cometchat-production` / `cometchat-native-production`).
 >
 > Start with dev mode for now? You can upgrade to production auth
 > anytime by choosing 'Set up production auth' from the menu."
@@ -396,148 +447,197 @@ If the user has auth AND wants to set up production mode now:
 > "How should your app's users map to CometChat users?
 >
 > 1. Use your existing user ID as the CometChat UID (simplest)
-> 2. Generate a separate CometChat UID and store it in your database
-> 3. Let me just set up dev mode for now
->
-> Option 1 works if your user IDs are alphanumeric strings (no spaces,
-> no special characters). What does a typical user ID look like in
-> your system?"
+> 2. Generate a separate CometChat UID and store it alongside your user record
+> 3. Let me just set up dev mode for now"
 
-If they share an example, validate it's CometChat-compatible
-(alphanumeric, underscores, hyphens — no spaces or special chars).
+If they share an example, validate it's CometChat-compatible (alphanumeric, underscores, hyphens — no spaces or special chars; max 100 chars). Firebase UIDs, Clerk user IDs, Supabase UUIDs, and Auth0 `sub` claims are all CometChat-compatible by default.
 
 #### 3f. Confirm the plan
 
-**This is critical. Show EXACTLY what you'll do before doing it.**
+**This is critical. Show EXACTLY what you'll do before doing it.** The plan format differs by framework.
 
+**Web example (Next.js, marketplace):**
 > "Here's what I'll create:
 >
 > **New files:**
-> - `app/providers/CometChatProvider.tsx` — initialization + login
-> - `app/messages/page.tsx` — inbox with conversation list + message view
-> - `app/components/ChatDrawer.tsx` — slide-out drawer for product page chat
-> - `.env.local` — CometChat credentials (already filled)
+> - `app/providers/CometChatProvider.tsx`
+> - `app/messages/page.tsx`
+> - `app/components/ChatDrawer.tsx`
+> - `.env.local`
 >
 > **Files I'll modify:**
-> - `app/products/[id]/page.tsx` — add ChatDrawer import + trigger button
-> - `app/layout.tsx` — wrap children with CometChatProvider
+> - `app/products/[id]/page.tsx` — add ChatDrawer trigger
+> - `app/layout.tsx` — wrap with CometChatProvider
 > - `app/components/Navbar.tsx` — add 'Messages' link
 >
-> **Files I will NOT touch:**
-> - `app/page.tsx` (your home page)
-> - Any other existing pages
+> **Dependencies:** @cometchat/chat-sdk-javascript, @cometchat/chat-uikit-react
 >
-> **Dependencies to install:**
-> - @cometchat/chat-sdk-javascript
-> - @cometchat/chat-uikit-react
+> **Auth mode:** Development (Auth Key).
+> Proceed? [y/n]"
+
+**RN example (Expo Router, messaging):**
+> "Here's what I'll create:
 >
-> **Auth mode:** Development (Auth Key). Upgrade to production
-> with `/cometchat` → 'Set up production auth' when ready.
+> **New files:**
+> - `providers/CometChatProvider.tsx`
+> - `app/(tabs)/messages.tsx`
+> - `.env`
 >
+> **Files I'll modify:**
+> - `app/_layout.tsx` — wrap with the four-wrapper chain
+> - `app/(tabs)/_layout.tsx` — add the Messages tab
+> - `index.js` — `import 'react-native-gesture-handler'` at line 1 (if missing)
+>
+> **Dependencies (via `npx expo install`):**
+> @cometchat/chat-uikit-react-native, @cometchat/chat-sdk-react-native,
+> react-native-gesture-handler, react-native-reanimated,
+> react-native-safe-area-context, react-native-screens,
+> @react-native-async-storage/async-storage, @react-native-community/netinfo,
+> react-native-video, react-native-image-picker, react-native-document-picker,
+> react-native-vector-icons, react-native-fs
+>
+> **Auth mode:** Development (Auth Key).
 > Proceed? [y/n]"
 
-Wait for explicit confirmation. If the user says no or wants changes,
-go back to the relevant question and re-ask.
+**Bare RN variant** — same as Expo, except `npm install` instead of `npx expo install`, plus:
+- Run `cd ios && pod install`
+- Patch `ios/<Name>/Info.plist`, `android/app/src/main/AndroidManifest.xml` for permissions
+- Add `ios/<Name>/PrivacyInfo.xcprivacy` (Apple Privacy Manifest)
+- Patch `android/build.gradle` for the async-storage Maven repo (v3+)
+
+Wait for explicit confirmation. If the user says no or wants changes, go back to the relevant question and re-ask.
 
 ### Step 4 — Reference pattern skills
 
-**All 13 skills are already loaded in your context** as `.claude/skills/`
-files. Do NOT use the `Skill()` tool — that's for a different system.
-Instead, simply read and follow the instructions in these skills:
+**All skills are already loaded in your context** as `.claude/skills/` files. Do NOT use the `Skill()` tool. Read and follow them directly.
 
+**For web frameworks:**
 1. `cometchat-core` — initialization, provider, CSS, anti-patterns
 2. `cometchat-components` — component catalog, composition patterns
-3. Framework skill for the detected framework:
+3. Framework-specific:
    - `reactjs` → `cometchat-react-patterns`
    - `nextjs` → `cometchat-nextjs-patterns`
    - `react-router` → `cometchat-react-router-patterns`
    - `astro` → `cometchat-astro-patterns`
 4. `cometchat-placement` — placement pattern for the chosen approach
 
-These are reference documents in your context, not tool calls.
+**For React Native:**
+1. `cometchat-native-core` — init, login, four-wrapper provider chain, env vars, anti-patterns
+2. `cometchat-native-components` — component catalog
+3. Framework-specific:
+   - `expo` (managed + Expo Router) → `cometchat-native-expo-patterns`
+   - `react-native` (bare CLI) → `cometchat-native-bare-patterns`
+4. `cometchat-native-placement` — placement pattern (stack/tab/modal/bottom-sheet/embed)
 
 ### Step 5 — Write the integration
 
-Execute the confirmed plan. For each file:
+Execute the confirmed plan. The order of operations is the same for every framework, but the file names + provider shape differ.
 
-1. **CometChatProvider** — follow the framework skill's provider pattern.
-   Use the correct env var prefix. Module-level `initialized` guard.
-   Mount at the level agreed in Step 3f.
+**Web — common steps:**
 
+1. **CometChatProvider** — follow the framework skill's provider pattern. Use the correct env var prefix. Module-level `initialized` guard. Mount at the level agreed in Step 3f.
 2. **Chat component(s)** — follow the placement skill's pattern.
-   Use the component compositions from the components skill.
-   If drawer/modal: connect to the specific user/group the user specified.
-
-3. **Wire into existing project** — READ each file before modifying:
-   - Router: add the route entry. Show the user the diff.
-   - Nav: add the link. Show the user the diff.
-   - Trigger page: add the drawer/modal import + trigger button. Show diff.
-
+3. **Wire into existing project** — READ each file before modifying. Add the route, nav link, drawer/modal trigger.
 4. **CSS import** — add once at the root level per framework conventions.
-
-5. **Environment variables** — write `.env` with the correct prefix.
-   If auth key is already there from the wizard, don't duplicate.
-
+5. **Environment variables** — write the env file with the correct prefix.
 6. **Install dependencies:**
    ```bash
    npm install @cometchat/chat-sdk-javascript @cometchat/chat-uikit-react
    ```
 
-7. **Update config.json** — save all the choices in one call:
+**React Native — common steps:**
+
+1. **Entry file** (`index.js` / `App.tsx` / `app/_layout.tsx`) — verify `import "react-native-gesture-handler";` is **line 1**. Not line 2, not after another import. Non-negotiable.
+2. **CometChatProvider** — follow `cometchat-native-core` § 6. Module-level `initialized` guard. Module-level `loginInFlight` promise for login concurrency.
+3. **Four-wrapper chain** — wrap the app's root in this exact order:
+   ```tsx
+   <GestureHandlerRootView style={{ flex: 1 }}>
+     <SafeAreaProvider>
+       <CometChatThemeProvider>
+         <CometChatProvider>
+           {/* navigator / Expo Router <Stack> */}
+         </CometChatProvider>
+       </CometChatThemeProvider>
+     </SafeAreaProvider>
+   </GestureHandlerRootView>
+   ```
+4. **Chat screen(s)** — follow `cometchat-native-placement`'s pattern.
+5. **Every `<CometChatMessageList>` MUST pass `hideReplyInThreadOption={true}`** (see hard rules).
+6. **Wire into existing project** — READ each file before modifying.
+7. **Environment variables** — write `.env` with the correct prefix (`EXPO_PUBLIC_` for Expo, bare for `react-native`).
+8. **Install dependencies:**
+
+   **Expo managed:**
    ```bash
-   npx @cometchat/skills-cli config save \
-     --intent "<intent>" \
-     --experience <n> \
-     --placement "<type>" \
-     --placement-path "<path>" \
-     --auth-mode "<mode>" --json
+   npx expo install @cometchat/chat-uikit-react-native @cometchat/chat-sdk-react-native \
+     react-native-gesture-handler react-native-reanimated react-native-safe-area-context \
+     react-native-screens @react-native-async-storage/async-storage \
+     @react-native-community/netinfo react-native-video react-native-image-picker \
+     react-native-document-picker react-native-vector-icons react-native-fs
    ```
-   Pass only the fields you have — `config save` accepts any subset.
-   This replaces the old 5-command `config set k v` chain. Omit
-   `--experience` in the AI-written path (it only applies to CLI-
-   generated experiences 1/2/3).
-
-8. **Record state so Phase B commands work — DO NOT SKIP.** Every
-   Phase B command (`info`, `status`, `doctor`, `verify`, `uninstall`,
-   `apply-theme`, `apply-feature`, `add-widget`, `add-user-mgmt`,
-   `production-auth`) reads `.cometchat/state.json` to know what the
-   integration looks like. Without this step, every one of them reports
-   "not integrated in this project" even though the code is there, and
-   the user can't iterate on their integration at all.
-
-   Pass every file you wrote (owned) and every existing file you patched:
+
+   **Bare RN:**
    ```bash
-   npx @cometchat/skills-cli state record \
-     --framework "<framework>" \
-     --placement "<type>" \
-     --placement-path "<path>" \
-     --auth-mode "<mode>" \
-     --files-owned "src/providers/CometChatProvider.tsx,src/components/ChatDrawer.tsx,src/pages/MessagesPage.tsx" \
-     --files-patched "src/main.tsx:v3/main.tsx,src/App.tsx:v3/App.tsx,src/components/Layout.tsx:v3/Layout.tsx" \
-     --json
+   npm install @cometchat/chat-uikit-react-native @cometchat/chat-sdk-react-native \
+     react-native-gesture-handler react-native-reanimated react-native-safe-area-context \
+     react-native-screens @react-native-async-storage/async-storage \
+     @react-native-community/netinfo react-native-video react-native-image-picker \
+     react-native-document-picker react-native-vector-icons react-native-fs
+   cd ios && pod install && cd ..
    ```
 
-   - `--files-owned` — comma-separated list of every NEW file you wrote
-     (the provider, drawer, inbox page, etc.). The CLI computes SHA-256
-     checksums for each so it can detect drift later.
-   - `--files-patched` — comma-separated `path:patch_id` pairs for every
-     EXISTING file you modified (main.tsx, App.tsx, Layout.tsx, nav, the
-     trigger page). `patch_id` can be any stable label — `v3/<filename>`
-     is a reasonable default.
-
-   If this call errors (CLI flag mismatch, missing --framework, etc.),
-   surface the error and retry with the correct flags rather than moving
-   on. A completed Phase A with a missing state.json is worse than a
-   visible error — the user discovers the breakage later when they try
-   to add a feature or run diagnostics.
-
-**Exception — "Just exploring" / demo mode:**
+   **Reanimated plugin (both):** verify `react-native-reanimated/plugin` is the LAST entry in `babel.config.js` `plugins` array. Metro cache is sensitive to plugin order.
+
+9. **Native config (bare RN only):**
+   - `ios/<Name>/Info.plist` — add `NSCameraUsageDescription`, `NSPhotoLibraryUsageDescription`, `NSMicrophoneUsageDescription`
+   - `android/app/src/main/AndroidManifest.xml` — add `CAMERA`, `RECORD_AUDIO`, `READ_MEDIA_IMAGES`, `READ_EXTERNAL_STORAGE` permissions
+   - `ios/<Name>/PrivacyInfo.xcprivacy` — add the 4 required API codes (C617.1, CA92.1, 35F9.1, E174.1). See `cometchat-native-bare-patterns`.
+   - `android/build.gradle` — async-storage Maven repo if v3+
+
+   **Expo managed** — all of this goes in `app.json` under `plugins` and `ios.infoPlist` / `android.permissions`. See `cometchat-native-expo-patterns`.
+
+#### Step 5 — common to ALL frameworks
+
+After the framework-specific work above, every integration ends the same way:
+
+10. **Update config.json** — save all the choices in one call:
+    ```bash
+    npx @cometchat/skills-cli config save \
+      --intent "<intent>" \
+      --placement "<type>" \
+      --placement-path "<path>" \
+      --auth-mode "<mode>" --json
+    ```
+    Pass only the fields you have — `config save` accepts any subset.
+
+11. **Record state so Phase B commands work — DO NOT SKIP.** Every Phase B command (`info`, `status`, `doctor`, `verify`, `uninstall`, `apply-theme`, `apply-feature`, `add-widget`, `add-user-mgmt`, `production-auth`) reads `.cometchat/state.json` to know what the integration looks like. Without this step, every one of them reports "not integrated in this project" even though the code is there.
+
+    Pass every file you wrote (owned) and every existing file you patched:
+    ```bash
+    npx @cometchat/skills-cli state record \
+      --framework "<framework>" \
+      --placement "<type>" \
+      --placement-path "<path>" \
+      --auth-mode "<mode>" \
+      --files-owned "<comma-list of new files>" \
+      --files-patched "<comma-list of path:patch_id pairs>" \
+      --json
+    ```
+
+    - `--files-owned` — comma-separated list of every NEW file you wrote (provider, drawer, inbox page, screen). The CLI computes SHA-256 checksums for each so it can detect drift later.
+    - `--files-patched` — comma-separated `path:patch_id` pairs for every EXISTING file you modified. `patch_id` can be any stable label — `v3/<filename>` is a reasonable default.
+
+    If this call errors (CLI flag mismatch, missing `--framework`, etc.), surface the error and retry. A completed Phase A with a missing state.json is worse than a visible error — the user discovers the breakage later when they try to add a feature or run diagnostics.
+
+**Exception — "Just exploring" / demo mode (web only):**
 ```bash
 npx @cometchat/skills-cli apply --experience 1 --framework <detected>
 npx @cometchat/skills-cli verify --json
 npx @cometchat/skills-cli install
 ```
 
+For RN demo mode, scaffold the minimal integration directly — there's no `apply` template path for RN.
+
 ### Step 6 — Verify + show result
 
 Run a TypeScript check to verify the code compiles:
@@ -545,27 +645,85 @@ Run a TypeScript check to verify the code compiles:
 npx tsc --noEmit
 ```
 
-**Do NOT run `npx @cometchat/skills-cli verify`** — it checks for
-CLI-generated `.cometchat/state.json` which doesn't exist in v3
-(AI writes code directly, not via `cometchat apply`). Use `tsc` instead.
+**Do NOT run `npx @cometchat/skills-cli verify`** — it checks for CLI-generated `.cometchat/state.json` that's authored by `cometchat apply`, not by AI integration. Use `tsc` instead.
+
+**RN extra: do not start Metro automatically** — let the user do that in their own terminal. Metro blocks the terminal and cannot be meaningfully observed from here.
 
-Surface any issues. Then:
+Surface any common issues:
 
+**Web:**
+- `Module not found: @cometchat/chat-uikit-react` → install didn't complete
+- CSS variable warnings → CSS import not at root or wrong path
+
+**RN:**
+- `Cannot find module '@cometchat/chat-uikit-react-native'` → install didn't complete
+- `JSX element 'GestureHandlerRootView' has no corresponding closing tag` → wrapper chain partially applied
+- `Property 'hideReplyInThreadOption' does not exist on type '...'` → v3 types installed; user needs v5 (`^5.0.0`)
+
+Then:
+
+**Web result message:**
 > "CometChat is integrated! Here's what was set up:
 >
-> - Messages page at /messages ✓
-> - Chat drawer on product page ✓
+> - <list of new + patched files> ✓
 > - Provider + CSS wired ✓
 > - Dependencies installed ✓
 >
-> Run `npm run dev` and try it out. Pre-seeded test users
-> (cometchat-uid-1 through uid-5) are ready to chat.
+> Run `npm run dev` and open the app:
+> - **Vite (reactjs)**: http://localhost:5173
+> - **Next.js**: http://localhost:3000/chat
+> - **React Router v7**: http://localhost:5173/chat
+> - **Astro**: http://localhost:4321/chat"
+
+**RN result message:**
+> "CometChat is integrated! Here's what was set up:
+>
+> - <list of new + patched files> ✓
+> - Provider + four-wrapper chain ✓
+> - `import 'react-native-gesture-handler'` verified at line 1 ✓
+> - Dependencies installed ✓
+> - `hideReplyInThreadOption={true}` on MessageList ✓
+>
+> Next steps:
+>
+> **Expo managed:**
+> 1. `npx expo start --clear`
+> 2. Open the app in Expo Go (if no native modules) or a dev build
+>
+> **Bare RN:**
+> 1. `npm start -- --reset-cache`
+> 2. In another terminal: `npm run ios` or `npm run android`"
+
+**Common ending — empty conversation list explanation (every framework):**
+
+> ---
+>
+> **About the empty conversation list you'll see:**
+>
+> Every CometChat app ships with **5 pre-created test users**:
+> `cometchat-uid-1` through `cometchat-uid-5`. Your integration is
+> logged in as `cometchat-uid-1` by default, and a brand-new app has
+> no messages yet — so the conversation list will be empty when you
+> first load the page. **This is normal, not a bug.**
+>
+> **To see chat actually working** (60 seconds, no code changes):
+> 1. Open `https://app.cometchat.com` → your app → **Users** tab
+> 2. Click `cometchat-uid-2` → **Send Message** button
+> 3. Pick `cometchat-uid-1` as the recipient, type "hello", send
+> 4. Refresh the dev URL (web) or reload the app (RN: shake → Reload, or press `r` in Metro)
+> 5. A conversation will appear — open it to see the message and reply
+>
+> The 5 test users (`cometchat-uid-1` through `uid-5`) can also chat
+> with each other from the dashboard, so you can seed multiple
+> conversations the same way.
 >
 > What would you like to do next?"
 
 ### Step 7 — Iteration menu
 
-Use `AskUserQuestion`:
+Use `AskUserQuestion`. The option set differs by family — RN has two extra options (push notifications + testing) that don't apply to web.
+
+**Web — 8 canonical options:**
 - **question:** "What would you like to do next?"
 - **header:** "Next step"
 - **multiSelect:** false
@@ -579,62 +737,82 @@ Use `AskUserQuestion`:
   7. label: "Run diagnostics", description: "Check for drift, missing env vars, broken imports."
   8. label: "I'm done", description: "Exit."
 
-For **component customization**: read `cometchat-components` + docs MCP,
-then write the customization code directly. This is pure AI work — no
-CLI command. Ask the user what they want to customize, read the relevant
-component's props from the catalog, and propose changes.
+**RN — 10 canonical options:**
+- **question:** "What would you like to do next?"
+- **header:** "Next step"
+- **multiSelect:** false
+- **options:**
+  1. label: "Customize look and feel (themes)", description: "Colors, typography, dark mode — edit CometChatThemeProvider."
+  2. label: "Add a feature", description: "Calls, reactions, polls, extensions, AI agent — browse the catalog."
+  3. label: "Customize a component", description: "Custom bubbles, headers, message composer actions, empty states."
+  4. label: "Add another placement", description: "Add a modal chat, a bottom sheet, or another tab — without touching the existing integration."
+  5. label: "Set up push notifications", description: "APNs + FCM setup, CometChat dashboard config, client registration, tap-to-deep-link. Required for production."
+  6. label: "Set up production auth", description: "Replace the dev Auth Key with a server-minted auth token. Read `cometchat-native-production` skill."
+  7. label: "Set up user management", description: "Server endpoints for creating, updating, deleting CometChat users."
+  8. label: "Set up testing", description: "Jest + React Native Testing Library setup, mocks for the UI Kit / SDK, E2E with Detox or Maestro."
+  9. label: "Troubleshoot an issue", description: "Metro cache, pod install, iOS privacy manifest, push notifications, native module linking."
+  10. label: "I'm done", description: "Exit."
+
+For **theme customization**: read the framework-appropriate theming skill and write the customization code.
+
+For **adding features**: read the framework-appropriate features skill. Features fall into buckets (Default, Dashboard-toggle, Package-install, Component-swap). Ask which feature, then follow the right bucket's recipe.
+
+For **component customization**: read the customization + components skills, then write the customization code directly. Ask the user what they want to customize, read the relevant component's props from the catalog, propose changes.
+
+For **production auth**: read the framework-appropriate production skill. It's interactive — ask the user about their auth system and generate the server-side token endpoint for their backend.
 
-For **production auth**: read the `cometchat-production` skill (already
-in your context). It's interactive — ask the user about their auth
-system and generate the server-side token endpoint for their framework.
+For **push notifications (RN only)**: read `cometchat-native-push`. Structured 12-section walkthrough.
+
+For **testing (RN only)**: read `cometchat-native-testing`. Ask the user whether they want unit tests (Jest + RNTL), E2E (Detox vs Maestro), or both.
+
+For **troubleshooting (RN)**: read `cometchat-native-troubleshooting` and match the symptom to a triage table. (Web: option 7 "Run diagnostics" runs `cometchat doctor` against `.cometchat/state.json`.)
 
 ### Re-rendering the menu after each action
 
-After every Phase B action completes, you **MUST** re-invoke
-`AskUserQuestion` with the **exact same 8 options** listed above
-(same `question`, `header`, `multiSelect: false`, same option labels
-and descriptions — verbatim). This gives the user arrow-key selection
-in their terminal.
+After every Phase B action completes, you **MUST** re-invoke `AskUserQuestion` with the **exact same option set** (web: 8 options, RN: 10) — same `question`, `header`, `multiSelect: false`, same labels and descriptions, verbatim. This gives the user arrow-key selection in their terminal.
 
 **Do NOT:**
-- Present the options as a prose bullet list (`"What would you like to
-  do next?\n  - Customize the theme...\n  - Add calls..."`) — this
-  forces the user to type their answer, which is a worse UX.
-- Invent new options based on what the user just did (e.g. "Customize
-  theme to match Nestly's brand", "Swap the drawer header for a custom
-  view"). The 8 options above are the canonical set and don't change
-  between iterations.
-- Skip the menu and ask a freeform "What's next?" — always route
-  through `AskUserQuestion`.
-- Drop options or add new ones. The user expects the same 8 choices
-  every time, even if some are redundant with what they just did
-  (they may want to do the same kind of action twice, e.g. add two
-  features).
-
-The iteration loop is the whole point of Phase B. Re-rendering the
-canonical menu via `AskUserQuestion` after every action is how the
-user controls the session.
+- Present the options as a prose bullet list — forces typed answers, worse UX.
+- Invent new options based on what the user just did. The canonical set doesn't change between iterations.
+- Skip the menu and ask freeform "What's next?" — always route through `AskUserQuestion`.
+- Drop options or add new ones. The user expects the same choices every time, even if some are redundant with what they just did (they may want to do the same kind of action twice).
+
+The iteration loop is the whole point of Phase B. Re-rendering the canonical menu via `AskUserQuestion` after every action is how the user controls the session.
 
 ## Hard rules
 
+### Always (every framework)
+
 - **Ask, don't assume.** Every integration decision should be confirmed.
-- Always run `detect` first. Do not assume the framework.
+- **Always run `detect` first.** Do not assume the framework.
 - Always use `npx @cometchat/skills-cli` for CLI commands.
 - NEVER replace existing project files unless the user chose demo mode.
 - ALWAYS read existing files before modifying them.
 - ALWAYS show the plan (Step 3f) and get confirmation before writing.
-- For component names and props, use the `cometchat-components` skill
-  or docs MCP — never invent from training data.
-- After writing code, update `.cometchat/config.json` with the choices made.
-- **NEVER use the `Skill()` tool** to load CometChat skills. All 13
-  skills are already in your context as `.claude/skills/` files. Just
-  read and follow them directly.
+- **Every `<CometChatMessageList>` must pass `hideReplyInThreadOption={true}`** unless the user has explicitly opted into thread support and you've built the thread screen too. Without it, tapping a message shows a "Reply in Thread" action that leads to a broken (undefined) thread view.
+- **NEVER build a custom search UI.** The UI Kit ships `<CometChatSearch>` — full dual-scope search across conversations + messages with built-in filter chips, pagination, and result highlighting. Any request involving "search", "find messages", "search conversations" MUST use the built-in component (and `showSearchBar` / `onSearchBarClicked` on `CometChatConversations` for web; `hideSearch={false}` for RN). Do NOT create custom search bars, hand-rolled result lists, or filter UIs.
+- For component names and props, use the framework-appropriate `*-components` skill or docs MCP — never invent from training data.
+- After writing code, record state in `.cometchat/state.json` (Step 5 step 11) so the iteration menu can detect the integration in a future session.
+- **NEVER use the `Skill()` tool** to load CometChat skills. They're already in your context as `.claude/skills/` files. Just read and follow them directly.
+
+### Web only
+
+- **CSS import goes once at the root level** per framework conventions. The framework skill (cometchat-{react,nextjs,react-router,astro}-patterns) tells you exactly where.
+- **For drawer / widget animations, animate `right` / `left`, NEVER `transform` / `translate-*`.** A `transform` on a CometChat-containing element creates a new containing block that re-anchors absolutely-positioned overlays (emoji picker, action sheet, reactions, thread panel) to the transformed element instead of the viewport. Tailwind utilities `translate-x-*`, `-translate-x-*`, `scale-*`, `rotate-*`, `transform-*` are also banned for this reason. See `cometchat-placement` § 10.
+
+### React Native only
+
+- **`import "react-native-gesture-handler"` must be line 1 of the entry file.** Not line 2. Not after another import. This is non-negotiable.
+- **All four wrappers are required, in this order:** `GestureHandlerRootView → SafeAreaProvider → CometChatThemeProvider → CometChatProvider`. Omitting any of them breaks gestures, safe areas, theming, or login state — and it fails silently in dev.
+- **Login API is `CometChatUIKit.login({ uid })` or `CometChatUIKit.login({ authToken })`** — same method, different object key. There is no `loginWithAuthToken`. Passing a bare string like `login("cometchat-uid-1")` silently fails on RN.
 
 ## Error handling
 
-If the CLI's `--json` output includes `human_message` / `suggestion` fields,
-show those to the user. Then show the raw `error` in parentheses for
-debuggability. If `retryable: false`, do NOT offer a retry.
+If the CLI's `--json` output includes `human_message` / `suggestion` fields, show those to the user. Then show the raw `error` in parentheses for debuggability. If `retryable: false`, do NOT offer a retry.
+
+For RN: if a command errors (e.g., `pod install` fails, `npx expo install` fails), surface the raw error output and consult `cometchat-native-troubleshooting` for the relevant triage table before retrying. Don't loop silently.
+
+If the user's project is bare RN with `ios/` and `android/` but no `package.json` scripts for `ios`/`android` (common when React Native was added incrementally to an existing native app), flag that and pause. Writing integration code won't help if the app can't build.
 
 ## Optional: docs MCP
 
@@ -647,6 +825,8 @@ Not required for integration or Phase B CLI flows.
 
 ## Skill routing reference
 
+### Web family
+
 | Skill | When to load |
 |---|---|
 | `cometchat-core` | Always — before any integration code |
@@ -658,5 +838,23 @@ Not required for integration or Phase B CLI flows.
 | `cometchat-astro-patterns` | framework = astro |
 | `cometchat-theming` | When customizing themes |
 | `cometchat-features` | When adding features |
+| `cometchat-customization` | When writing custom formatters, events, request-builder filters |
 | `cometchat-production` | When setting up production auth |
 | `cometchat-troubleshooting` | When diagnosing problems |
+
+### React Native family
+
+| Skill | When to load |
+|---|---|
+| `cometchat-native-core` | Always — before any integration code |
+| `cometchat-native-components` | Always — before writing component code |
+| `cometchat-native-placement` | When integrating — for placement patterns |
+| `cometchat-native-expo-patterns` | framework = expo (managed + Expo Router) |
+| `cometchat-native-bare-patterns` | framework = react-native (bare CLI) |
+| `cometchat-native-theming` | When customizing themes |
+| `cometchat-native-features` | When adding features |
+| `cometchat-native-customization` | When writing custom text formatters, events, request-builder filters, or DataSource decorators |
+| `cometchat-native-production` | When setting up production auth or user management |
+| `cometchat-native-push` | When setting up push notifications |
+| `cometchat-native-testing` | When adding tests |
+| `cometchat-native-troubleshooting` | When diagnosing problems |

package/skills/cometchat-components/SKILL.md

@@ -192,6 +192,15 @@ Full-featured dual-scope search: searches across conversations AND messages with
 
 **Works with:** CometChatConversations (replaces the list when search is active)
 
+> **Hard rule — never roll your own search.** Any request involving
+> "search", "find messages", "search conversations", or "search across
+> conversations" MUST use `<CometChatSearch>` (or `showSearchBar={true}`
+> + `onSearchBarClicked` on `CometChatConversations` to swap into
+> `<CometChatSearch>` on click). Do NOT build custom `<input type="search">`
+> bars, hand-rolled result lists, or filter UIs — they bypass the SDK's
+> pagination, highlighting, and dual-scope (conversations + messages)
+> matching that ship with the built-in component.
+
 ---
 
 ### CometChatThreadHeader

package/skills/cometchat-production/SKILL.md

@@ -539,6 +539,66 @@ A simpler approach: if any CometChat operation returns a 401 or auth error, re-f
 
 **Guard refresh calls with the same concurrency pattern.** If two components both see a 401 at the same time, two `loginWithAuthToken` calls race and the SDK throws *"Please wait until the previous login request ends."* Route token refresh through the same `ensureLoggedIn(uid, authToken)` helper defined in `cometchat-core`'s provider pattern — the module-level `loginInFlight` promise dedupes concurrent refreshes automatically.
 
+Concrete refresh handler — pair the helper from `cometchat-core` with the connection listener and a token-refetch path:
+
+```typescript
+import { CometChat } from "@cometchat/chat-sdk-javascript";
+import { CometChatUIKit } from "@cometchat/chat-uikit-react";
+
+// Module-level — shared across every refresh attempt.
+// Identical shape to the one in cometchat-core § 2.
+let refreshInFlight: Promise<unknown> | null = null;
+
+async function refreshSession(uid: string): Promise<void> {
+  if (refreshInFlight) {
+    // Another component already triggered a refresh — wait for it,
+    // don't fire a second loginWithAuthToken.
+    await refreshInFlight;
+    return;
+  }
+
+  refreshInFlight = (async () => {
+    // 1. Fetch a fresh token from your server endpoint.
+    //    Your existing useCometChatToken hook (Step 1) calls /api/cometchat-token.
+    //    Extract that fetch into a helper so the refresh path can reuse it.
+    const res = await fetch("/api/cometchat-token", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ uid }),
+    });
+    if (!res.ok) throw new Error(`Token refresh failed: ${res.status}`);
+    const { token } = (await res.json()) as { token: string };
+
+    // 2. Re-authenticate with the new token. SDK swaps the in-memory
+    //    session — no full reload needed.
+    await CometChatUIKit.loginWithAuthToken(token);
+  })();
+
+  try {
+    await refreshInFlight;
+  } finally {
+    refreshInFlight = null;
+  }
+}
+
+// Wire it into the connection listener so a disconnect triggers refresh.
+CometChat.addConnectionListener(
+  "auth-refresh-listener",
+  new CometChat.ConnectionListener({
+    onDisconnected: () => {
+      const uid = CometChatUIKit.getLoggedInUser()?.getUid();
+      if (uid) {
+        refreshSession(uid).catch((e) => {
+          console.error("CometChat refresh failed; user may need to re-login", e);
+        });
+      }
+    },
+  }),
+);
+```
+
+`refreshInFlight` mirrors `loginInFlight` from `cometchat-core` § 2 — same dedup pattern, separate promise so the initial-login and refresh paths don't accidentally serialize against each other. If the same component renders in StrictMode AND a 401 arrives during the second mount, the listener and the provider effect can both touch the SDK without colliding.
+
 ---
 
 ## 5. User management patterns