@cometchat/skills 4.4.2 → 5.0.1

package/skills/cometchat-ios-troubleshooting/SKILL.md

@@ -1,1003 +1,45 @@
 ---
 name: cometchat-ios-troubleshooting
-description: "Diagnose and fix common CometChat iOS integration issues — build errors, runtime errors, and debugging techniques."
+description: "Diagnose a broken CometChat iOS (Swift) integration — a screen that never populates, credentials read as the literal $(...), login that silently fails, empty lists, no messages, or a version/SDK mismatch. Triggers: 'cometchat ios not working', 'chat screen blank swift', 'cometchat login not working ios', 'credentials not read swift', 'conversations empty ios', 'cometchat swift errors'."
 license: "MIT"
-compatibility: "CometChatUIKitSwift ^5; iOS 13+"
+compatibility: "CometChatUIKitSwift 5.1.22 + CometChatSDK 4.1.7; Xcode 16+; iOS 15.1+; SPM only"
 metadata:
   author: "CometChat"
-  version: "3.0.0"
-  tags: "chat cometchat ios troubleshooting debugging errors fixes"
+  version: "1.0.0"
+  tags: "cometchat ios swift troubleshooting debug diagnostics blank-screen spm"
 ---
 
-> **Ground truth:** `CometChatUIKitSwift ~> 5` (+ `CometChatCallsSDK ~> 5`) — Pods/SPM `.swiftinterface` + `ui-kit/ios`. **Official docs:** https://www.cometchat.com/docs/ui-kit/ios/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them.
+> **Ground truth:** `CometChatUIKitSwift` 5.1.22 + `CometChatSDK` 4.1.7 (symbols verified vs `catalogs/ios-v5.json`); signatures FETCHED via `cometchat-ios-core/references/docs-map.md`; the invariants below (init→login order, credentials flow, SPM-only) are `RULES.md` + `cometchat-ios-core`. This diagnostics catalog is cross-checked against the live `{DOCS_BASE}/ui-kit/ios/troubleshooting.md` page (base + paths in `cometchat-ios-core/references/docs-map.md`), and adds the host-side/runtime symptoms it doesn't cover.
 
-## Purpose
+## Companion skills (read first)
+- `cometchat-ios-core` — the correct init→login→render order, the `Secrets.xcconfig`→Info.plist→`Bundle.main` credential flow, and the SwiftUI launch hook the fixes below restore.
 
-This skill helps diagnose and fix common issues when integrating CometChat iOS UI Kit. It covers build errors, runtime errors, and debugging techniques.
+## Use this skill when
+An iOS CometChat integration compiles but misbehaves at runtime: a screen that never fills, login that does nothing, or empty data.
 
----
-
-## 1. Build Errors
-
-### "No such module 'CometChatUIKitSwift'"
-
-**Cause:** SDK not installed or not linked properly.
-
-**Solutions:**
-
-**CocoaPods:**
-```bash
-# Clean and reinstall
-cd /path/to/your/project
-rm -rf Pods Podfile.lock
-pod install --repo-update
-
-# Open workspace (not project!)
-open YourApp.xcworkspace
-```
-
-**Swift Package Manager:**
-1. In Xcode, go to File → Packages → Reset Package Caches
-2. File → Packages → Resolve Package Versions
-3. Clean build folder: Cmd + Shift + K
-4. Build again
-
-**Check Podfile:**
-```ruby
-platform :ios, '13.0'
-use_frameworks!
-
-target 'YourApp' do
-  pod 'CometChatUIKitSwift', '~> 5.1'
-end
-```
-
----
-
-### "No such module 'CometChatSDK'"
-
-**Cause:** Core SDK not installed alongside UI Kit.
-
-**Solution:** The UI Kit should include the SDK automatically. If not:
-
-```ruby
-# Podfile
-pod 'CometChatUIKitSwift', '~> 5.1'
-pod 'CometChatSDK', '~> 4.0'  # Add explicitly if needed
-```
-
----
-
-### "No such module 'CometChatCallsSDK'"
-
-**Cause:** Calls SDK not installed but code references it.
-
-**Solutions:**
-
-1. **If you need calls:**
-```ruby
-# Podfile
-pod 'CometChatCallsSDK', '~> 5.0'
-```
-
-2. **If you don't need calls:**
-Wrap call-related code in conditional compilation:
-```swift
-#if canImport(CometChatCallsSDK)
-import CometChatCallsSDK
-// Call-related code here
-#endif
-```
-
----
-
-### "Value of type 'CometChatException' has no member 'localizedDescription'"
-
-**Cause:** Using wrong property for error description.
-
-**Solution:** Use `errorDescription` instead of `localizedDescription`:
-
-```swift
-case .onError(let error):
-    print(error.errorDescription)
-    print(error.errorCode)
-```
-
-`CometChatException` has:
-- `errorDescription` — human-readable error message
-- `errorCode` — error code string
-- `details` — optional dictionary with additional info
-
----
-
-### "'CometChatException' is not convertible to 'any Error'"
-
-**Cause:** Trying to use `CometChatException` with Swift's `Result<T, Error>` type.
-
-**Solution:** `CometChatException` does NOT conform to Swift's `Error` protocol. Don't use `Result<T, Error>` with CometChat callbacks. Instead, use direct callbacks:
-
-```swift
-// tier2-expect-error — this block intentionally demonstrates the compile error below
-// ❌ WRONG - Don't use Result<T, Error>
-func login(completion: @escaping (Result<User, Error>) -> Void) {
-    CometChatUIKit.login(uid: uid) { result in
-        switch result {
-        case .success(let user):
-            completion(.success(user))
-        case .onError(let error):
-            completion(.failure(error))  // ERROR: CometChatException is not Error
-        }
-    }
-}
-
-// ✅ CORRECT - Use CometChatException directly
-func login(completion: @escaping (User?, CometChatException?) -> Void) {
-    CometChatUIKit.login(uid: uid) { result in
-        switch result {
-        case .success(let user):
-            completion(user, nil)
-        case .onError(let error):
-            completion(nil, error)
-        @unknown default:
-            completion(nil, nil)
-        }
-    }
-}
-```
-
----
-
-### "Cannot find 'CometChatConversationsWithMessages' in scope" or "Cannot find 'CometChatMessages' in scope"
-
-**Cause:** Neither class exists in the kit. They look like "pre-built composite UIViewControllers" but are NOT exported from `CometChatUIKitSwift`. Older docs and AI-generated guides sometimes claim they exist.
-
-**Solution:** Compose your own `MessagesVC` from the real building blocks (`CometChatMessageHeader` + `CometChatMessageList` + `CometChatMessageComposer`). The pattern is the same one the kit's sample app uses (`SampleApp/View Controllers/CometChat Components/MessagesVC.swift`).
-
-```swift
-import CometChatUIKitSwift
-import CometChatSDK
-
-let conversations = CometChatConversations()
-let navController = UINavigationController(rootViewController: conversations)
-
-conversations.set(onItemClick: { [weak navController] conversation, _ in
-    let messagesVC = MessagesVC()  // your own VC composing CometChatMessageHeader + List + Composer
-    if let group = conversation.conversationWith as? Group {
-        messagesVC.set(group: group)
-    } else if let user = conversation.conversationWith as? User {
-        messagesVC.set(user: user)
-    }
-    navController?.pushViewController(messagesVC, animated: true)
-})
-```
-
-See `cometchat-ios-components` § 13 ("Custom MessagesVC Implementation") for the full `MessagesVC` source.
-
----
-
-### "Cannot find 'CometChatCallLogs' in scope"
-
-**Cause:** `CometChatCallLogs` requires `CometChatCallsSDK` which is not installed.
-
-**Solutions:**
-
-1. **Install the Calls SDK:**
-```ruby
-# Podfile
-pod 'CometChatCallsSDK', '~> 5.0'
-```
-
-2. **Or wrap in conditional compilation:**
-```swift
-#if canImport(CometChatCallsSDK)
-let callLogs = CometChatCallLogs()
-#else
-// Show placeholder or hide calls tab
-#endif
-```
-
----
-
-### "Duplicate symbols" or "Multiple commands produce"
-
-**Cause:** Conflicting dependencies or duplicate frameworks.
-
-**Solutions:**
-
-1. **Clean derived data:**
-```bash
-rm -rf ~/Library/Developer/Xcode/DerivedData
-```
-
-2. **Check for duplicate pods:**
-```bash
-pod deintegrate
-pod install
-```
-
-3. **Check Build Phases:**
-   - Go to Target → Build Phases → Link Binary With Libraries
-   - Remove any duplicate frameworks
-
----
-
-### "The iOS deployment target is set to X.X, but the range of supported deployment target versions is Y.Y to Z.Z"
-
-**Cause:** Minimum iOS version mismatch.
-
-**Solution:**
-
-1. Update your project's deployment target to iOS 13.0 or higher
-2. Update Podfile:
-```ruby
-platform :ios, '13.0'
-```
-
-3. Run:
-```bash
-pod install
-```
-
----
-
-### "Sandbox: rsync.samba denied"
-
-**Cause:** Xcode sandbox permission issue (common in Xcode 15+).
-
-**Solution:**
-
-1. Disable User Script Sandboxing in Build Settings:
-   - Select your app target
-   - Go to Build Settings
-   - Search for "User Script Sandboxing"
-   - Set **ENABLE_USER_SCRIPT_SANDBOXING** to **No**
-
-2. Or add to your `Podfile`:
-```ruby
-post_install do |installer|
-  installer.pods_project.targets.each do |target|
-    target.build_configurations.each do |config|
-      config.build_settings['ENABLE_USER_SCRIPT_SANDBOXING'] = 'NO'
-    end
-  end
-end
-```
-
-3. Then run:
-```bash
-pod install
-```
-
-4. Clean and rebuild:
-```bash
-rm -rf ~/Library/Developer/Xcode/DerivedData
-```
-
----
-
-### "Framework not found" during archive
-
-**Cause:** Framework search paths issue.
-
-**Solution:**
-
-1. Go to Target → Build Settings
-2. Search for "Framework Search Paths"
-3. Add: `$(inherited)` and `$(PROJECT_DIR)/Pods`
-4. Set "Build Active Architecture Only" to No for Release
-
----
-
-## 2. Runtime Errors
-
-### "CometChat is not initialized"
-
-**Cause:** Trying to use CometChat before initialization completes.
-
-**Solution:**
-
-```swift
-// ❌ Wrong - using before init completes
-CometChatUIKit(uiKitSettings: settings) { _ in }
-let conversations = CometChatConversations()  // Too early!
-
-// ✅ Correct - wait for completion
-CometChatUIKit(uiKitSettings: settings) { result in
-    switch result {
-    case .success:
-        DispatchQueue.main.async {
-            let conversations = CometChatConversations()
-            // Now safe to use
-        }
-    case .failure(let error):
-        print("Init failed: \(error)")
-    }
-}
-```
-
----
-
-### "Invalid App ID" or "App not found"
-
-**Cause:** Wrong App ID or region.
-
-**Solutions:**
-
-1. Verify App ID in CometChat Dashboard
-2. Check region matches (us, eu, or in)
-3. Ensure no extra spaces in credentials
-
-```swift
-let uiKitSettings = UIKitSettings()
-    .set(appID: "YOUR_APP_ID")  // No spaces!
-    .set(region: "us")           // Lowercase
-    .build()
-```
-
----
-
-### "Invalid Auth Key"
-
-**Cause:** Wrong or expired Auth Key.
-
-**Solutions:**
-
-1. Get fresh Auth Key from Dashboard → API & Auth Keys
-2. Use the correct key type (Auth Key, not REST API Key)
-3. Check for copy/paste errors
-
----
-
-### "User not found" or "UID not found"
-
-**Cause:** Trying to login with a UID that doesn't exist.
-
-**Solutions:**
-
-1. **Use pre-created test users:**
-   - `cometchat-uid-1` through `cometchat-uid-5`
-
-2. **Create user first:**
-```swift
-let user = User(uid: "new-user-123", name: "John Doe")
-CometChatUIKit.create(user: user) { result in
-    switch result {
-    case .success(let user):
-        // Now login
-        CometChatUIKit.login(uid: user.uid ?? "") { _ in }
-    case .onError(let error):
-        print("Create failed: \(error)")
-    }
-}
-```
-
----
-
-### "Already logged in"
-
-**Cause:** Calling login when user is already logged in.
-
-**Solution:**
-
-```swift
-// Check for existing session first
-if let currentUser = CometChatUIKit.getLoggedInUser() {
-    print("Already logged in as: \(currentUser.name ?? "")")
-    // Proceed to chat UI
-} else {
-    // Login
-    CometChatUIKit.login(uid: "user-123") { _ in }
-}
-```
-
----
-
-### Blank/Empty Conversation List
-
-**Cause:** No conversations exist for the logged-in user.
-
-**Solutions:**
-
-1. **Send a test message:**
-   - Go to CometChat Dashboard → Users
-   - Select another user
-   - Send a message to your logged-in user
-
-2. **Check user is logged in:**
-```swift
-if let user = CometChatUIKit.getLoggedInUser() {
-    print("Logged in as: \(user.uid ?? "")")
-} else {
-    print("Not logged in!")
-}
-```
-
-3. **Check for errors:**
-```swift
-let conversations = CometChatConversations()
-conversations.set(onError: { error in
-    print("Error loading conversations: \(error.errorDescription ?? "")")
-})
-conversations.set(onEmpty: {
-    print("No conversations found")
-})
-```
-
----
-
-### Messages Not Sending
-
-**Cause:** Various issues with message sending.
-
-**Solutions:**
-
-1. **Check user/group is set:**
-```swift
-let composer = CometChatMessageComposer()
-composer.set(user: user)  // Must be set!
-```
-
-2. **Check for errors:**
-```swift
-composer.set(onError: { error in
-    print("Composer error: \((error as? CometChatException)?.errorDescription ?? "")")
-})
-```
-
-3. **Verify network connection:**
-```swift
-import Network
-
-let monitor = NWPathMonitor()
-monitor.pathUpdateHandler = { path in
-    if path.status == .satisfied {
-        print("Connected")
-    } else {
-        print("No connection")
-    }
-}
-monitor.start(queue: DispatchQueue.global())
-```
-
----
-
-### Push Notifications Not Working
-
-**Cause:** Multiple possible issues.
-
-**Checklist:**
-
-1. **Physical device?** Push doesn't work on simulator
-
-2. **Permissions granted?**
-```swift
-UNUserNotificationCenter.current().getNotificationSettings { settings in
-    print("Authorization status: \(settings.authorizationStatus.rawValue)")
-}
-```
-
-3. **Token registered?**
-```swift
-func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
-    let token = deviceToken.map { String(format: "%02.2hhx", $0) }.joined()
-    print("APNs Token: \(token)")
-    
-    // Register with CometChat
-    CometChat.registerTokenForPushNotification(token: token, settings: ["voip": false]) { success in
-        print("Token registered: \(success)")
-    } onError: { error in
-        print("Token registration failed: \(error?.errorDescription ?? "")")
-    }
-}
-```
-
-4. **Certificate uploaded?** Check Dashboard → Notifications → Push Notifications
-
-5. **Correct environment?** Development vs Production certificate must match
-
----
-
-### Calls Not Working
-
-**Cause:** Missing SDK or permissions.
-
-**Checklist:**
-
-1. **CometChatCallsSDK installed?**
-```ruby
-pod 'CometChatCallsSDK', '~> 5.0'
-```
-
-2. **Permissions in Info.plist?**
-```xml
-<key>NSCameraUsageDescription</key>
-<string>Camera access for video calls</string>
-<key>NSMicrophoneUsageDescription</key>
-<string>Microphone access for calls</string>
-```
-
-3. **Background modes enabled?**
-   - Audio, AirPlay, and Picture in Picture
-   - Voice over IP
-
-4. **Testing on real device?** Calls don't work on simulator
-
-5. **Did you call `CometChatCalls.login(...)`?** ⚠️ **On iOS there is NO `CometChatCalls.login`** — the iOS `CometChatCallsSDK` has no `login`/`joinSession`/`SessionSettingsBuilder`. The authority is the vendored `CometChatCallsSDK.swiftinterface` (`generateToken` / `startSession` / `CallSettingsBuilder` / `CallsEventsDelegate`). The `calls-sdk-ios` repo's own `skills/` describe a *different* API and will mislead you — don't follow them. Default calling works through the UI Kit (`CometChatUIKit` calling-enabled) without a separate calls login; for custom calling, use `generateToken` → `startSession`.
-
-### Background push for calls not arriving (Privacy manifest / APNs vs FCM)
-
-**Cause:** Missing privacy manifest, or an APNs-vs-FCM provider mismatch.
-
-**Fix:**
-- Add a **`PrivacyInfo.xcprivacy`** privacy manifest to the app target (required by App Store review; its absence can also break some push/SDK behaviors).
-- Match the **provider** to your token type: if you registered an **APNs** device/VoIP token, the dashboard provider must be **APNs** (`.p8` + Team ID + Key ID, dev-vs-prod environment matching the build); if you route iOS through **FCM**, register with the FCM provider and the `FCM_IOS` platform. A token registered against the wrong provider silently never delivers. See `cometchat-ios-push`.
-
----
-
-### Memory Warnings / Crashes
-
-**Cause:** Memory leaks or retain cycles.
-
-**Solutions:**
-
-1. **Use weak references in closures:**
-```swift
-conversations.set(onItemClick: { [weak self] conversation, _ in
-    self?.openMessages(for: conversation)
-})
-```
-
-2. **Remove listeners when done:**
-```swift
-override func viewWillDisappear(_ animated: Bool) {
-    super.viewWillDisappear(animated)
-    CometChatMessageEvents.removeListener("my-listener")
-}
-```
-
-3. **Profile with Instruments:**
-   - Product → Profile → Leaks
-   - Look for CometChat-related leaks
-
----
-
-### UI Not Updating
-
-**Cause:** Updates happening on background thread.
-
-**Solution:**
-
-```swift
-// Always update UI on main thread
-CometChatUIKit.login(uid: "user-123") { result in
-    DispatchQueue.main.async {
-        switch result {
-        case .success:
-            self.showConversations()
-        case .onError(let error):
-            self.showError(error)
-        }
-    }
-}
-```
-
----
-
-## 3. Debugging Techniques
-
-### Inspect SDK errors
-
-The CometChat iOS SDK has **no public log-level API** (there is no
-`CometChat.setLogLevel` / `AppSettingsBuilder` logging toggle). Diagnose by
-reading the `CometChatException` handed to each call's `onError` closure:
-
-```swift
-CometChat.init(appId: appID, appSettings: settings, onSuccess: { _ in
-    print("CometChat init OK")
-}, onError: { error in
-    // CometChatException → code + message (init's onError is non-optional)
-    print("init failed:", error.errorCode, error.errorDescription)
-})
-```
-
-### Check Connection Status
-
-```swift
-CometChat.addConnectionListener("debug-listener", self)
-
-extension YourClass: CometChatConnectionDelegate {
-    func connected() {
-        print("✅ CometChat connected")
-    }
-    
-    func connecting() {
-        print("🔄 CometChat connecting...")
-    }
-    
-    func disconnected() {
-        print("❌ CometChat disconnected")
-    }
-}
-```
-
-### Monitor Message Events
-
-```swift
-class DebugMessageListener: CometChatMessageDelegate {
-    
-    func onTextMessageReceived(textMessage: TextMessage) {
-        print("📩 Text message received: \(textMessage.text ?? "")")
-    }
-    
-    func onMediaMessageReceived(mediaMessage: MediaMessage) {
-        print("📎 Media message received: \(mediaMessage.messageType)")
-    }
-    
-    func onMessageDeleted(message: BaseMessage) {
-        print("🗑 Message deleted: \(message.id)")
-    }
-}
-
-CometChat.addMessageListener("debug-messages", DebugMessageListener())
-```
-
-### Network Debugging
-
-Use Charles Proxy or Proxyman to inspect CometChat API calls:
-
-1. Install Charles Proxy
-2. Enable SSL Proxying for `*.cometchat.io`
-3. Install Charles certificate on device/simulator
-4. Monitor requests and responses
-
-### Xcode Debugging
-
-**Breakpoints:**
-- Set breakpoints in CometChat callbacks
-- Use symbolic breakpoints for CometChat methods
-
-**Console:**
-```swift
-// Print current state
-print("User: \(CometChatUIKit.getLoggedInUser()?.uid ?? "none")")
-print("Logged in: \(CometChatUIKit.getLoggedInUser() != nil)")
-```
-
----
-
-## 4. Common Error Codes
-
-| Code | Description | Solution |
-|---|---|---|
-| `ERR_UID_NOT_FOUND` | User doesn't exist | Create user first |
-| `ERR_ALREADY_LOGGED_IN` | User already logged in | Check session before login |
-| `ERR_NOT_LOGGED_IN` | No active session | Login first |
-| `AUTH_ERR_AUTH_TOKEN_NOT_FOUND` | Invalid auth token | Generate new token |
-| `ERR_INVALID_APP_ID` | Wrong App ID | Verify in dashboard |
-| `ERR_INVALID_API_KEY` | Wrong API/Auth Key | Get correct key from dashboard |
-| `ERR_BLOCKED_BY_EXTENSION` | Blocked by extension | Check extension settings |
-| `ERR_RATE_LIMIT_EXCEEDED` | Too many requests | Implement rate limiting |
-| `ERR_WEBSOCKET_CONNECTION_FAILED` | Connection failed | Check network, retry |
-
----
-
-## 5. Performance Issues
-
-### Slow Conversation Loading
-
-**Solutions:**
-
-1. **Limit initial fetch:**
-```swift
-let conversations = CometChatConversations()
-conversations.set(conversationsRequestBuilder: ConversationRequest.ConversationRequestBuilder()
-    .set(limit: 20)  // Reduce initial load
-)
-```
-
-2. **Enable pagination:**
-Conversations automatically paginate. Ensure you're not fetching all at once.
-
-### Slow Message Loading
-
-**Solutions:**
-
-1. **Limit message fetch:**
-```swift
-let messageList = CometChatMessageList()
-messageList.set(messagesRequestBuilder: MessagesRequest.MessageRequestBuilder()
-    .set(uid: user.uid ?? "")
-    .set(limit: 30)  // Reduce initial load
-)
-```
-
-2. **Hide unnecessary features:**
-```swift
-messageList.hideReceipts = true  // If not needed
-messageList.hideAvatar = true    // If not needed
-```
-
-### High Memory Usage
-
-**Solutions:**
-
-1. **Release unused view controllers:**
-```swift
-// Don't keep strong references to dismissed VCs
-```
-
-2. **Clear image cache if needed:**
-```swift
-// CometChat handles image caching internally
-// But you can clear URLCache if needed
-URLCache.shared.removeAllCachedResponses()
-```
-
----
-
-## 6. SwiftUI-Specific Issues
-
-### View Not Updating
-
-**Cause:** SwiftUI not detecting state changes.
-
-**Solution:**
-
-```swift
-struct ChatView: View {
-    @State private var selectedConversation: Conversation?
-    
-    var body: some View {
-        ConversationsWrapper(selectedConversation: $selectedConversation)
-            .onChange(of: selectedConversation) { newValue in
-                // Handle selection
-            }
-    }
-}
-
-struct ConversationsWrapper: UIViewControllerRepresentable {
-    @Binding var selectedConversation: Conversation?
-    
-    func makeUIViewController(context: Context) -> CometChatConversations {
-        let vc = CometChatConversations()
-        vc.set(onItemClick: { conversation, _ in
-            selectedConversation = conversation
-        })
-        return vc
-    }
-    
-    func updateUIViewController(_ uiViewController: CometChatConversations, context: Context) {
-        // Handle updates if needed
-    }
-}
-```
-
-### Navigation Issues
-
-**Cause:** Mixing UIKit navigation with SwiftUI.
-
-**Solution:**
-
-```swift
-struct ChatNavigationView: View {
-    @State private var path = NavigationPath()
-    
-    var body: some View {
-        NavigationStack(path: $path) {
-            ConversationsView(onSelect: { conversation in
-                path.append(conversation)
-            })
-            .navigationDestination(for: Conversation.self) { conversation in
-                MessagesView(conversation: conversation)
-            }
-        }
-    }
-}
-```
-
----
-
-## 7. Quick Fixes Checklist
-
-When something isn't working:
-
-1. [ ] **Clean build:** Cmd + Shift + K
-2. [ ] **Delete derived data:** `rm -rf ~/Library/Developer/Xcode/DerivedData`
-3. [ ] **Reinstall pods:** `pod deintegrate && pod install`
-4. [ ] **Check credentials:** App ID, Auth Key, Region
-5. [ ] **Check user exists:** Use test users or create first
-6. [ ] **Check network:** Device has internet connection
-7. [ ] **Check permissions:** Camera, microphone, notifications
-8. [ ] **Check main thread:** UI updates on main thread
-9. [ ] **Check completion handlers:** Wait for async operations
-10. [ ] **Inspect errors:** read the `CometChatException` in each call's `onError` (`errorCode` + `errorDescription`) — the SDK has no log-level toggle
-
----
-
-## 8. Theming Errors
-
-### "Value of type 'MessageBubbleStyle' has no member 'outgoingBackgroundColor'"
-
-**Cause:** Incorrect property access for message bubble styles.
-
-**Solution:** Message bubble styles use separate `.incoming` and `.outgoing` style objects, not combined properties:
-
-```swift
-// ✅ CORRECT - Use separate incoming/outgoing styles
-CometChatMessageBubble.style.outgoing.backgroundColor = CometChatTheme.primaryColor
-CometChatMessageBubble.style.incoming.backgroundColor = CometChatTheme.neutralColor300
-
-// For text colors within bubbles
-CometChatMessageBubble.style.outgoing.textBubbleStyle.textColor = .white
-CometChatMessageBubble.style.incoming.textBubbleStyle.textColor = CometChatTheme.textColorPrimary
-```
-
----
-
-### "Value of type 'ConversationsStyle' has no member 'titleColor'"
-
-**Cause:** Using incorrect property names for component styles.
-
-**Solution:** Check the actual property names in the style struct:
-
-```swift
-// ✅ CORRECT ConversationsStyle properties
-CometChatConversations.style.listItemTitleTextColor = CometChatTheme.textColorPrimary
-CometChatConversations.style.listItemTitleFont = CometChatTypography.Heading4.medium
-CometChatConversations.style.listItemSubTitleTextColor = CometChatTheme.textColorSecondary
-CometChatConversations.style.listItemSubTitleFont = CometChatTypography.Body.regular
-```
-
----
-
-### "Value of type 'MessageComposerStyle' has no member 'inputBackgroundColor'"
-
-**Cause:** Using incorrect property names for composer style.
-
-**Solution:** Use the correct property names:
-
-```swift
-// ✅ CORRECT MessageComposerStyle properties
-CometChatMessageComposer.style.composeBoxBackgroundColor = CometChatTheme.backgroundColor01
-CometChatMessageComposer.style.composeBoxBorderColor = CometChatTheme.borderColorDefault
-CometChatMessageComposer.style.placeHolderTextColor = CometChatTheme.textColorTertiary
-CometChatMessageComposer.style.textFiledColor = CometChatTheme.textColorPrimary
-CometChatMessageComposer.style.activeSendButtonImageBackgroundColor = CometChatTheme.primaryColor
-```
-
----
-
-### "Value of type 'BadgeStyle' has no member 'cornerRadius'" (type mismatch)
-
-**Cause:** `BadgeStyle.cornerRadius` is `CometChatCornerStyle?`, not a simple value.
-
-**Solution:**
-
-```swift
-// ✅ CORRECT - cornerRadius is optional CometChatCornerStyle
-CometChatBadge.style.cornerRadius = CometChatCornerStyle(cornerRadius: 8)
-// or nil for default pill shape
-CometChatBadge.style.cornerRadius = nil
-```
-
----
-
-### "Cannot assign value of type 'UIColor' to type 'CGColor'"
-
-**Cause:** `BadgeStyle.borderColor` is `CGColor`, not `UIColor`.
-
-**Solution:**
-
-```swift
-// ✅ CORRECT - use .cgColor
-CometChatBadge.style.borderColor = UIColor.clear.cgColor
-CometChatBadge.style.borderColor = UIColor.white.cgColor
-```
-
----
-
-### Theme Changes Not Applying
-
-**Cause:** Theme configured after UI is already displayed.
-
-**Solution:** Configure theme before showing any CometChat UI:
-
-```swift
-// In AppDelegate or App init, BEFORE showing any CometChat views
-func configureTheme() {
-    CometChatTheme.primaryColor = UIColor.systemBlue
-    CometChatTheme.backgroundColor01 = UIColor.systemBackground
-    // ... other theme settings
-}
-
-// Call this before CometChatUIKit.init()
-configureTheme()
-```
-
----
-
-### "Type 'CometChatSpacing' has no member 'Spacing1'" or similar
-
-**Cause:** Using incorrect property access for spacing values.
-
-**Solution:** `CometChatSpacing` uses nested classes, not direct properties:
-
-```swift
-// ✅ CORRECT - Use nested class syntax
-CometChatSpacing.Spacing.s1 = 4
-CometChatSpacing.Spacing.s2 = 8
-CometChatSpacing.Padding.p1 = 4
-CometChatSpacing.Padding.p2 = 8
-CometChatSpacing.Radius.r1 = 4
-CometChatSpacing.Radius.r2 = 8
-CometChatSpacing.Radius.rMax = 1000
-CometChatSpacing.Margin.m1 = 4
-```
-
----
-
-### "Cannot infer type of closure parameter" or "Cannot infer contextual base"
-
-**Cause:** Missing type annotations in closures for custom views.
-
-**Solution:** Always provide explicit type annotations for closure parameters:
-
-```swift
-import CometChatSDK
-
-// ✅ CORRECT - Explicit type annotation
-users.set(subtitle: { (user: User?) -> UIView in
-    let label = UILabel()
-    if user?.status == .online {
-        label.text = "Online"
-        label.textColor = .systemGreen
-    } else {
-        label.text = "Offline"
-        label.textColor = .gray
-    }
-    return label
-})
-```
-
-Note: Use `set(subtitle:)` method, not direct property assignment. The `User` type is from `CometChatSDK`.
-
----
-
-### "Value of type 'CometChatUsers' has no member 'subtitleView'"
-
-**Cause:** Using wrong property name.
-
-**Solution:** `CometChatUsers` uses `subtitle`, not `subtitleView`:
-
-```swift
-// ✅ CORRECT
-users.set(subtitle: { (user: User?) -> UIView in
-    // Return custom view
-})
-
-// Different components use different names:
-// - CometChatUsers: set(subtitle:)
-// - CometChatConversations: set(subtitleView:)
-// - CometChatMessageHeader: set(subtitleView:)
-```
-
----
-
-## 10. Getting Help
-
-### CometChat Resources
+## Start here — iOS fails SILENTLY, on ORDER and CREDENTIALS
+The two dominant causes of "the screen never populates":
+1. **`login()` was called before `initFromSettings` resolved.** Both are async and must COMPLETE in order; login-before-init fails with no crash and no visible error — just a screen that never loads (`cometchat-ios-core`).
+2. **Credentials came through as the literal `$(COMETCHAT_APP_ID)`.** The `Secrets.xcconfig` → attach-to-configs → declare-in-Info.plist → read-via-`Bundle.main` chain has four steps; miss one and you init with the literal placeholder, which then fails auth.
 
-- **Documentation:** https://www.cometchat.com/docs/ios-uikit
-- **GitHub Issues:** https://github.com/cometchat/cometchat-uikit-ios/issues
-- **Support:** https://www.cometchat.com/support
+## Symptom → cause → fix
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| Screen never populates, no error | `login` before `init` resolved | Chain them: call login only inside the init completion (`cometchat-ios-core` `references/swiftui.md`) |
+| Auth fails immediately | Wrong Region, or creds read as `$(...)` | Region must match the dashboard app; verify `Bundle.main` returns the value, not the literal `$(` |
+| Values are the literal `$(...)` | `xcconfig` not attached, or Info.plist key missing | Attach `Secrets.xcconfig` to the build configs AND declare each key in Info.plist (`references/setup-credentials.md` §2-§3) |
+| SPM won't resolve / kit crashes at runtime | `CometChatSDK` version drifted from the kit's exact pin | Pin CometChatUIKitSwift 5.1.22 + CometChatSDK 4.1.7 + CometChatCallsSDK 5.0.3 exactly (`cometchat-ios-core` Install) |
+| Build fails after adding a Podfile | Tried CocoaPods | SPM only — a Podfile is a detection signal, not an instruction; remove the pod integration |
+| Conversations empty | New app has no conversations, or wrong scope | Send a first message; check the request scope |
+| `login` "user not found" | UID does not exist in the app | Use a real UID (Dashboard → Users; fresh apps seed `cometchat-uid-1`) — never a guessed `superhero*` |
+| Calls fail / no permission prompt | Missing usage-description strings or VoIP entitlement | Add `NSCameraUsageDescription` + `NSMicrophoneUsageDescription`; enable the VoIP entitlement (`cometchat-ios-push`/`-calls`) |
+| Works in dev, fails in release | Auth Key stripped for release but still using `login(uid:)` | Switch to `login(authToken:)` with a server token (`cometchat-ios-production`) |
 
-### Information to Include in Bug Reports
+## When the table does not cover it
+Enable SDK logging and read the Xcode console: an init/lifecycle error (a call made before `init()` resolved) is the usual "nothing renders" cause; auth errors are almost always Region or a literal-placeholder credential. Then fetch the feature's page via `cometchat-ios-core/references/docs-map.md`. Never diagnose from the binary framework's headers or from memory — fetch the documented signature.
 
-1. CometChatUIKitSwift version
-2. iOS version
-3. Xcode version
-4. Device (simulator or physical)
-5. Error message / stack trace
-6. Steps to reproduce
-7. Relevant code snippets
+## Verify it works
+init and login both resolve (in order) before the chat screen renders · `Bundle.main` returns real credential values, not `$(...)` · the exact kit/SDK versions are pinned · conversations render or show the empty state · a message sends and arrives · calls prompt for permission.
 
+## What NOT to do
+Do not hard-code credentials to get past the `$(...)` literal — fix the xcconfig/Info.plist chain; do not add CocoaPods to work around an SPM resolve issue — pin the exact versions; do not hard-code a UID to dodge "user not found."