@cometchat/skills 4.4.2 → 5.0.1

package/skills/cometchat-moderation/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: cometchat-moderation
+description: "Trust & Safety for CometChat — auto-moderate text/image/video/file with dashboard rules + keyword lists, block or flag-for-review, let users report messages, and keep an audit trail. Cross-family: rules/lists/queues are dashboard+REST; report/block UI is built into each family's UI Kit. Triggers: 'add moderation', 'profanity filter', 'image moderation', 'block bad words', 'report a message', 'flag inappropriate content', 'content safety', 'spam/scam detection', 'CSAM/minor safety', 'malware scan attachments', 'moderation queue'."
+license: "MIT"
+compatibility: "CometChat Moderation (dashboard rules/lists + Flagged/Blocked/Reviewed queues) · Moderation REST API v3 · per-family UI Kit report/block + Chat SDK flagging."
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat moderation trust-safety profanity image-moderation spam csam malware report flag audit"
+---
+
+> **Ground truth:** capabilities and rule names are FETCHED from the live docs — `{DOCS_BASE}/moderation/overview`, `/moderation/{rules-management,lists-management,flagged-messages,blocked-messages,reviewed-messages}`, `{DOCS_BASE}/rest-api/moderation-apis/overview`, and the client hooks `{DOCS_BASE}/ui-kit/<family>/core-features#moderation` (built-in report) + `{DOCS_BASE}/sdk/<platform>/ai-moderation` (SDK flagging). `DOCS_BASE = https://www.cometchat.com/docs`; append `.md`. Most of this is dashboard configuration; verify the exact rule/list options and any REST shapes against the docs before asserting them.
+
+## Use this skill when
+Making a chat safe/compliant: profanity/toxicity filtering, image/video safety, spam/scam detection, malware scanning of attachments, letting users report content, a moderator review queue, or an audit trail for T&S. Trust & Safety is a procurement gate for social, gaming, marketplace, dating, education and healthcare apps.
+
+## How it works
+Every message runs through the **rule engine** as it's sent; a rule either lets it through, **blocks** it (hidden immediately), or **flags** it for a moderator. Users can also **report** a message manually, which flags it. Blocked/flagged items land in dashboard queues; a moderator's decision (approve/block/mark reviewed) moves it to the audit trail.
+
+```
+send → rules → pass → delivered
+             → block → Blocked Messages
+             → flag  → Flagged Messages → moderator → Reviewed Messages (audit)
+```
+
+## 1. Configure rules + lists (dashboard / REST)
+- **Rules Management** (`/moderation/rules-management`): turn on the built-in rules you need and set each to **block** or **flag**. Available categories (fetch the current list — it grows):
+  - **Text:** word-pattern match (profanity), contact/email removal, spam & scam, platform circumvention, toxicity, hate & harassment, self-harm, explicit content, privacy/sensitive-info, impersonation, violent/terroristic, non-consensual sexual content.
+  - **Image:** unsafe/prohibited, minor-safety/CSAM, graphic violence, explicit/sexual, hate symbols, fraud (fake IDs), **malware scan**.
+  - **Video / Audio / File:** **malware & virus scan** of attachments.
+- **Lists Management** (`/moderation/lists-management`): your own keyword / regex / sentence lists, linked to rules — this is the "banned words" surface. Lists are reusable across rules.
+- **Programmatic setup:** the **Moderation REST API** (`/rest-api/moderation-apis/overview`) manages rules + keyword lists from your server (e.g. per-tenant config, CI-seeded rules). Fetch its shapes before writing calls.
+
+## 2. Wire the client (per family — built into the UI Kit)
+- **Report a message:** the UI Kits ship a built-in **Report Message** action on the message — enable it via that family's moderation feature (`{DOCS_BASE}/ui-kit/<family>/core-features#moderation`; wire through `cometchat-<family>-features`). No hand-rolled report UI.
+- **Blocked content:** rule-blocked messages simply don't render for recipients; nothing extra to build.
+- **SDK path (custom UI / headless):** flag messages directly with the Chat SDK (`{DOCS_BASE}/sdk/<platform>/ai-moderation`) — the per-feature fallback when a family has no drop-in.
+
+## 3. Moderator review + audit
+- **Flagged Messages** / **Blocked Messages** dashboards: moderators review, approve false positives, or confirm blocks — and use them to refine rules.
+- **Reviewed Messages** is the **audit trail** of every moderation decision (who did what, when) for compliance records — pair with `cometchat-compliance` for retention/eDiscovery of these records.
+
+## Legacy extensions — migrate, don't double-run
+If the app still uses the **legacy extensions** (Profanity Filter, Data Masking, Image Moderation), **disable them before enabling the new moderation rules.** Running both processes every message twice → performance issues and message delays. Treat this as a required migration step, not optional.
+
+## Enablement note
+Moderation is a dashboard/plan capability — enable it on the app (and on the **production** app, not just dev). `npx @cometchat/skills-cli@3 features` can toggle app extensions/AI after `auth login`; the rule/list configuration itself is done in the dashboard or via the Moderation REST API.
+
+## Common pitfalls
+1. **Legacy extensions left on** alongside new rules — double-processing, delays. Disable the old ones first.
+2. **Rules configured on dev only** — content ships unmoderated in production; enable on the production app.
+3. **Hand-rolling a report button** — the UI Kit already ships Report Message; wire the built-in.
+4. **Block vs flag confused** — block hides immediately (good for clear violations); flag routes to a human (good for borderline). Set each rule deliberately.
+5. **No one watching the queues** — flagged content needs a moderator workflow; wire notifications/ownership.
+6. **Assuming a rule exists** — fetch the current rule catalog; don't promise a category the docs don't list.
+
+## Verify it works
+A message with a banned word/keyword is blocked or flagged per the rule · an unsafe image is caught · an attachment is malware-scanned · a user's Report action flags a message into the queue · a moderator decision appears in Reviewed Messages · legacy extensions are off · rules are enabled on the production app.

package/skills/cometchat-onboarding/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: cometchat-onboarding
+description: "The shared FRONT DOOR for adding CometChat to ANY app — a consultative, enterprise-grade DISCOVER → UNDERSTAND → PLAN journey that ALWAYS runs first, before any framework core. Detects the whole repo, runs a features + design-system conversation (core chat/threads/groups/media/calls/search/…; a preset theme, match your design system, or build one), maps each feature to its UI Kit component (or the SDK method where the UI Kit has none — UI-Kit-first, SDK-fallback), shares a full integration PLAN, then hands a scoped build directive to the framework core on approval — final output is production-ready. Triggers: 'add cometchat', 'add chat', 'add chat to my app', 'add calling', 'integrate cometchat', 'build a chat feature'."
+license: "MIT"
+compatibility: "Framework-agnostic (React/Next/Angular/Vue/RN/Flutter/Android/iOS/… — degrades gracefully when a signal is absent). Emits NO CometChat components — output is a plan artifact + a scoped directive to a framework core skill."
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat onboarding journey discover understand plan front-door router-gate agnostic intent"
+---
+
+> **Ground truth:** this skill runs FIRST for every "add CometChat" request and produces NO integration code — its only outputs are (1) the shared **plan artifact** and (2) a **scoped build directive** to the framework core. Repo facts come from `npx @cometchat/skills detect --json` (the authority) + **READING THE REPO** for the rest — NEVER memory, never the dashboard CLI (AUDIT-059). The archetype→capability map and plan template are in `references/` (loaded on demand). Credentials + implementation belong to the framework core (`cometchat-<family>-core`, family resolved from `peers.yaml`). Draw the boundary at PLAN.
+
+<!-- onboarding is a platform-NEUTRAL journey skill (like the cross-family a11y/i18n): no per-platform Companion block. Its "companion" is whatever framework core the plan names on hand-off. -->
+
+## Use this skill when
+Any first-contact "add CometChat" intent, on ANY stack: "add chat", "add cometchat", "add chat to my app", "add voice/video calling", "integrate cometchat". The router (`cometchat`) ALWAYS routes here FIRST — a mandatory gate. It runs before ANY framework core so the developer gets discover → understand → plan before a line is written. (An *upgrade* request — "upgrade my v6 UI Kit to v7" — is reconciliation, not onboarding; the router sends that straight to migration. And a re-entry on an already-integrated repo short-circuits: see §Re-entry.)
+
+## What this skill does — and only this (the four beats)
+Run the four beats in order, as a CONSULTATIVE conversation (senior-engineer tone: recommend with a reason, surface trade-offs, never a blank form). Nothing is written to the user's code in ANY beat — the first write happens only AFTER beat 4's approval, inside the framework core. The final output is PRODUCTION-READY (the core's contract guarantees it).
+
+> **The build model — UI Kit first, SDK per-feature fallback (NO "which approach?" question).** A renderable app on a platform with a shipped UI Kit ALWAYS gets the **UI Kit** as its UI layer (fastest path to a production-ready surface). There is NO "UI Kit vs SDK" architecture choice to make. Instead, PER FEATURE: if the UI Kit has a component/prop for it → **use the component**; if it does NOT → call the platform's **Chat SDK** method directly (already installed under the UI Kit — init/login use it). The SDK is the FALLBACK for what the UI Kit doesn't expose (AI agents, campaigns, advanced/AI moderation, transient messages, bots, webhooks, …), looked up in the detected family's core `references/docs-map.md` → SDK docs (`references/platforms.md`). The ONLY exception: a backend/no-DOM/non-renderable context has no UI layer — there the SDK is the whole build; say so honestly.
+
+### 1. DETECT everything (environment + the WHOLE current repo)
+Run the detect probe (above), then **READ THE REPO** for the rest (on web: `package.json` deps/scripts, the lockfile, framework config files and source; on iOS: `*.xcodeproj`/`*.xcworkspace`, `Package.swift`, a `Podfile` as a signal only — `references/platforms.md`). Capture, framework-agnostically, degrading gracefully when a signal is absent (record it `null`, never guess):
+- **Framework & build:** `framework` · `framework_version` · `bundler` · `router` · `ssr_strategy` (ssr/csr/islands) · `env_prefix` (VITE_/NEXT_PUBLIC_/…) · `package_manager` (from the lockfile) · `language` (TS/JS) · `project_name` (plus mobile version fields for expo/RN/android/flutter). **Non-web platforms have different fields** — iOS, Android, React Native and Flutter each have a column in `references/platforms.md`.
+- **App integration state:** **installed UI Kit + `version_conflict`** (a major other than the family's target — React v7, Angular v5, RN v5, iOS v5, Android v6, Flutter v6; `peers.yaml`) · **existing CometChat integration** · **credential presence** (an existing `.cometchat/config.json` or `*_COMETCHAT_APP_ID` env).
+- **App architecture (infer from source, `null` when absent):** **auth system** (nextauth / clerk / firebase / auth0 / supabase / custom) · **styling / design system** (tailwind / css-modules / mui / styled-components / chakra) · **state management** (redux / zustand / mobx / recoil / context).
+> **`version_conflict` STOP still applies HERE.** If detection shows a UI Kit major other than the family's target for an *add* request, STOP and surface it in the plan (reconcile first — `RULES.md`); do not hand off a build over a mixed-major repo. If CometChat is already wired for THIS major → **Re-entry** (below).
+> **A signal being absent is DATA, not a blocker.** Missing auth ⇒ recommend the dev Auth-Key path + a note to add prod auth later; missing framework ⇒ record it and (per §Non-React) state the platform's core isn't built yet. Never fabricate a signal, never stall on one.
+
+### 2. UNDERSTAND — the features + design conversation (each question WITH a recommended default from the repo)
+A SHORT, consultative Q&A (clarification contract: ask **and wait**); every question carries a repo-inferred recommendation so the developer confirms rather than composes:
+1. **Archetype / shape** — `1:1`/marketplace · `support` · `community`/groups · `full-messenger` · `embedded`. Infer from routes (seller/product → `1:1`; `/support` → `support`; `/community`/`/groups` → `community`). "Detected `<signal>` → recommend `<archetype>` — keep or change?"
+2. **Features** — WHICH capabilities (from the detected platform's manifest — `features.json` react-v7 / `features.angular-v5.json` angular-v5 / `features.ios-v5.json` iOS / … — grouped; naming only one hands the wrong menu to every other family): **Core chat** (1:1 + groups, messages, **threads**, media/attachments, typing, receipts, **reactions, mentions** — the last two are ON BY DEFAULT in v7 core, NOT extensions to enable — AUDIT-077) is the recommended default and always included; then offer the add-ons — **voice/video calls · search · polls/stickers · translation · push notifications · AI/smart-replies · moderation · AI agents**. Do NOT list `reactions`/`mentions` as add-ons (they're core), and never offer a `deprecated:true` feature (email-replies · e2e-encryption · live-streaming). **First SUBTRACT what's already present (AUDIT-043)** — `detect`/existing-integration for wired features, and ASK which dashboard-gated extensions are already enabled (the CLI can't read per-app enabled-state); don't re-offer an already-on feature like translation. Ask "core chat + which of these?" Don't ask about individual components/props (the core decides those). **Each chosen feature maps to a UI Kit component where one exists, or an SDK method where it doesn't** (AI agents · campaigns · advanced/AI moderation · bots · webhooks · transient messages → SDK) — the plan's **Feature coverage** section records which, so nothing is silently dropped or hand-rolled.
+3. **Design / theming** — HOW it should look. Present the light/dark MODE and the palette, and **ALWAYS include the AUTO option**: **(a)** **Auto — follow the device's light/dark (OS) setting** — the RECOMMENDED default for a fresh app (whether the kit follows the OS BY ITSELF differs per platform — **iOS does, with no host code, so do not offer to wire it there; web does not** — `references/platforms.md`, AUDIT-004), **(b)** a fixed **light** preset, **(c)** a fixed **dark** preset, **(d)** **match your existing design system** (recommended when discovery detected Tailwind/MUI/Chakra/a token theme — reuse it), **(e)** a **brand palette** (your colors as the platform's theme tokens — CSS custom properties on web, `UIColor`/`dynamicColor` on iOS), or **(f)** a **custom design system**. All map to the UI Kit's theme tokens / `customization`. Recommend from the detected `styling` signal: none → **auto + default tokens**; a design system detected → **auto + match**. **Omitting the auto / follow-system option is a defect (AUDIT-042) — the kit supports it and it's the pack's fresh-app default; never present a light-only menu.**
+4. **Scope / placement** — smallest surface that satisfies the archetype (default) vs. the full combined app; the placement shapes differ by platform (`references/platforms.md`). Default to the SMALLEST reasonable production-ready surface.
+The archetype → capability translation is in `references/archetypes.md`; the feature menu is the DETECTED platform's manifest (`references/platforms.md`) — never offer a feature that platform does not ship. Recommend, don't interrogate.
+
+### 3. PLAN — share the FULL plan artifact BEFORE anything is written
+Assemble and present the **plan artifact** — the concrete deliverable of this skill. It MUST contain every section of the plan-completeness contract (template + contract in `references/plan-artifact.md`):
+1. **What I found** — the beat-1 discovery summary — the fields that APPLY to the detected platform (web: framework/bundler/router/SSR/pkg-mgr/env-prefix; iOS: deployment target/dependency manager/UI framework/Xcode project), plus language, auth, styling, existing-CometChat — each value or `null`. Do not report a field the platform does not have.
+2. **What you want (feature coverage)** — the confirmed intent (archetype · **features** · **design/theming** · scope) translated to **CometChat capabilities** (intent→capability map from `references/archetypes.md`; features from `features.json`), **each tagged UI Kit component or SDK method** — the UI-Kit-first / SDK-fallback split. Flag the SDK-backed ones (AI agents · campaigns · advanced moderation · bots · …) so the core wires them from the SDK docs; nothing is silently dropped or hand-rolled.
+3. **What I'll do** — a NUMBERED action list (the scoped build steps, in order).
+4. **Files that will change** — the concrete paths/areas the build will touch (additive — APPEND, never replace).
+5. **Packages** — the exact package(s) the plan installs (named, with major pins; the core owns the exact coordinates).
+6. **Credential + auth strategy** — dev **Auth Key** vs prod **server-minted auth token**, CHOSEN from discovery (a real auth system detected ⇒ recommend the prod token path wired to it; none ⇒ dev Auth-Key path + a note to harden for prod). State it; do NOT fetch credentials here. **Say in the plan that the core will OFFER to fetch App ID/Region/Auth Key from the dashboard (loading the CometChat CLI on demand → `provision`) or let the user paste them — so the fetch step isn't dropped on hand-off and never degrades into a "paste them yourself" TODO (AUDIT-039).**
+7. **The modify-or-approve gate** — explicitly invite the user to EDIT the plan or approve it. Nothing is written before approval.
+
+### 4. MODIFY or START — edit the plan, else hand a SCOPED directive to the core
+- The user may **edit** any part of the plan (change the archetype, add/drop a feature, narrow scope, switch the credential strategy) → re-render the plan and re-present the gate. Loop until they approve.
+- On **approval**, emit a **scoped build directive** and hand off:
+  - **Framework detected** → resolve `<family>` from `peers.yaml` (React web → `react-v7`; Angular → `angular-v5`; iOS → `ios`; React Native/Expo → `react-native`; Android → `android-v6`, reading `android_variant` from gradle files for cohort; Flutter → `flutter-v6`) and hand off to `cometchat-<family>-core` with the scoped surface (archetype + features + theming + scope + credential strategy + affected files), pulling in ONLY the additional SHIPPED skills the plan names (theming → `customization`, framework glue → `patterns`, features → `features`, voice/video → `calls`, **push → `cometchat-<family>-push`** (thin, docs-first), v6→v7 upgrade → `migration`). The core builds **UI Kit first** and, for any **SDK-backed feature** the plan flagged (AI agents · campaigns · advanced moderation · …), wires the **SDK method** looked up in `cometchat-<family>-core/references/docs-map.md` → SDK docs. The core owns detect-reuse, credentials, and the production-ready build. **Android extra:** cohort-split skills (`android_variant`: `views` → `kotlin-*`, `compose` → `compose-*`) pick `{kotlin,compose}-{components,placement,customization}`; cohort-neutral skills (`features`, `calls`, `push`, `production`, `testing`, `troubleshooting`, `builder-settings`, `events`, `extensions`, `migration`). Credentials → `app/src/main/assets/cometchat-settings.json` (gitignored), not `.env`.
+  - **A framework with no shipped core detected** → still deliver the full discover→understand→plan, then state clearly that **that platform's implementation core isn't built yet** (framework-ready posture; see §Not in this pack). Do not fake an implementation.
+> **Scoped, not the kitchen sink.** The directive names the SMALLEST surface the approved plan calls for (e.g. "1:1 chat surface for the marketplace, dev Auth-Key, touch `src/features/chat/*`"), so the core builds that — not every component.
+
+## Calling-FIRST intent — the "add calling" decision tree
+When the PRIMARY first-contact intent is **calling** ("add calling / voice-video / a video call" as the GOAL, not "add chat" that includes calls), run the **`references/calling-first.md`** decision tree instead of defaulting to the UI-Kit path — calling is the ONE intent where an approach choice is legitimate (standalone build-your-own-UI calling is a real product; a CHAT build still gets NO approach question). In brief: detect the UI Kit → offer **prebuilt** (`cometchat-<family>-calls`) vs **standalone from scratch**; if no UI Kit, ask *"chat too, or calling only?"*; for from-scratch, ask **one-on-one (ringing) vs meet-style**, then hand off to the platform's headless Calls SDK v5 skill (**`cometchat-js-v5-sdk`** web, **`cometchat-ios-v5-sdk`** iOS, **`cometchat-android-v5-calls-sdk`** Android, **`cometchat-react-native-v5-sdk`** React Native, **`cometchat-flutter-v5-sdk`** Flutter — resolved from `peers.yaml`, not a literal; not installed? `npx @cometchat/skills add --family <platform>-calls` adds it alongside) with the mode. Still run beats 1–3 + a short plan before hand-off.
+
+## The hand-off boundary (REUSE the core; do NOT fork it)
+This skill does **discover + understand + plan**. The framework core does **credentials + implement + verify**. The line is BEAT 4's approval:
+- Onboarding OWNS: whole-repo discovery, intent elicitation with recommendations, the plan artifact, the modify/approve gate, the scoped directive.
+- The core OWNS (do NOT restate or fork here): credential fetch/provision + env write (`references/setup-credentials.md`), init→login→render, component/prop selection, the production-ready build. It REUSES this discovery (re-reads the same signals + any `.cometchat` config, skips re-setup) — one detection approach, two consumers.
+
+## Competitor SDK present (`migrate_from` non-null)
+Name the vendor in the plan and offer the one-prompt migration; on "migrate"/"replace" hand straight to that entry's `skill` (no plan gate — it runs end-to-end). Never install CometChat alongside Sendbird/Stream silently.
+
+## Re-entry (already-integrated repo)
+If beat-1 discovery shows CometChat already wired for the current major (`existing_cometchat: true`, no `version_conflict`), do NOT re-run the full journey. Summarize what's already integrated, ask what the user wants to ADD or CHANGE, and route that incremental ask straight to the framework core (or the calls/features/customization skill it names) — onboarding is the FIRST-contact front door, not a gate on every subsequent change.
+
+## Not in this pack — missing skills & not-yet-built cores (graceful-degrade posture)
+**The rule: only hand off to a core/skill that SHIPS in this pack** — present under `skills/` and declared in `peers.yaml`. Never route to an uninstalled skill and never pretend it's there; run beats 1–3 in full, produce the plan artifact, and in beat 4 be honest and offer the nearest shipped alternative. **React, Angular, iOS, React Native, Android and Flutter all ship FULL sets** (`cometchat-<family>-core` + `-calls` · `-push` · `-migration` · …), plus the headless `cometchat-android-v5-sdk` (Android Chat SDK) and the from-scratch calling skills `cometchat-js-v5-sdk` (web) / `cometchat-ios-v5-sdk` (iOS) / `cometchat-android-v5-calls-sdk` (Android). Only apply this posture where a capability has genuinely NO shipped skill, or the platform has no `peers.yaml` peer (Vue today) — then deliver the plan as the hand-off spec and say the implementation skill isn't built yet. Never silently pretend React, and never decline a family that ships. **Per-platform routing table + how to word an honest decline: `references/not-in-this-pack.md`.**
+
+## Common pitfalls
+- **Writing code in beats 1–3.** The first write is post-approval, in the core. Onboarding that scaffolds before the plan is approved has skipped its own gate.
+- **Asking "UI Kit or SDK?"** There is NO approach choice (calling-first excepted) — the UI Kit is always the UI layer, the SDK the per-feature FALLBACK inside the same build. Don't ask; map each feature to its component, or its SDK method where none exists.
+- **Hand-rolling a feature that already exists.** Never build custom UI/logic for something the UI Kit has a component for, OR the SDK has a method for. Check the UI Kit first (`component-props.md` / catalog), then the SDK docs (`docs-map.md`). Hand-roll ONLY when neither has it.
+- **Declining a family that ships.** calls + **push** + migration ARE installed on every family — route to them normally (`cometchat-<family>-calls` / `-push` / `-migration`). Apply the **§Not in this pack** posture ONLY where no skill ships, and never route an unknown platform to React by default.
+- **Asking blank questions, or skipping features/design.** Beat 2 must cover archetype · WHICH features · HOW it looks (**auto/follow-OS [default]** · fixed light/dark · match design system · brand · custom) · scope, each WITH a repo-inferred recommendation. A bare "which archetype?" is under-delivery; omitting **auto/follow-OS** is a defect (AUDIT-042).
+- **Forking the credential/detect flow.** Do NOT re-implement credentials or detection here — plan them, then let the core execute (the hand-off boundary above).
+- **Over-scoping the directive.** Hand off the smallest surface the plan names, not the whole combined app (that's a later grow-on-request in the core).
+- **Stalling on a missing signal.** Absent auth/framework/styling is recorded `null` and flows into a recommendation — never a blocker. (`version_conflict` on an *add* IS a STOP; a missing signal is not.)
+
+## Verify before done (this skill's "done" = a good plan + a clean hand-off, NOT a running app)
+Onboarding is complete when: (1) beat-1 discovery ran and every signal is captured or explicitly `null`; (2) every intent question (archetype · **features** · **design/theming** · scope) was asked WITH a repo-inferred recommendation and answered; (3) the plan artifact was presented containing ALL plan-completeness sections incl. **Feature coverage** (UI Kit component vs SDK method per feature) (`references/plan-artifact.md`); (4) the user approved (or edited → re-approved); (5) EITHER a scoped directive was handed to a SHIPPED core (`cometchat-<family>-core`), OR — where no skill ships for the platform/capability — the **§Not in this pack** posture was stated (honest + plan-as-spec + shipped alternative), never a hand-off to an uninstalled skill. This skill does NOT build, test, or run the app — the chosen core does the build (production-ready per its contract); testing is advisory/human unless the user asks (`RULES.md`).
+
+## Deep references (load ONLY when the beat needs them — keeps this file thin)
+- `references/archetypes.md` — the archetype → CometChat-capability map (1:1/marketplace · support · community · full-messenger · embedded) + the repo-signal → recommended-default heuristics for beat 2, and the intent→capability translation for the plan's "what you want".
+- `references/plan-artifact.md` — the plan-artifact TEMPLATE (fill-in) + the **plan-completeness contract** (the seven sections the plan MUST contain) + a worked example.
+- `references/calling-first.md` — the "add calling" decision tree (UI-Kit-present → prebuilt vs scratch; no-UI-Kit → chat-too? ; scratch → one-on-one vs meet → hand off per platform: web `cometchat-js-v5-sdk`, iOS `cometchat-ios-v5-sdk`, Android `cometchat-android-v5-calls-sdk`, React Native `cometchat-react-native-v5-sdk`). Load when the primary intent is calling.
+- `references/not-in-this-pack.md` — the graceful-degrade posture in full: the per-platform table of which skills SHIP (so a shipped family is never declined) + how to word an honest decline. Load in beat 4 when a needed skill may not exist.
+- `references/platforms.md` — the per-platform beat-1 signal columns (web · iOS · Android · React Native · Flutter) + the platform feature manifests.

package/skills/cometchat-onboarding/references/archetypes.md

@@ -0,0 +1,51 @@
+# archetypes — intent → CometChat capability map + repo-signal → recommended default
+
+This is the translation layer for beats 2 and 3: it turns a **product archetype** into **CometChat capabilities** (the plan's "what you want"), and it turns **beat-1 repo signals** into the **recommended default** each intent question carries (the "make it easy + recommend" requirement). Capabilities named here are conceptual (chat surface / 1:1 / groups / calls / search / threads) — the framework core maps each to its own components on hand-off; onboarding does not name UI-Kit symbols.
+
+## The five archetypes → capabilities
+
+| Archetype | Product shape | CometChat capabilities (the plan's intent→capability) | Default modality | Default scope |
+|---|---|---|---|---|
+| **1:1 / marketplace** | Buyers ↔ sellers, requester ↔ provider — a "message this person" entry point off a profile/listing | 1:1 conversations · a conversation list · a message pane (send/receive, attachments) · unread + presence · a "Message <X>" entry button wired to open the conversation | chat | smallest 1:1 surface (a message button → a conversation ↔ message pane), NOT the full app |
+| **support** | Customers ↔ support agents; often a launcher/widget in a corner, sometimes ticket-scoped | 1:1 (customer↔agent) conversations · a message pane · often **embedded** placement (a launcher/popup, not a full page) · optionally calls for escalation · agent-side may want a conversation list | chat | an embedded/widget support surface |
+| **community / groups** | Members talk inside communities, channels, or rooms | **groups** · group conversations · group members + management/moderation · a message pane · often a groups/channels list · optionally group calls | chat | a groups + group-message surface |
+| **full messenger** | A complete standalone chat app (the "everything" experience) | the whole combined experience: conversations + users/groups tabs · message pane · threads · search · calls · the full grow-target | both | the full combined app (the core's grow target) |
+| **embedded** | Chat lives INSIDE an existing screen/flow, not as its own page (a side panel, drawer, or inline widget) | a scoped chat surface constrained to a container (a fixed-size panel/drawer), 1:1 or group as the host flow needs; minimal chrome | chat | a placement-constrained embedded surface |
+
+> **Modality overlay.** Any archetype can be `chat` / `calls` / `both`. "Add calling" or a repo already using CometChat chat → recommend `calls`/`both`. Calls layer: 1:1 voice/video and/or group calls, incoming-call handling, and (on native) the platform permission config — the framework core + its calls skill own the details.
+
+## Repo-signal → recommended default (beat 2 — infer, then let the user confirm)
+
+Each question's recommendation comes from what beat-1 detected. Phrase every one as **"detected <signal> → recommend <default> — keep or change?"** — never a blank ask.
+
+**Archetype (from routing/domain signals):**
+- Marketplace/e-commerce signals — routes or dirs like `/products`, `/listings`, `/sellers`, `/checkout`; a product/seller/vendor model → **1:1 / marketplace**.
+- Support/helpdesk signals — `/support`, `/help`, `/contact`, `/agent`, a tickets model, a widget/launcher pattern → **support** (embedded placement).
+- Community/social signals — `/community`, `/groups`, `/channels`, `/rooms`, `/feed`, a groups/members model → **community / groups**.
+- A greenfield/standalone app, or an explicit "build a chat app" → **full messenger**.
+- Chat is clearly a secondary feature bolted onto an existing screen (dashboard/app shell with no obvious chat page) → **embedded**.
+- No decisive signal → recommend the SMALLEST reasonable default (**1:1**) and say so; the user confirms or changes. (Do not stall — smallest-reasonable-default + flag, per `RULES.md` clarification only where genuinely blocking.)
+
+**Modality:**
+- Trigger was "add calling"/"add voice/video" → **calls** (or **both** if chat isn't present yet).
+- Repo already has CometChat chat wired → **calls** (adding to existing).
+- Otherwise → **chat**.
+
+**Scope:**
+- Default to the **smallest surface** that satisfies the archetype (the core's production-ready core surface for 1:1/support/community; a placement-constrained surface for embedded).
+- Recommend the **full combined app** ONLY for **full messenger** or an explicit "the whole chat app" ask.
+
+**Credential + auth strategy (feeds plan section 6):**
+- A real auth system detected (`auth` ∈ nextauth/clerk/firebase/auth0/supabase/custom) → recommend the **prod server-minted auth-token** path, wired to that system (map the app's user id → the CometChat UID); note the dev Auth-Key is fine to start but must not ship.
+- No auth detected (`auth: null`) → recommend the **dev Auth-Key** path to get moving, with an explicit note to add prod token auth before production.
+- The framework core executes whichever is chosen (its `references/setup-credentials.md`); onboarding only decides + states it.
+
+**Placement / SSR hints (feeds plan sections 3–4):**
+- `styling` (tailwind/mui/…) → note "match the existing design system" as a plan step (hand to customization on build).
+- **Theme MODE default = AUTO (follow the OS light/dark setting).** For a fresh app (no `styling` detected), recommend **auto** — the core syncs `theme` ↔ `prefers-color-scheme` (the kit ships light+dark but does NOT auto-follow the OS on its own; pack default per AUDIT-004). ALWAYS offer the auto/follow-system option in the design question — never a light-only or fixed-preset-only menu (AUDIT-042). Mode (auto/light/dark) and palette (default tokens / match design system / brand / custom) are independent — auto can pair with any palette.
+- `ssr: ssr`/`islands` (Next App Router, Astro) → flag the client-boundary work in the plan (the chat surface is client-side; the core's patterns skill owns the directive).
+- `state` (redux/zustand/context) → note where the "current conversation / logged-in CometChat user" state should live so it fits the app's existing store, not a new one.
+
+## Notes
+- These are **recommendations**, not decisions — the user confirms or overrides every one at the beat-4 gate.
+- Onboarding names capabilities and archetypes; the **framework core** names components. Keep that split so this file stays platform-neutral and doesn't rot with UI-Kit changes.

package/skills/cometchat-onboarding/references/calling-first.md

@@ -0,0 +1,77 @@
+# calling-first.md — the "add calling" decision tree
+
+Load this when the PRIMARY, explicit first-contact intent is **calling** — the user opens with "add calling / add voice-video / add a video call to my app" as the GOAL, not "add chat" that merely includes calls. Standalone, build-your-own-UI calling (a video-only app, a meeting room, an embedded call widget with no chat surface) is a legitimate product, so **calling is the one intent where onboarding offers an approach choice**. (A CHAT build still gets NO approach question — the "Asking 'UI Kit or SDK?'" pitfall stands for chat.)
+
+Run it as a consultative Q&A (clarification contract: ask **and wait** at each branch). Still run beats 1–3 (whole-repo discovery + a short plan naming the mode + packages + credential strategy) BEFORE the hand-off — this tree replaces the archetype/approach question for calling-first intent; it does not skip the plan.
+
+## Step 1 — detect the UI Kit (beat 1)
+Is a CometChat UI Kit installed? Web/RN: `@cometchat/chat-uikit-*` in `package.json`. **iOS: the `ios` row's `kit_package` (`peers.yaml`) in `Package.swift`/`Podfile`, or an `*.xcodeproj`/`*.xcworkspace` that resolves it.** Android: `com.cometchat:chatuikit-*` in the gradle files. Flutter: `cometchat_chat_uikit` in `pubspec.yaml`.
+
+## Step 2 — branch on that
+- **UI Kit IS installed** → ask:
+  > *"Your UI Kit already ships a prebuilt calling UI (incoming-call surface, call buttons, ongoing-call). Use that, or build a standalone calling feature from scratch with no prebuilt UI?"*
+  - **prebuilt** → hand off to `cometchat-<family>-calls` (e.g. `cometchat-react-v7-calls`, **`cometchat-ios-calls`** on iOS). It rides the SAME init/login — enable calling on the existing UIKit settings (`uiKit.callsSDK`). Done.
+  - **from scratch** → Step 3.
+- **UI Kit is NOT installed** → ask:
+  > *"We also ship UI Kits with a prebuilt calling UI. Do you need CHAT as well, or only calling? If you'll want chat too, the UI Kit gives you both with a prebuilt call UI; if it's calling-only, we can build it from scratch."*
+  - **chat too / wants prebuilt** → the normal UI-Kit journey (`cometchat-<family>-core` + `calls`).
+  - **calling only / from scratch** → Step 3.
+
+## Step 3 — from-scratch / standalone calling → ask the call SHAPE
+> *"One-on-one (ringing — call a specific user, they get an incoming prompt to accept/reject) or meet-style (a session room anyone joins by id)?"*
+
+### Step 3b — ringing on MOBILE ⇒ ask DELIVERY too (ask **and wait**; never assume)
+Answered **one-on-one ringing** on a mobile platform (Android/iOS/Flutter/React-Native)? Ask this BEFORE
+the plan — it is an architecture fork, not a later add-on:
+> *"Do calls need to ring when the app is in the background or closed — the way WhatsApp does? Or is
+> in-app ringing enough (both people have the app open)?"*
+
+- **In-app / foreground only** → the ringing recipe (`initiateCall` / `CallListener` / `acceptCall`).
+  **Say the limit out loud in the plan:** in auto socket mode the Chat SDK drops its WebSocket the moment
+  the app is backgrounded, so a backgrounded callee never rings and the caller just times out (~45 s) —
+  verified live on two devices. It is NOT replayed when they return.
+- **Background / killed-app ringing** → that is **VoIP push**, a separate build, and a **real device**
+  either way (neither emulators nor the iOS Simulator can prove it).
+  *Android:* an FCM project + `FirebaseMessagingService`, `PhoneAccount` registration, a
+  `ConnectionService` — `/calls/android/voip-calling`, docs-first, paired with the platform's `push` skill.
+  *iOS:* the separate `CometChatPushNotifications` package (an APNs **VoIP** provider in the dashboard,
+  Background Modes → Voice over IP, and a device — APNs never delivers a VoIP push to the Simulator). The
+  SDK owns `PKPushRegistryDelegate` and `CXProviderDelegate`; writing either yourself fights it for the
+  same callbacks. Certified on device via `cometchat-ios-v5-sdk`.
+  Name it as its own plan item with its own prerequisites — do not fold it into the ringing recipe and do
+  not promise it from that recipe.
+
+**Why this is asked, not assumed.** "One-on-one ringing" reads as *WhatsApp* to most people, and the
+foreground-only build passes every casual test (both apps open during development) before failing in the
+user's real world. A user who wanted VoIP and got the ringing recipe does not find out until their
+callee's phone stays silent. Web/JS has no VoIP-push equivalent — skip 3b there.
+
+## Step 4 — resolve the headless skill FROM THE DETECTED PLATFORM
+The headless calls skill is **per-platform** — resolve it from `peers.yaml` (the peer whose `consumption: sdk` and whose `kit_package` is a `calls-sdk-*`), never from a literal. Today's live headless-calls peers:
+
+| Detected platform | Peer | Skill | Calls package | Ringing also needs |
+|---|---|---|---|---|
+| web / JS | `js-calls` | `cometchat-js-v5-sdk` | `@cometchat/calls-sdk-javascript@5` | `@cometchat/chat-sdk-javascript@4` |
+| React Native | `react-native-calls` | `cometchat-react-native-v5-sdk` | `@cometchat/calls-sdk-react-native@5` | `@cometchat/chat-sdk-react-native@4` |
+| iOS | `ios-calls` | `cometchat-ios-v5-sdk` | `CometChatCallsSDK` | the Chat SDK for signaling |
+| Android | `android-calls` | `cometchat-android-v5-calls-sdk` | `com.cometchat:calls-sdk-android` | the Chat SDK for signaling |
+| Flutter | `flutter-calls` | `cometchat-flutter-v5-sdk` | `cometchat_calls_sdk: ^5.0.7` | `cometchat_sdk` v5 |
+
+**Is that skill installed?** `add` installs ONE family per run — a UI-Kit install carries only that family's skills, so the headless calls skill may not be in the project's skills folder yet. If it isn't, install it before the hand-off — it is added ALONGSIDE the existing UI Kit skills (nothing is removed):
+`npx @cometchat/skills add --family <js-calls|react-native-calls|ios-calls|android-calls|flutter-calls>` (same `--ide` you installed with). Never hand off to a skill that is not present.
+
+> ⚠️ **The JOIN STEP IS NOT PORTABLE — do not copy it across platforms.** Web joins with `joinSession(token, sessionSettings, containerEl)` into a sized **DOM element**. React Native has **no `joinSession` at all**: you join by RENDERING `<CometChatCalls.Component callToken sessionSettings />` inside a flex-sized `View`. Flutter is a third shape again — `joinSession` RETURNS a `Widget?` and mounts nothing, so the app must place it in the widget tree; an agent that ports another platform's snippet produces a call that joins successfully and renders a blank screen. Name the mode and let the platform's own skill own the recipe.
+
+Then hand off to the resolved skill with the chosen mode named in the directive:
+- **meet-style** → Calls SDK only (`generateToken` → the platform's join step). No Chat SDK.
+- **one-on-one ringing** → Calls SDK media + **Chat SDK signaling** (`initiateCall` / `CallListener` / `acceptCall`) — note the platform's extra chat-SDK dependency from the table in the plan, and carry the Step-3b delivery answer through.
+
+## Hand-off directive shape
+`"standalone <meet-style|one-on-one ringing> calling via cometchat-js-v5-sdk, <session-room|ring-a-user> surface, dev Auth-Key, package(s): @cometchat/calls-sdk-javascript@5[ + @cometchat/chat-sdk-javascript@4 for ringing], touch <paths>"`. Android: `"standalone <meet-style|one-on-one ringing> calling via cometchat-android-v5-calls-sdk, <session-room|ring-a-user> surface, <in-app ringing (foreground-only)|+ VoIP push for background/killed>, dev Auth-Key in assets/cometchat-settings.json, package(s): com.cometchat:calls-sdk-android:5.0.+[ + com.cometchat:chat-sdk-android:5.0.+ for ringing], touch <paths>"`. The headless skill owns install, init→login→generateToken→joinSession, listeners, and teardown. **A ringing directive on mobile MUST carry the Step 3b delivery answer** — without it the recipe silently defaults to foreground-only and the user learns the limit after the build.
+
+**iOS:** `"standalone <meet-style|one-on-one ringing> calling via cometchat-ios-v5-sdk, <session-room|ring-a-user> surface, <in-app ringing (foreground-only)|+ VoIP push for background/killed>, dev Auth-Key, package(s): CometChatCallsSDK@5 via SPM (github.com/cometchat/calls-sdk-ios)[ + CometChatSDK@4 for ringing][ + CometChatPushNotifications@1 for VoIP], Info.plist camera+mic usage strings, touch <paths>"`. The headless iOS skill owns install, init->login->join, listeners and teardown.
+
+**Flutter:** `"standalone <meet-style|one-on-one ringing> calling via cometchat-flutter-v5-sdk, <session-room|ring-a-user> surface, <in-app ringing (foreground-only)|+ push for background/killed>, dev Auth-Key in cometchat-settings.json (a registered Flutter ASSET — commit a placeholder with no real key so a fresh clone builds; real keys supplied locally / generated in CI, per `cometchat-flutter-v6-core`), package(s): cometchat_calls_sdk: ^5.0.7[ + cometchat_sdk v5 for ringing], minSdk 26 / iOS 15.1, touch <paths>"`. Three Flutter-specific things the directive must not lose:
+- the token API is **`generateCallToken`**, not `generateToken` — the latter is deprecated and the live docs still show it.
+- ⚠️ **do not carry another platform's calling snippet across.** Flutter's `joinSession` returns a `Widget?` and mounts nothing; the app places it in the widget tree. An agent that pattern-matches the container-based platforms produces a call that joins and renders a blank screen.
+- for Step 3b, Flutter has **no first-party CometChat push package** — background ringing is FCM on Android and APNs/CallKit on iOS, wired by the app. Say so rather than promising a package that does not exist.

package/skills/cometchat-onboarding/references/not-in-this-pack.md

@@ -0,0 +1,8 @@
+# Not in this pack — missing skills & not-yet-built cores
+
+The graceful-degrade posture, in full. The entry keeps the one-line rule; this is the detail,
+including exactly which skills ship per platform and how to word an honest decline.
+
+**The rule: only hand off to a core/skill that SHIPS in this pack** — present under `skills/` and declared in `peers.yaml`. When a needed skill is NOT installed, never route to it and never pretend it's there; run beats 1–3 in full, produce the plan artifact, and in beat 4 be honest and offer the nearest shipped alternative. Two cases:
+- **Shipped skills to route to (by platform — NEVER decline what IS shipped; `peers.yaml` is the authority):** **React** (`react-v7`): calling → `cometchat-react-v7-calls`; push → `cometchat-react-v7-push` (docs-first — honestly note live delivery needs a device check); migration → `cometchat-react-v7-migration`. **Angular** (`angular-v5`): the full set incl. `-calls`, `-push`, `-migration`. **iOS** (`ios`): `cometchat-ios-core` + `-calls`/`-push`/`-migration`. **React Native** (`react-native`): calling → `cometchat-react-native-calls`; push → `cometchat-react-native-push`; migration → `cometchat-react-native-migration`. **Android** (`android-v6`): `cometchat-android-v6-core` + the cohort-split `{kotlin,compose}-*` skills, `-calls` (prebuilt call UI), `-push` (FCM), `-migration`; **headless Chat SDK** → `cometchat-android-v5-sdk`; **headless calling from scratch (meet-style or 1:1 ringing, no UI Kit)** → `cometchat-android-v5-calls-sdk` (via `calling-first.md`). **Flutter** (`flutter-v6`): `cometchat-flutter-v6-core` + `-calls`/`-push`/`-migration`. Web headless calling from scratch → `cometchat-js-v5-sdk`. The headless **JS Chat SDK** is not a separate skill, but its methods ARE the per-feature fallback used INSIDE the UI-Kit build (`docs-map.md` → SDK docs). Only apply the "not in this pack" posture for a capability with genuinely NO shipped skill (see §Not in this pack) — push is now shipped on every family, so route to it.
+- **Not-yet-built core (no matching `peers.yaml` peer — Vue today; a plain-JS chat UI is likewise SDK-only):** still deliver the plan; state that CometChat DOES support that platform but its implementation skill isn't built in this pack yet; offer the plan as the hand-off spec (or for a manual integration following CometChat's docs). Never silently pretend React. **Never put a shipped family on this list** — a literal agent will decline the user (this file once listed Android/RN/Flutter/Angular after they had shipped; `lint-skills.mjs` now checks the list against the shipped `-core` dirs).

package/skills/cometchat-onboarding/references/plan-artifact.md

@@ -0,0 +1,133 @@
+# plan-artifact — the template + the plan-completeness contract
+
+The plan artifact is onboarding's DELIVERABLE. Because an onboarding skill emits no CometChat symbols, its "completeness oracle" is not a symbol catalog — it is this **plan-completeness contract**: the fixed set of sections the plan MUST contain, so every run of onboarding produces the same complete plan shape (not a lucky partial). This mirrors how `contracts.json` fixes the floor for a UI-Kit surface; here the floor is the plan itself. The matching machine-checkable contract lives in `contracts.json` as `onboarding-plan` (kind `plan`).
+
+## The plan-completeness contract — the plan MUST contain all seven
+
+| # | Section | What it fixes | Sourced from |
+|---|---|---|---|
+| 1 | **Discovery summary** | Every beat-1 signal, each a value or explicit `null` — framework · bundler · language · package manager · auth · styling · state · routing · SSR/CSR · existing CometChat · installed UI Kit / `version_conflict` · env file + prefix | repo read (package.json / lockfile / configs / source) |
+| 2 | **Intent → capability map** | The confirmed archetype · modality · scope, TRANSLATED to CometChat capabilities, **each tagged UI Kit component or SDK method** (UI-Kit-first / SDK-fallback — flag SDK-backed features so the core wires them from the SDK docs) | beat-2 answers + `references/archetypes.md` |
+| 3 | **Numbered actions** | The scoped build steps, in order — what the core will do | archetype + scope |
+| 4 | **Files that will change** | The concrete paths/areas the build touches (additive — APPEND, never replace) | discovery + scope |
+| 5 | **Packages** | The exact package(s) to install, with major pins (the core owns exact coordinates) | modality + framework |
+| 6 | **Credential + auth strategy** | Dev Auth-Key vs prod server-minted auth token, CHOSEN from discovery (§archetypes credential heuristic) | `auth` signal |
+| 7 | **Modify-or-approve gate** | An explicit invitation to EDIT or APPROVE — nothing is written before approval | always |
+
+A plan missing any of the seven is **incomplete** — do not present it or hand off. (This is the onboarding analogue of "dropped a contract min_capability".)
+
+## The template (fill every section; keep it concrete, not generic)
+
+```md
+## CometChat integration plan
+
+### 1. What I found (discovery)
+- Framework:      <value | null>
+- Bundler:        <value | null>
+- Language:       <TypeScript | JavaScript>
+- Package mgr:    <npm | pnpm | yarn | bun | null>
+- Auth:           <nextauth | clerk | firebase | auth0 | supabase | custom | null>
+- Styling:        <tailwind | css-modules | mui | styled-components | chakra | null>
+- State:          <redux | zustand | mobx | recoil | context | null>
+- Routing:        <value | null>
+- SSR/CSR:        <ssr | csr | islands | null>
+- Existing CometChat: <yes (uikit <ver>) | no> · version_conflict: <none | detail>
+- Env file/prefix:    <.env / VITE_ | .env.local / NEXT_PUBLIC_ | … | n/a>
+
+### 2. What you want (intent → CometChat capabilities)
+- Archetype: <1:1/marketplace | support | community | full-messenger | embedded>
+- Modality:  <chat | calls | both>
+- Scope:     <smallest surface | full combined app | embedded panel>
+- Theming:   <auto/follow-OS light+dark (default) | fixed light | fixed dark> + <default tokens | match design system | brand palette | custom>
+- → Capabilities: <the archetype's capability list from archetypes.md, e.g.
+  "1:1 conversations · conversation list · message pane (send/receive + attachments) ·
+   a 'Message seller' entry button">
+
+### 3. What I'll do
+1. <install the packages>
+2. <credentials + env (dev Auth-Key OR prod token path — see §6)>
+3. <init → login → render the scoped surface>
+4. <wire the entry point into the existing app (routing/auth/state reuse)>
+5. <match the existing design system>   ← if styling detected
+6. <calls layer + permissions>          ← if modality includes calls
+7. <…scoped to the archetype; smallest correct set>
+
+### 4. Files that will change (additive — nothing replaced)
+- <path/area 1>
+- <path/area 2>
+- <env file>
+(APPEND only — your existing code is not rewritten.)
+
+### 5. Packages
+- <exact package@major> …   (the framework core owns the exact coordinates + pins)
+
+### 6. Credential + auth strategy
+- <Dev Auth-Key path — get moving now; do NOT ship the Auth Key to prod>
+  OR
+- <Prod server-minted auth token wired to <detected auth>: your backend mints a
+  per-user CometChat auth token; frontend logs in with it. Map <app user id> → CometChat UID.>
+(Credentials are fetched by the framework core at build time — it will OFFER to fetch the App ID/Region/Auth Key from the dashboard (loading the CometChat CLI on demand → `provision`) or let you paste them manually, then write the env itself; this section only states the dev-vs-prod strategy, not the fetch method.)
+
+### 7. Approve or edit
+Edit any part of this plan (change the archetype, add calling, narrow scope, switch the
+credential strategy), or approve to start. **Nothing is written until you approve.**
+```
+
+## After approval — the scoped build directive (hand-off, not part of the plan the user sees)
+On approval, hand the framework core a compact directive naming ONLY the scoped surface:
+```
+build-directive:
+  core: cometchat-<family>-core        # the framework core for the detected framework
+  archetype: 1:1/marketplace
+  modality: chat
+  scope: smallest 1:1 surface (message button → conversation ↔ message pane)
+  credentials: dev-auth-key            # from plan §6
+  touch: [src/features/chat/*, src/components/MessageSellerButton.tsx, .env]
+  also-skills: []                      # only what the plan named (calls / customization / patterns …)
+```
+The core then does credentials + build + verify. For a framework with no shipped core (React Native, Vue, Flutter, iOS, Android — NOT React or Angular, which both ship one), DO NOT emit a directive — state the not-yet-built posture and offer the plan as the hand-off spec.
+
+## Worked example (Next.js marketplace, chat only)
+
+```md
+## CometChat integration plan
+
+### 1. What I found (discovery)
+- Framework: Next.js (App Router) · Bundler: Turbopack/Webpack · Language: TypeScript
+- Package mgr: pnpm · Auth: NextAuth · Styling: Tailwind · State: Zustand
+- Routing: App Router · SSR/CSR: ssr · Existing CometChat: no · version_conflict: none
+- Env file/prefix: .env.local / NEXT_PUBLIC_
+
+### 2. What you want (intent → CometChat capabilities)
+- Archetype: 1:1/marketplace · Modality: chat · Scope: smallest 1:1 surface
+- → Capabilities: 1:1 conversations · conversation list · message pane (send/receive + attachments)
+  · unread + presence · a "Message seller" button off the listing page
+
+### 3. What I'll do
+1. Install the React UI Kit + Chat SDK (major-pinned).
+2. Credentials: prod server-minted auth token wired to NextAuth (Auth Key dev-only to start).
+3. Client-only init → login → render the scoped 1:1 surface (App Router client boundary).
+4. Add a "Message seller" button on the listing page → opens the conversation.
+5. Match the Tailwind design tokens (hand to customization).
+
+### 4. Files that will change (additive)
+- src/app/(chat)/… (a client chat route)
+- src/components/MessageSellerButton.tsx
+- src/lib/cometchat/… (init/login helpers)
+- .env.local
+(APPEND only.)
+
+### 5. Packages
+- The resolved family's `kit_package` (+ `sdk_package` / `calls_package` where the row has them),
+  read from `peers.yaml` — plus that kit's required peer deps. Never hardcode one family's packages.
+
+### 6. Credential + auth strategy
+- Prod server-minted auth token: a Next route mints a per-user CometChat auth token from the
+  NextAuth session; the client logs in with it. Map the NextAuth user id → CometChat UID.
+  Dev Auth-Key is fine locally but never shipped.
+
+### 7. Approve or edit
+Edit any part (add calling, widen to groups, change the credential path), or approve to start.
+Nothing is written until you approve.
+```
+On approval → hand off to `cometchat-<family>-core` with the scoped directive above; pull in `customization` (Tailwind match) and `patterns` (Next App-Router client boundary) because the plan named them — nothing else.

package/skills/cometchat-onboarding/references/platforms.md

@@ -0,0 +1,105 @@
+<!-- family-agnostic: per-platform-by-design — this reference IS the per-family table; lint-skills GATE R
+     requires one entry per shipped family, so naming a single family here is the point, not a defect. -->
+
+# Platform specifics — what differs per platform
+
+This gate is framework-agnostic, but several of its beats have a platform-specific answer. The
+entry keeps the neutral rule; the concrete values live here. Load when you have detected the
+platform. **Every family that ships a `-core` in `peers.yaml` has a column below** — a missing
+column means beat 1 gets improvised (`lint-skills.mjs` checks this table against the shipped cores).
+
+## Detection fields (beat 1) — web
+
+| | Web (React) | Web (Angular) |
+|---|---|---|
+| project marker | `package.json` (`react`, no `react-native`/`expo`) | `package.json` (`@angular/core`) + `angular.json` |
+| dependency manager | npm/pnpm/yarn (from the lockfile) | npm/pnpm/yarn (from the lockfile) |
+| build/bundler | `bundler` · `router` · `ssr_strategy` | Angular CLI (`angular.json` builder); `router` = `@angular/router` |
+| UI framework | React | Angular standalone components (kebab-case selectors) |
+| version floor | `framework_version` | Angular 17–21 (the kit's range — `cometchat-angular-v5-core`) |
+| language | TS / JS | TS |
+| credentials file | `.env` (with the framework's env prefix) | `src/environments/environment.ts` (build-time file replacement — NOT `.env`) |
+| existing integration | `@cometchat/chat-uikit-react` in `package.json` | `@cometchat/chat-uikit-angular` in `package.json` |
+
+## Detection fields (beat 1) — mobile
+
+| | iOS (Swift) | Android (Kotlin) | React Native | Flutter |
+|---|---|---|---|---|
+| project marker | `*.xcodeproj` / `*.xcworkspace` / `Package.swift` | `settings.gradle(.kts)` + `app/build.gradle(.kts)` | `package.json` with `react-native` (+ `expo` ⇒ Expo; `app.json`, `metro.config.js`) | `pubspec.yaml` (+ `pubspec.lock`) |
+| dependency manager | **SPM**. A `Podfile` is a DETECTION signal only — CocoaPods distribution is winding down, so never integrate through it | Gradle (Kotlin DSL or Groovy; version catalog if `gradle/libs.versions.toml`) + the Cloudsmith Maven repo | npm/yarn (lockfile); Expo vs bare decides the `patterns` skill (`expo-patterns` / `bare-patterns`) | pub |
+| build/bundler | not applicable — no bundler, no SSR, no routing story | not applicable — record `android_variant` instead (below) | Metro — no bundler/SSR choice | not applicable |
+| UI framework | **UIKit or SwiftUI** — ask if ambiguous; the shipped kit is UIKit | **`android_variant`: `views` (XML Views → `kotlin-*` skills) or `compose` (Jetpack Compose → `compose-*` skills)** — read it from the compose plugin / `androidx.compose` deps; `mixed`/`unknown` ⇒ ask | React Native components | Flutter widgets |
+| version floor | `deployment_target` (the kit's floor is iOS 15.1) | `minSdk` / `compileSdk` / Kotlin / AGP — **UI Kit v6: minSdk 28, compileSdk 36, Kotlin 2.1, AGP 8.9.1**; **headless Calls SDK v5: minSdk 26** (its TRUE transitive floor — the docs overview's 24 fails the manifest merge; `cometchat-android-v5-calls-sdk`). Read the app's `minSdk` in beat 1 and put the bump in the plan | React Native ≥ 0.77 | Flutter ≥ 3.19, Dart ≥ 3.10.1 |
+| language | Swift | Kotlin (Java is the legacy cohort) | TS / JS | Dart |
+| credentials file | `Config/Secrets.xcconfig` → `Info.plist` → `Bundle.main` | `app/src/main/assets/cometchat-settings.json` (**gitignored**; read by `initFromSettings` — chat, UI Kit AND calls share the ONE file); build-time extras via `local.properties` → `BuildConfig` | `.env` | `cometchat-settings.json` — a **registered asset** in `pubspec.yaml`, not a dotenv file |
+| existing integration | `CometChatUIKitSwift` in `Package.swift` / `Podfile` | any `com.cometchat:` coordinate in `app/build.gradle(.kts)` — `chatuikit-*` (UI Kit v6), `chat-sdk-android` (headless chat), `calls-sdk-android` (headless calls) | `@cometchat/chat-uikit-react-native` in `package.json` | `cometchat_chat_uikit` in `pubspec.yaml` |
+
+There is no `env_prefix` on iOS/Android/Flutter, and no lockfile-derived package manager on
+iOS/Android — asking for either signals the gate was not really platform-aware.
+
+## Follow-the-OS theming (beat 3)
+
+Whether the kit follows the OS by itself DIFFERS per platform — do not assume the web answer:
+
+- **Web (React):** it does NOT. There is no `theme="system"`, so the core syncs `theme` ↔ the
+  `prefers-color-scheme` media query (AUDIT-004).
+- **Web (Angular):** the kit's `initFromPreference()` respects `prefers-color-scheme` and keeps its own
+  `matchMedia` listener — one call, no host observer (`cometchat-angular-v5-customization`).
+- **iOS:** it DOES, with no host code at all. The kit's components override
+  `traitCollectionDidChange` and its palette uses dynamic colours, so light/dark follows the device
+  automatically. Do not offer to "wire up" OS theming on iOS, and do not port the web recipe —
+  `prefers-color-scheme` does not exist outside a web view, and the observer is unnecessary anyway.
+- **Android:** it DEPENDS on the cohort. **Views:** it DOES with no extra code — extend
+  `CometChatTheme.DayNight` (AppCompat DayNight follows the system `uiMode`). **Compose:** it does NOT
+  by itself — the host MUST wrap the kit UI in `CometChatTheme(colorScheme = if (isSystemInDarkTheme())
+  darkColorScheme() else lightColorScheme()) { … }`; with no wrapper the kit renders its light defaults
+  and ignores the OS setting (like the React Native "supply BOTH light and dark" case below, NOT the
+  automatic iOS case). The core Compose golden path emits this wrapper when theming is "Auto — follow
+  OS"; full theming API is `cometchat-android-v6-compose-customization`.
+- **React Native:** supply BOTH `light` and `dark` to the provider; the kit then follows the OS scheme —
+  setting only `light` is the classic bug (`cometchat-react-native-customization`).
+- **Flutter:** Flutter's own `themeMode: ThemeMode.system` — nothing CometChat-specific (`cometchat-flutter-v6-customization`).
+
+## The feature menu (beat 2)
+
+The offered capabilities come from the DETECTED platform's manifest, and they are not the same
+list:
+
+- **Web (React):** `features.json` · **Web (Angular):** `features.angular-v5.json`
+- **iOS:** `features.ios-v5.json`
+- **Android:** `features.android-v6.json` (UI Kit) · `features.sdk-android-v5.json` (headless chat) ·
+  `features.android-calls-v5.json` (headless calling-first — `calling-first.md`)
+- **React Native:** `features.rn-v5.json`
+- **Flutter:** `features.flutter-v6.json`
+
+Never offer a feature the detected platform does not ship. On iOS in particular there is **no
+composite chat component** — the host composes header + list + composer and owns the list ↔ detail
+navigation, so "a chat screen" is a composition task, not a single drop-in. On Android the
+headless calls family is receive-only for screen share and has no virtual background — do not offer either.
+
+## Scope / placement (beat 4)
+
+The placement vocabulary is platform-specific — offer only the shapes that exist on the detected
+platform, never the web menu everywhere:
+
+- **Web (React · Angular):** full-page · **embedded** in an existing route/section · a docked
+  **sidebar / side-panel** · a **popup / floating widget**.
+- **Mobile (iOS · Android · React Native · Flutter):** a **full-screen route** · a dedicated **tab** ·
+  a **pushed navigation-stack screen** (list → detail) · a **modal / bottom-sheet** · **embedded** as a
+  panel inside an existing screen. There is **no sidebar and no popup** on mobile — do not offer them.
+  The concrete recipes live in `cometchat-<family>-placement` (iOS also: iPad split view; Android: the
+  Activity/Fragment flow per `android_variant`).
+
+Default to the SMALLEST reasonable production-ready surface, not the full combined app.
+
+## SDK-fallback lookup
+
+Per-feature fallback resolves through the DETECTED platform's core docs-map, never React's by
+default:
+
+> **Web (React):** `cometchat-react-v7-core/references/docs-map.md`
+> **Web (Angular):** `cometchat-angular-v5-core/references/docs-map.md`
+> **iOS:** `cometchat-ios-core/references/docs-map.md`
+> **Android:** `cometchat-android-v6-core/references/docs-map.md` (UI Kit) · `cometchat-android-v5-sdk/references/docs-map.md` (headless chat) · `cometchat-android-v5-calls-sdk/references/docs-map.md` (headless calls)
+> **React Native:** `cometchat-react-native-core/references/docs-map.md`
+> **Flutter:** `cometchat-flutter-v6-core/references/docs-map.md`