@cometchat/skills 4.4.2 → 5.0.0

package/skills/cometchat-angular-v5-core/references/setup-credentials.md

@@ -0,0 +1,137 @@
+# Setup & credentials
+
+## 1. Reuse before asking
+A prior `.cometchat/config.json`, or an `environment.ts` that already has a non-empty `appId` → reuse it. Skip re-provisioning and do not re-ask.
+
+## 2. Credentials — OFFER the dashboard fetch, don't default to manual paste
+When credentials are missing, present **both** paths and default to the fetch:
+
+> *"I can fetch your App ID / Region / Auth Key by logging into your CometChat dashboard (I'll load the CometChat CLI to do it), or you can paste them manually — which do you prefer?"*
+
+**Never silently skip to "paste them yourself", and never end the build with a "to finish, add credentials manually" TODO.** Only load the CLI if the user picks the fetch; a manual paste never touches it.
+
+### The CLI — dashboard/API client only, loaded on demand
+`@cometchat/skills-cli` does four things: `auth` (dashboard login), `provision` (fetch App ID/Region/Auth Key), `config`, and `features <list|enable|disable|ai-key>` (toggle dashboard extensions + AI) — §7 below uses that fourth one. It knows nothing about Angular, does **not** write env files, detect the project, or generate code — the SKILL owns all of that.
+
+Load it on demand from public npm (`@3` pins the CLI major that matches the v5 skills):
+```bash
+npx @cometchat/skills-cli@3 <cmd>
+```
+No auth needed.
+
+### Fetch path (user opted in)
+Let each command finish — do not background or race them. `<cli>` = the full invocation above.
+
+1. **Check auth:** `<cli> auth status --json` → `logged-in` | `logged-out`.
+2. **Log in if needed:** `<cli> auth login` — opens the dashboard in a browser, polls, stores the bearer in the OS keychain. Surface terminal errors verbatim (`ACCESS_DENIED` / `EXPIRED` / `TIMEOUT` / `ABORTED`) and stop; do not retry silently.
+> **If the browser is NOT already signed in to the dashboard — tell the user this BEFORE running the command.** `auth login` opens a URL carrying a one-time device-session id and then polls for up to **15 minutes**. If the browser is signed out, the dashboard redirects to its login page, and after signing in it drops the user on the dashboard home — **not back at the authorization URL**. The session is never authorized, the CLI polls until `TIMEOUT`, and it looks like "login worked but the CLI still can't see my apps".
+>
+> Say this up front: *"A browser window will open. If you're asked to sign in, sign in — then come back and open that same URL again (I'll print it). The CLI keeps waiting for up to 15 minutes."*
+>
+> - **Do NOT kill the command** while the user signs in — it is still polling, and re-running it invalidates the previous session id.
+> - On `TIMEOUT` the CLI re-prints the URL. Opening it again while signed in completes immediately; that is the recovery, not a re-login.
+> - `ALREADY_AUTHENTICATED` means the session id was already consumed — run `auth status` before assuming failure; you may already be logged in.
+
+3. **Pick the app — reuse first, ask with CURATED options, never auto-create.** `<cli> provision list --json` returns the raw list; the SKILL decides how to present it. Rank by relevance (technology matching Angular, then most recent) and offer at most 4: the **top 3** (name · region · App ID) plus **"Show all N apps"**. The free-text/"Other" answer is the manual-paste path. Only list everything if they pick "show all". **Never dump 29 apps as the primary prompt.** Never create an app unprompted; zero apps → ask first.
+4. **Fetch:** `<cli> provision use --app-id "<id>" --json` returns `{ appId, region, authKey }` and writes a framework-neutral `.cometchat/config.json`. It writes no env file. Treat the Auth Key as a secret — never echo it back.
+
+### Manual path
+Dashboard → your app → **Credentials** → App ID, Region (`us` / `eu` / `in`), Auth Key (**dev only**). If neither path yields them, ASK and WAIT — never proceed with placeholders.
+
+## 3. Write the config — Angular's shape
+Angular resolves config at **build time** via file replacement. There is no `.env` and no bundler prefix.
+
+```ts
+// src/environments/environment.ts
+export const environment = {
+  production: false,
+  cometchat: { appId: 'APP_ID', region: 'REGION', authKey: 'AUTH_KEY' },
+};
+```
+```ts
+// src/environments/environment.prod.ts — no authKey in production
+export const environment = {
+  production: true,
+  cometchat: { appId: 'APP_ID', region: 'REGION', authKey: '' },
+};
+```
+```json
+// angular.json → the production configuration
+"fileReplacements": [
+  { "replace": "src/environments/environment.ts",
+    "with": "src/environments/environment.prod.ts" }
+]
+```
+Angular 15+ omits `src/environments/` from the scaffold — create it if absent.
+
+## 4. ⚠️ After writing credentials, GITIGNORE the file (required step)
+This is the Angular-specific trap, and it is worse than React's. A `.env` at least looks like a secret and many scaffolds ignore it. `src/environments/environment.ts` is **ordinary source that Angular's scaffold commits by default** — so the moment you write a real Auth Key into it, the developer's next `git commit -a` publishes a credential that can mint a session for **any user in the app**.
+
+Shipping the file empty is right, but it does not solve this: the file becomes dangerous exactly when the skill does its job. So writing credentials and securing the file are **one action**, not two.
+
+Do this immediately after writing the values:
+
+1. **Add it to `.gitignore`:**
+   ```
+   /src/environments/environment.ts
+   ```
+2. **Commit a template instead** so a fresh clone still builds — without it the build fails with `Cannot find module '../environments/environment'`:
+   ```ts
+   // src/environments/environment.example.ts  (tracked, empty)
+   export const environment = {
+     production: false,
+     cometchat: { appId: '', region: '', authKey: '' },
+   };
+   ```
+3. **Tell the developer** the file is now ignored and that a new clone must copy the example across.
+4. **Check whether it was already tracked** — `git ls-files --error-unmatch src/environments/environment.ts`. If it was, `git rm --cached` it as part of the same change, or the ignore rule does nothing.
+
+> **Divergence from the docs.** `{DOCS_BASE}/ui-kit/angular/integration.md` shows the same `environment.ts` shape used here, but says nothing about the file being tracked or about gitignoring it. That is an omission, not permission — the guide is showing you where config goes, not making a security claim. Perform the steps above regardless.
+
+`environment.prod.ts` stays **tracked**, with **`appId` and `region` POPULATED** and only
+`authKey` empty. App ID and Region are not secrets — they identify the app; the Auth Key is
+the secret, and production mints a per-user token server-side instead
+(`cometchat-angular-v5-production`).
+
+> ⚠️ **Leaving `appId`/`region` empty produces a build that succeeds and then does nothing.**
+> `ng build` is green, but at runtime `main.ts`'s credential guard throws before
+> `bootstrapApplication`, so `app-root` stays empty and the page is blank — with the thrown
+> message visible only in the console. "The production build passed" is not evidence the
+> artifact boots: serve `dist/` and confirm the conversation list actually renders.
+
+**CI injection** — writing the file from CI secrets at build time — is a fine addition, but it is not an alternative: it does nothing for the local file the skill just wrote.
+
+**If an Auth Key was already committed, it must be ROTATED in the dashboard.** Deleting it in a later commit does not help; it is in the history and in every clone.
+
+## 5. Verify before building anything
+```ts
+const { appId, region, authKey } = environment.cometchat;
+if (!appId || !region || !authKey) {
+  throw new Error('CometChat credentials empty — check src/environments/environment.ts.');
+}
+```
+Failing loudly here saves a long debug session: without it, init rejects and every list renders empty with no obvious cause. An empty credential otherwise surfaces later as a cryptic `ERROR_API_KEY_NOT_FOUND`. A failure on init or login is most often a **Region mismatch** — re-check the dashboard value.
+
+## 6. Which UID to log in as — do NOT invent one
+`login(uid)` authenticates as a user that **must already exist**; it does not create one. Logging in as a missing UID fails and the screen stays blank.
+
+- **Never suggest a remembered "classic sample" UID** — `superhero1`, `cc-user-*` and similar are not seeded in modern apps and only mislead.
+- The only tentative suggestion allowed is `cometchat-uid-1..5`, and only labelled *"if this is a freshly-created app"* — never presented as known-good for this app.
+- **Ask the user.** Dashboard → your app → **Users** lists every UID. Prefer their answer over any suggestion.
+- **When no UID is known, do not guess — use create-if-missing.** `ensureDevUser()` in `lifecycle.md` calls `CometChatUIKit.createUser()` then logs in, which is valid on any app without probing. Dev only; production uses a server-minted token.
+
+## 7. Dashboard-gated features
+Extensions and AI features are dashboard toggles. The CLI can flip them (`<cli> features list`, `<cli> features enable <id>`), or do it in the dashboard. Either way you still wire any client component — see `cometchat-angular-v5-features`.
+
+## 8. Production
+Mint a per-user **auth token** from your backend and call `loginWithAuthToken` — never ship the Auth Key to the browser. See `cometchat-angular-v5-production`.
+
+## Checklist
+- [ ] Reused existing config if present
+- [ ] Offered dashboard fetch **and** manual paste; did not default to paste
+- [ ] `environment.ts` written; `environment.prod.ts` has an empty `authKey`
+- [ ] `fileReplacements` wired in `angular.json`
+- [ ] **`environment.ts` gitignored immediately after writing credentials**, `environment.example.ts` committed, developer told
+- [ ] If it was already tracked, `git rm --cached` applied in the same change
+- [ ] Credentials validated at startup with a thrown error
+- [ ] Login UID confirmed to exist (asked, not guessed)

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

@@ -0,0 +1,70 @@
+# Theming — CSS variables, brand, light/dark
+
+## How the kit is themed
+Everything is CSS custom properties, prefixed `--cometchat-`. Override them anywhere that cascades to the kit — usually `styles.css`.
+
+```css
+/* styles.css */
+:root {
+  --cometchat-primary-color: #6851D6;
+  --cometchat-neutral-color-300: #E8E8E8;
+  --cometchat-border-color-default: #DCDCDC;
+}
+```
+Register the kit stylesheet first (`angular.json` → `styles`), or there is nothing to override. Full token list: `{DOCS_BASE}/ui-kit/angular/customization/theming.md`.
+
+## Light / dark — ThemeService applies, but does NOT persist
+`ThemeService` (injectable, `providedIn: 'root'`) owns applying the theme: it sets a `currentTheme` signal, writes `data-theme` on `<html>` through the `DOCUMENT` token (SSR-safe), reads the OS `prefers-color-scheme` on construction, and keeps its own `matchMedia` listener so the UI follows the OS live.
+
+> ⚠️ **Its docstrings are wrong about persistence — verified against the shipped 5.1.0 code.** `initFromPreference()` claims to read `localStorage` first; `setTheme()` and `toggleTheme()` claim to persist. **The class never touches `localStorage` at all** — `applyTheme()` only sets the signal and the attribute. A manual toggle is therefore **lost on reload**. Do not repeat the docstring's claim to the developer.
+
+Follow the OS — this part works, one line at app start:
+```ts
+import { Component, inject } from '@angular/core';
+import { ThemeService } from '@cometchat/chat-uikit-angular';
+
+@Component({ selector: 'app-root', standalone: true, template: '<router-outlet />' })
+export class AppComponent {
+  constructor() { inject(ThemeService).initFromPreference(); }
+}
+```
+
+### If the user needs a manual toggle that survives reload
+Add **only** the missing persistence. Let the kit keep applying themes and watching the OS — a second `matchMedia` listener will drift from `currentTheme()`.
+
+```ts
+import { Injectable, inject, effect } from '@angular/core';
+import { ThemeService } from '@cometchat/chat-uikit-angular';
+
+const KEY = 'app.theme';
+
+@Injectable({ providedIn: 'root' })
+export class ThemePreference {
+  private theme = inject(ThemeService);
+
+  restore() {
+    const saved = localStorage.getItem(KEY);
+    if (saved === 'light' || saved === 'dark') this.theme.setTheme(saved);
+  }
+  set(next: 'light' | 'dark') {
+    localStorage.setItem(KEY, next);
+    this.theme.setTheme(next);
+  }
+  toggle() { this.set(this.theme.currentTheme() === 'dark' ? 'light' : 'dark'); }
+}
+```
+Call `restore()` once at app start, **after** `initFromPreference()`, so a stored choice wins over the OS default. Route every user-facing toggle through `set()`/`toggle()` rather than `ThemeService` directly, or the write is skipped.
+
+**Known residual, accepted:** if the OS theme changes while the app is open, the kit's own listener applies it and overrides a stored manual choice until the next reload — its "only follow system changes if the user has not set a manual preference" comment describes a check the code does not have. Fixing that from outside means racing the kit's listener, which is worse than the bug. Leave it.
+
+`CometChatUIKit.themeMode` (`'light' | 'dark'`) still exists for a one-off set without DI, but `ThemeService` is the supported path.
+
+## Scoping a theme to part of the app
+Set the variables on a wrapper rather than `:root`:
+```css
+.cc-brand-dark { --cometchat-primary-color: #1B1B1B; }
+```
+
+## Do not
+- Do not restyle kit internals with descendant selectors keyed on generated class names — they change between releases. Use the variables.
+- Do not use `!important` to win against the kit; if a variable is not taking effect, the stylesheet is not registered or your rule is not in the cascade path.

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

@@ -0,0 +1,27 @@
+# Troubleshooting — symptom → cause → fix
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Element renders nothing, no error | class not in `imports: []` | add it to that component's `imports` array |
+| `npm install` fails with `ERESOLVE` | project is on Angular 22 | scaffold with `@angular/cli@21`; peer range is `<22.0.0` |
+| Build error: path not exported by package | `@import` of the kit stylesheet | register the full `node_modules/...` path in `angular.json` `styles` |
+| Blank pane, correct markup | ancestor has no height | `html, body { height: 100% }` + `100dvh` shell + `min-height: 0` |
+| Lists render but always empty | rendering before `login()` resolved | init → login must resolve before bootstrap |
+| "Please wait until the previous login request ends." | concurrent `login()` | cache the in-flight promise (`lifecycle.md`) |
+| Config appears empty at runtime | credentials put in `.env` | Angular reads `environment.ts`, not `.env` |
+| Messages arrive but UI does not update | Async SDK callback doesn't repaint (Angular v21 is zoneless by default, so `NgZone.run()` won't help) | write to a **signal** or call `ChangeDetectorRef.markForCheck()` after the update (`lifecycle.md`) |
+| Memory grows on each route change | no teardown | `takeUntil(destroy$)` + `removeMessageListener(id)` in `ngOnDestroy` |
+| Import fails to compile | used the bare class name | use the exported `…Component` form (AI-assistant exports are the exception) |
+| Header shows one chat, messages another | `[user]`/`[group]` mismatch across components | pass the same subject to header, list and composer |
+| Clicking a conversation does not highlight it | `activeConversation` not bound | bind it to the same state that drives the message pane |
+| Reply button does nothing | thread surface not rendered | wire a thread panel or hide the affordance |
+| Dropdown or menu clipped | ancestor `overflow: hidden` or `transform` | remove it from the chain, or move the overlay root |
+| Composer off-screen on mobile | `100vh` instead of `100dvh` | use `100dvh` |
+| Layout jumps when messages load | box sizes to content | pin the height so loading and loaded share one box |
+| Calls never ring | calls SDK missing or calling not enabled | install `@cometchat/calls-sdk-javascript@^5`; check `isCallingEnabled()` |
+| Feature absent with no error | dashboard extension not enabled | enable it in the dashboard; most extensions need no client code |
+
+## When none of these fit
+1. Confirm the symbol exists — the exported name, not the docs title.
+2. Fetch the component's docs page (`docs-map.md`) and compare inputs against what you passed.
+3. Check the browser console for a CometChat error code before assuming it is a UI problem.

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

@@ -0,0 +1,94 @@
+---
+name: cometchat-angular-v5-customization
+description: "Brand and customize the CometChat Angular UI Kit — CSS variable tokens, light/dark via ThemeService, localization, date/time formats, global config, and swapping component regions with ng-template. Triggers: 'change the chat colours', 'match my brand angular', 'dark mode', 'translate the chat', 'change the date format', 'custom avatar in the list'."
+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 customization theming v5 branding dark-mode localization tokens"
+---
+
+> **Ground truth:** `@cometchat/chat-uikit-angular@5` (5.1.0–5.2.0 verified). Theme tokens, `ThemeService` and the global config are FETCHED from `{DOCS_BASE}/ui-kit/angular/customization/theming.md`, `/customization/global-config.md`, `/customization/localization.md`, `/customization/date-time-formatting.md` and `/message-bubble-styling.md` — base + paths in `cometchat-angular-v5-core/references/docs-map.md`. CSS variable names are version-pinned; never invent a token.
+
+## Companion skills (read first)
+- `cometchat-angular-v5-core` — install and `references/theming.md` for the token basics. Assumed.
+- `cometchat-angular-v5-components` — view slots, when the change is structural rather than visual.
+
+## Use this skill when
+Changing how the kit **looks or reads**: colours, fonts, dark mode, language, date formats, or replacing a region's markup.
+
+## Pick the smallest lever
+| Want | Use | Cost |
+| --- | --- | --- |
+| Different colours / spacing | CSS variables | one stylesheet |
+| Light ↔ dark | `ThemeService` | one line |
+| Different language | `CometChatLocalize` | config |
+| Different date format | per-component `*DateTimeFormat` inputs | one input |
+| Different markup in a region | `*View` slot + `ng-template` | a template |
+| Different behaviour | not customization — see `features` or `components` | — |
+
+Reach for the first that works. Replacing a whole region to change a colour throws away selection, presence and receipts.
+
+## CSS variables
+Every visual is a `--cometchat-*` custom property. Override wherever it cascades — usually `styles.css`.
+```css
+:root {
+  --cometchat-primary-color: #6851D6;
+  --cometchat-border-color-default: #DCDCDC;
+  --cometchat-text-color-primary: #141414;
+}
+```
+Scope to part of the app by setting them on a wrapper instead of `:root`. Full token list: `{DOCS_BASE}/ui-kit/angular/customization/theming.md`.
+
+Never target generated class names with descendant selectors — they change between releases. Never use `!important`; if a token is not applying, the kit stylesheet is not registered (`angular.json` → `styles`) or your rule is not in the cascade path.
+
+## Light / dark — ThemeService does it all
+```ts
+import { Component, inject } from '@angular/core';
+import { ThemeService } from '@cometchat/chat-uikit-angular';
+
+@Component({ selector: 'app-root', standalone: true, template: '<router-outlet />' })
+export class AppComponent {
+  constructor() { inject(ThemeService).initFromPreference(); }
+}
+```
+That single call respects the OS `prefers-color-scheme`, applies `data-theme` to `<html>` via the `DOCUMENT` token (SSR-safe), and keeps its own `matchMedia` listener so the UI follows the OS live.
+
+> ⚠️ **It does NOT persist, despite its docstrings.** Verified against shipped 5.1.0: `initFromPreference()` claims to read `localStorage` first and `setTheme()`/`toggleTheme()` claim to persist, but the class never touches `localStorage` — a manual toggle is lost on reload. If the user needs a toggle that survives reload, add persistence **around** the service (`cometchat-angular-v5-core/references/theming.md`) rather than replacing it; a second `matchMedia` listener will drift from `currentTheme()`.
+
+Toggle: `themeService.toggleTheme()` — do not compute the next value yourself. Set a specific mode: `themeService.setTheme('dark')`. Read: `themeService.currentTheme()` — a signal, so it works directly in templates.
+
+> **Divergence from the docs.** `{DOCS_BASE}/ui-kit/angular/customization/theming.md` documents `setTheme()`, `toggleTheme()` and setting `data-theme` by hand, but does **not** mention `initFromPreference()` or following the OS `prefers-color-scheme`. `initFromPreference()` is real and verified against the installed 5.1.0 kit — prefer it over a hand-written `matchMedia` listener. Do not "correct" it away because the guide omits it; the omission is a docs gap, not evidence the method is wrong.
+
+> Do **not** hand-roll a `matchMedia('(prefers-color-scheme: dark)')` listener. That is the React recipe; React's kit cannot read the OS. Angular's can, and duplicating it creates state that drifts from `currentTheme()`.
+
+## Localization
+`CometChatLocalize` ships 19 languages. Set the language once at startup; the `TranslatePipe` and `getLocalizedString()` read from it. To override individual strings or add a language, fetch `{DOCS_BASE}/ui-kit/angular/customization/localization.md` — the override shape is version-specific and worth reading rather than guessing.
+
+## Date & time formats
+Per-component inputs, not global CSS: `lastMessageDateTimeFormat` (conversations), `messageSentAtDateTimeFormat` (search), `callInitiatedDateTimeFormat` (call logs), `lastActiveAtDateTimeFormat` (message header). Pipes `CalendarDatePipe`, `MessageDatePipe` and `ConversationDatePipe` are exported if you need the same formatting in your own markup.
+
+## Global config
+`COMETCHAT_GLOBAL_CONFIG` is an injection token for app-wide kit defaults. Prefer it over repeating the same input on every component instance. Details: `{DOCS_BASE}/ui-kit/angular/customization/global-config.md`.
+
+## Structural changes
+Replacing markup rather than styling it is a **view slot** — `itemView`, `titleView`, `subtitleView`, `leadingView`, `trailingView`, `headerView`, `emptyView`, `errorView`, `loadingView`. See `cometchat-angular-v5-components`. Override the smallest slot that does the job.
+
+## Common pitfalls
+1. **Hand-rolling OS theme detection** — `ThemeService.initFromPreference()` already does it.
+2. **Replacing `itemView` for a colour change** — loses selection, presence and receipts.
+3. **Styling generated class names** — breaks on the next kit release.
+4. **`!important` wars** — the stylesheet is not registered, or the rule is out of cascade.
+5. **Two theme sources** — `ThemeService` plus your own `data-theme` writer; they drift.
+
+## Verify it works
+Brand colours apply in both themes · dark mode survives a reload ONLY if you persisted the choice yourself (the kit does not — see the warning above); without that, a reload falls back to the OS setting · the OS theme is respected on first load · localized strings render · overridden regions keep click, presence and receipts working.
+
+## Explain what you built (REQUIRED close)
+Tell the developer what changed, naming the files: what you themed — which tokens changed and whether light/dark follows the OS. Flag anything dev-only as dev-only, and say what you did **not** touch — this is additive.
+
+**Then offer these THREE options as a SELECTABLE choice and WAIT for the pick — never auto-continue (`RULES.md` §19):**
+1. **Add another feature** → a feature from `features.angular-v5.json`, or deeper structural customization via view slots. **Never offer an `auto` entry** (reactions, mentions, receipts, typing, media) — those are core in v5 and already on.
+2. **Add a feature** (search, calls, polls, AI) → `cometchat-angular-v5-features`.
+3. **Test it manually** → do nothing further; hand back so the user runs it.

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

@@ -0,0 +1,107 @@
+---
+name: cometchat-angular-v5-features
+description: "Enable or build any CometChat feature in an Angular app, and say which need zero client code. Covers: reactions · mentions · threaded replies · search · read receipts · typing indicators · presence · media & file attachments · voice notes · polls · stickers · GIFs · message translation · link preview · thumbnails · pin message · save / bookmark messages · reminders · message shortcuts · voice transcription · rich media preview · URL shortener · collaborative whiteboard & document · disappearing messages · support desk integrations · AI smart replies, conversation starter, summary and assistant · voice & video calling · push notifications · notification feed · moderation & reporting · campaigns · custom message types · text formatters & rich text · card messages. Triggers: 'add polls angular', 'enable reactions', 'let users save/bookmark messages', 'pin a message', 'add smart replies', 'turn on translation', 'add stickers or GIFs', 'send a custom message type', 'enable an extension angular'."
+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 features v5 extensions ai reactions polls stickers translation"
+---
+
+> **Ground truth:** the feature existence oracle is `features.angular-v5.json` (pack root). A feature a user asks for MUST be an `id` there — if it is not listed it does not exist; do not invent it. Exact enablement steps and payloads are FETCHED from each entry's `docs_topic` (a PATH — resolve it against `DOCS_BASE` in `cometchat-angular-v5-core/references/docs-map.md`). UI component names come from the `angular-v5` catalog.
+
+## Companion skills (read first)
+- `cometchat-angular-v5-core` — install, credentials, `init→login→render`. Assumed, never restated.
+- `cometchat-angular-v5-components` — component names, inputs/outputs, slots.
+
+## Use this skill when
+Someone asks to add or enable a capability: "add polls", "enable reactions", "turn on smart replies".
+
+## FIRST — classify the request
+Most features need **no client code at all**. Writing some is the most common mistake here.
+
+| Class | What you do | Examples |
+| --- | --- | --- |
+| **Already on** | Nothing. Confirm and show where it appears. | reactions, mentions, receipts, typing, media attachments, voice notes |
+| **Dashboard extension — zero code** | Enable in the dashboard. Nothing else — the kit either mounts a dedicated bubble component or renders it inline automatically. | polls, stickers, collaborative whiteboard, collaborative document, message translation, link preview, thumbnail generation |
+| **Dashboard extension — HOST-COMPOSED** | Enable in the dashboard, **then you build the UI**: `CometChat.callExtension()` to send/fetch, your own component to render. The dashboard toggle alone does nothing visible. | pin message, save message, message shortcuts, voice transcription, rich media preview, GIFs, reminders, URL shortener, disappearing messages, support integrations |
+| **Dashboard + AI** | Enable in the dashboard, then optionally place a component. | smart replies, conversation starter, conversation summary, AI assistant |
+| **Client code** | Real wiring. | threads, search, custom message types, text formatters, rich text, calls |
+
+**10 of the 17 extensions are host-composed — nearly two-thirds.** `needs_stitching: true` in `features.angular-v5.json` is the authoritative signal (not `ui_components`: three zero-code entries — message translation, link preview, thumbnail generation — legitimately have `ui_components: []` because they render inline into an existing bubble/menu rather than through a separately-importable component). Verify against `needs_stitching` before answering, never from memory or from this table's examples alone.
+
+Ask which app in the dashboard before telling someone to toggle something.
+
+## Already on by default — do NOT "add" these
+`reactions` · `mentions` · delivery/read receipts · typing indicators · media & file attachments · voice notes.
+
+These are **core in v5, not extensions**. Angular's extensions page does not list reactions or mentions, which confirms it. If one is not visible the cause is a missing `@Input()` or an unsized container — not a missing feature. Never write a reaction picker or typing indicator by hand.
+
+## Dashboard extensions — enabling is necessary, NOT always sufficient
+Dashboard → your app → Extensions → enable. Then **check the running app**, because there are two kinds:
+
+**Auto-rendered — emit nothing.** The kit surfaces these itself once enabled: polls, stickers, collaborative document/whiteboard (bubbles in the message list), link preview and thumbnails (inside the bubble), message translation (an entry in the message menu).
+
+**Host-composed — the kit renders NO affordance.** Enabling them changes nothing visible; you must call the extension and render your own control:
+
+```ts
+import { CometChat } from '@cometchat/chat-sdk-javascript';
+
+// SEND — exact slug, endpoint and payload are on the extension's own docs page
+await CometChat.callExtension('pin-message', 'POST', 'v1/pin', { msgId, receiverType });
+```
+**Send is only a third of the job.** You also need to FETCH the pinned/saved list back and RENDER it — full pattern, incl. the type-safe way to turn a fetched entry into displayable text: `references/host-composed-extensions.md`.
+
+Currently host-composed in Angular (10): **pin message · save message · message shortcuts · voice transcription · rich media preview · GIFs · reminders · URL shortener · disappearing messages · support integrations.** `needs_stitching: true` in `features.angular-v5.json` is the authoritative signal — not `ui_components`, see the table above.
+
+> **Do not conclude a feature "does not exist" because the kit has no component and the SDK has no named method for it.** Extensions are reached through the generic `CometChat.callExtension()` — there is no `pinMessage()` to grep for. Searching `node_modules` for the SEND/FETCH calls will find nothing and that is expected.
+
+> **`docs_topic` is a PATH, not a URL.** Prefix it with `DOCS_BASE` from `cometchat-angular-v5-core/references/docs-map.md`, then append `.md`:
+> `{DOCS_BASE}` + `/fundamentals/pin-message` + `.md`
+> Do **not** hardcode `https://www.cometchat.com/docs/...`. `DOCS_BASE` may point at a docs preview while a docs change is in flight, and a hardcoded production URL silently reads the pre-change page — so you would fetch a page that is missing the very detail you were sent to find.
+
+Available (from Angular's extensions page): Bitly · Link Preview · Message Shortcuts · Pin Message · Rich Media Preview · Save Message · Thumbnail Generation · TinyURL · Voice Transcription · Giphy · Message Translation · Polls · Reminders · Stickers · Stipop · Tenor · Collaborative Document · Collaborative Whiteboard · Disappearing Messages · Chatwoot · Intercom.
+
+Two have a bubble you may reference when customizing, but you still do not mount them yourself: `CometChatPollBubbleComponent`, `CometChatStickerBubbleComponent`.
+
+**Not available for Angular:** end-to-end encryption, live streaming, email replies. They exist for other platforms. Say so plainly rather than improvising.
+
+## AI features
+Enable in the dashboard (AI section), then place the component you need:
+```html
+<cometchat-smart-replies></cometchat-smart-replies>
+<cometchat-conversation-starter></cometchat-conversation-starter>
+<cometchat-conversation-summary></cometchat-conversation-summary>
+```
+`<cometchat-message-list>` also emits `smartReplyClick` and `conversationStarterClick` when those are enabled, so the built-in surfaces work without extra components. The AI assistant is `CometChatAIAssistantChat` — no `Component` suffix.
+
+## Features that DO need code
+| Feature | Where |
+| --- | --- |
+| Threaded replies | `cometchat-angular-v5-placement` — thread panel |
+| Search | `cometchat-angular-v5-placement` — search column |
+| Custom message types | `references/custom-messages.md` |
+| Text formatters / rich text | `references/formatters.md` |
+| Voice & video calls | `cometchat-angular-v5-calls` |
+| Push notifications | `cometchat-angular-v5-push` |
+
+## Common pitfalls
+1. **Building a feature that is already on** — hand-rolled reaction pickers are the classic. Check the "already on" list first.
+2. **Assuming every extension is zero-code** — 10 of them render no affordance and need `CometChat.callExtension()`. Equally, do not write code for the auto-rendered ones.
+3. **Declaring a feature absent because `node_modules` has no method for it** — extensions have no named SDK method; they go through the generic `callExtension()`. Check the extension's docs page before saying it is unsupported.
+4. **Re-implementing a server-side feature in the browser** — `localStorage`, an in-memory `Map`, or a local `BehaviorSubject` where an extension exists. Saved/pinned messages, reminders and shortcuts are stored **server-side and are per-user across devices**; a browser-local copy does not sync to the user's phone and dies with the cache. If a request is about remembering something *about a message*, check `features.angular-v5.json` before writing storage of your own.
+5. **Offering a feature Angular does not have** — E2E encryption, live streaming, email replies.
+6. **Forgetting the dashboard step** — the code is right, the feature is off, and it looks broken.
+7. **Treating reactions/mentions as extensions** — they are core in v5.
+
+## Verify it works
+The feature appears in a real conversation · you wrote no code for a dashboard-only feature · the dashboard toggle is on for the app the credentials point at.
+
+## Explain what you built (REQUIRED close)
+Tell the developer what changed, naming the files: the feature you just enabled (and whether it needed a dashboard toggle). Flag anything dev-only as dev-only, and say what you did **not** touch — this is additive.
+
+**Then offer these THREE options as a SELECTABLE choice and WAIT for the pick — never auto-continue (`RULES.md` §19):**
+1. **Add another feature** → another grow-set feature from `features.angular-v5.json` that is NEITHER wired NOR already enabled — ASK about dashboard state rather than assuming. **Never offer an `auto` entry** (reactions, mentions, receipts, typing, media) — those are core in v5 and already on.
+2. **Customize theming** → `cometchat-angular-v5-customization`.
+3. **Test it manually** → do nothing further; hand back so the user runs it.

package/skills/cometchat-angular-v5-features/references/custom-messages.md

@@ -0,0 +1,133 @@
+# Custom message types
+
+Angular v5 has **no plugin architecture** — `CometChatMessagePlugin` / `CometChatPluginRegistry` are React v7 symbols and do not exist here. A custom type is three separate concerns: send it, make the list fetch it, render it.
+
+## 1. Send — plain SDK
+```ts
+import { CometChat } from '@cometchat/chat-sdk-javascript';
+
+async function sendOrderUpdate(receiverId: string) {
+  const msg = new CometChat.CustomMessage(
+    receiverId,
+    CometChat.RECEIVER_TYPE.USER,
+    'order_update',                       // your type key
+    { orderId: 42, status: 'shipped' },
+  );
+  await CometChat.sendCustomMessage(msg);
+}
+```
+
+> ⚠️ **The sender will not see this message until they refresh — unless you publish it.** `<cometchat-message-list>`/`<cometchat-conversations>` render from an internal store that `<cometchat-message-composer>` updates for you on every normal send. A raw SDK call bypasses the composer entirely, so nothing tells the currently-mounted list a message now exists — the SDK real-time listener that would otherwise deliver it does **not** echo a message back to its own sender. This is not specific to custom types: **any message sent by calling the SDK directly instead of through the composer needs this**, including the plain-text reply from a host-composed extension's affordance (`references/host-composed-extensions.md`) or from `custom-messages.md`'s own update path below.
+>
+> Publish it through the kit's own event bus so its list picks it up exactly as if the composer had sent it — verified against the installed 5.1.0 kit: `publishMessageSent(data: IMessages)`, where `IMessages = { message: CometChat.BaseMessage; status: MessageStatus; parentMessageId?: number | null }`. Pass the object, not the bare message — a bare message silently fails the shape the list expects. `CometChatMessageEvents.ccMessageSent` (a raw `Subject`) is the same underlying event but is `@deprecated` in favour of this typed method — do not `.next()` it directly in new code.
+
+```ts
+import { CometChatMessageEvents, MessageStatus } from '@cometchat/chat-uikit-angular';
+
+function announceSent(msg: CometChat.BaseMessage) {
+  CometChatMessageEvents.publishMessageSent({ message: msg, status: MessageStatus.success });
+}
+```
+
+## 2. Make the list FETCH it
+`<cometchat-message-list>` fetches only the default types unless told otherwise. Your custom type is silently absent until you widen the request — this is the step people miss.
+
+The kit exports the defaults so you extend rather than replace them:
+```ts
+import { CometChat } from '@cometchat/chat-sdk-javascript';
+import { DEFAULT_MESSAGE_TYPES, DEFAULT_MESSAGE_CATEGORIES } from '@cometchat/chat-uikit-angular';
+
+class ChatComponent {
+  readonly messagesRequestBuilder = new CometChat.MessagesRequestBuilder()
+    .setTypes([...DEFAULT_MESSAGE_TYPES, 'order_update'])
+    .setCategories([...DEFAULT_MESSAGE_CATEGORIES, CometChat.CATEGORY_CUSTOM])
+    .setLimit(30);
+}
+```
+```html
+<cometchat-message-list [user]="activeUser()" [messagesRequestBuilder]="messagesRequestBuilder"></cometchat-message-list>
+```
+Both constants are `readonly string[]`. Spreading them keeps every built-in type working — hardcoding a list instead is how text messages disappear.
+
+## 3. Render it — `MessageBubbleConfigService.setBubbleView()`
+Register a template against your type key. This is the documented API — do **not** reach for `[listItemTemplate]`, and do not reverse-engineer the bubble internals.
+
+> ⚠️ **The key is `{type}_{category}` — NOT your bare type.** A custom `location` message registers under **`location_custom`**, because its category is `custom`. This trips everyone: `setBubbleView('location', …)` is accepted silently, never matches, and the bubble renders the kit's fallback **"This message type is not supported."** — which reads like a missing feature rather than a key typo. Built-in keys follow the same rule (`text_message`, `image_message`). Verified against the kit: `type MessageTypeKey` — *"Format: `{type}_{category}`"*.
+
+```ts
+import { Component, ViewChild, TemplateRef, inject, AfterViewInit } from '@angular/core';
+import { MessageBubbleConfigService } from '@cometchat/chat-uikit-angular';
+
+@Component({ /* … */ })
+export class ChatComponent implements AfterViewInit {
+  @ViewChild('locationBubble', { static: true }) locationBubble!: TemplateRef<unknown>;
+  private bubbleConfig = inject(MessageBubbleConfigService);
+
+  ngAfterViewInit() {
+    this.bubbleConfig.setBubbleView('location_custom', { contentView: this.locationBubble });
+  }
+}
+```
+```html
+<ng-template #locationBubble let-message>
+  <div class="location-card">{{ message?.getCustomData()?.label }}</div>
+</ng-template>
+```
+
+**Register only the parts you want to change; unregistered parts keep their defaults:**
+
+| Slot | Replaces |
+| --- | --- |
+| `contentView` | the message content — the usual choice for a custom type |
+| `bubbleView` | the entire bubble, losing the built-in frame |
+| `headerView` · `footerView` · `statusInfoView` | partial overrides around the content |
+
+Prefer `contentView`: replacing `bubbleView` discards timestamps, receipts, reactions and thread affordances that the default frame provides.
+
+Full guide, including the type-key rules: `{DOCS_BASE}/ui-kit/angular/guides/custom-message-types.md`.
+
+## 4. Updating a custom message after it was sent — location sharing, live status
+Some custom types change after sending — a live location marker that moves, a poll-style status that ticks over. Do **not** reach for `sendTransientMessage()` for this: transient messages are explicitly *"not saved or tracked anywhere"* and only reach a receiver who is online at that instant (verified against `{SDK_DOCS_BASE}/sdk/javascript/transient-messages.md`) — a location share sent this way vanishes from chat history and never reaches an offline recipient. That is wrong for anything that must persist as a message.
+
+**The documented mechanism is `CometChat.editMessage()`** — it accepts a `TextMessage` **or a `CustomMessage`** (`{SDK_DOCS_BASE}/sdk/javascript/edit-message.md`):
+```ts
+import { CometChat } from '@cometchat/chat-sdk-javascript';
+
+async function updateLocation(message: CometChat.CustomMessage, lat: number, lng: number) {
+  message.setCustomData({ ...message.getCustomData(), lat, lng });
+  await CometChat.editMessage(message);   // returns the updated BaseMessage
+}
+```
+Keep the `CustomMessage` instance you sent (or re-fetch it with `CometChat.getMessageDetails(id)`); do not construct a fresh message for an update — `editMessage` mutates the existing one in place, it does not create a new bubble.
+
+**`editMessage()` is also a raw SDK call — the EDITOR needs the same local-echo publish as §1's send.** Without it, the person who moved the location marker will not see their own update until they refresh, even though the SDK call succeeded:
+```ts
+import { CometChat } from '@cometchat/chat-sdk-javascript';
+import { CometChatMessageEvents, MessageStatus } from '@cometchat/chat-uikit-angular';
+
+async function publishLocalEdit(updated: CometChat.BaseMessage) {
+  CometChatMessageEvents.publishMessageEdited({ message: updated, status: MessageStatus.success });
+}
+```
+
+**The receiver needs a listener, not a poll** — register `onMessageEdited` alongside your other SDK listeners (same `listenerId`/`ngOnDestroy`/repaint conventions as `cometchat-angular-v5-core/references/lifecycle.md`). Angular v21 is **zoneless by default**, so repaint by writing a **signal** (not `NgZone.run()`, which no longer triggers CD):
+```ts
+import { CometChat } from '@cometchat/chat-sdk-javascript';
+import { WritableSignal } from '@angular/core';
+
+function registerEditListener(messages: WritableSignal<CometChat.BaseMessage[]>, listenerId: string) {
+  CometChat.addMessageListener(listenerId, {
+    onMessageEdited: (message: CometChat.BaseMessage) => {
+      // update your local message store via the signal so the bubble re-renders (zoneless-safe)
+      messages.update((prev) => prev.map((m) => (m.getId() === message.getId() ? message : m)));
+    },
+  });
+}
+```
+> **Verify in your running app** whether `<cometchat-message-list>` already re-renders a visible bubble on `onMessageEdited` for you, or whether you must update your own tracked copy of the message and let Angular's change detection pick it up through the bubble's `TemplateRef` context. This is not stated in the docs either way.
+
+## What `CometChatTemplatesService` is (and is not)
+It is **not** a custom-type registry, and it is not the API above. It is a DI-based alternative to passing `*View` inputs — `setConversationItemTemplate(TemplateRef)`, `setConversationTitleTemplate(...)`, `setSharedTemplates(...)` and their `get`/`clear` pairs. Use it when the same override applies app-wide. For custom message BUBBLES use `MessageBubbleConfigService`.
+
+## If you find yourself reading the kit bundle here, stop
+The three steps above are the documented path, verified against the installed 5.1.0 kit and the live guide. If you are searching `node_modules` for `setBubbleView`, `contentView`, `effectiveContentView` or `MessageTypeKey`, you are re-deriving something the guide already states. **And if your bubble renders "This message type is not supported", the answer is not in the bundle — it is the `{type}_{category}` key above** — fetch `{DOCS_BASE}/ui-kit/angular/guides/custom-message-types.md` instead. Reading the bundle is right only for behaviour the docs genuinely omit (`cometchat-angular-v5-core/SKILL.md`), and custom-message rendering is not one of those.

package/skills/cometchat-angular-v5-features/references/formatters.md

@@ -0,0 +1,28 @@
+# Text formatters & rich text
+
+Angular's formatter surface is richer than React's and has five dedicated guides.
+
+## Built-in formatters
+`CometChatTextFormatter` (base) · `CometChatMentionsFormatter` · `CometChatUrlFormatter` · `CometChatEmojiFormatter` · `CometChatMarkdownFormatter`
+
+Mentions and URLs are **on by default**. Do not add them.
+
+## Applying formatters to a list
+Both `<cometchat-message-list>` and `<cometchat-conversations>` accept a `textFormatters` input:
+```html
+<cometchat-message-list [user]="activeUser()" [textFormatters]="formatters"></cometchat-message-list>
+```
+```ts
+import { CometChatMentionsFormatter, CometChatUrlFormatter } from '@cometchat/chat-uikit-angular';
+readonly formatters = [new CometChatMentionsFormatter(), new CometChatUrlFormatter()];
+```
+Passing `textFormatters` **replaces** the defaults for that component — include the ones you still want.
+
+## App-wide defaults
+`FormatterConfigService` sets formatters once for every text-rendering component instead of per-component. Prefer it when the same set applies everywhere.
+
+## Custom formatter
+Extend `CometChatTextFormatter`. Fetch `{DOCS_BASE}/ui-kit/angular/guides/custom-text-formatter.md` for the exact hook signatures before implementing — the guides for hashtag, shortcut, mentions and URL formatters each show a working variant.
+
+## Rich text editing
+The composer's rich text editor (bold, italic, lists, code, links, undo/redo) is backed by `RichTextEditorService` and uses native browser APIs — no external editor dependency. Guide: `{DOCS_BASE}/ui-kit/angular/guides/rich-text-formatting.md`. Do not bolt on a third-party editor; it will fight the composer's own state.