@cometchat/skills 4.4.1 → 5.0.0

package/skills/cometchat-angular-v5-core/references/anti-patterns.md

@@ -0,0 +1,49 @@
+# Anti-patterns — code that compiles, shows no error, and does not work
+
+## 1. Component missing from `imports: []`  ⭐ most common
+```ts
+@Component({ standalone: true, imports: [CommonModule], template: '<cometchat-conversations></cometchat-conversations>' })
+```
+Angular treats the unknown element as plain HTML and renders **nothing**. No error, no warning, blank space.
+**Fix:** import the class into that component's `imports` array. Every kit component, in every component that uses it.
+
+## 2. Unsized ancestor chain
+The kit fills its container. If any ancestor has no resolved height, the list computes to 0px and you see a blank pane.
+**Fix:** `html, body { height: 100%; margin: 0; }`, a `100dvh` shell, and `min-height: 0` on every flex column. See `layout.md`.
+
+## 3. No teardown in `ngOnDestroy`
+RxJS subscriptions and CometChat listeners survive the component. Symptoms: memory grows per route change, handlers fire against destroyed views, duplicate messages.
+**Fix:** `takeUntil(this.destroy$)` on every subscription and `CometChat.removeMessageListener(id)` in `ngOnDestroy`.
+
+## 4. Async SDK-callback state doesn't repaint
+`onTextMessageReceived` fires asynchronously, so assigning to a plain field does not trigger change detection. The message is in memory; the DOM never updates.
+**Fix:** Angular v21 is **zoneless by default**, so `NgZone.run()` is a no-op for CD — write to a **signal** (`messages.update(...)`) or call `ChangeDetectorRef.markForCheck()` after the update. (`NgZone.run()` only helps if you've opted back into zones with `provideZoneChangeDetection()`.) Kit components handle this internally — this applies to your own listeners.
+
+## 5. Rendering before `login()` resolves
+Components mount with no session and render empty lists with no error, which looks like "the API returned nothing".
+**Fix:** init and login must resolve before bootstrap, or gate the chat route. See `lifecycle.md`.
+
+## 6. Concurrent `login()`
+Two callers racing throws **"Please wait until the previous login request ends."** A route guard plus a component `ngOnInit` is enough to cause it.
+**Fix:** cache the in-flight **promise**, never a boolean. See `lifecycle.md`.
+
+## 7. Using the class name as a selector, or the docs title as either
+`<CometChatConversations>` and `<cometchat-conversations-component>` are both wrong. Class `CometChatConversationsComponent`, selector `<cometchat-conversations>`, docs title "Conversations" — three different strings.
+
+## 8. Guessing the bare class name
+`CometChatConversations` (no suffix) exists inside the package but is **not exported** — importing it fails to compile. 109 such internal-only names exist. Always use the exported `…Component` form. The AI-assistant exports are the sole exception and carry no suffix.
+
+## 9. Putting credentials in `.env`
+Angular does not read `.env`. Values must be in `src/environments/environment.ts` and swapped via `fileReplacements`. A `.env` file is silently ignored, so config appears empty at runtime.
+
+## 10. Shipping the Auth Key to production
+The Auth Key can mint a session for **any** user. Production must call `loginWithAuthToken` with a token minted server-side. See `setup-credentials.md`.
+
+## 11. `@import` of the kit stylesheet
+`@import '@cometchat/chat-uikit-angular/styles/css-variables.css'` fails the build — the package `exports` map does not expose that path. Register the full `node_modules/...` path in `angular.json` `styles` instead.
+
+## 12. Installing on Angular 22
+`npm install` hard-fails with `ERESOLVE` (peer range `>=17.0.0 <22.0.0`). Do not "fix" it with `--force` or `--legacy-peer-deps` — that installs a combination nobody has tested. Scaffold with `@angular/cli@21`.
+
+## 13. Hand-rolling what the kit already renders
+Message bubbles, receipts, reaction pickers, typing indicators and attachment previews are rendered by the kit. Rebuilding them by hand means losing realtime updates and every future fix. If an affordance appears not to work, it is nearly always a missing input or an unsized container.

package/skills/cometchat-angular-v5-core/references/component-props.md

@@ -0,0 +1,55 @@
+# Inputs, outputs & content projection
+
+Beyond the golden path. Anything not here: fetch the component's docs page (`docs-map.md`) — do not guess.
+
+## The Angular shape
+- Props are `@Input()` → template attribute binding: `[user]="selected"`
+- Events are `@Output()` → template event binding: `(itemClick)="fn($event)"`. Output names are plain (`itemClick`, `error`, `closeClick`) — there is **no** `cc` prefix; that is the React convention, not Angular's.
+- Slots are **content projection** — you pass a `<ng-template>` or project children, not a render-prop function as in React.
+
+## Conversations
+```html
+<cometchat-conversations
+  [activeConversation]="selected"
+  (itemClick)="onOpen($event)"
+  (error)="onError($event)">
+</cometchat-conversations>
+```
+`activeConversation` is what visually reflects the selected row. Omit it and the list looks stateless even though clicking works — a real defect, not cosmetic.
+
+## Message header / list / composer
+All three take the same subject — one of `[user]` or `[group]`, never both:
+```html
+<cometchat-message-header [user]="selectedUser"></cometchat-message-header>
+<cometchat-message-list   [user]="selectedUser"></cometchat-message-list>
+<cometchat-message-composer [user]="selectedUser"></cometchat-message-composer>
+```
+For a group, swap all three to `[group]`. Mixing them across the three components shows one conversation's header above another's messages.
+
+## Thread
+```html
+<cometchat-thread-header [parentMessage]="threadParent" (closeClick)="threadParent = null"></cometchat-thread-header>
+<cometchat-message-list  [user]="selectedUser" [parentMessageId]="threadParent?.getId()"></cometchat-message-list>
+```
+The reply affordance in a bubble is on by default but inert until you render a thread surface — wire it or hide it, never leave a dead button.
+
+## Users / Groups / Group members
+```html
+<cometchat-users  (itemClick)="onUser($event)"></cometchat-users>
+<cometchat-groups (itemClick)="onGroup($event)"></cometchat-groups>
+<cometchat-group-members [group]="activeGroup"></cometchat-group-members>
+```
+Group members must expose view · kick · ban · banned list · change scope · search to be complete. Change-scope uses `CometChatChangeScopeComponent`; the banned list comes from the SDK.
+
+## Content projection instead of render props
+```html
+<cometchat-conversations>
+  <ng-template #itemView let-conversation>
+    <div class="my-row">{{ conversation.getConversationId() }}</div>
+  </ng-template>
+</cometchat-conversations>
+```
+Slot names vary per component — confirm on the component's docs page before using one.
+
+## Services for headless control
+Some behaviour is reachable without a component, via DI: `ChatStateService` (active chat), `MessageListService`, `ConversationsService`, `SearchMessagesService`, `GroupMembersService`, `ThemeService`. Inject with `inject(ChatStateService)`. Use these for state coordination, not for rebuilding UI the kit already renders.

package/skills/cometchat-angular-v5-core/references/dependencies.md

@@ -0,0 +1,66 @@
+# Dependencies & support matrix
+
+## Install
+```bash
+npm install @cometchat/chat-uikit-angular@^5 @cometchat/chat-sdk-javascript@^4 @cometchat/cards-angular@^1 dompurify@^3
+```
+Calls (optional): `npm install @cometchat/calls-sdk-javascript@^5`
+
+## Peer dependencies — verified against the published 5.1.0
+| Package | Range | Notes |
+| --- | --- | --- |
+| `@angular/core` | `>=17.0.0 <22.0.0` | 22 fails to install — see below |
+| `@angular/common` | `>=17.0.0 <22.0.0` | |
+| `@cometchat/chat-sdk-javascript` | `^4.1.13` | required |
+| `@cometchat/cards-angular` | `^1.0.0` | **required** — added in 5.1.0 |
+| `dompurify` | `^3.0.0` | required |
+| `@cometchat/calls-sdk-javascript` | `^5.0.3` | optional — calls only |
+
+> `@cometchat/cards-angular` was added between 5.0.3 and 5.1.0. Omitting it produces an incomplete install.
+
+## Angular version support
+| Angular | Status |
+| --- | --- |
+| 17 | Works (within the peer range) but undocumented |
+| 18 – 21 | Supported and documented |
+| 22 | **Install fails** — `ERESOLVE`, peer range excludes it |
+
+> **Divergence from the docs.** `{DOCS_BASE}/ui-kit/angular/overview.md` lists Angular "v18, v19, v20, v21, v22" as supported. That is wrong against the published 5.1.0 package: the peer range is `>=17.0.0 <22.0.0` (so 22 hard-fails `ERESOLVE`). The table above is verified against npm — **trust it over the guide**. Do not scaffold Angular 22 because the docs say it is supported, and never `--force` past the install failure. (The version range needs a kit release; `@cometchat/cards-angular` as a required peer was corrected upstream and now appears in the overview's peer list — verified against cometchat/docs, 2026-09-09.)
+
+CometChat's stated policy is 18 through latest, so the range is expected to widen in a future kit release. Until that ships, 22 does not install. Scaffold new apps with:
+```bash
+npx -y @angular/cli@21 new my-app
+```
+
+## Stylesheet + icon assets — BOTH are required
+`angular.json` → `projects.<app>.architect.build.options`:
+
+`styles`:
+```json
+"node_modules/@cometchat/chat-uikit-angular/styles/css-variables.css"
+```
+The package-specifier `@import` form does not work — the `exports` map does not expose it.
+
+`assets` (282 SVG icons ship under `src/lib/assets`):
+```json
+{ "glob": "**/*", "input": "node_modules/@cometchat/chat-uikit-angular/src/lib/assets", "output": "assets" }
+```
+Missing this leaves icons broken across every component with no error — the most commonly missed Angular setup step. Verify after `ng serve`: send/attach/emoji buttons in the composer should render as icons, not blank space.
+
+## Versions this skill was verified against
+`@cometchat/chat-uikit-angular@5.1.0` · `@cometchat/chat-sdk-javascript@4.1.13`
+
+## Production build: budgets + the CommonJS bailout
+
+A stock CLI app budgets the initial bundle at 500 kB warning / 1 MB error. The kit plus the Chat SDK is ~4.2 MB, so the DEFAULT `ng build` (which is the production config) exits non-zero:
+```
+✘ [ERROR] bundle initial exceeded maximum budget. Budget 1.00 MB was not met by 3.21 MB with a total of 4.21 MB.
+```
+`ng serve` is unaffected, so this only bites at ship time. Under `configurations.production`:
+```json
+"budgets": [{ "type": "initial", "maximumWarning": "5mb", "maximumError": "6mb" }]
+```
+Also silence the CommonJS bailout warning (the Chat SDK is not ESM) under `build.options`:
+```json
+"allowedCommonJsDependencies": ["@cometchat/chat-sdk-javascript"]
+```

package/skills/cometchat-angular-v5-core/references/docs-map.md

@@ -0,0 +1,132 @@
+# docs-map — where to look anything up
+
+## 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
+```
+**Fetch rule:** build a URL as `DOCS_BASE` + the path below, then append `.md` for the clean Markdown twin. The same applies to any `docs_topic` in `features.angular-v5.json` / `contracts.angular-v5.json` — those are paths, not URLs, so they resolve against whatever `DOCS_BASE` is set to.
+```
+Fetch:  {DOCS_BASE}/ui-kit/angular/components/cometchat-conversations.md
+```
+Most pages open with an **"AI Integration Quick Reference"** block — read that first for package, imports and key inputs.
+
+## Scoped Angular v5 index (prefer over the global llms.txt)
+```
+{DOCS_BASE}/ui-kit/angular/llms-angular-v5.md
+```
+A 91-page, Angular-v5-only routing index including a **"Task guides (recipes)"** section — start here to find the right page. Site-wide `{DOCS_BASE}/llms.txt` spans every product and is far larger; last resort only.
+
+> This scoped index now resolves on prod (corrected upstream — verified against cometchat/docs, 2026-09-09). If a `.md` twin ever 404s, fall back to the same path without `.md`, or use the per-page paths below.
+
+## Component docs (append `.md`)
+| Need | Path under `{DOCS_BASE}/ui-kit/angular` |
+| --- | --- |
+| Conversation list | `/components/cometchat-conversations` |
+| Message header | `/components/cometchat-message-header` |
+| Message list | `/components/cometchat-message-list` |
+| Message composer | `/components/cometchat-message-composer` |
+| Thread header | `/components/cometchat-thread-header` |
+| Users / Groups | `/components/cometchat-users` · `/components/cometchat-groups` |
+| Group members | `/components/cometchat-group-members` |
+| Search | `/components/cometchat-search` |
+| Reactions | `/components/cometchat-reactions` |
+| Calls | `/components/cometchat-call-buttons` · `/components/cometchat-incoming-call` |
+| Notification feed | `/components/notification-feed` *(no `cometchat-` prefix — the one exception)* |
+| All components | `/components/components-overview` |
+| Theming | `/customization/theming` |
+| Localization | `/customization/localization` |
+| Global config | `/customization/global-config` |
+| Events · Methods · Core | `/events` · `/methods` · `/core-features` |
+| Extensions · AI · Calls | `/extensions` · `/ai-features` · `/call-features` |
+| Services (DI) | `/api-reference/introduction` |
+| **v4→v5 migration / upgrade** | `/customization/migration-guide` *(the official "Upgrading From V4": Integration · Components · Theming · Properties · Shared Dependencies · State Management · Localization · Quick Checklist. Angular has **no** `migration-property-changes` twin like React's — per-component inputs/outputs come from each component page above.)* |
+
+## Task guides (recipes) — build FROM these
+| Task | Path |
+| --- | --- |
+| New chat | `/guides/new-chat` |
+| Group chat | `/guides/group-chat` |
+| Threaded messages | `/guides/threaded-messages` |
+| Search messages | `/guides/search-messages` |
+| Message privately | `/guides/message-privately` |
+| Block / unblock | `/guides/block-unblock-user` |
+| Custom message types | `/guides/custom-message-types` |
+| Text formatters | `/guides/custom-text-formatter` · `/guides/mentions-formatter` · `/guides/url-formatter` · `/guides/hashtag-formatter` · `/guides/shortcut-formatter` |
+| Rich text | `/guides/rich-text-formatting` |
+| Card messages | `/guides/card-messages` |
+| State management | `/guides/state-management` |
+| RxJS patterns | `/guides/subscription-patterns` |
+| Call log details | `/guides/call-log-details` |
+
+**Reference layouts** — whole-screen shells, not single-feature recipes. Fetch the matching one before composing a surface:
+
+| Layout | Path | Shape |
+| --- | --- | --- |
+| Tab-based app | `/ui-kit/angular/angular-tab-based-chat` | left sidebar + `@switch (activeTab)` over `ChatStateService`. **The grow target** — build it only when the user asks for tabs. Its tab set (Chats · Call Logs · Users) is ONE example, not the definitive list. |
+| Conversation list ↔ pane | `/ui-kit/angular/angular-conversation` | the default "add chat" shape (`placement/references/core-surface.md`) |
+| Single 1:1 chat | `/ui-kit/angular/angular-one-to-one-chat` | one fixed conversation, no selector |
+
+Use a guide as the implementation SOURCE, then compare your output against it.
+
+## SDK docs — the per-feature fallback
+When a capability has **no UI Kit component**, drop to the headless JS SDK. Angular uses the same SDK as every other web family — there is no Angular-specific SDK.
+
+```
+SDK_DOCS_BASE = https://www.cometchat.com/docs
+# Production docs base
+SDK index (scoped — PREFER):  {SDK_DOCS_BASE}/sdk/javascript/llms-javascript-v4.md
+Convention:                   {SDK_DOCS_BASE}/sdk/javascript/<page> then append .md
+```
+The scoped index groups every SDK page by area — Messaging · Calling · Users · Groups · AI, campaigns & webhooks · Real-time Listeners · Key Concepts. Each page opens with an **"AI Integration Quick Reference"** accordion listing package, import and key methods — read that first, then the examples.
+
+Common entry points: `/sdk/javascript/send-message` · `/sdk/javascript/receive-messages` · `/sdk/javascript/retrieve-conversations` · `/sdk/javascript/user-management` · `/sdk/javascript/groups-overview` · `/sdk/javascript/ai-agents`.
+
+Using the SDK from Angular, two rules from `lifecycle.md` always apply: remove listeners in `ngOnDestroy`, and repaint after SDK-callback state updates via a **signal** or `ChangeDetectorRef.markForCheck()` (Angular v21 is zoneless by default, so `NgZone.run()` won't trigger change detection).
+
+## Never
+Do not read a symbol's shape from `node_modules/**/*.d.ts` and present it as documentation, and never answer inputs/outputs from memory. Fetch the page.
+
+## Docs first for the API — the installed kit for BEHAVIOUR the docs omit (full detail)
+> `SKILL.md` § "Docs first for the API" keeps the spine; the deep methodology + examples live here.
+
+**What exists and what it is called comes from the docs.** Fetch the component's page (`DOCS_BASE` + path + `.md`).
+Each opens with an **AI Integration Quick Reference** — selector, key inputs/outputs, view slots, anchors into the
+props table. Read that first; it usually answers the question without loading the page.
+
+Do **not** invent an API from the type declarations. The types expose internal-only names that are not importable
+and members with no defined behaviour — that is how a plausible-but-wrong symbol reaches the emitted code.
+
+**But reading the shipped bundle IS correct when the docs state a prop and not its semantics.** The props table
+often gives a type and a one-line description without saying how the input behaves. Real examples in this kit:
+
+- `attachmentOptions` is documented as *"Custom attachment options for the attachment menu"* — it does not say
+  whether yours **append to** or **replace** the built-ins. (They append: the composer pushes yours onto the built-in
+  list.) Guess "replace" and you silently delete image/video/file/audio attachments.
+- `messagesRequestBuilder` — whether a supplied builder overrides or merges with defaults is not stated for the
+  message list.
+
+When behaviour is load-bearing and undocumented, **verify it in the installed package**
+(`node_modules/@cometchat/chat-uikit-angular/fesm2022/*.mjs`) rather than guessing. Then do two things:
+
+1. **State in your summary that you verified it against the installed kit**, not the docs — so the developer knows it
+   is pinned to this version.
+2. **Report it as a docs gap**, naming the page and the missing sentence. That is how the docs improve instead of
+   every agent re-deriving it.
+
+Reading the package is also fine for confirming the installed **version**.

package/skills/cometchat-angular-v5-core/references/layout.md

@@ -0,0 +1,64 @@
+# Layout & sizing — why the chat pane collapses
+
+## The rule
+Every kit component fills its container. If any ancestor has no resolved height, the component computes to **0px** and you get a blank pane with no error. This is the second most common failure after a missing `imports` entry.
+
+## The prepared ancestor chain
+```css
+/* styles.css — global, required */
+html, body { height: 100%; margin: 0; }
+```
+Then the shell:
+```css
+.cc-shell { display: flex; height: 100dvh; width: 100%; min-height: 0; overflow: hidden; }
+.cc-side  { width: 320px; min-height: 0; overflow: hidden; }
+.cc-main  { flex: 1; display: flex; flex-direction: column; min-height: 0; overflow: hidden; }
+```
+`100dvh` (not `100vh`) so mobile browser chrome does not clip the composer.
+
+## `overflow: hidden` is what makes each pane scroll ITSELF
+`min-height: 0` lets a child shrink; **`overflow: hidden` on the shell and on each column is what keeps its scrolling inside it.** Omit it and the panes grow the page instead: scrolling the conversation list scrolls the WHOLE window, message pane and all, and the header scrolls away with it. The height chain looks right, nothing errors, and the app feels broken.
+
+Both are required, and they do different jobs:
+- `min-height: 0` — the column may shrink below its content
+- `overflow: hidden` — the overflow is contained, so the kit's own list scrolls internally
+
+The kit's lists manage their own scrolling. Your job is to give them a **fixed-size box to scroll inside**; the moment the box can grow, they stop scrolling and the document does.
+
+## `min-height: 0` on every flex column
+A flex item defaults to `min-height: auto`, which refuses to shrink below its content. Nested scrollable lists then overflow the viewport instead of scrolling internally. Every column in the chain needs `min-height: 0`.
+
+## Ancestors that break it
+- `transform`, `filter` or `backdrop-filter` on an ancestor creates a containing block that breaks the height chain and can trap `position: fixed` overlays.
+- `overflow: hidden` on a mid-level wrapper clips the composer.
+- A host element with no display set: kit components are custom elements, so give the host `display: block` or `display: flex` where you control it.
+
+## No reflow between loading and loaded
+The pane must not change size when data arrives. Give the pinned box its height up front so the kit's loading and empty views occupy the same box as the loaded list. If the layout jumps, an ancestor is sizing to content rather than to the viewport.
+
+## Thread and search panels
+Both are additional columns in the same shell, not overlays:
+```css
+.cc-thread { width: 360px; min-height: 0; border-left: 1px solid var(--cometchat-border-color-default); }
+```
+Opening a thread must not resize the message list — reserve the column or animate width, never remount the list. Closing must return to the exact prior layout (the panel-close round-trip).
+
+## Responsive — one pane on mobile
+Below ~768px, show a single pane: the list, or the conversation, never both squeezed.
+```css
+@media (max-width: 768px) {
+  .cc-shell { flex-direction: column; }
+  .cc-side  { width: 100%; }
+  .cc-side[hidden], .cc-main[hidden] { display: none; }
+}
+```
+Drive `hidden` from the same selection state that drives the message components, and give the mobile conversation view a back control that clears the selection.
+
+## Quick diagnosis
+| Symptom | Cause |
+| --- | --- |
+| Blank pane, no error | an ancestor has no height — check `html, body` |
+| List overflows the page | a flex column is missing `min-height: 0` |
+| Composer off-screen on mobile | `100vh` instead of `100dvh`, or `overflow: hidden` on a wrapper |
+| Layout jumps when data loads | the box is sizing to content, not the viewport |
+| Dropdown clipped | an ancestor has `overflow: hidden` or a `transform` |

package/skills/cometchat-angular-v5-core/references/lifecycle.md

@@ -0,0 +1,202 @@
+# Lifecycle — init → login → render, the Angular way
+
+## The invariant
+`init()` must RESOLVE before `login()`, and `login()` before any kit component renders. Out of order, components mount with no session and render empty lists with no error.
+
+## Where init goes
+Angular has no React-style root effect. Two correct placements:
+
+**A. Before `bootstrapApplication` (simplest, recommended).** See the core SKILL.md recipe — init and login resolve, then the app boots. Nothing can render early because the app has not booted yet.
+
+**B. `provideAppInitializer` (when you need DI during init).**
+```ts
+// src/app/app.config.ts
+import { ApplicationConfig, provideAppInitializer, inject } from '@angular/core';
+import { CometChatUIKit } from '@cometchat/chat-uikit-angular';
+import { environment } from '../environments/environment';
+import { ensureLoggedIn } from './cometchat-session';   // the guarded login below
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideAppInitializer(() => {
+      const { appId, region, authKey } = environment.cometchat;
+      // initFromSettings — NOT the classic builder init — so integrationSource
+      // ="ai-agent" is persisted for telemetry attribution and the Calls SDK
+      // inherits the same source.
+      return CometChatUIKit.initFromSettings({
+        appId, region,
+        credentials: { authKey },
+        chatSDK: { presenceSubscription: { type: 'ALL_USERS' } },
+      }).then(() => ensureLoggedIn('cometchat-uid-1'));
+    }),
+  ],
+};
+```
+Angular waits for the returned promise before rendering the first component. On Angular 17-18 use the older `{ provide: APP_INITIALIZER, useFactory, multi: true }` form — same semantics.
+
+`initFromSettings` returns `Promise<InitResult>`. `CometChatUIKit.isInitialized()` is a cheap synchronous check.
+
+## The docs show `init(builder)` — that is CORRECT for them, and wrong for us
+`{DOCS_BASE}/ui-kit/angular/integration.md` and `quickstart.md` initialise with the classic builder:
+the classic `UIKitSettingsBuilder` chain (`setAppId` / `setRegion` / `setAuthKey`) passed to the UI Kit's builder-style init.
+
+That is **not stale documentation** — it is the right recipe for its reader, and it must not be "fixed".
+
+The SDK ships two integration sources and the init path selects between them:
+
+| Caller | Path | Recorded as |
+| --- | --- | --- |
+| A developer following the docs by hand | the builder-style `init` | `manual` |
+| An agent following this pack | `CometChatUIKit.initFromSettings({ … })` | `ai-agent` |
+
+Verified in the shipped SDK: `INTEGRATION_SOURCE = { AI_AGENT: "ai-agent", MANUAL: "manual" }`, with the builder-style init storing `MANUAL` and `initFromSettings()` storing `AI_AGENT`.
+
+So the split is deliberate on both sides. **Use `initFromSettings` here** — a static gate enforces it — and do **not** raise the docs' builder recipe as a docs bug or propose changing it. Converting the public docs to `initFromSettings` would tag every hand-built integration as agent-built and destroy the distinction the field exists to measure.
+
+## Guarded login — the one that bites
+A second `login()` while the first is still in flight throws **"Please wait until the previous login request ends."** Sequential calls are fine (the second returns the cached user); concurrent ones are not. Route guards, resolvers and a component `ngOnInit` firing together will do this.
+
+Cache the **promise**, never a boolean flipped before the await:
+```ts
+// src/app/cometchat-session.ts
+import { CometChatUIKit } from '@cometchat/chat-uikit-angular';
+
+// Cache the PROMISE, once per page load. Concurrent callers await the same one;
+// later callers get the resolved value. A second sequential login() returns the
+// cached user, so calling it once per load is safe even with a stored session.
+let session: Promise<unknown> | null = null;
+
+export function ensureLoggedIn(uid: string) {
+  if (!session) {
+    session = CometChatUIKit.login(uid).catch((e) => { session = null; throw e; });
+  }
+  return session;
+}
+```
+
+> ⚠️ **Do NOT short-circuit on `CometChatUIKit.getLoggedInUser()`.** It is tempting:
+> ```ts
+> const existing = CometChatUIKit.getLoggedInUser();   // ← don't
+> if (existing) return Promise.resolve(existing);
+> ```
+> `initFromSettings` hydrates the kit's own `_loggedInUser` from storage when a session exists, so this returns a user **before `login()` has run in this page**. You then skip `login()` entirely and the kit's post-login wiring never executes. Worse, the kit's view and the SDK's can disagree — `CometChatUIKit.getLoggedInUser()` returning a user does **not** guarantee `CometChat.getLoggedinUser()` is populated or that requests will authorise. Trust the promise, not the cached flag.
+
+## Dev-only: `ensureDevUser` — create-if-missing, then log in
+
+`login(uid)` authenticates a user that **must already exist**; it does not create one. `cometchat-uid-1` is the docs sample, **not a guarantee about this app** — on an app whose sample users were never seeded or have been cleaned up, login fails with a user-not-found and the screen stays blank with no obvious cause.
+
+You cannot pre-check existence: `CometChat.getUser()` needs a session, and in dev you hold only the Auth Key, not the REST key. Probing `uid-1..5` would mean up to five failed login attempts. So **create-if-missing, then log in** — one deterministic call that is valid on any app, fresh or customised:
+
+```ts
+// src/app/cometchat-session.ts — continued: add below ensureLoggedIn() (merge the imports)
+import { CometChat } from '@cometchat/chat-sdk-javascript';        // for CometChat.User
+import { CometChatUIKit } from '@cometchat/chat-uikit-angular';
+
+// createUser uses the Auth Key configured in init — verified vs installed 5.1.0:
+//   static createUser(user: CometChat.User): Promise<CometChat.User>
+export async function ensureDevUser(uid = 'cometchat-uid-1', name = 'Demo User') {
+  try {
+    const u = new CometChat.User(uid);
+    u.setName(name);
+    await CometChatUIKit.createUser(u);
+  } catch {
+    // ERR_UID_ALREADY_EXISTS is EXPECTED — the user is there. Fall through to login.
+  }
+  return ensureLoggedIn(uid);                                       // now guaranteed to succeed
+}
+```
+
+**DEV ONLY.** It depends on the Auth Key being in the browser. Production mints a per-user auth token server-side and calls `loginWithAuthToken` — see `setup-credentials.md`. When the developer names a real UID, log in as that instead; only fall back to this when no UID is known.
+
+## Readiness gap — `login()` resolving is not "ready to fetch"
+`login()` can resolve slightly before the session can authorise requests. A list that mounts in that window fires its first fetch, gets an auth error, and — for `ConversationsService` — **caches the failure**: the built-in Retry button does not re-attempt, so a transient startup error becomes a permanent "OOPS!" until a page reload.
+
+Defend against it:
+- **Bootstrap after login resolves** (core's `main.ts` recipe) rather than rendering a chat route that races it. Nothing mounts until the session exists.
+- If you must gate a route instead, resolve `ensureLoggedIn()` in the guard and let the route render only after it settles.
+- Handle `(error)` on lists and give the user a real retry that **remounts** the component, since the built-in one may not recover.
+- Do not "fix" this with a `setTimeout` — it hides a race rather than ordering it.
+Production uses a server-minted token instead: `CometChatUIKit.loginWithAuthToken(token)`. Never ship the Auth Key to the browser — see `setup-credentials.md`.
+
+## Reading the session — `loggedInUser$`
+The kit exposes an RxJS Observable. This is the Angular-idiomatic way to react to login/logout; React has no equivalent.
+```ts
+import { Component, OnDestroy, inject, ChangeDetectorRef } from '@angular/core';
+import { CometChatUIKit } from '@cometchat/chat-uikit-angular';
+import { Subject, takeUntil } from 'rxjs';
+
+@Component({ selector: 'app-shell', standalone: true, template: '' })
+export class ShellComponent implements OnDestroy {
+  private destroy$ = new Subject<void>();
+  user: unknown = null;
+
+  constructor() {
+    CometChatUIKit.loggedInUser$
+      .pipe(takeUntil(this.destroy$))
+      .subscribe((u) => { this.user = u; });
+  }
+
+  ngOnDestroy() { this.destroy$.next(); this.destroy$.complete(); }
+}
+```
+`CometChatUIKit.getLoggedInUser()` is the synchronous one-shot equivalent.
+
+## Teardown — required, not optional
+Every subscription and every CometChat SDK listener must be released in `ngOnDestroy`, or the app leaks on each route change and stale handlers fire against destroyed views.
+```ts
+import { CometChat } from '@cometchat/chat-sdk-javascript';
+
+class ExampleComponent {
+  private listenerId = 'chat-example';
+  private destroy$ = { next: () => {}, complete: () => {} };
+
+  ngOnDestroy() {
+    this.destroy$.next();
+    this.destroy$.complete();
+    CometChat.removeMessageListener(this.listenerId);   // same id used to register
+  }
+}
+```
+Register listeners with a stable id you keep on the component instance.
+
+## Async SDK callbacks — messages arrive but the UI does not update
+CometChat SDK callbacks fire asynchronously (and, with zones, outside Angular's zone), so state you set inside them does not repaint on its own. Symptom: the message exists in memory, the DOM never changes.
+
+**Angular v21 is ZONELESS by default** — no provider needed: `ng new` (21.2.x) adds no `zone.js` and no `provideZoneChangeDetection()`, and does NOT add `provideZonelessChangeDetection()` or `OnPush` either (components stay `Default` CD) — so **`NgZone.run()` does NOT trigger change detection**; there's no zone to re-enter. Use a **signal** (the cleanest zoneless pattern — writing it schedules CD) or call **`ChangeDetectorRef.markForCheck()`** after mutating plain state. Both work whether the app is zoneless or (legacy) zone-based:
+```ts
+import { CometChat } from '@cometchat/chat-sdk-javascript';
+import { signal } from '@angular/core';
+
+class ExampleComponent {
+  private listenerId = 'chat-example';
+  // signal: writing to it schedules change detection under the zoneless default
+  messages = signal<unknown[]>([]);
+
+  constructor() {
+    CometChat.addMessageListener(this.listenerId, {
+      onTextMessageReceived: (msg: unknown) => {
+        this.messages.update((prev) => [...prev, msg]);   // repaints — no NgZone needed
+      },
+    });
+  }
+}
+```
+Prefer a signal (template reads `messages()`); if you keep a plain field instead, inject `ChangeDetectorRef` and call `this.cdr.markForCheck()` after the mutation. Only if you have deliberately opted back into zones with `provideZoneChangeDetection()` is `NgZone.run()` the right remedy. The kit's own components handle this internally — you only need this for your own SDK listeners.
+
+## Logout — cleanup only runs if the SDK call resolves
+```ts
+import { CometChatUIKit } from '@cometchat/chat-uikit-angular';
+
+export async function signOut(navigateToLogin: () => void) {
+  try {
+    await CometChatUIKit.logout();
+  } catch {
+    // swallow — still treat the user as signed out locally, see below
+  } finally {
+    navigateToLogin();   // unconditional — do not gate this on the promise resolving
+  }
+}
+```
+Verified in the installed 5.1.0 bundle: `CometChatUIKit.logout()` only runs its local cleanup (`detachListeners`, clearing the cached user, `loggedInUser$` → `null`) **inside** `CometChat.logout()`'s `.then()`. A rejection (reproduced: `USER_NOT_LOGED_IN` — *"an authToken is need to use the userLogout end-point"*) skips cleanup entirely — `getLoggedInUser()`/`loggedInUser$` keep reporting the old session, and `initFromSettings` rehydrates that same stale user on the next reload (§ above), so sign-out silently doesn't stick. Undocumented in the pack and the official docs.
+
+Never drive a login-screen redirect off `loggedInUser$` emitting `null` after calling logout — on a rejection it may not. `catch` the call and navigate/clear your own app-level "signed in" state unconditionally in a `finally`; treat the kit's local cache as advisory, not authoritative, for this one transition.