@cometchat/skills 4.4.1 → 5.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://code.claude.com/schemas/marketplace.json",
+  "name": "cometchat",
+  "description": "CometChat AI-coding skills (v5) — add real-time chat, voice/video calling and push to your app via your AI coding agent. Thin dispatcher + on-demand, verified UI Kit skills across React v7, Angular v5, React Native v5, Android v6 (Kotlin/Compose), iOS v5 (Swift/UIKit) and Flutter v6.",
+  "owner": {
+    "name": "CometChat",
+    "email": "support@cometchat.com"
+  },
+  "plugins": [
+    {
+      "name": "cometchat-skills",
+      "source": ".",
+      "skills": "./skills",
+      "strict": true,
+      "description": "UI Kit skills for integrating CometChat across React v7, Angular v5, React Native v5, Android v6 (Kotlin/Compose), iOS v5 (Swift/UIKit, SPM) and Flutter v6. The /cometchat dispatcher detects your project — web (React on Vite/Next/CRA, or Angular) or mobile (React Native/Expo, Android, iOS, Flutter) — and routes to task-shaped skills (core, components, placement, customization, features, calls, push, migration; plus platform patterns). Headless Calls SDK skills cover calling without a UI Kit. Run `/cometchat add chat to my app` to start. Thin entry with progressive disclosure. Backed by a deterministic CLI and a CI-gated verification pipeline: every skill is checked against its pinned kit (symbol catalog + compile fence), and several families also pass a live simulator/emulator smoke (per-family status in peers.yaml).",
+      "version": "5.0.0",
+      "author": {
+        "name": "CometChat"
+      },
+      "homepage": "https://github.com/cometchat/cometchat-skills",
+      "repository": "https://github.com/cometchat/cometchat-skills",
+      "license": "MIT",
+      "keywords": [
+        "chat",
+        "messaging",
+        "calls",
+        "react",
+        "vite",
+        "nextjs",
+        "ui-kit",
+        "cometchat",
+        "ai-agent",
+        "v7",
+        "ios",
+        "swift",
+        "uikit-ios",
+        "spm",
+        "xcode",
+        "v5",
+        "mobile",
+        "angular",
+        "react-native",
+        "android",
+        "android-sdk",
+        "flutter",
+        "js-calls",
+        "react-native-calls",
+        "android-calls",
+        "ios-calls",
+        "flutter-calls"
+      ],
+      "category": "communications"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

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

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# v5.0.0
+
+## New
+- Added CometChat UI Kit integration skills for six platforms: React v7, Angular v5, React Native v5, iOS v5 (Swift / SPM), Android v6 (Kotlin / Compose), and Flutter v6.
+- Added headless Calls SDK v5 skills for JavaScript, React Native, iOS, Android, and Flutter, letting you add voice and video calling without a UI Kit.
+- Added a guided onboarding journey that scopes each integration — framework, features, placement, and theming — before any code is generated.
+- Added task-shaped skills per platform (core, components, placement, customization, features, calls, push, and migration) that load on demand as the build needs them.
+- Added automatic connection to the first-party CometChat Docs MCP, with a guided-add step and a direct documentation-fetch fallback, so skills always read current documentation.
+
+## Breaking
+- **Full pack replacement, not an additive update.** v5 is a new generation of skills — new platform targets (React v7, Angular v5, React Native v5, iOS v5, Android v6, Flutter v6), new skill names, and a new layout. Same package name (`@cometchat/skills`), so every existing v4 user is affected.
+- **82 v4 skill folders were removed** (the React-UI-Kit-v6 generation and its siblings — e.g. `cometchat-core`, `cometchat-features`, `cometchat-theming`). Their v5 equivalents live under the per-platform, task-shaped names above.
+- **Naming shift:** `cometchat-<platform>-v5-*` now refers to the Calls/Chat SDK skills on several platforms (e.g. `cometchat-flutter-v5-*` is the Calls SDK). Update any tooling that referenced v4 skill names.
+- **`@cometchat/skills-cli` is now credentials-only (v3.0.0).** The code-writing subcommands from v2 were removed; the CLI now fetches dashboard credentials (App ID, Region, Auth Key) and toggles extensions / AI features. v4-generated `AGENTS.md`/rules files that invoke removed commands should be regenerated.
+
+## Removed
+- 82 v4 skill folders (the React-UI-Kit-v6 generation and its siblings).
+- `packages/skills-native`, `packages/registry`, the deploy templates, and most of `docs/`.
+- The v2 code-writing CLI subcommands (see Breaking).
+
+## Upgrading from v4
+- **`@cometchat/skills add` removes stale v4 skills:** before laying down the current family's v5 skills it deletes the skill folders earlier versions shipped (e.g. `cometchat-core`, `cometchat-features`, `cometchat-theming`; the full list is in `bin/legacy-skills.json`) and prints what it removed, so no stale v4 skills are left behind. Other v5 skills already in the directory (a second family, a calls peer, a `--global` install from another project) and your own skills, including any you named `cometchat-*`, are untouched.
+- If you installed v4 skills into a location this CLI does not manage, or pinned old skill names in an `AGENTS.md` / editor-rules file, remove those references by hand.
+- The companion CLI changed majors (`@cometchat/skills-cli` 2.x → 3.x) and is credentials-only; run `npx @cometchat/skills-cli@3 --help` for the current commands.
+
+## Enhancements
+- The Claude Code plugin (`/plugin marketplace add cometchat/cometchat-skills`) now carries the v5 pack and auto-connects the CometChat Docs MCP.
+- `add` detects native projects too (an Xcode project or workspace, an iOS `Package.swift`, Gradle, `pubspec.yaml`), not just JavaScript frameworks. `--family` forces a platform or adds a headless Calls SDK skill alongside a UI Kit.
+- Agent instruction files (`AGENTS.md`, `GEMINI.md`, `CONVENTIONS.md`, `.windsurfrules`, `.clinerules/cometchat.md`, `.github/copilot-instructions.md`) are written inside a `<!-- cometchat-skills:start/end -->` block, so your own content in those files is kept.
+- `add --global` installs Claude Code skills to `~/.claude/skills` and prints the `claude mcp add --scope user` command instead of writing a project `.mcp.json`; agents with no user-level location are skipped with a note.
+- Smaller installs: each skill folder now gets only the reference files and catalogs its family's skills cite.
+- `@cometchat/skills-cli` warns when `.cometchat/config.json` (which can hold your Auth Key) is already tracked by git, and removed v2 commands explain where that functionality moved.
+- Skills are checked against the pinned UI Kit and SDK: a symbol catalog guards against hallucinated APIs and a compile fence confirms the generated code builds. Several families additionally pass a live smoke run on a real simulator/emulator; the remaining families are being wired to it (per-family status in `peers.yaml`).
+
+## Fixes
+- None

package/README.md

@@ -1,199 +1,77 @@
-# cometchat-skills
+# @cometchat/skills (v5)
 
-**Add CometChat to any React, React Native, Angular, Android, Flutter, or iOS project through your AI coding agent.** Works with Claude Code, Cursor, Codex, VS Code Copilot, Windsurf, Cline, Kiro, and [30+ more agents](https://github.com/vercel-labs/skills).
+**Add CometChat chat & calling to your app through your AI coding agent.** Install the skills, then ask your agent *"add chat to my app"* — it has a short conversation with you (framework, intent, placement, credentials), then writes production-grade integration code into the files you already have.
 
-v4 takes an AI-first approach: your agent has a short conversation with you to understand your project and chat requirements, then writes production-grade integration code tailored to the files you already have. One slash — `/cometchat` — works for every supported framework, on web, mobile, and native.
+v5 is a **multi-platform** pack: a thin `cometchat` dispatcher + an `onboarding` journey + on-demand, verified skills for six UI Kits — **React v7 · Angular v5 · React Native v5 · iOS v5 · Android v6 · Flutter v6** — plus headless **Calls SDK v5** skills (JavaScript · React Native · iOS · Android · Flutter) and the **Android Chat SDK v5**. It's **docs-maximal** (builds from the official CometChat task guides and verifies against them) and **two-gate tested** (a deterministic reviewer + a black-box acceptance explorer).
 
-## Install
-
-```bash
-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, 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:
-
-```bash
-npx @cometchat/skills add --family web      # React / Next.js / React Router / Astro
-npx @cometchat/skills add --family native   # Expo / bare RN
-npx @cometchat/skills add --family angular  # Angular 12-15
-npx @cometchat/skills add --family android  # Native Android (V5 stable + V6 beta)
-npx @cometchat/skills add --family flutter  # Flutter (V5 stable + V6 beta)
-npx @cometchat/skills add --family ios      # Native iOS (V5 stable)
-npx @cometchat/skills add --family all      # install every published skill
-```
-
-### Two install shapes
+> **v5 ships on npm as `@cometchat/skills` (5.x).** It's a multi-platform rewrite of the v4 pack — same package name, new major. Upgrading? `add` removes the old v4 skills for you (see `CHANGELOG.md`).
 
-**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.
+## Install
 
 ```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.
+The installer **detects your project automatically** — React (Vite, Next.js, CRA, Astro, React Router), Angular, React Native / Expo, and native iOS (Xcode project), Android (Gradle) and Flutter (`pubspec.yaml`) — and installs the skills for your coding agent: **Claude Code by default**; target another with `--ide` (Cursor, Codex, Cline, Kiro, Replit Agent, Windsurf, Copilot, Gemini, …) or `--ide all`. Use `--family` to force a platform (e.g. from a monorepo root) or to add the headless SDK skills **alongside** a UI Kit — a second `add` never removes the first family's skills:
 
 ```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/
+npx @cometchat/skills add --family flutter      # force the Flutter v6 UI Kit skills
+npx @cometchat/skills add --family js-calls     # add headless JS Calls SDK skills next to the React ones
 ```
 
-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.
+Pin the agent as well (CI / Docker) with `--ide claude|cursor|codex|replit|…` (e.g. `--ide claude` → `.claude/skills/`). The full `--family` list is: `react · angular · react-native · ios · android · flutter` (UI Kits) and `android-sdk · react-native-calls · ios-calls · android-calls · flutter-calls · js-calls` (headless SDKs).
 
-> **Migrating from v3?** `npx @cometchat/skills-native add` still works (with a deprecation notice). New projects should use the unified command.
+## Use it
 
-Then in your IDE:
+After install, open your project in your agent and say:
 
 ```
-/cometchat add chat to my app
+add chat to my app
 ```
 
-Or add voice & video calling (new in v4.2):
+The `cometchat` dispatcher routes to `cometchat-onboarding` (discover → understand → plan → approve), then hands a scoped build directive to that platform's `-core` skill, pulling in the others as the approved plan needs them (components, placement, theming, features, calls, push). Iterate afterward — *"add reactions" · "switch to dark mode" · "add a details side panel" · "switch to server-minted auth tokens"* (production auth — server-minted `loginWithAuthToken` — is covered inside each family's `-core` credentials/lifecycle guidance, and by the dedicated `-production` skill where one exists).
 
-```
-/cometchat add voice and video calls to my app
-```
+## Credentials (dashboard CLI)
 
-When integrating chat, the dispatcher now asks **how** you want to customize (new in v4.3):
+A separate, dashboard-only CLI fetches your App ID / Region / Auth Key so you don't paste them by hand:
 
-```
-◉ Visually — drag-and-drop in browser
-○ In code — code-driven defaults
-```
-
-Pick **Visually** and the dispatcher opens CometChat's Visual Builder in your browser, waits while you customize colors / layout / features, then fetches the config and emits the integration into your existing app — no ZIP downloads, no manual file copying. Works for React, React Native, iOS, Android v6, and Flutter v6. Angular customers auto-route to the In-code path (Visual Builder doesn't ship Angular code yet).
-
-## What happens
-
-1. **Detects** your framework (React / Next.js / React Router / Astro / Expo / bare React Native / Angular / Android / Flutter / iOS), router, env prefix, existing auth system
-2. **Onboards** you to CometChat in the terminal — no browser round-trip. Signup, login, app creation all via the CLI.
-3. **Asks** what you're building (marketplace, SaaS, messaging, support, social, or just exploring) and **where** chat should live in your project — it reads your routes/screens, nav, and components before proposing a placement that fits (route+drawer for web, stack/tab/modal/bottom-sheet for RN, route/modal for Angular, Activity/Fragment for Android, navigation controller for iOS, route/modal sheet for Flutter)
-4. **Shows the plan** — exactly which files it will create, which it will modify, and which it will not touch — and waits for your approval
-5. **Writes** the provider, integration components, and route/screen/trigger wiring
-6. **Saves** credentials with the correct convention for your framework (`.env` with `VITE_` / `NEXT_PUBLIC_` / `PUBLIC_` / `EXPO_PUBLIC_` prefix on web/RN; `src/environments/environment.ts` on Angular; `local.properties` + `BuildConfig` on Android; `Secrets.swift` / `.xcconfig` on iOS; Dart const file or `--dart-define` on Flutter) and records your choices in `.cometchat/config.json`
-
-No templates, no experiences to pick — the agent writes real code that fits your app.
-
-## Supported frameworks
-
-| Framework | Chat | Voice & Video Calls | Visual Builder |
-|---|---|---|---|
-| React.js / Vite / CRA | ✅ | ✅ Ringing + Session | ✅ (v4.3) |
-| Next.js (App Router + Pages Router) | ✅ | ✅ Ringing + Session | ✅ (v4.3) |
-| React Router v6 / v7 | ✅ | ✅ Ringing + Session | ✅ (v4.3) |
-| Astro (React islands) | ✅ | ✅ Ringing + Session | ✅ (v4.3) |
-| Expo (managed + Expo Router) | ✅ | ✅ Ringing + Session | ✅ (v4.3) |
-| Bare React Native (CLI) | ✅ | ✅ Ringing + Session | ✅ (v4.3) |
-| Angular 12-15 | ✅ | ✅ Ringing + Session | ❌ (auto-falls back to In code) |
-| Android (V5 stable + V6 beta) | ✅ | ✅ Ringing + Session | ✅ V6 (v4.3) |
-| Flutter (V5 stable + V6 beta) | ✅ | ✅ Ringing + Session | ✅ V6 chat-only (v4.3) |
-| iOS (V5 stable) | ✅ | ✅ Ringing + Session | ⏸ Pending Xcode 26 vendor fix |
-
-**Calling modes:**
-- **Ringing** — kit-driven incoming/outgoing call surfaces, system-level VoIP push (CallKit on iOS, ConnectionService on Android, web push fallback on browsers). Production-grade for 1:1 + group calls.
-- **Session** — both peers join a shared `/meet/:sessionId` URL. No ringing. For embedded meetings, scheduled calls, support flows, broadcast use-cases.
-
-The dispatcher asks Ringing vs Session up front in Step 3.0.
-
-## After the first integration
-
-Re-run `/cometchat` anytime to pick from the iteration menu:
-
-- **Customize look & feel** — theme presets (slack / whatsapp / imessage / discord / notion) or your own brand color
-- **Add a feature** — 40+ features including calls, reactions, polls, AI smart replies, file sharing, presence
-- **Customize a component** — custom message bubbles, headers, composer actions, empty/loading states
-- **Add another placement** — floating widget (web), modal / bottom sheet / extra tab (RN)
-- **Set up production auth** — replace the dev Auth Key with a server-side token endpoint
-- **Set up user management** — server endpoints for creating/updating/deleting CometChat users
-- **Run diagnostics** — verify, drift detection, symptom-to-cause lookup
-
-React Native projects also get **Set up push notifications** (APNs + FCM end-to-end), **Set up testing** (Jest + RNTL + Detox/Maestro), and **Troubleshoot an issue** (Metro cache, pod install, privacy manifest) in the menu.
-
-## Recommended: CometChat Docs MCP
-
-For deeper component customization (custom views, SDK events, request builders), install the docs MCP:
-
-**Claude Code:**
 ```bash
-claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp
+npx @cometchat/skills-cli@3 auth login
+npx @cometchat/skills-cli@3 provision run
 ```
 
-**Cursor** (`.cursor/mcp.json`):
-```json
-{ "mcpServers": { "cometchat-docs": { "url": "https://www.cometchat.com/docs/mcp" } } }
-```
+The CLI is dashboard/API-only (`auth · provision · config · features`) — it never writes framework code; the skills do all detection, env-writing, and codegen.
 
-**Windsurf:**
-```json
-{ "mcpServers": { "cometchat-docs": { "type": "sse", "serverUrl": "https://www.cometchat.com/docs/mcp" } } }
-```
+## What's in the pack
 
-No authentication required. Not needed for the initial integration — the skill handles Phase A without it.
+A thin `cometchat` router + a `cometchat-onboarding` journey, then a **full skill set per platform**. Every UI-Kit family ships `core` (install · credentials · init→login→render · the golden-path chat surface) plus, as the platform needs them, `components · placement · customization · features · calls · push · migration` and platform extras (`patterns`, `production`, `testing`, `troubleshooting`, `events`, the Android `compose-*` / `kotlin-*` cohorts):
 
-## CLI (used by the agent under the hood)
+| Family | UI Kit package | Consumption |
+|---|---|---|
+| **React v7** | `@cometchat/chat-uikit-react@7` | drop-in UI Kit (+ Vite / Next.js / React Router / Astro glue) |
+| **Angular v5** | `@cometchat/chat-uikit-angular@5` | drop-in UI Kit |
+| **React Native v5** | `@cometchat/chat-uikit-react-native@5` | drop-in UI Kit (bare + Expo) |
+| **iOS v5** | `CometChatUIKitSwift` (SPM) | drop-in UI Kit (host-composed screens) |
+| **Android v6** | `chatuikit-{compose,kotlin}-android` | drop-in UI Kit (Compose + Kotlin/View) |
+| **Flutter v6** | `cometchat_chat_uikit ^6` | drop-in UI Kit |
+| **Calls SDK v5** (headless) | JS · React Native · iOS · Android · Flutter | standalone voice/video, no UI Kit |
+| **Chat SDK v5** (headless) | Android | headless messaging, no UI Kit |
 
-The skill calls `@cometchat/skills-cli` commands. You can also run them directly:
+## Compatibility
 
-```bash
-# Onboarding
-npx @cometchat/skills-cli auth signup       # create account, all in terminal
-npx @cometchat/skills-cli auth login        # sign in (masked password)
-npx @cometchat/skills-cli auth status       # check current session
-
-# App provisioning — web example
-npx @cometchat/skills-cli provision list    # list apps on your account
-npx @cometchat/skills-cli provision setup \
-  --name my-chat --region us --industry saas_businesses \
-  --framework reactjs                       # create app + write .env (VITE_ prefix) + save config
-
-# App provisioning — React Native example (Expo or bare RN)
-npx @cometchat/skills-cli provision setup \
-  --name my-rn-chat --region us --industry online_marketplaces \
-  --framework expo                          # writes EXPO_PUBLIC_* env vars
-# Use --framework react-native for bare RN (no env prefix; pair with react-native-dotenv)
-
-# Project introspection
-npx @cometchat/skills-cli detect            # framework, router, env prefix
-npx @cometchat/skills-cli config show       # read .cometchat/config.json
-npx @cometchat/skills-cli doctor            # diagnostics
-
-# See everything
-npx @cometchat/skills-cli --help
-```
+- **React v7** — `@cometchat/chat-uikit-react@7` (7.1.x) + `@cometchat/chat-sdk-javascript@4`; calls `@cometchat/calls-sdk-javascript@5`. React ≥ 18.
+- **Angular v5** — `@cometchat/chat-uikit-angular@5` (5.1–5.2) + Chat SDK v4 + Calls SDK v5. Angular 17–21.
+- **React Native v5** — `@cometchat/chat-uikit-react-native@5` + `@cometchat/chat-sdk-react-native@4` + `@cometchat/calls-sdk-react-native@5`.
+- **iOS v5** — `CometChatUIKitSwift` 5.1.x + `CometChatSDK` 4.1.x + `CometChatCallsSDK` 5.0.x (Swift Package Manager).
+- **Android v6** — `chatuikit-{compose,kotlin}-android` 6.0.x + `chat-sdk-android` 5.0.x + `calls-sdk-android` 5.0.x.
+- **Flutter v6** — `cometchat_chat_uikit ^6` (6.1.x) + `cometchat_calls_sdk ^5` (calls).
 
-## Prerequisites
+Exact pinned versions per family live in `peers.yaml` and each family's `SKILL.md` frontmatter (both ship in the package).
 
-- An AI coding agent ([Claude Code](https://claude.ai/code), [Cursor](https://cursor.sh), [Kiro](https://kiro.dev), VS Code Copilot, or any [skills.sh](https://skills.sh)-compatible agent)
-- Node.js 18+
-- React 18+ (React 19 fully supported)
+## Links
 
-No CometChat account required before starting — the skill walks you through signup from the terminal.
+- Docs: [cometchat.com/docs](https://www.cometchat.com/docs)
+- UI Kits: [`@cometchat/chat-uikit-react`](https://www.npmjs.com/package/@cometchat/chat-uikit-react) · [`-angular`](https://www.npmjs.com/package/@cometchat/chat-uikit-angular) · [`-react-native`](https://www.npmjs.com/package/@cometchat/chat-uikit-react-native)
 
 ## License
 

package/RULES.md

@@ -0,0 +1,114 @@
+# RULES — shared rules for the CometChat skills pack
+# (Ships INSIDE the pack. Every skill references this file; rules are never inlined per family.
+#  This is the shippable shared RULES.md — distinct from the factory's own references/RULES.md,
+#  which governs how skills are AUTHORED. Keep them in sync when a rule changes.)
+
+## Code safety
+- APPEND, never REPLACE the user's code. Additive diffs only. Never delete a competing SDK's files/deps without an explicit, waited-for confirmation.
+- No speculative scaffolding; reuse the developer's existing primitives; golden-path defaults over prop sprawl.
+
+## Platform / package integrity
+- One package per platform — never cross them:
+  react → @cometchat/chat-uikit-react · angular → @cometchat/chat-uikit-angular ·
+  react-native → @cometchat/chat-uikit-react-native · flutter → cometchat_chat_uikit ·
+  android → Kotlin/Compose (V6) or Java/Views (V5) · ios → Swift.
+- Web UI Kit code never goes into RN and vice-versa (CSS/`<a href>`/`document.*` vs native deps).
+- NEVER mix SDK majors (V5/V6/V7) in one skill — different packages, primitives, theme systems.
+
+## version_conflict — STOP gate
+- When detection shows a version_conflict — a UI Kit major other than the one this family targets (React v7, Angular v5, RN v5, iOS v5, Android v6, Flutter v6; see `peers.yaml`), or two majors at once — STOP. Surface the detail, reconcile (upgrade kit / load matching-version skills / remove unwanted cohort), re-read. Not a warning. (Detection = `npx @cometchat/skills detect --json`, the pack's offline probe and the authority; else the skill's own repo read. Never the dashboard CLI.)
+
+## Credentials & secrets
+- Auth key is dev-only client-side; teach server-side token exchange for production. Never hardcode; never echo the auth key to stdout.
+- **Never provision a NEW CometChat app or account on the user's behalf.** Reuse the existing configured app (`.cometchat/config.json` / env App ID); if unknown, `provision list` and ASK which EXISTING app to use (ask + wait). Create a new app ONLY on an explicit user request, confirming the name first — an integration run must not silently spawn apps.
+- **The login UID must exist in the app — and never suggest a legacy/guessed sample UID.** `login(uid)` does not create users. Do NOT offer `superhero1`/`superhero1..5` (or any other remembered "classic sample" set) — they aren't seeded in modern apps and mislead users. When you ASK which UID to use, do not fabricate candidates from memory; the only tentative suggestion allowed is `cometchat-uid-1`, labelled "if this is a fresh app." Prefer the user's own UID / the Dashboard Users tab.
+- Env conventions: Vite `VITE_`, Next `NEXT_PUBLIC_` (.env.local), Astro `PUBLIC_`, Expo `EXPO_PUBLIC_`, RN bare `COMETCHAT_`, Angular `environment.ts` object, Android `app/src/main/assets/cometchat-settings.json` for INIT credentials (build-time extras only: `local.properties`→`BuildConfig`), Flutter const/`--dart-define`, iOS `Secrets.swift`/xcconfig.
+
+## Ordering invariants
+- `init() → login() → render` — never render UI Kit components before init+login resolve.
+- **Init via `initFromSettings` (telemetry attribution).** Use `CometChatUIKit.initFromSettings(...)` (UI Kit) — or `CometChat.initFromSettings(...)` for a headless SDK build. **The signature is per-platform:** web/JS pass a `CometChatSettings` object; **Android passes `(context, CallbackListener<String>)`** and the settings come from `app/src/main/assets/cometchat-settings.json` (there is no `CometChatSettings` type on Android). Either way, NOT the classic builder `UIKitSettingsBuilder`/`init()`. It persists `integrationSource="ai-agent"` (and routes the Calls SDK). **Web/JS only** — `settings` is a `CometChatSettings` object: `{ appId, region, credentials:{authKey}, chatSDK:{presenceSubscription:{type:"ALL_USERS"}} }`. **Android does NOT use this shape**: its `assets/cometchat-settings.json` uses `uiKit.subscribePresenceForAllUsers`.
+  - **Calls SDK build (any framework) → `CometChatCalls.initFromSettings(settings)` by DEFAULT — the SAME ai-agent attribution** (`integrationSource="ai-agent"`), mirroring `CometChatUIKit.initFromSettings` / `CometChat.initFromSettings` above. NOT the publicly-documented `CometChatCalls.init(appId, region)` — that is the FALLBACK ONLY. `CometChatCalls.initFromSettings` is INTENTIONALLY undocumented (ai-agent-only / `@nodoc`, like `CometChatUIKit.initFromSettings`), so its settings shape is baked in the calls skill's `references/docs-map.md`. Applies to EVERY framework's calls skill going forward (React, Angular, and future React Native / Flutter / iOS / Android calls families). (AUDIT-175, sibling of AUDIT-084.)
+- Web UI Kit: theme/CSS variables imported ONCE at app root.
+- **Follow-the-OS theming is a CORE-surface obligation, not a customization add-on, on any platform whose kit does NOT follow the OS by itself.** When the plan's theming answer is "Auto — follow OS" (the fresh-app default), the family's **core** golden path MUST emit whatever host wiring makes the kit track the device light/dark — the "Auto" default is a broken promise otherwise. It differs per platform (see onboarding `references/platforms.md` for the authoritative per-platform table): **web/React** syncs `theme` ↔ `prefers-color-scheme` (AUDIT-004); **React Native** supplies BOTH `light` and `dark` to the provider / `mode:"auto"` (AUDIT-211); **Android Compose** wraps the kit UI in `CometChatTheme(colorScheme = if (isSystemInDarkTheme()) darkColorScheme() else lightColorScheme()){}` (AUDIT-217) — with no wrapper it renders light defaults and ignores the OS. **Truly-automatic platforms (iOS; Android Views via `CometChatTheme.DayNight`) need NO host code — do not add any.** The rule: the CORE skill owns the bare follow-OS wiring; `customization` owns brand tokens/typography on top. A core skill that recommends "Auto" but omits the wiring is under-delivering its own default.
+
+## Layout / sizing — the reflow-free surface (give the UI real dimensions or it collapses/reflows)
+- UI Kit components are `height:100%`/flex-fill: they take the size of their parent, and they ship their OWN loading/empty state (`loadingView`/`emptyView`). A surface that looks broken is a HOST **container-sizing** defect, not a kit bug — one root cause (a **content-driven** box the kit then fills), two failure modes: **static collapse** (a ~0px sliver / top-left cram) and **load-transition reflow** (the surface is SMALL while the conversation list loads, then GROWS to full size — the box expands WITH content instead of being pinned; looks broken and can misplace the UI).
+- **PIN the box independent of content so it's full-size from frame 1 and the loading→loaded swap causes no shift.** Four invariants (the pack's `references/layout.md` is the single source of truth for the web recipe):
+  - **Prepare the ancestor chain** — `html, body, #root { height:100%; margin:0 }` so a full-height container isn't sized against `0`. A bare app has none → collapse.
+  - **Pin a content-INDEPENDENT height** — full-app → `100dvh`; embedded → a fixed height (e.g. `600px`) or a sized grid/flex cell. **Never `min-height`/`auto`** on the surface box (it grows with content = the reflow).
+  - **Size the panes** — each column/pane `height:100%; min-width:0; min-height:0; overflow:hidden` so content **scrolls internally** and never spills; sizing the root alone leaves the kit filling nothing. Give the app container `overflow:hidden`.
+  - **Let the kit's own loading state fill the pinned box** — render `loadingView`/`emptyView` INSIDE the pinned surface so it's full-size before content loads; do NOT gate the whole surface behind your own placeholder→chat swap (that IS the reflow).
+  - (Also: no `transform`/`filter`/`backdrop-filter` on an ancestor — it clips the kit's `position:fixed` overlays.)
+- **Full-page chat: NEUTRALIZE the scaffold's boilerplate CSS first.** A fresh Vite/CRA/Next app ships template CSS that centers + width-caps + pads the root — `#root { max-width:1280px; margin:0 auto; padding:2rem; text-align:center }` + `body { display:flex; place-items:center }`. Full-height chat dropped into that renders as a centered, ~1280px, padded box with side gutters, and message bubbles/overlays clip off the edge ("exceeding the viewport"). Reset it before the chat CSS: `html, body, #root { height:100%; margin:0; padding:0 }` + `#root { max-width:none; text-align:left; display:block }` + remove `body{place-items:center}`. Find the platform's equivalent scaffold cruft (Next `globals.css`, CRA `App.css`) and clear it.
+
+## Localization & CSS isolation
+- **Never render a raw localization key as a label.** The kit localizes via `CometChatProvider` (it auto-wires `LocaleProvider`); a snake_case token in the UI (e.g. `group_info`, `add_members`) is a **missing/wrong key** — `getLocalizedString` returns the key on a miss. Use the kit component or `useLocale().getLocalizedString(key)`, never `<x>group_info</x>`. (v6→v7 changed some keys; a stale key falls through to the raw string.)
+- **Don't let the host app's global CSS leak into the `.cometchat` subtree.** The kit's layout is correct by default (conversations header is fixed `flex-shrink:0`, the list is `flex:1`, item titles are left-aligned). A global `text-align`/flex-centering/`flex`/reset (or Tailwind base) on the kit's ancestors mis-aligns (centered list names) or mis-sizes (expanding header) kit internals. Scope global styles away from `.cometchat`; never override the internal BEM classes — customize via `--cometchat-*` vars + view slots.
+- **To differentiate a NESTED kit surface, override THAT surface's OWN background variable — a wrapper background is not enough.** A kit sub-surface that paints an **opaque** background from its own token (e.g. `.cometchat-message-list` paints `--cometchat-message-list-bg`, default `--cometchat-background-color-03`) COVERS any background set on a wrapping `div` — the wrapper bg never shows. Canonical case: the **thread panel** — its header/composer paint their own opaque `--cometchat-background-color-01`, but the thread message list paints `-03` (same as the main list), so the thread list looks undifferentiated even after you give the thread wrapper a background. **Fix:** scope the list's OWN token on the thread wrapper — `.cc-thread-panel { --cometchat-message-list-bg: var(--cometchat-background-color-01); }` (cascades to the list, matches the thread header/composer, differs from the main list's `-03`; verified vs 7.1.0). Generalizes to any opaque sub-surface — override its background variable via a scoped ancestor, never the internal BEM class. Depth: your platform's `customization` skill. (AUDIT-020/024.)
+- **A per-theme override must select the element the theme attribute is ON — not a descendant.** `CometChatProvider` renders ONE wrapper — `<div data-theme="light|dark" class="cometchat">` — so `data-theme` and `.cometchat` are the SAME element. A per-theme brand override is `.cometchat[data-theme="dark"] { … }` (same element); `[data-theme="dark"] .cometchat { … }` targets a `.cometchat` NESTED inside a `[data-theme]` ancestor, which does not exist → it matches nothing and silently does nothing. To retint a kit INTERNAL per theme use `[data-theme="dark"] .cometchat-<element-class> { … }` (the wrapper as ancestor, a kit class as the descendant — the kit's own convention). Verified vs 7.1.0. (AUDIT-025.)
+
+## Clarification contract
+- Where a skill must ask, it ASKS and WAITS — never infers, never defaults, even in auto/approval mode. On agents without a question primitive, render a numbered list and wait; map by value/label, accept free-text; if headless, STOP and emit the question.
+- **CURATE large choice sets — don't dump a long list.** When the options are many (e.g. many CometChat apps to pick from), show the **top 3 most-relevant as selectable options + a "Show all N" option**, with the free-text/"Other" answer as the manual/paste fallback — expand to the full list only if the user picks "Show all." A wall of 20+ rows as the prompt is a UX regression.
+
+## Truthful output
+- Every `CometChat*` symbol must exist in the target family+major catalog. Every claimed feature must exist in `features.json`. Read real signatures from live docs; compile-verify before "done". Treat live docs as source of truth for what's new.
+- **A baked "closed list" (model FIELD sets, enum values, method inventories) and a NEGATIVE-capability claim ("no X on this platform / that symbol is invented") are the two easiest things to get WRONG, and both are asserted as FACT — so both must be RE-PROBED against the SHIPPED source of the exact target major every authoring pass, never carried forward from an earlier probe.** A closed list that isn't (undercounts a real field) makes a real API look phantom — worse than no list; the correct fix for a docs PHANTOM field is the shipped list, not a hand-counted subset. A negative claim ("Flutter has no local screen share") must be re-checked against the BARREL/exports before it is stated — a symbol the barrel reaches that an emit can call COMPILES, so "invented"/"impossible" is falsifiable. Docs can LAG the shipped SDK (a method ships before its page); when source and docs disagree on existence, source wins for "does it compile," and note the docs lag. (AUDIT-231; mirrors AUDIT-230's signature-drift class — same lesson at field-set + capability-absence granularity.)
+- **Canonical doc channel = a 3-TIER ladder: (1) the CometChat docs MCP, auto-connected → (2) guide the user to add it → (3) plain fetch.** Try them in order, and never HARD-STOP.
+  - **Tier 1 — MCP, auto-connected.** The pack ships the first-party docs MCP in its plugin manifest (plugin-root `.mcp.json` → server `cometchat-docs` = `https://mcp.cometchat.com/mcp`), so for a plugin install it connects automatically (plugin-scoped servers need no trust prompt). PREFER its tools — `search_cometchat_docs` · `fetch_cometchat_doc_page` · `get_cometchat_implementation_bundle` (the bundle tool is **NON-AUTHORITATIVE**: curated static recipes that can lag live docs, so prefer `fetch_cometchat_doc_page` and reconcile any bundle against it).
+  - **Tier 2 — if the MCP is NOT connected, tell the user and help them add it** (one line, never masked): `claude mcp add --transport http cometchat-docs https://mcp.cometchat.com/mcp` — or reinstall/enable the plugin (`/plugin`, then `/mcp` to reconnect) — then retry. Verify with `claude mcp list`.
+  - **Tier 3 — if it still won't connect, fall back to a plain fetch** of `DOCS_BASE`/`SDK_DOCS_BASE` + path + `.md`. This tier keeps every skill working with NO MCP at all, so never require the MCP and never hardcode a docs host.
+  - The `<path>` catalog in each family's `references/docs-map.md` stays the source of truth for WHICH page; the tier is only HOW to read it. The MCP tracks whatever docs environment it points at (production by default; a preview when repointed), so tier 1 also subsumes the `DOCS_BASE` env-swap.
+- **If asked to "fix" something, check the live doc first and say where the fix belongs.** When a defect is really a **feature-correctness/behavior gap in the CometChat docs** (the doc is wrong or missing it), tell the user plainly it's a **docs** issue to report to CometChat — don't silently hand-roll a permanent local workaround for what the docs should carry. If the live doc is already correct, fix the integration to match it.
+- **Compile hygiene — import the `CometChat` SDK namespace only when used as a VALUE.** It ships as an ambient global, so `CometChat.User`/`.Group`/`.BaseMessage` resolve as types with NO import. Import it only for value use (`instanceof CometChat.User`, `CometChat.CometChatHelper.*`, `new CometChat.*RequestBuilder`). A type-only import trips strict TS (`noUnusedLocals`+`verbatimModuleSyntax`, the Vite React-TS defaults) → `TS6133`; `import type` does not fix it. (AUDIT-007.)
+
+## Completeness & determinism
+- Emit a contracted feature/component's FULL `contracts.json` min_capabilities every time (same minimum on every prompt) — no random subset, no unrequested scope. Least-code = use the drop-in that already provides them; the minimum set itself is fixed.
+
+- **A family that cannot be resolved is REPORTED, never guessed.** No "nearest family" fallback, no
+  default-to-react: installing one framework's skills into another's project hands the agent APIs
+  that do not exist there, and it looks like success. Refuse, name what was detected and what is
+  shippable, write nothing, exit non-zero (AUDIT-105).
+
+## Fetch discipline — docs are the source of truth (never `.d.ts`)
+> Paths below are **per-family**: use YOUR family's core skill — `cometchat-react-v7-core` or `cometchat-angular-v5-core` (and the same shape for any family added later). Every family ships its own `references/docs-map.md` with its own `DOCS_BASE`.
+- The hot path (install + `init → login → render` + the drop-in props) is BAKED in your family's **`-core`** skill — do NOT fetch it.
+- For anything else (exhaustive props, view-slots, long-tail components, theming tokens, feature steps) fetch the docs **`.md` twin**: append `.md` to the page URL — clean Markdown + the "AI Integration Quick Reference" JSON. Route with your family's **`-core/references/docs-map.md`**.
+- Fallback order: `.md` twin → if it 404s, the HTML docs page (same URL, no `.md`) → **NEVER** `node_modules/**/*.d.ts`, and never training memory.
+- Versions, **migrations**, dashboard paths and best-practices change fast: always fetch, never answer from memory. **A migration is a fetch-heavy task, not a baked-only one** — the skill's baked breaking-change map is a *closed list* (what was removed/renamed); the *shapes* (a target component's inputs/outputs, an SDK method's signature) still come from docs. Each family's `docs-map.md` carries a migration/upgrade row; the baked map naming a symbol is not a substitute for fetching what replaces it.
+- **If the bundle is the only place left to look, that is a SKILL defect — say so.** Reading `node_modules` is not a permitted last resort; it is a signal that the skill gave you no route. State plainly which lookup was unroutable (so it can be fixed) rather than silently reverse-engineering the shipped bundle — the bundle shows a symbol's shape but never whether it is the *sanctioned* API, and an internal-only `declare class` is indistinguishable from an exported one.
+- **Manifest / native-platform symbols are NOT docs symbols — verify them against the AAR/framework artifact per COHORT, and prefer auto-merge.** Manifest `<activity>`/`<provider>`/`<service>` fully-qualified class names, package namespaces, and permission strings are not in the docs `.md` twins. When a mobile skill bakes one, it MUST match the fully-qualified name in the **installed artifact's manifest** for that cohort (Android: the AAR `AndroidManifest.xml`), and it MUST NOT carry a name from a different cohort or an older major. Most kit-owned Activities are **already declared in the AAR manifest and merge in automatically** — the default guidance is "you do NOT declare these; they auto-merge," and any manual `<activity>` example is a cohort-split, artifact-verified fallback, never a copy of a prior major's namespace. (A v6 Android kit renamed `com.cometchat.chatuikit.*` → `com.cometchat.uikit.{compose,kotlin}.*`; baking the old `com.cometchat.chatuikit.calling.CometChatCallActivity` is exactly this class of defect — AUDIT-218.)
+
+## Default-on affordances — wire or hide (never dead-end)
+- A drop-in can render a live-looking control **by default** that is **inert/partial until stitched** (callback + companion panel/sibling component, sometimes a Dashboard toggle). The UI Kit gives the trigger; the host must supply the destination.
+- When fetching a component's props, classify every default-visible affordance: works standalone, or needs wiring? If it needs wiring, the emitted code MUST either wire the destination or hide the trigger. Never leave a default-on affordance dead-ending. `enablement:"default"` ≠ "no wiring."
+- **Wire the FULL round-trip, not just the entry.** When you open/mount a companion component in response to a trigger, wire its COMPLETE interaction — the way IN *and* the way OUT (its own back/close/cancel callback), plus any result/confirm path. A component you toggle open owns state you must also toggle closed: its built-in back/close button fires a callback that does nothing unless YOU handle it. Before shipping, check every rendered control of the companion (back, close, cancel, result-click, submit) has a wired handler — an opened panel whose back button dead-ends is the SAME defect as an unwired trigger. Concretely, `CometChatSearch` (opened from `onSearchBarClicked`) renders a back button by default (`hideBackButton` default `false`) → you MUST wire **`onBack`** to close it (same state that opened it), and **`onConversationClicked`/`onMessageClicked`** to close it + select the result. Opening it without `onBack` is a broken product (AUDIT-017).
+- Known v7 cases (`features.json` `needs_stitching`): `CometChatConversations` `showSearchBar` (default `true`, client-side name filter only) → `onSearchBarClicked` → render `CometChatSearch` **in the conversations list column** (over the list; the message pane stays — NOT a full-screen takeover; full-screen only on mobile's single pane) **+ wire its `onBack` (close) and `onConversationClicked`/`onMessageClicked` (close + select)**, or `showSearchBar={false}`; `CometChatMessageList` thread-reply indicator → `onThreadRepliesClick` + thread panel (**+ the panel's `CometChatThreadHeader` close button**) or `hideReplyInThreadOption`. (Wire the destination, its EXIT, AND put it in the right place — a full-screen search opened from a sidebar bar is a placement defect, AUDIT-014; a search with no `onBack` is a round-trip defect, AUDIT-017.)
+- **Selection has THREE obligations, and every panel closes (AUDIT-079).** When you compose a selector (conversations/users/groups tabs) or a list ↔ a message pane, selecting an item has THREE jobs — doing only the first is a dead-end: (1) **render** the target pane; (2) **REFLECT** the selection in the list so the open row highlights — pass the built-in active-item prop: `CometChatConversations activeConversation` · `CometChatUsers activeUser` · `CometChatGroups activeGroup` (real v7 props; without them there's no active state and the user can't tell what's selected); (3) make EVERY side panel you open **closeable** — the round-trip above applies to the **user/group details** panel too (`CometChatGroupMembers` renders a header back button whose `onBack` is the host's to wire; a host-composed user-details panel adds its own close), not just search/thread. If a selection opens a panel, a close must lead back out of it.
+- **Two searches, two SCOPES — never both global (AUDIT-041).** `CometChatConversations onSearchBarClicked` → a **GLOBAL** `CometChatSearch` (all conversations + messages, **NO `uid`/`guid`**) over the list column; `CometChatMessageHeader onSearchOptionClicked` (`showSearchOption` default `true`) → a **SCOPED** `CometChatSearch` passing the OPEN chat's **`uid` (1:1) / `guid` (group)** so it searches ONLY that conversation, in the side panel. Emitting the header search WITHOUT `uid`/`guid` (in-chat search returns whole-app results) is a defect. Docs already cover it (`components/search` → "Scoped Search", `uid`/`guid`); the rule is spelled out here so the scope isn't dropped from dense prose.
+- **A capability-gated surface must be GATED ON REAL AVAILABILITY — a comment is not a gate, and a fallbackView is not always a fix (AUDIT-162).** Some drop-ins render the kit's raw "OOPS! Looks like something went wrong" screen when a backend capability/plan is unavailable — e.g. `CometChatCallLogs` when call-logs aren't in the plan. **Verified live: `CometChatCallLogs` renders that from its OWN INTERNAL error state WITHOUT throwing** — so an outer `CometChatErrorBoundary`/`fallbackView` never fires and CANNOT override it (its `onError` may also not fire). So the emitted code MUST **actually gate the trigger** on an availability flag (omit/disable the tab/route — a REAL condition in code, NOT a `// omit when …` TODO comment; a comment-only gate ships the dead-end). **A `fallbackView` only helps if the component THROWS — verify per component; do NOT assume it does.** For a component that renders its own internal error state (proven: `CometChatCallLogs`), the ONLY reliable protection is the availability gate. **The gate must key on real AVAILABILITY, not a proxy:** a feature being ENABLED (e.g. calling via `uiKit:{callsSDK:{}}`, which makes the header Voice/Video buttons appear) is necessary to OFFER the surface but is **not sufficient** for it to render — call-logs availability is a SEPARATE plan gate (proven live). Confirm availability with a one-time SDK probe you own (`CallLogRequestBuilder → fetchNext()`) or the known plan; default the surface OFF. Emitting an always-mounted `CometChatCallLogs` (or any such surface) with no real availability gate is a dead-affordance defect.
+  - **This rule is FAMILY-WIDE, and the SAME "OOPS!" screen has a SECOND root cause: SDK-readiness, not just plan (AUDIT-163, Angular).** On Angular, `<cometchat-call-logs>` mounted unguarded renders the identical "OOPS! / Retry" screen from a *client-side crash* — `[CometChatCallLogs] Error: TypeError: Cannot read properties of null (reading 'CallLogRequestBuilder')` — because its `ngOnInit` synchronously does `new CometChatUIKitCalls.CallLogRequestBuilder()` while `CometChatUIKitCalls` is still `null` (the Calls SDK is lazy-loaded via `loadCallsSDK().then(...)` and populates late; **Retry does NOT recover** and **no network request is made** — so this is NOT the plan gate). The fix here is a **readiness gate**, distinct from the availability probe — but **`callingReady` ALONE is NOT sufficient (proven live):** `CometChatUIKit.callingReady` defaults to a pre-resolved `Promise.resolve()` and even after `initCalling()` runs the lazily-loaded `CometChatUIKitCalls` namespace can still be `null`. Gate on the NAMESPACE actually being populated: `callingReady.then(() => callsReady.set(!!CometChatUIKitCalls))`, then `*ngIf="callsReady()"`. So a call-logs/`callsSDK`-backed surface needs BOTH gates conceptually — **readiness** (SDK loaded) AND **availability** (in plan) — before it may mount; default it OFF and reveal it only when its gate(s) pass. Every family that ships a lazily-loaded calls surface (React, Angular, RN, …) inherits this — do not treat it as a React-only or plan-only concern. (STOPGAP in the skills until the kit component awaits `getCometChatCalls()`/`callingReady` itself — filed upstream; the call-logs docs page omits the prerequisite — DOCS-BACKLOG.)
+
+## Reuse built-in props/callbacks/slots — UI Kit first, SDK fallback, hand-roll last
+- **The order for EVERY feature: UI Kit component → SDK method → (only if neither) hand-roll.** First check if the UI Kit has a component/prop for the feature and use it. If the UI Kit has NO component for it (AI agents, campaigns, advanced/AI moderation, bots, webhooks, transient messages, low-level presence, …), drop to the **JavaScript Chat SDK** and call its method directly — the SDK library is already installed under the UI Kit. Hand-roll ONLY when neither the UI Kit nor the SDK exposes it. Never re-implement a feature that already exists in either.
+- Before adding custom UI (buttons, handlers, panels) for a requested capability, map the affordance to an existing prop on the component (callbacks, `show*/hide*`, view slots). Don't scatter your own buttons when a built-in trigger exists.
+- **Render custom controls in the component's OWN view slot — NEVER as a sibling on top.** A search icon / action button / banner / custom header goes INSIDE the component via its slot, not above or beside it: Conversations header → `headerView` (search bar → `searchView`); MessageHeader actions → `trailingView` / `auxiliaryButtonView`; MessageList banner → `headerView` / `footerView`; Composer extra button → `auxiliaryButtonView` / `headerView`. Rendering search "on top of" the conversation list instead of in its `headerView` (or over the message header instead of its `trailingView`) is a defect. Baked slot map: your platform's `core` skill -> `references/component-props.md`.
+- **A FULL-REPLACE slot replaces everything it covers — re-render what you keep (AUDIT-083).** A list's `headerView` replaces the ENTIRE default header, including the "Chats"/"Groups"/"Users" **title**. So to add a "New chat"/"Create group" button, render the title AND your button together inside `headerView` — a bare button there silently drops the title. Use `useLocale().getLocalizedString(...)` for the title.
+- **A form the kit ships NO component for must cover its FULL domain (AUDIT-081).** Host-built forms (e.g. create-group — v7 has no `CometChatCreateGroup` component) include EVERY variant from the SDK: a create-group form offers Public · Private · **Password**-protected (with a password field), not just public/private (`CometChat.GROUP_TYPE.PASSWORD` + `new CometChat.Group(guid, name, type, password)`).
+- Discovery order: (1) the baked hot-path props in your family's **`-core`** skill; (2) the component's **`.md` twin** — its prop table + "AI Integration Quick Reference" JSON (append `.md` to the docs URL; route via your family's **`-core/references/docs-map.md`**); (3) if the UI Kit has NO component for the feature → the **SDK method** from the SDK docs (`docs-map.md` → SDK docs: the `llms.txt` index + the page's AI-Integration-Quick-Reference accordion); (4) only hand-roll when NEITHER the UI Kit nor the SDK has it. **Never read `node_modules` `.d.ts`; never guess from memory.**
+- Use these instead of custom buttons: `CometChatMessageHeader` `onItemClick` → open user/group profile on header click; `CometChatMessageHeader` search button (`showSearchOption` default `true`) + `onSearchOptionClicked` → open message search; `CometChatConversations` `onSearchBarClicked` → open conversation search; `CometChatMessageList` `onThreadRepliesClick` → open thread panel.
+- **Scope the conversation list to the request (reuse the built-in request-builder prop — don't hand-roll a filter).** A **1:1 / DM-only** ask must not show the app's seeded groups: pass `CometChatConversations conversationsRequestBuilder={new CometChat.ConversationsRequestBuilder().setConversationType("user")}` (groups-only → `"group"`) — the builder INSTANCE, not `.build()` (the kit builds it; passing the built object breaks the list). Don't add a Groups tab to a 1:1 app. A generic unscoped "add chat" keeps both types. (AUDIT-038)
+
+## Responsive / mobile-first layout — collapse to one screen at a time (never dead-end mobile)
+- Any layout that composes more than one pane (list + message view, list + detail/thread, a full-app placement) MUST collapse to ONE screen at a time on small viewports. A fixed side-by-side layout that squashes/overflows on a phone is a defect — the same class as a dead-ending affordance (§ wire-or-hide): it dead-ends the mobile user.
+- There is NO built-in responsive shell (no `WithMessages`/`CometChatUI` in v7); the host composes it. Mobile = a navigation stack: conversation list → tap a conversation → the message view REPLACES the list full-screen with a back control → tap the header → the details/thread view REPLACES the message view. The same selection state renders side-by-side on wide viewports.
+- Reuse the built-in back affordance, don't hand-roll it: `CometChatMessageHeader` ships `hideBackButton` (default `false`) + `onBack()`. On mobile wire `onBack` to clear the selection (pop to the list); on wide set `hideBackButton` (the list is always present).
+- Web recipe: drive the visible pane from selection state + `window.matchMedia("(max-width: 768px)")` (SSR-guarded, with a `change` listener). Panes need explicit height; never transition them with `transform` on a chat wrapper (clips the kit's `position:fixed` overlays — animate `right`/`left`/width). Native (RN/Flutter): stack navigation, one screen per route. Depth + recipe live in your platform's `placement` skill.
+
+## The CLI is a dashboard/API client only (loaded on demand)
+- **Env-writing and codegen are the SKILL's job** — done by reading your repo and emitting code, never a CLI command. **Detection** is `npx @cometchat/skills detect --json` (the skills pack's offline probe: framework, UI Kit + `version_conflict`, `existing_cometchat` = a CometChat UI Kit/SDK dependency is present), topped up by the skill's own repo read. The dashboard CLI (`@cometchat/skills-cli`, loaded on demand) does DASHBOARD/API operations only: `auth` (dashboard login) + `provision` (fetch an app's App ID/Region/Auth Key) + `config` + **`features`** (enable/disable dashboard **extensions + AI** for an app — `features list`/`enable <id>`/`disable <id>`). It writes no code and knows no framework (see your platform's `core` skill -> `references/setup-credentials.md`). For a feature: the CLI `features enable <id>` flips the DASHBOARD toggle; the SKILL wires the component/prop in code. Installing/refreshing the skill files is the separate `@cometchat/skills add`.
+
+## Verification scope — BUILD the feature; do NOT test it unless asked
+- **Your job is to BUILD the requested integration, not to test it.** After building, a `tsc`/build to confirm it compiles is sufficient. Do **NOT** scaffold or run end-to-end / browser / Playwright / headless / unit / integration tests, add a test framework or test files, or set up CI — **unless the user EXPLICITLY asks for tests.** "Add chat to my app" means add chat, not write a test suite or launch a browser to prove it.
+- **A skill's "Verify it works" section is an ADVISORY, human-run sanity check** (start the app, see the conversation list render, send a message) — it is NOT an instruction for you to automate. Offer the checklist to the user if useful; never spin up a headless browser / E2E run to satisfy it yourself.
+- Automated E2E/smoke testing of these skills is an INTERNAL CometChat-team activity (a separate skill-reviewer), never part of a customer integration. If you think testing is warranted, ASK first — don't do it unprompted.