@cometchat/skills 4.4.1 → 5.0.0

package/skills/cometchat-flutter-v6-core/references/anti-patterns.md

@@ -0,0 +1,55 @@
+# anti-patterns — the real bugs, Flutter v6
+
+## Startup
+1. **Rendering a `CometChat*` widget before `login` succeeds** → blank screen or a listener exception. Gate
+   the first frame (`lifecycle.md`).
+2. **Missing `WidgetsFlutterBinding.ensureInitialized()`** → `initFromSettings` cannot read the settings
+   asset through `rootBundle`; first-run crash.
+3. **`init` inside a screen's `initState`** that can be re-entered → repeated init, raced Calls-SDK routing.
+4. **Using `init()` + `UIKitSettingsBuilder` instead of `initFromSettings()`** → loses
+   `integrationSource="ai-agent"` telemetry attribution (`RULES.md` §5). The docs still show the old path.
+5. **A REAL Auth Key committed in `cometchat-settings.json`** → the key is in your repo history. Do NOT fix this by gitignoring the file — it is a registered Flutter asset, so a fresh clone / CI `flutter build bundle` then fails with *"No file or variants found for asset."* Commit a **placeholder** `cometchat-settings.json` (empty/placeholder `authKey`) that dev and CI overwrite locally; guard the real key with a pre-commit/CI check.
+6. **Auth Key in a production build** → it authenticates *any* user. Prod is `loginWithAuthToken` with a
+   server-minted token.
+7. **Inventing a UID.** `login` requires a user that already exists. Ask, or read Dashboard → Users.
+
+## Layout
+8. **A kit list without `Expanded`/`Flexible` in a `Column`** → unbounded-height exception or a zero-height
+   list. The single most common Flutter integration failure (`layout.md`).
+9. **The surface inside a `SingleChildScrollView`** → infinite height constraints; same failure.
+10. **`resizeToAvoidBottomInset: false`** → the composer disappears under the keyboard.
+11. **No `Scaffold`/`SafeArea`** → missing `Material` ancestor, or UI under the notch/home indicator.
+
+## v5 carry-overs (all REMOVED in v6 — see `cometchat-flutter-v6-migration`)
+12. **Registering extensions** — `UIKitSettings.extensions`, `CometChatUIKitChatExtensions`,
+    `DataSource`, `ChatConfigurator`, `*ExtensionDecorator`, `CometChatUIKit.getDataSource()`. v6 deleted
+    the entire pattern; a dashboard-enabled extension surfaces **automatically** with zero client code.
+    Emitting registration is a defect, not a harmless no-op.
+13. **Combined shell widgets** — `CometChatConversationsWithMessages`, `CometChatUsersWithMessages`,
+    `CometChatGroupsWithMessages`, `CometChatMessages`, `CometChatUI`, `CometChatMessenger`,
+    `CometChatUserList`, `CometChatContactList`. v6 has **no** shell widget; the host composes screens.
+14. **GetX controllers** — `CometChatMessagesController`, `CometChatOngoingCallController`. v6 is BLoC.
+15. **`CometChatCompactMessageComposer`** → one `CometChatMessageComposer`.
+
+## Cross-family contamination
+16. **Carrying a React name into Flutter.** `CometChatThreadHeader` does not exist here — it is
+    `CometChatThreadedHeader`. Nor do `showSearchOption`/`onSearchOptionClicked` on the message header, or
+    `onItemClick` on the conversation list (it is **`onItemTap`**). Equally: `CometChatMediaRecorder` DOES
+    exist in Flutter though it is a React phantom. **Never reuse another family's symbol or phantom list —
+    check `catalogs/flutter-v6.json`.**
+17. **Importing calls widgets from the chat barrel.** `CometChatIncomingCall`, `CometChatOutgoingCall`,
+    `CometChatCallButtons`, `CometChatCallLogs`, `CometChatCallBubble` and `CometChatCalls` resolve ONLY
+    from `package:cometchat_chat_uikit/cometchat_calls_uikit.dart`. A calls screen imports **both** barrels.
+18. **Adding `cometchat_sdk` as a direct dependency to get `User`/`Group`/`TextMessage`.** The kit barrel
+    already re-exports the whole Chat SDK.
+
+## Composition
+19. **Passing `parentMessageId` without `user:`/`group:`** on a thread list/composer → replies silently
+    never send. Both are required.
+20. **A dead-ending affordance.** A search field that opens nothing, or a thread indicator with no
+    `onThreadRepliesClick` — wire it to a destination or hide it (`hideSearch`).
+21. **Hand-rolling what the widget already exposes.** Custom UI belongs in a slot
+    (`auxiliaryButtonView` / `trailingView` / `appBarOptions`), never stacked on top of the widget.
+22. **Client-side filtering the conversation list.** Scope `conversationsRequestBuilder` instead.
+23. **Hand-rolling moderation or report UI.** Both are automatic in `CometChatMessageList`; the work is in
+    the Dashboard.

package/skills/cometchat-flutter-v6-core/references/docs-map.md

@@ -0,0 +1,143 @@
+# docs-map — CometChat Flutter v6: intent → the exact docs page to fetch
+
+Fetch a page instead of guessing a prop. This file is the map; `SKILL.md` bakes only the hot path.
+
+## Reaching docs — PREFER the CometChat docs MCP; fetch is the fallback
+The canonical doc channel is the **first-party CometChat docs MCP** — tools `search_cometchat_docs`,
+`fetch_cometchat_doc_page`, and `get_cometchat_implementation_bundle`. **If those tools are connected,
+use them instead of a raw web fetch:**
+- **Find the page** → `search_cometchat_docs(query, version?)` — replaces browsing the scoped `llms-*` index.
+- **Read the page** → `fetch_cometchat_doc_page(path)` — pass the SAME `<path>` the tables below list
+  (the conversations page path for your platform); the MCP resolves the `.md` twin and returns raw Markdown.
+  A full `https://…/docs/<path>` URL also works.
+- **A whole feature/recipe** → `get_cometchat_implementation_bundle(...)` is **NON-AUTHORITATIVE** — curated STATIC recipes that can lag the live docs (verified stale vs v7: e.g. `CometChatConversationsWithMessages`, `css-variables.css`). Treat any bundle as a hint only: RECONCILE it against the `fetch_cometchat_doc_page` result + the pack's hardening; never emit bundle code verbatim.
+
+The MCP reads whatever docs environment it is pointed at (production by default; a preview when repointed),
+so it also carries the environment-swap concern below — no hardcoded host on the skill side.
+
+**If the MCP tools are NOT connected:** add it (`claude mcp add --transport http cometchat-docs https://mcp.cometchat.com/mcp`, or reinstall/enable the plugin) and retry; only if it still will not connect, fall back to a plain fetch via `DOCS_BASE` (defined next).
+Either way the `<path>` catalog in this file is the source of truth for WHICH page — MCP-vs-fetch is only HOW.
+
+## DOCS_BASE — the fetch FALLBACK entry point (⚠️ SWAP HERE to change environments)
+```
+DOCS_BASE = https://www.cometchat.com/docs
+```
+> The ONLY line to change for a preview/staging deploy. Every path below is identical across environments.
+>
+> **Fetch rule:** build a URL as `DOCS_BASE` + the path shown, then append `.md`. Never hardcode a host
+> anywhere else; never read installed Dart source in place of a missing doc (see the DOCS GAP protocol).
+
+## The convention
+`DOCS_BASE` + `<path>` + `.md` → raw Markdown (verbatim code + prop tables).
+```
+Fetch:  {DOCS_BASE}/ui-kit/flutter/conversations.md
+```
+Fallback order: `.md` twin → the same URL **without** `.md` (HTML) → **DOCS GAP** (below).
+
+## ⚠️ Scoped index — DOES NOT EXIST YET for Flutter (tracked DOCS GAP, go-live dependency)
+```
+{DOCS_BASE}/ui-kit/flutter/llms.txt   → 404 as of 2026-08-21
+{DOCS_BASE}/sdk/flutter/llms.txt      → 404 as of 2026-08-21
+```
+Neither scoped index has been generated. **Until they exist, use the page table below as the index**
+(it was derived from the global index and is complete for this family), and fall back to the global
+all-products index — `{DOCS_BASE}/llms.txt` (large; last resort) — for anything not listed.
+> **Go-live ask (owner: docs):** generate the **scoped UI-Kit `llms.txt` for Flutter v6, including its
+> "Task guides (recipes)" section**, and the **SDK `llms.txt` for the Flutter Chat SDK**. Without them the
+> docs-maximal, guide-first completeness check degrades to component-wiring only. Tracked in `DOCS-BACKLOG.md`.
+
+## `[verified]` signatures — confirmed against the kit AND the live docs
+These signatures were wrong on the live pages when the skill was written (`DOCS-BACKLOG` F1/F2/F3/F5); all four
+were **corrected upstream** and re-verified against `cometchat/docs`@`2ebb1db` (2026-09-09), so the pages now
+AGREE with `SKILL.md`. Kept here as the authoritative signature reference. Re-verify with
+`npm run verify:fences:flutter-v6` if a page ever drifts again.
+
+| Symbol | Confirmed signature |
+|---|---|
+| `CometChatThreadedHeader` | `parentMessage:` + required `loggedInUser:` (not `message:`) |
+| `onThreadRepliesClick` | `void Function(BaseMessage, BuildContext, {CometChatMessageTemplate? template})` |
+| `CometChatThreadedHeader` back/error | none — no `onBack:` / `onError:`; back comes from the screen's own `AppBar` |
+| `CometChatSearch` results | `onConversationClicked` / `onMessageClicked` |
+| `getting-started` init | `initFromSettings()` + `cometchat-settings.json` — **deliberately undocumented (F4 WONTFIX)**; this skill is its reference |
+
+## Component docs (intent → path)
+| Intent | Path |
+|---|---|
+| Install · init · login · first screen | `/ui-kit/flutter/getting-started` |
+| What v6 is · architecture | `/ui-kit/flutter/overview` · `/ui-kit/flutter/components-overview` |
+| Conversation list props | `/ui-kit/flutter/conversations` |
+| Message list props | `/ui-kit/flutter/message-list` |
+| Composer props | `/ui-kit/flutter/message-composer` |
+| Message header props | `/ui-kit/flutter/message-header` |
+| Thread screen | `/ui-kit/flutter/threaded-messages-header` (⚠️ see the wrong-pages table) |
+| Search | `/ui-kit/flutter/search` (⚠️ see the wrong-pages table) |
+| Users / Groups / Members | `/ui-kit/flutter/users` · `/groups` · `/group-members` |
+| Calls (incoming/outgoing/logs/buttons) | `/ui-kit/flutter/call-features` · `/incoming-call` · `/outgoing-call` · `/call-logs` · `/call-buttons` |
+| Notification feed | `/ui-kit/flutter/notification-feed` |
+| Push notifications (FCM/APNs setup — `-push`) | `/notifications/push-overview` · `/notifications/flutter-push-notifications-android` · `/notifications/flutter-push-notifications-ios` (NOT the legacy singular `/notifications/flutter-push-notifications`) |
+| Theming — tokens & palette | `/ui-kit/flutter/theme-introduction` · `/color-resources` · `/component-styling` · `/message-bubble-styling` |
+| Customization — slots & behavior | `/ui-kit/flutter/customization-overview` · `-view-slots` · `-state-views` · `-menu-options` · `-bloc-data` · `-datasource` · `-text-formatters` |
+| Custom message types | `/ui-kit/flutter/message-template` |
+| Formatters (mentions / custom / shortcut) | `/ui-kit/flutter/mentions-formatter-guide` · `/custom-text-formatter-guide` · `/shortcut-formatter-guide` |
+| Events (SDK listeners vs UI events) | `/ui-kit/flutter/events` |
+| Extensions (all dashboard-enabled) | `/ui-kit/flutter/extensions` |
+| Localization | `/ui-kit/flutter/localize` |
+| Sounds | `/ui-kit/flutter/sound-manager` |
+| Methods / helpers | `/ui-kit/flutter/methods` |
+| Troubleshooting | `/ui-kit/flutter/troubleshooting` |
+| v5 → v6 upgrade | `/ui-kit/flutter/upgrading-from-v5` |
+
+## Task guides (recipes) — BUILD FROM THESE, then COMPARE (docs-maximal, `RULES.md` §20)
+For a whole task, **build from the guide and compare your implementation against it for completeness**,
+then apply the hardening deltas in `SKILL.md`. **No matching guide? Build the normal way** (wire the
+widgets + fetch props) — the guide is an enhancement, not a prerequisite.
+
+| Task | Guide |
+|---|---|
+| Guide index | `/ui-kit/flutter/guide-overview` |
+| One-to-one chat | `/ui-kit/flutter/flutter-one-to-one-chat` |
+| Conversation + messages | `/ui-kit/flutter/flutter-conversation` |
+| Tab-based app (the grow target) | `/ui-kit/flutter/flutter-tab-based-chat` · `/multi-tab-chat-ui-guide` |
+| Group chat | `/ui-kit/flutter/guide-group-chat` |
+| Threaded messages | `/ui-kit/flutter/guide-threaded-messages` (⚠️ signatures wrong — see above) |
+| Start a new chat | `/ui-kit/flutter/guide-new-chat` |
+| Message privately | `/ui-kit/flutter/guide-message-privately` |
+| Block / unblock | `/ui-kit/flutter/guide-block-unblock-user` |
+| Call log details | `/ui-kit/flutter/guide-call-log-details` |
+| AI agentic flow | `/ui-kit/flutter/guide-message-agentic-flow` |
+
+## SDK docs — the FALLBACK reference (so the SDK ALSO works, `RULES.md` §13)
+**UI-Kit first, SDK fallback.** For every feature, first check whether the UI Kit has a widget/prop
+(the table above + the catalog). If it does — use it. If it does NOT (AI agents, campaigns,
+advanced/AI moderation, transient messages, bots, webhooks, banned-members listing, low-level presence)
+— drop to the Flutter Chat SDK and call its method directly. The SDK is **already installed and
+re-exported by the kit barrel**, so `User`, `Group`, `Conversation`, `BaseMessage`, `TextMessage` and the
+`*RequestBuilder` types need no extra import.
+```
+SDK_DOCS_BASE = https://www.cometchat.com/docs/sdk/flutter
+```
+| Intent | Path |
+|---|---|
+| Overview · setup · auth | `/overview` · `/setup` · `/authentication-overview` |
+| Send / receive / edit / delete messages | `/messaging-overview` · `/send-message` · `/receive-messages` |
+| Real-time listeners | `/real-time-listeners` · `/connection-status` |
+| Users · presence · block | `/users-overview` · `/user-presence` · `/block-users` |
+| Groups · members · kick/ban | `/groups-overview` · `/group-kick-ban-members` |
+| Conversations & unread | `/conversations-overview` |
+| Threads | `/threaded-messages` |
+| AI agents / chatbots | `/ai-agents` · `/ai-moderation` |
+| Campaigns | `/campaigns` |
+| Push token registration | no `sdk/flutter` page (`/sdk/flutter/push-notifications` 404s) — use the three `/notifications/*` push pages in the component table above |
+| Webhooks | `/webhooks-overview` |
+> Each SDK page carries an **AI Integration Quick Reference** block with method signatures — read that
+> first. The SDK's scoped `llms.txt` does not exist yet (see the index gap above); use this table.
+
+## DOCS GAP protocol (`RULES.md` §20 — never silently source-fill)
+If a prop/method/behavior you need is **absent or wrong** in the docs:
+1. **Do not** substitute reading installed Dart source as though it were documentation, and do not bake a
+   permanent workaround into a skill for what is really a docs bug (AUDIT-072 / CHECKLIST row 24).
+2. **Verify** the actual behavior by compiling against the pinned kit
+   (`npm run verify:fences:flutter-v6` / `test-suite/typecheck/flutter-v6`) — the compiler is the oracle.
+3. **TELL THE DEVELOPER**: page · section · what's there now · what it should say · why it matters.
+4. **Record it** in `DOCS-BACKLOG.md` (owner **docs**) + an `AUDIT.md` row, and bake only a clearly-labelled
+   temporary stopgap in the skill, citing the backlog entry — exactly as F1–F5 are handled in `SKILL.md`.

package/skills/cometchat-flutter-v6-core/references/layout.md

@@ -0,0 +1,45 @@
+# layout — the mobile sizing standard (bounded height, safe area, keyboard)
+
+The Flutter instance of the pack's reflow-free-surface standard. The web recipe (`100dvh`, `min-height:0`
+columns, prepared ancestor chain) does NOT apply here; the principle does: **the kit's list widgets expand
+to fill their parent, so the parent must supply a bounded height — never let content drive it.**
+
+## The four invariants
+
+**1. Bounded height for every list.** `CometChatConversations`, `CometChatMessageList`, `CometChatUsers`,
+`CometChatGroups`, `CometChatGroupMembers` and `CometChatSearch` all want to fill their parent. Inside a
+`Column`, wrap them in `Expanded` (or `Flexible`); otherwise Flutter throws
+*"RenderFlex children have non-zero flex but incoming height constraints are unbounded"* — or the list
+collapses to zero height.
+```dart
+Widget messagePane(User user) => Column(children: [
+      CometChatMessageHeader(user: user),
+      Expanded(child: CometChatMessageList(user: user)),   // REQUIRED — bounds the list
+      CometChatMessageComposer(user: user),
+    ]);
+```
+
+**2. Never nest the surface in an unbounded scroll parent.** A `SingleChildScrollView`, a `ListView`, or a
+`Column` inside one gives its children *infinite* height, so a kit list inside it throws or renders
+nothing. If chat must sit inside a scrolling page, give it a **fixed** height (`SizedBox(height: 480)`) or
+a sized cell — a content-driven box is the defect, not the kit.
+
+**3. `Scaffold` + `SafeArea`.** The surface belongs in a `Scaffold` (it supplies the `Material` ancestor the
+kit's widgets need) with `SafeArea` so the composer clears the home indicator and the header clears the
+notch. A bare `Container` at the root is the usual cause of "the composer is under the home bar".
+
+**4. Keyboard avoidance — leave `resizeToAvoidBottomInset` alone.** It defaults to `true`, which is what
+keeps `CometChatMessageComposer` above the keyboard. Setting it to `false`, or placing the surface inside a
+widget that swallows the inset, hides the input the moment the user types. If the composer is covered:
+check for `resizeToAvoidBottomInset: false`, a nested `Scaffold`, or a manual `MediaQuery.viewInsets` hack.
+
+## No load-transition reflow
+The kit ships its own loading and empty states, so give it the full box immediately and let it render its
+loader **inside** that box. Do not gate the whole screen behind your own placeholder→chat swap sized
+differently from the final surface — that is what makes the UI jump when messages arrive. (The init/login
+gate in `lifecycle.md` is different and correct: it runs *before* the chat screen exists at all.)
+
+## Embedded / modal placements
+A bottom sheet, dialog, or embedded panel must still supply a bounded height — `showModalBottomSheet` with
+a `SizedBox(height: MediaQuery.of(context).size.height * 0.9)`, or a `Container` with a fixed height.
+Recipes: `cometchat-flutter-v6-placement`.

package/skills/cometchat-flutter-v6-core/references/lifecycle.md

@@ -0,0 +1,87 @@
+# lifecycle — init once, login, gate the first frame, log out
+
+Loaded when the task touches startup, session, or "why is it blank / why did it re-init".
+
+## The invariant
+`initFromSettings()` → `login(uid)` → **only then** render any `CometChat*` widget. Both are async and
+callback-reporting; a widget rendered before login succeeds shows blank or throws.
+
+## Init once — not once per widget, and hot-restart-safe
+Do it at app startup (before `runApp`, or in the root widget's `initState`), never inside a screen that
+can be re-entered. `initFromSettings` reads `cometchat-settings.json` and persists
+`integrationSource="ai-agent"`; calling it twice is wasteful and races the Calls SDK routing.
+
+```dart
+Future<void> main() async {
+  WidgetsFlutterBinding.ensureInitialized();   // REQUIRED before any plugin/asset access
+  runApp(const MyApp());                       // init happens inside the gate widget below
+}
+```
+> `WidgetsFlutterBinding.ensureInitialized()` is mandatory — `initFromSettings` loads an asset through
+> `rootBundle`, which needs the binding. Omitting it is a common first-run crash.
+
+## Gate the first frame (the pattern that prevents the blank screen)
+Hold the app on a loader until init AND login have both reported success; only then build the chat.
+Keep the gate at the ROOT so a hot restart re-runs it cleanly.
+
+```dart
+import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
+import 'package:flutter/material.dart';
+
+class ChatGate extends StatefulWidget {
+  const ChatGate({super.key});
+  @override
+  State<ChatGate> createState() => _ChatGateState();
+}
+
+class _ChatGateState extends State<ChatGate> {
+  bool _ready = false;
+  String? _error;
+
+  @override
+  void initState() {
+    super.initState();
+    _start();
+  }
+
+  Future<void> _start() async {
+    await CometChatUIKit.initFromSettings(
+      onError: (e) => setState(() => _error = e.message),
+    );
+    if (_error != null) return;
+    // Already signed in after a restart? login() no-ops for the same UID.
+    await CometChatUIKit.login(
+      'cometchat-uid-1',                       // ASK for a real UID — never invent one
+      onSuccess: (_) => setState(() => _ready = true),
+      onError: (e) => setState(() => _error = e.message),
+    );
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    if (_error != null) return Scaffold(body: Center(child: Text('CometChat: $_error')));
+    if (!_ready) return const Scaffold(body: Center(child: CircularProgressIndicator()));
+    // Only past this point may a CometChat* widget be built.
+    return const Scaffold(body: SafeArea(child: CometChatConversations()));
+  }
+}
+```
+> `setState` after an await needs the usual `if (!mounted) return;` guard in real code.
+
+## Who is logged in
+`CometChatUIKit.loggedInUser` is the cached `User?` — the sync getter the thread screen needs
+(`loggedInUser:` is a REQUIRED param on `CometChatThreadedHeader`). It is populated by `login`, so it is
+non-null anywhere behind the gate above. `CometChatUIKit.login` itself calls `getLoggedInUser()` first and
+returns early when that UID is already signed in — **no host-side concurrent-login guard is needed.**
+
+## Production auth — the Auth Key is dev-only
+`login(uid)` uses the Auth Key from the settings file, which means the key ships inside the app bundle.
+That is acceptable for development only. For production:
+1. Omit `credentials.authKey` from `cometchat-settings.json`.
+2. Mint a per-user **auth token** on your server (CometChat REST API, using the App's REST key).
+3. Sign in with `CometChatUIKit.loginWithAuthToken(authToken, onSuccess: …, onError: …)`.
+Say this out loud to the user when you wire the dev path — flag dev-only AS dev-only.
+
+## Logout
+`CometChatUIKit.logout()` clears the session; send the user back to the gate afterwards so a subsequent
+login re-runs cleanly. Do not re-`init` on logout.

package/skills/cometchat-flutter-v6-core/references/setup-credentials.md

@@ -0,0 +1,84 @@
+# setup-credentials — detect, reconcile, fetch, write, authorize
+
+The full version of `SKILL.md` §"Setup & credentials". Load when doing first-time setup or debugging auth.
+
+## 1. Detect the project (`npx @cometchat/skills detect --json`, topped up by reading the repo — `RULES.md`)
+Parse, recording `null` rather than guessing when a signal is absent:
+
+| Signal | Where |
+|---|---|
+| Flutter/Dart constraints | `pubspec.yaml` → `environment:` |
+| Existing CometChat + **major** | `pubspec.yaml` deps + `pubspec.lock` (`cometchat_chat_uikit`) |
+| State management | deps: `flutter_bloc` · `riverpod` · `provider` · `get` · `mobx` |
+| Navigation | deps/source: `go_router` · `auto_route` · plain `Navigator` |
+| Config strategy | `--dart-define` in run configs · `envied` · `flutter_dotenv` · a constants file |
+| Existing credentials | `cometchat-settings.json` · `.cometchat/config.json` · `--dart-define` keys |
+| App entry | `lib/main.dart` — where `runApp` is, and what wraps it |
+| Platform floors | `android/app/build.gradle.kts` (`minSdk`) · `ios/Podfile` (`platform :ios`) |
+
+## 2. version_conflict — STOP
+A non-v6 `cometchat_chat_uikit` present on an **add** request is a STOP, not a warning: reconcile first,
+never mix majors (`RULES.md`). v5 → v6 is `cometchat-flutter-v6-migration`. If v6 is already wired and
+working, this is a **re-entry** — summarize what exists and ask what to ADD, don't re-run setup.
+
+## 3. Credentials — OFFER the fetch FIRST (never degrade to "paste it yourself")
+**(a) Fetch from the dashboard — the default.** Load the CLI on demand:
+```bash
+npx @cometchat/skills-cli@3 auth login
+npx @cometchat/skills-cli@3 provision list --json
+npx @cometchat/skills-cli@3 provision use --app-id <id> --json
+```
+- **Never auto-create an app.** List, show the top few plus a "show all", and ASK which.
+- `provision use` returns App ID / Region / Auth Key **and** writes a neutral `.cometchat/config.json`.
+  It does **not** know Flutter — writing the settings asset is the skill's job.
+
+**(b) Manual paste** — Dashboard → Your App → Credentials. Use only if the user declines (a) or the CLI
+can't run. Ask and WAIT; never guess a value.
+
+## 4. Write the settings asset
+`cometchat-settings.json` at the **project root** (beside `pubspec.yaml`):
+```json
+{
+  "appId": "APP_ID",
+  "region": "REGION",
+  "credentials": { "authKey": "AUTH_KEY" },
+  "uiKit": { "subscribePresenceForAllUsers": true, "enableCalling": false },
+  "chatSDK": { "autoEstablishSocketConnection": true }
+}
+```
+Register it (exact indentation matters in YAML):
+```yaml
+flutter:
+  uses-material-design: true
+  assets:
+    - cometchat-settings.json
+```
+Then: `flutter pub get`. **Do NOT gitignore a registered asset** — a fresh clone / CI `flutter build bundle`
+fails with *"No file or variants found for asset: cometchat-settings.json"* if the file is missing. Instead
+**commit a placeholder `cometchat-settings.json`** (same shape, placeholder/empty `authKey` — never a real
+dev key) so the asset path always resolves, and have each dev and CI overwrite it with real credentials
+locally / at build time. Guard against committing a real key with a pre-commit hook or CI check, not
+`.gitignore`. Never echo the Auth Key back to the user or into logs.
+> Optional keys: `chatSDK.adminHost` / `chatSDK.clientHost` (dedicated/on-prem clusters only).
+> `uiKit.enableCalling` stays `false` until the user asks for calls (→ `cometchat-flutter-v6-calls`).
+
+### If the team already uses `--dart-define` / envied
+The settings **file** is what `initFromSettings` reads — it cannot read `--dart-define`. Two honest options,
+state the trade-off and let the user choose:
+- Keep `initFromSettings` and generate `cometchat-settings.json` at build time from your existing secret
+  source (CI writes the file). Keeps telemetry attribution.
+- Or use the classic `UIKitSettingsBuilder` + `CometChatUIKit.init(...)` with `--dart-define` values —
+  works, but loses `integrationSource="ai-agent"`. Only if the user prefers it after hearing the trade-off.
+
+## 5. Authorize — confirm it actually worked
+`initFromSettings` reaches `onSuccess`, then `login` reaches `onSuccess` with a `User`. Failure modes:
+- **Wrong Region** — the single most common cause of an immediate auth error. `us` / `eu` / `in`, matching
+  the Dashboard exactly.
+- **UID doesn't exist** — `login` needs an existing user (Dashboard → Users; fresh apps seed
+  `cometchat-uid-1…`). Never invent one.
+- **Asset not found** — see `troubleshooting.md`.
+
+## 6. Production
+Omit `credentials.authKey`, mint a per-user auth token server-side, and call
+`CometChatUIKit.loginWithAuthToken(...)` (`lifecycle.md`). Tell the user plainly that the Auth Key path you
+wired is dev-only — flag dev-only AS dev-only.

package/skills/cometchat-flutter-v6-core/references/troubleshooting.md

@@ -0,0 +1,26 @@
+# troubleshooting — symptom → cause → fix
+
+The first stop when a Flutter integration renders wrong. Live page: `/ui-kit/flutter/troubleshooting`.
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Blank/white screen where chat should be | A widget rendered before `login` succeeded | Gate the first frame on init **and** login (`lifecycle.md`) |
+| `Unable to load asset: cometchat-settings.json` | File missing, not at project root, or not registered | Add it and list it under `flutter: assets:` in `pubspec.yaml`; re-run `flutter pub get` |
+| Crash on `initFromSettings` before any UI | `WidgetsFlutterBinding.ensureInitialized()` missing | Call it first in `main()` |
+| `RenderFlex children have non-zero flex but incoming height constraints are unbounded` | A kit list inside an unbounded parent | Wrap in `Expanded`, or give a fixed height (`layout.md`) |
+| The list renders as a zero-height sliver | Same — content-driven parent | Same |
+| Composer hidden by the keyboard | `resizeToAvoidBottomInset: false`, or a nested/absent `Scaffold` | Leave the default `true`; one `Scaffold` per screen |
+| Header under the notch / composer under the home bar | No `SafeArea` | Wrap the body in `SafeArea` |
+| `AUTH_ERR_AUTH_TOKEN_NOT_FOUND` / login fails immediately | Wrong **Region**, or the UID does not exist | Check `region` against the Dashboard; use a real UID from Dashboard → Users |
+| Login fails only in release builds | Auth Key stripped/obfuscated, or no network permission | Verify the settings asset ships; check Android `INTERNET` permission |
+| `Undefined name 'CometChatIncomingCall'` (or any call widget) | Imported only the chat barrel | Also import `package:cometchat_chat_uikit/cometchat_calls_uikit.dart` |
+| Call buttons missing from the message header | Calls not enabled | `uiKit.enableCalling: true` in the settings file **and** `cometchat_calls_sdk` added (→ `-calls`) |
+| Thread replies never appear / never send | `parentMessageId` passed without `user:`/`group:` | Pass BOTH on the thread list *and* composer |
+| `The named parameter 'onBack' isn't defined` on the thread header | Following the docs page | It has no `onBack` — use the screen's `AppBar` (`DOCS-BACKLOG` F5) |
+| `The named parameter 'onConversationItemClick' isn't defined` | Following the search docs page | `onConversationClicked` / `onMessageClicked` (`DOCS-BACKLOG` F3) |
+| An enabled extension (polls/stickers) doesn't appear | Expecting v5-style registration | v6 auto-surfaces it; confirm the Dashboard toggle, add NO client code |
+| Presence/online status never updates | `subscribePresenceForAllUsers` false in settings | Set it `true` (default) |
+| Messages arrive only after reopening the screen | Socket not auto-connecting | `chatSDK.autoEstablishSocketConnection: true` |
+| Android build fails on minSdk | App below the real floor (the docs' 24 is too low) | `minSdk = 26` in `android/app/build.gradle.kts` — forced by `cometchat_calls_sdk`, a hard dependency of the kit |
+| iOS pod install fails | Deployment target too low (the docs' 13.0 is too low on 5.0.7) | `platform :ios, '15.1'` in `ios/Podfile`, then `pod install` |
+| Everything breaks after upgrading from v5 | Mixed majors / removed v5 APIs | → `cometchat-flutter-v6-migration`; never mix majors |