@cometchat/skills 4.4.1 → 5.0.0

package/skills/cometchat-ios-core/references/anti-patterns.md

@@ -0,0 +1,80 @@
+# Anti-patterns — what does NOT exist, and what compiles but is wrong
+
+> Catalog-verified against the shipped 5.1.22 `.swiftinterface`. If a symbol is not in
+> `catalogs/ios-v5.json`, it does not exist in the installed kit — no matter where you saw it.
+
+## 1. v4 composite components — they do not exist in v5
+
+The single most damaging carry-over. These are **v4** names and are NOT in the v5 public API:
+
+- `CometChatConversationsWithMessages`
+- `CometChatUsersWithMessages`
+- `CometChatGroupsWithMessages`
+- `CometChatMessages`
+
+They appeared on v5 documentation pages (tracked as **IOS-DOCS-001**), which is exactly why the
+rule is "verify against the catalog", not "trust a code sample". v5 has **no composite** — the
+host composes header + list + composer itself and owns the navigation. See `layout.md`.
+
+If you find yourself reaching for a one-liner chat screen: there isn't one. That is the design.
+
+## 2. Styles are PROPERTIES, not setters
+
+The kit's API is setter-based and returns `Self`, so `set(...)` is the reflex — but styling is
+not applied that way:
+
+```swift
+// wrong — no such setter
+list.set(style: myStyle)
+
+// right — assign the style property
+list.style = myStyle
+```
+
+Guessing the call form is the most common compile failure. Fetch the component's `.md` twin via
+`docs-map.md` and match the shape exactly.
+
+## 3. `CometChatCallLogs` hands back `Any`
+
+Unlike every other list component, five of its setters pass untyped values. Using them directly
+does not compile — cast first:
+
+```swift
+callLogs.set(onItemClick: { callLog, _ in
+    guard let log = callLog as? CallLog else { return }
+    // …
+})
+```
+
+This is a property of the shipped binary, not a docs error. Treat every `CometChatCallLogs`
+callback parameter as `Any` until proven otherwise.
+
+## 4. The thread trap — two parent APIs
+
+A threaded reply view needs its parent message, and there is more than one way to hand it over.
+Mixing them (setting a parent message id on one component and a parent message object on
+another) yields a view that renders but never sends. Set the parent ONE way, on the component
+the docs prescribe for that surface, and verify by actually sending a reply.
+
+## 5. Assuming the SDK ships with the kit's dependencies resolved
+
+The kit is a prebuilt binary xcframework compiled against ONE `CometChatSDK` version, and SPM
+does **not** resolve that transitively. Pin the exact version. On 5.1.19 the shipped
+`.swiftinterface` also hard-imports `CometChatCallsSDK`, so the Calls SDK must resolve for ANY
+integration to compile — even a chat-only one that never places a call. 5.1.18 built without it,
+so treat this as a packaging regression to state plainly, not as a design requirement to teach.
+
+## 6. Answering API from memory
+
+The kit's surface is largely un-prefixed (`User`, `Group`, `ConversationRequest`), so a
+plausible-looking name is often a real type from a DIFFERENT module — which is why guessing here
+fails silently rather than loudly. Always fetch the `.md` twin via `docs-map.md`. Never read the
+`.swiftinterface` as a substitute for the docs; it is the catalog's source, not user-facing API
+guidance.
+
+## 7. Three things that are NOT like the web UI Kit
+
+Read these before writing any Swift, or you will carry React habits across and they will compile but not work.
+1. **The API is SETTER-based, not prop-based.** `view.set(user: user)`, `view.set(controller: self)` — chained, returning `Self`. There are no props.
+2. **There is NO composite/all-in-one component.** `CometChatMessages`, `CometChatConversationsWithMessages` and friends are **v4** and do not exist in v5 — never emit them, in any file. You compose the chat screen from three components. (Some v5 doc pages still showed them; that is tracked as IOS-DOCS-001 and corrected upstream.)
+3. **The default UX is a NAVIGATION STACK**, not side-by-side panes. The list pushes the chat screen. There is nothing to "collapse on mobile" — iOS is one-pane by construction.

package/skills/cometchat-ios-core/references/docs-map.md

@@ -0,0 +1,123 @@
+# docs-map — CometChat iOS v5: intent → the exact docs page to fetch
+
+## Reaching docs — PREFER the CometChat docs MCP; fetch is the fallback
+The canonical doc channel is the **first-party CometChat docs MCP** — tools `search_cometchat_docs`,
+`fetch_cometchat_doc_page`, and `get_cometchat_implementation_bundle`. **If those tools are connected,
+use them instead of a raw web fetch:**
+- **Find the page** → `search_cometchat_docs(query, version?)` — replaces browsing the scoped `llms-*` index.
+- **Read the page** → `fetch_cometchat_doc_page(path)` — pass the SAME `<path>` the tables below list
+  (the conversations page path for your platform); the MCP resolves the `.md` twin and returns raw Markdown.
+  A full `https://…/docs/<path>` URL also works.
+- **A whole feature/recipe** → `get_cometchat_implementation_bundle(...)` is **NON-AUTHORITATIVE** — curated STATIC recipes that can lag the live docs (verified stale vs v7: e.g. `CometChatConversationsWithMessages`, `css-variables.css`). Treat any bundle as a hint only: RECONCILE it against the `fetch_cometchat_doc_page` result + the pack's hardening; never emit bundle code verbatim.
+
+The MCP reads whatever docs environment it is pointed at (production by default; a preview when repointed),
+so it also carries the environment-swap concern below — no hardcoded host on the skill side.
+
+**If the MCP tools are NOT connected:** add it (`claude mcp add --transport http cometchat-docs https://mcp.cometchat.com/mcp`, or reinstall/enable the plugin) and retry; only if it still will not connect, fall back to a plain fetch via `DOCS_BASE`/`SDK_DOCS_BASE` (defined next).
+Either way the `<path>` catalog in this file is the source of truth for WHICH page — MCP-vs-fetch is only HOW.
+
+## DOCS_BASE — the fetch FALLBACK entry point (⚠️ SWAP HERE to change environments)
+```
+DOCS_BASE     = https://www.cometchat.com/docs
+SDK_DOCS_BASE = https://www.cometchat.com/docs
+```
+> **Fetch rule:** always build a URL as `DOCS_BASE` + the path shown, then append `.md`.
+> Never hardcode a host anywhere else; **never** read the kit's `.swiftinterface`, and never
+> answer API from memory.
+>
+> **Known docs gap (DOCS-BACKLOG.md):** Some iOS v5 pages on production may still document v4
+> composite components (`*WithMessages`) that do not exist in 5.1.22. Verify every symbol against
+> `catalogs/ios-v5.json` before emitting; the catalog is the ground truth, not the docs.
+
+## The convention
+`DOCS_BASE` + `<path>` + `.md` → raw Markdown (verbatim Swift + an "AI Integration Quick Reference"
+block: component, package, props, callbacks).
+```
+Fetch:  {DOCS_BASE}/ui-kit/ios/conversations.md
+```
+Fallback order: `.md` twin → if it 404s, the same URL **without** `.md` (HTML) → **never** the
+`.swiftinterface`, never memory.
+
+## Scoped iOS v5 index
+```
+{DOCS_BASE}/ui-kit/ios/llms-ios-v5.md
+```
+> Covers all 51 iOS UI Kit v5 pages, and its **"Task guides (recipes)"** section is the source for
+> the guide list below. Prefer this index over the site-wide `{DOCS_BASE}/llms.txt` (large; last
+> resort). The twin of React's `llms-react-v7.md` and Angular's `llms-angular-v5.md`.
+> If this path 404s, fall back to the trigger table below.
+
+## SDK docs — the FALLBACK reference (a feature the UI Kit has NO component for)
+The rule of the pack: **for every feature, first check whether the UI Kit has a component for it**
+(the table below + `catalogs/ios-v5.json`). **If it does — USE it. If it does NOT** (AI agents,
+campaigns, moderation, add-members, transient messages, low-level presence, webhooks) **— drop to the
+Chat SDK and call its method directly.** The SDK is already linked under the kit. Look the method up —
+never guess:
+- **SDK index:** prefer the scoped `{SDK_DOCS_BASE}/sdk/ios/llms-ios-v4.md` — it routes every iOS
+  Chat SDK v4 page by intent. If it 404s, fall back to `{SDK_DOCS_BASE}/sdk/ios/overview.md` and
+  the page for the area.
+- **Convention:** `{SDK_DOCS_BASE}/sdk/ios/<page>` + `.md`. Each page opens with an **"AI Integration
+  Quick Reference"** accordion (package · import · key methods) — read that FIRST.
+- **Worked example (the kit ships no component):** adding group members →
+  `{SDK_DOCS_BASE}/sdk/ios/group-add-members.md` →
+  `CometChat.addMembersToGroup(guid:groupMembers:bannedUIDs:onSuccess:onError:)`, driven from a
+  `CometChatUsers` picker in `selectionMode`.
+
+## Don't fetch the hot path — it's baked
+Install, the exact version trio, `init → login → render`, the golden-path composition and its five
+layout rules are BAKED in `cometchat-ios-core`. Fetch ONLY for exhaustive API, long-tail components,
+theming tokens, or feature enablement.
+
+## The 80% trigger table  (URL = `{DOCS_BASE}` + path, then append `.md`)
+| Intent | Path (append `.md`) |
+|---|---|
+| install / init / login / permissions | `/ui-kit/ios/getting-started` |
+| conversation list → chat screen (THE core recipe) | `/ui-kit/ios/ios-conversation` |
+| 1:1 or group chat from a user/group list | `/ui-kit/ios/ios-one-to-one-chat` |
+| tab-based app | `/ui-kit/ios/ios-tab-based-chat` |
+| conversation list (full API) | `/ui-kit/ios/conversations` |
+| message list · composer · header | `/ui-kit/ios/message-list` · `message-composer` · `message-header` |
+| users · groups · group members | `/ui-kit/ios/users` · `groups` · `group-members` |
+| threads | `/ui-kit/ios/threaded-messages-header` |
+| search | `/ui-kit/ios/search` |
+| call buttons · incoming · outgoing · ongoing · logs | `/ui-kit/ios/call-buttons` · `incoming-call` · `outgoing-call` · `ongoing-call` · `call-logs` |
+| calling setup | `/ui-kit/ios/calling-integration` |
+| AI features / assistant history | `/ui-kit/ios/ai-features` · `/ui-kit/ios/ai-assistant-chat-history` |
+| theming: tokens · colors · per-component · bubbles | `/ui-kit/ios/theme-introduction` · `color-resources` · `component-styling` · `message-bubble-styling` |
+| localization · sounds | `/ui-kit/ios/localize` · `/ui-kit/ios/sound-manager` |
+| formatters (mentions · shortcuts) | `/ui-kit/ios/mentions-formatter-guide` · `shortcut-formatter-guide` |
+| message templates | `/ui-kit/ios/message-template` |
+| events | `/ui-kit/ios/events` |
+| extensions (dashboard-gated) | `/ui-kit/ios/extensions` |
+| full component list | `/ui-kit/ios/components-overview` |
+| v4 → v5 upgrade | `/ui-kit/ios/upgrading-from-v4` |
+| push notifications | `/notifications/push-overview` |
+
+## Task guides (recipes) — for a whole FEATURE, BUILD FROM the guide + COMPARE against it
+For a TASK ask (a whole capability, not one component's API), the docs ship **end-to-end guides**. iOS
+has **nine** — more than React:
+`guide-overview` · `guide-new-chat` · `guide-group-chat` · `guide-group-ownership` ·
+`guide-threaded-messages` · `guide-message-privately` · `guide-block-unblock-user` ·
+`guide-call-log-details` · `guide-ai-agent`
+(at `{DOCS_BASE}/ui-kit/ios/<guide>.md`). Use the matching guide **two ways**:
+1. **As the implementation SOURCE** — build the feature from the official recipe, adapted
+   **ADDITIVELY** into the user's app (reuse their navigation, auth and layout; never drop in the
+   guide's standalone shell).
+2. **As a COMPLETENESS check** — after you emit, DIFF your implementation against the guide: every
+   component, call and affordance it shows. Fill any gap.
+
+> **Then apply the baked HARDENING DELTAS — the guide is the BASELINE, not the whole truth.**
+> The guides do not carry the runtime lessons: `set(controller:)` on every component or its
+> affordances are inert; the composer pinned to the **safe-area bottom** (NOT `keyboardLayoutGuide` — the kit composer already handles the keyboard, and double-pinning collapses the list)
+> the recipe shows; explicit vertical division or the list collapses; the host nav bar hidden or you
+> get two headers; and the thread trap — `CometChatThreadedMessageHeader` takes
+> `set(parentMessage:)`; the LIST takes `set(user:parentMessage:withParent:)` (parent in the same
+> call as the target); the composer takes `set(user:)` + `set(parentMessageId:)`.
+
+**No matching guide? → build from this skill's baked golden path** and fetch each component's `.md`
+twin for exact API. The guide is an enhancement when present, never a hard dependency.
+
+## Not in the table?
+Fetch the page from the trigger table nearest your intent, or the site-wide `{DOCS_BASE}/llms.txt`.
+Never guess a path; never read the `.swiftinterface`; never answer API from memory. If a symbol is not
+in `catalogs/ios-v5.json`, it does not exist in v5 — do not emit it, whatever a page says.

package/skills/cometchat-ios-core/references/install.md

@@ -0,0 +1,23 @@
+# Install — Swift Package Manager
+
+The full install detail. The entry keeps only the three pinned versions and the SPM-only rule.
+
+**Use SPM. Do not use CocoaPods and do not offer it as an option**, even if the user's project already has a `Podfile`: CocoaPods distribution is being wound down and its spec repo is going read-only, so a Podfile-based integration cannot receive future releases. A project already on CocoaPods should be moved to SPM as part of adding CometChat.
+
+Add these three packages. The kit is a **prebuilt binary compiled against ONE Chat SDK version** and SPM does not resolve that transitively, so the versions are **exact, not floors** — overriding either side is unsupported and either fails to build or crashes at runtime.
+
+| Package | Repository | Version |
+|---|---|---|
+| `CometChatUIKitSwift` | `https://github.com/cometchat/cometchat-uikit-ios` | **exactly 5.1.22** |
+| `CometChatSDK` | `https://github.com/cometchat/chat-sdk-ios` | **exactly 4.1.7** |
+| `CometChatCallsSDK` | `https://github.com/cometchat/calls-sdk-ios` | **exactly 5.0.3** |
+
+> **All three must be added BY HAND — including the Calls SDK, and including for a chat-only app.**
+> This is a **packaging regression in 5.1.19**, not a design requirement, so treat it as a workaround with a shelf life rather than a permanent rule:
+> - 5.1.19's compiled `.swiftinterface` carries `import CometChatCallsSDK`, and Swift requires every import in an interface to be resolvable — so the module must be present to compile **any** integration, even one with no calling.
+> - Nothing in the kit's **public API actually uses a CallsSDK type** (0 references), and **5.1.16 and 5.1.18 have no such import at all**. It appears in 5.1.19 only. That makes it an internal import leaking into the public interface, not an intentional dependency.
+> - The kit's own `Package.swift` declares **neither** `CometChatSDK` nor `CometChatCallsSDK`, so SPM cannot supply them. Omit the Calls SDK and the build fails with `unable to resolve module dependency: 'CometChatCallsSDK'`.
+>
+> If a future release drops that import, the Calls SDK goes back to being calls-only and belongs to `cometchat-ios-calls`. Re-check the interface before assuming this still applies.
+
+Deployment target **iOS 15.1+**. Add the usage descriptions the kit's media features need to `Info.plist` (camera, microphone, photo library) — see `references/setup-credentials.md`.

package/skills/cometchat-ios-core/references/layout.md

@@ -0,0 +1,186 @@
+# The iOS sizing standard — why each rule exists
+
+> Every rule below was measured on a simulator by the native review harness (iPhone 16 / iOS
+> 18.2, kit 5.1.22), not reasoned across from the web UI Kit. Where a claim is unverified, it
+> says so.
+
+v5 ships **no composite chat component**. The host composes `CometChatMessageHeader` +
+`CometChatMessageList` + `CometChatCompactMessageComposer` and owns the layout. That means the sizing
+below is YOUR responsibility — the kit will not correct it, and every failure here is a RUNTIME
+failure that compiles perfectly.
+
+## Rule 1 — exactly one target
+
+`conversationWith` is a `User` **or** a `Group`, never both. Set one:
+
+```swift
+if let user { list.set(user: user) } else if let group { list.set(group: group) }
+```
+
+Setting both is not a compile error; it produces a surface bound to the wrong conversation.
+
+## Rule 2 — `set(controller:)` is REQUIRED. Omitting it CRASHES the app.
+
+Call `set(controller: self)` on the header, the list and the composer. It hands the kit a
+controller to present its OWN sub-screens from — the action sheet behind a long-press, the media
+picker, the details screen.
+
+**Measured: omitting it is not a degradation, it is a crash.** Long-press any message in a surface
+built without `set(controller:)` and the app dies:
+
+```
+EXC_BREAKPOINT (SIGTRAP) — nil force-unwrap
+  MessagePopupViewController.buildUI()
+  ← CometChatMessageList.onCellLongPressGestureRecognized
+  ← CometChatMessageBubble.onLongPressEnded
+```
+
+The kit force-unwraps the presenting controller it was never given. There is no error, no no-op,
+no degraded mode — the process terminates on a gesture any user will perform within minutes.
+
+**An earlier version of this file said the opposite.** It reported that omitting `set(controller:)`
+"affects neither rendering nor primary navigation" and called the kit's presented sub-screens
+"genuinely untested" — because our own gate only tapped, and a tap never reaches this path. The
+sub-screens were testable all along; the answer is a crash. `Fixtures/broken-no-controller` scored
+WORKING for the entire life of this project while modelling an app that dies on first long-press.
+The gate now long-presses and detects process death, so the fixture fails as it always should have.
+
+The lesson is the one this pack keeps relearning: an untested path reported as "probably fine" is a
+claim, not a measurement. Say "untested" and stop there, or test it.
+
+## Rule 3 — pin to the safe area, top AND bottom
+
+```swift
+headerView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor)
+composerView.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor)
+```
+
+Both anchors come straight from the published recipe. **Do not pin the composer to
+`view.keyboardLayoutGuide.topAnchor`.** `CometChatCompactMessageComposer` does its own keyboard
+adjustment, so that double-applies the offset. Measured on iPhone 16 / iOS 18.2 with the keyboard
+raised:
+
+<!-- Provenance: the table below was measured against `CometChatMessageComposer`, which the golden
+     path used before it moved to the compact composer. The rule carries over because the compact
+     composer self-adjusts the same way — it registers
+     `UIResponder.keyboardWillChangeFrameNotification` and offsets itself (source-verified on
+     master-v5). The numbers are NOT a re-measurement of the compact composer; re-measure before
+     quoting them as such. -->
+
+
+| | safe-area pin (correct) | keyboardLayoutGuide pin |
+|---|---|---|
+| message list | `(0, 109, 393, 267)` — survives | **height 0 — gone** |
+| composer internal stack | on the keyboard top | **`(0, -249, 393, 0)`** |
+
+The user taps to type and the entire conversation disappears, along with the text field they were
+about to type into. It compiles, and it looks perfect until that first tap.
+
+This skill previously taught the keyboardLayoutGuide pin as a "hardening delta" over the docs, and
+asserted it was simulator-verified. That assertion was false: no gate raised the keyboard, so
+nothing could contradict it. The gate now taps the composer and grades whether a list survives
+above the keyboard (`Fixtures/broken-keyboard-double-pin` is the standing regression case).
+
+## Rule 4 — divide the vertical space EXPLICITLY
+
+The list must be pinned top and bottom so it scrolls internally instead of growing its parent:
+
+```swift
+messageListView.topAnchor.constraint(equalTo: headerView.bottomAnchor),
+messageListView.bottomAnchor.constraint(equalTo: composerView.topAnchor),
+```
+
+Without both, the surface collapses to its intrinsic content height. **This is the defect the
+harness catches most often**: a collapsed pane measured 10% of screen height where a correct one
+measures ~90%. It compiles, it mounts, and a launch-only screenshot of the conversation list
+looks perfectly fine — the collapse is one tap away, on the pushed screen.
+
+## Rule 5 — one navigation bar, not two
+
+`CometChatMessageHeader` carries its own title and back control. Left alone, `UINavigationController`
+adds a second bar above it:
+
+```swift
+override func viewDidLoad() {
+    super.viewDidLoad()
+    navigationController?.setNavigationBarHidden(true, animated: false)
+}
+override func viewWillDisappear(_ animated: Bool) {
+    super.viewWillDisappear(animated)
+    navigationController?.setNavigationBarHidden(false, animated: true)   // restore for the list
+}
+```
+
+Hide it on the message screen only, and restore it on the way out — hiding it globally strips
+the conversation list's own bar.
+
+## Navigation, not panes
+
+The web kit's default is side-by-side. iOS composes by NAVIGATION: the conversation list
+pushes the message pane. Wire selection or the list is a dead end:
+
+```swift
+conversations.set(onItemClick: { [weak nav] conversation, _ in
+    let vc = MessagesVC()
+    vc.user  = conversation.conversationWith as? CometChatSDK.User
+    vc.group = conversation.conversationWith as? CometChatSDK.Group
+    nav?.pushViewController(vc, animated: true)
+})
+```
+
+## Surface errors
+
+A failed load and an empty account render the SAME empty list. Wire `set(onError:)` or a
+failure is indistinguishable from "no conversations yet".
+
+### Own the bar centrally — the per-screen recipe does not survive real flows
+
+The published recipe (hide in `viewDidLoad`, restore in `viewWillDisappear`) works for a single
+push and breaks in three flows we measured:
+
+| flow | result |
+|---|---|
+| activate the list's search field, then open a conversation | host bar returns |
+| chat → thread | host bar returns — and on the THREAD screen that is what you want: it has no back control of its own (see below) |
+| pop back thread → chat | chat screen ends with two headers |
+
+Measured on the search flow: `(0,109,393,579)` becomes `(0,199,393,488)` — two headers, 91pt lost.
+
+**Why the obvious fixes fail.** `viewDidLoad` runs once, so it cannot correct a later transition.
+`viewWillAppear` cannot either: the INCOMING screen's `viewWillAppear` runs BEFORE the outgoing
+screen's `viewWillDisappear`, so the restore lands last and clobbers the hide. `isMovingFromParent`
+handles the pushes but not the pop-back.
+
+**What works, measured, with no flash** — decide the bar on the navigation controller:
+
+```swift
+final class NavBarCoordinator: NSObject, UINavigationControllerDelegate {
+    // Hide the bar ONLY on screens whose kit header has its own back control (your composed chat
+    // screen). Do NOT hide it on a pushed thread screen: CometChatThreadedMessageHeader ships NO
+    // back/close of its own (measured — its public surface is hideReceipt/hideBubbleHeader/
+    // hideReplyCount/hideReplyCountBar/hideAvatar plus setters), and edge-swipe does not pop it.
+    // Hiding the host bar there removes the ONLY exit and strands the user. Same rule for any
+    // pushed kit list (CometChatGroupMembers etc.): keep the host bar, hide the KIT's — see the
+    // placement skill.
+    private func shouldHide(_ vc: UIViewController) -> Bool { vc is MessagesVC }   // your chat screens ONLY
+
+    func navigationController(_ nav: UINavigationController, willShow vc: UIViewController, animated: Bool) {
+        nav.setNavigationBarHidden(shouldHide(vc), animated: animated)
+    }
+    func navigationController(_ nav: UINavigationController, didShow vc: UIViewController, animated: Bool) {
+        let want = shouldHide(vc)                       // re-assert ONLY if clobbered, so no flash
+        if nav.isNavigationBarHidden != want { nav.setNavigationBarHidden(want, animated: false) }
+    }
+}
+```
+
+Hold the coordinator somewhere that outlives the push — `UINavigationController.delegate` is weak.
+With it in place the message pane measures `(0,109,393,579)` through all four flows.
+
+**Note on how this was found.** An earlier pass reported the defect with `CometChatSearch` as the
+trigger; a fixture built around presenting and dismissing `CometChatSearch` measured clean every
+time, and this file recorded it as unreproduced. The real trigger is activating the list's OWN
+`UISearchController` — which is simply how a user reaches search, so the original report was right
+about the symptom and wrong about the cause. `Fixtures/broken-navbar-after-search` is the standing
+regression case, and the gate now asserts `navBars == 0` on the message pane, because the collapse
+ratio cannot see this (488/852 = 57%, over the 50% minimum).

package/skills/cometchat-ios-core/references/setup-credentials.md

@@ -0,0 +1,197 @@
+# Setup & credentials (iOS UI Kit v5)
+
+> Verified against `CometChatUIKitSwift` 5.1.22 / `CometChatSDK` 4.1.7. Exact API always comes
+> from the docs `.md` twin via `docs-map.md` — never from memory and never from `.swiftinterface`.
+
+## 1. Detect before you add anything
+
+Read the project, don't ask what you can see:
+
+| Signal | Means |
+|---|---|
+| `Package.swift` / `*.xcodeproj` naming `CometChatUIKitSwift` | already integrated via SPM — REUSE, do not re-add |
+| `Podfile` naming `CometChatUIKitSwift` | integrated via **CocoaPods** — see *version_conflict* below |
+| `*.xcworkspace` present | CocoaPods project; open the workspace, never the `.xcodeproj` |
+| none of the above | greenfield add |
+
+## 2. Credentials — the full chain, including the two steps that make it work
+
+The chain is `Secrets.xcconfig` → build settings → `Info.plist` → `Bundle.main`. Drawing the chain
+is not enough: **an xcconfig that is not ATTACHED to the build configurations substitutes nothing**,
+and `Info.plist` only exposes a value if the key is DECLARED there. Miss either and
+`Bundle.main.infoDictionary` hands back the literal string `$(COMETCHAT_APP_ID)` — which is why the
+guard in step 4 exists, and why omitting these steps drops you straight into the failure it detects.
+
+### Step 0 — get the App ID / Region / Auth Key — OFFER to FETCH first, never default to "paste it yourself"
+Before writing any file, you need three values: **App ID · Region · Auth Key** (Auth Key is dev-only).
+**OFFER to fetch them from the CometChat Dashboard** — load the CLI on demand
+(`@3` pins the CLI major that matches the v5 skills):
+
+```bash
+npx @cometchat/skills-cli@3 auth login
+npx @cometchat/skills-cli@3 provision use --app-id <id> --json
+```
+
+Ask which EXISTING app; never auto-create. **Already have App ID / Region / Auth Key? Just paste them** —
+manual paste is the fallback, not the default. Mint **auth tokens server-side** for production; never
+ship the Auth Key (§4). The CLI is a dashboard/API client only (`auth`/`provision`/`config`/`features`) —
+it does NOT write env files or generate code; this skill does the wiring in Steps 1–5 below.
+
+### Step 1 — write the file (gitignored)
+
+`Config/Secrets.xcconfig`:
+
+```
+COMETCHAT_APP_ID = 123456abcdef
+COMETCHAT_REGION = us
+COMETCHAT_AUTH_KEY = <dev only — see §4>
+```
+
+Add `Config/Secrets.xcconfig` to `.gitignore` **before** you put a real value in it.
+
+> `//` starts a comment in an xcconfig, so any value containing it is silently truncated. Values
+> here are plain identifiers, but keep it in mind if you ever add a URL.
+
+### Step 2 — ATTACH it to the build configurations (the step everyone misses)
+
+*Xcode:* select the **project** (not the target) → **Info** → **Configurations** → expand **Debug**
+and **Release** → set the configuration file to `Secrets.xcconfig`.
+
+*xcodegen* (`project.yml`), at the top level:
+
+```yaml
+configFiles:
+  Debug: Config/Secrets.xcconfig
+  Release: Config/Secrets.xcconfig
+```
+
+Without this the keys are not build settings at all and nothing substitutes them.
+
+### Step 3 — DECLARE the keys in `Info.plist`
+
+Build settings are not visible to your code on their own. Each one you want at runtime must be
+declared as an `Info.plist` entry whose value is the `$(...)` reference.
+
+> **First check whether the project HAS an `Info.plist`.** Since Xcode 13 the default is
+> `GENERATE_INFOPLIST_FILE = YES` and there is no plist file in the project at all. You cannot add
+> a CUSTOM key to a generated plist through build settings — measured on Xcode 16:
+>
+> | build setting | reaches the built `Info.plist`? |
+> |---|---|
+> | `INFOPLIST_KEY_NSCameraUsageDescription` (an Apple-defined key) | **yes** |
+> | `INFOPLIST_KEY_COMETCHAT_APP_ID` (a custom key) | **no — silently dropped** |
+>
+> `INFOPLIST_KEY_*` only understands keys Apple defines. So on a generated-plist project, either
+> add a real `Info.plist` and point `INFOPLIST_FILE` at it, or add the keys through the target's
+> **Info** tab, which makes Xcode create one for you. The §3 usage descriptions below are Apple
+> keys, so those CAN stay as `INFOPLIST_KEY_*` build settings — it is only the `COMETCHAT_*`
+> credentials that need a real file.
+
+```xml
+<key>COMETCHAT_APP_ID</key>
+<string>$(COMETCHAT_APP_ID)</string>
+<key>COMETCHAT_REGION</key>
+<string>$(COMETCHAT_REGION)</string>
+<key>COMETCHAT_AUTH_KEY</key>
+<string>$(COMETCHAT_AUTH_KEY)</string>
+```
+
+### Step 4 — read it back, and fail loudly
+
+An unsubstituted value arrives as the literal `$(COMETCHAT_APP_ID)`, not as `nil` — a
+silent-wrong-value trap, so reject that form explicitly:
+
+```swift
+func credential(_ key: String) -> String? {
+    guard let v = Bundle.main.infoDictionary?[key] as? String,
+          !v.isEmpty, !v.hasPrefix("$(") else { return nil }   // reject the un-substituted form
+    return v
+}
+```
+
+### Step 5 — verify the substitution before blaming CometChat
+
+Build, then print `Bundle.main.infoDictionary?["COMETCHAT_APP_ID"]`. A real App ID means the chain
+works. The literal `$(COMETCHAT_APP_ID)` means step 2 or step 3 is missing — the credentials are
+fine and the wiring is not. An init/login failure here is NOT a CometChat problem.
+
+> For a shipping build, do not carry the Auth Key in the Release configuration at all — see §4.
+
+## 3. `Info.plist` usage descriptions
+
+The kit's media affordances call system pickers, and iOS terminates the app if the matching
+usage string is absent. Add the ones your chosen features actually need:
+
+| Key | Needed by |
+|---|---|
+| `NSCameraUsageDescription` | camera attachments, video calling |
+| `NSMicrophoneUsageDescription` | voice notes, voice/video calling |
+| `NSPhotoLibraryUsageDescription` | image/video attachments |
+
+Write a real sentence for each ("Take photos to send in chat") — App Review rejects placeholders.
+
+## 4. Auth Key vs auth token — the production rule
+
+- **Auth Key** authenticates as ANY user. It is a development convenience only. Shipping it in
+  an app binary hands every account to anyone who unzips the IPA.
+- **Production**: mint an auth token **server-side** and log in with it. The client never holds
+  the Auth Key.
+
+`login(uid:)` does NOT create users. On a fresh app the docs' pre-created test users are
+`cometchat-uid-1 … 5`; for any real app, ASK which UID to use rather than guessing.
+
+## 5. version_conflict
+
+CocoaPods distribution is winding down and its spec repo is going read-only, so **SPM is the
+only supported integration path**. A `Podfile` is a DETECTION signal, never an instruction.
+
+If the project already integrates via CocoaPods, STOP and surface the choice — do not silently
+add SPM alongside it. Two package managers resolving the same binary xcframework is the
+`version_conflict` case: state it, recommend migrating to SPM, and let the user decide.
+
+The kit is a prebuilt binary compiled against ONE SDK version, and SPM does not resolve that
+transitively — pin `CometChatSDK` to the exact version the kit requires, or you get link errors
+that look like missing symbols.
+
+## 6. `cometchat-settings.json` — telemetry attribution
+
+Separate from the xcconfig chain above, and required for CometChat to attribute the integration
+to the skills rather than to a hand-written one.
+
+`CometChatUIKit.initFromSettings` takes **no parameters**. That is not a limitation — it reads a
+JSON file from the app bundle. Create `cometchat-settings.json` and add it to the target's **Copy
+Bundle Resources**:
+
+```json
+{
+  "appId": "<your app id>",
+  "region": "<your region>",
+  "authKey": "<dev only — see §4>",
+  "presenceSubscription": { "type": "ALL_USERS" }
+}
+```
+
+Valid `presenceSubscription.type` values are `ALL_USERS`, `ROLES`, `FRIENDS`, `NONE` — the SDK
+rejects anything else by name. **Gitignore this file**: it carries the Auth Key, exactly like
+`Secrets.xcconfig`.
+
+### Call it BEFORE the classic init, not instead of it
+
+| init path | `integrationSource` | login / render |
+|---|---|---|
+| classic `CometChatUIKit(uiKitSettings:)` alone | *absent* — calls stamped **`"manual"`** | works |
+| `initFromSettings` alone | `"ai-agent"` | **fails — `Err_101`** |
+| `initFromSettings` **then** classic | `"ai-agent"` | works |
+
+Measured on 5.1.19 with the app container wiped between runs. On this version
+`initFromSettings` initialises the Chat SDK but leaves the UI Kit layer uninitialised, so using it
+alone breaks login — a kit defect, and the reason the recipe runs both.
+
+> Why this is worth the extra call: without it every app you build is attributed to
+> `"manual"`. That is not merely missing attribution, it is **wrong** attribution.
+
+> A note on verifying this API: `integrationSource` appears **nowhere** in the shipped
+> `.swiftinterface`, and an earlier version of this pack concluded from that fact that attribution
+> was impossible on iOS. That was wrong. The interface lists which SYMBOLS EXIST; it says nothing
+> about runtime behaviour or where a function's inputs come from. Both facts here came from the
+> shipped binaries and from measuring `UserDefaults`, not from the interface.