@cometchat/skills 4.0.0 → 4.2.0

package/skills/cometchat/SKILL.md

@@ -2,7 +2,7 @@
 name: cometchat
 description: Entry-point for CometChat integration in any React, React Native, Angular, Android, Flutter, or iOS project — web (React/Next.js/React Router/Astro), React Native (Expo/bare), Angular (12-15), native Android (V5 stable, V6 beta), Flutter (V5 stable, V6 beta), and native iOS (V5 stable). Detects the framework, gathers requirements through an interactive conversation, and writes production-quality integration code.
 license: "MIT"
-allowed-tools: "executeBash, readFile, fileSearch, listDirectory, AskUserQuestion"
+allowed-tools: "shell, file-read, file-search, file-list, ask-user"
 metadata:
   author: "CometChat"
   version: "3.0.0"
@@ -13,7 +13,7 @@ metadata:
 
 The user wants to add CometChat to any kind of project. Trigger phrases:
 
-- `/cometchat`
+- `/cometchat` (or invoke the cometchat skill via your agent's mechanism — keyword "cometchat" or "integrate chat" works in most agents)
 - "add cometchat", "integrate cometchat", "add chat to my app"
 - "add messaging", "add chat ui", "add in-app chat"
 
@@ -41,7 +41,7 @@ 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.
 
-Pattern skills (loaded from your context, not via `Skill()`):
+Pattern skills (loaded from your context as plain files — not via your agent's skill-loading mechanism):
 - `cometchat-core` (web) / `cometchat-native-core` (RN) / `cometchat-angular-core` (Angular) / `cometchat-android-{v5,v6}-core` (Android) / `cometchat-flutter-{v5,v6}-core` (Flutter) — init, login, provider chain, env vars, anti-patterns
 - `cometchat-components` (web) / `cometchat-native-components` (RN) / `cometchat-angular-components` (Angular) / `cometchat-android-v5-components` or `cometchat-android-v6-{compose,kotlin}-components` (Android) / `cometchat-flutter-v6-components` (V6 only — V5 splits into `-conversations`/`-messages`/`-users-groups`) — component catalog, props, composition
 - `cometchat-placement` (web) / `cometchat-native-placement` (RN) / `cometchat-angular-placement` (Angular) / `cometchat-android-v5-placement` or `cometchat-android-v6-{compose,kotlin}-placement` (Android) / `cometchat-flutter-v6-placement` (V6 only) — WHERE to put chat
@@ -74,14 +74,14 @@ The JSON output includes `framework` (one of `reactjs`, `nextjs`, `react-router`
 
 **Android — `android_version` is load-bearing.** When `framework === "android"`, the detect output includes `android_version: "v5" | "v6" | null`. The cohort selects which V5 or V6 pattern set to load — V5 (live, `chat-uikit-android:5.x`, Java + Kotlin Views) and V6 (beta, `chatuikit-{compose,kotlin}-android:6.x`) are different SDKs with different APIs. Treat them as separate routing targets even though both live under `--family android`.
 
-If `android_version` is `null`, the project is greenfield (no cometchat dep yet). Ask the user via `AskUserQuestion`:
+If `android_version` is `null`, the project is greenfield (no cometchat dep yet). Ask the user:
 > "Which CometChat Android UI Kit do you want to use? V5 is the live SDK (recommended for production today). V6 is beta (Compose + Kotlin Views split, future-facing)."
 
 Save the choice into `.cometchat/config.json` under `android_version` so subsequent `/cometchat` runs don't re-ask.
 
 **Flutter — `flutter_version` is load-bearing too.** When `framework === "flutter"`, the detect output includes `flutter_version: "v5" | "v6" | null`. V5 is GetX-based (`cometchat_chat_uikit:^5.2`); V6 is Bloc-based (`cometchat_chat_uikit:^6.0.0-beta2`). The two cohorts have different state-management primitives, different barrel exports, and different theme APIs — never mix them. Same `--family flutter` install ships both sets; routing picks the right one.
 
-If `flutter_version` is `null`, ask via `AskUserQuestion`:
+If `flutter_version` is `null`, ask the user:
 > "Which CometChat Flutter UI Kit do you want to use? V5 is the live SDK (GetX-based, recommended for production today). V6 is beta (Bloc-based, future-facing)."
 
 Save the choice into `.cometchat/config.json` under `flutter_version`.
@@ -141,6 +141,55 @@ Save the choice into `.cometchat/config.json` under `flutter_version`.
 
 Store this mental map — you'll use it throughout the conversation.
 
+#### Then show the user what you found — Step 1.5 (the "I see you" moment)
+
+This is the most important moment of the whole flow. After running detection + reading the project, narrate what you found in **3–5 specific, observation-grounded bullets** BEFORE asking any question. The user should feel that you understand their project before deciding whether to trust you with it.
+
+The shape (use it verbatim — the structure earns trust):
+
+> Taking a look at your project...
+>
+> - **{Framework} + {Build tool} {version}** {with TypeScript / JavaScript / etc., as detected}
+> - **{Router or nav state}** — {one observation about how routing is set up, or "no router yet" for greenfield}
+> - **{Auth system status}** — {"NextAuth detected → I'll wire token-based login", or "no auth detected → I'll start with dev mode + a test user; you can upgrade later"}
+> - **{Existing CometChat state}** — {"existing `cometchat/` folder with X — I'll patch around it", or "fresh start — no prior CometChat code"}
+> - **{One personal observation}** — {something specific you noticed: "Tailwind classes throughout", "shadcn/ui components", "monorepo with apps/* and packages/*"}
+>
+> Ready to set this up? I'll walk you through account setup, then ask where chat should live.
+
+**The rules for this moment:**
+
+1. **Be specific, not generic.** "Vite + React 19 + TypeScript" beats "a React project." Read the actual versions from `package.json`.
+2. **Five bullets max.** Beyond five, it stops feeling observational and starts feeling like a recital. Cut to what's *interesting* about the project.
+3. **Lead with what's load-bearing.** Framework + version, router, auth, existing CometChat, then one personal touch. The personal touch is what makes it land — show you actually looked.
+4. **Skip the bullet if there's nothing to say.** No router on greenfield → say "no router yet"; don't invent one. No auth → say "no auth detected"; don't list every package you didn't find.
+5. **End with a single confident question.** Not five questions. The flow continues into Step 2 (credentials) or Step 3 (placement) — let the next step ask.
+
+**Examples of good vs bad bullets:**
+
+| ✓ Good (specific, observational) | ✗ Bad (generic, unfounded) |
+|---|---|
+| "Vite + React 19 + TypeScript, Tailwind for styling" | "A React project with TypeScript" |
+| "React Router v7 detected (`routes.ts` + `react-router.config.ts`)" | "Some routing is configured" |
+| "NextAuth in `auth.config.ts` — I'll mint CometChat tokens server-side via your existing session cookie" | "Authentication is set up" |
+| "shadcn/ui detected (`components/ui/*`) — I'll use your existing Button + Dialog primitives in the chat trigger" | "Some UI components are present" |
+| "Monorepo: `apps/web` is your dashboard, `apps/marketing` is the public site — I'll integrate into apps/web" | "This is a monorepo" |
+
+**For greenfield projects (the test case):**
+
+> Taking a look at your project...
+>
+> - **Vite + React 19 + TypeScript** — fresh `cometchat-test-app` scaffold
+> - **No router yet** — for the demo, chat will mount in `src/App.tsx` directly; we can move it to a route later
+> - **No auth system detected** — I'll set you up in dev mode with a pre-seeded test user (`cometchat-uid-1`); production auth is a one-flag upgrade later
+> - **Fresh start** — no existing CometChat code to patch around
+>
+> Ready to set this up? I'll get you a CometChat account first, then ask where chat should live.
+
+This moment costs ~5 seconds of conversation but anchors the rest. Skip it and the user feels like they're talking to a script. Run it well and the rest of the flow feels effortless.
+
+---
+
 **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
@@ -160,15 +209,17 @@ To check whether the pattern skills are loaded, attempt to read `cometchat-core/
 **If `framework` is `expo` or `react-native` AND `cometchat-native-core` is NOT loaded:**
 
 ```bash
-npx @cometchat/skills-native add
+npx @cometchat/skills add --family native
 ```
 
 **If `framework` is `reactjs`, `nextjs`, `react-router`, or `astro` AND `cometchat-core` is NOT loaded:**
 
 ```bash
-npx @cometchat/skills add
+npx @cometchat/skills add --family web
 ```
 
+> **Important — `--family <name>` is non-negotiable.** Without the family flag, `npx @cometchat/skills add` (default) installs only the cross-family base skills (cometchat dispatcher + i18n + a11y + calls dispatcher). It does NOT install `cometchat-core`, `cometchat-react-patterns`, `cometchat-placement`, etc. — the framework-specific skills with the actual integration patterns. Running base-only twice doesn't load the missing skills; only `--family <name>` does. Skipping the flag here causes the agent to write integration code from training memory instead of from the framework-specific skills, which produces real bugs (e.g. the `minHeight: 0` flex-shrink trap in `cometchat-react-patterns` rule 6a — only in that skill).
+
 **If `framework` is `angular` AND `cometchat-angular-core` is NOT loaded:**
 
 ```bash
@@ -203,7 +254,7 @@ After the install completes, tell the user:
 
 > "I just installed the {family} pattern skills into your workspace. Please re-run `/cometchat` to continue — your config is saved in `.cometchat/config.json` and credentials in `.env`, so the next run picks up at code generation without re-asking the questions you've already answered."
 
-**Why re-run rather than continue in this session:** Claude Code (and most coding agents) snapshot the skill set at session start and do NOT hot-reload SKILL.md mid-session. Even though the install writes the new skill files into `.claude/skills/`, your in-context skill set is the snapshot. Continuing would mean writing code from training memory — which the skills explicitly forbid (this is the same failure mode that produced the `UIKitSettingsBuilder` and `getLoggedinUser` casing bugs at v2.2.0). The re-run is the only safe path.
+**Why re-run rather than continue in this session:** Claude Code, Cursor, Cline, Kiro, and other modern AI coding agents snapshot the skill set at session start and do NOT hot-reload SKILL.md mid-session. Even though the install writes the new skill files into `.claude/skills/` (or `.cursor/skills/` / `.kiro/skills/` / `.agents/skills/` — your agent's skills dir), your in-context skill set is the snapshot. Continuing would mean writing code from training memory — which the skills explicitly forbid (this is the same failure mode that produced the `UIKitSettingsBuilder` and `getLoggedinUser` casing bugs at v2.2.0). The re-run is the only safe path.
 
 **Non-default IDE — pass `--ide`.** The default installer target is `claude` (`.claude/skills/`). If the dispatcher's own SKILL.md was loaded from a different location, pass the matching flag:
 
@@ -225,6 +276,21 @@ 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.**
 
+#### Hard rule — signup flows MUST ask, not infer
+
+**For Sign-Up paths specifically (Step 2b → 2b.5 → 2b.6 → 2c), the following structured prompts are NON-NEGOTIABLE and MUST be rendered via `AskUserQuestion`:**
+
+| Prompt | When | Skipped only if |
+|---|---|---|
+| **Role** (Step 2b.6) | After `auth me` if `meta.role === null` | `auth me` returned a non-null role |
+| **Intent** (Step 2b.6) | After `auth me` if `meta.intent === null` | `auth me` returned a non-null intent |
+| **App name** (Step 2c) | Before `provision setup` | NEVER — even if a suggested default exists, user must explicitly confirm |
+| **Region** (Step 2c) | Before `provision setup` | `last_app.region` exists AND user accepted the "use same region?" confirmation |
+| **Industry** (Step 2c) | Before `provision setup` | `last_app.industry` exists AND user accepted the "same industry?" confirmation |
+| **Product** (Step 3.0 Tier 3) | After Step 2c if Tier 1 (`auth me last_app.product`) AND Tier 2 (natural-language inference from slash-command + prior turn) both returned null | Tier 1 OR Tier 2 resolved a non-null value |
+
+**Auto-mode classifiers do NOT authorize bypassing these prompts.** "Allowed by auto mode classifier" applies to Bash/tool approvals — it does NOT apply to structured user prompts. The agent must surface each prompt regardless of approval mode. Rationalizations like "fresh test scaffold = just exploring, skip the prompt" or "moving forward without stops for the demo" are **explicit spec violations** — the dashboard's `/select-product` + `/create-app` + `/choose-role` + `/choose-intent` flows ask these in the browser; the CLI flow MUST ask them in the terminal for parity. Skipping them silently picks defaults that affect downstream Step 3a (intent → archetype) and Step 3b.1 (industry → recommendation upsells) — the user can't correct values they never saw asked.
+
 If config has `appId` set, verify credentials are in `.env` and skip to Step 3.
 
 Otherwise check:
@@ -236,7 +302,7 @@ If `status` is `"logged-in"`, skip to **Step 2b.5** (fetch dashboard profile).
 
 If `status` is `"logged-out"`, ask:
 
-Use `AskUserQuestion`:
+Ask the user (preserve this exact shape — `question`, `header`, `multiSelect`, `options[].label`, `options[].description` — agents have varying primitive names but they all support this structured form):
 - **question:** "Let's set up CometChat. Do you have an account?"
 - **header:** "Account"
 - **multiSelect:** false
@@ -311,7 +377,7 @@ Response shape:
     "region": "us",
     "industry": "online_marketplaces",
     "technology": "react",
-    "product": "support"
+    "product": "chat-messaging"
   }
 }
 ```
@@ -321,11 +387,27 @@ Field meanings (from the dashboard's signup screens — see `/Users/swapnil/Down
 - `role`: `"frontend"` / `"backend"` / `"fullstack_engineer"` / `"startup_founder"` / `"product_leader/manager"` / `"engineering_leader/manager"` / `"others"` (when `others`, `other_role` carries the freeform value)
 - `intent`: `"building"` / `"evaluating"` / `"exploring"` (this is the **dashboard's** intent — distinct from Step 3a's `placement_intent` which asks about app archetype)
 - `last_app`: most-recently-created app on the user's account (or `null` if they have none). The dashboard's `/create-app` and `/select-product` screens write `industry`, `technology`, `product` into the app's `metadata` — we surface them here so Step 2c can pre-fill region/industry instead of asking again.
+- `last_app.product`: the surface the user picked on the dashboard's `/select-product` screen — `"chat-messaging"` / `"voice-video"` / `"ai-agent"` / `"byo-agent"` / `null`. **Load-bearing for Step 3.0** — it decides which dispatcher (chat or calls) handles the integration. `chat-messaging` runs the existing chat flow; `voice-video` hands off to `cometchat-calls`; `ai-agent` and `byo-agent` are out of scope for `/cometchat` today and point at the AI Agents docs.
+
+  > **Dashboard ↔ canonical mapping** (load-bearing — wired in `cometchat-api.ts:listApps`):
+  >
+  > | Dashboard `metadata.features` | Canonical `last_app.product` |
+  > |---|---|
+  > | `chat` | `chat-messaging` |
+  > | `calling` | `voice-video` |
+  > | `aiAgent` | `ai-agent` |
+  > | `byo-agent` | `byo-agent` |
+  >
+  > The dashboard's `/select-product` is **single-select** and writes `metadata.features = "<dashboard-key>"`; the CLI maps it to canonical at the API boundary so downstream code only sees canonical values. If dashboard sends an unknown key (e.g. `moderation`), `product` is left `undefined` and Step 3.0 infers from natural language or asks at routing time.
+  >
+  > The combined value `chat-messaging+voice-video` is **CLI-only** — surfaced in Step 3.0's prompt as "Both Chat and Calling" when inference can't tell. The dashboard picker doesn't expose "Both" today.
 
 **Store the response in working memory.** Reference these fields downstream:
 
 - **Step 2c (new app):** if `last_app` is non-null, default `--region` and `--industry` to the values from `last_app` and only ask the user to confirm — do NOT re-prompt from scratch.
+- **Step 3.0 (product branch):** route by `last_app.product`. `chat-messaging` continues into Step 3a; `voice-video` short-circuits to the `cometchat-calls` dispatcher; `ai-agent` and `byo-agent` exit with a docs pointer.
 - **Step 3a:** if `meta.intent === "exploring"`, skip the placement-intent question and route straight to the "Just exploring" branch (one route/screen with `<CometChatConversations />` and `cometchat-uid-1` pre-logged-in).
+- **Step 3b.1 (industry tailoring):** use `last_app.industry` to layer industry-specific upsells onto the placement recommendation — moderation features for dating apps, HIPAA-aware production patterns for healthcare, link-preview for marketplaces, etc. Augment, don't replace.
 - **Step 5 explanations:** if `meta.role === "frontend"`, lead with concrete component composition + CSS examples; if `meta.role === "engineering_leader/manager"`, lead with placement architecture trade-offs (where state lives, what gets cached, how routing fits the project's pattern).
 - **Greeting:** if `meta.name` is non-null, greet by name in any user-facing message during the rest of the flow ("Got it, Swapnil — let's pick an app").
 
@@ -337,6 +419,7 @@ Field meanings (from the dashboard's signup screens — see `/Users/swapnil/Down
 - `name` is `null` → no greeting (don't ask, the dashboard will collect it on next browser visit).
 - `role` is `null` → **ask in Step 2b.6** (this is the case for accounts that signed up via `auth signup` from the CLI — they never saw the dashboard's `/choose-role` screen).
 - `intent` is `null` → **ask in Step 2b.6**.
+- `last_app.product` is `null` (or `last_app` itself is `null`) → **resolved in Step 3.0** via natural-language inference, falling back to a prompt only if ambiguous. Do NOT ask product upfront in Step 2b.6 — the dashboard's `/select-product` is a structured form because a UI can't read intent; the agent flow can.
 - `last_app` is `null` → ask region/industry normally in Step 2c.
 
 After this step, proceed to **Step 2b.6**.
@@ -348,11 +431,13 @@ The dashboard's `/choose-role` and `/choose-intent` screens collect two profile
 - `role` shapes the depth and angle of code explanations in Step 5
 - `intent` decides whether Step 3a's placement question is needed (`exploring` short-circuits to a single screen)
 
+(`product` is resolved separately in **Step 3.0** via natural-language inference + lazy ask — not here.)
+
 If `auth me` returned non-null values for both, **skip this step entirely** and go to Step 2c — the dashboard already collected them, do not re-ask.
 
-If either is `null` (typical for accounts created via `cometchat auth signup` rather than the dashboard browser flow), ask the user. The options below mirror the dashboard exactly so that anyone who later visits the dashboard sees consistent terminology.
+If either is `null` (typical for accounts created via `cometchat auth signup` rather than the dashboard browser flow), ask the user. The options below mirror the dashboard exactly so anyone who later visits the dashboard sees consistent terminology.
 
-**If `role === null`** — `AskUserQuestion`:
+**If `role === null`** — ask the user (preserve the structured shape — `question`/`header`/`multiSelect`/`options[].label`/`options[].description` — agents have varying primitive names but all support this form):
 - **question:** "What's your role? (We'll tailor explanations to match.)"
 - **header:** "Role"
 - **multiSelect:** false
@@ -368,9 +453,9 @@ If either is `null` (typical for accounts created via `cometchat auth signup` ra
   | Engineering Manager | `engineering_leader/manager` |
   | Other | `others` |
 
-  If the user picks **Other**, follow up with a free-form `AskUserQuestion` for `other_role` (single short text field; store the freeform value in `other_role`).
+  If the user picks **Other**, follow up with a free-form question for `other_role` (single short text field; store the freeform value in `other_role`).
 
-**If `intent === null`** — `AskUserQuestion`:
+**If `intent === null`** — ask the user (preserve the structured shape):
 - **question:** "What brings you to CometChat?"
 - **header:** "Intent"
 - **multiSelect:** false
@@ -382,7 +467,13 @@ If either is `null` (typical for accounts created via `cometchat auth signup` ra
   | I'm evaluating | Comparing options for my team. | `evaluating` |
   | I'm exploring | Just looking around for now. | `exploring` |
 
-**Store the answers in working memory under the same keys** (`role`, `other_role`, `intent`) as if they had come from `auth me`. Downstream steps (3a + 5) treat dashboard-supplied and CLI-collected values identically.
+**Do NOT ask for `product` in this step.** The dashboard's `/select-product` is a structured form because a UI can't read intent; the CLI/agent flow is conversational and the user has often already said what they want. Asking upfront ("Chat & Messaging? Voice & Video? Both?") is friction the dashboard has but the agent doesn't need.
+
+The product decision happens in **Step 3.0** (Branch by product), where it actually matters for routing. Step 3.0 first tries to infer from the user's slash-command args and prior turn, and only falls back to a prompt if it can't tell. By then the agent has more context (the framework is detected, credentials are set up, the user has shared more about their goal), so inference works better than upfront.
+
+This step (Step 2b.6) is for `role` + `intent` only — those are profile fields the dashboard collected upfront, so we collect them here too if they're missing.
+
+**Store the answers in working memory under the same keys** (`role`, `other_role`, `intent`, `product`) as if they had come from `auth me`. Downstream steps (3.0 + 3a + 5) treat dashboard-supplied and CLI-collected values identically.
 
 > **Note:** These answers are not yet persisted back to the dashboard `/me` endpoint — they only live for the current session. A follow-up will add a `cometchat auth me --update` mode that PATCHes them server-side so the next session won't re-ask. Until then, the user may be asked again in a fresh session.
 
@@ -410,9 +501,14 @@ npx @cometchat/skills-cli provision setup \
 
 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 — **if Step 2b.5 returned `last_app.region`**, default to that value and ask only `"Use the same region as your <last_app.name> app (<region>)? [Y/n]"`. Otherwise `AskUserQuestion`:
+**If no apps exist** (or user wants new), collect via **structured `AskUserQuestion` prompts — NON-NEGOTIABLE.** Do NOT silently default app name / region / industry on signup flows. The agent must surface each prompt and let the user pick. Auto-mode does NOT authorize bypassing these — they're load-bearing for the rest of the integration (`industry` drives Step 3b.1 recommendations downstream).
+
+1. **App name** — SUGGEST `<project-name>-chat` from package.json `name`, then **ask the user to confirm or override** (preserve the structured shape):
+   - **question:** "What should we name your CometChat app?"
+   - **header:** "App name"
+   - Pre-filled default: `<project-name>-chat`. User must explicitly accept or change before the CLI runs `provision setup`.
+
+2. **Region** — **if Step 2b.5 returned `last_app.region`**, default to that value and ask only `"Use the same region as your <last_app.name> app (<region>)? [Y/n]"`. Otherwise **MUST ask** via structured prompt:
    - **question:** "Which region for your CometChat app?"
    - **header:** "Region"
    - **options:** US (recommended), EU, India
@@ -423,8 +519,11 @@ This creates/updates the env file with the correct prefix AND writes `.cometchat
    | US | `us` |
    | EU | `eu` |
    | India | `in` |
-3. Industry — **if Step 2b.5 returned `last_app.industry`**, default to that value and ask only `"Same industry as your previous app (<industry>)? [Y/n]"`. Otherwise `AskUserQuestion`:
-   - **options:** SaaS / Business, Marketplace, Social / Community, Other (or finer-grained from the table below)
+
+3. **Industry** — **if Step 2b.5 returned `last_app.industry`**, default to that value and ask only `"Same industry as your previous app (<industry>)? [Y/n]"`. Otherwise **MUST ask** via structured prompt:
+   - **question:** "What industry is your app in? (Drives industry-specific recommendations downstream.)"
+   - **header:** "Industry"
+   - **options** — full 11-option set (see table below); do NOT pick a default like `saas_businesses` without asking
 
 **Industry key mapping:**
 
@@ -592,13 +691,58 @@ After writing credentials, don't echo the Auth Key back in the transcript. Confi
 
 This is the core of v3. A multi-step conversation that gathers everything you need before writing a single line of code.
 
+#### 3.0. Branch by product (chat vs calls)
+
+`product` decides which dispatcher (chat or calls) handles the rest of Step 3. Resolve it in this priority order:
+
+**1. Use `last_app.product` if non-null** — set by the dashboard's `/select-product` screen. Trust it.
+
+**2. Otherwise, infer from the user's slash-command args + prior turn.** Most users name what they want; don't make them re-pick from a list:
+
+| User said something like… | Set `product` to |
+|---|---|
+| "add chat", "integrate messaging", "build chat", "I want messaging" | `chat-messaging` |
+| "add calling", "integrate voice/video", "add video calls", "set up voip" | `voice-video` |
+| "add both chat and calls", "chat with calling on top", "messaging and calls" | `chat-messaging+voice-video` |
+
+Confirm inferred values briefly so the user can redirect if you guessed wrong:
+> "Got it — setting up Chat & Messaging. (If you wanted calling instead, say so and I'll switch.)"
+
+**3. Only if you can't tell** (plain `/cometchat` with no further context, ambiguous wording like "set up CometChat") — **MUST ask via `AskUserQuestion`. NON-NEGOTIABLE.** Do NOT silently default to chat-messaging or rationalize a shortcut (e.g. "fresh test scaffold → just exploring") to skip this prompt. Auto-mode does NOT authorize bypassing. The product decision drives Step 3a (chat) vs `cometchat-calls` dispatcher handoff — getting it wrong forces a re-run.
+
+- **question:** "Which surface do you want to add to your app?"
+- **header:** "Product"
+- **multiSelect:** false
+- **options:**
+
+  | Label | Description shown under the label | `product` value |
+  |---|---|---|
+  | Chat & Messaging | Real-time user to user & group chats. | `chat-messaging` |
+  | Voice & Video Calling | In-app calling & conferencing. | `voice-video` |
+  | Both Chat and Calling | I want chat with calling on top — chat is the main surface, calls ride alongside. | `chat-messaging+voice-video` |
+
+  > AI Agent / BYO Agent intentionally hidden — `/cometchat` doesn't yet ship integration paths for those products. Step 3.0's routing table below still gracefully handles `ai-agent` / `byo-agent` values that arrive from `auth me` (real dashboard signups), pointing the user at the AI Agents docs.
+
+Once `product` is resolved, route — the rest of Step 3 is chat-shaped, and a calls-only integration shouldn't sit through it.
+
+| `product` value | Branch | What runs |
+|---|---|---|
+| `chat-messaging` | Continue to 3a | Existing chat flow — placement intent, recommendation, framework skills, scaffold chat surfaces. |
+| `voice-video` | **Hand off to `cometchat-calls`** | Stop here. Invoke the `cometchat-calls` dispatcher with the framework + family + credentials already established. Calls dispatcher routes to the per-family `cometchat-{family}-calls` skill in **standalone** mode — no chat UI Kit, full calls surface, VoIP push wired by default, `IncomingCall` mounted at app root. |
+| `chat-messaging+voice-video` | Run 3a–6 (chat), THEN hand off to `cometchat-calls` in additive mode | Full chat flow first. After Step 6 verifies the chat integration, invoke `cometchat-calls` in **additive** mode — patches the existing provider to mount `IncomingCall` at root, adds call buttons inline on chat surfaces, opt-in VoIP push. Skip `apply-feature calls` — `cometchat-calls` covers it end-to-end. |
+| `ai-agent` / `byo-agent` | Exit with docs pointer | Tell the user: *"`/cometchat` integrates chat and calling surfaces. AI Agents have their own integration path — see https://www.cometchat.com/docs/ai-agents."* Exit cleanly; do not attempt to scaffold. |
+
+**If config has `placement_intent` set from a previous run**, confirm it and skip to Step 3b. The product branch above still runs first — a chat-mode integration that's now adding calls re-enters via the `chat-messaging+voice-video` row, not the chat-only row.
+
+**Why this branch comes before 3a:** Step 3a's options are all chat archetypes (Messaging app, Marketplace, SaaS, …). For a `voice-video` product, that taxonomy doesn't apply — the user isn't picking *where chat lives*, they're picking *where the call trigger lives* (profile button vs `/calls` route vs always-on lock-screen-ringer). The `cometchat-calls` dispatcher owns its own placement question with the right options for the calls surface.
+
 #### 3a. "What are you building?"
 
 If config has `intent` set, confirm it and move on.
 
 **If `meta.intent === "exploring"` from Step 2b.5** (the user already told the dashboard during signup that they're just exploring), skip the rest of Step 3 entirely and route to the "Just exploring" branch — scaffold the minimal integration in Step 5 (one route/screen showing `<CometChatConversations />` with `cometchat-uid-1` pre-logged-in). Do not ask the placement-intent question; the user has already said "show me the simplest thing."
 
-Otherwise, use `AskUserQuestion`:
+Otherwise, ask the user (preserve this exact shape — `question`, `header`, `multiSelect`, `options[].label`, `options[].description` — agents have varying primitive names but all support this structured form):
 - **question:** "What kind of app are you building?"
 - **header:** "Your app"
 - **multiSelect:** false
@@ -614,29 +758,70 @@ Otherwise, use `AskUserQuestion`:
 
 #### 3b. Show what you recommend and why
 
-The recommendation table differs by family because the placement vocabulary is different (web has routes/drawers/widgets; RN has screens/tabs/sheets):
+This is the second wow moment after the detection summary. Don't just list a placement — **tell the user why**. Two sentences of reasoning earn confidence; a table alone reads like a lookup.
+
+The recommendation has two layers:
+
+1. **The placement** — what you'll set up (route / drawer / modal / tab / widget)
+2. **The reason** — why this fits the user's archetype (one or two sentences grounded in how their kind of app actually works)
+
+When you write your response, lead with the reason, then the concrete placement, then offer to override:
+
+> **For a marketplace app, I'd put a "Chat with seller" drawer on your product page + an inbox at `/messages`.**
+>
+> The drawer keeps buyers in the buying flow — they can ask a question without losing the listing. The inbox is for going back to past conversations. Two surfaces, one integration.
+>
+> Sound right, or want to try a different shape?
+
+That's the shape. The recommendation tables below are the *what*; the reasoning column is the *why* you should narrate.
 
 **Web family (reactjs, nextjs, react-router, astro):**
 
-| Intent | What you'll set up |
-|---|---|
-| **Messaging app** | A dedicated messages page at a route you choose. Two-pane: conversation list + active chat. |
-| **Marketplace** | A "Chat with seller" drawer on your product page + an inbox page at /messages. |
-| **SaaS / dashboard** | A chat modal triggered from your navbar + a full messages page. |
-| **Social / community** | A full messenger page with tabs: Chats, Calls, Users, Groups. |
-| **Support** | A floating widget bubble in the bottom-right corner. |
+| Intent | Placement | Why |
+|---|---|---|
+| **Messaging app** | Dedicated messages page (route you pick), two-pane: conversation list + active chat | Chat IS the product. Users land directly on it; the route is the home of your app. |
+| **Marketplace** | "Chat with seller" drawer on the product page + inbox at `/messages` | Drawer keeps buyers in the buying flow; the inbox handles "go back to a past conversation." |
+| **SaaS / dashboard** | Modal triggered from your navbar + full messages page | Modal feels lightweight (chat without leaving your work); the page is for serious conversations. |
+| **Social / community** | Full messenger page with tabs: Chats, Calls, Users, Groups | Discovery matters as much as messaging — users want to find people, not just their existing threads. |
+| **Support** | Floating widget bubble in the bottom-right | One-way customer-to-team — minimal cognitive load on the customer; your team triages from the dashboard. |
 
 **React Native family (expo, react-native):**
 
-| Intent | What you'll set up |
+| Intent | Placement | Why |
+|---|---|---|
+| **Messaging app** | Dedicated "Messages" bottom tab → conversations → thread | Mobile users expect chat as a first-class destination; a tab puts it one tap away. |
+| **Marketplace** | "Chat with seller" button on the product screen → modal thread + Inbox stack screen | Modal preserves the buying context; the Inbox is the "back to a conversation" entry point. |
+| **SaaS / productivity** | "Chat" stack screen accessible from nav, optionally bottom sheet for quick replies | Stack screen for focused conversations; bottom sheet for fast back-and-forth without leaving your current work. |
+| **Social / community** | "Messages" bottom tab + "Message" button on profile screens → modal thread | Tab handles discovery; per-profile button is the "I want to talk to THIS person" path. |
+| **Support** | Modal triggered from a "Help" or "Support" button in header/settings | Lightweight, doesn't compete with your product's primary tabs. |
+
+When explaining, reference the ASCII diagrams from `cometchat-placement` (web) or `cometchat-native-placement` (RN) so the user can visualize the shape.
+
+**One sentence to hand them control:** end the recommendation with "Sound right, or want to try a different shape?" — never "Which would you like?" The first phrasing implies you've thought it through and they can override; the second implies you're just collecting answers.
+
+#### 3b.1 — Tailor the recommendation by `last_app.industry`
+
+If `auth me` returned `last_app.industry`, layer the industry-specific upsell onto the placement archetype recommendation. Do NOT replace it — augment it. Industry is a hint, not a rule.
+
+| Industry value | What to add to the recommendation |
 |---|---|
-| **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. |
+| `healthcare` | Mention HIPAA-aware patterns: server-minted auth tokens (NEVER Auth Key), data-masking extension, audit-log retention, recording consent. Point at `cometchat-{family}-production` and `cometchat-features` for the moderation suite. |
+| `dating` | Suggest enabling Profanity Filter + Image Moderation + Sentiment Analysis upfront — dating apps almost always want them. Suggest a "Report user" button next to the message header. |
+| `online_marketplaces` | Confirm the drawer-on-product-page placement (default for marketplace archetype). Suggest enabling Link Preview (buyers share product URLs) and Quick Replies for sellers. |
+| `community_and_social` | Suggest enabling Reactions + Mentions + Threaded Conversations (these are default-on but worth surfacing as design-system colors). Recommend the tab-based "full messenger" placement. |
+| `online_education` | Suggest a `/messages` route + a "Help" button in the navbar (instructor support). Mention Recording for class sessions if calls product is also enabled. |
+| `events_and_streaming` | Suggest the floating widget for live audience chat. If calls product is enabled, recommend group calls + screen-share for hosts. |
+| `sports_and_gaming` | Suggest tab-based messenger + Reactions + GIPHY/Stipop sticker integration (gamer apps lean heavily on stickers). |
+| `team_comms_and_workflows` | Match Slack-like patterns: dedicated `/messages` route, threaded conversations on, mentions on. Skip the floating widget. |
+| `on_demand_services` | Marketplace drawer pattern. Mention auto-translate for cross-language driver/rider chat. |
+| `saas_businesses` | Modal-from-navbar default (matches the SaaS archetype). Suggest server-minted auth tokens + user-mgmt API for tenant scoping. |
+| `other` / `null` | No industry-specific upsell — recommendation stays at the archetype level only. |
 
-When explaining, reference the ASCII diagrams from `cometchat-placement` (web) or `cometchat-native-placement` (RN) so the user can visualize.
+Phrase the upsell as a *follow-up* after the base recommendation, not a replacement:
+
+> "For the marketplace archetype, I'll set up the chat-with-seller drawer + /messages inbox. Since this is a marketplace app (per your dashboard), I'll also enable Link Preview by default — buyers and sellers share product URLs in chat all the time, and the preview helps. You can disable it after with `cometchat apply-feature link-preview --remove`."
+
+Don't drown the user — pick at most 2 industry-specific suggestions per session. The verification matrix in the iteration menu surfaces the rest later.
 
 Ask: "Does this sound right, or do you want a different approach?" Let them override.
 
@@ -758,64 +943,136 @@ If the user has auth AND wants to set up production mode now:
 
 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
+#### 3f. Confirm the plan — the third wow moment
+
+**This is the trust contract. Show EXACTLY what you'll do BEFORE doing it.** Three sections, in this order:
 
-**This is critical. Show EXACTLY what you'll do before doing it.** The plan format differs by framework.
+1. **Files I'll create** — new files, with a one-line purpose for each
+2. **Files I'll modify** — existing files, with the specific edit (not "wrap with provider" alone — say "wrap the children of `<Layout>` with `<CometChatProvider>` at line ~14")
+3. **Files I won't touch** — call out the load-bearing files that stay untouched (auth config, route definitions outside the chat surface, your existing components). This is the reassurance.
 
-**Web example (Next.js, marketplace):**
-> "Here's what I'll create:
+Then dependencies + auth mode + an approval line that hands the user control.
+
+The shape (use it verbatim — three sections + reassurance):
+
+> Here's the plan:
+>
+> **Files I'll create**
+> - `cometchat/CometChatProvider.tsx` — wraps the kit's auth + theme providers, gates render on login
+> - `cometchat/init.ts` — module-level CometChat.init + login, called from the provider
+> - `app/messages/page.tsx` — full-page messages route (your inbox)
+> - `app/components/ChatDrawer.tsx` — the "chat with seller" drawer for product pages
+> - `.env.local` — your CometChat App ID + Region + Auth Key (gitignored)
 >
-> **New files:**
-> - `app/providers/CometChatProvider.tsx`
-> - `app/messages/page.tsx`
-> - `app/components/ChatDrawer.tsx`
-> - `.env.local`
+> **Files I'll modify**
+> - `app/layout.tsx` — wrap `{children}` with `<CometChatProvider>` (one line, around line 14)
+> - `app/products/[id]/page.tsx` — add the `<ChatDrawer />` trigger button next to the seller info (your existing layout stays)
+> - `app/components/Navbar.tsx` — add a `<Link href="/messages">Messages</Link>` next to your existing nav items
 >
-> **Files I'll modify:**
-> - `app/products/[id]/page.tsx` — add ChatDrawer trigger
-> - `app/layout.tsx` — wrap with CometChatProvider
-> - `app/components/Navbar.tsx` — add 'Messages' link
+> **Files I won't touch**
+> - `auth.config.ts` — your NextAuth setup stays as-is; we'll wire CometChat to it in production-auth mode later
+> - `tailwind.config.ts`, `globals.css` — no styling changes outside `cometchat/`
+> - Anything under `app/products/`, `app/cart/`, etc. — your existing routes are untouched
 >
-> **Dependencies:** @cometchat/chat-sdk-javascript, @cometchat/chat-uikit-react
+> **Dependencies**
+> `@cometchat/chat-sdk-javascript`, `@cometchat/chat-uikit-react`
 >
-> **Auth mode:** Development (Auth Key).
-> Proceed? [y/n]"
+> **Auth mode** Development (Auth Key for now; production auth is a one-flag upgrade later)
+>
+> **Estimated time** ~30 seconds to write the code, ~1 minute for `npm install` to finish.
+>
+> If anything looks off, just tell me what to change. Otherwise, say "go" and I'll write it.
+
+**The rules for this moment:**
+
+1. **Be specific in the modify section.** "Wrap with provider" is vague. "Wrap `{children}` with `<CometChatProvider>` at line ~14" tells the user exactly what to expect when they git-diff later.
+2. **List the don't-touch files explicitly.** Users worry about agents stomping their auth config, their tailwind, their routes. Naming what stays untouched defuses that worry up front.
+3. **Estimated time matters.** Two short numbers — a few seconds to write code, a couple minutes for `npm install`. Sets expectations; reduces "is it stuck?" mid-flow.
+4. **End with a hand-off, not a yes/no.** "Say 'go' and I'll write it. Or tell me what to change." Beats "Proceed? [y/n]" — it implies the user can adjust without throwing the whole plan away.
+5. **Never abbreviate the plan in subsequent runs.** Every integration deserves a fresh, full plan. If the user has been through this before, they can skim — but don't pre-skim for them.
+
+**Web example (Next.js + NextAuth, marketplace):** see the shape above.
+
+**Web example (Vite + React, greenfield messaging app):**
+
+> Here's the plan:
+>
+> **Files I'll create**
+> - `src/cometchat/CometChatProvider.tsx` — wraps the kit's providers, gates render on login
+> - `src/cometchat/init.ts` — `CometChat.init` + `CometChat.login` (with `cometchat-uid-1` for dev)
+> - `src/components/ChatScreen.tsx` — your full-page chat surface (conversations + messages)
+> - `.env` — your CometChat App ID + Region + Auth Key (gitignored)
+>
+> **Files I'll modify**
+> - `src/main.tsx` — wrap `<App />` with `<CometChatProvider>` (line ~10)
+> - `src/App.tsx` — render `<ChatScreen />` instead of the Vite default (you can move it to a route later)
+>
+> **Files I won't touch**
+> - `vite.config.ts`, `tsconfig.*` — no build config changes
+> - `src/index.css`, `src/App.css` — kit ships its own CSS; your styles stay
+>
+> **Dependencies** `@cometchat/chat-sdk-javascript`, `@cometchat/chat-uikit-react`
+>
+> **Auth mode** Development (Auth Key + `cometchat-uid-1`; you can log in as `cometchat-uid-1`–`uid-5` to chat with yourself across browser windows)
+>
+> **Estimated time** ~30 seconds to write, ~1 minute for `npm install`.
+>
+> Say "go" or tell me what to change.
 
 **RN example (Expo Router, messaging):**
-> "Here's what I'll create:
+
+> Here's the plan:
+>
+> **Files I'll create**
+> - `cometchat/CometChatProvider.tsx` — four-wrapper chain (gesture handler → safe area → theme → CometChat)
+> - `cometchat/init.ts` — init + login, module-level guard
+> - `app/(tabs)/messages.tsx` — your Messages tab
+> - `.env` — `EXPO_PUBLIC_COMETCHAT_APP_ID` + region + auth key
+>
+> **Files I'll modify**
+> - `app/_layout.tsx` — wrap with the four-wrapper chain (line ~10)
+> - `app/(tabs)/_layout.tsx` — add the Messages tab as the third entry, after Home and Profile
+> - `index.js` — `import 'react-native-gesture-handler'` at line 1 (mandatory; without it release builds break silently)
+>
+> **Files I won't touch**
+> - `app.json` — no Expo config changes for dev mode (production push needs them, but that's later)
+> - Your existing `app/(tabs)/index.tsx`, `profile.tsx` — stay as-is
 >
-> **New files:**
-> - `providers/CometChatProvider.tsx`
-> - `app/(tabs)/messages.tsx`
-> - `.env`
+> **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`
 >
-> **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)
+> **Auth mode** Development (Auth Key).
 >
-> **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
+> **Estimated time** ~30 seconds to write, ~3 minutes for `expo install` (RN deps are heavier).
 >
-> **Auth mode:** Development (Auth Key).
-> Proceed? [y/n]"
+> Say "go" or tell me what to change.
 
-**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
+**Bare RN variant** — same as Expo, except:
+- `npm install` instead of `npx expo install`
+- Run `cd ios && pod install` (~1-2 min extra)
+- Patch `ios/<Name>/Info.plist`, `android/app/src/main/AndroidManifest.xml` for camera/mic 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.
+Surface these in the "Files I'll modify" section so the user knows they're coming.
+
+**After approval — the writing moment:**
+
+When the user says "go", narrate progress as you work. Don't be silent for 30 seconds while you write 5 files. Brief structured updates, one per beat:
+
+> ✓ Created `cometchat/CometChatProvider.tsx`
+> ✓ Created `cometchat/init.ts`
+> ✓ Modified `src/main.tsx` (wrapped App with provider)
+> ✓ Wrote `.env` (Auth Key hidden)
+> Installing dependencies (this takes ~1 minute)...
+
+The structured beats make the writing feel like a contract being executed, not a black box churning.
+
+**If the user says no or wants changes:** go back to the relevant question and re-ask. Don't try to negotiate the plan in-line — the plan is atomic. Adjust the source decision, then regenerate the plan.
 
 ### Step 4 — Reference pattern skills
 
-**All skills are already loaded in your context** as `.claude/skills/` files. Do NOT use the `Skill()` tool. Read and follow them directly.
+**All skills are already loaded in your context** as `.claude/skills/` (or `.cursor/skills/` / `.kiro/skills/` / `.agents/skills/` — your agent's skills dir) files. NEVER explicitly load CometChat skills via your agent's skill-loading mechanism — the skills are already in your context. Just read and follow them directly.
 
 **For web frameworks:**
 1. `cometchat-core` — initialization, provider, CSS, anti-patterns
@@ -1152,7 +1409,7 @@ Then:
 
 ### Step 7 — Iteration menu
 
-Use `AskUserQuestion`. The option set differs by family — RN has two extra options (push notifications + testing) that don't apply to web.
+Ask the user (preserve this exact shape — `question`, `header`, `multiSelect`, `options[].label`, `options[].description` — agents have varying primitive names but all support this structured form). 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?"
@@ -1209,15 +1466,15 @@ For **troubleshooting (RN)**: read `cometchat-native-troubleshooting` and match
 
 ### Re-rendering the menu after each action
 
-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.
+After every Phase B action completes, you **MUST** re-render the menu via your agent's structured-question primitive 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 — 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`.
+- Skip the menu and ask freeform "What's next?" — always route through your agent's structured-question primitive.
 - 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.
+The iteration loop is the whole point of Phase B. Re-rendering the canonical menu via your agent's structured-question primitive after every action is how the user controls the session.
 
 ## Hard rules
 
@@ -1233,7 +1490,7 @@ The iteration loop is the whole point of Phase B. Re-rendering the canonical men
 - **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.
+- **NEVER explicitly load CometChat skills via your agent's skill-loading mechanism.** They're already in your context as `.claude/skills/`, `.cursor/skills/`, `.kiro/skills/`, or `.agents/skills/` files. Just read and follow them directly.
 
 ### Web only