@cometchat/skills 4.4.1 → 5.0.0

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

@@ -0,0 +1,61 @@
+---
+name: cometchat-flutter-v6-patterns
+description: "Project wiring for the Flutter v6 UI Kit — navigation (Navigator / go_router / auto_route), state management (bloc / riverpod / provider / getx), config & secrets, platform setup, and web/desktop caveats. Triggers: 'cometchat with go_router', 'cometchat with riverpod', 'where do I put init in flutter', 'dart-define cometchat', 'cometchat flutter web'."
+license: "MIT"
+compatibility: "Flutter >=3.38.9; cometchat_chat_uikit ^6 (6.1.x, verified 6.1.0)"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat flutter patterns navigation state-management go-router riverpod config v6"
+---
+
+> **Ground truth:** the CometChat side is `cometchat-flutter-v6-core`; this skill only adds the DELTA for a given toolchain. Framework mechanics (go_router, riverpod, `--dart-define`) are baked Flutter knowledge, not kit API. Kit symbols come from the catalog.
+
+## Companion skills (read first)
+- `cometchat-flutter-v6-core` — install, credentials, the settings asset, `init→login→render`. This skill ASSUMES it.
+- `cometchat-flutter-v6-placement` — WHERE the surface goes; this skill is HOW it hooks into your app's plumbing.
+
+## Use this skill when
+Wiring the kit into a specific project shape, or debugging "where does init go" / "the theme resets on navigation" / "my secrets are in git".
+
+## Prerequisites & install
+Covered by core. No new package.
+
+## Navigation (BAKED — the delta per router)
+The kit uses plain `Navigator.push`/`pop` internally and in every recipe, which works under **all** of these — you do not have to convert its recipes.
+
+- **Plain `Navigator`** — nothing to do. Core's recipes are already this.
+- **`go_router`** — register chat screens as routes and push with `context.push('/chat/:uid')`. The kit's own internal pops still work because go_router sits on the same `Navigator`. Put the **init/login gate above the router** (wrap `MaterialApp.router`'s builder, or gate in `redirect`) so no chat route can build before login resolves.
+- **`auto_route`** — same principle: an `AutoRouteGuard` that waits for login is the idiomatic gate.
+- **Calling adds one requirement**: `navigatorKey: CallNavigationContext.navigatorKey` on `MaterialApp` (→ `-calls`). With `go_router`, pass the same key into the router config rather than creating a second one.
+
+## State management (BAKED)
+The kit is **self-contained** — every widget drives its own BLoC internally. You do **not** wire the kit into your app's state layer, and you do not need `flutter_bloc` yourself.
+- **bloc / cubit** — expose the logged-in user from your auth cubit; gate chat routes on it. Do not try to own the kit's internal blocs.
+- **riverpod** — a `FutureProvider` that performs `initFromSettings` + `login` and which chat screens `.when(...)` on, is the cleanest gate.
+- **provider / getx** — same shape: one async init future, everything chat-related below it.
+- **Reading kit state** — `CometChatUIKit.loggedInUser` is the sync getter. For list state, use the widget's `stateCallBack` / `onLoad`, not a global store.
+
+## Config & secrets (BAKED — Flutter-specific)
+`initFromSettings` reads a **bundled asset**, so it cannot read `--dart-define`. Two honest options; state the trade-off and let the user choose:
+1. **Keep `initFromSettings`** and generate `cometchat-settings.json` at build time from your existing secret source (CI writes the file). Keeps `integrationSource="ai-agent"` telemetry.
+2. **Use the classic `UIKitSettingsBuilder` + `CometChatUIKit.init(...)`** with `--dart-define` values. Works, but loses telemetry attribution.
+> Either way the Auth Key ends up in the app bundle and is **dev-only** — production means a server-minted auth token + `loginWithAuthToken` (core's `lifecycle.md`). Do NOT gitignore the registered `cometchat-settings.json` asset (a fresh clone / CI build then fails with *"No file or variants found for asset"*) — commit a **placeholder** version (no real Auth Key) that dev/CI overwrite, and guard the real key with a pre-commit/CI check.
+
+## Platform setup (BAKED)
+- **Android** — `minSdk = 26` in `android/app/build.gradle.kts` (the docs' 24 is too low); INTERNET permission; calling adds camera/mic.
+- **iOS** — `platform :ios, '15.1'` in the Podfile, then `pod install`; photo/camera/mic usage strings for attachments and calls. Both floors come from `cometchat_calls_sdk`, which the kit depends on unconditionally — they apply whether or not you use calling (DOCS-BACKLOG D7).
+- **Web** — the kit supports web, but plugin-backed features (media picker, calling) behave differently; verify anything you promise. `flutter run -d chrome` with the same settings asset.
+- **Desktop** — not a documented target; if asked, say so honestly rather than guessing.
+
+## Common pitfalls (BAKED)
+- **Init inside a screen that can be re-entered** (or inside a route builder) → repeated init. Gate ONCE at the root (`lifecycle.md`).
+- **A chat route reachable before login resolves** → blank screen. Guard the route, not just the widget.
+- **Expecting `initFromSettings` to read `--dart-define`** — it reads an asset. See above.
+- **Adding `flutter_bloc` to "connect" the kit** — unnecessary; the kit owns its blocs.
+- **Two navigator keys** when calling is on — the router and `CallNavigationContext` must share one.
+- **`cometchat-settings.json` committed** — the Auth Key is in your repo.
+- **Forgetting `WidgetsFlutterBinding.ensureInitialized()`** before an asset-reading init.
+
+## Verify it works
+The app builds on each target platform you claim; chat routes are unreachable until login resolves; navigating away and back does not re-init; secrets are not in git; with calling on, an incoming call presents from any route.

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

@@ -1,279 +1,109 @@
 ---
 name: cometchat-flutter-v6-placement
-description: >
-  Use when deciding WHERE to put CometChat in a Flutter app. Covers placement patterns:
-  tab-based home (IndexedStack), Navigator.push messages screen, modal/bottom sheet chat,
-  thread overlay, embedded panel, and floating widget. Includes Scaffold configuration,
-  resizeToAvoidBottomInset, SafeArea, and keyboard-aware spacing patterns.
-  Triggers on "add chat to my app", "where to put chat", "messages screen layout",
-  "tab bar with chat", "chat in modal", "chat in drawer", "embedded chat",
-  "Scaffold layout", or "keyboard handling".
+description: "Where CometChat chat lives in a Flutter app and how to wire each shape — a tab-based app, a chat tab inside an existing app, a full-screen route, a modal / bottom-sheet chat, or an embedded panel. Triggers: 'add a chat tab', 'full screen chat page flutter', 'chat bottom sheet', 'embed chat in my screen', 'build a full chat app in flutter'."
 license: "MIT"
-compatibility: "cometchat_chat_uikit ^6.0.1; flutter >=2.5.0"
+compatibility: "Flutter >=3.38.9; cometchat_chat_uikit ^6 (6.1.x, verified 6.1.0)"
 metadata:
   author: "CometChat"
-  version: "3.0.0"
-  tags: "cometchat flutter placement route modal drawer tabs scaffold keyboard layout"
+  version: "1.0.0"
+  tags: "cometchat flutter placement layout navigation tabs bottom-sheet v6"
 ---
 
-> **Ground truth:** `cometchat_chat_uikit: ^6.0` widgets + `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 symbols against the installed package/source before relying on them.
+> **Ground truth:** every widget below is in `catalogs/flutter-v6.json`. The recipes follow the official guides (`flutter-tab-based-chat` · `multi-tab-chat-ui-guide` · `flutter-conversation` · `flutter-one-to-one-chat`) via `../cometchat-flutter-v6-core/references/docs-map.md`. Sizing follows the ONE mobile standard in `../cometchat-flutter-v6-core/references/layout.md` — change sizing rules THERE, not here.
 
-# CometChat Flutter UIKit — Placement
+## Companion skills (read first)
+- `cometchat-flutter-v6-core` — install, credentials, `init→login→render`, the golden-path screens. This skill ASSUMES it.
+- `cometchat-flutter-v6-components` — the widget catalog these compose.
 
-WHERE to put CometChat in your Flutter app. Five patterns, each with complete code.
+## Use this skill when
+Deciding or wiring WHERE chat lives — either (a) **growing the core surface into the full tab-based app**, or (b) a scoped-down placement: a chat tab in an existing app, a modal/bottom sheet, or an embedded panel. A plain unscoped "add chat" is NOT this skill — that is the core surface in `-core`.
 
-**Before using this skill:**
-- Read `cometchat-flutter-v6-core` for init, login, and rules
-- Read `cometchat-flutter-v6-components` for component names and props (when available)
+## Prerequisites & install
+Covered by core. No new package.
 
----
-
-## Placement Recommendation
-
-| User intent | Recommended pattern | Components |
-|-------------|-------------------|------------|
-| Messaging app | Tab-based home (full screen) | IndexedStack + CometChatConversations + Messages screen |
-| Marketplace / platform | Navigator.push from product page | Single-thread messages screen |
-| SaaS / dashboard | Modal or bottom sheet | CometChatConversations in BottomSheet |
-| Social / community | Tab-based home with calls | IndexedStack + Conversations + CallLogs + Users + Groups |
-| Support / helpdesk | Floating action button → modal | FAB + showModalBottomSheet |
-| Just exploring | Replace home page | CometChatConversations as Scaffold body |
-
----
-
-## Pattern 1: Tab-Based Home (Most Common)
-
-BottomNavigationBar with IndexedStack to preserve tab state. This is what master_app uses.
-
-```dart
-class HomeScreen extends StatefulWidget {
-  const HomeScreen({super.key});
-  @override
-  State<HomeScreen> createState() => _HomeScreenState();
-}
-
-class _HomeScreenState extends State<HomeScreen> {
-  int _currentIndex = 0;
-
-  @override
-  Widget build(BuildContext context) {
-    return Scaffold(
-      body: IndexedStack(
-        index: _currentIndex,
-        children: [
-          // Tab 0: Conversations
-          CometChatConversations(
-            hideAppbar: true,
-            onItemTap: (conversation) => _openChat(context, conversation),
-          ),
-          // Tab 1: Call Logs
-          CometChatCallLogs(hideAppbar: true),
-          // Tab 2: Users
-          CometChatUsers(
-            hideAppbar: true,
-            onItemTap: (_, user) => _pushMessages(context, user: user),
-          ),
-          // Tab 3: Groups
-          CometChatGroups(
-            hideAppbar: true,
-            onItemTap: (_, group) => _pushMessages(context, group: group),
-          ),
-        ],
-      ),
-      bottomNavigationBar: BottomNavigationBar(
-        currentIndex: _currentIndex,
-        onTap: (i) => setState(() => _currentIndex = i),
-        type: BottomNavigationBarType.fixed,
-        items: const [
-          BottomNavigationBarItem(icon: Icon(Icons.chat_outlined), label: 'Chats'),
-          BottomNavigationBarItem(icon: Icon(Icons.call_outlined), label: 'Calls'),
-          BottomNavigationBarItem(icon: Icon(Icons.person_outline), label: 'Users'),
-          BottomNavigationBarItem(icon: Icon(Icons.people_outline), label: 'Groups'),
-        ],
-      ),
-    );
-  }
-
-  void _openChat(BuildContext context, Conversation conversation) {
-    final user = conversation.conversationWith is User
-        ? conversation.conversationWith as User : null;
-    final group = conversation.conversationWith is Group
-        ? conversation.conversationWith as Group : null;
-    _pushMessages(context, user: user, group: group);
-  }
-
-  void _pushMessages(BuildContext context, {User? user, Group? group}) {
-    Navigator.push(context, MaterialPageRoute(
-      builder: (_) => MessagesScreen(user: user, group: group),
-    ));
-  }
-}
-```
-
-**Key details:**
-- `IndexedStack` keeps all tabs alive — no re-fetch when switching tabs
-- `hideAppbar: true` on all components — the parent Scaffold provides the AppBar
-- `onItemTap` extracts `User`/`Group` from `conversation.conversationWith`
-- Protected groups need a join/password screen before navigating to messages
-
----
-
-## Pattern 2: Messages Screen (Navigator.push)
+## The one invariant every placement shares
+Mobile shows **one screen at a time**, so placement is a NAVIGATION problem, not a column problem:
+1. **Bounded height** — every kit list needs `Expanded`/`Flexible` or a fixed height. Unbounded ⇒ exception or a zero-height list.
+2. **`Scaffold` + `SafeArea`**, `resizeToAvoidBottomInset` left at `true`.
+3. **Round-trip** — everything you push must pop back to the state that opened it.
+4. **One init/login gate at the root**, not per screen (core's `lifecycle.md`).
 
-The standard messages screen pushed from any conversation/user/group tap.
+## Placement patterns (BAKED)
 
+**A. Tab-based app (the GROW target — the full app).** Bottom tabs: Chats (`CometChatConversations`) · Users (`CometChatUsers`) · Groups (`CometChatGroups`) · Calls (`CometChatCallLogs`), each pushing the message screen. **Incoming calls need NO widget from you** — once calling is enabled the kit's `CallEventService` presents the incoming-call overlay itself from any tab; you only set `navigatorKey: CallNavigationContext.navigatorKey` on your `MaterialApp` (see `-calls`). Do NOT mount `CometChatIncomingCall` at the root yourself — that plus the kit's own overlay = a double incoming screen. Build from `flutter-tab-based-chat`. Note `hideAppbar: true` on the list widgets when your own `Scaffold` already supplies one, or you get two headers.
 ```dart
-class MessagesScreen extends StatefulWidget {
-  final User? user;
-  final Group? group;
-  const MessagesScreen({super.key, this.user, this.group})
-      : assert(user != null || group != null);
-  @override
-  State<MessagesScreen> createState() => _MessagesScreenState();
-}
-
-class _MessagesScreenState extends State<MessagesScreen> {
-  late User? _user;
-  late Group? _group;
-
-  @override
-  void initState() {
-    super.initState();
-    _user = widget.user;   // Mutable copy — updated by SDK listeners
-    _group = widget.group;
-  }
-
-  @override
-  Widget build(BuildContext context) {
-    final colorPalette = CometChatThemeHelper.getColorPalette(context);
-    return Scaffold(
-      resizeToAvoidBottomInset: true, // matches sample app; composer clamps to viewInsets (ENG-34434)
-      appBar: CometChatMessageHeader(
-        user: _user,
-        group: _group,
-        onBack: () => Navigator.pop(context),
-      ),
-      body: SafeArea(
-        top: false, // Header is the appBar — top inset already handled; keep bottom inset
-        child: Container(
-          color: colorPalette.background3,
-          child: Column(
-            children: [
-              Expanded(child: CometChatMessageList(user: _user, group: _group)),
-              CometChatMessageComposer(user: _user, group: _group),
-            ],
-          ),
-        ),
-      ),
-    );
-  }
-}
+// Tab-based placement: four list components + group details + global search
+// Users tab
+CometChatUsers(
+  hideAppbar: true,
+  onItemTap: (user) => Navigator.push(context, MaterialPageRoute(builder: (_) => MessageScreen(user: user))),
+)
+// Groups tab
+CometChatGroups(
+  hideAppbar: true,
+  onItemTap: (group) => Navigator.push(context, MaterialPageRoute(builder: (_) => MessageScreen(group: group))),
+)
+// Group details: members + kick/ban/scope built in
+CometChatGroupMembers(group: group, hideAppbar: true)
+// Global search from conversations list (onSearchTap -> push this screen). Result callbacks are
+// onConversationClicked/onMessageClicked — verified against kit 6.1.0 and the live search page
+// (DOCS-BACKLOG F3 corrected upstream).
+CometChatSearch(
+  onConversationClicked: (conv) { Navigator.pop(context); openChat(conv); },
+  onMessageClicked: (msg) { Navigator.pop(context); openChat(msg); },
+  onBack: () => Navigator.pop(context),
+)
 ```
-
-### Critical Scaffold Rules
-
-1. `resizeToAvoidBottomInset: true` (or omit — `true` is the Scaffold default) — matches the kit sample app (`messages_screen.dart` defaults it; `thread_screen.dart` sets it `true`). The composer clamps the native keyboard height to Flutter's `viewInsets` (kit fix ENG-34434), so `true` does NOT double-compensate on `^6.0.1`. (Pre-6.0.1 kits double-compensated with `true`; `false` was the old workaround — if you see a double keyboard gap, upgrade the kit.)
-2. `SafeArea(top: false)` wrapping `Container(color: colorPalette.background3, ...)` — the header is the `appBar`, so the top inset is already handled; keep the bottom inset. The `background3` container gives the list/composer the correct surface color.
-3. Mutable `_user`/`_group` — Keep mutable copies in State, not `widget.user`/`widget.group`. Update from SDK listeners for block/kick/scope changes.
-
----
-
-## Pattern 3: Thread Screen
-
-Thread replies pushed from `onThreadRepliesClick`. Same Scaffold rules apply.
-
 ```dart
-class ThreadScreen extends StatelessWidget {
-  final User? user;
-  final Group? group;
-  final BaseMessage message;
-  final CometChatMessageTemplate? template;
+import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
+import 'package:flutter/material.dart';
 
-  const ThreadScreen({
-    super.key, this.user, this.group,
-    required this.message, this.template,
-  });
+class ChatsTab extends StatelessWidget {
+  const ChatsTab({super.key});
 
   @override
   Widget build(BuildContext context) {
-    final colorPalette = CometChatThemeHelper.getColorPalette(context);
     return Scaffold(
-      resizeToAvoidBottomInset: true, // same as messages screen
-      appBar: CometChatMessageHeader(
-        user: user, group: group,
-        onBack: () => Navigator.pop(context),
-      ),
+      appBar: AppBar(title: const Text('Chats')),
       body: SafeArea(
-        child: Container(
-          color: colorPalette.background3,
-          child: Column(
-            children: [
-              CometChatThreadedHeader(
-                parentMessage: message,
-                loggedInUser: CometChatUIKit.loggedInUser!,
-                template: template,
-              ),
-              Expanded(
-                child: CometChatMessageList(
-                  user: user, group: group,
-                  parentMessageId: message.id,
-                  // Scope the list to this thread only: exclude the parent and
-                  // request just the replies for message.id.
-                  withParent: false,
-                  messagesRequestBuilder: MessagesRequestBuilder()
-                    ..parentMessageId = message.id,
-                  hideReplyInThreadOption: true,
-                ),
+        child: CometChatConversations(
+          hideAppbar: true,                       // the Scaffold already has one
+          onItemTap: (conversation) {
+            final entity = conversation.conversationWith;
+            Navigator.push(context, MaterialPageRoute(
+              builder: (_) => MessageScreen(
+                user: entity is User ? entity : null,
+                group: entity is Group ? entity : null,
               ),
-              CometChatMessageComposer(
-                user: user, group: group,
-                parentMessageId: message.id,
-              ),
-            ],
-          ),
+            ));
+          },
         ),
       ),
     );
   }
 }
 ```
+> The Calls tab (`CometChatCallLogs`) comes from the **calls barrel** — that screen imports both barrels (`-calls`). Incoming-call presentation is handled by the kit itself; you don't mount an incoming widget at the root.
 
-Wire it from the messages screen:
-```dart
-CometChatMessageList(
-  onThreadRepliesClick: (message, ctx, {template}) {
-    Navigator.push(context, MaterialPageRoute(
-      builder: (_) => ThreadScreen(
-        user: _user, group: _group,
-        message: message, template: template,
-      ),
-    ));
-  },
-)
-```
-
----
-
-## Pattern 4: Modal / Bottom Sheet Chat
+**B. Chat tab inside an existing app.** Same as (A) but only the Chats tab: drop `CometChatConversations` into your existing tab scaffold. Keep the init/login gate at YOUR app root so chat is ready before the tab is first shown.
 
-Quick chat access from any screen without full navigation.
+**C. Full-screen route.** `Navigator.pushNamed('/chat')` → a `Scaffold` holding the core surface. The simplest placement; nothing extra.
 
+**D. Modal / bottom-sheet chat.** A sheet has no intrinsic height — give it one explicitly, or the list throws.
 ```dart
-void _openChatModal(BuildContext context, User user) {
+import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
+import 'package:flutter/material.dart';
+
+void openChatSheet(BuildContext context, User user) {
   showModalBottomSheet(
     context: context,
-    isScrollControlled: true,
-    useSafeArea: true,
+    isScrollControlled: true,                     // REQUIRED: lets it exceed half-height
     builder: (_) => SizedBox(
-      height: MediaQuery.sizeOf(context).height * 0.85,
-      child: Scaffold(
-        resizeToAvoidBottomInset: true, // same rule applies to the inner Scaffold
-        appBar: CometChatMessageHeader(
-          user: user,
-          onBack: () => Navigator.pop(context),
-        ),
-        body: Column(
+      height: MediaQuery.of(context).size.height * 0.9,   // bounded — the kit fills it
+      child: SafeArea(
+        child: Column(
           children: [
+            CometChatMessageHeader(user: user),
             Expanded(child: CometChatMessageList(user: user)),
             CometChatMessageComposer(user: user),
           ],
@@ -283,145 +113,28 @@ void _openChatModal(BuildContext context, User user) {
   );
 }
 ```
-
-**Key details:**
-- `isScrollControlled: true` — allows the sheet to be taller than half screen
-- `useSafeArea: true` — respects notch/status bar
-- Inner `Scaffold` uses `resizeToAvoidBottomInset: true` (same as the messages screen)
-- Use `MediaQuery.sizeOf(context)` not `MediaQuery.of(context).size`
-
----
-
-## Pattern 5: Embedded Panel
-
-Chat embedded alongside other content (e.g., split view on tablets).
-
-```dart
-class SplitView extends StatelessWidget {
-  final User user;
-  const SplitView({super.key, required this.user});
-
-  @override
-  Widget build(BuildContext context) {
-    return Scaffold(
-      resizeToAvoidBottomInset: true,
-      body: Row(
-        children: [
-          // Left: your app content
-          Expanded(flex: 3, child: YourProductPage()),
-          // Right: embedded chat
-          Expanded(
-            flex: 2,
-            child: Column(
-              children: [
-                CometChatMessageHeader(user: user),
-                Expanded(child: CometChatMessageList(user: user)),
-                CometChatMessageComposer(user: user),
-              ],
-            ),
-          ),
-        ],
-      ),
-    );
-  }
-}
-```
-
----
-
-## Pattern 6: Floating Action Button → Chat
-
-```dart
-Scaffold(
-  body: YourMainContent(),
-  floatingActionButton: FloatingActionButton(
-    onPressed: () => _openChatModal(context, supportUser),
-    child: const Icon(Icons.chat),
-  ),
-)
-```
-
----
-
-## Incoming Calls — Global Placement
-
-Incoming call handling MUST be at the app root level, not per-screen. **`VoipCallHandler` does NOT exist as a public symbol** (it appears only in comments inside `call_event_service.dart` and `ongoing_call_bloc.dart`). The canonical V6 root-mount API is `CometChatUIKit.init` + `MaterialApp(navigatorKey: CallNavigationContext.navigatorKey)`:
-
-```dart
-import 'package:cometchat_chat_uikit/cometchat_calls_uikit.dart' show CallNavigationContext;
-import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
-
-void main() async {
-  WidgetsFlutterBinding.ensureInitialized();
-  await CometChatUIKit.init(
-    uiKitSettings: (UIKitSettingsBuilder()
-      ..appId = APP_ID
-      ..region = REGION
-      ..authKey = AUTH_KEY
-      ..subscriptionType = CometChatSubscriptionType.allUsers
-      ..enableCalls = true)
-      .build(),
-  );
-  runApp(MyApp());
-}
-
-class MyApp extends StatelessWidget {
-  @override
-  Widget build(BuildContext context) {
-    return MaterialApp(
-      navigatorKey: CallNavigationContext.navigatorKey, // ← Bug 1 fix per project_v6_flutter_calls_partial; even 6.0.1 sample omits this
-      home: HomeScreen(),
-    );
-  }
-}
-```
-
-See `cometchat-flutter-v6-calls` §1.7 for full root-mount details. CallEventService mounts `IncomingCallOverlay` automatically when `enableCalls=true`.
-
----
-
-## Anti-Patterns
-
-```dart
-// ❌ WRONG — CometChatMessageList not wrapped in Expanded (unbounded → won't scroll)
-Scaffold(
-  body: Column(children: [
-    CometChatMessageList(user: user),   // needs Expanded inside a Column
-    CometChatMessageComposer(user: user),
-  ]),
-)
-
-// ❌ WRONG — passing widget.user directly (stale after block/kick)
-CometChatMessageList(user: widget.user)
-
-// ❌ WRONG — incoming call handler only on messages screen
-// Calls ring on ALL screens, not just the one with call buttons
-
-// ❌ WRONG — navigating to messages without extracting user/group
-onItemTap: (conv) => Navigator.push(context, MaterialPageRoute(
-  builder: (_) => MessagesScreen(conversation: conv), // Wrong!
-))
-
-// ✅ CORRECT — extract user/group from conversation
-onItemTap: (conv) {
-  final user = conv.conversationWith is User ? conv.conversationWith as User : null;
-  final group = conv.conversationWith is Group ? conv.conversationWith as Group : null;
-  Navigator.push(context, MaterialPageRoute(
-    builder: (_) => MessagesScreen(user: user, group: group),
-  ));
-}
-```
-
----
-
-## Checklist
-
-- [ ] `resizeToAvoidBottomInset: true` (or omitted — default) on Scaffolds with `CometChatMessageComposer`
-- [ ] `SafeArea(top: false)` wrapping `Container(color: colorPalette.background3, ...)` for the message screen body
-- [ ] Mutable `_user`/`_group` state copies, not `widget.user`/`widget.group`
-- [ ] `onItemTap` extracts `User`/`Group` from `conversation.conversationWith`
-- [ ] Protected groups handled (check `group.hasJoined` and `group.type`)
-- [ ] Incoming call handler mounted at app root level
-- [ ] Thread screen also uses `resizeToAvoidBottomInset: true`
-- [ ] `hideAppbar: true` when parent provides its own AppBar
-- [ ] `IndexedStack` used for tab-based home (preserves tab state)
+> `isScrollControlled: true` + an explicit height are both required; without them the sheet caps at ~half screen and the composer fights the keyboard.
+
+**E. Embedded panel (chat inside a bigger screen).** Give the region a fixed height or a sized flex cell — never let it sit inside an unbounded `SingleChildScrollView`/`Column`. If the host page scrolls, the chat needs its own `SizedBox(height: …)`.
+
+## Choosing
+| The ask | Placement |
+|---|---|
+| "add chat" (unscoped) | NOT here — core surface (`-core`) |
+| "build the full chat app" | A — tab-based |
+| "add a chat tab" | B |
+| "a chat screen/page" | C |
+| "popup / floating / sheet chat" | D |
+| "chat inside my dashboard screen" | E |
+
+## Common pitfalls (BAKED)
+- **Over-delivering the tab app for a plain "add chat"** — that is the core surface, not this.
+- **A list with no bounded height** — the most common Flutter failure (`layout.md`).
+- **A bottom sheet without `isScrollControlled` + an explicit height.**
+- **Two headers** — your `Scaffold` `AppBar` plus the widget's own; set `hideAppbar: true`.
+- **Mounting `CometChatIncomingCall` yourself** — unnecessary and causes a double incoming-call screen. The kit presents the overlay automatically once calling is enabled; you only set `CallNavigationContext.navigatorKey` on your `MaterialApp` (`-calls`).
+- **A pushed screen with no way back** (`navigation-round-trip`).
+- **Re-running init/login per screen** instead of gating once at the root.
+
+## Verify it works
+Each placement renders full-size with no unbounded-height exception; item tap pushes and back pops; the composer stays above the keyboard; on the tab app an incoming call surfaces from every tab. Growing beyond this ⇒ `-calls` / `-features`.