@cometchat/skills 4.4.1 → 5.0.0

package/skills/cometchat-angular-v5-components/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: cometchat-angular-v5-components
+description: "Choose, compose and customize CometChat Angular UI Kit components — the closed component list, real @Input/@Output names, view-slot overrides via ng-template, and the surfaces that have NO kit component and must be host-composed. Triggers: 'which components exist', 'customize the conversation list', 'custom message bubble', 'create a group', 'show banned members', 'swap the list item'."
+license: "MIT"
+compatibility: "@cometchat/chat-uikit-angular ^5 (5.1.0–5.2.0 verified); Angular 17-21"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat angular components uikit v5 slots content-projection customization"
+---
+
+> **Ground truth:** the existence oracle is the `angular-v5` catalog (`references/catalog.md`, generated from the installed 5.1.0 kit). Not listed = not importable. Exact inputs/outputs/view slots are FETCHED from each component's `.md` twin via `cometchat-angular-v5-core/references/docs-map.md` — every page opens with an **AI Integration Quick Reference**; read that first. Never answer an input or output from memory or from the type declarations.
+
+## Companion skills (read first)
+- `cometchat-angular-v5-core` — install, credentials, `init→login→render`, the golden-path surface. This skill ASSUMES it and never restates it.
+
+## Use this skill when
+Picking which component to use, overriding part of one, or discovering that the thing asked for has no component at all.
+
+## Naming — three different strings per component
+`CometChatConversationsComponent` (import) · `<cometchat-conversations>` (template) · "Conversations" (docs title). The bare `CometChatConversations` is **internal-only and not importable** — 109 such names exist. The AI-assistant exports are the sole suffix exception (`CometChatAIAssistantChat`).
+
+## Output names carry NO prefix
+Angular outputs are plain: `itemClick`, `select`, `error`, `closeClick`, `selectionChange`. There is **no** `cc` prefix — that is React's convention. Binding `(ccConversationClicked)` silently never fires.
+> ⚠️ An output that does not exist fails the SAME silent way — Angular treats an unknown event on a component as a plain DOM listener, so `(closeClick)` on `<cometchat-message-header>` compiles clean and never fires. `closeClick` is real on `<cometchat-thread-header>` but NOT on the message header (verified vs compiled 5.1.0). Use `backClick` there.
+
+| Component | Outputs |
+| --- | --- |
+| `<cometchat-conversations>` | `itemClick` `select` `error` `searchBarClick` `contextMenuOpen` `contextMenuClose` `scrollToTop` `scrollToBottom` `selectionChange` |
+| `<cometchat-users>` | `itemClick` `select` `error` `empty` `selectionChange` |
+| `<cometchat-groups>` | `itemClick` `select` `error` `selectionChange` |
+| `<cometchat-group-members>` | `itemClick` `error` `empty` `selectionChange` |
+| `<cometchat-message-list>` | `threadRepliesClick` `reactionClick` `reactionListItemClick` `smartReplyClick` `conversationStarterClick` `messagePrivatelyClick` `replyClick` `error` |
+| `<cometchat-message-composer>` | `sendButtonClick` `textChange` `attachmentAdded` `attachmentRemoved` `mentionSelected` `closePreview` `error` |
+| `<cometchat-message-header>` | `backClick` `itemClick` `searchClick` `voiceCallClick` `videoCallClick` `conversationSummaryClick` `error` |
+| `<cometchat-thread-header>` | `closeClick` `backClick` |
+| `<cometchat-search>` | `backClick` `conversationClick` `messageClick` `searchError` |
+
+Anything not listed: fetch the component's docs page (`cometchat-angular-v5-core/references/docs-map.md`). Do not guess an output name.
+
+## Component catalog (BAKED closed list)
+Full per-component inputs live in the docs — this is the "which one do I reach for" map. Complete list: `references/catalog.md`.
+
+**Lists** `<cometchat-conversations>` · `<cometchat-users>` · `<cometchat-groups>` · `<cometchat-group-members>`
+**Message pane** `<cometchat-message-header>` · `<cometchat-message-list>` · `<cometchat-message-composer>` · `<cometchat-thread-header>`
+**Bubbles** text · image · video · audio · file · card · poll · sticker · action · delete · call · collaborative-document · collaborative-whiteboard *(all rendered BY the message list — see below)*
+**Calls** `<cometchat-call-buttons>` · `<cometchat-incoming-call>` · `<cometchat-outgoing-call>` · `<cometchat-ongoing-call>` · `<cometchat-call-logs>`
+**Search** `<cometchat-search>` · `<cometchat-search-bar>` · `<cometchat-search-conversations-list>` · `<cometchat-search-messages-list>`
+**AI** `CometChatAIAssistantChat` · `<cometchat-smart-replies>` · `<cometchat-conversation-starter>` · `<cometchat-conversation-summary>`
+**Reactions** `<cometchat-reactions>` · `<cometchat-reaction-list>` · `<cometchat-reaction-info>` · `<cometchat-emoji-keyboard>`
+**Support** `<cometchat-error-boundary>` · `<cometchat-notification-feed>` · `<cometchat-notification-badge>` · `<cometchat-change-scope>` · `<cometchat-flag-message-dialog>` · `<cometchat-media-recorder>`
+
+## Do NOT hand-roll what the list already renders
+Message bubbles, receipts, reaction pickers, typing indicators, attachment previews and the context menu are rendered **by** `<cometchat-message-list>` when the corresponding feature is on. Rebuilding them by hand loses realtime updates and every future fix. If an affordance looks broken it is nearly always a missing `@Input()` or an unsized container, not a missing component. **`<cometchat-conversations>` / `-users` / `-groups` / `-call-logs` / `-search` / `-message-list` specifically all rely on an internal `height: 100%` down to their own scroll region — none sizes itself.** Placed in a flex column without `flex: 1; min-height: 0` (the `.cc-fill` class, `cometchat-angular-v5-placement/references/core-surface.md`), a list doesn't scroll: it grows past its container and gets silently clipped.
+
+## Building your OWN chrome? The kit exports the atoms too
+The rule above covers what `<cometchat-message-list>` renders for you. A second case is your own UI — a signed-in user bar, a profile header, a custom row — where the kit still ships the piece you are about to rebuild:
+
+| Atom | Selector | Use it for |
+| --- | --- | --- |
+| `CometChatAvatarComponent` | `<cometchat-avatar>` | any user/group avatar — `[image]`, `[name]`, `[loading]` |
+| `CometChatListItemComponent` | `<cometchat-list-item>` | a row with avatar + title + trailing content |
+| `CometChatButtonComponent` | `<cometchat-button>` | an action button that matches kit styling |
+| `CometChatDateComponent` | `<cometchat-date>` | a timestamp with the kit's formatting |
+| `CometChatPopoverComponent` | `<cometchat-popover>` | anchored menus/pickers |
+
+```html
+<!-- ✅ themed, falls back to initials when there is no picture, follows light/dark -->
+<cometchat-avatar [image]="user?.getAvatar()" [name]="user?.getName()"></cometchat-avatar>
+
+<!-- ❌ hand-rolled: needs your own fallback URL, ignores the theme, drifts from the kit -->
+<img [src]="user?.getAvatar() || 'https://…/astronaut.png'" class="my-avatar" />
+```
+
+A hand-rolled `<img>` is the common one. It forces you to invent a placeholder, it does not render initials when the user has no picture, and it ignores every avatar token in the theme. **Before styling a presentational element yourself, check this table** — and remember these are standalone components, so each one you use goes in the consuming component's `imports: []`.
+
+## Customizing part of a component — view slots
+Override a region with a `<ng-template>` bound to a `*View` input. This is Angular's content projection; it replaces React's render props.
+
+```ts
+import { Component, ViewChild, TemplateRef } from '@angular/core';
+import { CometChatConversationsComponent } from '@cometchat/chat-uikit-angular';
+
+@Component({
+  selector: 'app-convo-list',
+  standalone: true,
+  imports: [CometChatConversationsComponent],
+  templateUrl: './convo-list.component.html',
+})
+export class ConvoListComponent {
+  @ViewChild('customItem', { static: true }) customItem!: TemplateRef<unknown>;
+
+  // A trigger must have a handler in the SAME class, or the template fails to compile
+  // (TS2339). `(itemClick)` emits a Conversation — discriminate it before binding the
+  // subject to [user] or [group] (see cometchat-angular-v5-placement).
+  open(conversation: CometChat.Conversation) { /* select the conversation */ }
+}
+```
+```html
+<ng-template #customItem let-conversation>
+  <div class="my-row">{{ conversation?.getConversationId() }}</div>
+</ng-template>
+
+<cometchat-conversations [itemView]="customItem" (itemClick)="open($event)"></cometchat-conversations>
+```
+
+Slots available per component (verified against the kit):
+
+| Component | View slots |
+| --- | --- |
+| conversations · users · groups | `headerView` `menuView` `loadingView` `emptyView` `errorView` `itemView` `leadingView` `titleView` `subtitleView` `trailingView` (+ `searchView` on conversations) |
+| message-header | `headerView` `itemView` `leadingView` `titleView` `subtitleView` `trailingView` `backButtonView` `auxiliaryButtonView` |
+| message-list | `headerView` `footerView` `emptyView` `errorView` `loadingView` `bubbleFooterView` `appendView` |
+
+Override the smallest slot that does the job — replacing `itemView` when you only wanted a different subtitle loses selection, presence and receipts.
+
+## Surfaces with NO kit component (host-composed)
+Requested often, and there is nothing to import. Build these yourself against the SDK — see `references/host-composed.md`.
+- **Create a group** — no component. Offer all three types: public, private, **and password-protected**.
+- **Banned members** — no component; `<cometchat-group-members>` covers view/kick/ban/scope but the banned LIST comes from the SDK.
+- **Login / user picker** — no component; app-owned.
+
+## Common pitfalls
+1. Component not in `imports: []` → renders nothing, silently. Every component, every consuming component.
+2. Guessing an output name (`ccItemClicked`) → binding never fires and Angular does not warn.
+3. Replacing `itemView` for a cosmetic tweak → loses built-in selection/presence/receipts.
+4. Mixing `[user]` and `[group]` across header/list/composer → one conversation's header over another's messages.
+5. Hand-rolling bubbles → loses realtime updates.
+
+## Verify it works
+The overridden region renders your template · the rest of the component is unchanged · clicks still fire · realtime updates still arrive · nothing collapsed to zero height.

package/skills/cometchat-angular-v5-components/references/catalog.md

@@ -0,0 +1,111 @@
+# Component catalog — every exported component, class → selector
+
+Generated from the installed kit's component declarations. **This table covers COMPONENTS only — a name missing from it is not therefore "not importable."** The kit also exports **253 non-component values** (services, event buses, constants, pipes, formatters): see § Non-component exports below. Anything in neither place: check `docs-map.md` — never conclude a symbol is absent from its absence here alone.
+
+| Class | Selector |
+| --- | --- |
+| `CometChatAIAssistantChat` | `<cometchat-ai-assistant-chat>` |
+| `CometChatAIAssistantChatHistory` | `<cometchat-ai-assistant-chat-history>` |
+| `CometChatAIAssistantMessageBubble` | `<cometchat-ai-assistant-message-bubble>` |
+| `CometChatActionBubbleComponent` | `<cometchat-action-bubble>` |
+| `CometChatActionSheetComponent` | `<cometchat-action-sheet>` |
+| `CometChatAudioBubbleComponent` | `<cometchat-audio-bubble>` |
+| `CometChatAudiosBubbleComponent` | `<cometchat-audios-bubble>` |
+| `CometChatAvatarComponent` | `<cometchat-avatar>` |
+| `CometChatButtonComponent` | `<cometchat-button>` |
+| `CometChatCallBubbleComponent` | `<cometchat-call-bubble>` |
+| `CometChatCallButtonsComponent` | `<cometchat-call-buttons>` |
+| `CometChatCallLogsComponent` | `<cometchat-call-logs>` |
+| `CometChatCardBubbleComponent` | `<cometchat-card-bubble>` |
+| `CometChatChangeScopeComponent` | `<cometchat-change-scope>` |
+| `CometChatCheckboxComponent` | `<cometchat-checkbox>` |
+| `CometChatCollaborativeDocumentBubbleComponent` | `<cometchat-collaborative-document-bubble>` |
+| `CometChatCollaborativeWhiteboardBubbleComponent` | `<cometchat-collaborative-whiteboard-bubble>` |
+| `CometChatConfirmDialogComponent` | `<cometchat-confirm-dialog>` |
+| `CometChatContextMenuComponent` | `<cometchat-context-menu>` |
+| `CometChatConversationItemComponent` | `<cometchat-conversation-item>` |
+| `CometChatConversationStarterComponent` | `<cometchat-conversation-starter>` |
+| `CometChatConversationSummaryComponent` | `<cometchat-conversation-summary>` |
+| `CometChatConversationsComponent` | `<cometchat-conversations>` |
+| `CometChatCreatePollComponent` | `<cometchat-create-poll>` |
+| `CometChatDateComponent` | `<cometchat-date>` |
+| `CometChatDeleteBubbleComponent` | `<cometchat-delete-bubble>` |
+| `CometChatDropDownComponent` | `<cometchat-dropdown>` |
+| `CometChatEmojiKeyboardComponent` | `<cometchat-emoji-keyboard>` |
+| `CometChatErrorBoundaryComponent` | `<cometchat-error-boundary>` |
+| `CometChatFileBubbleComponent` | `<cometchat-file-bubble>` |
+| `CometChatFilesBubbleComponent` | `<cometchat-files-bubble>` |
+| `CometChatFlagMessageDialogComponent` | `<cometchat-flag-message-dialog>` |
+| `CometChatFullScreenViewerComponent` | `<cometchat-fullscreen-viewer>` |
+| `CometChatGroupItemComponent` | `<cometchat-group-item>` |
+| `CometChatGroupMemberItemComponent` | `<cometchat-group-member-item>` |
+| `CometChatGroupMembersComponent` | `<cometchat-group-members>` |
+| `CometChatGroupsComponent` | `<cometchat-groups>` |
+| `CometChatImageBubbleComponent` | `<cometchat-image-bubble>` |
+| `CometChatImagesBubbleComponent` | `<cometchat-images-bubble>` |
+| `CometChatIncomingCallComponent` | `<cometchat-incoming-call>` |
+| `CometChatLinkDialogComponent` | `<cometchat-link-dialog>` |
+| `CometChatLinkPopoverComponent` | `<cometchat-link-popover>` |
+| `CometChatListItemComponent` | `<cometchat-list-item>` |
+| `CometChatMarkdownRenderer` | `<cometchat-markdown-renderer>` |
+| `CometChatMediaRecorderComponent` | `<cometchat-media-recorder>` |
+| `CometChatMessageBubbleComponent` | `<cometchat-message-bubble>` |
+| `CometChatMessageComposerComponent` | `<cometchat-message-composer>` |
+| `CometChatMessageHeaderComponent` | `<cometchat-message-header>` |
+| `CometChatMessageInformationComponent` | `<cometchat-message-information>` |
+| `CometChatMessageListComponent` | `<cometchat-message-list>` |
+| `CometChatMessagePreviewComponent` | `<cometchat-message-preview>` |
+| `CometChatNotificationBadgeComponent` | `<cometchat-notification-badge>` |
+| `CometChatNotificationFeedComponent` | `<cometchat-notification-feed>` |
+| `CometChatOngoingCallComponent` | `<cometchat-ongoing-call>` |
+| `CometChatOutgoingCallComponent` | `<cometchat-outgoing-call>` |
+| `CometChatPollBubbleComponent` | `<cometchat-poll-bubble>` |
+| `CometChatPopoverComponent` | `<cometchat-popover>` |
+| `CometChatRadioButtonComponent` | `<cometchat-radio-button>` |
+| `CometChatReactionInfoComponent` | `<cometchat-reaction-info>` |
+| `CometChatReactionListComponent` | `<cometchat-reaction-list>` |
+| `CometChatReactionsComponent` | `<cometchat-reactions>` |
+| `CometChatSearchBarComponent` | `<cometchat-search-bar>` |
+| `CometChatSearchComponent` | `<cometchat-search>` |
+| `CometChatSearchConversationsListComponent` | `<cometchat-search-conversations-list>` |
+| `CometChatSearchMessagesListComponent` | `<cometchat-search-messages-list>` |
+| `CometChatSmartRepliesComponent` | `<cometchat-smart-replies>` |
+| `CometChatStickerBubbleComponent` | `<cometchat-sticker-bubble>` |
+| `CometChatStickersKeyboardComponent` | `<cometchat-stickers-keyboard>` |
+| `CometChatStreamMessageBubble` | `<cometchat-stream-message-bubble>` |
+| `CometChatTextBubbleComponent` | `<cometchat-text-bubble>` |
+| `CometChatThreadHeaderComponent` | `<cometchat-thread-header>` |
+| `CometChatThreadViewComponent` | `<cometchat-thread-view>` |
+| `CometChatToastComponent` | `<cometchat-toast>` |
+| `CometChatToolCallArgumentBubble` | `<cometchat-toolcall-argument-bubble>` |
+| `CometChatToolCallResultBubble` | `<cometchat-toolcall-result-bubble>` |
+| `CometChatTypingIndicatorComponent` | `<cometchat-typing-indicator>` |
+| `CometChatUserItemComponent` | `<cometchat-user-item>` |
+| `CometChatUsersComponent` | `<cometchat-users>` |
+| `CometChatVideoBubbleComponent` | `<cometchat-video-bubble>` |
+| `CometChatVideosBubbleComponent` | `<cometchat-videos-bubble>` |
+| `CometChatVoiceNoteBubbleComponent` | `<cometchat-voice-note-bubble>` |
+
+## Non-component exports (the other half of the oracle)
+
+Verified against 5.1.0's public `export { … }` block. These have **no selector** — you `inject()` a service, call a static, or use a pipe in a template. Reaching for `.d.ts` to check whether one of these exists is the failure this section prevents.
+
+| Kind | Exported from `@cometchat/chat-uikit-angular` |
+| --- | --- |
+| **State / theming** | `ChatStateService` · `ThemeService` · `ConnectionStateService` |
+| **Config / templates** | `MessageBubbleConfigService` · `CometChatTemplatesService` · `FormatterConfigService` · `COMETCHAT_GLOBAL_CONFIG` |
+| **Init / constants** | `CometChatUIKit` · `UIKitSettings` · `UIKitSettingsBuilder` · `CometChatUIKitConstants` · `DEFAULT_MESSAGE_TYPES` · `DEFAULT_MESSAGE_CATEGORIES` · `MENTIONS_LIMIT` |
+| **Event buses** (6, all-static) | `CometChatMessageEvents` · `CometChatGroupEvents` · `CometChatUserEvents` · `CometChatCallEvents` · `CometChatConversationEvents` · `CometChatUIEvents` |
+| **Per-message actions** | `CometChatActions` · `CometChatActionsIcon` · `CometChatActionsView` · `CometChatOption` · `CometChatMessageComposerAction` |
+| **Localization** | `CometChatLocalize` · `getLocalizedString` · `TranslatePipe` |
+| **Pipes** | `TranslatePipe` · `MessageDatePipe` · `ConversationDatePipe` · `CalendarDatePipe` · `BadgeCountPipe` · `CategoryUnreadCountPipe` · `CardJsonPipe` |
+| **Text formatters** | `CometChatTextFormatter` · `CometChatMentionsFormatter` · `CometChatUrlFormatter` · `CometChatEmojiFormatter` · `CometChatMarkdownFormatter` · `CometChatMarkdownParser` · `CometChatMarkdownRenderer` |
+| **Data services** (inject to read list state) | `ConversationsService` · `MessageListService` · `MessageHeaderService` · `MessageComposerService` · `GroupMembersService` · `SearchConversationsService` · `SearchMessagesService` · `CallLogsService` · `IncomingCallService` · `OngoingCallService` · `OutgoingCallService` · `CallButtonsService` · `NotificationUnreadCountService` (+20 more internal-leaning `*Service`s in the export block) |
+| **Calls / misc** | `CometChatUIKitCalls` · `CometChatNotifications` · `CometChatLogger` · `CometChatToastService` |
+| **Search filters** | `CometChatSearchFilter` · `CometChatSearchScope` |
+
+> **`export type { … }` — type-only, cannot be used as a value:** `CalendarObject`, `SearchConversationClickEvent`, `SearchMessageClickEvent`, `IMessages`, `MessageStatus`, `CometChatEmoji`, `BubblePart`, … Import them under `import type`; instantiating one is a compile error.
+>
+> **SDK entities are NOT kit exports.** `CometChat`, `User`, `Group`, `TextMessage`, `MediaMessage`, `CustomMessage`, `BaseMessage`, `Conversation`, `GroupMember`, and every `*RequestBuilder` come from **`@cometchat/chat-sdk-javascript`** — importing them from the Angular package fails. (`CometChatSoundManager` is the inverse trap: it is *declared* in the kit's `.d.ts` and compiled into the bundle but is in **neither** export block, so it is not importable at all — AUDIT-152.)
+>
+> The machine oracle is the full 3,723-symbol `angular-v5.json` catalog, which tracks each symbol's source package; this file is its curated, agent-facing half.

package/skills/cometchat-angular-v5-components/references/host-composed.md

@@ -0,0 +1,46 @@
+# Host-composed surfaces — no kit component exists
+
+These are asked for regularly. There is nothing to import; build them against the SDK. Say so plainly rather than inventing a component name.
+
+## Create a group
+No kit component. Offer **all three** types — omitting password-protected is a real gap, not a simplification.
+
+```ts
+import { CometChat } from '@cometchat/chat-sdk-javascript';
+import { CometChatUIKitConstants } from '@cometchat/chat-uikit-angular';
+
+type GroupType = 'public' | 'private' | 'password';
+
+async function createGroup(guid: string, name: string, type: GroupType, password?: string) {
+  const t =
+    type === 'public'  ? CometChatUIKitConstants.GroupTypes.public  :
+    type === 'private' ? CometChatUIKitConstants.GroupTypes.private :
+                         CometChatUIKitConstants.GroupTypes.password;
+  const group = new CometChat.Group(guid, name, t, password);
+  return CometChat.createGroup(group);
+}
+```
+The form is yours: a name field, a type selector with all three options, and a password field revealed only for `password`. After creation, refresh the groups list.
+
+## Banned members
+`<cometchat-group-members>` handles view / kick / ban / scope change, but the banned LIST has no component. Fetch it:
+
+```ts
+import { CometChat } from '@cometchat/chat-sdk-javascript';
+
+async function bannedMembers(guid: string) {
+  const req = new CometChat.BannedMembersRequestBuilder(guid).setLimit(30).build();
+  return req.fetchNext();
+}
+
+async function unban(guid: string, uid: string) {
+  return CometChat.unbanGroupMember(guid, uid);
+}
+```
+Render with your own list UI and give each row an unban action. Paginate with repeated `fetchNext()` — do not assume one page is all of them.
+
+## Login / user picker
+No component, by design — authentication is app-owned. Development can log in a known UID; production mints an auth token server-side (`cometchat-angular-v5-core/references/setup-credentials.md`).
+
+## Rule
+If a request maps to none of the shipped components, say so, point at the SDK docs (`cometchat-angular-v5-core/references/docs-map.md` → SDK section), and build it host-side. Never invent a component name to fill the gap — it will not compile, and a plausible-looking name is worse than an honest "there isn't one".

package/skills/cometchat-angular-v5-core/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: cometchat-angular-v5-core
+description: "Add CometChat chat to an Angular app end-to-end — detect the project, get & verify dashboard credentials, init→login→render with standalone components, and the drop-in conversation UI. The core knowledge every other Angular v5 skill builds on. Triggers: 'add chat to my angular app', 'integrate cometchat angular', 'set up cometchat credentials angular', 'show conversations and messages angular'."
+license: "MIT"
+compatibility: "Node.js >=18; Angular 17-21 (NOT 22 — see Install); @cometchat/chat-uikit-angular ^5 (5.1.0–5.2.0 verified); @cometchat/chat-sdk-javascript ^4"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat angular core chat integration uikit v5 setup credentials standalone"
+---
+
+> **Ground truth:** `@cometchat/chat-uikit-angular@^5` + `@cometchat/chat-sdk-javascript@^4`, symbols verified across 5.1.0–5.2.0 / 4.1.13–4.2.0 (unchanged set; catalog `verifiedCompatibleRange`). This file is the THIN map loaded every run; deep detail lives in `references/*`, loaded ONLY when the task needs it.
+
+## Use this skill when
+Adding CometChat to an Angular app, or you need the setup every other Angular v5 skill assumes: install, credentials, init→login→render ordering, and the component map.
+
+## Prerequisites & install
+
+### The three Angular rules that break everything else
+Read these first. Each produces code that compiles, shows no error, and does not work.
+
+1. **Every component must be in `imports: []`.** The kit ships *standalone* components. Use `<cometchat-conversations>` in a template without importing `CometChatConversationsComponent` into that component's `imports` array and Angular renders **nothing** — no error, no warning, blank space. This is the single most common failure.
+2. **Config lives in `src/environments/environment.ts`, NOT `.env`.** Angular resolves it at build time via file replacement. Any `.env` instruction is wrong here.
+3. **Class name ≠ selector ≠ docs title.** `CometChatConversationsComponent` (import) · `<cometchat-conversations>` (template) · "Conversations" (docs). All three are different; use the right one in the right place.
+
+### Install
+```bash
+npm install @cometchat/chat-uikit-angular@^5 @cometchat/chat-sdk-javascript@^4 @cometchat/cards-angular@^1 dompurify@^3
+```
+Calls only (optional): `npm install @cometchat/calls-sdk-javascript@^5`
+
+> ⚠️ **Angular 22 fails to install.** The kit's peer range is `@angular/core >=17.0.0 <22.0.0`, so `npm install` on Angular 22 hard-fails with `ERESOLVE`. Scaffold a new app with `npx -y @angular/cli@21 new <app>`. CometChat's stated policy is that 18+ is supported, so this range is expected to widen in a future kit release — until it ships, 22 does not work. Angular 17 works but is undocumented.
+
+`angular.json` needs **three** changes under `projects.<app>.architect.build` — the stylesheet, the icon assets, and the production budgets.
+
+`styles` — the kit stylesheet must come **FIRST**, before your own:
+```json
+"styles": [
+  "node_modules/@cometchat/chat-uikit-angular/styles/css-variables.css",
+  "src/styles.css"
+]
+```
+> ⚠️ **Order decides, and failing it is SILENT** — the kit re-declares tokens under `[data-theme="dark"]` at your `:root`'s specificity, so appending the kit file makes it win and your brand colors vanish without error. Detail: `references/theming.md`.
+
+`assets` — the kit ships ~300 SVG icons under `src/lib/assets` (the glob copies them all; count is not load-bearing):
+```json
+{ "glob": "**/*", "input": "node_modules/@cometchat/chat-uikit-angular/src/lib/assets", "output": "assets" }
+```
+
+**Production budgets — raise them or `ng build` HARD-FAILS.** The kit + Chat SDK is ~4.2 MB against a stock 1 MB error budget, so the DEFAULT `ng build` exits non-zero while `ng serve` is fine. Raise `budgets` + set `allowedCommonJsDependencies`: `references/dependencies.md`.
+
+> ⚠️ **Miss the `assets` entry and icons are broken throughout the kit** (send/attach/emoji, call controls, menus) — nothing errors, it just reads as a theming problem. The single most commonly missed setup step in Angular.
+> ⚠️ Do **not** `@import` the kit's `css-variables.css` in a `.scss`/`.css` file — the package's `exports` map does not expose that path and the build fails. The full `node_modules/...` path in `angular.json` bypasses it.
+
+Full dependency table: `references/dependencies.md`.
+
+## Setup & credentials (essentials — full detail: `references/setup-credentials.md`)
+Three values: **App ID**, **Region**, **Auth Key**. When they are missing, **OFFER both paths and default to the fetch** — *"I can fetch them by logging into your CometChat dashboard, or you can paste them manually"* — and never end the build with a "add credentials yourself" TODO.
+
+```ts
+// src/environments/environment.ts
+export const environment = {
+  production: false,
+  cometchat: { appId: 'APP_ID', region: 'REGION', authKey: 'AUTH_KEY' },
+};
+```
+**A fourth value you must ASK for: the login UID.** The app logs in as somebody the moment it opens, and only the developer knows who that should be. **Ask — do not pick one silently:**
+
+> *"Which user should the app log in as on startup? You'll find your UIDs under Dashboard → your app → Users. If this is a fresh app I can create `cometchat-uid-1` for you and log in as that."*
+
+`cometchat-uid-1` is the docs **sample**, not a promise about this app — on an app whose sample users were never seeded, `login()` fails and the screen stays blank with no visible error. Never hardcode it and move on; if the developer has no UID, use the create-if-missing `ensureDevUser()` (`references/lifecycle.md`).
+
+Create `environment.prod.ts` with the same shape and wire `fileReplacements` in `angular.json`. **The Auth Key is dev-only** — production mints an auth token server-side and calls `loginWithAuthToken`. See `references/setup-credentials.md`.
+
+## Integration ordering (BAKED — invariant)
+**`init()` must resolve BEFORE `login()`, and `login()` before any kit component renders.** Out of order, components mount with no session and render empty.
+
+In Angular this is an app initializer, not a component effect:
+
+```ts
+// src/main.ts
+import { bootstrapApplication } from '@angular/platform-browser';
+import { CometChatUIKit } from '@cometchat/chat-uikit-angular';
+import { environment } from './environments/environment';
+// Angular 20+ scaffolds `src/app/app.ts` exporting `App`; 17-19 scaffold `app.component.ts`
+// exporting `AppComponent`. Use whichever YOUR app has (wrong one → "Could not resolve …").
+import { App } from './app/app';                 // Angular 20+ (CLI 21 default)
+// import { AppComponent } from './app/app.component';   // Angular 17-19
+import { appConfig } from './app/app.config';
+
+const { appId, region, authKey } = environment.cometchat;
+// authKey is DEV-only: prod ships it empty + logs in with a server token — so require it
+// only in dev, else every prod build throws behind a green `ng build`.
+if (!appId || !region) {
+  throw new Error('CometChat appId/region empty — check src/environments/environment*.ts.');
+}
+if (!environment.production && !authKey) {
+  throw new Error('CometChat authKey empty — dev login needs it (production uses an auth token).');
+}
+
+// `cometchat-uid-1` is the docs SAMPLE, not a guarantee this app has it — a missing UID renders a
+// blank screen. Use a real UID from Dashboard → Users, or ensureDevUser() (references/lifecycle.md).
+const uid = 'cometchat-uid-1';
+
+// Prod only: YOUR backend mints this user's auth token (endpoint shape: cometchat-angular-v5-production).
+async function fetchAuthToken(): Promise<string> {
+  const res = await fetch('/api/cometchat-token', { credentials: 'include' });
+  if (!res.ok) throw new Error(`CometChat token endpoint: HTTP ${res.status}`);
+  return ((await res.json()) as { authToken: string }).authToken;
+}
+
+// initFromSettings (NOT the classic builder init) so integrationSource="ai-agent" propagates for
+// telemetry attribution, and routes the Calls SDK too.
+// Bootstrap the app in `finally` so it ALWAYS mounts: a failed init/login (empty prod authKey, a wrong
+// UID, a network blip) must leave CHAT degraded, never the WHOLE Angular app blank behind a green build.
+(async () => {
+  try {
+    await CometChatUIKit.initFromSettings({
+      appId,
+      region,
+      credentials: { authKey },                              // dev only — empty in prod
+      chatSDK: { presenceSubscription: { type: 'ALL_USERS' } },
+    });
+    await (environment.production
+      ? CometChatUIKit.loginWithAuthToken(await fetchAuthToken())  // prod: authKey stays server-side
+      : CometChatUIKit.login(uid));                                // dev: Auth-Key login
+  } catch (e) {
+    console.error('CometChat init/login failed', e);
+  } finally {
+    bootstrapApplication(App, appConfig).catch((err) => console.error(err));
+  }
+})();
+```
+
+Guarded login, `ensureDevUser` (create-if-missing for a dev start), `provideAppInitializer`, route guards, and the `loggedInUser$` Observable: `references/lifecycle.md`.
+
+## Docs first for the API — the installed kit for BEHAVIOUR the docs omit
+**What exists and what it is called comes from the docs.** Fetch the component's page (`references/docs-map.md` → `DOCS_BASE` + path + `.md`); read its **AI Integration Quick Reference** first. Do **not** invent an API from the type declarations — they expose internal-only names and members with no defined behaviour.
+
+**But reading the shipped bundle IS correct when the docs state a prop and not its semantics** (e.g. `attachmentOptions` — does yours *append* or *replace*? it appends; `messagesRequestBuilder` — override or merge?). When behaviour is load-bearing and undocumented, verify it in `node_modules/@cometchat/chat-uikit-angular/fesm2022/*.mjs`, then (1) say in your summary you verified against the installed kit, and (2) report it as a docs gap.
+
+> Full methodology + the worked examples — see `references/docs-map.md` § "Docs first for the API".
+
+## Component / API map (BAKED closed list)
+Exported **class** → template **selector**. Anything not here, look up via `references/docs-map.md` — do not guess.
+
+| Class | Selector | Purpose |
+| --- | --- | --- |
+| `CometChatConversationsComponent` | `<cometchat-conversations>` | conversation list |
+| `CometChatMessageHeaderComponent` | `<cometchat-message-header>` | active chat header |
+| `CometChatMessageListComponent` | `<cometchat-message-list>` | message pane |
+| `CometChatMessageComposerComponent` | `<cometchat-message-composer>` | composer |
+| `CometChatThreadHeaderComponent` | `<cometchat-thread-header>` | thread panel header |
+| `CometChatUsersComponent` | `<cometchat-users>` | user directory |
+| `CometChatGroupsComponent` | `<cometchat-groups>` | group directory |
+| `CometChatGroupMembersComponent` | `<cometchat-group-members>` | member management |
+| `CometChatSearchComponent` | `<cometchat-search>` | search surface |
+| `CometChatErrorBoundaryComponent` | `<cometchat-error-boundary>` | error containment |
+| `CometChatIncomingCallComponent` | `<cometchat-incoming-call>` | app-root call listener |
+
+Non-component exports you will need: `CometChatUIKit` (init/login), `UIKitSettingsBuilder`, `ChatStateService` (active chat state), `CometChatUIKitConstants`, `CometChatLocalize`, `ThemeService`.
+
+> **Naming exception:** the AI-assistant exports carry **no** `Component` suffix — `CometChatAIAssistantChat`, not `…ChatComponent`.
+
+## Golden path — the production-ready CORE surface
+The default for an unscoped "add chat": ships conversations · messages. **This is deliberately the CORE surface, not the whole app** — a users / groups / calls **tab selector**, a details or thread side panel, threads, search, and calling are **grow targets**, correct to omit unless asked. Build them via `cometchat-angular-v5-placement` (`references/combined-app.md` / `references/core-surface.md`), not by improvising here.
+
+```ts
+// src/app/chat/chat.component.ts
+import { Component, inject } from '@angular/core';
+import { CometChat } from '@cometchat/chat-sdk-javascript';   // Conversation / User / Group types
+import {
+  CometChatConversationsComponent, CometChatMessageHeaderComponent,
+  CometChatMessageListComponent, CometChatMessageComposerComponent,
+  CometChatErrorBoundaryComponent, CometChatUIKitConstants, ThemeService,
+} from '@cometchat/chat-uikit-angular';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-chat',
+  standalone: true,
+  imports: [                                 // ← omit this and NOTHING renders
+    CommonModule,
+    CometChatErrorBoundaryComponent,
+    CometChatConversationsComponent,
+    CometChatMessageHeaderComponent,
+    CometChatMessageListComponent,
+    CometChatMessageComposerComponent,
+  ],
+  templateUrl: './chat.component.html',
+  styleUrl: './chat.component.css',
+})
+export class ChatComponent {
+  // FOLLOW THE OS light/dark setting: the kit ships both themes but does NOT follow the OS itself.
+  // `initFromPreference()` reads prefers-color-scheme + keeps its own matchMedia listener live — do
+  // not hand-roll one; put it in the ROOT component for a multi-page app (references/theming.md).
+  constructor() { inject(ThemeService).initFromPreference(); }
+
+  // TWO slots, never one: `(itemClick)` emits a Conversation whose subject is a User (1:1) OR a Group.
+  // Binding one `selected` to `[user]` ships clean on 1:1 and throws "getUid is not a function" on a GROUP.
+  // `| undefined`, NOT `| null` — the kit declares `user?`/`group?` and strictTemplates (ON by default)
+  // rejects `| null` with TS2322. Full rationale: references/anti-patterns.md.
+  selectedUser: CometChat.User | undefined = undefined;
+  selectedGroup: CometChat.Group | undefined = undefined;
+  get hasChat() { return !!(this.selectedUser || this.selectedGroup); }
+
+  onItemClick(conversation: CometChat.Conversation) {
+    const subject = conversation.getConversationWith();
+    // Ask the Conversation what it is — do NOT duck-type on getGuid() (a Conversation has none, so it
+    // silently sends every group down the user path).
+    if (conversation.getConversationType() === CometChatUIKitConstants.MessageReceiverType.group) {
+      this.selectedGroup = subject as CometChat.Group;
+      this.selectedUser = undefined;
+    } else {
+      this.selectedUser = subject as CometChat.User;
+      this.selectedGroup = undefined;
+    }
+  }
+}
+```
+
+```html
+<!-- chat.component.html -->
+<cometchat-error-boundary>
+  <div class="cc-shell">
+    <aside class="cc-side">
+      <cometchat-conversations class="cc-fill" (itemClick)="onItemClick($event)"></cometchat-conversations>
+    </aside>
+    <!-- Pass BOTH slots on all three components; exactly one is non-null. -->
+    <main class="cc-main" *ngIf="hasChat; else empty">
+      <cometchat-message-header [user]="selectedUser" [group]="selectedGroup"></cometchat-message-header>
+      <!-- The thread-reply indicator is clickable whether or not you bind (threadRepliesClick);
+           unwired it emits into a dead handler (RULES §12 wire-or-hide). This golden path omits the
+           thread PANEL (first GROW step), so HIDE the affordance here; add panel + wire when you grow
+           into it — references/layout.md. -->
+      <cometchat-message-list class="cc-fill" [user]="selectedUser" [group]="selectedGroup"
+        [hideReplyInThreadOption]="true"></cometchat-message-list>
+      <cometchat-message-composer [user]="selectedUser" [group]="selectedGroup"></cometchat-message-composer>
+    </main>
+    <ng-template #empty><div class="cc-empty">Select a conversation</div></ng-template>
+  </div>
+</cometchat-error-boundary>
+```
+
+```css
+/* chat.component.css — the shell MUST be sized or the list collapses to 0px. `.cc-fill`
+   (flex: 1; min-height: 0) is REQUIRED on every kit list (-conversations/-users/-groups/
+   -call-logs/-search/-message-list): each resolves an internal height:100% to its own
+   overflow-y:auto region and does not size itself. <cometchat-error-boundary> ships NO :host
+   rule (verified vs 5.1.0), so size it too. Full rationale: `references/layout.md`. */
+cometchat-error-boundary { display: flex; flex-direction: column; flex: 1; min-height: 0; overflow: hidden; }
+/* The kit themes its OWN surfaces only — without this your own regions stay browser-white. */
+html, body { height: 100%; margin: 0;
+  background: var(--cometchat-background-color-01);
+  color: var(--cometchat-text-color-primary); }
+
+.cc-shell { display: flex; height: 100dvh; width: 100%; min-height: 0; overflow: hidden; }
+.cc-side  { width: 320px; min-height: 0; overflow: hidden; display: flex; flex-direction: column; border-right: 1px solid var(--cometchat-border-color-default); }
+.cc-fill  { flex: 1; min-height: 0; overflow: hidden; }
+.cc-main  { flex: 1; display: flex; flex-direction: column; min-height: 0; overflow: hidden; }
+.cc-empty { flex: 1; display: grid; place-items: center; color: var(--cometchat-text-color-secondary); }
+```
+
+`html, body { height: 100%; margin: 0; }` is required — an unprepared ancestor chain collapses the kit. Full sizing rules, thread/search wiring and the mobile one-pane fallback: `references/layout.md`.
+
+## Deep references (load ONLY when the task needs them)
+| File | Load when |
+| --- | --- |
+| `references/lifecycle.md` | init/login ordering, guarded login, `loggedInUser$`, logout, route guards |
+| `references/setup-credentials.md` | dashboard steps, environment files, production auth tokens |
+| `references/layout.md` | sizing, collapse, thread/search panels, responsive |
+| `references/component-props.md` | inputs/outputs beyond the golden path, content projection |
+| `references/theming.md` | CSS variables, brand colours, dark mode, following the OS theme |
+| `references/anti-patterns.md` | "it compiles but does nothing" failures |
+| `references/troubleshooting.md` | symptom → cause → fix |
+| `references/dependencies.md` | versions, peers, Angular support matrix |
+| `references/docs-map.md` | anything not baked here — component docs + SDK fallback |
+
+## Common pitfalls (top 4 — full list in `references/anti-patterns.md`)
+1. **Component missing from `imports: []`** → renders nothing, silently.
+2. **Unsized ancestor chain** → the message list collapses to zero height.
+3. **No `ngOnDestroy` teardown** → RxJS subscriptions and CometChat listeners leak on every route change.
+4. **Async SDK callbacks don't repaint** → messages arrive but the view never updates. Angular v21 is **zoneless by default**, so `NgZone.run()` is a no-op for CD — write to a **signal** or call `ChangeDetectorRef.markForCheck()` (see `lifecycle.md`).
+
+## Verify it works
+`ng serve`, then confirm: conversations list renders with data · clicking one opens header+list+composer · **clicking a GROUP conversation works too** (not just 1:1) · sending a message appears immediately · a second browser receives it live · no console errors · nothing collapsed to zero height · **OS set to dark renders dark** (`document.documentElement.getAttribute('data-theme')` is `"dark"`, not `null`) · **`ng build` (PRODUCTION config) succeeds** — see the budget note in Install.
+
+## Explain what you built (REQUIRED close)
+Tell the developer: which files changed, where credentials live and that the Auth Key is dev-only, that components must stay in `imports: []`, and what to run next.
+
+**Then state the SCOPE BOUNDARY explicitly — do not leave it implied:**
+> *"This is the core chat surface: a conversation list beside the message pane. It does **not** include a users / groups / calls tab selector, a details or thread side panel, search, or voice/video calling — say the word and I'll add any of them."*
+
+Without this the developer cannot tell a deliberate default from an incomplete build.
+
+**Then offer these THREE options as a SELECTABLE choice and WAIT for the pick — never auto-continue (`RULES.md` §19):**
+
+- **① Add another feature** → **check what is already wired FIRST, then suggest only the gap.** Read the code you just emitted, and **ASK** which dashboard-gated items are already on (per-app dashboard state can't be read reliably — never assume off). Suggest 3–4 from the grow-set in `features.angular-v5.json`: voice/video **calls** (`npm-package`) · **push** / **AI** smart replies · starter · summary (`dashboard-toggle`) · **polls · stickers · translation · pin · save** (`dashboard-extension`) · **threads · search · custom message types** (`code-prop`). **Never suggest an `auto` entry** — reactions, mentions, receipts, typing and media are core in v5 and already on; offer to customize instead. Then route to `-features` / `-calls` / `-push`.
+- **② Customize theming** → ask whether they have a preset/brand theme (brand colour, light/dark, match an existing design system) or want to talk it through, then wire it (→ `cometchat-angular-v5-customization`).
+- **③ Test it manually** → do NOTHING further — hand back so the user runs and checks it themselves. (`cometchat-angular-v5-testing` covers what to mock; `-production` covers hardening before ship.)