docs(ui-kit/angular): Angular v5 skills docs — LLM index + AI Integration Quick References (ENG-38204)

agent-skills.mdx

@@ -0,0 +1,293 @@
+---
+title: "Build CometChat with AI Agent Skills"
+sidebarTitle: "Agent Skills"
+description: "Install the CometChat agent skills and let your AI coding agent — Claude Code, Cursor, GitHub Copilot, Replit, and more — add production-grade chat and calling to your React or Angular app from natural-language prompts."
+canonical: "https://www.cometchat.com/docs/agent-skills"
+---
+
+**CometChat Agent Skills** teach your AI coding agent how to build with CometChat.
+Install the skills once, then open your project and say *"add chat to my app"* —
+the agent has a short conversation with you (framework, intent, placement,
+credentials), then writes production-grade integration code directly into the
+files you already have.
+
+The skills author against the official **React UI Kit v7** and **Angular UI Kit v5**
+task guides and verify their output against them, so what the agent writes builds and
+runs against the current published UI Kit — not a hallucinated API.
+
+<Note>
+The skills work **inside your existing project** with your existing agent. They
+don't scaffold a throwaway demo — they detect your setup and integrate CometChat
+into the app you're already building.
+</Note>
+
+## Prerequisites
+
+- **Node.js 18+** — the installer runs through `npx`, so there's nothing to install globally.
+- A **CometChat account** — [sign up free](https://app.cometchat.com) to get an app's App ID, Region, and Auth Key.
+- An **existing React or Angular app**:
+  - **React** 18+ — **Vite**, **Create React App**, **Next.js**, **React Router**, or **Astro**.
+  - **Angular** 17–21 — **Angular CLI** or **Nx**. (Angular 22 is not yet installable: the UI Kit's peer range is `<22.0.0`.)
+- One of the [supported AI coding agents](#supported-agents) below.
+
+<Note>
+The skills target the **React UI Kit v7** and the **Angular UI Kit v5** today. The
+installer tells you if it can't detect a supported setup — it never guesses or
+scaffolds a throwaway project. In an empty or ambiguous project the agent asks which
+framework you're building rather than assuming one.
+</Note>
+
+## Install
+
+Run the installer in your project root:
+
+```bash
+npx @cometchat/skills add
+```
+
+It detects your React or Angular setup and opens a picker to install the skills for
+the AI agent(s) you use. To pin a single agent — useful in CI or a Dockerfile — pass
+`--ide`:
+
+```bash
+npx @cometchat/skills add --ide claude    # Claude Code   → .claude/skills/
+npx @cometchat/skills add --ide cursor    # Cursor        → ./.cometchat/skills + router
+npx @cometchat/skills add --ide replit    # Replit Agent  → .agents/skills/
+npx @cometchat/skills add --ide all       # every supported agent
+```
+
+### Supported agents
+
+| Agent | Install with |
+| --- | --- |
+| Claude Code | `--ide claude` |
+| Cursor | `--ide cursor` |
+| GitHub Copilot | `--ide copilot` |
+| Windsurf | `--ide windsurf` |
+| Replit Agent | `--ide replit` |
+| Cline | `--ide cline` |
+| Codex | `--ide codex` |
+| Gemini | `--ide gemini` |
+| Continue | `--ide continue` |
+| Aider | `--ide aider` |
+| Kiro | `--ide kiro` |
+| Antigravity | `--ide antigravity` |
+
+<Note>
+Claude Code, Kiro, and Replit get a native `SKILL.md` tree. The other agents get
+an orienting router plus a `./.cometchat/skills` tree. Add `--global` (Claude
+Code, Kiro, and Replit only) to install into your user-level directory instead of
+the project.
+</Note>
+
+## Use it
+
+Open your project in your agent and prompt it:
+
+```
+add chat to my app
+```
+
+or type the dispatcher directly:
+
+```
+/cometchat
+```
+
+The `cometchat` dispatcher detects your framework and routes to `cometchat-onboarding`,
+which walks a short **discover → understand → plan → approve** flow. Once you
+approve the plan, it hands a scoped build directive to that family's `core` skill
+(`cometchat-react-v7-core` or `cometchat-angular-v5-core`) and pulls in the other
+skills as the plan needs them (components, placement, theming, features, calls, push).
+
+Keep iterating in plain language afterward:
+
+- *"Add message reactions and threaded replies."*
+- *"Switch the chat to dark mode and match my brand color."*
+- *"Add a group details side panel."*
+- *"Set up production authentication."*
+
+## Connect your credentials
+
+You don't paste your **App ID / Region / Auth Key** by hand. During the build,
+when the skill notices they're missing, it offers two paths and defaults to
+fetching them from your dashboard:
+
+- **Fetch from your dashboard (recommended)** — the skill runs the standalone
+  [CometChat CLI](/cli) for you, on demand: it opens the dashboard login in your
+  browser, lets you pick one of your **existing** apps, pulls the credentials,
+  and writes a neutral `.cometchat/config.json`. You can also run the CLI yourself
+  — it works on its own, in a script, or in CI.
+- **Paste manually** — copy App ID, Region, and Auth Key from **Dashboard → Your
+  App → Credentials** if you'd rather not log in.
+
+Either way, the **skill** then writes the framework env file (`.env` / `VITE_` /
+`NEXT_PUBLIC_` …) from those credentials — the CLI only fetches them and never
+touches your framework code.
+
+<Warning>
+**Keep credentials out of version control.** Both `.cometchat/config.json` and
+the generated env file contain your **Auth Key**. Make sure they're in
+`.gitignore` — Vite, CRA, and Astro ignore only `*.local` (not `.env`), so add
+`.env` yourself; Next.js ignores `.env.local` by default. The Auth Key is for
+**development only**: in production, mint a short-lived per-user **auth token** on
+your backend and log in with `loginWithAuthToken()` — never ship the Auth Key to
+a production client.
+</Warning>
+
+<Note>
+Prefer to drive it yourself? The credential CLI is also a standalone tool —
+`npx @cometchat/skills-cli auth login`, then `provision run`. See the
+[CLI reference](/cli) for the full command surface.
+</Note>
+
+## What's in the pack
+
+Task-shaped skills the agent loads on demand — two shared, then one set per framework:
+
+| Skill | Purpose |
+| --- | --- |
+| `cometchat` | Thin dispatcher — detect the framework and route |
+| `cometchat-onboarding` | Discover → understand → plan → approve (the front door) |
+| `cometchat-react-v7-core` | Install · credentials · init → login → render · the golden-path chat surface |
+| `cometchat-react-v7-components` | The v7 component catalog + props / slots |
+| `cometchat-react-v7-placement` | Where chat lives — full app / sidebar / popup / embed |
+| `cometchat-react-v7-customization` | Theming · brand · light/dark · view slots |
+| `cometchat-react-v7-patterns` | Vite / Next.js / React Router / Astro glue (env · SSR · routing) |
+| `cometchat-react-v7-features` | Enable a feature — reactions · polls · AI · moderation · … |
+| `cometchat-react-v7-calls` | Voice / video calling |
+| `cometchat-react-v7-push` | Web push (Notifications product) |
+| `cometchat-react-v7-migration` | Upgrade a v6 UI Kit → v7 |
+
+**Angular UI Kit v5**
+
+| Skill | Purpose |
+| --- | --- |
+| `cometchat-angular-v5-core` | Install · credentials · init → login → render · the golden-path chat surface |
+| `cometchat-angular-v5-components` | The v5 component catalog + inputs / outputs / view slots |
+| `cometchat-angular-v5-placement` | Where chat lives — chat shell · thread and details panels · routing |
+| `cometchat-angular-v5-customization` | Theming · brand · light/dark · view slots |
+| `cometchat-angular-v5-patterns` | Angular CLI / Nx glue (environments · SSR · lazy routes · RxJS) |
+| `cometchat-angular-v5-features` | Enable a feature — reactions · polls · AI · moderation · … |
+| `cometchat-angular-v5-calls` | Voice / video calling |
+| `cometchat-angular-v5-push` | Web push (Notifications product) |
+| `cometchat-angular-v5-production` | Server-minted auth tokens · hardening before you ship |
+| `cometchat-angular-v5-testing` | Testing an app that embeds CometChat |
+| `cometchat-angular-v5-troubleshooting` | Diagnosing a broken integration |
+
+## Example prompts
+
+Everything starts from one prompt — **"add chat to my app"** — then you refine in
+plain language. Example prompts, grouped by goal:
+
+**Get started**
+
+- *"Add chat to my app."* — the default: a conversation list + message view
+- *"Add 1:1 direct messaging between my users."*
+- *"Add group chat with file sharing."*
+- *"Build a full chat app with Chats, Users, and Calls tabs."*
+
+**Where chat lives**
+
+- *"Add a support chat widget in the bottom-right corner."*
+- *"Add a floating chat popup I can toggle open and closed."*
+- *"Put chat in a sidebar next to my app."*
+- *"Embed a chat panel on my dashboard page."*
+
+**Features**
+
+- *"Add message reactions, typing indicators, and read receipts."*
+- *"Add threaded replies and @mentions."*
+- *"Add image and file sharing."*
+- *"Add message search."*
+- *"Add polls and stickers."*
+
+**Calling & AI**
+
+- *"Add voice and video calling with a click-to-call button."*
+- *"Add smart replies and conversation summaries."*
+- *"Add an AI assistant to the chat."*
+- *"Turn on moderation so banned words are blocked before delivery."*
+
+**Look & feel**
+
+- *"Switch the chat to dark mode and match my brand color."*
+- *"Make the chat follow the user's system light/dark setting."*
+
+**Ship it**
+
+- *"Set up production authentication with auth tokens."*
+- *"Add web push notifications."*
+- *"Migrate my v6 UI Kit to v7."*
+
+The agent plans each change with you, then writes the integration into your
+existing files — you don't have to know the component or prop names.
+
+## Manage the skills
+
+- **Update** — re-run `npx @cometchat/skills add` to pull the latest skills; it overwrites the installed skill tree in place.
+- **Inspect** — `npx @cometchat/skills list` shows the installed skills, and `npx @cometchat/skills doctor` runs an environment health check.
+- **Uninstall** — delete the installed skill directory for your agent (for example `.claude/skills/cometchat*`, `.agents/skills/`, or `./.cometchat/skills`).
+- **Version control** — commit the skill files so your whole team shares the same setup. Do **not** commit `.cometchat/config.json` or the generated env file — they hold your Auth Key.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| The agent doesn't pick up the skills | Installed for a different agent, or a router-based agent needs pointing at the tree | Re-run `npx @cometchat/skills add --ide <your-agent>`. For router agents (Cursor, Copilot, …) open `.cometchat/skills/cometchat/SKILL.md` to orient it. |
+| Blank screen, no errors | A UI Kit component rendered before `init()` + `login()` resolved, or the wrong Region / env prefix | The `init → login → render` order is required. Check that the Region matches your dashboard app and the env prefix matches your bundler (`VITE_` / `NEXT_PUBLIC_` / `PUBLIC_`). |
+| `login()` fails — "user not found" | Logging in a UID that doesn't exist in the app | Use a UID that exists (Dashboard → your app → **Users**; fresh apps seed `cometchat-uid-1`). |
+| Auth error on init / login | Region mismatch between your code and the dashboard app | Re-check the Region (`us` / `eu` / `in`) in both the dashboard and your env file. |
+| `ERROR_API_KEY_NOT_FOUND` | An env var is empty or not picked up by the bundler | Confirm the env file uses the right prefix for your bundler, then restart the dev server. |
+| Version conflict during install | An older **v6** UI Kit is already installed | Ask the agent to migrate — the `cometchat-react-v7-migration` skill upgrades v6 → v7. |
+
+## Compatibility
+
+**React**
+
+| Dependency | Version |
+| --- | --- |
+| `@cometchat/chat-uikit-react` | `7.x` (verified 7.1.x) |
+| `@cometchat/chat-sdk-javascript` | `4.x` |
+| `@cometchat/calls-sdk-javascript` | `5.x` (calling) |
+| React | `≥ 18` |
+
+**Angular**
+
+| Dependency | Version |
+| --- | --- |
+| `@cometchat/chat-uikit-angular` | `5.x` (verified 5.1.0) |
+| `@cometchat/chat-sdk-javascript` | `^4.1.13` |
+| `@cometchat/cards-angular` | `^1.0.0` |
+| `@cometchat/calls-sdk-javascript` | `^5.0.3` (calling) |
+| `dompurify` | `^3.0.0` |
+| Angular | `≥ 17` and `< 22` |
+
+<Note>
+Angular 22 is not yet installable — the UI Kit's peer range is `>=17.0.0 <22.0.0`, so
+`npm install` fails with `ERESOLVE` on Angular 22. Scaffold with `@angular/cli@21` until
+a kit release widens the range.
+</Note>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="CLI Reference" icon="terminal" href="/cli">
+    Authenticate, provision credentials, and manage the skills from your terminal
+  </Card>
+  <Card title="MCP Integration" icon="plug" href="/mcp-server">
+    Connect CometChat to any Model Context Protocol–compatible agent
+  </Card>
+  <Card title="React Integration" icon="react" href="/ui-kit/react/integration-react">
+    The manual React UI Kit setup the skills automate
+  </Card>
+  <Card title="Angular Integration" icon="angular" href="/ui-kit/angular/integration">
+    The manual Angular UI Kit setup the skills automate
+  </Card>
+  <Card title="React Components" icon="grid-2" href="/ui-kit/react/components-overview">
+    Browse all prebuilt React components
+  </Card>
+  <Card title="Angular Components" icon="grid-2" href="/ui-kit/angular/components/components-overview">
+    Browse all prebuilt Angular components
+  </Card>
+</CardGroup>

ui-kit/angular/angular-conversation.mdx

@@ -39,7 +39,7 @@
 
 ## Step 1 — Update AppComponent
 
 Wire the conversation list and message components together in your root component. The UIKit's `ChatStateService` handles all the wiring — when a user clicks a conversation, `cometchat-conversations` updates the service, and the message components automatically react to the change.
 
 ```ts title="src/app/app.component.ts" expandable
 import { Component, inject, OnInit } from "@angular/core";
@@ -87,8 +87,10 @@
   styles: `
     :host {
       display: flex;
-      height: 100vh;
-      width: 100vw;
+      height: 100dvh;      /* dvh, not vh: 100vh includes mobile browser chrome and overflows */
+      width: 100%;
+      min-height: 0;       /* without this a flex child refuses to shrink below its content */
+      overflow: hidden;    /* the shell never scrolls — the kit's lists scroll internally */
     }
     .chat-layout {
       display: flex;
@@ -134,6 +136,14 @@
 }
 ```
 
+<Warning>
+**The shell needs `overflow: hidden`, and every flex ancestor of the message list needs `min-height: 0`.**
+
+`height: 100vh` alone is not enough. The kit's lists scroll internally, but a flex child defaults to `min-height: auto` and refuses to shrink below its content — so the message list pushes the shell past the viewport and the browser scrolls the **page** instead of the list, carrying the header and composer off-screen with it.
+
+One missing `min-height: 0` anywhere between the viewport and the message list is enough to bring the page scroll back. `100dvh` is preferred over `100vh` because `vh` units include mobile browser chrome and overflow on phones.
+</Warning>
+
 How it works:
 - `cometchat-conversations` calls `ChatStateService.setActiveConversation()` automatically when a conversation is clicked.
 - `setActiveConversation()` extracts the `User` or `Group` and sets it as the active entity, enforcing mutual exclusivity (setting a user clears the group, and vice versa).

ui-kit/angular/angular-one-to-one-chat.mdx

@@ -79,8 +79,10 @@
     .chat-window {
       display: flex;
       flex-direction: column;
-      height: 100vh;
-      width: 100vw;
+      height: 100dvh;      /* dvh, not vh: 100vh includes mobile browser chrome and overflows */
+      width: 100%;
+      min-height: 0;       /* without this a flex child refuses to shrink below its content */
+      overflow: hidden;    /* the shell never scrolls — the kit's lists scroll internally */
     }
     .empty-conversation {
       height: 100vh;
@@ -139,6 +141,14 @@
 }
 ```
 
+<Warning>
+**The shell needs `overflow: hidden`, and every flex ancestor of the message list needs `min-height: 0`.**
+
+`height: 100vh` alone is not enough. The kit's lists scroll internally, but a flex child defaults to `min-height: auto` and refuses to shrink below its content — so the message list pushes the shell past the viewport and the browser scrolls the **page** instead of the list, carrying the header and composer off-screen with it.
+
+One missing `min-height: 0` anywhere between the viewport and the message list is enough to bring the page scroll back. `100dvh` is preferred over `100vh` because `vh` units include mobile browser chrome and overflow on phones.
+</Warning>
+
 Key points:
 - `CometChat.getUser(UID)` fetches the user object from the SDK — you need a real user object, not a manually constructed one.
 - `chatStateService.setActiveUser(user)` sets the active entity — all message components auto-subscribe and render accordingly.

ui-kit/angular/angular-tab-based-chat.mdx

@@ -123,8 +123,10 @@
   styles: `
     :host {
       display: flex;
-      height: 100vh;
-      width: 100vw;
+      height: 100dvh;      /* dvh, not vh: 100vh includes mobile browser chrome and overflows */
+      width: 100%;
+      min-height: 0;       /* without this a flex child refuses to shrink below its content */
+      overflow: hidden;    /* the shell never scrolls — the kit's lists scroll internally */
     }
     .tab-layout {
       display: flex;
@@ -196,6 +198,14 @@
 }
 ```
 
+<Warning>
+**The shell needs `overflow: hidden`, and every flex ancestor of the message list needs `min-height: 0`.**
+
+`height: 100vh` alone is not enough. The kit's lists scroll internally, but a flex child defaults to `min-height: auto` and refuses to shrink below its content — so the message list pushes the shell past the viewport and the browser scrolls the **page** instead of the list, carrying the header and composer off-screen with it.
+
+One missing `min-height: 0` anywhere between the viewport and the message list is enough to bring the page scroll back. `100dvh` is preferred over `100vh` because `vh` units include mobile browser chrome and overflow on phones.
+</Warning>
+
 How it works:
 - The `activeTab` property drives which list component renders — `cometchat-conversations`, `cometchat-call-logs`, or `cometchat-users`.
 - `cometchat-conversations` calls `ChatStateService.setActiveConversation()` on click, which extracts the `User` or `Group` and sets it as the active entity.