@cometchat/skills 4.4.2 → 5.0.0

package/skills/cometchat-flutter-v6-core/SKILL.md

@@ -1,643 +1,204 @@
 ---
 name: cometchat-flutter-v6-core
-description: >
-  Use when writing any code that uses cometchat_chat_uikit. Contains hard rules that prevent
-  silent failures, crashes, and subtle bugs. Covers CometChatUIKit.init, login, logout,
-  UIKitSettings, UIKitSettingsBuilder, listener lifecycle, theme caching, Scaffold
-  resizeToAvoidBottomInset, subscriptionType, region, muid preservation, and the
-  Clean Architecture + BLoC component pattern. Also use when seeing errors like
-  "Authentication null", "APP ID null", ERR_ALREADY_LOGGED_IN, or StateError from
-  uninitialized ServiceLocator. Make sure to use this skill for any CometChat Flutter
-  UIKit code, even simple widget usage.
+description: "Add CometChat chat to a Flutter app end-to-end — detect the project, get & verify dashboard credentials, init→login→render, and the drop-in conversation UI. The core knowledge every other Flutter v6 skill builds on. Triggers: 'add chat to my flutter app', 'integrate cometchat flutter', 'set up cometchat credentials flutter', 'show conversations and messages in flutter'."
 license: "MIT"
-compatibility: "cometchat_chat_uikit ^6.0.1; flutter_bloc ^8.1.0. File-based init (CometChatUIKit.initFromSettings + project-root cometchat-settings.json — ENG-35866 Skills Telemetry) requires cometchat_chat_uikit >= 6.0.3; on older UIKit use the UIKitSettingsBuilder fallback."
+compatibility: "Flutter >=3.38.9; Dart >=3.10.8 <4.0.0; cometchat_chat_uikit ^6 (6.1.x, verified 6.1.0); cometchat_sdk ^5.0.6; cometchat_calls_sdk ^5.0.4 (calls only)"
 metadata:
   author: "CometChat"
-  version: "3.0.0"
-  tags: "cometchat flutter core rules init login logout lifecycle"
+  version: "1.0.0"
+  tags: "cometchat flutter core chat integration uikit v6 setup credentials"
 ---
 
-# CometChat Flutter UIKit — Core Rules
+> **Ground truth:** `cometchat_chat_uikit@6` (6.1.0) + `cometchat_sdk@^5.0.6`. Every `CometChat*` symbol here is in `catalogs/flutter-v6.json` — **compiler-verified** against the published package. Signatures marked **[verified]** were compiled because the docs were **wrong**, or (for `initFromSettings`) deliberately **silent** (`DOCS-BACKLOG.md` PART 4): trust this file for those, fetch the rest via `references/docs-map.md`. THIN map loaded every run; depth in `references/*`.
 
-> **Ground truth:** `cometchat_chat_uikit: ^6.0` (calls folded in; transitively `cometchat_sdk ^5` + `cometchat_calls_sdk ^5.0.2`) — the pub-cache package source + `docs/ui-kit/flutter`. **Official docs:** https://www.cometchat.com/docs/ui-kit/flutter/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP). Verify Dart symbols against the resolved package source before relying on them.
+<!-- core is the companion the other flutter v6 skills read; it has no Companion block of its own. -->
 
-Non-negotiable constraints for all CometChat UIKit code. Violating these causes silent failures or crashes.
+## Use this skill when
+"add chat to my Flutter app", "integrate CometChat in Flutter", "set up CometChat credentials", "show a conversations + messages screen". An unscoped **"add chat"** means a **production-ready core surface** — a `CometChatConversations` screen pushing a message screen, with **threaded replies** and **search** wired, in `Scaffold`/`SafeArea`, keyboard-safe, every screen popping back — NOT a two-widget demo, NOT the whole tab-based app (see the golden path). It **grows on request** → `cometchat-flutter-v6-placement`.
 
-## Rule: INIT_FIRST
-
-Init — `CometChatUIKit.initFromSettings()` (recommended) or the `CometChatUIKit.init(uiKitSettings: …)` fallback — must complete before any login, component usage, or SDK call.
-
-### File-based init with `cometchat-settings.json` (recommended)
-
-> **🚧 Version gate (ENG-35866 — Skills Telemetry).** `CometChatUIKit.initFromSettings()` ships in **`cometchat_chat_uikit` ≥ `6.0.3`** (which pulls `cometchat_sdk ^5.0.3` + `cometchat_calls_sdk ^5.0.2` transitively). It reads `cometchat-settings.json` via `rootBundle` and lets the SDK self-report `integrationSource`. On older UIKit the method does not exist — use the **`UIKitSettingsBuilder` fallback** below. If unsure of the installed version, use the fallback.
-
-**Step 1 — create `cometchat-settings.json` at the project root.** Fill `appId` / `region` / `credentials.authKey` from the CLI `provision setup` output; leave everything else at the defaults below. These are the **same credentials** used everywhere else in the app — this file is the single source, so there's no second copy to keep in sync.
-
-```json
-{
-  "appId": "APP_ID_HERE",
-  "region": "us",
-  "credentials": {
-    "authKey": "AUTH_KEY_HERE"
-  },
-  "chatSDK": {
-    "presenceSubscription": {
-      "type": "ALL_USERS",
-      "roles": []
-    },
-    "autoEstablishSocketConnection": true,
-    "adminHost": null,
-    "clientHost": null
-  },
-  "callsSDK": {
-    "host": null,
-    "adminHost": null,
-    "clientHost": null,
-    "callsHost": null
-  },
-  "uiKit": {
-    "subscribePresenceForAllUsers": true
-  }
-}
+## Install
+```bash
+flutter pub add cometchat_chat_uikit
 ```
+Pin the major in `pubspec.yaml` — `cometchat_chat_uikit: ^6.1.0` (a bare `any` can resolve across majors). The Chat SDK (`cometchat_sdk`) comes **transitively and is re-exported by the kit barrel** — do NOT add it separately unless you import SDK-only paths. Voice/video calling = a settings flag + native config (`cometchat_calls_sdk` is already a transitive kit dependency — see below) → `cometchat-flutter-v6-calls`.
 
-**Step 2 — register it as a bundled asset in `pubspec.yaml`.** The SDK loads it with `rootBundle.loadString('cometchat-settings.json')`, so the asset key must be the bare filename — register it at the **root** (not nested under `assets/`, which would make the key `assets/cometchat-settings.json` and the lookup miss):
+**Platform minimums** — Android `minSdk = 26` in `android/app/build.gradle.kts`; iOS `platform :ios, '15.1'` in `ios/Podfile`. **The `getting-started` page says 24 / 13.0 and both are too low** (DOCS-BACKLOG D7). The kit's own AAR allows 21, but transitive deps set the real floor and this one is not optional: `cometchat_chat_uikit` depends on **`cometchat_calls_sdk`** unconditionally — it sits in the main `dependencies:` block — and that package pins `minSdkVersion 26` / `platform :ios, '15.1'` (5.0.7). Gradle and CocoaPods take the maximum across the graph, so a lower value is a build error whether or not the app uses calling.
 
-```yaml
-flutter:
-  assets:
-    - assets/
-    - cometchat-settings.json
-```
+## Setup & credentials (essentials — full detail: `references/setup-credentials.md`)
+1. **Detect** by READING the repo — `pubspec.yaml` + lockfile (deps and the kit major), `lib/main.dart`, state management, navigation, and how config is handled. Reuse an existing `.cometchat/config.json` or settings asset (skip re-setup). Signal table: `references/setup-credentials.md`.
+2. **version_conflict — STOP** if the project already has `cometchat_chat_uikit` v5 (or any non-v6 major); reconcile first, never mix majors (`RULES.md`). A v5 project that wants v6 → `cometchat-flutter-v6-migration`.
+3. **Credentials — OFFER the dashboard fetch FIRST; never default to "paste it yourself."** When App ID / Region / Auth Key are missing, offer **(a) fetch from your dashboard (recommended)** — load the CLI on demand, pick an **EXISTING** app (never auto-create) — or **(b) manual paste**. Then the SKILL writes `cometchat-settings.json` (§4) from those creds; the CLI is dashboard/API-only and never writes Dart (`RULES.md` §21). Never defer credentials to a "add them yourself" TODO. Exact commands + the app-picker flow: `references/setup-credentials.md`.
+4. **Write the settings asset + register it** — commit only a placeholder (no real Auth Key) and do **not** gitignore it (a registered asset must exist or a fresh-clone `flutter build` fails — see the note in §Integration ordering); never echo the Auth Key. Prod → server-minted auth token, not the Auth Key.
+5. **Authorize** = `init` then `login` both hit `onSuccess`. An auth error is almost always the wrong **Region**.
 
-- **Commit `cometchat-settings.json` — do not gitignore it** (the file is part of the integration). Its `authKey` is an **optional demo/POC credential**: a quick-start affordance so a PM or developer can see working chat *before* the backend auth-token flow is wired (that flow often waits on internal approvals). Because the file is committed to source control, treat the key as public — use a **dedicated demo CometChat app** (a committed key trips secret scanners and stays in git history; never reuse a production app's key). Switch to a server-minted `authToken` via `loginWithAuthToken` before production, where `authKey` must not ship.
+## Integration ordering (BAKED — invariant; docs: init must complete before login, login before any widget)
+`initFromSettings()` once at startup → `login(UID)` after init succeeds → only THEN render any `CometChat*` widget.
 
-**Step 3 — init in `main()`.** No `UIKitSettingsBuilder`, no config const — the SDK reads `cometchat-settings.json` itself:
+**Init via `initFromSettings` — the file-based, telemetry-attributed path (`RULES.md` §5).** It reads a `cometchat-settings.json` **asset** and persists `integrationSource="ai-agent"`. **Flutter's signature takes NO settings argument** (unlike web, which passes a settings object) — the file IS the input:
 
 ```dart
-import 'package:flutter/material.dart';
+// [verified vs 6.1.0] — INTENTIONALLY undocumented upstream (@nodoc, owner decision:
+// DOCS-BACKLOG F4 WONTFIX). Prefer it over the docs' UIKitSettingsBuilder + init()
+// path, which loses telemetry attribution. The shape below is the contract.
 import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
 
-void main() async {
-  WidgetsFlutterBinding.ensureInitialized();
-  // tier2-version-gated: initFromSettings ships in cometchat_chat_uikit >= 6.0.3 (ENG-35866).
-  await CometChatUIKit.initFromSettings(
-    onSuccess: (String successMessage) => debugPrint('Init done'),
-    onError: (CometChatException e) => debugPrint('Init failed: ${e.message}'),
-  );
-  runApp(const MyApp());
-}
-```
-
-### `UIKitSettingsBuilder` init (fallback — UIKit before `6.0.3`)
-
-```dart
-// ✅ CORRECT
-final settings = (UIKitSettingsBuilder()
-      ..appId = 'APP_ID'
-      ..region = 'us'
-      ..authKey = 'AUTH_KEY'
-      ..subscriptionType = CometChatSubscriptionType.allUsers)
-    .build();
-
-await CometChatUIKit.init(
-  uiKitSettings: settings,
-  onSuccess: (_) => debugPrint('Init done'),
-  onError: (e) => debugPrint('Init failed: ${e.message}'),
-);
-
-// ❌ WRONG — login before init completes
-CometChatUIKit.init(uiKitSettings: settings);
-CometChatUIKit.login('uid'); // Race condition
-```
-
-## Rule: AUTH_CHECK_AFTER_INIT
-
-After `CometChatUIKit.init()` completes (in its `onSuccess`), the static field `CometChatUIKit.loggedInUser` is already populated if a cached session exists. Use this synchronous check — do NOT call `CometChat.getLoggedInUser()` separately.
-
-```dart
-// ✅ CORRECT — synchronous check after init completes
-CometChatUIKit.init(
-  uiKitSettings: settings,
-  onSuccess: (_) {
-    final hasUser = CometChatUIKit.loggedInUser != null;
-    // Route to home or login based on hasUser
-  },
-);
-
-// ❌ WRONG — separate async getLoggedInUser call after init
-CometChatUIKit.init(
-  uiKitSettings: settings,
-  onSuccess: (_) {
-    CometChat.getLoggedInUser(
-      onSuccess: (user) { ... },  // Unreliable when no session exists
-      onError: (e) { ... },
-    );
-  },
+await CometChatUIKit.initFromSettings(
+  onSuccess: (String message) => debugPrint('CometChat initialized'),
+  onError: (CometChatException e) => debugPrint('Init failed: ${e.message}'),
 );
 ```
 
-The `init()` method internally calls `getLoggedInUser()` and sets `CometChatUIKit.loggedInUser` before firing `onSuccess`. Calling it again is redundant and the callback-based version can silently fail when no session exists (the SDK logs "Please log in to CometChat before calling this method" and neither callback fires consistently).
-
-This also applies to `login()` and `loginWithAuthToken()` — all three populate `CometChatUIKit.loggedInUser` before calling `onSuccess`.
-
-```dart
-// ❌ ALSO WRONG — async getLoggedInUser after init (redundant native bridge round-trip)
-CometChatUIKit.init(
-  uiKitSettings: settings,
-  onSuccess: (_) async {
-    final user = await CometChatUIKit.getLoggedInUser(); // Unnecessary!
-    if (user != null) { ... }
-  },
-);
-
-// ❌ ALSO WRONG — raw SDK getLoggedInUser (bypasses UIKit, unreliable)
-User? existingUser = await CometChat.getLoggedInUser();
-```
-
-## Rule: SCAFFOLD_NO_RESIZE (version-aware — prose guidance, not a lint)
-
-On `cometchat_chat_uikit ^6.0.1`, a `Scaffold` containing `CometChatMessageComposer` should use `resizeToAvoidBottomInset: true` (or omit it — `true` is Flutter's default). The composer clamps the native keyboard height to Flutter's `viewInsets` (kit fix **ENG-34434**), so `true` does NOT double-compensate. The kit sample app uses `true` (the messages screen defaults it; the thread screen sets it explicitly).
-
-The old "must be `false`" rule was correct only for **pre-6.0.1** kits (before the clamp landed). On those versions `false` was the workaround for the double-compensation / layout-jump bug. If you see a double keyboard gap on a current kit, the fix is to upgrade to `^6.0.1` — not to set `false`.
-
-```dart
-// ✅ CORRECT on ^6.0.1 (true, or omit — true is the default)
-Scaffold(
-  resizeToAvoidBottomInset: true,
-  body: Column(
-    children: [
-      Expanded(child: CometChatMessageList(user: user)),
-      CometChatMessageComposer(user: user),
-    ],
-  ),
-)
-
-// ⚠ Only on PRE-6.0.1 kits — false was the stopgap before the ENG-34434 clamp.
-//   On ^6.0.1 this is unnecessary; upgrade the kit instead.
-Scaffold(
-  resizeToAvoidBottomInset: false,
-  body: Column(
-    children: [
-      Expanded(child: CometChatMessageList(user: user)),
-      CometChatMessageComposer(user: user),
-    ],
-  ),
-)
-```
-
-## Rule: ANDROID_MINSDK_26
-
-**Set `minSdk = 26` in `android/app/build.gradle.kts` (In-code path too, not just Visual Builder).** `cometchat_chat_uikit: ^6.0.1` depends transitively on `cometchat_calls_sdk` (`>=5.0.2 <6.0.0`), which floors Android `minSdk` at **26**. A default `flutter create` app sets `minSdk` lower (Flutter's platform default), so `flutter build apk` fails with:
-
-```
-uses-sdk:minSdkVersion 21 cannot be smaller than version 26 declared in library [cometchat_calls_sdk]
-```
-
-`flutter analyze` does NOT catch this — it only surfaces at the APK/AAB build. Set it up front:
-
-```kotlin
-// android/app/build.gradle.kts
-android { defaultConfig { minSdk = 26 } }
-```
-
-(Verified — real `flutter build apk --debug` against kit 6.0.1.)
-
-## Rule: LISTENER_LIFECYCLE
-
-SDK listeners MUST be registered with a unique ID in `initState()` and removed with the same ID in `dispose()`. Forgetting removal causes duplicate events and memory leaks.
-
-```dart
-// ✅ CORRECT
-class _MyScreenState extends State<MyScreen> with MessageListener {
-  late final String _listenerId;
-
-  @override
-  void initState() {
-    super.initState();
-    _listenerId = 'my_screen_${DateTime.now().millisecondsSinceEpoch}';
-    CometChat.addMessageListener(_listenerId, this);
-  }
-
-  @override
-  void dispose() {
-    CometChat.removeMessageListener(_listenerId);
-    super.dispose();
-  }
-}
-
-// ❌ WRONG — hardcoded ID causes collisions; missing dispose removal
-class _MyScreenState extends State<MyScreen> with MessageListener {
-  @override
-  void initState() {
-    super.initState();
-    CometChat.addMessageListener('messages', this); // Collision!
-  }
-  // Missing dispose → listener leaks
-}
-```
-
-## Rule: THEME_CACHE
-
-Cache theme values in `didChangeDependencies()` with a `_themeInitialized` flag. Never call `CometChatThemeHelper.getColorPalette(context)` in `build()` — during keyboard animation, `MediaQuery` changes trigger rebuilds, and each lookup does expensive InheritedWidget traversal (44-95ms instead of <16ms).
-
-```dart
-// ✅ CORRECT — Hybrid pattern
-class _MyWidgetState extends State<MyWidget> {
-  late CometChatColorPalette _colorPalette;
-  late CometChatSpacing _spacing;
-  late CometChatTypography _typography;
-  bool _themeInitialized = false;
-
-  @override
-  void didChangeDependencies() {
-    super.didChangeDependencies();
-    if (!_themeInitialized) {
-      _colorPalette = CometChatThemeHelper.getColorPalette(context);
-      _spacing = CometChatThemeHelper.getSpacing(context);
-      _typography = CometChatThemeHelper.getTypography(context);
-      _themeInitialized = true;
-    }
-  }
-}
-
-// ❌ WRONG — lookup in build causes jank
-@override
-Widget build(BuildContext context) {
-  final colors = CometChatThemeHelper.getColorPalette(context); // Expensive!
-  return Container(color: colors.primary);
+`cometchat-settings.json` at the **project root**, registered in `pubspec.yaml` under `flutter: assets:`:
+```json
+{
+  "appId": "APP_ID",
+  "region": "REGION",
+  "credentials": { "authKey": "AUTH_KEY" },
+  "uiKit": { "subscribePresenceForAllUsers": true, "enableCalling": false },
+  "chatSDK": { "autoEstablishSocketConnection": true }
 }
 ```
-
-## Rule: SUBSCRIPTION_TYPE_REQUIRED
-
-Omitting `subscriptionType` in `UIKitSettingsBuilder` silently disables all presence events (online/offline, typing indicators). No error is thrown.
-
-```dart
-// ✅ CORRECT
-UIKitSettingsBuilder()
-  ..subscriptionType = CometChatSubscriptionType.allUsers
-
-// ❌ WRONG — no error, but presence events never fire
-UIKitSettingsBuilder()
-  ..appId = 'APP_ID'
-  ..region = 'us'
-```
-
-## Rule: REGION_LOWERCASE
-
-Region must be a lowercase string. The SDK validates against `['us', 'eu', 'in']`.
-
-```dart
-// ✅ CORRECT
-..region = 'us'
-
-// ❌ WRONG — throws ERR_INVALID_REGION
-..region = 'US'
-```
-
-## Rule: SERVICE_LOCATOR_INIT
-
-Each component's `ServiceLocator.instance.setup()` must be called before creating its BLoC. The UIKit widgets do this automatically, but if you create BLoCs manually:
+> Keys are read exactly as above. `uiKit.enableCalling` is the **only** way to turn calling on via this path (`UIKitSettings` defaults it to false) — leave it `false` until the user asks for calls. `credentials.authKey` is **dev-only**; omit it for production and log in with a server-minted token.
+> **Make a fresh clone build.** A file registered under `flutter: assets:` MUST exist at build time or `flutter build bundle` fails with *"No file or variants found for asset: cometchat-settings.json."* So do **not** gitignore the registered asset. Instead **commit a placeholder `cometchat-settings.json`** — same shape, with a placeholder/empty `authKey` (NEVER a real dev Auth Key) — and have each developer and CI overwrite it locally/at build time with real credentials. (Enforce "no real key committed" via a pre-commit check or CI, not `.gitignore`.) For production, CI generates the prod-flavoured file (no Auth Key) at build time (`cometchat-flutter-v6-production`).
 
 ```dart
-// ✅ CORRECT
-ConversationsServiceLocator.instance.setup();
-final bloc = ConversationsBloc(
-  getLoggedInUserUseCase: ConversationsServiceLocator.instance.getLoggedInUserUseCase,
-  // ...
-);
-
-// ❌ WRONG — StateError: not initialized
-final bloc = ConversationsBloc(
-  getLoggedInUserUseCase: ConversationsServiceLocator.instance.getLoggedInUserUseCase,
+// login AFTER init succeeds. CometChatUIKit.login already checks getLoggedInUser()
+// internally and no-ops if that UID is signed in, so no host-side re-login guard is needed.
+await CometChatUIKit.login(
+  uid,
+  onSuccess: (User user) => debugPrint('Logged in: ${user.name}'),
+  onError: (CometChatException e) => debugPrint('Login failed: ${e.message}'),
 );
 ```
+> **Which UID?** `login()` needs a user that ALREADY EXISTS — never invent one. ASK, or take one from Dashboard → **Users**; fresh apps seed `cometchat-uid-1…`. The only tentative suggestion is `cometchat-uid-1`, labelled "if this is a fresh app." **Prod → `CometChatUIKit.loginWithAuthToken(authToken, …)`** with a token minted server-side.
+> Init-once, hot-restart, and gating the first frame: `references/lifecycle.md`.
 
-## Rule: MUID_PRESERVATION
-
-When sending messages, the SDK may return an empty `muid` in the success callback. The UIKit preserves the original `muid` for pending→sent deduplication. If you handle `ccMessageSent` events, compare by `muid` first, then `id`.
-
-## Pattern: Callback → Async Bridge
-
-The CometChat SDK uses callback-based APIs (`onSuccess`/`onError`). Wrap them with `Completer` for async/await:
-
-```dart
-import 'dart:async';
-
-Future<User> loginAsync(String uid) {
-  final completer = Completer<User>();
-  CometChatUIKit.login(uid,
-    onSuccess: (user) => completer.complete(user),
-    onError: (e) => completer.completeError(e),
-  );
-  return completer.future;
-}
-
-// Usage
-try {
-  final user = await loginAsync('user123');
-} on CometChatException catch (e) {
-  debugPrint('Login failed: ${e.message}');
-}
-```
-
-This pattern is used internally by the UIKit's repository layer. Use it when calling SDK methods directly outside UIKit components.
-
-## Component Architecture Pattern
-
-Every component follows this structure:
-
-```
-{component}/
-├── bloc/
-│   ├── {component}_bloc.dart      # Extends Bloc<Event, State>, registers SDK listeners
-│   ├── {component}_event.dart     # Equatable events
-│   └── {component}_state.dart     # Equatable state with copyWith
-├── domain/
-│   ├── usecases/                  # One class per operation
-│   └── repositories/              # Abstract interface
-├── data/
-│   ├── repositories/              # Impl delegates to datasource
-│   └── datasources/               # SDK calls
-├── di/
-│   └── {component}_service_locator.dart  # Singleton, setup() method
-└── widgets/                       # UI, uses BlocConsumer/BlocBuilder
-```
-
-## Naming Conventions
-
-| Type | Pattern | Example |
-|------|---------|---------|
-| Widget | `CometChat{Name}` | `CometChatConversations` |
-| BLoC | `{Name}Bloc` | `ConversationsBloc` |
-| Event | `{Verb}{Name}` | `LoadConversations`, `MessageReceived` |
-| State | `{Name}State` | `ConversationsLoaded`, `MessageListState` |
-| Repository | `{Name}Repository` / `{Name}RepositoryImpl` | `ConversationsRepository` |
-| Use Case | `{Verb}{Name}UseCase` | `GetConversationsUseCase` |
-| Service Locator | `{Name}ServiceLocator` | `ConversationsServiceLocator` |
-| Style | `CometChat{Name}Style` | `CometChatConversationsStyle` |
-
-## Checklist — Every CometChat Screen
-
-- [ ] `CometChatUIKit.init()` called before any usage
-- [ ] Auth check uses `CometChatUIKit.loggedInUser` after init, not `CometChat.getLoggedInUser()`
-- [ ] `subscriptionType` set in UIKitSettingsBuilder
-- [ ] `region` is lowercase
-- [ ] Scaffold hosting `CometChatMessageComposer` uses `resizeToAvoidBottomInset: true` (or omits it) on `^6.0.1` — the composer clamps to `viewInsets` (ENG-34434); `false` is only the pre-6.0.1 stopgap
-- [ ] Theme cached in `didChangeDependencies()`, not `build()`
-- [ ] SDK listeners registered with unique ID, removed in `dispose()`
-- [ ] Colors from `CometChatThemeHelper`, never hardcoded
-
-## Visual Builder integration
-
-> **⚠ The Visual Builder emits V5-shaped code.** The canonical builder repo at the `chat_builder/` directory inside the Flutter Visual Builder ZIP (download from https://preview.cometchat.com/downloads/cometchat-builder-flutter.zip) uses `cometchat_chat_uikit: ^5.2.12` + `cometchat_calls_uikit: ^5.0.13` — the **V5** Flutter UI Kit packages. There is no V6-native Visual Builder canonical from vendor side yet ([F22 finding, 2026-05-22](https://github.com/cometchat/cometchat-skills/issues)). When a V6 project picks the Visually path, the copied `chat_builder/` path-dep brings V5 deps in transitively — your V6 host app code is untouched, but the Visual-Builder-emitted screens are V5-flavored. Treat as transitional until vendor publishes a V6 canonical. V6 customers preferring a single-version dep tree should use the In-code path.
->
-> The recipe below is identical to what `cometchat-flutter-v5-core` §"Visual Builder integration" prescribes (both reference the same canonical). This page kept for V6 customers who still hit the Visually flow.
-
-When the dispatcher's Step 3.1 sets `customize=visual` and the platform resolves to `flutter`, skills runs **`cometchat builder export --platform flutter`** — a single CLI command that downloads the canonical static template ZIP from `preview.cometchat.com/downloads/cometchat-builder-flutter.zip`, fetches the per-builder settings JSON, applies F3 + F10 missing-field defaults, and writes the entire `chat_builder/` package to `--output` (default: `chat_builder/`).
-
-The `chat_builder/` directory is wired **as a path dependency** in the customer's project — it owns the entire chat surface (conversations, messages, users, groups, calls). The customer's app initializes settings and launches a screen via `ChatBuilder.launchBuilder(context)` or `ChatBuilder.launchMessages(...)`.
-
-This is intentionally a heavier copy than iOS (Pod) / Android (Gradle plugin) — the Flutter builder package is not yet published to pub.dev.
-
-### 1. Run `cometchat builder export`
-
-```bash
-cometchat builder export --platform flutter --json
-```
-
-Defaults to `--output chat_builder/`. The command writes the entire canonical `chat_builder/` Dart package (~50 files: `lib/`, `assets/`, `android/`, `ios/`, `pubspec.yaml`) — verbatim from the canonical ZIP — and patches `chat_builder/assets/sample_app/cometchat-builder-settings.json` with the **envelope-shape JSON** the CLI emits: `{ builderId, name, settings: {...} }` (F3 + F10 defaults injected: `mentionAll: true`, `inAppSounds: { incomingMessageSound: true, outgoingMessageSound: true }`). No SKILLS-AUTO-GENERATED sentinel (JSON forbids `//` comments).
-
-> The CLI is the source of truth for the written shape. The vendor canonical's own checked-in `cometchat-builder-settings.json` carries only `{ builderId, settings }` (no top-level `name`) — `BuilderSettingsHelper.loadFromAsset()` reads only `builderId` + `settings` and **ignores any extra top-level keys**, so the CLI's additional `name` (and any other extras) are harmless.
-
-`BuilderSettingsHelper.loadFromAsset()` reads this exported settings file at runtime.
-
-Resync = re-run the same command with `--force` (full re-download + replace). See `cometchat-core` §11.6 for the resync contract.
-
-#### F56 + F57 + F58 — known canonical-ZIP rough edges (re-apply after every export)
-
-Three issues live in the upstream canonical `chat_builder/` Dart package (verified 2026-05-25 against `preview.cometchat.com/downloads/cometchat-builder-flutter.zip`). Vendor-side fixes pending; agent must work around them on **every** `builder export` (first emit AND every resync, since `--force` re-overwrites the patches):
-
-**F56 — Wrong asset path in `api_services.dart`**
-
-`chat_builder/lib/services/api_services.dart` line ~41:
-
-```dart
-// Canonical (broken):
-await loadJsonFromAssets('assets/chat_builder/sample_data.json');
-
-// Agent must patch to:
-await loadJsonFromAssets('assets/sample_app/sample_data.json');
-```
-
-The canonical references `assets/chat_builder/sample_data.json` — a path that doesn't exist in the customer's host app after the standard `cp -r chat_builder/assets/ assets/` copy. The actual file lands at `assets/sample_app/sample_data.json`. Without this patch, the login screen's "default users" list silently falls back to empty and customers see an empty user picker.
-
-**F57 — F56 patch is overwritten on every resync**
-
-`builder export --platform flutter --force` re-copies the canonical's `api_services.dart` verbatim — re-introducing the wrong path. Agent must re-apply the F56 patch after every resync. This is a known re-apply task; document it in the customer-facing summary so they know "the agent will need to patch this each time the dashboard settings change".
+## Widget / API map (BAKED closed list — from the catalog)
+Init/session: `CometChatUIKit` (`initFromSettings` · `login` · `loginWithAuthToken` · `logout` · `loggedInUser`), `UIKitSettingsBuilder`, `CometChatSubscriptionType`, `CometChatException`.
+Core surface: `CometChatConversations`, `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer`; wired affordances `CometChatThreadedHeader`, `CometChatSearch`.
+Grow set (added on request): `CometChatUsers`, `CometChatGroups`, `CometChatGroupMembers`, `CometChatChangeScope`, `CometChatCallLogs`. Incoming calls need NO widget — with calling on, the kit presents the overlay itself (`-calls`).
+> **TWO BARRELS — a real compile trap.** `package:cometchat_chat_uikit/cometchat_chat_uikit.dart` gives you the chat widgets **and the re-exported Chat SDK** (`User`, `Group`, `Conversation`, `BaseMessage`, `TextMessage` — no separate import). **Every calls symbol** (`CometChatIncomingCall`, `CometChatOutgoingCall`, `CometChatCallButtons`, `CometChatCallLogs`, `CometChatCallBubble`, `CometChatCalls`) lives ONLY in `package:cometchat_chat_uikit/cometchat_calls_uikit.dart`, and that barrel does NOT re-export the chat widgets — a calls screen imports **both**. Verified: using `CometChatIncomingCall` with only the chat import fails to compile.
+> The v6 widget is **`CometChatThreadedHeader`** — `CometChatThreadHeader` (the React name) does NOT exist here. Never carry a name across families.
 
-**F58 — Asset copy is additive, not idempotent**
+## Hot-path props (BAKED — the golden path needs NO fetch)
+- `CometChatConversations`: `onItemTap(Conversation)` (select → push the message screen) · `hideSearch` · `searchReadOnly` (set `true` so the field acts as a button) · `onSearchTap` (→ push `CometChatSearch`) · `conversationsRequestBuilder` (scope to `user`/`group` when the ask is DM-only or groups-only — reuse the builder, don't client-filter) · `hideAppbar` · `appBarOptions` · `onBack`.
+- `CometChatMessageHeader`: `user:` / `group:` (pass the SAME target as the list) · `showBackButton` (default `true`) + `onBack` · `hideVoiceCallButton` / `hideVideoCallButton` (call buttons are built in — leave them unless calls are out of scope) · `auxiliaryButtonView` / `trailingView` (where a custom action goes — see search below).
+- `CometChatMessageList`: `user:` / `group:` · `parentMessageId` (thread mode) · `onThreadRepliesClick` **[verified]** — the type is `ThreadRepliesClick = void Function(BaseMessage message, BuildContext context, {CometChatMessageTemplate? template})`; a one-argument closure does **not** compile (`DOCS-BACKLOG` F2).
+- `CometChatMessageComposer`: `user:` / `group:` · `parentMessageId` (thread mode). A plain send needs nothing else.
+- `CometChatSearch` **[verified]**: `onConversationClicked` / `onMessageClicked` (**not** the docs' `onConversationItemClick` / `onMessageItemClick` — `DOCS-BACKLOG` F3) · `onBack` · `user:` / `group:` / `searchIn` to scope it to one chat.
+> Any OTHER widget or a rarer prop → fetch its `.md` twin via `references/docs-map.md`. Full catalog: `cometchat-flutter-v6-components`.
 
-The standard prescription `cp -r chat_builder/assets/ assets/` is additive — files removed from the canonical (e.g., a deprecated icon) stay in the customer's `assets/` directory because cp doesn't delete. On resync, use `rsync -a --delete chat_builder/assets/ assets/` instead, OR `rm -rf assets/ && cp -r chat_builder/assets/ assets/` first.
+## Golden path — the production-ready CORE surface (default for an unscoped "add chat"; grows on request)
+Setup → init/login → **gate the first frame** on both resolving (show a loader; never render a `CometChat*` widget before login succeeds) → then:
 
-**Tracking**: a single vendor ticket bundles F22 (V5-shaped canonical), F56 (wrong asset path), F57 (resync overwrite of F56 fix), F48 lineage (font paths in earlier Android-ZIP iterations) — see CometChat Linear for the consolidated upstream-fix request. v4.3.0 ships with the agent-side workarounds documented above; a future release picks up the upstream fixes when they land.
-
-### Files skills writes (after `builder export`)
-
-| Path | Content |
-|---|---|
-| `lib/cometchat/cometchat_app.dart` | Thin `StatefulWidget` that initializes the kit then exposes a launch trigger calling `ChatBuilder.launchBuilder(context)` |
-| `lib/cometchat/secrets.dart` | Credentials class (`Secrets.appId / region / authKey`) populated by Step 2c, added to `.gitignore` |
-
-### Files patched
-
-| Path | Patch |
-|---|---|
-| `pubspec.yaml` | Add `chat_builder: { path: ./chat_builder }` to dependencies. Add `assets/` + `assets/sample_app/` to `flutter.assets`. Add font families `arial / inter / roboto / times New Roman` exactly as defined in `chat_builder/pubspec.yaml`. **As a `path:` dependency the `chat_builder` package carries its own transitive deps** (`get`, `shared_preferences`, `http`, `toast`, `path_provider`, `permission_handler`, `intl` per `chat_builder/pubspec.yaml`) and pub resolves them automatically — you do NOT list them in the host app. Only if you vendor `chat_builder`'s Dart files directly into your app (instead of using the `path:` dep) must you add those seven to your own `dependencies` |
-| `lib/main.dart` | Insert `WidgetsFlutterBinding.ensureInitialized()` + `await BuilderSettingsHelper.loadFromAsset()` before `runApp()` |
-| `ios/Podfile` | `platform :ios, '13.0'` (raise if lower) |
-| `android/app/build.gradle.kts` | `ndkVersion = "27.0.12077973"`, **`minSdk = 26`** (REQUIRED — `cometchat_chat_uikit 6.0.1` pulls `cometchat_calls_sdk` transitively, which floors `minSdk` at 26; a default `flutter create` sets it lower and `flutter build apk` then fails with "uses-sdk:minSdkVersion … cannot be smaller than version 26 declared in library [cometchat_calls_sdk]") |
-| `android/gradle.properties` | **Non-negotiable:** append `android.enableJetifier=true`. CometChat Chat SDK transitively pulls `com.android.support:support-compat:26.1.0` which collides with `androidx.core:core` — without Jetifier the build fails with `Duplicate class android.support.v4.os.ResultReceiver` etc. Same root cause as `cometchat-android-v6-core` §1.3a — Flutter's Android side has identical exposure. Validated 2026-05-19 on smoke test |
-| `android/app/src/main/AndroidManifest.xml` + `ios/Runner/Info.plist` | `RECORD_AUDIO` / `CAMERA` permissions + `NSMicrophoneUsageDescription` / `NSCameraUsageDescription` if any call feature is enabled |
-
-### Init flow (lib/main.dart)
+1. **Conversations screen** — `CometChatConversations` inside `Scaffold` + `SafeArea`. Wire `onItemTap` → `Navigator.push` the message screen for that conversation's `User`/`Group`. Wire the **global search** the documented way: `searchReadOnly: true` + `onSearchTap` → push a `CometChatSearch` screen, whose `onConversationClicked`/`onMessageClicked` navigate to the hit and whose `onBack` pops. (Or set `hideSearch: true` — but never leave the field dead.)
+2. **Message screen** — `CometChatMessageHeader` + `Expanded(child: CometChatMessageList(...))` + `CometChatMessageComposer`, all carrying the SAME `user:`/`group:`. `Expanded` is what makes the list fill the screen; the header/composer keep their intrinsic height. Leave `Scaffold.resizeToAvoidBottomInset` at its default `true` so the composer rides above the keyboard. The header's `showBackButton` defaults to `true` — wire `onBack` to `Navigator.pop`.
+3. **Thread screen (DEFAULT — include unless the user opts out)** — wire the list's `onThreadRepliesClick` to push a screen with `CometChatThreadedHeader(parentMessage:, loggedInUser:)` — both required, and it has **no `onBack`**, so the screen's own `AppBar` provides back — plus a `CometChatMessageList` + `CometChatMessageComposer` that each take `parentMessageId: parentMessage.id` **AND the same `user:`/`group:` as the parent chat**. **Passing `parentMessageId` without the user/group target makes thread replies silently never send.**
+4. **In-chat scoped search** — Flutter's `CometChatMessageHeader` has **no** search prop (unlike React). Put the action in the header's `auxiliaryButtonView`/`trailingView` slot — custom UI goes IN the slot, never stacked on top — and push `CometChatSearch(user: …/group: …)` so it searches only that chat.
 
 ```dart
-import 'package:flutter/material.dart';
-import 'package:chat_builder/builder/builder_settings_helper.dart';
-
-Future<void> main() async {
-  WidgetsFlutterBinding.ensureInitialized();
-  await BuilderSettingsHelper.loadFromAsset();
-  runApp(const MyApp());
-}
-```
-
-`BuilderSettingsHelper.loadFromAsset()` reads `assets/sample_app/cometchat-builder-settings.json` and populates the in-memory settings the `ChatBuilder.*` screens consume. Standard `CometChatUIKit.init(uiKitSettings: ...)` (see this file's `INIT_FIRST` rule) is still required and runs before any chat surface mounts.
-
-> **`runApp(const MyApp())` above assumes you keep `flutter create`'s default `MyApp` class.** If you instead use the **Recommended** root below (`CometChatBuilderRoot`), you've renamed/removed `MyApp` — so also **delete or update `test/widget_test.dart`** (the default test instantiates `MyApp()` and will otherwise fail `flutter analyze` with `The name 'MyApp' isn't a class`). Pick ONE root-widget name and keep main.dart + the test file consistent. (Verified 2026-06-14: this orphaned test was the only `flutter analyze` error on a clean builder-export wiring.)
-
-> **Extensions + AI features are dashboard-enabled in V6 — do NOT add V5-style `..extensions` / `..aiFeature` / `..callingExtension` setters.** Those three `UIKitSettingsBuilder` fields exist in the **V5** kit (and the builder reference app is V5-shaped — `chat_builder` pins `cometchat_chat_uikit ^5.2.x`, so its `InitializeCometChat.init()` passes them). They were **removed in V6** — adding them does not compile against `cometchat_chat_uikit ^6.0.1`. In V6 the extension-backed builder features (polls, collaborative whiteboard/document, stickers, message translation, reactions) and AI features are turned on in the **CometChat dashboard** (the builder enables them server-side) and the kit auto-wires them; calling is enabled with `..enableCalls = true`. So the V6 `UIKitSettingsBuilder` needs only `appId`/`region`/`authKey`/`subscriptionType` (+ `enableCalls` for calls) — the builder JSON's feature flags render because the features are enabled on the app, not because of a builder setter.
-
-### Recommended: mount `ChatBuilder.createApp()` as the root
-
-The cleanest integration mirrors the canonical's own `lib/main.dart`, which mounts `ChatBuilder.createApp()` directly as the app root and lets the package own init, theming, and call-navigation wiring:
-
-```dart
-// lib/main.dart
-import 'package:flutter/material.dart';
-import 'package:chat_builder/builder/chat_builder.dart';
-import 'package:chat_builder/builder/builder_settings_helper.dart';
-// ...plus the package's prefs/page-manager bootstrap if you vendor those files
-
-Future<void> main() async {
-  WidgetsFlutterBinding.ensureInitialized();
-  await BuilderSettingsHelper.loadFromAsset();
-  runApp(const CometChatBuilderRoot());
-}
-
-class CometChatBuilderRoot extends StatelessWidget {
-  const CometChatBuilderRoot({super.key});
-
-  @override
-  Widget build(BuildContext context) => ChatBuilder.createApp();
-}
-```
-
-`ChatBuilder.createApp()` returns a `MaterialApp` that already wires (a) `CometChatColorPalette` as a `ThemeData` extension in BOTH light and dark themes — this is what actually applies the builder's brand color + text colors to the kit, and (b) `navigatorKey: CallNavigationContext.navigatorKey` so incoming-call routing works. Use this path when CometChat owns the whole chat surface.
-
-### Alternative: a host-app wrapper (when you can't mount `createApp()` as root)
-
-If the host app already owns its root `MaterialApp` and you must mount CometChat as a sub-surface (a route/tab/dialog), hand-roll a wrapper — but you are then responsible for replicating what `createApp()` does for you: the theme palette and the navigator key.
-
-```dart
-// lib/cometchat/cometchat_app.dart
-import 'package:flutter/material.dart';
-import 'package:chat_builder/builder/chat_builder.dart';
+// [verified vs 6.1.0] the message screen — the shape the whole surface hangs off.
 import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
-import 'package:cometchat_calls_uikit/cometchat_calls_uikit.dart';
-
-import 'secrets.dart';
-
-/// Top-level chat surface emitted by the Visual Builder Visually path.
-/// The `chat_builder` package owns the UI; this widget bootstraps UI Kit init
-/// then renders a launch trigger. Step 3c placement decides where this widget
-/// mounts in the host app (a route, a tab, a dialog).
-class CometChatApp extends StatefulWidget {
-  const CometChatApp({super.key});
-
-  @override
-  State<CometChatApp> createState() => _CometChatAppState();
-}
+import 'package:flutter/material.dart';
 
-class _CometChatAppState extends State<CometChatApp> {
-  bool _isReady = false;
-  String? _initError;
+class MessageScreen extends StatelessWidget {
+  final User? user;
+  final Group? group;
+  const MessageScreen({super.key, this.user, this.group});
 
   @override
-  void initState() {
-    super.initState();
-    _bootstrap();
-  }
-
-  void _bootstrap() {
-    // V6: extensions + AI features are dashboard-enabled and auto-wire — there
-    // are NO ..extensions / ..aiFeature / ..callingExtension setters (those are
-    // V5; see callout above). Add ..enableCalls = true if you need calling.
-    final settings = (UIKitSettingsBuilder()
-          ..appId = Secrets.appId
-          ..region = Secrets.region
-          ..authKey = Secrets.authKey
-          ..subscriptionType = CometChatSubscriptionType.allUsers)
-        .build();
-
-    CometChatUIKit.init(
-      uiKitSettings: settings,
-      onSuccess: (_) => setState(() => _isReady = true),
-      onError: (e) => setState(() => _initError = e.message),
+  Widget build(BuildContext context) {
+    return Scaffold(                       // resizeToAvoidBottomInset defaults to true = keyboard-safe
+      body: SafeArea(
+        child: Column(
+          children: [
+            CometChatMessageHeader(user: user, group: group, onBack: () => Navigator.pop(context)),
+            Expanded(                      // REQUIRED — the list fills the remaining height
+              child: CometChatMessageList(
+                user: user,
+                group: group,
+                onThreadRepliesClick: (BaseMessage message, BuildContext context,
+                    {CometChatMessageTemplate? template}) {
+                  Navigator.push(context, MaterialPageRoute(
+                    builder: (_) => ThreadScreen(parentMessage: message, user: user, group: group),
+                  ));
+                },
+              ),
+            ),
+            CometChatMessageComposer(user: user, group: group),
+          ],
+        ),
+      ),
     );
   }
+}
+
+// The thread screen the callback pushes — part of the DEFAULT surface, not an extra.
+// NOTE: the list AND composer each take parentMessageId *and* the same user:/group:
+// as the parent chat. parentMessageId alone => replies silently never send.
+class ThreadScreen extends StatelessWidget {
+  final BaseMessage parentMessage;
+  final User? user;
+  final Group? group;
+  const ThreadScreen({super.key, required this.parentMessage, this.user, this.group});
 
   @override
   Widget build(BuildContext context) {
-    if (_initError != null) {
-      return Scaffold(body: Center(child: Text('CometChat init failed: $_initError')));
-    }
-    if (!_isReady) {
-      return const Scaffold(body: Center(child: CircularProgressIndicator()));
-    }
-    // The bare Scaffold below does NOT apply the builder's theme palette.
-    // If this wrapper owns the MaterialApp, replicate the canonical's
-    // ThemeData (both light + dark) and navigatorKey — see note below.
     return Scaffold(
-      resizeToAvoidBottomInset: true,
-      body: Center(
-        child: ElevatedButton(
-          onPressed: () => ChatBuilder.launchBuilder(context),
-          child: const Text('Open chat'),
+      // The thread screen's back affordance is the AppBar — CometChatThreadedHeader
+      // has NO onBack/onError param (the docs show one; it does not exist, DOCS-BACKLOG F5).
+      // A pushed route gets the back button automatically.
+      appBar: AppBar(title: const Text('Thread')),
+      body: SafeArea(
+        child: Column(
+          children: [
+            CometChatThreadedHeader(                      // note the 'ed' — see the map above
+              parentMessage: parentMessage,               // NOT `message:` (DOCS-BACKLOG F1)
+              loggedInUser: CometChatUIKit.loggedInUser!, // required
+            ),
+            Expanded(
+              child: CometChatMessageList(
+                user: user, group: group, parentMessageId: parentMessage.id,
+              ),
+            ),
+            CometChatMessageComposer(
+              user: user, group: group, parentMessageId: parentMessage.id,
+            ),
+          ],
         ),
       ),
     );
   }
 }
 ```
-
-If this wrapper (or the host app) supplies the root `MaterialApp`, theme color/typography are honored ONLY if you wire `CometChatColorPalette` as a `ThemeData` extension and set the navigator key — both UNCONDITIONALLY, exactly as the canonical's `ChatBuilder.createApp()` does (it sets both regardless of whether calls are enabled):
-
-```dart
-MaterialApp(
-  theme: ThemeData(
-    fontFamily: /* builder typography font */,
-    extensions: [
-      CometChatColorPalette(
-        textPrimary: /* builder light primary text */,
-        textSecondary: /* builder light secondary text */,
-        primary: /* builder brand color */,
-      ),
-    ],
-  ),
-  darkTheme: ThemeData(
-    fontFamily: /* builder typography font */,
-    extensions: [
-      CometChatColorPalette(
-        textPrimary: /* builder dark primary text */,
-        textSecondary: /* builder dark secondary text */,
-        primary: /* builder brand color */,
-      ),
-    ],
-  ),
-  // UNCONDITIONAL — the canonical wires this in every MaterialApp it builds,
-  // not just when calls are enabled. Incoming-call routing needs it (Bug 1),
-  // and gating it behind "calls enabled" breaks call routing if a feature flag
-  // is flipped on later in the dashboard without a code change.
-  navigatorKey: CallNavigationContext.navigatorKey,
-  home: /* your chat surface */,
-)
-```
-
-`ChatBuilder.launchBuilder(context)` opens the builder's login / dashboard flow; once a user is logged in, the package's internal navigation handles conversations → messages.
-
-For direct deep-links into a specific user or group thread (skipping the dashboard), use:
-
-```dart
-ChatBuilder.launchMessages(context: context, user: user);
-ChatBuilder.launchMessages(context: context, group: group);
-```
-
-These are the two public entry points the `chat_builder` package exposes — see `chat_builder/lib/builder/chat_builder.dart` (inside the Flutter Visual Builder ZIP at https://preview.cometchat.com/downloads/cometchat-builder-flutter.zip).
-
-On `^6.0.1`, any `Scaffold` whose body chain reaches `CometChatMessageComposer` should use `resizeToAvoidBottomInset: true` (or omit it — `true` is the default), because the composer clamps the keyboard height to `viewInsets` (ENG-34434). See this file's `SCAFFOLD_NO_RESIZE` rule — `false` is only the pre-6.0.1 stopgap.
-
-### Calls + builder
-
-If any `VoiceAndVideoCalling.*` flag is enabled in the builder settings (e.g. `VoiceAndVideoCalling.oneOnOneVoiceCalling` — there is NO `CometChatBuilderSettings` type; the canonical app uses plain static-field holders like `VoiceAndVideoCalling`/`CoreMessagingExperience` in `builder_settings.dart`), the `chat_builder` package handles incoming/outgoing call surfaces internally (it ships its own call routes). External wiring still required:
-1. Add `cometchat_calls_uikit` to `pubspec.yaml`
-2. iOS `Info.plist` + Android `AndroidManifest.xml` permissions per `cometchat-flutter-v6-calls`
-3. `navigatorKey: CallNavigationContext.navigatorKey` on the root `MaterialApp` — kit 6.0.1 requires this for incoming-call routing (Bug 1; see `cometchat-flutter-v6-calls` §1.7). Note the canonical wires this **unconditionally** in `ChatBuilder.createApp()` (it does NOT gate on whether calls are enabled), and the "Alternative: host-app wrapper" guidance above does the same — so if you mounted `ChatBuilder.createApp()` or followed that MaterialApp template, this is already in place
-4. Push wiring — defer to `cometchat-flutter-v6-push`. The real token-registration API is `CometChatNotifications.registerPushToken(PushPlatforms.FCM_FLUTTER_ANDROID, fcmToken: …)`; a class named `PNRegistry` does **not** exist anywhere in the SDK or UI Kit (verified against `cometchat_sdk/lib/notification/main/cometchat_notifications.dart` 2026-06-03 — supersedes the inverted [[project_sdk_symbol_audit_2026_05_14]] claim)
-5. **6.0.1 GA status:** the beta2 outgoing→in-call transition bug is FIXED in 6.0.1 ([[project_v6_flutter_calls_partial]]). V6 calls now work end-to-end once the navigatorKey line in step 3 is in place — V5 is no longer required for calls.
-
-### What is NOT honored in v1
-
-Skills emits a launch-button trigger, not the full multi-tab layout the `chat_builder` package's internal `Dashboard` provides. Customers get the dashboard once they tap "Open chat" — but the host-app surface is intentionally minimal so Step 3c placement (route, tab, dialog) can decide the mount shape. Chat-feature toggles ARE honored via the builder JSON. **Theme color + typography are honored ONLY if the mounted root is `ChatBuilder.createApp()` (or a `MaterialApp` that replicates its `CometChatColorPalette` `ThemeData` extension + `fontFamily`)** — the bare-`Scaffold` wrapper above does NOT apply that palette, so on that path the kit falls back to default colors. See the "Alternative: host-app wrapper" guidance for the exact `ThemeData` wiring. For deep customization beyond what the builder JSON allows, fall back to the code-driven path (see this file's standard placement pattern) and skip `chat_builder` entirely.
+> **SIZE it the mobile way — `references/layout.md`.** The kit's list widgets expand to fill their parent, so the failure mode here is an **unbounded height** error or a collapsed list, and the fix is always the same: give the list a bounded box (`Expanded`/`Flexible` inside a `Column`, or a sized parent) instead of letting content drive it. Never nest the surface in an unbounded `SingleChildScrollView`/`Column` without `Expanded`.
+> **Match the data scope to the REQUEST.** Real apps ship seeded groups, so a plain `CometChatConversations` lists both 1:1s and groups. A **DM-only** ask scopes the list to user conversations via `conversationsRequestBuilder`; a **groups-only** app scopes to groups; a generic "add chat" keeps BOTH. Reuse the builder — never hand-roll a client-side filter, and don't add a Groups tab to a 1:1-only app.
+> **Prod auth:** mint a per-user auth token server-side and call `loginWithAuthToken` — the Auth Key is dev-only (`references/lifecycle.md`).
+
+## Growing on request
+Add each only when asked: **Users / Groups / Calls tabs** (`CometChatUsers` · `CometChatGroups` · `CometChatCallLogs`) · **group details** (`CometChatGroupMembers` + `CometChatChangeScope`) · **calls** (→ `-calls`; incoming calls = only `navigatorKey: CallNavigationContext.navigatorKey` on the root `MaterialApp` — never mount `CometChatIncomingCall` yourself, that doubles the kit's overlay) · **features** (→ `-features`). The full tab-based app is the union of these — recipe in `-placement`. A scoped-DOWN ask (chat tab, bottom sheet, embedded panel) → the matching `-placement` variant.
+
+## Deep references (load ONLY when the task needs them)
+- `setup-credentials.md` — detect signals · version_conflict · dashboard creds · the settings asset.
+- `lifecycle.md` — init-once + hot restart · gating the first frame · prod auth-token · logout.
+- `layout.md` — mobile sizing (bounded height · `Expanded` · SafeArea · keyboard).
+- `docs-map.md` — intent → live doc page (component twins **+ the SDK-docs section**) · DOCS-GAP protocol · the pages that are wrong.
+- `anti-patterns.md` — v5 carry-overs · unbounded height · render-before-login · the two-barrel trap.
+- `troubleshooting.md` — symptom → cause → fix.
+
+## Common pitfalls (top 5 — full list in `references/anti-patterns.md`)
+- **version_conflict** (v5 installed) · **wrong Region** · **Auth Key shipped to prod** · **rendering a widget before `login` succeeds**.
+- **Emitting v5 architecture into a v6 app.** v6 REMOVED the extension pattern — no `UIKitSettings.extensions`, no `CometChatUIKitChatExtensions`, no `DataSource`/`ChatConfigurator`/`*ExtensionDecorator`, no `CometChatUIKit.getDataSource()`. Dashboard-enabled extensions surface **automatically** with zero client code. Also gone: the v5 combined shells (`CometChatConversationsWithMessages`, `CometChatUsersWithMessages`, `CometChatMessages`, `CometChatUI`) — v6 has no shell widget; the host composes screens. Full map: `cometchat-flutter-v6-migration`.
+- **Trusting the docs on the `[verified]` signatures above.** The thread-header params, `onThreadRepliesClick`, and the search callbacks were wrong on the live pages (`DOCS-BACKLOG.md` PART 4 F1/F2/F3/F5) — **all four are now corrected upstream** (re-verified against `cometchat/docs`@`2ebb1db`, 2026-09-09), so the `[verified]` names now agree with the pages; keep them. `initFromSettings` is different: it is deliberately undocumented and stays that way (F4 WONTFIX), so this skill is its only reference.
+
+## Verify it works
+Run the app: `init` then `login` both hit `onSuccess` → the conversations screen renders **full-size** (no sliver, no unbounded-height exception) → tap a conversation → messages send/receive → **"reply in thread" opens the thread screen and back returns** → the search field pushes search, a result navigates, back pops → the composer stays visible with the keyboard open → every pushed screen pops back. Blank screen ⇒ rendered before `login` resolved, or wrong Region/App ID. No bounded height, no thread wiring, or a dead search field ⇒ **under-delivery**. Tab-based app ⇒ verify per `-placement`.
+> Build the feature; do **not** write tests or run a test framework unless asked (`RULES.md`) — the above is an advisory human pass.
+
+## Explain what you built (REQUIRED close — `RULES.md` §19)
+Don't end on a silent code dump. Briefly: **(1) what I wired** (3–5 bullets, NAME the files); **(2) decisions & why**, flagging dev-only AS dev-only (Auth Key → server token for prod; the `<uid>`); **(3) what I did NOT touch** (additive — routing/state/theme intact). Then offer THREE options as a selectable choice and **WAIT** for the pick:
+- **① Add another feature** — first check what's already wired, and ASK which dashboard extensions are already on (you can't read per-app state). Suggest 3–4 that are neither (**calls · push · polls · stickers · translation · AI smart replies · moderation**). **Never suggest reactions, mentions, quoted reply or threads — they are ON by default in v6**; offer to customize them instead. → `-features` / `-calls`.
+- **② Customize theming** — ask for a brand/preset theme or talk through options → `-customization`.
+- **③ Test it manually** — do NOTHING further; hand it back.
+
+A capability not in this pack: say so honestly + link CometChat's docs.