@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/skills/shared/external/app-clips/references/data-handoff-notifications-location.md

@@ -0,0 +1,135 @@
+# App Clip Data Handoff, Notifications, and Location
+
+Use this when implementing App Group/full-app migration, keychain or Sign in with Apple handoff, ephemeral notifications, notification relaunch routing, or physical location confirmation.
+
+## Contents
+
+- [Data Migration to Full App](#data-migration-to-full-app)
+- [Keychain Sharing](#keychain-sharing)
+- [Sign in with Apple](#sign-in-with-apple)
+- [Ephemeral Notifications](#ephemeral-notifications)
+- [Location Confirmation](#location-confirmation)
+- [Lifecycle and Ephemeral State](#lifecycle-and-ephemeral-state)
+
+## Data Migration to Full App
+
+When a user installs the full app, it replaces the App Clip. Use a **shared App Group container** for non-secret data the full app needs:
+
+```swift
+// In both targets: add App Groups capability with the same group ID
+
+// App Clip  -  write non-secret data
+func savePendingOrder(_ order: PendingOrder) throws {
+    guard let containerURL = FileManager.default.containerURL(
+        forSecurityApplicationGroupIdentifier: "group.com.example.myapp.shared"
+    ) else { return }
+
+    let data = try JSONEncoder().encode(order)
+    let fileURL = containerURL.appendingPathComponent("pending-order.json")
+    try data.write(to: fileURL)
+}
+
+// Full app  -  read migrated data
+func loadPendingOrder() throws -> PendingOrder? {
+    guard let containerURL = FileManager.default.containerURL(
+        forSecurityApplicationGroupIdentifier: "group.com.example.myapp.shared"
+    ) else { return nil }
+
+    let fileURL = containerURL.appendingPathComponent("pending-order.json")
+    guard FileManager.default.fileExists(atPath: fileURL.path) else { return nil }
+    let data = try Data(contentsOf: fileURL)
+    return try JSONDecoder().decode(PendingOrder.self, from: data)
+}
+```
+
+### Shared UserDefaults
+
+Use shared defaults for small, non-secret state such as identifiers, timestamps, feature choices, or pending-cart metadata:
+
+```swift
+let shared = UserDefaults(suiteName: "group.com.example.myapp.shared")
+shared?.set(orderID, forKey: "pendingOrderID")
+```
+
+Any app or extension target provisioned with the same App Group entitlement can read and write the shared container and shared defaults suite. Treat App Group storage as a convenience handoff channel, not a trust boundary. Do not put passwords, refresh tokens, payment credentials, or other secrets in shared containers or shared defaults.
+
+## Keychain Sharing
+
+Starting in iOS 15.4, the full app can access keychain items created by its corresponding App Clip when the App Clip and full app have the correct association entitlements. This is one-way: the App Clip cannot read keychain items created by the full app. Use labels, service names, or account naming to distinguish App Clip-created items before migration.
+
+## Sign in with Apple
+
+Store the `ASAuthorizationAppleIDCredential.user` identifier in the shared container so the full app can verify the account without re-prompting unnecessarily:
+
+```swift
+let provider = ASAuthorizationAppleIDProvider()
+provider.getCredentialState(forUserID: userID) { state, error in
+    if state == .authorized {
+        // Continue full-app account migration.
+    }
+}
+```
+
+## Ephemeral Notifications
+
+App Clips can request ephemeral notification authorization by setting `NSAppClipRequestEphemeralUserNotification` in the App Clip target's `NSAppClip` `Info.plist` dictionary. The authorization can last up to 8 hours after each launch, but users can disable it from the App Clip card. Before scheduling, check `UNUserNotificationCenter` settings and require `authorizationStatus == .ephemeral`.
+
+A notification tap relaunches the App Clip without the original invocation URL. For multi-experience App Clips, include a target content identifier so the App Clip can route after notification relaunch. Use a URL matching the relevant App Store Connect advanced App Clip experience, not an arbitrary opaque ID:
+
+- Remote notifications: APNs `target-content-id`
+- Local notifications: `UNNotificationContent.targetContentIdentifier`
+
+## Location Confirmation
+
+Use `APActivationPayload` to verify a user's physical location without requesting full location access. The confirmation region can have a radius up to 500 meters:
+
+```swift
+import AppClip
+import CoreLocation
+
+func verifyLocation(from activity: NSUserActivity) {
+    guard let payload = activity.appClipActivationPayload else { return }
+
+    let center = CLLocationCoordinate2D(latitude: 37.334722, longitude: -122.008889)
+    // Apple allows a confirmation region radius up to 500 meters.
+    let region = CLCircularRegion(center: center, radius: 100, identifier: "store-42")
+
+    payload.confirmAcquired(in: region) { inRegion, error in
+        if let error = error as? APActivationPayloadError {
+            switch error.code {
+            case .doesNotMatch:
+                break
+            case .disallowed:
+                break
+            @unknown default:
+                break
+            }
+            return
+        }
+
+        if inRegion {
+            routeToInStoreExperience()
+        }
+    }
+}
+```
+
+Enable location confirmation in the App Clip target's `Info.plist`, not the full app's:
+
+```xml
+<key>NSAppClip</key>
+<dict>
+    <key>NSAppClipRequestLocationConfirmation</key>
+    <true/>
+</dict>
+```
+
+This is lightweight: the system confirms whether the invocation is within your registered physical region without granting continuous location access. The App Clip card discloses that the clip can verify location. Available iOS 14.0+.
+
+## Lifecycle and Ephemeral State
+
+- **No Home Screen icon**  -  App Clips appear in the App Library and recent apps.
+- **Automatic removal**  -  the system may remove unused App Clips and their data after a limited, system-determined period.
+- **No persistent state guarantee**  -  treat App Clip local storage as ephemeral; migrate important non-secret data to the shared container or a server.
+- **Relaunching**  -  returning from the App Library uses the last invocation URL; returning from the App Switcher launches without an invocation URL, so restore saved state.
+- **Location access**  -  use when-in-use authorization only; App Clip location authorization is short-lived and resets.

package/pipeline/skills/shared/external/app-clips/references/routing-and-experiences.md

@@ -0,0 +1,125 @@
+# App Clip Routing and Experiences
+
+Use this when implementing invocation URL routing, App Store Connect experiences, Local Experiences, Safari Smart App Banners, QR/NFC/App Clip Codes, AASA, or associated domains.
+
+## Contents
+
+- [Invocation URL Handling](#invocation-url-handling)
+- [App Clip Experience Configuration](#app-clip-experience-configuration)
+- [Invocation Methods](#invocation-methods)
+- [Safari Smart App Banner](#safari-smart-app-banner)
+- [Local Testing](#local-testing)
+
+## Invocation URL Handling
+
+App Clips receive an `NSUserActivity` of type `NSUserActivityTypeBrowsingWeb`. Route from the invocation URL and keep the same router available to the full app.
+
+### SwiftUI
+
+```swift
+@main
+struct DonutShopClip: App {
+    var body: some Scene {
+        WindowGroup {
+            ContentView()
+                .onContinueUserActivity(NSUserActivityTypeBrowsingWeb) { activity in
+                    handleInvocation(activity)
+                }
+        }
+    }
+
+    private func handleInvocation(_ activity: NSUserActivity) {
+        guard let url = activity.webpageURL,
+              let components = URLComponents(url: url, resolvingAgainstBaseURL: true)
+        else { return }
+
+        let locationID = components.queryItems?
+            .first(where: { $0.name == "location" })?.value
+
+        routeToLocation(id: locationID)
+    }
+}
+```
+
+### UIKit scenes
+
+For UIKit scene-based apps, distinguish notification from handling:
+
+- Cold launch: inspect `connectionOptions.userActivities` in `scene(_:willConnectTo:options:)`.
+- Continued activity: handle the actual `NSUserActivity` in `scene(_:continue:)`.
+- Relaunch warning: `scene(_:willContinueUserActivityWithType:)` can tell you a continuation is coming, but it does not provide the activity or URL.
+
+**Key rule:** The full app must handle every invocation URL the App Clip supports. After a user installs the full app, it replaces the App Clip and receives future invocations.
+
+## App Clip Experience Configuration
+
+Configure experiences in **App Store Connect** after uploading a build containing the App Clip.
+
+### Default App Clip experience
+
+- Required for every App Clip.
+- Provide: header image, subtitle, and call-to-action verb.
+- App Store Connect generates a **default App Clip link** with an `appclip.apple.com` URL.
+- Supports web and shared-link invocation; QR and NFC can encode links, but count as physical triggers for size-policy decisions.
+
+### Demo App Clip link
+
+- Auto-generated by App Store Connect for demo versions of your app.
+- Supports NFC tags and QR codes for testing physical invocations.
+- App Clip Codes require the short version of the demo App Clip link.
+- Does not replace Maps, Smart App Banners, or website App Clip cards.
+- Can use the larger current App Clip binary limit.
+- Cannot contain URL parameters.
+
+### Advanced App Clip experiences
+
+- Required for: Maps integration, location association, per-location card imagery, and precise physical-place routing.
+- Normal production path for App Clip Codes; demo App Clip Codes require the short demo link.
+- Each experience has its own invocation URL, header image, and metadata.
+- URL **prefix matching** lets one registered URL cover many sub-paths.
+- Use the App Store Connect API to manage large numbers of experiences programmatically.
+
+### Associated domains
+
+For custom URLs, add entries to the Associated Domains entitlement on both the full app and App Clip targets, and host an AASA file:
+
+```text
+appclips:example.com
+```
+
+## Invocation Methods
+
+| Method | Requirements |
+|---|---|
+| **App Clip Codes** | Advanced experience for production; short demo App Clip link for demo codes; NFC-integrated or scan-only |
+| **NFC tags** | Encode invocation URL in an NDEF payload; physical trigger for size-policy decisions |
+| **QR codes** | Encode invocation URL; physical trigger for size-policy decisions |
+| **Safari Smart App Banners** | Associate the App Clip with the website and add the banner meta tag |
+| **Maps** | Advanced experience with place association |
+| **Messages** | Share invocation URL as text; demo links have limited preview behavior |
+| **Siri Suggestions** | Location-based; requires advanced experience for location suggestions |
+| **Other apps with Link Presentation** | Can surface App Clip experiences through rich link metadata |
+| **Other apps using SwiftUI `Link` / `UIApplication.open(_:)`** | Open default, associated-website, or demo-link URLs; advanced App Clip experiences are not supported for this launch path |
+
+## Safari Smart App Banner
+
+Add this meta tag to your website to show the App Clip banner:
+
+```html
+<meta name="apple-itunes-app"
+      content="app-id=YOUR_APP_ID, app-clip-bundle-id=com.example.MyApp.Clip,
+               app-clip-display=card">
+```
+
+Use `app-clip-display=card` when the webpage should display the App Clip card in Safari or SFSafariViewController on iOS 15+. Do not rely on `app-argument` for App Clips; Apple documents `app-argument` for full-app Smart App Banners, not App Clip launches.
+
+## Local Testing
+
+Test the invocation path, not just direct Xcode launch:
+
+```swift
+// Use the _XCAppClipURL environment variable in the scheme,
+// or register a Local Experience in Settings → Developer → Local Experiences.
+```
+
+A direct Xcode launch can skip the invocation path and hide routing bugs.

package/pipeline/skills/shared/external/app-clips/references/size-capabilities-and-promotion.md

@@ -0,0 +1,113 @@
+# App Clip Size, Capabilities, and Promotion
+
+Use this before App Clip feasibility reviews or capability audits, and when checking size budgets, measurement, Background Assets, SKOverlay, Live Activities App Clip extension constraints, CloudKit limits, or unsupported capabilities.
+
+## Contents
+
+- [Feasibility Review Template](#feasibility-review-template)
+- [Size Limits](#size-limits)
+- [Background Assets](#background-assets)
+- [SKOverlay for Full App Promotion](#skoverlay-for-full-app-promotion)
+- [Capabilities and Limitations](#capabilities-and-limitations)
+- [Additional Restrictions](#additional-restrictions)
+
+## Feasibility Review Template
+
+For capability reviews, explicitly cover:
+
+- Size basis: deployment target, physical versus digital invocation, reliable-internet expectation, App Thinning Size Report, and demo-link/App Clip Code constraints.
+- Download fit: large bundled media, ML models, catalogs, or required pre-task downloads should move to streaming/server-backed content, post-task assets, or the full app.
+- UX fit: reject marketing-only, ad-heavy, web-view-heavy, install-gated, or launch-blocking App Clip designs.
+- CloudKit boundary: App Clips can read the public database on iOS 16+ with `CloudKit-Anonymous`; do not plan public writes, iCloud Documents, key-value storage, private/shared containers, full CloudKit sync, or durable offline state in the App Clip.
+- Live Activities boundary: App Clip-only widget extension, Live Activities only, App Clip Extension capability, and exact raw entitlement key `com.apple.developer.on-demand-install-capable`; hand implementation details to ActivityKit/WidgetKit.
+- Unsupported runtime features: name App Intents, Background Tasks, background URL sessions, custom URL schemes, in-app purchases, durable persistent local state, SKAdNetwork, and App Tracking Transparency when relevant.
+- Sibling handoff: keep this skill at feasibility and App Clip boundary level; route StoreKit purchases, BackgroundTasks, CloudKit schema/sync, detailed ActivityKit/WidgetKit work, durable credentials, and long-term state to sibling or full-app domains.
+- Depth control: for product/PM feasibility reviews, stop at capability fit, size basis, invocation constraints, and handoff destinations. Describe location confirmation, install promotion, App Group/keychain handoff, and Live Activities conceptually. Do not add Swift package decomposition, API symbols such as `APActivationPayload`, `CLCircularRegion`, or `SKOverlay.AppClipConfiguration`, App Group/keychain implementation recipes, or other API-level implementation guidance unless the user asks for implementation.
+
+## Size Limits
+
+App Clip binaries must stay within strict uncompressed size limits, measured with the App Thinning Size Report:
+
+| Deployment / Invocation Support | Maximum Uncompressed Size |
+|---|---|
+| iOS 15 and earlier | 10 MB |
+| iOS 16 and earlier | 15 MB |
+| iOS 17 and later | 100 MB |
+
+The larger iOS 17+ limit is for digital invocations where a reliable internet connection is likely, when the App Clip does not support physical invocations and does not support iOS 16 or earlier. Physical invocation or iOS 16 support uses a smaller budget. App Store Connect demo links can use the larger limit while supporting NFC tags and QR codes for testing; demo App Clip Codes require the short demo link. Apple has changed App Clip size policy over time, so re-check the current App Store Connect and App Clip documentation before making release-blocking decisions.
+
+**Measure size:** Archive the app → Distribute → Export as Ad Hoc/Development with App Thinning → check `App Thinning Size Report.txt`.
+
+For feasibility reviews, name the size basis explicitly: deployment target, physical versus digital invocation, reliable-internet expectation, and whether demo links or App Clip Codes are in scope.
+
+## Background Assets
+
+Use Background Assets only for content that can arrive after launch without blocking the in-the-moment task. App Clips cannot set a background asset download's priority to essential with `isEssential`. They are a poor fit for large bundled media, ML models, catalogs, or downloads that must finish before useful work. Move those flows to streaming/server-backed content, post-task assets, or the full app.
+
+## SKOverlay for Full App Promotion
+
+Display an overlay recommending the full app from within the App Clip.
+
+### SwiftUI
+
+```swift
+struct OrderCompleteView: View {
+    @State private var showOverlay = false
+
+    var body: some View {
+        VStack {
+            Text("Order placed!")
+            Button("Get the full app") { showOverlay = true }
+        }
+        .appStoreOverlay(isPresented: $showOverlay) {
+            SKOverlay.AppClipConfiguration(position: .bottom)
+        }
+    }
+}
+```
+
+### UIKit
+
+```swift
+func displayOverlay() {
+    guard let scene = view.window?.windowScene else { return }
+
+    let config = SKOverlay.AppClipConfiguration(position: .bottom)
+    let overlay = SKOverlay(configuration: config)
+    overlay.delegate = self
+    overlay.present(in: scene)
+}
+```
+
+`SKOverlay.AppClipConfiguration` resolves to the App Clip's corresponding full app. Available iOS 14.0+.
+
+**Never** block the user's task to force installation  -  show the overlay after task completion.
+
+## Capabilities and Limitations
+
+### Available to App Clips
+
+SwiftUI, UIKit, Core Location (when-in-use), Sign in with Apple, Apple Pay, CloudKit public database reads only with `CloudKit-Anonymous` (iOS 16+), Background Assets, StoreKit `SKOverlay`, Keychain, App Groups, ephemeral notifications, and Live Activities through an App Clip-only widget extension.
+
+### Live Activities
+
+Starting in iOS 16, an App Clip can offer a Live Activity through a widget extension that belongs only to the App Clip. That extension can include only Live Activities, not ordinary widgets, and it needs the App Clip Extension capability. When reviewing this boundary, always name the exact raw entitlement key: `com.apple.developer.on-demand-install-capable`. Keep detailed ActivityKit and WidgetKit implementation guidance in those sibling skills.
+
+### Not available / no runtime functionality
+
+In feasibility reviews, explicitly name restricted or unsupported App Clip runtime features instead of summarizing them generically: App Intents, Background Tasks, background URL sessions, custom URL schemes, in-app purchases, durable persistent local state, SKAdNetwork, App Tracking Transparency, CallKit, Contacts, CoreMotion, EventKit, HealthKit, HomeKit, MediaPlayer, Messages, NearbyInteraction, PhotoKit, SensorKit, and Speech.
+
+## Additional Restrictions
+
+- No background URL sessions.
+- No background Bluetooth.
+- No multiple scenes on iPad.
+- No on-demand resources.
+- No custom URL schemes.
+- No in-app purchases; reserve purchase flows for the full app and StoreKit sibling guidance.
+- No durable local-state guarantee; migrate important non-secret state to a server or full-app handoff.
+- No CloudKit public writes, iCloud Documents, iCloud key-value storage, private containers, or shared containers.
+- No App Clip design that requires install, marketing exposure, web-view navigation, or blocking downloads before the user gets value.
+- Hand off detailed ActivityKit/WidgetKit Live Activity implementation, StoreKit purchase/full-app monetization, BackgroundTasks processing, CloudKit schema or sync beyond public reads, durable credentials, and long-term state to sibling or full-app domains without adding implementation detail here.
+- In feasibility answers, avoid implementation-level Swift package routing, App Group/keychain recipes, location-confirmation API symbols, `SKOverlay` API calls, or framework snippets unless the user explicitly asks for implementation.
+- `UIDevice.name` and `identifierForVendor` return empty strings.