motasem-userpilot · Sep 27, 2026 · Jun 30, 2026 · Jul 7, 2026 · Jul 8, 2026 · Jul 8, 2026
diff --git a/.github/workflows/ci.yml → .github/workflows/quality-gate.yml b/.github/workflows/ci.yml → .github/workflows/quality-gate.yml
@@ -15,7 +15,7 @@
 #
 # Only the SDK is built here — the Sample/ apps are covered by publish-sample.yml.
 
-name: CI
+name: Quality Gate
 
 on:
   pull_request:
@@ -25,7 +25,7 @@ on:
 
 # 🛑 A new push to the same PR/branch supersedes the previous run
 concurrency:
-  group: ci-${{ github.workflow }}-${{ github.ref }}
+  group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 permissions:

diff --git a/.gitignore b/.gitignore
@@ -63,7 +63,8 @@ fastlane/test_output
 # Mac OS X
 *.DS_Store
 
-# AI agent tooling (Cursor / Claude / local agent memory)
+# AI agent tooling (local while evaluating — not tracked)
+# Keeps files on disk across branch switches; use git rm --cached if they were previously tracked.
 .agents/
 .claude/
 .cursor/
@@ -72,3 +73,8 @@ CLAUDE.md
 
 # Locally generated agent specs/plans — not project documentation
 docs/superpowers/
+plan/
+
+# Local GitHub Actions cleanup helper and audit records
+/scripts/cleanup-github-actions.py
+/.local/github-actions-cleanup/
diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 # Userpilot iOS SDK
 
 ![version](https://img.shields.io/github/v/tag/Userpilot/ios-sdk?label=version)
-[![Documentation](https://img.shields.io/badge/Documentation-blue.svg)](https://docs.userpilot.com/article/313-install-userpilot-on-your-ios-app)
+[![Documentation](https://img.shields.io/badge/Documentation-blue.svg)](https://docs.userpilot.com/developer/installation/mobile/ios/installation)
 [![Swift Package Manager compatible](https://img.shields.io/badge/Swift%20Package%20Manager-compatible-brightgreen.svg)](https://github.com/apple/swift-package-manager)
 [![CocoaPods compatible](https://img.shields.io/badge/CocoaPods-compatible-red.svg)](https://cocoapods.org/pods/Userpilot)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/Userpilot/ios-sdk/blob/main/LICENSE)
@@ -25,6 +25,8 @@ This document provides a step-by-step walkthrough of the installation and initia
     - [Initializing](#initializing)
     - [Using the SDK](#using-the-SDK)
     - [Configurations](#configurations-optional)
+    - [Scan QR Code for Review](#scan-qr-code-for-review)
+    - [Offline Mode](#offline-mode)
     - [Auto Capture](#auto-capture)
     - [Push Notification](#push-notification)
     - [Multi-Instance Support](#multi-instance-support)
@@ -66,6 +68,8 @@ Before you begin, ensure your iOS project meets the following requirements:
 
 Once integrated, the Userpilot SDK is available throughout your application.
 
+See the official [iOS SDK release notes](https://docs.userpilot.com/developer/installation/mobile/ios/mobile-ios-release-notes) for version history and upgrade details.
+
 ### Initializing
 
 To use Userpilot, initialize it once in your App Delegate or Scene Delegate during app launch. This ensures the SDK is ready as soon as your app starts. Replace `<APP_TOKEN>` with your Application Token, which can be fetched from your [Environments Page](https://run.userpilot.io/environment).
@@ -187,11 +191,13 @@ userpilot.triggerExperience("<EXPERIENCE_ID>")
 
 If you have additional configuration needs, you can pass a custom configuration when initializing Userpilot. You can enable logging, provide navigation and experience delegates, and set up analytics listeners.
 
+Interaction value capture is disabled by default. Call `.enableInteractionValueCapture(true)` on the configuration to capture control values when interaction autocapture is enabled.
+
 ```swift
 userpilot = Userpilot(
     config: Userpilot.Config(token: "APP_TOKEN")
-        .logging(true) // Enable or disable logging.
-        .enableUseInAppBrowser(enabled: true) // Enable Open external link In-app browser using SFSafariViewController.
+        .logging(enabled: true) // Enable or disable logging.
+        .enableUseInAppBrowser(true) // Enable Open external link In-app browser using SFSafariViewController.
         .disableRequestPushNotificationsPermission() // Disable SDK push permission request flow (default false).
 )
 userpilot.navigationDelegate = self
@@ -210,7 +216,18 @@ public protocol UserpilotNavigationDelegate: AnyObject {
 }
 ```
 
-The Userpilot SDK automatically handles navigation if you haven't implemented the `UserpilotNavigationHandler`. When a deep link is external, the SDK will handle it appropriately. For complete control over link handling, you can override the `UserpilotNavigationHandler` protocol. This allows you to customize the behavior for all types of links as per your requirements.
+Implement `UserpilotNavigationDelegate` to control link handling. Without a delegate, the SDK opens custom schemes through the system and web links through the system browser or the configured in-app browser.
+
+Assign `userpilot.navigationDelegate` immediately after initializing the SDK,
+and keep a strong reference to the delegate because the SDK holds it weakly.
+Navigation callbacks run on the main thread. In SDK 1.4.0 and later, the latest
+link received during initialization is held until a delegate is assigned or the
+next main-queue turn after initialization. If no delegate is assigned, the SDK
+uses its normal URL-opening behavior. This startup delay does not wait for a
+router that your app initializes asynchronously; buffer the URL in your delegate
+if your navigation UI is not ready.
+
+See the [SDK Callbacks guide](https://docs.userpilot.com/developer/installation/mobile/ios/callbacks#navigation-handler).
 
 #### Analytics Delegate
 
@@ -289,17 +306,29 @@ public protocol UserpilotExperienceDelegate: AnyObject {
 }
 ```
 
+### Scan QR Code for Review
+
+To review a draft Flow or Survey on a real device, configure the Userpilot custom URL scheme and scan the experience QR code from the Mobile Builder. The QR code opens a Userpilot preview link in your app, and the SDK loads the draft experience for review.
+
+See the official [Custom URL Scheme guide](https://docs.userpilot.com/developer/installation/mobile/ios/custom_scheme) for setup and troubleshooting.
+
+### Offline Mode
+
+SDK **1.4.0 and later** automatically stores offline analytics, flow/survey/NPS interactions, and push-notification opens for the current user. Stored events survive app restarts and are sent together when the connection returns. All event types share a **3 MB / 5,000-event** limit; events removed for sending are not retried if that send fails.
+
+See the official [Offline Mode guide](https://docs.userpilot.com/developer/installation/mobile/ios/features#offline-mode) for supported events, exclusions, and delivery limits.
+
 ### Auto Capture
 
 The Userpilot SDK supports automatic capture of screen views and user interaction events. please refer to the [Userpilot Documentation](https://docs.userpilot.com/developer/installation/mobile/ios/installation).
 
 ### Push Notification
 
-Userpilot SDK supports handling push notifications to help you deliver targeted messages and enhance user engagement. For setup instructions, and integration details, please refer to the [Push Notifications Guide](https://docs.userpilot.com/developer/installation/mobile/ios/push-notifications).
+Userpilot SDK supports handling push notifications to help you deliver targeted messages and enhance user engagement. For setup instructions and integration details, see the official [Push Notifications Guide](https://docs.userpilot.com/developer/installation/mobile/ios/push-notifications).
 
 ### Multi-Instance Support
 
-Userpilot iOS SDK supports running multiple independent instances in the same process. Each instance keeps its own analytics, autocapture scope, storage, and experience overlay window isolated from other instances. For setup instructions and routing details, please refer to the [Multi-Instance Guide](Sources/Userpilot/Userpilot.docc/MultiInstance.md).
+Userpilot iOS SDK supports running multiple independent instances in the same process. Each instance keeps its own analytics, autocapture scope, storage, and experience overlay window isolated from other instances. For setup instructions and routing details, see the official [Multi-Instance Guide](https://docs.userpilot.com/developer/installation/mobile/ios/multi-instance).
 
 ## 📝 Documentation