@cometchat/skills 4.2.1 → 4.4.0

package/skills/cometchat/SKILL.md

@@ -1,14 +1,15 @@
 ---
 name: cometchat
-description: Entry-point for CometChat integration in any React, React Native, Angular, Android, Flutter, or iOS project — web (React/Next.js/React Router/Astro), React Native (Expo/bare), Angular (12-15), native Android (V5 stable, V6 beta), Flutter (V5 stable, V6 beta), and native iOS (V5 stable). Detects the framework, gathers requirements through an interactive conversation, and writes production-quality integration code.
+description: Entry-point for CometChat integration in any React, React Native, Angular, Android, Flutter, or iOS project — web (React/Next.js/React Router/Astro), React Native (Expo/bare), Angular (12-15), native Android (V6 stable, V5 legacy), Flutter (V6 stable, V5 legacy), and native iOS (V5 stable). Detects the framework, gathers requirements through an interactive conversation, and writes production-quality integration code.
 license: "MIT"
-allowed-tools: "shell, file-read, file-search, file-list, ask-user"
 metadata:
   author: "CometChat"
   version: "3.0.0"
   tags: "cometchat dispatcher entry react nextjs react-router astro expo react-native angular android flutter ios chat"
 ---
 
+> **Ground truth:** the `cometchat detect --json` output + the per-platform `*-core` skills this dispatcher routes to + the `packages/registry` catalogs. (Official docs linked below.) Verify symbols against the installed package/source before relying on them.
+
 ## Use this skill when
 
 The user wants to add CometChat to any kind of project. Trigger phrases:
@@ -16,6 +17,7 @@ The user wants to add CometChat to any kind of project. Trigger phrases:
 - `/cometchat` (or invoke the cometchat skill via your agent's mechanism — keyword "cometchat" or "integrate chat" works in most agents)
 - "add cometchat", "integrate cometchat", "add chat to my app"
 - "add messaging", "add chat ui", "add in-app chat"
+- **Customize an existing CometChat integration** — "make the chat match my brand", "change the chat colors / theme", "style the message bubbles", "translate the chat / add a language", "change the notification (or call) sounds". These route through this dispatcher too: detect the framework, then load the family's `*-theming` + `*-customization` (+ `cometchat-i18n` for localization) skills. If `.cometchat/state.json` already exists, jump to the Step 7 iteration menu's customization options instead of re-running Phase A.
 
 This is the **entry point for every framework**. Do NOT invoke
 framework-specific skills directly — this dispatcher detects the
@@ -27,12 +29,12 @@ framework first and routes to the right ones.
 |---|---|
 | **Web** | React (Vite/CRA), Next.js, React Router v6/v7, Astro |
 | **React Native** | Expo (managed + Expo Router), bare RN CLI |
-| **Angular** | Angular 12-15 (Angular CLI / NgModule) |
-| **Android** | V5 stable (Java + Kotlin Views) / V6 beta (Compose + Kotlin Views) |
-| **Flutter** | V5 stable (GetX-based, `cometchat_chat_uikit:^5.2`) / V6 beta (Bloc-based, `cometchat_chat_uikit:^6.0.0-beta`) |
+| **Angular** | Angular 17-21 (standalone components; `@cometchat/chat-uikit-angular@5`) |
+| **Android** | V6 stable (Compose + Kotlin Views, `chatuikit-{compose,kotlin}-android:6.x`) / V5 legacy (Java + Kotlin Views, `chat-uikit-android:5.x`) |
+| **Flutter** | V6 stable (Bloc-based, `cometchat_chat_uikit:^6.0`) / V5 legacy (GetX-based, `cometchat_chat_uikit:^5.2`) |
 | **iOS** | V5 stable (Swift; SwiftUI + UIKit hosting; `CometChatUIKitSwift:~> 5.1`) |
 
-The web family loads `@cometchat/chat-uikit-react` + `@cometchat/chat-sdk-javascript`. The RN family loads `@cometchat/chat-uikit-react-native` + `@cometchat/chat-sdk-react-native`. The Angular family loads `@cometchat/chat-uikit-angular` + `@cometchat/chat-sdk-javascript`. The Android family loads `com.cometchat:chat-uikit-android:5.x` (V5) or `com.cometchat:chatuikit-{compose,kotlin}-android:6.x` (V6) from Maven Central. The Flutter family loads `cometchat_chat_uikit:^5.2` (V5; pair with `cometchat_calls_uikit:^5.0` for calls) or `cometchat_chat_uikit:^6.0.0-beta` (V6; calls fold into the same package) from the Cloudsmith Dart pub-hosted registry. The dispatcher decides which set after Step 1's detection.
+The web family loads `@cometchat/chat-uikit-react` + `@cometchat/chat-sdk-javascript`. The RN family loads `@cometchat/chat-uikit-react-native` + `@cometchat/chat-sdk-react-native`. The Angular family loads `@cometchat/chat-uikit-angular` + `@cometchat/chat-sdk-javascript`. The Android family loads `com.cometchat:chatuikit-{compose,kotlin}-android:6.x` (V6 — stable, recommended) or `com.cometchat:chat-uikit-android:5.x` (V5 — legacy) from Maven Central. The Flutter family loads `cometchat_chat_uikit:^6.0` (V6 — stable, recommended; calls fold into the same package) or `cometchat_chat_uikit:^5.2` (V5 — legacy; pair with `cometchat_calls_uikit:^5.0` for calls) from the Cloudsmith Dart pub-hosted registry. The dispatcher decides which set after Step 1's detection.
 
 ## How v3 works
 
@@ -53,8 +55,32 @@ don't guess where the trigger button goes, don't guess the auth system.
 
 ## Steps
 
+> **Clarification contract (ALL coding agents) — read `references/asking-questions.md`.** Everywhere the steps below say "ask the user", "render an `AskUserQuestion`", "MUST ask", or "NON-NEGOTIABLE prompt", they mean: **follow that contract.** `AskUserQuestion` is only Claude Code's name for it — on Codex / Cursor / Gemini CLI / Windsurf / any agent without that primitive, render the question as a **numbered text list and WAIT for a real answer** (never default, never infer; auto/approval mode does not authorize skipping). Map the answer by **value/label, not ordinal position**, accept a free-text fallback, and if running headless, STOP and emit the question rather than guessing. This contract governs every prompt in this skill and all skills it routes to.
+
 ### Step 1 — Detect framework + map the project
 
+> **If the CLI itself can't run — degrade, don't dead-end.** Every step
+> below calls `npx @cometchat/skills-cli …`. That can fail to *launch*
+> (no network to fetch the package, npx/Node absent, a sandbox that
+> blocks process spawn or the npm registry) — distinct from the CLI
+> running and returning a JSON `error` (handled in the error-handling
+> section near the end). When a command can't launch at all:
+> - **`detect`** → detect by hand. Everything the CLI's detector keys on
+>   is in the files this step already tells you to read: `package.json`
+>   deps (`@cometchat/chat-uikit-react` → web, `…-react-native` → RN,
+>   `…-angular` → Angular), `pubspec.yaml` (Flutter), `build.gradle`
+>   (Android), `Podfile`/`Package.swift` (iOS), plus the router/version
+>   markers. Determine the framework + version from those and continue.
+> - **`config show`** → treat as no saved config; read `.cometchat/config.json`
+>   directly if it exists, else proceed greenfield and ask the questions.
+> - **Action commands** (`auth login`, `apply-feature`, `builder export`,
+>   `verify`) genuinely need the CLI. If one can't run, don't silently
+>   skip it — tell the user it's unavailable, give the manual dashboard
+>   equivalent (e.g. fetch creds from app.cometchat.com → *Credentials*;
+>   toggle the extension in *Extensions*), and continue best-effort.
+> Never STOP the whole flow just because `npx` is unavailable — manual
+> detection + reading the project is a complete substitute for routing.
+
 First, check if `.cometchat/config.json` exists:
 ```bash
 npx @cometchat/skills-cli config show --json
@@ -72,17 +98,38 @@ npx @cometchat/skills-cli detect --json
 
 The JSON output includes `framework` (one of `reactjs`, `nextjs`, `react-router`, `astro`, `expo`, `react-native`, `angular`, `android`, `flutter`, `ios`, or `null`), framework-specific fields (`router`, `expo_mode`, `react_native_version`, `android_version`, `flutter_version`, `env_prefix`), and a `compatibility.supported` flag. If `supported` is `false`, stop and surface the warnings.
 
-**Android — `android_version` is load-bearing.** When `framework === "android"`, the detect output includes `android_version: "v5" | "v6" | null`. The cohort selects which V5 or V6 pattern set to load — V5 (live, `chat-uikit-android:5.x`, Java + Kotlin Views) and V6 (beta, `chatuikit-{compose,kotlin}-android:6.x`) are different SDKs with different APIs. Treat them as separate routing targets even though both live under `--family android`.
+#### If `framework === null` — greenfield with no project at all (ENG-35718)
+
+A null framework means the working directory has no recognizable scaffold — no `package.json`, no `pubspec.yaml`, no `AndroidManifest.xml`, no Podfile, no Xcode project. The earlier behavior dumped the user into a vague "want me to create one?" with two unlabeled options. Replace it with a **named-scaffold prompt** so the user picks a target deterministically:
+
+> "I don't see a project here yet. Want me to create one? Pick the closest match — you can change details after:
+>
+> 1. **React (Vite)** — fastest web demo; `npm create vite@latest cometchat-demo -- --template react-ts`
+> 2. **Next.js (App Router)** — production-grade web with SSR; `npx create-next-app@latest cometchat-demo --typescript --app`
+> 3. **Expo (managed)** — fastest mobile demo; `npx create-expo-app@latest cometchat-demo --template`
+> 4. **Other** — tell me what framework you're using and I'll skip the scaffold step.
+>
+> What sounds right?"
+
+Render this as an `AskUserQuestion` with the same 4 options. After the user picks, run the scaffold command, `cd` into the new directory, then re-run `detect` so the rest of the dispatcher behaves as if `framework` had been detected normally. Do NOT proceed to Step 2 without a real framework — every step below assumes one exists.
+
+If the user declines all four (chooses "Other" and then says "no, I just wanted to look around"), stop politely and tell them: *"You can run `/cometchat` again from inside a React / Next.js / Expo / Angular / Android / iOS / Flutter project and I'll detect it automatically."* Don't try to integrate into an empty directory — every subsequent step will fail.
+
+**Android — `android_version` is load-bearing.** When `framework === "android"`, the detect output includes `android_version: "v5" | "v6" | null`. The cohort selects which V5 or V6 pattern set to load — V6 (stable + recommended, `chatuikit-{compose,kotlin}-android:6.x`, Compose + Kotlin Views split) and V5 (legacy, `chat-uikit-android:5.x`, Java + Kotlin Views) are different SDKs with different APIs. Treat them as separate routing targets even though both live under `--family android`. **V6 went GA 2026-05-25** ([docs](https://www.cometchat.com/docs/ui-kit/android/v6/overview)) — was beta in earlier `/cometchat` releases; the prompt + recommendation flipped from V5 → V6 in v4.3.0.
 
 If `android_version` is `null`, the project is greenfield (no cometchat dep yet). Ask the user:
-> "Which CometChat Android UI Kit do you want to use? V5 is the live SDK (recommended for production today). V6 is beta (Compose + Kotlin Views split, future-facing)."
+> "Which CometChat Android UI Kit do you want to use? V6 is the latest stable SDK (recommended; Compose + Kotlin Views split, went GA 2026-05-25). V5 is the legacy SDK (Java + Kotlin Views — still supported but no new features)."
 
-Save the choice into `.cometchat/config.json` under `android_version` so subsequent `/cometchat` runs don't re-ask.
+Save the choice into `.cometchat/config.json` under `androidVersion`:
+```bash
+npx @cometchat/skills-cli config save --android-version v5 --json
+```
+The CLI accepts `--android-version v5` / `v6` and `--flutter-version v5` / `v6` flags (added 2026-05-22 — F46 fix). Subsequent `/cometchat` runs read this from config and don't re-ask.
 
-**Flutter — `flutter_version` is load-bearing too.** When `framework === "flutter"`, the detect output includes `flutter_version: "v5" | "v6" | null`. V5 is GetX-based (`cometchat_chat_uikit:^5.2`); V6 is Bloc-based (`cometchat_chat_uikit:^6.0.0-beta2`). The two cohorts have different state-management primitives, different barrel exports, and different theme APIs — never mix them. Same `--family flutter` install ships both sets; routing picks the right one.
+**Flutter — `flutter_version` is load-bearing too.** When `framework === "flutter"`, the detect output includes `flutter_version: "v5" | "v6" | null`. V6 (stable + recommended) is Bloc-based (`cometchat_chat_uikit:^6.0`, calls folded into the same package). V5 (legacy) is GetX-based (`cometchat_chat_uikit:^5.2`; pair with `cometchat_calls_uikit:^5.0` for calls). The two cohorts have different state-management primitives, different barrel exports, and different theme APIs — never mix them. Same `--family flutter` install ships both sets; routing picks the right one. **V6 went GA 2026-05-25** ([docs](https://www.cometchat.com/docs/ui-kit/flutter/overview)) at version 6.0.1 — was `6.0.0-beta2` in earlier `/cometchat` releases; the prompt + recommendation flipped from V5 → V6 in v4.3.0.
 
 If `flutter_version` is `null`, ask the user:
-> "Which CometChat Flutter UI Kit do you want to use? V5 is the live SDK (GetX-based, recommended for production today). V6 is beta (Bloc-based, future-facing)."
+> "Which CometChat Flutter UI Kit do you want to use? V6 is the latest stable SDK (recommended; Bloc-based, calls folded into the same package, went GA 2026-05-25 at 6.0.1). V5 is the legacy SDK (GetX-based — still supported but no new features)."
 
 Save the choice into `.cometchat/config.json` under `flutter_version`.
 
@@ -104,10 +151,10 @@ Save the choice into `.cometchat/config.json` under `flutter_version`.
 - Existing nav structure — read the root navigator to see stack vs tab vs drawer layout
 
 **For Angular (`angular`):**
-- `package.json` — name, `@angular/core` version (12-15 supported), all `@angular/*` deps
-- `angular.json` — workspace config; identify the project name + `sourceRoot`
-- Root NgModule — usually `src/app/app.module.ts`; check imports + declarations + `schemas`
-- Routing — `src/app/app-routing.module.ts` or root `RouterModule.forRoot([...])`; list all routes
+- `package.json` — name, `@angular/core` version (**17-21 supported**; the v5 kit's peer range is `>=17 <22`), all `@angular/*` deps
+- `angular.json` — workspace config; identify the project name + `sourceRoot`; the `build.options.styles` array (where the kit's `css-variables.css` is registered) + the `assets` glob
+- Bootstrap — **standalone**: `src/main.ts` (`bootstrapApplication`) + `src/app/app.config.ts` (providers). v5 is standalone-first — there is no NgModule/`CUSTOM_ELEMENTS_SCHEMA`. (A legacy NgModule app must migrate to standalone, or pin the v4 `legacy` kit — different skill.)
+- Routing — `src/app/app.routes.ts` (`provideRouter` / `loadComponent`); list all routes
 - Layout — `src/app/app.component.{ts,html}`; identify nav, sidebar, header components
 - Existing pages/components — list under `src/app/pages/`, `src/app/components/`, or wherever the project organizes them
 - Environment files — `src/environments/environment.ts` (and `.prod.ts`); credentials live here, NOT in `.env`
@@ -124,7 +171,7 @@ Save the choice into `.cometchat/config.json` under `flutter_version`.
 
 **For Flutter (`flutter`):**
 - `pubspec.yaml` — package name + Dart SDK constraint + Flutter SDK constraint + `dependencies:` (this is where `cometchat_chat_uikit` lives)
-- For V5: a typical project has BOTH `cometchat_chat_uikit:^5.2` AND `cometchat_calls_uikit:^5.0` if calls are needed. V6 folds calls into the single `cometchat_chat_uikit:^6.0.0-beta2` package (no separate calls package).
+- For V5: a typical project has BOTH `cometchat_chat_uikit:^5.2` AND `cometchat_calls_uikit:^5.0` if calls are needed. V6 folds calls into the single `cometchat_chat_uikit:^6.0` package (no separate calls package; depends on `cometchat_calls_sdk: >=5.0.2 <6.0.0` transitively).
 - `lib/` — Dart source. The app entry is `lib/main.dart` (the `void main() => runApp(...)` site); init goes in `main()` or in a top-level `Stateful`/`State.initState()`.
 - `lib/<config>.dart` (or similar) — credentials. There is NO Flutter `.env` convention — credentials are typically defined as `const` Dart values in a config file, OR injected at compile time via `--dart-define=COMETCHAT_APP_ID=...` flags read inside Dart with `String.fromEnvironment`. NOT a `.env` file at runtime.
 - `android/app/build.gradle` and `ios/Runner/Info.plist` — platform-specific config (FCM service registration, Push capabilities, microphone/camera Info.plist entries for calls). Flutter projects DO have these subdirs but they're configured Flutter-side; do not run the native skill flows.
@@ -141,6 +188,19 @@ Save the choice into `.cometchat/config.json` under `flutter_version`.
 
 Store this mental map — you'll use it throughout the conversation.
 
+#### Post-detect order of operations — run these gates IN THIS ORDER
+
+> The moment `detect --json` returns, run the following **in order** before
+> you write anything or commit to a plan. Each is detailed in its own
+> subsection below; this is the precedence when more than one applies:
+>
+> 1. **Pattern skills installed?** (see "Pattern skills not installed? — CHECK THIS FIRST") — if the framework's pattern skills aren't loaded, install them and have the user re-run **now**, before anything else. A late discovery is the worst-timed interruption.
+> 2. **`version_conflict` gate** (see "Version-conflict pre-flight") — STOP if the installed UI Kit major doesn't match what the skills target, or both V5+V6 are declared.
+> 3. **`coexistence` gate** (see "Coexistence pre-flight") — STOP if a competing chat/calling SDK is present; carry the Firebase/SW advisories into the push journey.
+> 4. **Step 1.5 "I see you" summary** (below) — only once the gates pass, narrate what you found, then continue to Step 2.
+>
+> Gates 1–3 are hard stops that can each send the user away to fix something; run them before the Step 1.5 summary so you don't narrate a plan you then have to retract. (The subsections appear below in roughly this order, but this list is the authoritative precedence.)
+
 #### 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.
@@ -181,7 +241,7 @@ The shape (use it verbatim — the structure earns trust):
 >
 > - **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
+> - **No auth system detected** — I'll set you up in dev mode; we'll pick a test user (default `cometchat-uid-1` through `uid-5`) when I confirm credentials in the next step; 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.
@@ -193,14 +253,42 @@ This moment costs ~5 seconds of conversation but anchors the rest. Skip it and t
 **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
-- Angular: @angular/core@<12 → upgrade required; @angular/core@>=16 → warning (skill is verified against v15)
+- Angular: @angular/core@<17 → upgrade required (v5 kit peer range is `>=17 <22`); skill verified against v21 standalone
 - Android V5: minSdk@<21 → upgrade required; minSdk@<24 → warning; AGP@<7.0 → warning
 - Android V6: minSdk@<28 → upgrade required (V6 raised the floor from API 23 to API 28); Kotlin@<1.9 → warning; for Compose stack, Compose BOM@<2024.x → warning
 - Flutter V5: Dart SDK <2.17 → upgrade required; Flutter <2.5 → warning; Android `minSdk 24` (Flutter platform default) when V5 is in use
 - Flutter V6: Dart SDK <2.17 → upgrade required; Flutter <2.5 → warning; Android `minSdk 26` REQUIRED (cometchat_calls_sdk in V6 raised the floor)
 - iOS V5: iOS deployment target <13 → upgrade required; Swift <5.0 → upgrade required; Xcode 15+ requires `ENABLE_USER_SCRIPT_SANDBOXING = NO` in Build Settings (or the `post_install` Podfile hook)
 
-#### Pattern skills not installed?
+#### Version-conflict pre-flight — STOP if `detect` reports `version_conflict` (P0-6)
+
+*(Gate 2 in the post-detect order above — runs after the pattern-skills check, before the coexistence gate and the Step 1.5 summary.)*
+
+> **The moment `detect --json` returns, check `version_conflict`. If it is non-null, STOP — do NOT write integration code yet.** It fires when the project already has a CometChat UI Kit at a major version these skills don't target (e.g. `chat-uikit-react` v5 in a v6-targeted web project), or when BOTH a V5 and a V6 UI Kit are declared (Android/Flutter half-migrated / duplicate tree). Proceeding emits guidance for the wrong major → `duplicate class` / `unresolved reference` / won't-compile failures the user can't easily trace. Surface `version_conflict.detail` to the user and ask how to reconcile (upgrade the installed kit to the targeted major, or load the matching-version skills, or remove the cohort they're not integrating) **before** Step 2. Re-run `detect` after they fix it. This is a gate, not a warning.
+
+#### Coexistence pre-flight — STOP if `detect` reports a competing chat SDK (P0-10)
+
+*(Gate 3 in the post-detect order above — runs after the version-conflict gate, before the Step 1.5 summary.)*
+
+> **Also check `coexistence` in the same `detect --json` output.** It surfaces three collisions you must resolve before mounting CometChat:
+>
+> - **`coexistence.competing_sdks`** lists other chat / calling / push providers already in the project (Sendbird, Stream, Twilio, PubNub, TalkJS, Agora, OneSignal). If any entry has `kind: "chat"` or `"calling"`, **STOP** — silently adding CometChat means two chat providers mounted in one tree, duplicate WebSocket connections, and a confusing double UI. Ask the user (use the clarification contract — `references/asking-questions.md`):
+>   > "I see **{name}** ({coordinate}) already in this project. How do you want to proceed?"
+>   > 1. **Replace it** — I'll integrate CometChat and leave the old SDK's code in place for you to remove (I won't delete it without confirmation).
+>   > 2. **Run alongside** — keep both, namespaced; chat stays on {name}, CometChat powers a new surface. (Heavier; two realtime stacks.)
+>   > 3. **Switch fully** — integrate CometChat now and you'll migrate {name}'s usages over later.
+>   >
+>   > WAIT for the answer; route accordingly. Never auto-delete the competing SDK's files or deps — that's the user's call.
+> - **`coexistence.existing_firebase: true`** — the project already wires Firebase. CometChat push is FCM-based, so on the `-push` journey you must **reuse the same Firebase app** (don't call `initializeApp` a second time) and **merge** rather than overwrite `firebase-messaging-sw.js`. Carry this fact into the push skill; it's an advisory, not a hard stop for chat-only integration.
+> - **`coexistence.existing_service_workers`** — lists existing SW files at paths CometChat web push would write to. Before generating `firebase-messaging-sw.js`, confirm you won't clobber the app's offline/caching logic; merge the messaging handlers into the existing worker instead.
+>
+> A competing **chat/calling** SDK is a gate (ask before proceeding). Firebase + service-worker entries are advisories you must honour on the push journey.
+
+#### Pattern skills not installed? — CHECK THIS FIRST
+
+*(Gate 1 in the post-detect order above — the highest-precedence gate; run it before the version-conflict/coexistence gates and before the Step 1.5 summary, even though it appears last in this section for readability.)*
+
+> **Run this check the moment `detect` returns a framework — BEFORE the Step 1.5 "I see you" summary, BEFORE credentials (Step 2), BEFORE any `AskUserQuestion`, and BEFORE creating a Visual Builder.** It is a gate, not a contingency. If the framework's pattern skills are missing, install them and tell the user to re-run **right now**. Do NOT lazily discover the gap later (e.g. when you try to read a pattern skill at code-gen) — agents don't hot-reload skills mid-session (see the re-run note below), so discovering it late forces the user to re-run **after** they've logged in, picked an app, and customized their Visual Builder. That's the worst-timed possible interruption. Catch it at second 5, not at the finish line.
 
 The dispatcher routes to web pattern skills (`cometchat-{core,components,placement,*-patterns}`), RN pattern skills (`cometchat-native-{core,components,placement,*-patterns}`), or Angular pattern skills (`cometchat-angular-{core,components,placement,patterns}`) based on the detected framework. If the matching set isn't loaded — i.e. the user has only the dispatcher in `.claude/skills/`, OR they installed only `@cometchat/skills` (web) but the project is RN/Angular, OR vice versa — **install the missing package yourself**. Do NOT stop and ask the user to run the npx command manually — that turns a 0-step recovery into a 2-step recovery for no benefit.
 
@@ -335,6 +423,8 @@ Terminal error handling (surface verbatim, stop, do not retry silently):
 - `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.
+- `AUTH_FAILED` — the bearer was rejected (401) — e.g. a stored token expired or was revoked, surfaced by a later `auth me` / `auth status`. Re-run `auth login` to re-authenticate. (Distinct from the device-auth codes above: this is the *post-login* "my session went stale" case, normalized from a 401 in `cometchat-api.ts`.)
+- `API_ERROR:<code>` (and any unlisted code) — an unexpected server-side error; do NOT pattern-match it. Fall through to the generic handler: show the CLI's `human_message` / `suggestion` if present, then the raw `error` in parentheses (see the error-handling rule near the end of this skill).
 
 After success, verify via `auth status --json` and proceed to **Step 2b.5**.
 
@@ -382,7 +472,7 @@ Response shape:
 }
 ```
 
-Field meanings (from the dashboard's signup screens — see `/Users/swapnil/Downloads/customer-dashboard-main/src/components/auth/Welcome/`):
+Field meanings (from the dashboard's signup screens):
 
 - `role`: `"frontend"` / `"backend"` / `"fullstack_engineer"` / `"startup_founder"` / `"product_leader/manager"` / `"engineering_leader/manager"` / `"others"` (when `others`, `other_role` carries the freeform value)
 - `intent`: `"building"` / `"evaluating"` / `"exploring"` (this is the **dashboard's** intent — distinct from Step 3a's `placement_intent` which asks about app archetype)
@@ -525,20 +615,20 @@ This creates/updates the env file with the correct prefix AND writes `.cometchat
    - **header:** "Industry"
    - **options** — full 11-option set (see table below); do NOT pick a default like `saas_businesses` without asking
 
-**Industry key mapping:**
+**Industry key mapping** — present these **labels** (verbatim from the dashboard's `/create-app` set, canonical in `packages/cli/src/utils/onboarding-options.ts` `INDUSTRIES`) and pass the mapped `--industry` value:
 
 | Label | `--industry` value |
 |---|---|
-| SaaS / Business | `saas_businesses` |
-| Marketplace | `online_marketplaces` |
-| Social / Community | `community_and_social` |
+| Online Marketplaces | `online_marketplaces` |
 | 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` |
+| Events & Streaming | `events_and_streaming` |
+| Online Education | `online_education` |
+| Community & Social | `community_and_social` |
+| SaaS & Multi-Tenant | `saas_businesses` |
+| Sports & Gaming | `sports_and_gaming` |
+| Team Comms & Workflows | `team_comms_and_workflows` |
+| On-Demand Services | `on_demand_services` |
 | Other | `other` |
 
 **Confirm before creating, then:**
@@ -691,6 +781,28 @@ After writing credentials, don't echo the Auth Key back in the transcript. Confi
 
 This is the core of v3. A multi-step conversation that gathers everything you need before writing a single line of code.
 
+#### Step 3 sub-flow order (NON-NEGOTIABLE — run in this exact order)
+
+1. **3.0** — Branch by product (chat vs calls) — sets `product`
+2. **3.1** — Customization preference (Visually vs In code) — sets `customize` ← **MUST run before 3a**
+3. **3a** — Intent ("What are you building?")
+4. **3b** — Recommendation (skip on Visually path per §3.1)
+5. **3c** — Placement
+6. **3d** — Authentication
+7. **3e** — User mapping (optional)
+8. **3f** — Plan confirmation
+
+**Common skip-bug (observed 2026-05-22 in a real Android run):** the agent
+runs 3a + 3c after Step 2 (provision) and goes straight to writing code,
+skipping 3.1 entirely. **Step 3.1 must fire on EVERY chat-messaging
+integration on a builder-supported platform** (react, react-native, ios,
+android, flutter — see §3.1 table). The only exception is Angular, which
+auto-routes to In-code with the explicit fallback note.
+
+The customer-visible symptom of the skip: agent never asks "How do you
+want to customize your chat experience? Visually vs In code". Customer
+gets the In-code path silently. Visual Builder feature is invisible to them.
+
 #### 3.0. Branch by product (chat vs calls)
 
 `product` decides which dispatcher (chat or calls) handles the rest of Step 3. Resolve it in this priority order:
@@ -730,12 +842,195 @@ Once `product` is resolved, route — the rest of Step 3 is chat-shaped, and a c
 | `chat-messaging` | Continue to 3a | Existing chat flow — placement intent, recommendation, framework skills, scaffold chat surfaces. |
 | `voice-video` | **Hand off to `cometchat-calls`** | Stop here. Invoke the `cometchat-calls` dispatcher with the framework + family + credentials already established. Calls dispatcher routes to the per-family `cometchat-{family}-calls` skill in **standalone** mode — no chat UI Kit, full calls surface, VoIP push wired by default, `IncomingCall` mounted at app root. |
 | `chat-messaging+voice-video` | Run 3a–6 (chat), THEN hand off to `cometchat-calls` in additive mode | Full chat flow first. After Step 6 verifies the chat integration, invoke `cometchat-calls` in **additive** mode — patches the existing provider to mount `IncomingCall` at root, adds call buttons inline on chat surfaces, opt-in VoIP push. Skip `apply-feature calls` — `cometchat-calls` covers it end-to-end. |
-| `ai-agent` / `byo-agent` | Exit with docs pointer | Tell the user: *"`/cometchat` integrates chat and calling surfaces. AI Agents have their own integration path — see https://www.cometchat.com/docs/ai-agents."* Exit cleanly; do not attempt to scaffold. |
+| `ai-agent` / `byo-agent` | Offer chat-first scaffold + docs pointer (ENG-35724) | Don't dead-end. Tell the user: *"AI Agents have their own integration path at https://www.cometchat.com/docs/ai-agents — but the agent UI lives inside a chat surface. Want me to set up the chat integration first? Once chat is wired, you can plug the AI Agent (or your BYO model) into the same `cometchat-features` flow without re-doing the integration."* If yes, treat `product = "chat-messaging"` and continue to 3a. If no, exit politely (don't push). Two segments hit this dead-end and bounced out — give them a path forward without rebuilding the AI integration in this dispatcher today. |
 
 **If config has `placement_intent` set from a previous run**, confirm it and skip to Step 3b. The product branch above still runs first — a chat-mode integration that's now adding calls re-enters via the `chat-messaging+voice-video` row, not the chat-only row.
 
 **Why this branch comes before 3a:** Step 3a's options are all chat archetypes (Messaging app, Marketplace, SaaS, …). For a `voice-video` product, that taxonomy doesn't apply — the user isn't picking *where chat lives*, they're picking *where the call trigger lives* (profile button vs `/calls` route vs always-on lock-screen-ringer). The `cometchat-calls` dispatcher owns its own placement question with the right options for the calls surface.
 
+#### 3.1 — Customization preference (Visually vs In code)
+
+**Only runs if** `product` includes `chat-messaging` (skip entirely for `voice-video` — the Visual Builder is chat-only today).
+
+**Only runs if** the resolved framework maps to a builder-supported platform. Use this table — these are the same cohorts the dashboard's Visual Builder emits code for:
+
+| Skills cohort/framework | Builder `platform` value | If Visually picked |
+|---|---|---|
+| `reactjs`, `nextjs`, `react-router`, `astro` | `react` | Build with React UI Kit, mount via `<CometChatApp />` |
+| `expo`, `react-native` | `react-native` | Build with RN UI Kit, mount in app root. `cometchat builder export --platform react-native` IS supported — it copies the builder's `src/config/` (`store.ts` + `config.json`) and patches `config.json` with the JSON-envelope settings. |
+| `android-v5`, `android-v6` | `android` | Build with Android UI Kit (V5 schema; V6 customers get a one-line migration shim) |
+| `ios` | `ios` | Build with iOS UI Kit |
+| `flutter-v5`, `flutter-v6` | `flutter` | Build with Flutter UI Kit (V5 schema; V6 same shim story as Android) |
+| `angular` | **not supported** | See "Angular" note below — auto-route to In code with an explicit one-time message. |
+
+> **Native Visually exports are V5-shaped today (F22 — transitional).** The Android, Flutter (and iOS) Builder canonicals emit **V5-flavored** UI Kit screens; a **V6 native project's own code is untouched**, but the Builder-exported screens come in at the V5 schema (the "migration shim" noted above bridges them). If a V6 native customer wants a single-version (pure-V6) dependency tree, the **In-code** path is the cleaner choice. React/Next/Astro and React Native are unaffected (web is V6-native; RN uses the `src/config/` store envelope, not a V5 canonical). The per-family `cometchat-{android-v6,flutter-v6}` skills carry the full warning — surface this at the choice so the decision is informed.
+
+##### Angular — explicit fallback
+
+The dashboard's Visual Builder export pipeline doesn't have an Angular emitter — `https://preview.cometchat.com/downloads/cometchat-builder-{platform}.zip` ships only `react`, `react-native`, `ios`, `android`, `flutter`. Skills can't bridge that gap by emitting Angular code from React/JSON output because the kit's Angular package (`@cometchat/chat-uikit-angular`) uses different selectors, modules, and content-projection slots than React.
+
+**For Angular projects:**
+1. **Do NOT show the Visually-vs-In-code prompt.** It's a dead choice — there's no Visually path to take.
+2. **Surface this once, then move on.** Print a brief, friendly note in the chat — single message, no follow-up question:
+
+   > *"The Visual Builder doesn't ship Angular code yet (the dashboard's export covers React / React Native / iOS / Android / Flutter today). I'll set up the code-driven Angular integration instead — you can theme via CSS variables (`--cometchat-*`, scoped to `.cometchat`) later. Want to be notified when an Angular Visual Builder lands? Drop a 👍 on https://github.com/cometchat/cometchat-skills/discussions/categories/feature-requests."*
+
+   Tweak wording to fit the conversation tone (greeting the user by name if `meta.name` is set, etc.) but keep it factual: WHY it's missing + WHAT we're doing instead + WHERE to register interest.
+
+3. **Set `customize=code` in `.cometchat/config.json`** so subsequent `/cometchat` reruns skip the prompt silently. Run via Bash:
+   ```bash
+   npx @cometchat/skills-cli config save --customize code --json
+   ```
+
+4. **Continue to Step 3a (intent).** The rest of the chat flow proceeds as normal — `cometchat-angular-{core,components,placement,patterns}` handle the actual code emission.
+
+5. **Stale `customize=visual` from a previous framework?** If `auth me`/config carries `customize=visual` from a prior run on a different framework, OVERWRITE it to `code` for this Angular session — same `config save` call as above — and surface the same note. The dispatcher must never try to call `builder create --platform angular` (the CLI rejects it with "Missing or invalid --platform"; the customer would see a confusing CLI error instead of the explanatory note).
+
+##### Next.js Pages Router — explicit fallback (F17)
+
+Visual Builder is architecturally incompatible with Next.js **Pages Router**. The canonical's `src/CometChat/` has 25+ per-component CSS imports, but Pages Router enforces "global CSS only in `pages/_app.tsx`" — Webpack fails the build on the first component import. App Router tolerates per-component CSS; Pages Router does not. There's no client-side workaround short of rewriting the canonical's styling architecture.
+
+The CLI guards this — `builder create --platform react` will refuse when `detect.router === "pages"` with an explicit F17 message. The dispatcher must surface this BEFORE calling the CLI, same shape as the Angular fallback:
+
+**For Next.js Pages Router projects (`detect.framework === "nextjs"` AND `detect.router === "pages"`):**
+
+1. **Do NOT show the Visually-vs-In-code prompt.** Same dead choice as Angular.
+2. **Surface this once:**
+
+   > *"Visual Builder isn't compatible with your Pages Router setup — the canonical's per-component CSS imports break Pages Router's strict 'global CSS in `_app.tsx` only' rule (F17). Two options: migrate to App Router (the Next.js 13+ default), or stay on Pages Router and I'll use the code-driven integration. Want to be notified when Pages Router compatibility lands? https://github.com/cometchat/cometchat-skills/discussions/categories/feature-requests"*
+
+3. **Set `customize=code` in `.cometchat/config.json`**:
+   ```bash
+   npx @cometchat/skills-cli config save --customize code --json
+   ```
+
+4. **Continue to Step 3a (intent).** `cometchat-nextjs-patterns` §4 covers the Pages Router provider mount (`_app.tsx` with `next/dynamic` + `ssr: false`).
+
+5. **App Router projects (`detect.router === "app"`)** are fully supported by Visual Builder — proceed with the Visually-vs-In-code prompt as normal.
+
+**If config has `customize` set from a previous run AND the framework is in the builder-supported table above**, confirm it (*"Continuing the visual-builder flow you started last time — builder ID `abc123`. Re-fetch latest config? [Y/n]"* for `customize=visual`; just *"Continuing in-code customization."* for `customize=code`) and skip the question. On `Y` for the re-fetch, jump straight to the `builder fetch` step below.
+
+**If `.cometchat/builder.json` already exists** (customer started a builder in a prior `/cometchat` invocation but didn't finish), surface it before asking: *"Found an existing builder for this project (`abc123`, created 3 days ago). Resume it, start fresh, or switch to code-driven?"* — three options via `AskUserQuestion`. "Resume" jumps to the `builder fetch` step; "Start fresh" creates a new one; "Code-driven" sets `customize=code` and falls through to 3a.
+
+Otherwise, ask:
+
+`AskUserQuestion`:
+- **Question:** "How do you want to customize your chat experience?"
+- **Header:** "Customize"
+- **Options** — which one is listed first and labeled **"(Recommended)"** depends on the framework:
+  - **Default (web React / Next.js App Router / React Router v7 / Astro, React Native, Android, Flutter, iOS):** present **Visually first, labeled "(Recommended)"**. This is deliberate — the Visual Builder is the headline path. Do NOT reorder In-code ahead of it or mark In-code recommended, even though In-code is the historical default. (Frameworks that don't support the builder — Angular, Next.js Pages Router — skip this prompt entirely per the notes above, so they never reach here.)
+  - **iOS:** now a full default (no carve-out). **ENG-35337 is RESOLVED end-to-end: the iOS Visual Builder export BUILDS and LAUNCHES** — `pod 'CometChatBuilder'` (1.1.2) + UIKitSwift 5.1.13 + CallsSDK 5.0.0 → `xcodebuild` BUILD SUCCEEDED, installed + launched clean on a physical iPhone (verified 2026-06-17; the earlier sim-only `EXCLUDED_ARCHS` quirk was an environment issue, not a project defect). Do NOT pin `> 1.1.2` — a `1.1.3` may not exist (see `cometchat-ios-core` §Visual Builder). iOS gets the same **Visually-recommended** default as every other builder-supported platform.
+  - *Visually — configure in the browser (no code)* — "Open CometChat's UI Kit Builder in your browser to **enable/disable features and configure** colors, layout, and styling through settings — no code (it's a configuration tool, **not** a drag-and-drop canvas). Then come back here and I'll wire the result into your app."
+  - *In code — code-driven defaults* — "I'll scaffold a clean integration with sensible defaults. You customize later by editing files / CSS variables."
+
+Persist the answer to `.cometchat/config.json` as `customize: "visual" | "code"` so reruns don't re-ask.
+
+**If the customer picks "In code":** continue to Step 3a as before. Nothing else in Step 3 changes for the In-code path.
+
+**If the customer picks "Visually":** run the visual-builder sub-flow below, then resume the rest of Step 3 (`3a` intent and `3c` placement still run — placement asks where the single `<CometChatApp />` mount goes; the visually-customized features replace what 3b would otherwise recommend).
+
+---
+
+##### 3.1.v — Visually sub-flow
+
+1. **Create the builder.** Run via Bash:
+
+   ```bash
+   cometchat builder create \
+     --app-id <appId-from-config> \
+     --platform <react|react-native|ios|android|flutter from the table above> \
+     --json
+   ```
+
+   Parse the JSON. On success, you get `{ status: "created", builderId, builderUrl, appId, platform, createdAt }`. Cache file `.cometchat/builder.json` is written automatically by the CLI.
+
+   **Error handling:**
+   - `Not logged in` → run `cometchat auth login` (or hand back to Step 1 auth) and retry.
+   - `AUTH_SCOPE` (token lacks `vcb:write`) → tell the customer: *"Your CometChat account doesn't have the Visual Builder add-on enabled — falling back to code-driven customization."* Set `customize=code` and continue to Step 3a.
+   - Any other API error → print the error, set `customize=code` (graceful fallback), continue to 3a.
+
+2. **Open the builder URL in the customer's default browser.** Try the OS-appropriate command via Bash:
+   - macOS: `open "<builderUrl>"`
+   - Linux: `xdg-open "<builderUrl>"` (suppress stderr — many SSH-only / headless boxes don't have a display)
+   - Windows: `start "" "<builderUrl>"`
+
+   If the open command exits non-zero (headless, no display, locked down), don't treat it as a failure — print the URL prominently with: *"Couldn't open your browser automatically. Open this URL on a machine where you can use a browser: `<builderUrl>`"*
+
+   Either way, print the URL itself in the terminal so the customer can copy/paste if the auto-open failed silently.
+
+   **Tell the customer** (F31, verified 2026-05-22 via headless Playwright): *"If you're not already logged into app.cometchat.com in your browser, you'll see the dashboard signup/login screen first. Log in with the SAME account you used to run `cometchat auth login` (typically your work email) — the dashboard will then redirect you to the Visual Builder UI for this specific builder ID."* Without this heads-up, customers seeing the signup screen think skills opened the wrong URL.
+
+3. **Wait for the customer.** Customizing in the Visual Builder typically takes minutes to hours — the customer may walk away. Use `AskUserQuestion` to block:
+   - **Question:** "When you're done customizing in the browser, let me know."
+   - **Header:** "Builder"
+   - **Options:**
+     - *Done — fetch my customization and integrate* — Customer finished customizing in the browser.
+     - *Skip — use code-driven defaults instead* — Customer changed their mind / didn't want to customize after all. Set `customize=code` and continue to 3a (do NOT delete the builder — customer can come back to it later).
+     - *Cancel — exit `/cometchat`* — Customer wants to stop entirely. Exit cleanly.
+
+4. **Export the per-builder integration** (only on "Done"). The CLI command depends on the platform `cometchat detect` resolved:
+
+   | Detected framework | `--platform` value | Default `--output` | Layout kind |
+   |---|---|---|---|
+   | reactjs, nextjs, react-router, astro | `react` | `src/CometChat` (or `src/app/CometChat` for Next App Router via `--output`) | single-dir |
+   | react-native, expo | `react-native` | `src/config` | single-dir |
+   | flutter | `flutter` | `chat_builder` | single-dir |
+   | ios | `ios` | `CometChat` | selective — 3 files: MessagesVC.swift, ThreadedMessagesVC.swift, cometchat-builder-settings.json |
+   | android | `android` | `cometchat` | selective — 2 files: BuilderSettingsHelper.kt, cometchat-builder-settings.json (agent rewrites package decl + moves to app/src/main/java/<package>/cometchat/ — see cometchat-android-v6-core §"Visual Builder integration") |
+
+   For example, on a React Vite project:
+
+   ```bash
+   cometchat builder export --platform react --json
+   ```
+
+   (No `--id` needed — the CLI reads it from `.cometchat/builder.json`. Pass `--output <dir>` for non-default destinations like `src/app/CometChat` for Next.js App Router.)
+
+   This **single command** mirrors the dashboard's Export-button workflow:
+   1. Downloads the canonical static template ZIP from `preview.cometchat.com/downloads/cometchat-builder-<platform>.zip`
+   2. Fetches the customer's per-builder settings via `GET /vcb/builders/{id}`
+   3. Applies F3 + F10 missing-field defaults (`inAppSounds`, `mentionAll`)
+   4. Unzips the template into a temp dir
+   5. Patches the platform's Settings file:
+      - **React** — `CometChatSettings.ts` with `export const CometChatSettings = <settings>;` + sentinel comment
+      - **React Native** — `config.json` with `{ builderId, name, settings }` envelope (no sentinel — JSON forbids `//`)
+      - **Flutter** — `assets/sample_app/cometchat-builder-settings.json` with the same envelope (no sentinel)
+      - **iOS / Android** — `cometchat-builder-settings.json` with the same envelope (no sentinel)
+   6. Copies the platform-relevant subdirectory (or files, for selective layouts) to `--output`
+
+   The command runs an F25 case-collision pre-check (warns if a lowercase `src/cometchat/` with In-code-shape files exists alongside the intended `src/CometChat/` output, on macOS APFS / HFS+ default).
+
+   Parse the returned JSON: `{ status: "exported", builderId, appId, platform, output, settings_file, builder_name, dashboardSetupNeeded }`. Skills' Step 5 file-emission section then patches the customer's existing project to wire in the exported integration (entry file, package.json, tsconfig — see `cometchat-core` §11.2).
+
+   **4a. Enable the dashboard side of the toggled-on features — DO NOT SKIP.** The Visual Builder's feature toggles control **UI visibility only** — they show/hide a feature's buttons in the exported app. Extension- and AI-backed features (polls, message translation, collaborative document/whiteboard, stickers, smart replies, conversation starter/summary) **also need their server-side capability enabled** ("Requires Dashboard setup" in the builder docs), which is a *separate* backend store the builder export never touches. If you skip this, the customer sees the poll button in their builder app, clicks it, and it fails at runtime. The export tells you exactly which ones: iterate `dashboardSetupNeeded` from the export JSON and run the matching enable for each —
+      - `type: "extension"` → `cometchat apply-feature <id> --app-id <appId>` (no code change, idempotent, survives resync).
+      - `type: "ai-feature"` → `cometchat apply-feature <id> --app-id <appId> --openai-key sk-...` (ask the customer for their OpenAI key once; if they don't have one, tell them the AI feature's UI will show but won't return results until a key is set in the dashboard).
+
+      Run these now, before continuing. This is the step that makes the **Visual Builder flow and enable-features compose** — the builder draws the UI, `apply-feature` turns on the capability behind it. (`dashboardSetupNeeded` is `[]` on older CLI builds that predate this field — if it's absent, fall back to scanning the exported `settings.chatFeatures.deeperUserEngagement` / `aiUserCopilot` for `true` values and map them: `messageTranslation→message-translation`, `polls→polls`, `collaborativeWhiteboard→collaborative-whiteboard`, `collaborativeDocument→collaborative-document`, `stickers→stickers`, `conversationStarter→conversation-starter`, `conversationSummary→conversation-summary`, `smartReply→smart-replies`.)
+
+   **Error handling:**
+   - `NOT_FOUND` (builder was deleted out-of-band, or token's appId mismatch) → offer to create a fresh one (`builder create` again) OR fall back to code-driven.
+   - `--output directory already exists` → on first emit this means the customer has a previous integration to overwrite; surface to the customer and re-run with `--force` if they confirm. On resync (step 7 iteration), use `--force` directly per `cometchat-core` §11.6.
+   - `Failed to download template ZIP` → network issue or wrong CC_BUILDER_HOST env override; surface the error verbatim.
+   - Note: the per-builder settings are ALWAYS populated. The dashboard returns a full default config on `builder create` (typing indicators, threads, media, theme, etc.) — verified 2026-05-19 against the real `/vcb/builders` endpoint. "Customer said done but never customized" is indistinguishable from "customer kept the defaults" without diffing against the canonical default blob; don't try to detect it. Always export with whatever comes back.
+
+5. **Continue to Step 3a.** The intent question (3a) and the placement question (3c) still run — intent feeds the *recommendation*, but in the Visually path the recommendation is effectively pre-decided by the builder. Skills should phrase 3a as: *"Just for context — what kind of app is this? (This won't change your visual customizations; it helps me set the right defaults for placement.)"* and skip 3b entirely (no "Here's why I recommend X" — they already chose visually).
+
+##### 3.1.f — Failure-mode summary
+
+| Failure | What skills does |
+|---|---|
+| Framework is `angular` | Dashboard's Visual Builder has no Angular emitter. Surface the one-time explanation note (see "Angular — explicit fallback" above), set `customize=code`, route to the code-driven Angular flow. NEVER call `builder create --platform angular` (the CLI rejects it). |
+| `auth login` token has no `vcb:write` scope | Tell customer their account lacks the add-on; auto-fall-through to In code; do not block. |
+| Customer's network can't reach `apimgmt.cc-cluster-2.io` (corp firewall) | `builder create` errors with network failure; fall back to In code; warn customer the Visual Builder requires outbound HTTPS. |
+| `open` / `xdg-open` / `start` exits non-zero | Treat as soft failure; print URL prominently; continue to wait for "done". |
+| Customer closes the terminal mid-wait | Builder persists server-side. On next `/cometchat` run, the `.cometchat/builder.json` cache triggers the "found existing builder" prompt at the top of 3.1. |
+| Customer says "Done" but didn't actually customize | The builder is never truly empty — `create` returns full defaults (verified 2026-05-19). Emit with what comes back; if they want to tweak later, they use the iteration menu's "Re-sync visual builder" option. |
+| `builder create` returns `ERR_BAD_REQUEST` even with valid `--platform` and a fresh name | The dashboard backend enforces ONE active builder per app — if any prior builder exists and is still "active", subsequent `POST /vcb/builders` calls reject. Detect via `cometchat builder list --json` (if any builder exists, reuse its `builderId` instead of creating new). Surface to the customer: *"Found an existing builder on this app — reusing it. Reset it via the dashboard if you want to start fresh."* Verified against real dashboard 2026-05-21. |
+| Builder ID expired / deleted server-side | `builder fetch` returns `NOT_FOUND`; offer to create fresh or fall to code. |
+| Stale `customize=visual` config from a previous (non-Angular) framework | Overwrite to `customize=code` for the Angular session; surface the Angular note once. Do NOT prompt the customer to "resume" a builder that targets the wrong platform. |
+| Customer is migrating **In-code → Visually** on the same project (existing `src/cometchat/` lowercase dir from a prior In-code integration) | **CASE-COLLISION RISK on macOS APFS / HFS+ default (case-insensitive)** — `src/cometchat/` and `src/CometChat/` resolve to the SAME directory. `cometchat builder export` runs an automatic pre-check: if `src/cometchat/` exists AND contains In-code-shape files (`init.ts` / `CometChatProvider.tsx`) BUT NOT Visual-shape files (`CometChatApp.tsx` + `context/`), it bails with the F25 message and asks the agent to `mv src/cometchat src/cometchat.bak` first. (If the lowercase dir is just the customer's own previous Visual export — `CometChatApp.tsx` + `context/` present — the check skips: that's a resync, not a migration.) F25 finding, 2026-05-22. |
+
 #### 3a. "What are you building?"
 
 If config has `intent` set, confirm it and move on.
@@ -805,11 +1100,11 @@ If `auth me` returned `last_app.industry`, layer the industry-specific upsell on
 
 | Industry value | What to add to the recommendation |
 |---|---|
-| `healthcare` | Mention HIPAA-aware patterns: server-minted auth tokens (NEVER Auth Key), data-masking extension, audit-log retention, recording consent. Point at `cometchat-{family}-production` and `cometchat-features` for the moderation suite. |
+| `healthcare` | Mention HIPAA-aware patterns: server-minted auth tokens (NEVER Auth Key), Moderation Rules API (Profanity / AI Image Moderation / Malware & Virus Scanner — configured via `apply-feature` → `/moderation/rules`, NOT legacy extensions), audit-log retention, recording consent. Point at `cometchat-{family}-production` and `cometchat-features` for the moderation suite. |
 | `dating` | Suggest enabling Profanity Filter + Image Moderation + Sentiment Analysis upfront — dating apps almost always want them. Suggest a "Report user" button next to the message header. |
 | `online_marketplaces` | Confirm the drawer-on-product-page placement (default for marketplace archetype). Suggest enabling Link Preview (buyers share product URLs) and Quick Replies for sellers. |
 | `community_and_social` | Suggest enabling Reactions + Mentions + Threaded Conversations (these are default-on but worth surfacing as design-system colors). Recommend the tab-based "full messenger" placement. |
-| `online_education` | Suggest a `/messages` route + a "Help" button in the navbar (instructor support). Mention Recording for class sessions if calls product is also enabled. |
+| `online_education` | Suggest a `/messages` route + a "Help" button in the navbar (instructor support). Mention Recording for class sessions if calls product is also enabled — but flag that **recording is a paid plan add-on (contact CometChat support to enable; not self-service / no CLI toggle)**. |
 | `events_and_streaming` | Suggest the floating widget for live audience chat. If calls product is enabled, recommend group calls + screen-share for hosts. |
 | `sports_and_gaming` | Suggest tab-based messenger + Reactions + GIPHY/Stipop sticker integration (gamer apps lean heavily on stickers). |
 | `team_comms_and_workflows` | Match Slack-like patterns: dedicated `/messages` route, threaded conversations on, mentions on. Skip the floating widget. |
@@ -931,6 +1226,29 @@ If no auth detected:
 > When you add auth later, run `/cometchat` again and choose
 > 'Set up production auth' to connect them."
 
+##### 3d.1. Confirm the dev-mode UID (ALWAYS ASK — ENG-35717)
+
+After committing to dev mode (whether or not auth was detected), **always ask the user which UID to log in with** before scaffolding. Do not silently pick `cometchat-uid-1` (or `superhero1`, or any other guess) and hard-code it. Two testers reported the agent committing to a default UID without confirming — and one of those defaults was flagged as a **Bot** in their dashboard, which makes auth-key login fail with an opaque error.
+
+The shape:
+
+> "Which UID should I log in as for dev mode? The default is `cometchat-uid-1` — your CometChat app ships with `cometchat-uid-1` through `cometchat-uid-5` pre-seeded so you can chat between browser windows. Use the default, or paste your own UID?"
+
+**Hard caveat — call this out alongside the question whenever you're emitting an auth-key dev login:**
+
+> ⚠️ **If the UID is marked as a "Bot" in the dashboard, auth-key login will fail** with `Auth token creation not allowed for this bot <uid>` and the chat surface will render but not connect. Bot users only accept auth-token login (server-side mint) — the dev auth-key flow refuses them by design. If you hit that error, go to Dashboard → Users → click the UID → toggle the "Bot" switch off, OR pick a non-bot UID. The default `cometchat-uid-1` is NOT a bot in a fresh CometChat app, but if you've reused an app where someone flagged it as a bot earlier, this trap fires.
+
+Use whatever UID the user chooses (or `cometchat-uid-1` if they confirm the default) in the generated `init.ts` / `CometChatProvider`. Do not invent a UID like `superhero1` from older docs — the canonical pre-seeded test users are `cometchat-uid-1` through `cometchat-uid-5`.
+
+> ⚠️ **Only `cometchat-uid-1` … `cometchat-uid-5` are pre-seeded — a custom UID MUST be created before login.** A CometChat app ships exactly these five test users. If the user pastes any other UID (e.g. `alice`, `test-user-7`), it does **not** exist yet, and dev `CometChatUIKit.login(uid)` will fail with **user-not-found** (`ERR_UID_NOT_FOUND` / "user not found"). So: if the chosen UID is **not** one of `cometchat-uid-1..5`, **create it first** before wiring login. The Auth Key can create users (it has create + login scope — see `cometchat-production`'s key table), so create it via the create-user REST call, then log in:
+> ```bash
+> # Create the custom user first (Auth Key works for create — server-side / one-time)
+> curl -X POST "https://<APP_ID>.api-<REGION>.cometchat.io/v3/users" \
+>   -H "apikey: <AUTH_KEY>" -H "Content-Type: application/json" \
+>   -d '{"uid":"<custom-uid>","name":"<Display Name>"}'
+> ```
+> Then `CometChatUIKit.login("<custom-uid>")` succeeds. (The five seeded UIDs skip this — they already exist.) Prefer steering the user to a seeded `cometchat-uid-N` for a quick demo; only create a custom user when they specifically want their own UID.
+
 #### 3e. Ask about user mapping (if auth detected)
 
 If the user has auth AND wants to set up production mode now:
@@ -1093,9 +1411,9 @@ The structured beats make the writing feel like a contract being executed, not a
 4. `cometchat-native-placement` — placement pattern (stack/tab/modal/bottom-sheet/embed)
 
 **For Angular:**
-1. `cometchat-angular-core` — init via `UIKitSettingsBuilder`, `APP_INITIALIZER` pattern, `CUSTOM_ELEMENTS_SCHEMA`, env config in `environment.ts`, login order, anti-patterns
-2. `cometchat-angular-components` — component catalog (kebab-case selectors, `[input]` callbacks vs `(output)` events, content-projection slots, NgModule imports)
-3. `angular` → `cometchat-angular-patterns` — module organization, lazy-loading the chat module, environment file editing, providers
+1. `cometchat-angular-core` — init via `CometChatUIKit.initFromSettings(cometchat-settings.json)` in `main.ts` (recommended; GA in `@cometchat/chat-uikit-angular >= 5.0.3`), or the `UIKitSettingsBuilder` fallback — standalone bootstrap, env config in `environment.ts`, login order, anti-patterns. **v5 is standalone — NO `CUSTOM_ELEMENTS_SCHEMA`, no NgModule** (those are v4 mental models).
+2. `cometchat-angular-components` — component catalog (kebab-case `<cometchat-*>` selectors, `[input]`/`(output)` bindings, view slots, **standalone `imports: []`** — not NgModule)
+3. `angular` → `cometchat-angular-patterns` — standalone providers, `loadComponent` lazy routes, functional route guards, NgZone, environment file editing
 4. `cometchat-angular-placement` — placement pattern (route, modal, drawer, embedded panel)
 
 **For Android — branches by `android_version`:**
@@ -1129,7 +1447,7 @@ If `flutter_version === "v5"`:
 8. `cometchat-flutter-v5-troubleshooting` — pubspec resolution, GetX errors, runtime crashes
 
 If `flutter_version === "v6"`:
-1. `cometchat-flutter-v6-core` — pubspec deps (single `cometchat_chat_uikit:^6.0.0-beta2` package), `UIKitSettingsBuilder`, init, login, message sending. The `enableCalls`/`CallingConfiguration()` knobs live in `cometchat-flutter-v6-calls`.
+1. `cometchat-flutter-v6-core` — pubspec deps (single `cometchat_chat_uikit: ^6.0` package), `UIKitSettingsBuilder`, init, login, message sending. The `enableCalls`/`CallingConfiguration()` knobs live in `cometchat-flutter-v6-calls`.
 2. `cometchat-flutter-v6-components` — full Bloc-driven widget catalog
 3. `cometchat-flutter-v6-conversations` / `-messages` / `-users-groups` / `-calls` — per-widget deep dives
 4. `cometchat-flutter-v6-features` — feature catalog
@@ -1158,6 +1476,12 @@ For projects migrating from V5 to V6, ALSO load `cometchat-flutter-v6-migration`
 
 Execute the confirmed plan. The order of operations is the same for every framework, but the file names + provider shape differ.
 
+**Branch by `customize` (from Step 3.1):**
+
+- `customize=visual` → emit a single `CometChatApp` wrapper that consumes the builder config cached in `.cometchat/builder.json` (the `settings` blob returned by `cometchat builder fetch`). The wrapper is one file per platform (`CometChatApp.tsx` for web/RN, `CometChatApp.kt` for Android, `CometChatApp.swift` for iOS, `cometchat_app.dart` for Flutter); the customer's existing entry file gets a single `<CometChatApp />` mount. Per-framework emit templates are documented in the per-family skills (`cometchat-{family}-core` § "Visual Builder integration"). The CSS-variable / theme overrides the customer chose in the Visual Builder are inlined verbatim — skills does NOT re-derive them. Then skip the framework-specific steps below and go straight to **dependency install** + **environment variables**.
+
+- `customize=code` (default) → run the framework-specific steps below as normal.
+
 **Web — common steps:**
 
 1. **CometChatProvider** — follow the framework skill's provider pattern. Use the correct env var prefix. Module-level `initialized` guard. Mount at the level agreed in Step 3f.
@@ -1238,7 +1562,7 @@ Execute the confirmed plan. The order of operations is the same for every framew
 1. **Migrate credentials to a Dart const file or `--dart-define`** — if `provision setup` wrote a `.env` (Flutter handoff), do the migration documented in Step 2d above. Confirm `lib/cometchat_config.dart` is in `.gitignore` if you go the const-file route.
 2. **Add the cometchat dep** to `pubspec.yaml` and run `flutter pub get`:
    - V5: `cometchat_chat_uikit: ^5.2.14` (and `cometchat_calls_uikit: ^5.0.15` if calls are needed). Both packages live on the Cloudsmith Dart pub registry, so you'll also need a `--hosted-url` flag in your CI scripts: `dart pub add cometchat_chat_uikit:^5.2.14 --hosted-url https://dart.cloudsmith.io/cometchat/cometchat/`.
-   - V6: `cometchat_chat_uikit: ^6.0.0-beta2` (single package — calls fold in).
+   - V6: `cometchat_chat_uikit: ^6.0` (single package — calls fold in).
 3. **Imports — V5 has TWO barrels.** For chat-only V5 apps, only the chat barrel is needed: `import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';`. For V5 + calls, ADD a second import: `import 'package:cometchat_calls_uikit/cometchat_calls_uikit.dart';` — the calls barrel does NOT re-export the chat barrel, so chat widgets aren't reachable through it alone. V6 has ONE barrel: `import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';`.
 4. **Init in `main.dart`** — `CometChatUIKit.init(uiKitSettings: settings, onSuccess: ..., onError: ...)`. V5 and V6 share the same init signature (callback-style); the difference is what comes after — V5 wires GetX controllers; V6 wires `BlocProvider`s. Always set `subscriptionType: CometChatSubscriptionType.allUsers` on the builder.
 5. **Place chat in your app** — Flutter routing is in code (`Navigator.push`/`go_router`/etc.). Wire chat screens into your app's existing navigation. V6 has a dedicated placement skill for route/modal/embed patterns; V5 covers the same ground inside its per-widget skills.
@@ -1263,9 +1587,9 @@ Execute the confirmed plan. The order of operations is the same for every framew
 **Angular — common steps:**
 
 1. **Migrate credentials into `environment.ts`** — if `provision setup` wrote a `.env` (Angular fallback), extend `src/environments/environment.ts` with a `cometchat: { appId, region, authKey }` block. Mirror in `environment.prod.ts` WITHOUT the `authKey` (production uses server-minted auth tokens — see `cometchat-angular-production`).
-2. **Add `CUSTOM_ELEMENTS_SCHEMA`** to the NgModule that hosts CometChat templates — kit atom components (`<cometchat-avatar>`, `<cometchat-status-indicator>`, etc.) are LitElement web components, not Angular standalone modules. Without the schema, Angular throws `Can't bind to '...' since it isn't a known property of 'cometchat-...'`.
-3. **Init service + APP_INITIALIZER** — follow `cometchat-angular-core` § 1-3. `UIKitSettingsBuilder().setAppId().setRegion().setAuthKey().build()`, then `CometChatUIKit.init(settings)` returns a Promise — chain login. Wire as `APP_INITIALIZER` so init completes before any component renders.
-4. **Import the right NgModule(s)** — for the chat-hosting module, add the kit modules from `@cometchat/chat-uikit-angular` (e.g. `CometChatConversations`, `CometChatMessages`) to `imports: []`. `cometchat-angular-components` documents the module name vs. component name pairing.
+2. **No `CUSTOM_ELEMENTS_SCHEMA`** — UI Kit **v5** ships real Angular **standalone components** (not web components). Importing the component class is all that's needed; the schema is a v4 mental model and should NOT be added.
+3. **Init service + APP_INITIALIZER** — follow `cometchat-angular-core` § 1-3. `new UIKitSettingsBuilder().setAppId().setRegion().setAuthKey().build()`, then `CometChatUIKit.init(settings)` returns a Promise — chain login (`login(uid)` takes a bare string in v5). Wire as `APP_INITIALIZER` so init completes before any component renders.
+4. **Import the component classes** — into the host **standalone component's** `imports: []`, e.g. `CometChatConversationsComponent`, `CometChatMessageListComponent` from `@cometchat/chat-uikit-angular`. There is no NgModule and no `*-with-messages` composite in v5 — compose the message components yourself. `cometchat-angular-components` lists the selector ↔ class pairing.
 5. **Wire chat into existing project** — READ each file before modifying. Add the route, nav link, modal trigger.
 6. **Theming** — inject `CometChatThemeService` to control palette/typography. See `cometchat-angular-theming`.
 7. **Install dependencies:**
@@ -1409,41 +1733,54 @@ Then:
 
 ### Step 7 — Iteration menu
 
-Ask the user (preserve this exact shape — `question`, `header`, `multiSelect`, `options[].label`, `options[].description` — agents have varying primitive names but all support this structured form). The option set differs by family — RN has two extra options (push notifications + testing) that don't apply to web.
+**Render this as the interactive picker (the `AskUserQuestion` structured form), NOT a flat "reply with a number" text dump.** The catch: the picker primitive caps at **4 options**, and this menu has 9 (web) / 11 (RN) leaves — so present it as a **two-level picker**: first a **category** picker (≤4 options), then, after the user picks a category, a **sub-picker** (≤4 options) listing that category's actions. Every sub-picker ends with a **"← Back"** option that returns to the category picker; selecting a leaf runs that action and, when it completes, returns to the category picker (until the user picks "I'm done"). Preserve the `question` / `header` / `multiSelect:false` / `options[].label` / `options[].description` shape at both levels. Map answers by **label, not ordinal**.
 
-**Web — 8 canonical options:**
-- **question:** "What would you like to do next?"
-- **header:** "Next step"
-- **multiSelect:** false
+> **Non-picker agents (Codex / Cursor / Gemini CLI / any without the picker primitive):** per the Clarification contract (§top), render the **flat numbered leaf list** instead (all 9/11 leaves, grouped under their category headings) and accept a number or free text. The two-level nesting is a picker-UX nicety, not a semantic requirement — the leaves are identical either way.
+
+**Web — category picker (level 1):**
+- **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."
-
-**RN — 10 canonical options:**
-- **question:** "What would you like to do next?"
-- **header:** "Next step"
-- **multiSelect:** false
+  1. label: "Customize", description: "Themes & brand colors, a component's look, or language & sounds."
+  2. label: "Add to your app", description: "A feature (calls, reactions, polls, AI, …) or a floating chat widget."
+  3. label: "Production & operations", description: "Server-side auth, user management, diagnostics."
+  4. label: "I'm done", description: "Exit."
+
+**Web — sub-pickers (level 2):**
+- **Customize →** (a) "Customize look and feel (themes)" — "Pick a preset (slack, whatsapp, imessage, discord, notion) or set brand colors." · (b) "Customize a component" — "Custom bubbles, headers, composer actions, details views — I'll read the docs and write it." · (c) "Localize & configure sounds" — "Translate the UI / change language and tune notification + call sounds. Read `cometchat-i18n` + `cometchat-theming`/`cometchat-customization`." · (d) "← Back"
+- **Add to your app →** (a) "Add a feature" — "Browse ~35 features — calls, reactions, polls, AI, and more." · (b) "Add a floating chat widget" — "An overlay button + drawer on top of your existing app." · (c) "← Back"
+- **Production & operations →** (a) "Set up production auth" — "Replace the dev Auth Key with a server-side token endpoint. Read `cometchat-production`." · (b) "Set up user management" — "Server endpoints for creating, updating, deleting CometChat users." · (c) "Run diagnostics" — "Check for drift, missing env vars, broken imports." · (d) "← Back"
+
+**RN — category picker (level 1):**
+- **question:** "What would you like to do next?" · **header:** "Next step" · **multiSelect:** false
 - **options:**
-  1. label: "Customize look and feel (themes)", description: "Colors, typography, dark mode — edit CometChatThemeProvider."
-  2. label: "Add a feature", description: "Calls, reactions, polls, extensions, AI agent — browse the catalog."
-  3. label: "Customize a component", description: "Custom bubbles, headers, message composer actions, empty states."
-  4. label: "Add another placement", description: "Add a modal chat, a bottom sheet, or another tab — without touching the existing integration."
-  5. label: "Set up push notifications", description: "APNs + FCM setup, CometChat dashboard config, client registration, tap-to-deep-link. Required for production."
-  6. label: "Set up production auth", description: "Replace the dev Auth Key with a server-minted auth token. Read `cometchat-native-production` skill."
-  7. label: "Set up user management", description: "Server endpoints for creating, updating, deleting CometChat users."
-  8. label: "Set up testing", description: "Jest + React Native Testing Library setup, mocks for the UI Kit / SDK, E2E with Detox or Maestro."
-  9. label: "Troubleshoot an issue", description: "Metro cache, pod install, iOS privacy manifest, push notifications, native module linking."
-  10. label: "I'm done", description: "Exit."
+  1. label: "Customize", description: "Themes, a component, or language & sounds."
+  2. label: "Add to your app", description: "A feature or another chat placement."
+  3. label: "Production & operations", description: "Push notifications, auth, user management, testing."
+  4. label: "Troubleshoot or finish", description: "Fix an issue, or exit."
+
+**RN — sub-pickers (level 2):**
+- **Customize →** (a) "Customize look and feel (themes)" — "Colors, typography, dark mode — edit CometChatThemeProvider." · (b) "Customize a component" — "Custom bubbles, headers, message composer actions, empty states." · (c) "Localize & configure sounds" — "Translate the UI / change language and tune notification + call sounds. Read `cometchat-i18n` + `cometchat-native-theming`." · (d) "← Back"
+- **Add to your app →** (a) "Add a feature" — "Calls, reactions, polls, extensions, AI agent — browse the catalog." · (b) "Add another placement" — "Add a modal chat, a bottom sheet, or another tab — without touching the existing integration." · (c) "← Back"
+- **Production & operations →** (a) "Set up push notifications" — "APNs + FCM setup, CometChat dashboard config, client registration, tap-to-deep-link. Required for production." · (b) "Set up production auth" — "Replace the dev Auth Key with a server-minted auth token. Read `cometchat-native-production`." · (c) "Set up user management" — "Server endpoints for creating, updating, deleting CometChat users." · (d) "Set up testing" — "Jest + React Native Testing Library setup, mocks for the UI Kit / SDK, E2E with Detox or Maestro." · (e) "← Back" *(this category has 4 actions + Back = 5; if your picker is hard-capped at 4, drop "Set up testing" to a follow-up "More…" entry or surface it via free-text — never silently omit it)*
+- **Troubleshoot or finish →** (a) "Troubleshoot an issue" — "Metro cache, pod install, iOS privacy manifest, push notifications, native module linking." · (b) "I'm done" — "Exit." · (c) "← Back"
+
+**Visual Builder option (conditional — only if `.cometchat/builder.json` exists):**
+
+If `.cometchat/builder.json` is present in the project (the customer picked Visually in Step 3.1), add an extra leaf **under the "Customize" category sub-picker** (it's a customization action):
+
+- label: "Re-sync visual builder", description: "Re-fetch your latest builder customizations from the dashboard and update the emitted code. Use this after you've gone back to the browser and tweaked colors / features / layout."
+
+When selected:
+1. Read `.cometchat/builder.json` to learn the platform.
+2. Surface to customer: *"This will re-download the latest Visual Builder template + your current settings, and replace the `src/CometChat/` directory entirely. Customer hand-edits inside that directory will be lost (per the SKILLS-AUTO-GENERATED contract). Continue?"* via `AskUserQuestion` (Continue / Cancel).
+3. On Continue: run `cometchat builder export --platform <p> --force --json` via Bash. The `--force` flag is required (it explicitly authorizes replacing the existing directory).
+4. Parse the returned JSON. On `status: "exported"`, surface a brief summary: *"Re-synced from builder `<builderId>`. Latest sync: `<settings_file>`."*
+5. Run `cometchat verify --builder --json` to confirm the integration is still intact (settings file valid, canonical wrappers present, entry file wired, deps declared).
+6. Re-render the iteration menu.
 
 For **theme customization**: read the framework-appropriate theming skill and write the customization code.
 
-For **adding features**: read the framework-appropriate features skill. Features fall into six buckets:
+For **adding features**: read the framework-appropriate features skill. The canonical public decision-reference for *which integration method (UI Kit / UI Kit Builder / Widget Builder / SDK) supports a feature, what dashboard setup it needs, and whether code is required* is the **[Features & Extensions Guide](https://www.cometchat.com/docs/fundamentals/features-and-extensions-guide)** — consult it (WebFetch or docs MCP) for any "can the builder do X? / is feature Y code-or-dashboard?" question; it outranks the local `catalog.json` snapshot when they disagree. Features fall into eight buckets (matching the catalog `type` field and `apply-feature`'s dispatch):
 
   - **default** — already enabled by the UI Kit, no action needed.
   - **extension** — pure boolean toggle. Run `cometchat apply-feature <id>` (web/RN with `state.json`) or `cometchat apply-feature <id> --app-id <X>` (native cohorts: iOS / Android / Flutter / Angular). Hits the dashboard API; no browser visit required.
@@ -1451,9 +1788,13 @@ For **adding features**: read the framework-appropriate features skill. Features
   - **dashboard-only** — third-party API keys / multi-field config (Giphy, Stipop, Tenor, Chatwoot, Intercom, Disappearing Messages, Message Shortcuts). The CLI returns `manual-action-required` and prints the dashboard path — these genuinely need the user to configure third-party credentials.
   - **package-install** — calls. Run `npm install @cometchat/calls-sdk-javascript` (or the framework's calls SDK).
   - **component-swap** — `rich-text-formatting`. Run `cometchat apply-feature rich-text-formatting`.
+  - **calls-feature** — voice/video calling sub-features (`screen-share`, `virtual-background`, `call-recording`, etc.). `apply-feature` verifies the calls SDK is installed + the platform supports it, then records the choice and points at the family's `cometchat-*-calls` reference; the actual wiring is a `CallSettingsBuilder` flag in code. **⚠ `call-recording` is a PAID plan add-on — there is NO dashboard toggle / API call the CLI can flip; the user must contact CometChat support to enable it on their plan.** Never claim recording was "enabled."
+  - **moderation** — profanity/image-moderation/data-masking/etc. Run `cometchat apply-feature <id> --config-json <…>` — it `PUT`s the rule config then enables via the `/moderation/rules` Rules API (NOT the legacy extensions). Returns `config-required` if no config is supplied.
 
   Ask which feature, look it up in `packages/registry/v6/features/catalog.json` (or run `cometchat features info <id>`) to learn its bucket, then execute the right recipe. **Never tell the user to "open the dashboard and flip a toggle" for an extension or ai-feature** — that's what `cometchat apply-feature <id>` does for them.
 
+  > **Enable-features on a Visual-Builder (Visually) project — two layers, both required.** `apply-feature` and the Visual Builder operate on **independent backend stores**: `apply-feature` toggles the **dashboard extension** (server-side capability — `/apps/{appId}/extensions`); the builder's `chatFeatures` toggle controls whether the feature's **UI** is shown in the *exported builder app* (`/vcb/builders/{id}`). They compose, but they're complementary — for an extension/AI-backed feature on a Visually-customized project you need *both*: (1) `apply-feature <id>` for the capability, and (2) the builder's toggle ON so the exported UI actually surfaces it. If the customer enabled an extension via `apply-feature` but the builder app doesn't show it, the builder toggle is OFF → have them flip it in the Visual Builder and **re-sync** (`builder export --force`). Because the two stores are independent, `apply-feature`'d extensions **always survive a resync** — `builder export` never reads or writes the extensions store. (On the In-code path there's no builder: `apply-feature` is sufficient because the UI Kit's `defaultExtensions[]` auto-surfaces any enabled extension.)
+
 For **component customization**: read the customization + components skills, then write the customization code directly. Ask the user what they want to customize, read the relevant component's props from the catalog, propose changes.
 
 For **production auth**: read the framework-appropriate production skill. It's interactive — ask the user about their auth system and generate the server-side token endpoint for their backend.
@@ -1476,6 +1817,36 @@ After every Phase B action completes, you **MUST** re-render the menu via your a
 
 The iteration loop is the whole point of Phase B. Re-rendering the canonical menu via your agent's structured-question primitive after every action is how the user controls the session.
 
+### Step 8 — Self-verification before declaring success
+
+**This is a process-level audit — distinct from the per-framework build verification in Step 6.** Before saying "done", "integration complete", or rendering the iteration menu, run through this checklist mentally. Each item targets a silent-skip failure mode that has bitten real testers in Round 1 (ENG-3571x cluster). Any "no" answer means the skill was misapplied — fix before declaring success.
+
+> **Why this exists:** Round-1 testers reported 8+ incidents where the build succeeded but the agent had silently skipped a load-bearing process step (Step 1.5 "I see you" omitted, Step 3.1 prompt skipped, plan never confirmed, env-var pre-flight bypassed, RN-bare "done" lying without a smoke test). Build-output verification catches compile errors. This checklist catches process-skip errors — which are the ones that ship to customers.
+
+**Process checks (must all be YES):**
+
+- [ ] **Step 1.5 "I see you" moment** — Did I render 3–5 specific, observation-grounded bullets about the user's project BEFORE asking any question? (Not generic — must cite actual files/deps/router config I read in Step 1.)
+- [ ] **Step 2 credentials confirmed** — Did I run `npx @cometchat/skills-cli config show --json` AFTER Step 2 and verify `appId` is non-empty + the env file exists + contains the framework-appropriate keys? (No silent moves past empty credentials.)
+- [ ] **Step 2b.5/2b.6 dashboard prompts** — On signup paths, did I render the structured `AskUserQuestion` prompts for role, intent, app name, region, industry? (No silent defaults — auto-mode does NOT authorize bypass.)
+- [ ] **Step 3.0 product branch** — Did I resolve product (chat / calls / both) via auth-me OR natural-language inference OR an explicit `AskUserQuestion`? (If both inference paths returned null, the prompt MUST have fired — non-negotiable.)
+- [ ] **Step 3.1 customize prompt** — On supported platforms (`reactjs`, `nextjs`, `react-router`, `astro`, `expo`, `react-native`, `angular`, `android`, `flutter`), did I render the Visually-vs-In-code prompt? (Or surface the explicit fallback note for unsupported platforms like Pages Router + Astro?) Common skip-bug: doing 3a + 3c without 3.1 — observed 2026-05-22 on a real Android run.
+- [ ] **Step 3d.1 UID confirmation** — Did I ask the user which UID to log in as (with the bot-caveat warning), OR did I silently default to `cometchat-uid-1`? (ENG-35717 — silent default is the bug.)
+- [ ] **Step 3f trust-contract plan** — Did I render the three-section plan (Files I'll create / Files I'll modify / Files I won't touch) + dependencies + auth mode + estimated time, and did the user say "go" before any file write?
+- [ ] **Step 5 state.json written** — Did I write `.cometchat/state.json` with `files_owned` + `files_patched` after the implementation completed? (Required for Step 7 iteration menu to detect prior integration.)
+- [ ] **Step 6 verification** — Did I run the framework-appropriate build command (`tsc --noEmit` / `npm run build` / `flutter analyze` / `./gradlew :app:assembleDebug` / `xcodebuild build`) and confirm success?
+- [ ] **RN-bare smoke** (if applicable) — Did I additionally run `pod install` + `npx react-native run-{ios,android}` and confirm Metro bundle reached 100%? (RN-bare "done" lies are the canonical regression — ENG-35718.)
+- [ ] **Step 7 iteration menu** — Did I re-render the canonical menu via `AskUserQuestion` (8 options web / 11 options RN — verbatim labels and descriptions) AFTER the action completed?
+
+**Rationalization checks (if any of these crossed my mind, I skipped a rule):**
+
+- "The user said 'just do it' / 'I trust you, skip the plan'" → Step 3f plan confirmation is the trust contract; skip it and a regression will silently break their existing surfaces (ENG-35713 location-sharing-wipes-attachments). Always show the plan.
+- "Pattern skills are probably loaded, I won't check" → Step 1 pattern-skill-presence check (cometchat-react-patterns etc.) is non-optional; if absent, the agent writes from training memory + emits the bugs the patterns explicitly prevent.
+- "The user is in auto-mode / seems impatient, so I'll skip the prompt" → Auto-mode authorizes Bash approvals, NOT structured-question bypasses. Surface every required prompt regardless.
+- "I already know this framework, I can skip framework-specific patterns skill" → Pattern skills carry version-pinned traps (e.g. Next.js 15+ `dynamic(ssr:false)` Client-Component rule, RN doc-picker GuardedResultAsyncTask swap) that don't exist in training data. ALWAYS read the patterns skill before emitting code for that framework.
+- "I'll write code now and migrate to production-auth later" → Production-auth migration is a SEPARATE iteration-menu action with its own skill (`cometchat-{family}-production`). Wire dev mode first, surface the production-upgrade path explicitly, let the user choose when to do it.
+
+If ANY of those rationalizations matches what I was about to do, STOP and apply the skipped rule before continuing.
+
 ## Hard rules
 
 ### Always (every framework)
@@ -1488,8 +1859,20 @@ The iteration loop is the whole point of Phase B. Re-rendering the canonical men
 - ALWAYS show the plan (Step 3f) and get confirmation before writing.
 - **Every `<CometChatMessageList>` must pass `hideReplyInThreadOption={true}`** unless the user has explicitly opted into thread support and you've built the thread screen too. Without it, tapping a message shows a "Reply in Thread" action that leads to a broken (undefined) thread view.
 - **NEVER build a custom search UI.** The UI Kit ships `<CometChatSearch>` — full dual-scope search across conversations + messages with built-in filter chips, pagination, and result highlighting. Any request involving "search", "find messages", "search conversations" MUST use the built-in component (and `showSearchBar` / `onSearchBarClicked` on `CometChatConversations` for web; `hideSearch={false}` for RN). Do NOT create custom search bars, hand-rolled result lists, or filter UIs.
+- **Check the kit catalog FIRST — do not invent custom UI when the kit has it.** Before writing any custom component, sidebar, back button, header action, user/group details panel, or action sheet, look up the framework's `*-components` skill and confirm whether the kit already ships that surface. Testers found the agent rebuilding things the kit already provides — custom search bars, custom back buttons, custom user/group details views — leading to inconsistent UX + extra code that then breaks at edge cases. Rule: enumerate kit options, name the one you'll use, then write code. If the kit genuinely doesn't have it, say so explicitly before building custom (ENG-35712).
+- **Preserve existing functionality when adding features.** Before adding a new feature (e.g. location-sharing, custom message type), re-list what's already integrated (attachments, polls, message history, composer extensions) and confirm the addition is additive. If the change *would* remove or override an existing surface, surface that to the user as a warning and get explicit consent. Testers found that adding location-sharing wiped out the attachment menu + polls + visible message history — that's a regression the agent must not introduce silently (ENG-35713).
+- **Split multi-axis customization prompts into sequenced single-axis ops.** When a user prompt bundles multiple changes ("change the receiver bubble color AND show time on the side instead of bottom AND change the sender content view"), don't try to satisfy them all in one edit — testers got the wrong fields swapped (sender vs receiver, whole bubble vs content view). Restate the changes back as a numbered list, confirm, and apply one at a time, verifying each before moving on. Honor the bubble-override / content-view distinction explicitly (ENG-35713).
+- **Default to file-per-concern, NOT single-file (ENG-35715).** Scaffold provider, init, components, and screens as separate files in a `cometchat/` (web/Angular/RN) or `<package>/cometchat/` (Android/Flutter/iOS) folder. ONLY collapse to a single file when the developer explicitly opts in ("just give me one file" / "single-file demo"). The default plan in Step 3f already lists 3-5 files — keep it that way; testers complained that some quick-start paths dumped everything into `App.tsx` and made it impossible to refactor later. When in doubt, ask: *"Should I split this into multiple files (provider / init / screens) or keep it in a single file for the demo?"*
+- **Auto dark/light theme is the default, NOT a follow-up prompt (ENG-35715).** Every kit ships a theme system that switches by OS color scheme — the React kit's `<CometChatThemeProvider>`, the RN kit's `useColorScheme()`-driven theme, Android's `CometChatTheme.DayNight` parent style, Flutter's `CometChatThemeMode.system`, iOS's `traitCollection.userInterfaceStyle`. The scaffold MUST wire this on the first pass without asking. If the developer explicitly says "light mode only" or "dark mode only," then pin; otherwise honor the OS. Testers found that the agent only applied one theme until they manually asked for dark mode — fix that by defaulting to system.
+- **Provider exposes a `telemetry` callback prop for init/login lifecycle (ENG-35715).** When generating any provider (`CometChatProvider.tsx` / `CometChatModule.ts` / Android `CometChatInitProvider.kt` / Flutter `CometChatBootstrap`), accept an optional `telemetry?: (event: TelemetryEvent) => void` prop and fire it at four phases: `init_started`, `init_finished`, `login_started`, `login_finished` — plus `init_failed` / `login_failed` with the error payload. Developers want this for their own analytics; without the hook they have to monkey-patch the kit or wrap every method. The hook is opt-in (do nothing if not passed) so it doesn't bloat the happy path.
+- **Confirm `appId` + `region` + `authKey` are populated BEFORE Step 5 code emission (ENG-35718).** Two testers shipped code with empty `import.meta.env.VITE_COMETCHAT_APP_ID` values because the agent moved on without confirming the env file was actually written. Pre-flight check after Step 2 / before Step 4 — run `npx @cometchat/skills-cli config show --json`, verify `appId` is non-empty AND the env file referenced exists AND the file contains the three keys. **For Angular/Android/Flutter/iOS this pre-flight checks the handoff `.env` that `provision setup` writes — NOT the platform-native file** (`environment.ts` / `local.properties` / Dart const / `Secrets.swift`), because the migration into that native file happens later in Step 5. Verify the native runtime file has the values as a *separate, post-migration* check at the end of Step 5 (a re-run of this gate after migration is fine — it then accepts the native file). If any check fails, STOP and prompt: *"Your credentials aren't in `<envFile>` yet. Paste them now or run `auth login` to fetch them, then I'll continue."* Do NOT proceed silently.
+- **Pull dashboard feature state BEFORE recommending what to enable (ENG-35716).** Before suggesting "do you want to turn on reactions / polls / message-translation / AI-replies", run `npx @cometchat/skills-cli features list --json` (or `features get --json --feature <name>` for one), parse the response, and **lead with what's already enabled vs disabled** in the user's dashboard. Two testers complained: the agent claimed features were "not implemented" and asked them to enable manually, while their dashboard had them on already. Rule: read dashboard state first, recommend deltas (turn ON the ones the user wants that are currently OFF), and TELL the user what's already on so they don't waste a round-trip enabling something live.
+- **Auto-resolve credentials from `auth me` / `provision list` when the user is already logged in (ENG-35716).** If `auth status --json` returns `"logged-in"` AND the env file is missing or empty, run `provision list --json` to see if the user has an existing app on the dashboard. If exactly one, suggest using it: *"You're already logged in and your dashboard has the app `<app.name>` (region `<app.region>`). Use those credentials? [Y/n]"* — then `provision setup --app-id <id> --json` writes the env file. The user shouldn't have to copy-paste credentials they already have in their account.
+- **RN-bare integrations require a smoke-test before declaring success (ENG-35718).** "Done" lying on RN bare is the canonical "app didn't even run once" failure. After the last file write, the dispatcher MUST attempt: (a) `cd ios && pod install && cd ..` (iOS), (b) `npx react-native run-ios --no-packager` OR `npx react-native run-android` (whichever the user wants first), (c) tail the Metro output for *"BUNDLE → 100%"* and the first frame render in the simulator/emulator. If pods install fails or Metro errors mid-bundle, surface the raw error and DON'T declare success. Bare RN is the family with the most "looks done but broken" failures because there are 8+ moving parts (Cocoapods, Hermes, autolinking, gesture-handler, reanimated, async-storage native modules, Metro cache). One smoke is worth the 2-minute wait.
+- **Fuzzy-match free-form answers before rejecting them (ENG-35724).** When the user types a value that isn't in the structured-prompt enum — e.g. *"chatting"* for the industry picker, *"shop"* for marketplace, *"video meet"* for voice-video — DO NOT bounce them back to the picker. Map to the closest enum value, restate it back, and confirm: *"By 'chatting' I think you mean Community & Social — does that match? [Y/n]"*. One round-trip saved per prompt. Use the structured form's `options[].label` + `options[].description` as the match corpus; cosine-similarity on the lowercase tokens or a simple substring + synonym table is enough — the agent can do this in-line without an external tool. If similarity is below a confidence threshold (say, < 0.4), then ask the user to pick from the list — but explain the rejection: *"I couldn't tell which of these fits — could you pick one?"*.
+- **Emitted code must be lint-clean for the project's lint config (ENG-35724).** Every `.ts` / `.tsx` / `.kt` / `.swift` / `.dart` the agent writes should pass the user's existing `eslint` / `tsc --noEmit` / `ktlint` / `swiftlint` / `dart analyze` with zero new warnings or info-level issues. Before declaring success, run the project's lint command (read `package.json`'s `scripts.lint` or use sane defaults: `npx eslint .` for JS, `flutter analyze` for Flutter, etc.). If new warnings appear from kit imports the user can't suppress, document them in a one-line `// eslint-disable-next-line <rule>` comment with a reason — DON'T leave noise that the user has to clean up. Testers complained that every scaffold introduced 5–15 info-level lints that pile up if multiple features are added in sequence.
 - For component names and props, use the framework-appropriate `*-components` skill or docs MCP — never invent from training data.
-- After writing code, record state in `.cometchat/state.json` (Step 5 step 11) so the iteration menu can detect the integration in a future session.
+- After writing code, record state in `.cometchat/state.json` (Step 5 step 11) so the iteration menu can detect the integration in a future session. **Timing:** record AFTER the RN-bare smoke-test passes (when one is required by the rule above); for all other frameworks, record immediately after the final file write. If the smoke-test fails, do NOT write state.json yet — fix the failure first, then record once the build succeeds.
 - **NEVER explicitly load CometChat skills via your agent's skill-loading mechanism.** They're already in your context as `.claude/skills/`, `.cursor/skills/`, `.kiro/skills/`, or `.agents/skills/` files. Just read and follow them directly.
 
 ### Web only
@@ -1509,9 +1892,9 @@ The iteration loop is the whole point of Phase B. Re-rendering the canonical men
 - **Credentials live in `src/environments/environment.ts`, NOT `.env`.** Angular bundles `environment.ts` at compile time; there is no runtime `.env` lookup. The CLI's `provision setup --framework angular` writes a `.env` only as a credentials handoff — migrate the values into `environment.ts` (and `environment.prod.ts` minus the `authKey`) during integration.
 - **Init runs through `APP_INITIALIZER`, not a wrapper component.** Angular has no React-style provider tree — `CometChatUIKit.init(settings)` must complete before any chat component renders. Wire it as `{ provide: APP_INITIALIZER, useFactory, deps: [...], multi: true }` in the root module.
 - **Login API is `CometChatUIKit.login({ uid })` (object form), NOT a bare string.** Same shape as the React Native UI Kit. Calling `CometChatUIKit.login("cometchat-uid-1")` silently fails on Angular too — always pass the credentials object: `login({ uid })` for dev, `login({ authToken })` for production.
-- **Events are `[onX]` Input callbacks, not `(onX)` Output bindings.** The Angular UI Kit declares almost no `@Output` — events like `onSendButtonClick`, `onAccept`, `onItemClick` are `@Input()` callback functions. Writing `(onAccept)="handleAccept()"` silently no-ops or fails template type checking.
+- **Angular v5 kit has TWO event-binding patterns (corrected 2026-06-02 — was wrong in v4 era).** New-style event names (no `on*` prefix) are `@Output()` — bind with **round brackets**: `(itemClick)="handler($event)"`, `(closeClick)`, `(sendButtonClick)`, `(threadRepliesClick)`, `(textChange)`, `(backClick)`, `(conversationClick)`, etc. Legacy `on*`-prefix names that still exist as `@Input()` callbacks are: `onAccept`, `onDecline`, `onVoiceCallClick`, `onVideoCallClick`, `onError`, `onSuccess` — bind with **square brackets**: `[onError]="handlerFn"`. Names like `onItemClick`, `onSendButtonClick`, `onThreadRepliesClick`, `onTextChange`, `onCloseClicked` **do not exist at all in v5** — use the round-bracket Output form above. See `cometchat-angular-components` §"Binding conventions" for the full mapping.
 - **`[messagesRequestBuilder]` is plural.** `[messageRequestBuilder]` (singular) on `<cometchat-message-list>` silently no-ops — the input doesn't exist.
-- **Match the kit's `auxilaryButtonView` typo** on `<cometchat-message-composer>` (missing first 'i'). The corrected spelling `auxiliaryButtonView` does not exist in the kit and silently no-ops.
+- **`auxiliaryButtonView` is correctly spelled (two i's) — corrected 2026-06-02.** Earlier versions of this rule said to "match a kit typo `auxilaryButtonView`" — that was wrong. The kit (`cometchat-message-composer.component.ts`) uses the correctly-spelled `auxiliaryButtonView` and earlier `auxilary`-typo claims were the source of confusion, not the kit.
 - **`CometChatThemeService` is the v4 theme entry point**, NOT the legacy v3 `CometChatTheme` class. Inject the service; access `themeService.theme` for palette/typography control.
 
 ### Android only
@@ -1530,7 +1913,7 @@ The iteration loop is the whole point of Phase B. Re-rendering the canonical men
 
 ### Flutter only
 
-- **Never mix V5 and V6 packages.** `cometchat_chat_uikit:^5.2` (V5, GetX-based, calls in a separate `cometchat_calls_uikit:^5.0` package) and `cometchat_chat_uikit:^6.0.0-beta2` (V6, Bloc-based, calls bundled in) are different SDKs with different state-management primitives, theme APIs, and barrel exports. The skills target one cohort each — pick V5 for production, V6 for beta evaluation, never both.
+- **Never mix V5 and V6 packages.** `cometchat_chat_uikit:^5.2` (V5, GetX-based, calls in a separate `cometchat_calls_uikit:^5.0` package) and `cometchat_chat_uikit: ^6.0` (V6, Bloc-based, calls bundled in) are different SDKs with different state-management primitives, theme APIs, and barrel exports. The skills target one cohort each — pick V6 for new projects, V5 for legacy projects, never both in the same app.
 - **V5 has TWO barrels; V6 has ONE.** V5 chat widgets (`CometChatConversations`, `CometChatMessageList`, `CometChatMessageComposer`) are reachable ONLY through `package:cometchat_chat_uikit/cometchat_chat_uikit.dart`. The calls package barrel re-exports `cometchat_uikit_shared` + `cometchat_sdk` + `cometchat_calls_sdk` but NOT `cometchat_chat_uikit` — using only the calls import will fail to resolve chat widgets. V6 ships a single package, so the chat barrel covers both chat AND calls.
 - **`subscriptionType` is required on `UIKitSettingsBuilder`.** Omitting it silently disables presence and typing-indicator events — no error is thrown, just no presence updates. Always set `..subscriptionType = CometChatSubscriptionType.allUsers` (or `..forFriends` / `..forRoles`).
 - **`CometChatUIKit.login(uid)` takes a String, not an object.** Both V5 and V6 use the bare-string form for dev login. For production: `CometChatUIKit.loginWithAuthToken(token, ...)`.
@@ -1538,7 +1921,7 @@ The iteration loop is the whole point of Phase B. Re-rendering the canonical men
 - **Listener IDs must be unique + removed in `dispose()`.** Hardcoded listener IDs collide across screens; missing `dispose()` removal leaks listeners across navigations. Use a per-instance ID and remove it on teardown.
 - **Credentials live in a Dart const file or `--dart-define`, NOT `.env`.** Flutter doesn't read `.env` at runtime; the CLI's `provision setup --framework flutter` writes a `.env` only as a credentials handoff — migrate during Step 5.
 - **`ComponentToggles` and `CallScreenOverlay` do not exist in V6.** Per-widget feature flags (e.g. `disableReactions`, `hideReplyInThreadOption`) replace v5's `BuilderSettings`. In-call UI is `CometChatOngoingCall` widget + `CometChatDisplayIncomingCallOverlay`, not an overlay class with `.show()`.
-- **AI widget availability varies across V6 betas.** Some AI widgets (`CometChatAIAssistantChatHistory`, `CometChatAIConversationSummary`) are exported in `6.0.0-beta2`; others may not be. If an import errors with "undefined name", the symbol isn't in that beta. Drive AI features via dashboard-enabled extensions for the most stable path — the kit surfaces AI replies/summaries inside the existing message list and composer regardless.
+- **AI widget availability varies across V6 versions.** Some AI widgets (`CometChatAIAssistantChatHistory`, `CometChatAIConversationSummary`) are exported in 6.0.1 (the GA cut); others were added in later patches or are still rolling out. If an import errors with "undefined name", the symbol isn't in that version. Drive AI features via dashboard-enabled extensions for the most stable path — the kit surfaces AI replies/summaries inside the existing message list and composer regardless.
 - **V6 conversations slot signatures are asymmetric.** `subtitleView` / `leadingView` / `titleView` take `(BuildContext, Conversation)` (two-arg). `trailingView` and `listItemView` take just `(Conversation)` (single-arg). Match the source — guessing one shape across all four breaks template type-checking. See `cometchat-flutter-v6-conversations` for the example.
 - **`PNRegistry` is sample-app code, not a kit API.** The kit's only public push surface is `CometChatNotifications.registerPushToken(token, providerId, platform)` and `unregisterPushToken()`. Use the kit API directly, or copy the sample-app `PNRegistry` helper into your project.
 
@@ -1550,7 +1933,7 @@ The iteration loop is the whole point of Phase B. Re-rendering the canonical men
 - **App theme parent is irrelevant on iOS** — but pod-side: Xcode 15+ requires `ENABLE_USER_SCRIPT_SANDBOXING = NO` in Build Settings (or the `post_install` Podfile hook). Without it, the resource-bundle build phase silently fails and assets/strings load empty at runtime.
 - **`pod 'CometChatUIKitSwift', '~> 5.1'`**, NOT `~> 5.0` — the binary target ships at 5.1.x (5.1.12 at last verification); the older pin would resolve to a stale subrelease.
 - **`CometChatLocalize.set(key:value:)` does not exist.** Public API is locale-only: `set(locale: Language)` / `set(locale: String)`. Override individual keys via your app's `Localizable.strings` instead.
-- **`CometChatTypography.setFont(name:)` is a class func**, not a settable `fontFamily` property. `CometChatTypography.fontFamily = "Avenir"` does not compile.
+- **iOS font override uses `overrideFont(family:)` on the `Typography` struct (corrected 2026-06-02).** Verified at `cometchat-uikit-ios-v5/CometChatUIKitSwift/Components/Shared/Helpers/CometChatTheme/Typography.swift:108`: the actual API is `mutating func overrideFont(family: CometChatFontFamily)` on the `Typography` struct value — NOT `CometChatTypography.setFont(name:)` as earlier versions of this rule claimed. To customize fonts: instantiate a `CometChatFontFamily` (with regular/medium/semibold/bold faces) then call `myTypography.overrideFont(family: customFamily)`. `CometChatTypography.fontFamily = "Avenir"` does not compile either way.
 - **`CometChatGroupMembers()` takes zero args**; pass the group via `set(group:)`. There is no `CometChatGroupMembers(group:)` initializer.
 - **`CometChatCallButtons(width:height:)` requires explicit dimensions**; there is no zero-arg initializer.
 - **`CometChatThreadHeader` does NOT exist** — the real class is `CometChatThreadedMessageHeader`.
@@ -1642,7 +2025,7 @@ Not required for integration or Phase B CLI flows.
 | `cometchat-android-v5-testing` | When adding tests (Espresso, Robolectric, mocking the kit/SDK) |
 | `cometchat-android-v5-troubleshooting` | When diagnosing problems (Gradle, manifest, ProGuard, lifecycle) |
 
-### Android V6 family (beta — `chatuikit-{compose,kotlin}-android:6.x`)
+### Android V6 family (stable, GA 2026-05-25 — `chatuikit-{compose,kotlin}-android:6.x`)
 
 | Skill | When to load |
 |---|---|
@@ -1682,7 +2065,7 @@ Not required for integration or Phase B CLI flows.
 | `cometchat-flutter-v5-push` | When setting up FCM / APNs / VoIP push |
 | `cometchat-flutter-v5-troubleshooting` | When diagnosing problems (pubspec, GetX, Pod errors, runtime crashes) |
 
-### Flutter V6 family (beta — `cometchat_chat_uikit:^6.0.0-beta2`)
+### Flutter V6 family (stable, GA 2026-05-25 — `cometchat_chat_uikit: ^6.0`)
 
 | Skill | When to load |
 |---|---|