@cometchat/skills 3.0.0

package/skills/cometchat/SKILL.md

@@ -0,0 +1,662 @@
+---
+name: cometchat
+description: Entry-point for CometChat integration. Guides a multi-step interactive conversation to understand the project, gather requirements, and write production-quality integration code.
+license: "MIT"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory, AskUserQuestion"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat dispatcher entry react chat"
+---
+
+## Use this skill when
+
+The user wants to add CometChat to any kind of project. Trigger phrases:
+
+- `/cometchat`
+- "add cometchat", "integrate cometchat", "add chat to my app"
+- "add messaging", "add chat ui"
+
+This is the **entry point**. Do not invoke framework-specific skills
+directly — this dispatcher will route to the right ones.
+
+## How v3 works
+
+v3 skills are **interactive and conversational**. You don't just detect
+the framework and dump code. You have a conversation with the developer
+to understand their project, their use case, and exactly where chat
+should go — THEN you write code that fits.
+
+The pattern skills teach you:
+- `cometchat-core` — initialization, login, CSS, env vars, provider pattern
+- `cometchat-components` — every component name, props, composition patterns
+- `cometchat-placement` — WHERE to put chat (route, modal, drawer, embed, widget)
+- `cometchat-{framework}-patterns` — framework-specific integration patterns
+
+**Key principle: ask, don't assume.** Every piece of information you need
+from the user should be asked explicitly. Don't guess the route path,
+don't guess where the trigger button goes, don't guess the auth system.
+
+## Steps
+
+### Step 1 — Detect framework + map the project
+
+First, check if `.cometchat/config.json` exists:
+```bash
+npx @cometchat/skills-cli config show --json
+```
+
+If config exists with previous answers, tell the user:
+> "I see you've set up CometChat before. Using your saved config:
+> Framework: {framework}, App: {appId}, Intent: {intent}.
+> Want to continue with these, or start fresh?"
+
+If no config, run detection:
+```bash
+npx @cometchat/skills-cli detect --json
+```
+
+**Then read the project yourself — this is critical:**
+- `package.json` — name, dependencies, scripts
+- The source directory structure — list all directories under `src/` or `app/`
+- Find the router: look for `createBrowserRouter`, `app/` directory, `pages/`,
+  `react-router.config.ts`, `astro.config.*`
+- Find the layout: `App.tsx`, `layout.tsx`, `root.tsx`, `Layout.astro`
+- Find the nav: look for components with "nav", "header", "sidebar" in name
+- Find existing pages/routes: list them so you can reference them later
+
+Store this mental map — you'll use it throughout the conversation.
+
+If `compatibility.supported` is `false`, stop and surface the warnings.
+
+### Step 2 — Set up credentials (onboarding)
+
+**CRITICAL: All onboarding happens via CLI commands. NEVER send the user
+to a browser or dashboard. The CLI handles signup, login, app creation,
+and credential writing — all from the terminal.**
+
+If config has `appId` set, verify credentials are in `.env` and skip to Step 3.
+
+Otherwise check:
+```bash
+npx @cometchat/skills-cli auth status --json
+```
+
+If `status` is `"logged-in"`, skip to **Step 2c** (app selection).
+
+If `status` is `"logged-out"`, ask:
+
+Use `AskUserQuestion`:
+- **question:** "Let's set up CometChat. Do you have an account?"
+- **header:** "Account"
+- **multiSelect:** false
+- **options:**
+  1. label: "Create a new account", description: "Free signup — I'll handle it right here, no browser needed."
+  2. label: "Sign in to existing account", description: "Log in and pick one of your apps."
+  3. label: "I'll paste credentials myself", description: "I already have my App ID, Region, and Auth Key."
+
+Option 1 → **Step 2b**. Option 2 → **Step 2a**. Option 3 → **Step 2d**.
+
+#### Step 2a — Sign in (existing account, browser flow)
+
+```bash
+npx @cometchat/skills-cli auth login
+```
+
+This command:
+1. Generates a short-lived session via the CLI auth API.
+2. Opens `https://app.cometchat.com/login?sessionId=<hex>` in the user's default browser.
+3. Polls the auth API every 5 seconds for up to 15 minutes.
+4. When the user finishes signing in (email+password, Google, or GitHub — whatever their account uses), the dashboard marks the session authenticated. The next poll receives the bearer token and stores it in the OS keychain.
+5. Prints `✓ Logged in as <email> (backend: keychain-macos).`
+
+Let the CLI block — do NOT background it, do NOT race it with other
+prompts. The user completes sign-in in the browser tab; the terminal
+waits.
+
+Terminal error handling (surface verbatim, stop, do not retry silently):
+- `ACCESS_DENIED` — user clicked Deny in the dashboard.
+- `EXPIRED` — 15-minute window elapsed.
+- `TIMEOUT` — max polls exhausted before user authorized.
+- `ABORTED` — user Ctrl-C'd the CLI.
+- `NETWORK` — couldn't reach the auth host.
+- `ALREADY_AUTHENTICATED` — this session was already consumed. Re-run
+  `auth login` to mint a fresh session.
+
+After success, verify:
+```bash
+npx @cometchat/skills-cli auth status --json
+```
+
+If `status` is `"logged-in"`, proceed to **Step 2c**.
+
+#### Step 2b — Sign up (new account, browser flow)
+
+```bash
+npx @cometchat/skills-cli auth signup
+```
+
+Same polling flow as Step 2a, but the CLI opens
+`https://app.cometchat.com/signup?sessionId=<hex>`. The browser
+handles everything — email, name, password, verification email, role,
+industry. The CLI never sees any of those values. When the user
+finishes signup in the browser, the next poll stores the bearer token
+in the OS keychain and the CLI prints `✓ Logged in as <email>`.
+
+No role / name / verification-code questions in the chat. The dashboard
+owns that flow now; skipping it keeps the user's password and verification
+code out of the transcript.
+
+Error codes match Step 2a (ACCESS_DENIED, EXPIRED, TIMEOUT, ABORTED,
+NETWORK, ALREADY_AUTHENTICATED). Surface verbatim and stop.
+
+After success, verify:
+```bash
+npx @cometchat/skills-cli auth status --json
+```
+
+If `status` is `"logged-in"`, proceed to **Step 2c**.
+
+#### Step 2c — Pick or create an app
+
+**Run this immediately — do NOT ask the user to go to any dashboard:**
+```bash
+npx @cometchat/skills-cli provision list --json
+```
+
+**If the user has existing apps**, show them and ask which to use:
+> "I found these CometChat apps on your account:
+> 1. my-marketplace-chat (us) — Developer plan
+> 2. test-app (eu) — Developer plan
+>
+> Which one should I use, or should I create a new one?"
+
+**For an existing app**, fetch credentials and wire everything in one call
+(pass `--framework` from Step 1 detection — one of `reactjs`, `nextjs`,
+`react-router`, `astro`):
+```bash
+npx @cometchat/skills-cli provision setup \
+  --app-id "<selected-appId>" --framework "<framework>" --json
+```
+
+This creates/updates `.env` with the correct prefix AND writes
+`.cometchat/config.json` in one step. Output is compact:
+`{ appId, region, framework, envFile, configPath }` — no authKey echoed
+back, no multi-command chain. Skip ahead to "Tell the user" below.
+
+**If no apps exist** (or user wants new), collect:
+1. App name — suggest `<project-name>-chat` from package.json `name`
+2. Region — use `AskUserQuestion`:
+   - **question:** "Which region for your CometChat app?"
+   - **header:** "Region"
+   - **options:**
+     1. label: "US", description: "United States (recommended)"
+     2. label: "EU", description: "Europe"
+     3. label: "India", description: "India"
+
+   **Region key mapping** (CLI expects lowercase):
+   | Label | `--region` value |
+   |---|---|
+   | US | `us` |
+   | EU | `eu` |
+   | India | `in` |
+3. Industry — use `AskUserQuestion`:
+   - **question:** "What's your app's industry?"
+   - **header:** "Industry"
+   - **options:**
+     1. label: "SaaS / Business", description: ""
+     2. label: "Marketplace", description: ""
+     3. label: "Social / Community", description: ""
+     4. label: "Other", description: ""
+
+**Industry key mapping:**
+
+| Label | --industry value |
+|---|---|
+| SaaS / Business | `saas_businesses` |
+| Marketplace | `online_marketplaces` |
+| Social / Community | `community_and_social` |
+| Healthcare | `healthcare` |
+| Dating | `dating` |
+| Education | `online_education` |
+| Events / Streaming | `events_and_streaming` |
+| Sports / Gaming | `sports_and_gaming` |
+| Team Communication | `team_comms_and_workflows` |
+| On-demand Services | `on_demand_services` |
+| Other | `other` |
+
+**Confirm before creating:**
+> "I'll create a CometChat app:
+> - Name: test-cometchat-vite-chat
+> - Region: US
+> - Industry: SaaS / Business
+>
+> Go ahead?"
+
+Then create the app AND wire `.env` AND save config in one step. Pass
+`--framework` from Step 1 detection (one of `reactjs`, `nextjs`,
+`react-router`, `astro`):
+```bash
+npx @cometchat/skills-cli provision setup \
+  --name "<name>" --region "<region>" --industry "<industry_key>" \
+  --framework "<framework>" --json
+```
+
+Output is compact: `{ appId, region, framework, envFile, configPath }`.
+The authKey is written to the env file but is NOT echoed to stdout, so
+credentials don't appear multiple times in the transcript. This replaces
+the old `provision create` → `provision use` → `config init` chain.
+
+Tell the user: "Your CometChat account and app are ready. Credentials
+saved to `.env`. Let's set up the integration."
+
+#### Step 2d — Paste keys manually
+
+Tell the user which env vars to set based on the detected framework:
+
+| Framework | Env file | Variables |
+|---|---|---|
+| reactjs (Vite) | `.env` | `VITE_COMETCHAT_APP_ID`, `VITE_COMETCHAT_REGION`, `VITE_COMETCHAT_AUTH_KEY` |
+| nextjs | `.env.local` | `NEXT_PUBLIC_COMETCHAT_APP_ID`, `NEXT_PUBLIC_COMETCHAT_REGION`, `NEXT_PUBLIC_COMETCHAT_AUTH_KEY` |
+| react-router | `.env` | `VITE_COMETCHAT_APP_ID`, `VITE_COMETCHAT_REGION`, `VITE_COMETCHAT_AUTH_KEY` |
+| astro | `.env` | `PUBLIC_COMETCHAT_APP_ID`, `PUBLIC_COMETCHAT_REGION`, `PUBLIC_COMETCHAT_AUTH_KEY` |
+
+> "Grab your credentials from https://app.cometchat.com → Your App →
+> API & Auth Keys. Create the env file above and tell me when done."
+
+After they confirm, verify:
+```bash
+npx @cometchat/skills-cli config init --json
+```
+
+### Step 3 — Interactive requirements gathering
+
+This is the core of v3. A multi-step conversation that gathers everything
+you need before writing a single line of code.
+
+#### 3a. "What are you building?"
+
+If config has `intent` set, confirm it and move on.
+
+Otherwise, use `AskUserQuestion`:
+- **question:** "What kind of app are you building?"
+- **header:** "Your app"
+- **multiSelect:** false
+- **options:**
+  1. label: "Messaging app", description: "Chat is the main feature — like Slack, Discord, or WhatsApp."
+  2. label: "Marketplace or platform", description: "Buyers and sellers communicate — like Airbnb, eBay, or Fiverr."
+  3. label: "SaaS or dashboard", description: "Team chat or support chat inside a product — like Notion or Intercom."
+  4. label: "Social or community", description: "User profiles with messaging — like a dating app or forum."
+  5. label: "Support or helpdesk", description: "Customer-to-agent communication."
+  6. label: "Just exploring", description: "Quick demo — fastest path to see chat working."
+
+**If "Just exploring":** skip the rest of Step 3. Use `cometchat apply`
+demo mode in Step 5.
+
+#### 3b. Show what you recommend and why
+
+Based on the intent, present the recommendation:
+
+| 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. |
+
+When explaining, reference the ASCII art from `cometchat-placement`
+("Visual reference — experience layouts") so the user can visualize it.
+
+Ask: "Does this sound right, or do you want a different approach?"
+Let them override.
+
+#### 3c. Ask where things should go
+
+**Show the user their actual project structure** — list the pages/routes
+you found in Step 1. Then ask placement-specific questions:
+
+**For Route placement (messaging, social):**
+> "I found these pages in your project:
+>   - /  (home)
+>   - /about
+>   - /products
+>   - /profile
+>
+> Where should the messages page live?"
+
+Default suggestion: `/messages`. Let user type a custom path.
+
+**For Drawer placement (marketplace):**
+> "Which page should have the 'Chat' button that opens the drawer?
+> I found these pages:
+>   - app/products/[id]/page.tsx
+>   - app/listings/page.tsx
+>   - app/profile/[id]/page.tsx
+>
+> Which one?"
+
+After they pick, read that page file. Look for existing buttons,
+actions, or interactive elements. Ask:
+> "I see a 'Contact Seller' button in ProductDetail.tsx at line 45.
+> Should I wire the chat drawer to that button, or add a new one?"
+
+**For Modal placement (SaaS):**
+> "Where should the 'Open chat' button go? I found these components
+> that look like navigation:
+>   - src/components/Navbar.tsx
+>   - src/components/Sidebar.tsx
+>
+> Which one should have the chat trigger?"
+
+**For Widget placement (support):**
+> "Should the widget appear on all pages, or only specific ones?"
+
+**For combinations (marketplace = drawer + route):**
+Ask both questions in sequence. The drawer and route are separate
+components wired into separate places.
+
+#### 3d. Detect and ask about authentication
+
+Read the project's `package.json` and source files. Look for auth:
+
+- `next-auth` / `@auth/core` → NextAuth
+- `@clerk/nextjs` / `@clerk/clerk-react` → Clerk
+- `@supabase/supabase-js` + auth usage → Supabase Auth
+- `firebase` / `firebase/auth` → Firebase Auth
+- `passport` → Passport.js
+- `jsonwebtoken` / `jose` → Custom JWT
+- None detected → no auth
+
+Report what you found and ask:
+
+If auth detected:
+> "I see you're using [NextAuth / Clerk / etc.]. Here's how CometChat
+> will work with it:
+>
+> - **Development (now):** I'll use CometChat's Auth Key for quick
+>   testing with pre-seeded users (cometchat-uid-1, uid-2, etc.)
+> - **Production (later):** Your server will call CometChat's REST API
+>   to generate per-user auth tokens. I can set this up now or later.
+>
+> Start with dev mode for now? You can upgrade to production auth
+> anytime by choosing 'Set up production auth' from the menu."
+
+If no auth detected:
+> "I don't see an authentication system in your project yet. For now,
+> I'll set up CometChat with a hardcoded test user (cometchat-uid-1).
+>
+> When you add auth later, run `/cometchat` again and choose
+> 'Set up production auth' to connect them."
+
+#### 3e. Ask about user mapping (if auth detected)
+
+If the user has auth AND wants to set up production mode now:
+
+> "How should your app's users map to CometChat users?
+>
+> 1. Use your existing user ID as the CometChat UID (simplest)
+> 2. Generate a separate CometChat UID and store it in your database
+> 3. Let me just set up dev mode for now
+>
+> Option 1 works if your user IDs are alphanumeric strings (no spaces,
+> no special characters). What does a typical user ID look like in
+> your system?"
+
+If they share an example, validate it's CometChat-compatible
+(alphanumeric, underscores, hyphens — no spaces or special chars).
+
+#### 3f. Confirm the plan
+
+**This is critical. Show EXACTLY what you'll do before doing it.**
+
+> "Here's what I'll create:
+>
+> **New files:**
+> - `app/providers/CometChatProvider.tsx` — initialization + login
+> - `app/messages/page.tsx` — inbox with conversation list + message view
+> - `app/components/ChatDrawer.tsx` — slide-out drawer for product page chat
+> - `.env.local` — CometChat credentials (already filled)
+>
+> **Files I'll modify:**
+> - `app/products/[id]/page.tsx` — add ChatDrawer import + trigger button
+> - `app/layout.tsx` — wrap children with CometChatProvider
+> - `app/components/Navbar.tsx` — add 'Messages' link
+>
+> **Files I will NOT touch:**
+> - `app/page.tsx` (your home page)
+> - Any other existing pages
+>
+> **Dependencies to install:**
+> - @cometchat/chat-sdk-javascript
+> - @cometchat/chat-uikit-react
+>
+> **Auth mode:** Development (Auth Key). Upgrade to production
+> with `/cometchat` → 'Set up production auth' when ready.
+>
+> Proceed? [y/n]"
+
+Wait for explicit confirmation. If the user says no or wants changes,
+go back to the relevant question and re-ask.
+
+### Step 4 — Reference pattern skills
+
+**All 13 skills are already loaded in your context** as `.claude/skills/`
+files. Do NOT use the `Skill()` tool — that's for a different system.
+Instead, simply read and follow the instructions in these skills:
+
+1. `cometchat-core` — initialization, provider, CSS, anti-patterns
+2. `cometchat-components` — component catalog, composition patterns
+3. Framework skill for the detected framework:
+   - `reactjs` → `cometchat-react-patterns`
+   - `nextjs` → `cometchat-nextjs-patterns`
+   - `react-router` → `cometchat-react-router-patterns`
+   - `astro` → `cometchat-astro-patterns`
+4. `cometchat-placement` — placement pattern for the chosen approach
+
+These are reference documents in your context, not tool calls.
+
+### Step 5 — Write the integration
+
+Execute the confirmed plan. For each file:
+
+1. **CometChatProvider** — follow the framework skill's provider pattern.
+   Use the correct env var prefix. Module-level `initialized` guard.
+   Mount at the level agreed in Step 3f.
+
+2. **Chat component(s)** — follow the placement skill's pattern.
+   Use the component compositions from the components skill.
+   If drawer/modal: connect to the specific user/group the user specified.
+
+3. **Wire into existing project** — READ each file before modifying:
+   - Router: add the route entry. Show the user the diff.
+   - Nav: add the link. Show the user the diff.
+   - Trigger page: add the drawer/modal import + trigger button. Show diff.
+
+4. **CSS import** — add once at the root level per framework conventions.
+
+5. **Environment variables** — write `.env` with the correct prefix.
+   If auth key is already there from the wizard, don't duplicate.
+
+6. **Install dependencies:**
+   ```bash
+   npm install @cometchat/chat-sdk-javascript @cometchat/chat-uikit-react
+   ```
+
+7. **Update config.json** — save all the choices in one call:
+   ```bash
+   npx @cometchat/skills-cli config save \
+     --intent "<intent>" \
+     --experience <n> \
+     --placement "<type>" \
+     --placement-path "<path>" \
+     --auth-mode "<mode>" --json
+   ```
+   Pass only the fields you have — `config save` accepts any subset.
+   This replaces the old 5-command `config set k v` chain. Omit
+   `--experience` in the AI-written path (it only applies to CLI-
+   generated experiences 1/2/3).
+
+8. **Record state so Phase B commands work — DO NOT SKIP.** Every
+   Phase B command (`info`, `status`, `doctor`, `verify`, `uninstall`,
+   `apply-theme`, `apply-feature`, `add-widget`, `add-user-mgmt`,
+   `production-auth`) reads `.cometchat/state.json` to know what the
+   integration looks like. Without this step, every one of them reports
+   "not integrated in this project" even though the code is there, and
+   the user can't iterate on their integration at all.
+
+   Pass every file you wrote (owned) and every existing file you patched:
+   ```bash
+   npx @cometchat/skills-cli state record \
+     --framework "<framework>" \
+     --placement "<type>" \
+     --placement-path "<path>" \
+     --auth-mode "<mode>" \
+     --files-owned "src/providers/CometChatProvider.tsx,src/components/ChatDrawer.tsx,src/pages/MessagesPage.tsx" \
+     --files-patched "src/main.tsx:v3/main.tsx,src/App.tsx:v3/App.tsx,src/components/Layout.tsx:v3/Layout.tsx" \
+     --json
+   ```
+
+   - `--files-owned` — comma-separated list of every NEW file you wrote
+     (the provider, drawer, inbox page, etc.). The CLI computes SHA-256
+     checksums for each so it can detect drift later.
+   - `--files-patched` — comma-separated `path:patch_id` pairs for every
+     EXISTING file you modified (main.tsx, App.tsx, Layout.tsx, nav, the
+     trigger page). `patch_id` can be any stable label — `v3/<filename>`
+     is a reasonable default.
+
+   If this call errors (CLI flag mismatch, missing --framework, etc.),
+   surface the error and retry with the correct flags rather than moving
+   on. A completed Phase A with a missing state.json is worse than a
+   visible error — the user discovers the breakage later when they try
+   to add a feature or run diagnostics.
+
+**Exception — "Just exploring" / demo mode:**
+```bash
+npx @cometchat/skills-cli apply --experience 1 --framework <detected>
+npx @cometchat/skills-cli verify --json
+npx @cometchat/skills-cli install
+```
+
+### Step 6 — Verify + show result
+
+Run a TypeScript check to verify the code compiles:
+```bash
+npx tsc --noEmit
+```
+
+**Do NOT run `npx @cometchat/skills-cli verify`** — it checks for
+CLI-generated `.cometchat/state.json` which doesn't exist in v3
+(AI writes code directly, not via `cometchat apply`). Use `tsc` instead.
+
+Surface any issues. Then:
+
+> "CometChat is integrated! Here's what was set up:
+>
+> - Messages page at /messages ✓
+> - Chat drawer on product page ✓
+> - Provider + CSS wired ✓
+> - Dependencies installed ✓
+>
+> Run `npm run dev` and try it out. Pre-seeded test users
+> (cometchat-uid-1 through uid-5) are ready to chat.
+>
+> What would you like to do next?"
+
+### Step 7 — Iteration menu
+
+Use `AskUserQuestion`:
+- **question:** "What would you like to do next?"
+- **header:** "Next step"
+- **multiSelect:** false
+- **options:**
+  1. label: "Customize look and feel (themes)", description: "Pick a preset (slack, whatsapp, imessage, discord, notion) or set brand colors."
+  2. label: "Add a feature", description: "Browse ~35 features — calls, reactions, polls, AI, and more."
+  3. label: "Customize a component", description: "Custom bubbles, headers, composer actions, details views — I'll read the docs and write it."
+  4. label: "Add a floating chat widget", description: "An overlay button + drawer on top of your existing app."
+  5. label: "Set up production auth", description: "Replace the dev Auth Key with a server-side token endpoint. Read `cometchat-production` skill."
+  6. label: "Set up user management", description: "Server endpoints for creating, updating, deleting CometChat users."
+  7. label: "Run diagnostics", description: "Check for drift, missing env vars, broken imports."
+  8. label: "I'm done", description: "Exit."
+
+For **component customization**: read `cometchat-components` + docs MCP,
+then write the customization code directly. This is pure AI work — no
+CLI command. Ask the user what they want to customize, read the relevant
+component's props from the catalog, and propose changes.
+
+For **production auth**: read the `cometchat-production` skill (already
+in your context). It's interactive — ask the user about their auth
+system and generate the server-side token endpoint for their framework.
+
+### Re-rendering the menu after each action
+
+After every Phase B action completes, you **MUST** re-invoke
+`AskUserQuestion` with the **exact same 8 options** listed above
+(same `question`, `header`, `multiSelect: false`, same option labels
+and descriptions — verbatim). This gives the user arrow-key selection
+in their terminal.
+
+**Do NOT:**
+- Present the options as a prose bullet list (`"What would you like to
+  do next?\n  - Customize the theme...\n  - Add calls..."`) — this
+  forces the user to type their answer, which is a worse UX.
+- Invent new options based on what the user just did (e.g. "Customize
+  theme to match Nestly's brand", "Swap the drawer header for a custom
+  view"). The 8 options above are the canonical set and don't change
+  between iterations.
+- Skip the menu and ask a freeform "What's next?" — always route
+  through `AskUserQuestion`.
+- Drop options or add new ones. The user expects the same 8 choices
+  every time, even if some are redundant with what they just did
+  (they may want to do the same kind of action twice, e.g. add two
+  features).
+
+The iteration loop is the whole point of Phase B. Re-rendering the
+canonical menu via `AskUserQuestion` after every action is how the
+user controls the session.
+
+## Hard rules
+
+- **Ask, don't assume.** Every integration decision should be confirmed.
+- Always run `detect` first. Do not assume the framework.
+- Always use `npx @cometchat/skills-cli` for CLI commands.
+- NEVER replace existing project files unless the user chose demo mode.
+- ALWAYS read existing files before modifying them.
+- ALWAYS show the plan (Step 3f) and get confirmation before writing.
+- For component names and props, use the `cometchat-components` skill
+  or docs MCP — never invent from training data.
+- After writing code, update `.cometchat/config.json` with the choices made.
+- **NEVER use the `Skill()` tool** to load CometChat skills. All 13
+  skills are already in your context as `.claude/skills/` files. Just
+  read and follow them directly.
+
+## Error handling
+
+If the CLI's `--json` output includes `human_message` / `suggestion` fields,
+show those to the user. Then show the raw `error` in parentheses for
+debuggability. If `retryable: false`, do NOT offer a retry.
+
+## Optional: docs MCP
+
+For deeper component customization:
+```
+claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp
+```
+
+Not required for integration or Phase B CLI flows.
+
+## Skill routing reference
+
+| Skill | When to load |
+|---|---|
+| `cometchat-core` | Always — before any integration code |
+| `cometchat-components` | Always — before writing component code |
+| `cometchat-placement` | When integrating — for placement patterns |
+| `cometchat-react-patterns` | framework = reactjs |
+| `cometchat-nextjs-patterns` | framework = nextjs |
+| `cometchat-react-router-patterns` | framework = react-router |
+| `cometchat-astro-patterns` | framework = astro |
+| `cometchat-theming` | When customizing themes |
+| `cometchat-features` | When adding features |
+| `cometchat-production` | When setting up production auth |
+| `cometchat-troubleshooting` | When diagnosing problems |