@cometchat/skills 4.0.0 → 4.1.0

package/README.md

@@ -10,7 +10,7 @@ v4 takes an AI-first approach: your agent has a short conversation with you to u
 npx @cometchat/skills add
 ```
 
-That's it — one command for every supported framework. The installer detects what you're working with (React, Next.js, React Router, Astro, Expo, bare React Native, Angular, native Android, Flutter, or native iOS) from your project and installs the right skills.
+That's it — one command for every supported framework. The installer detects what you're working with (React, Next.js, React Router, Astro, Expo, bare React Native, Angular, native Android, Flutter, or native iOS) from your project, then opens an interactive picker so you can choose which AI agents to install for — Claude Code, Cursor, Codex, Cline, Kiro, Replit Agent, and [50+ more](https://github.com/vercel-labs/skills) all in one pass.
 
 Override detection if needed:
 
@@ -24,7 +24,47 @@ npx @cometchat/skills add --family ios      # Native iOS (V5 stable)
 npx @cometchat/skills add --family all      # install every published skill
 ```
 
-Supported IDEs: Claude Code (default), Cursor, Kiro, VS Code Copilot, Replit Agent. Use `--ide <name>` to target a specific one, or `--ide all`. Replit users: skills land in `.agents/skills/` automatically when you pass `--ide replit`.
+### Two install shapes
+
+**Base install (default, recommended)** — `npx @cometchat/skills add` writes only the cross-family skills (the `cometchat` dispatcher and friends). Smallest initial install. After it lands, open your project in your IDE and run `/cometchat`:
+
+1. The dispatcher detects your framework (Vite + React → `web`, Expo → `native`, etc.)
+2. It asks the agent to install family-specific skills on demand via `npx @cometchat/skills add --family <X> --ide <Y>`
+3. The agent gets the 13 web skills (or 31 android, 28 flutter, etc.) at exactly the moment they're needed
+4. Integration continues with the full skill set loaded
+
+You install once with the multi-agent picker (Claude Code, Cursor, Codex, Cline, Kiro, Replit Agent, [50+ more](https://github.com/vercel-labs/skills)); the dispatcher handles framework-specific expansion as the project actually needs it.
+
+**Full family install** — `npx @cometchat/skills add --family <name>` writes the dispatcher + every skill for that family upfront (web=13, android=31, flutter=28, etc.). Use when you know the framework upfront and want all skills present without runtime expansion. Power users + CI smoke tests.
+
+```bash
+# Base install (recommended) — picker + dispatcher routes the rest
+npx @cometchat/skills add
+
+# Full family install — power-user / CI flow
+npx @cometchat/skills add --family web      # all 13 web skills upfront
+npx @cometchat/skills add --family native   # all 13 RN skills upfront
+npx @cometchat/skills add --family android  # all 31 Android skills upfront
+# ... etc
+```
+
+### Direct-write to one IDE (CI / Dockerfile)
+
+When stdin isn't a TTY (CI, Docker), or when you pass `--ide <name>`, the picker is skipped and skills are written directly to one IDE's directory. Default is base install; pass `--family <name>` for the full family install.
+
+```bash
+npx @cometchat/skills add --ide claude              # base install to .claude/skills/
+npx @cometchat/skills add --ide cursor              # base install to .cursor/skills/
+npx @cometchat/skills add --ide kiro                # base install to .kiro/skills/
+npx @cometchat/skills add --ide replit              # base install to .agents/skills/
+npx @cometchat/skills add --ide copilot             # base install to .github/copilot-instructions.md
+npx @cometchat/skills add --ide all                 # write base install to every supported IDE
+npx @cometchat/skills add --ide claude --family web # full web family install to .claude/skills/
+```
+
+Direct-write supports 10 agents: `claude`, `cursor`, `kiro`, `replit`, `copilot`, `continue`, `cline`, `aider`, `codex`, `gemini`. The interactive picker supports 55+ via the vercel-labs/skills ecosystem.
+
+Pass `--no-picker` to force direct-write even in an interactive terminal.
 
 > **Migrating from v3?** `npx @cometchat/skills-native add` still works (with a deprecation notice). New projects should use the unified command.
 

package/bin/install.js

@@ -6,6 +6,7 @@ const fs = require("fs");
 const path = require("path");
 const os = require("os");
 const readline = require("readline");
+const { spawn } = require("child_process");
 
 // ── Lazy-load optional deps ───────────────────────────────────────────────────
 function tryRequire(name) {
@@ -157,6 +158,26 @@ const SKILLS = [
   { name: "cometchat-ios-troubleshooting",       families: ["ios"], description: "iOS troubleshooting: SPM, CocoaPods, Xcode build errors, Info.plist, runtime crashes" },
 ];
 
+// ── Base skills (cross-family) ────────────────────────────────────────────────
+//
+// Skills registered for ALL six families. These are the baseline a dispatcher
+// needs to detect framework and route — they're installed in the default
+// interactive flow, before any family is resolved. The dispatcher (read at
+// runtime in the user's IDE) detects the framework and asks the agent to
+// install the relevant family skills via:
+//
+//   npx @cometchat/skills add --family <X> --ide <Y>
+//
+// (Logic already in `skills/cometchat/SKILL.md` Step 1 — "If `framework` is
+// X AND `cometchat-{X}-core` is NOT loaded: <install command>".)
+//
+// This list grows automatically as more cross-family skills are registered
+// (e.g. when the calls work merges, cometchat-calls/i18n/a11y join).
+const ALL_FAMILIES_SET = ["web", "native", "flutter", "angular", "android", "ios"];
+const BASE_SKILLS = SKILLS.filter(s =>
+  ALL_FAMILIES_SET.every(f => s.families.includes(f))
+);
+
 // ── Framework → family routing ────────────────────────────────────────────────
 const FRAMEWORK_TO_FAMILY = {
   reactjs:        "web",
@@ -384,13 +405,74 @@ function installCopilotSkills(skillsToInstall, baseDir) {
   return dest;
 }
 
+// ── Multi-agent picker via vercel-labs/skills ────────────────────────────────
+//
+// Spawns `npx -y skills@<pin> add cometchat-team/cometchat-skills -s <names>`
+// so the interactive multi-agent picker (Claude Code / Cursor / Codex /
+// Cline / Kiro / Replit / 50+ agents) shows. The user picks which agents
+// to write to; the skills CLI handles the per-agent path conventions.
+//
+// We pre-resolve the family-specific skill list (from `resolveFamilies` +
+// SKILLS table) and pass the names via `-s name1 name2 ...` so the user
+// only sees skills relevant to their detected family — not all 100+ in
+// the marketplace.
+//
+// Pin: `skills@1.5.5` was the version verified against this codebase.
+// Bump on intentional re-verification; pre-pin avoids breakage from a
+// future major bump in the upstream CLI.
+const SKILLS_CLI_PIN = "skills@1.5.5";
+const SKILLS_REPO = "cometchat-team/cometchat-skills";
+
+async function delegateToSkillsCli({ skills, families, isGlobal }) {
+  const skillNames = skills.map(s => s.name);
+  const familyLabel = families.includes("all") ? "all" : families.join("+");
+
+  console.log(`\n  ${c.bold(c.cyan("CometChat Skills"))}  —  ${c.bold(familyLabel)} family  —  ${skillNames.length} skills`);
+  console.log(`  ${c.gray("Launching multi-agent picker via vercel-labs/skills...")}\n`);
+
+  const npxArgs = [
+    "-y",                       // auto-accept the npx install prompt for the skills CLI itself
+    SKILLS_CLI_PIN,
+    "add",
+    SKILLS_REPO,
+    "-s", ...skillNames,        // space-separated skill names (skills CLI's flag shape)
+  ];
+  if (isGlobal) npxArgs.push("-g");
+
+  return new Promise((resolve) => {
+    const child = spawn("npx", npxArgs, {
+      stdio: "inherit",
+      shell: false,
+    });
+    child.on("close", (code) => resolve(code ?? 1));
+    child.on("error", (err) => {
+      console.error(c.red(`\n  ✗ Failed to spawn skills CLI: ${err.message}`));
+      console.error(c.dim(`  Falling back to legacy direct-write — re-run with --ide <name> to bypass the picker.\n`));
+      resolve(2);
+    });
+  });
+}
+
 function printHelp() {
   console.log(`
   ${c.bold("@cometchat/skills")} — Install CometChat AI coding skills
 
   ${c.bold("Usage:")}
-    ${c.cyan("npx @cometchat/skills add")}                       Auto-detect framework + install
-    ${c.cyan("npx @cometchat/skills add --family <name>")}       Override detection
+    ${c.cyan("npx @cometchat/skills add")}                       Base install + interactive multi-agent picker
+    ${c.cyan("npx @cometchat/skills add --family <name>")}       Install full family upfront (no runtime expansion)
+    ${c.cyan("npx @cometchat/skills add --ide <name>")}          Direct-write base skills to one IDE (CI/scripted)
+
+  ${c.bold("Two install shapes:")}
+    ${c.bold("Base install")} (default — no --family flag): writes only the cross-family
+      skills (the cometchat dispatcher + cross-family helpers). Once installed,
+      open your project in your IDE and run /cometchat — the dispatcher detects
+      your framework and asks the agent to install the family-specific skills
+      via \`npx @cometchat/skills add --family <X> --ide <Y>\`. Smallest initial
+      install, dispatcher routes the rest. Recommended for most users.
+    ${c.bold("Full family install")} (--family flag): writes the dispatcher + every
+      skill registered for that family (web=13, android=31, flutter=28, etc.)
+      upfront. Use when you know the project's framework and prefer all skills
+      present immediately. Used by power users + CI smoke tests.
 
   ${c.bold("Family values:")}
     ${c.cyan("web")}      React / Next.js / React Router / Astro
@@ -401,7 +483,7 @@ function printHelp() {
     ${c.cyan("ios")}      iOS native (V5 stable)
     ${c.cyan("all")}      Install every skill (legacy v3 behavior)
 
-  ${c.bold("IDE selection (default: claude):")}
+  ${c.bold("IDE selection (direct-write mode only — default: claude):")}
     ${c.cyan("--ide cursor")}    ${c.cyan("--ide kiro")}    ${c.cyan("--ide copilot")}    ${c.cyan("--ide replit")}    ${c.cyan("--ide all")}
 
   ${c.bold("Multi-family / monorepo:")}
@@ -409,8 +491,9 @@ function printHelp() {
 
   ${c.bold("Other:")}
     ${c.cyan("--global")}        Install globally (~/.claude/skills/, etc.)
-    ${c.cyan("--clean")}         Wipe existing cometchat-* skill dirs before install
+    ${c.cyan("--clean")}         Wipe existing cometchat-* skill dirs before install (direct-write mode only)
     ${c.cyan("--list")}          Show every skill with its family tags
+    ${c.cyan("--no-picker")}     Force direct-write even in interactive TTY (useful for testing the legacy path)
 
   ${c.bold("After installing, open your project in your IDE and run:")}
     ${c.cyan("/cometchat")}
@@ -448,37 +531,88 @@ async function main() {
     process.exit(0);
   }
 
-  // Resolve which families to install (flag(s) → detect → prompt).
-  const families = await resolveFamilies(args);
-
-  // Build the set of skills to install — union over all selected families.
-  // "all" is a singleton meaning "every published skill" (legacy v3 behavior).
+  // ── Install mode selection ─────────────────────────────────────────────
+  //
+  // Three valid invocation shapes:
+  //
+  //   1. `npx @cometchat/skills add` (TTY, no --family, no --ide)
+  //      → BASE INSTALL: install only cross-family skills (cometchat
+  //        dispatcher + cometchat-calls + i18n + a11y) via the multi-agent
+  //        picker. The dispatcher detects the framework AT RUNTIME inside
+  //        the user's IDE and asks the agent to install family-specific
+  //        skills via `npx @cometchat/skills add --family <X> --ide <Y>`.
+  //        Smallest initial install; routing is the dispatcher's job.
+  //
+  //   2. `npx @cometchat/skills add --family <X>` (TTY)
+  //      → FAMILY INSTALL: install the dispatcher + every skill registered
+  //        for family X (web=13, android=31, etc.) via the picker. Use this
+  //        when you know upfront which family you want and prefer all
+  //        skills present immediately.
+  //
+  //   3. `npx @cometchat/skills add --ide <Y>` (or non-TTY, e.g. CI)
+  //      → DIRECT WRITE: skips the picker and writes directly to one IDE's
+  //        directory. With --family, writes the family subset; without, falls
+  //        back to BASE skills (CI smoke). Used by Dockerfiles and the
+  //        legacy single-agent flow.
+  const ideExplicit = ideIdx !== -1;
+  const familyExplicit = args.includes("--family");
+  const isTTY = process.stdin.isTTY && process.stdout.isTTY;
+  const skipPicker = ideExplicit || !isTTY || args.includes("--no-picker");
+
+  // Resolve skill set based on mode:
+  //   - --family X → install the dispatcher + every skill registered for X
+  //     (legacy power-user / CI flow; everything present immediately)
+  //   - No --family (with or without --ide) → BASE install only. The
+  //     dispatcher handles family-specific install at runtime via its own
+  //     `npx @cometchat/skills add --family <X>` invocation logic.
   let skillsToInstall;
-  if (families.includes("all")) {
-    skillsToInstall = SKILLS;
-  } else {
-    const seen = new Set();
-    skillsToInstall = [];
-    for (const fam of families) {
-      for (const s of SKILLS) {
-        if (s.families.includes(fam) && !seen.has(s.name)) {
-          seen.add(s.name);
-          skillsToInstall.push(s);
+  let families;
+  if (familyExplicit) {
+    families = await resolveFamilies(args);
+    if (families.includes("all")) {
+      skillsToInstall = SKILLS;
+    } else {
+      const seen = new Set();
+      skillsToInstall = [];
+      for (const fam of families) {
+        for (const s of SKILLS) {
+          if (s.families.includes(fam) && !seen.has(s.name)) {
+            seen.add(s.name);
+            skillsToInstall.push(s);
+          }
         }
       }
     }
+
+    // If no pattern skills matched (only the dispatcher), all selected
+    // families are "coming soon" — bail with a friendly message rather than
+    // installing a half-broken set.
+    const patternSkills = skillsToInstall.filter(s => s.name !== "cometchat");
+    if (patternSkills.length === 0) {
+      const labels = families.map(f => FAMILY_LABELS[f] || f).join(", ");
+      console.log(c.yellow(`\n  ⚠ Pattern skills for ${labels} aren't published yet.`));
+      console.log(`  Supported families today: ${c.cyan("web")}, ${c.cyan("native")}, ${c.cyan("angular")}, ${c.cyan("android")}, ${c.cyan("flutter")}, ${c.cyan("ios")}.`);
+      console.log(`  Run with one of those, or wait for ${families.join(" + ")} skills to ship.\n`);
+      process.exit(1);
+    }
+  } else {
+    // Default: base install only (whether interactive or with --ide).
+    // The dispatcher detects the framework at runtime and installs the
+    // family-specific skills via its own runtime npx invocation.
+    skillsToInstall = BASE_SKILLS;
+    families = ["base"];
+    console.log(`\n  ${c.bold(c.cyan("CometChat Skills"))}  ${c.dim("(base install — dispatcher routes the rest at runtime)")}`);
+    console.log(`  ${c.gray(`Installing ${BASE_SKILLS.length} cross-family ${BASE_SKILLS.length === 1 ? "skill" : "skills"}: ${BASE_SKILLS.map(s => s.name).join(", ")}.`)}`);
+    console.log(`  ${c.gray("After install, open your project in your IDE → /cometchat detects your framework and asks the agent to install family-specific skills on demand.")}\n`);
   }
 
-  // If no pattern skills matched (only the dispatcher), all selected families
-  // are "coming soon" — bail with a friendly message rather than installing a
-  // half-broken set.
-  const patternSkills = skillsToInstall.filter(s => s.name !== "cometchat");
-  if (patternSkills.length === 0) {
-    const labels = families.map(f => FAMILY_LABELS[f] || f).join(", ");
-    console.log(c.yellow(`\n  ⚠ Pattern skills for ${labels} aren't published yet.`));
-    console.log(`  Supported families today: ${c.cyan("web")}, ${c.cyan("native")}, ${c.cyan("angular")}, ${c.cyan("android")}, ${c.cyan("flutter")}, ${c.cyan("ios")}.`);
-    console.log(`  Run with one of those, or wait for ${families.join(" + ")} skills to ship.\n`);
-    process.exit(1);
+  if (!skipPicker) {
+    const exitCode = await delegateToSkillsCli({
+      skills: skillsToInstall,
+      families,
+      isGlobal,
+    });
+    process.exit(exitCode);
   }
 
   const targets = ideArg === "all" ? Object.keys(IDE_TARGETS) : [ideArg];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cometchat/skills",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "publishConfig": {
     "access": "public"
   },

package/skills/cometchat/SKILL.md

@@ -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
@@ -614,29 +663,46 @@ 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 |
-|---|---|
-| **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. |
+| 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.
+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.
 
 Ask: "Does this sound right, or do you want a different approach?" Let them override.
 
@@ -758,60 +824,132 @@ 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:
+
+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.
+
+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)
+>
+> **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 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`
+>
+> **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:**
 
-**This is critical. Show EXACTLY what you'll do before doing it.** The plan format differs by framework.
+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, marketplace):**
-> "Here's what I'll create:
+**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)
 >
-> **New files:**
-> - `app/providers/CometChatProvider.tsx`
-> - `app/messages/page.tsx`
-> - `app/components/ChatDrawer.tsx`
-> - `.env.local`
+> **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
 >
-> **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
+> **Dependencies** `@cometchat/chat-sdk-javascript`, `@cometchat/chat-uikit-react`
 >
-> **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)
 >
-> **Auth mode:** Development (Auth Key).
-> Proceed? [y/n]"
+> **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
 >
-> **New files:**
-> - `providers/CometChatProvider.tsx`
-> - `app/(tabs)/messages.tsx`
-> - `.env`
+> **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'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)
+> **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
 >
-> **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
+> **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]"
+> **Auth mode** Development (Auth Key).
+>
+> **Estimated time** ~30 seconds to write, ~3 minutes for `expo install` (RN deps are heavier).
+>
+> 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
 

package/skills/cometchat-placement/SKILL.md

@@ -1278,6 +1278,34 @@ These rules apply to ALL placement patterns. Violating any of them causes integr
 
 6. **Every CometChat container must have explicit dimensions.** Components fill 100% of their parent. If the parent has no height, the components collapse to zero. Always set `height`, `min-height`, or use flex/grid layout with a bounded container.
 
+6a. **Flex parents that hold a `CometChatMessageList` MUST set `minHeight: 0`** (and `minWidth: 0` for horizontal flex parents). The W3C default `min-height: auto` makes flex children refuse to shrink below their intrinsic content size — so once the conversation grows past the viewport, the list pushes the composer below the fold and the layout breaks. **This is the canonical chat-layout bug** — works fine for short conversations, breaks for long ones. The fix is one CSS property; the diagnosis takes hours if you don't know the rule.
+
+```tsx
+/* ✓ CORRECT — header + list + composer with the flex-shrink trap fixed */
+<div style={{ display: "flex", flexDirection: "column", height: "100vh" }}>
+  <div style={{ flex: 1, display: "flex", flexDirection: "column", minHeight: 0 }}>
+    <div style={{ flex: "0 0 auto" }}>
+      <CometChatMessageHeader user={user} />
+    </div>
+    <div style={{ flex: "1 1 0", minHeight: 0, overflow: "hidden" }}>
+      <CometChatMessageList user={user} hideReplyInThreadOption />
+    </div>
+    <div style={{ flex: "0 0 auto" }}>
+      <CometChatMessageComposer user={user} />
+    </div>
+  </div>
+</div>
+
+/* ✗ WRONG — list grows past the viewport once messages exceed visible area */
+<div style={{ display: "flex", flexDirection: "column", height: "100vh" }}>
+  <CometChatMessageHeader user={user} />
+  <CometChatMessageList user={user} />          {/* takes intrinsic height, no scroll */}
+  <CometChatMessageComposer user={user} />     {/* falls off the bottom */}
+</div>
+```
+
+The wrap-each-component-in-a-flex-sized-div pattern is what makes this work. Don't pass the kit components directly as flex children — wrap them.
+
 7. **Resolve target users/groups before rendering CometChat components.** Use `CometChat.getUser(uid)` or `CometChat.getGroup(guid)` to get the full `CometChat.User` or `CometChat.Group` object. Do not pass a raw UID string to `user` props -- they expect object instances.
 
 8. **For SSR frameworks, wrap CometChat components appropriately.** See the `cometchat-core` skill, section 5 (SSR safety), for framework-specific patterns.

package/skills/cometchat-react-patterns/SKILL.md

@@ -468,30 +468,78 @@ Vite's HMR replaces modules without a full page reload. CometChat's SDK holds a
 
 However, if you change the provider file itself during development, HMR may re-execute the module. The `initialized` flag prevents double-init, but the WebSocket connection from the previous module instance may linger. If you see duplicate messages or connection issues during development, do a full page reload (`Ctrl+Shift+R`).
 
-### Container height
+### Container height (and the flex-shrink trap that breaks chat layouts)
 
-CometChat components fill 100% of their container. The most common visual bug is components rendering with zero height because their container has no explicit dimensions. Always ensure the chat container has a height:
+CometChat components fill 100% of their container. Two visual bugs to avoid:
+
+**Bug 1 — zero height:** components render with zero height because the container has no explicit dimensions.
+**Bug 2 — message list grows past the viewport:** the list scrolls fine until it has too many messages, then pushes the composer below the fold. **This is the classic flex-shrink trap.**
+
+The hard rule for two-pane / header+list+composer layouts: every flex container in the chain MUST have `minHeight: 0` (and `minWidth: 0` for horizontal flex). Without it, browsers default flex-children to `min-height: auto` (their intrinsic content size), so the list grows beyond the parent's bounds as messages accumulate.
 
 ```tsx
-/* CORRECT: explicit height */
+/* ✓ CORRECT: explicit height for a single-component surface */
 <div style={{ height: "100vh" }}>
   <CometChatConversations ... />
 </div>
 
-/* CORRECT: flex layout with bounded parent */
+/* ✓ CORRECT: header + list + composer with the flex-shrink trap fixed */
 <div style={{ display: "flex", flexDirection: "column", height: "100vh" }}>
   <nav>...</nav>
-  <div style={{ flex: 1 }}>
-    <CometChatConversations ... />
+  <div style={{
+    flex: 1,
+    display: "flex",
+    flexDirection: "column",
+    minHeight: 0,        // ← THIS IS THE HARD RULE — without it, list grows past the viewport
+  }}>
+    <div style={{ flex: "0 0 auto" }}>
+      <CometChatMessageHeader user={user} />
+    </div>
+    <div style={{ flex: "1 1 0", minHeight: 0, overflow: "hidden" }}>
+      <CometChatMessageList user={user} />
+    </div>
+    <div style={{ flex: "0 0 auto" }}>
+      <CometChatMessageComposer user={user} />
+    </div>
   </div>
 </div>
 
-/* WRONG: no height constraint -- component collapses to zero */
+/* ✓ CORRECT: two-pane (sidebar + active chat) — both axes need min-{width,height}: 0 */
+<div style={{ display: "flex", height: "100vh" }}>
+  <div style={{ width: 360, display: "flex", flexDirection: "column" }}>
+    <CometChatConversations onItemClick={...} />
+  </div>
+  <div style={{
+    flex: 1,
+    display: "flex",
+    flexDirection: "column",
+    minWidth: 0,         // ← horizontal flex parent: prevents content from forcing horizontal scroll
+    minHeight: 0,        // ← vertical flex (the inner column): prevents the list-overflow bug
+  }}>
+    {/* header / list / composer wrapped as above */}
+  </div>
+</div>
+
+/* ✗ WRONG: no height constraint — component collapses to zero */
 <div>
   <CometChatConversations ... />
 </div>
+
+/* ✗ WRONG: flex parent without minHeight: 0 — list grows past the viewport once
+   you accumulate more messages than fit on-screen. Composer falls off the bottom. */
+<div style={{ display: "flex", flexDirection: "column", height: "100vh" }}>
+  <CometChatMessageHeader user={user} />
+  <CometChatMessageList user={user} />          {/* takes intrinsic content height */}
+  <CometChatMessageComposer user={user} />     {/* gets pushed below the fold */}
+</div>
 ```
 
+**Why `minHeight: 0` is non-obvious:** the W3C spec sets the default `min-height` of a flex item to `auto` (its intrinsic content height). For a scrollable list inside a flex column, this means the list refuses to shrink below its content even when the parent is bounded. Setting `minHeight: 0` on the flex parent overrides this, letting the list shrink and scroll within the bounded container instead of overflowing it.
+
+**The rule, restated as something to grep for:**
+
+> Every flex container that holds `CometChatMessageList` (directly or indirectly) MUST have `minHeight: 0` on it. Same for `minWidth: 0` on horizontal flex parents. Skip this and the layout works for short conversations and breaks for long ones.
+
 ### Vite dependency optimization
 
 Vite pre-bundles dependencies for faster dev startup. CometChat's packages are large and may trigger Vite's "new dependency found, reloading" message on first load. This is normal and only happens once. If it causes issues, you can pre-include the packages: