@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

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

@@ -1,120 +1,180 @@
-# App Clip Data Handoff, Notifications, and Location
+# 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.
+Moving state to the full app, signing people in once, notifying them within
+the clip's window, and proving they are where the code is. Summary in
+`../SKILL.md`.
 
-## Contents
+## Handing data to the full app
 
-- [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:
+When someone installs the full app it replaces the clip. Anything non-secret
+the full app should pick up goes into a shared App Group container. Add the
+App Groups capability to both targets with the same group identifier.
 
 ```swift
-// In both targets: add App Groups capability with the same group ID
+import Foundation
 
-// 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)
+struct PendingTicket: Codable {
+    let seat: String
+    let showTime: Date
 }
 
-// Full app  -  read migrated data
-func loadPendingOrder() throws -> PendingOrder? {
-    guard let containerURL = FileManager.default.containerURL(
-        forSecurityApplicationGroupIdentifier: "group.com.example.myapp.shared"
-    ) else { return nil }
+enum SharedDrop {
+    static let group = "group.org.example.tickets"
+
+    static func file() -> URL? {
+        FileManager.default
+            .containerURL(forSecurityApplicationGroupIdentifier: group)?
+            .appending(path: "pending-ticket.json")
+    }
+
+    static func save(_ ticket: PendingTicket) throws {
+        guard let target = file() else { return }
+        try JSONEncoder().encode(ticket).write(to: target, options: .atomic)
+    }
 
-    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)
+    static func load() -> PendingTicket? {
+        guard let source = file(), FileManager.default.fileExists(atPath: source.path()) else {
+            return nil
+        }
+        guard let bytes = try? Data(contentsOf: source) else { return nil }
+        return try? JSONDecoder().decode(PendingTicket.self, from: bytes)
+    }
 }
 ```
 
-### Shared UserDefaults
+The clip calls `save`; the full app calls `load` on first launch. Both return
+early when the container is unavailable (for example, a misconfigured
+entitlement).
 
-Use shared defaults for small, non-secret state such as identifiers, timestamps, feature choices, or pending-cart metadata:
+For small values (identifiers, timestamps, choices, cart metadata), a shared
+defaults suite is enough:
 
 ```swift
-let shared = UserDefaults(suiteName: "group.com.example.myapp.shared")
-shared?.set(orderID, forKey: "pendingOrderID")
-```
+import Foundation
 
-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
+func rememberPendingOrder(_ orderID: String) {
+    UserDefaults(suiteName: "group.org.example.tickets")?.set(orderID, forKey: "pendingOrderID")
+}
+```
 
-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.
+Any target that carries the same App Group entitlement can read and write this
+data. Treat it as a convenience channel, not a trust boundary, and keep
+secrets out of it.
+
+## Keychain
+
+- From iOS 15.4 the full app can read keychain items the clip created. The
+  system uses the association entitlements to make sure only the matching
+  full app gets them: `com.apple.developer.parent-application-identifiers` on
+  the clip and `com.apple.developer.associated-appclip-app-identifiers` on the
+  full app (Xcode adds the latter when you archive).
+- It only works in that direction. The clip cannot read items the full app
+  stored.
+- On iOS 15.3 and earlier the full app cannot see the clip's items at all;
+  use a shared container value or Sign in with Apple instead.
+- Because people install, delete and reinstall, both targets may end up
+  writing the same logical item. Give clip-created items a distinct label,
+  service or account name (for example a `kSecAttrLabel` of `tickets-clip`),
+  and when migrating, detect duplicates, decide which copy wins and delete the
+  rest.
 
 ## 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:
+Store the stable user identifier from `ASAuthorizationAppleIDCredential.user`
+in the shared container. The full app checks that it is still valid instead
+of asking the person to sign in again:
 
 ```swift
-let provider = ASAuthorizationAppleIDProvider()
-provider.getCredentialState(forUserID: userID) { state, error in
-    if state == .authorized {
-        // Continue full-app account migration.
+import AuthenticationServices
+
+func adoptClipAccount(userID: String, onValid: @escaping @Sendable () -> Void) {
+    ASAuthorizationAppleIDProvider().getCredentialState(forUserID: userID) { state, _ in
+        if state == .authorized {
+            onValid()
+        }
     }
 }
 ```
 
-## Ephemeral Notifications
+Anything other than `.authorized` (revoked, not found, transferred) means the
+full app runs its normal sign-in.
 
-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`.
+## Ephemeral notifications
 
-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:
+- Add `NSAppClip` (a dictionary) to the clip's Info.plist and set
+  `NSAppClipRequestEphemeralUserNotification` to `true` inside it.
+- The clip may then schedule or receive notifications for up to 8 hours after
+  each launch.
+- The App Clip card mentions this and people can turn it off there, so check
+  the current status first:
 
-- Remote notifications: APNs `target-content-id`
-- Local notifications: `UNNotificationContent.targetContentIdentifier`
+```swift
+import UserNotifications
+
+func scheduleIfAllowed(_ request: UNNotificationRequest) async throws {
+    let center = UNUserNotificationCenter.current()
+    guard await center.notificationSettings().authorizationStatus == .ephemeral else { return }
+    try await center.add(request)
+}
+```
 
-## Location Confirmation
+- A clip whose job lasts longer than a day can ask for regular notification
+  permission, but a refusal also removes the 8-hour ephemeral window.
+- Tapping a notification relaunches the clip without an invocation URL.
+  Handle that in the clip and in the full app.
+- A clip that serves several places or businesses must tell the system which
+  experience a notification belongs to. Remote pushes set `target-content-id`
+  in the APNs payload; local notifications set
+  `UNNotificationContent.targetContentIdentifier`. The value is a URL that
+  matches the relevant advanced experience, as specific as possible, not an
+  arbitrary token.
 
-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:
+## Location confirmation
+
+`APActivationPayload` (iOS 14+) confirms that a physical invocation (App Clip
+Code, NFC tag or QR code) happened inside a region you name, without giving
+the clip ongoing location access. The region's radius may be at most 500 m.
 
 ```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
-            }
+enum BoothCheck: Sendable {
+    case confirmed, elsewhere, linkMismatch, notAllowed, unknown
+}
+
+func confirmAtBooth(_ activity: NSUserActivity, booth: CLLocationCoordinate2D,
+                    done: @escaping @Sendable (BoothCheck) -> Void) {
+    guard let payload = activity.appClipActivationPayload else {
+        done(.unknown)
+        return
+    }
+    let area = CLCircularRegion(center: booth, radius: 80, identifier: "booth")
+    payload.confirmAcquired(in: area) { inside, failure in
+        guard let failure else {
+            done(inside ? .confirmed : .elsewhere)
             return
         }
-
-        if inRegion {
-            routeToInStoreExperience()
+        guard let reason = failure as? APActivationPayloadError else {
+            done(.unknown)
+            return
+        }
+        switch reason.code {
+        case .doesNotMatch: done(.linkMismatch)
+        case .disallowed: done(.notAllowed)
+        @unknown default: done(.unknown)
         }
     }
 }
 ```
 
-Enable location confirmation in the App Clip target's `Info.plist`, not the full app's:
+Route into the location-specific flow only on `.confirmed`.
+
+- `.doesNotMatch`: the invocation URL does not match the registered App Clip URL.
+- `.disallowed`: the person denied location, or the invocation did not come
+  from an NFC tag or visual code.
+
+Enable it in the clip target's Info.plist only:
 
 ```xml
 <key>NSAppClip</key>
@@ -124,12 +184,19 @@ Enable location confirmation in the App Clip target's `Info.plist`, not the full
 </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.
+The system answers whether the invocation happened in the region; the App
+Clip card tells the person the clip can verify their location.
+
+## Lifecycle and short-lived state
+
+- No Home Screen icon. Clips show up in the App Library and in recently used
+  apps.
+- The system may delete an unused clip, with its data, after a period it
+  decides.
+- Nothing guarantees local state survives. Move important non-secret data to
+  the shared container or a server.
+- Relaunching from the App Library reuses the last invocation URL; relaunching
+  from the app switcher has none, so restore saved state.
+- Location is limited to When In Use. Authorization is short-lived and resets
+  automatically (the next day at 4:00 a.m.); continuous access cannot be
+  requested.

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

@@ -1,125 +1,177 @@
-# App Clip Routing and Experiences
+# 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.
+How an App Clip learns what to show, how App Store Connect maps URLs to
+experiences, which sources can launch a clip, and how to test it. Summary in
+`../SKILL.md`.
 
-## Contents
+## Handling the invocation URL
 
-- [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.
+Everything starts from the invocation URL. Parse it once, in a router that
+the clip and the full app both compile, because the full app replaces the
+clip after installation and must answer the same links.
 
 ### SwiftUI
 
 ```swift
-@main
-struct DonutShopClip: App {
+import Observation
+import SwiftUI
+
+@MainActor
+@Observable
+final class VisitRouter {
+    var venueID: String?
+
+    func open(_ link: URL) {
+        let parts = URLComponents(url: link, resolvingAgainstBaseURL: true)
+        venueID = parts?.queryItems?.first { $0.name == "venue" }?.value
+    }
+}
+
+struct VisitScreen: View {
+    let router: VisitRouter
+
+    var body: some View {
+        Group {
+            if let venue = router.venueID {
+                Text("Checking in at \(venue)")
+            } else {
+                ProgressView()
+            }
+        }
+    }
+}
+
+struct CoffeeClip: App {
+    @State private var router = VisitRouter()
+
     var body: some Scene {
         WindowGroup {
-            ContentView()
+            VisitScreen(router: router)
                 .onContinueUserActivity(NSUserActivityTypeBrowsingWeb) { activity in
-                    handleInvocation(activity)
+                    if let link = activity.webpageURL {
+                        router.open(link)
+                    }
                 }
         }
     }
-
-    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)
-    }
 }
 ```
 
+In the real target the `App` type carries `@main`. Copy is a literal here for
+brevity; ship localized strings.
+
 ### UIKit scenes
 
-For UIKit scene-based apps, distinguish notification from handling:
+```swift
+import UIKit
 
-- 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.
+final class ClipSceneDelegate: UIResponder, UIWindowSceneDelegate {
+    var window: UIWindow?
 
-**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.
+    func scene(_ scene: UIScene, willConnectTo session: UISceneSession,
+               options connectionOptions: UIScene.ConnectionOptions) {
+        let browsing = connectionOptions.userActivities.first { $0.activityType == NSUserActivityTypeBrowsingWeb }
+        if let link = browsing?.webpageURL {
+            route(link)
+        }
+    }
 
-## App Clip Experience Configuration
+    func scene(_ scene: UIScene, continue incoming: NSUserActivity) {
+        if incoming.activityType == NSUserActivityTypeBrowsingWeb, let link = incoming.webpageURL {
+            route(link)
+        }
+    }
 
-Configure experiences in **App Store Connect** after uploading a build containing the App Clip.
+    private func route(_ link: URL) {
+    }
+}
+```
 
-### Default App Clip experience
+- Cold launch: the activity is in `connectionOptions.userActivities` inside
+  `scene(_:willConnectTo:options:)`.
+- Already running: `scene(_:continue:)` delivers it.
+- `scene(_:willContinueUserActivityWithType:)` fires before either and has
+  neither the activity nor its URL; use it at most to show a loading state.
 
-- 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.
+The rule that ties this together: every invocation URL the clip supports must
+also work in the full app.
 
-### Demo App Clip link
+## App Store Connect experiences
 
-- 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.
+Experiences are set up in App Store Connect after you upload a build that
+contains the clip.
 
-### Advanced App Clip experiences
+### Default experience
 
-- 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.
+- Required for every clip.
+- It needs a header image, a subtitle, and the verb shown on the action
+  button.
+- App Store Connect creates the default link for you, hosted on
+  `appclip.apple.com`.
+- That link covers web and shared-link invocations. QR codes and NFC tags may
+  encode it, but they then count as physical invocations for the size policy.
 
-### Associated domains
+### Demo link
 
-For custom URLs, add entries to the Associated Domains entitlement on both the full app and App Clip targets, and host an AASA file:
+- Generated automatically for demo versions of an app.
+- Works from NFC tags and QR codes, so physical invocations can be tested.
+- App Clip Codes need the short form of the demo link.
+- It does not stand in for Maps, Smart App Banners or App Clip cards on a
+  website.
+- It qualifies for the larger current size limit.
+- It cannot carry URL parameters.
 
-```text
-appclips:example.com
-```
+### Advanced experiences
 
-## Invocation Methods
+- Needed for Maps, for associating the clip with a location, for per-location
+  card images and for exact routing at a physical place.
+- The normal route for App Clip Codes once they are printed for real use.
+- Every one carries its own URL, card image and card text.
+- Registered URLs match by prefix, so one entry can serve many sub-paths
+  (`https://example.com/venue/` covers `https://example.com/venue/12/table/4`).
+- When there are many (a chain of stores, say), create and update them
+  through the App Store Connect API rather than by hand.
 
-| 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 |
+### Associated domains
+
+Custom URLs and advanced experiences need the entry `appclips:example.com` in
+the Associated Domains of both the clip and the full app, and an
+association file on that domain that names the clip.
 
-## Safari Smart App Banner
+## Invocation sources
 
-Add this meta tag to your website to show the App Clip banner:
+| Source | How it reaches the clip |
+|---|---|
+| App Clip Codes | Advanced experience in production; short demo link for demo codes. Can embed NFC or be scan-only |
+| NFC tags | URL stored in an NDEF payload; a physical invocation for size purposes |
+| QR codes | URL encoded in the code; a physical invocation for size purposes |
+| Safari Smart App Banner | Link the clip to the site, then put the banner tag in the page head |
+| Maps | An advanced experience tied to a place |
+| Messages | The invocation URL shared as text; demo links preview in a limited way |
+| Siri Suggestions | Location-based; suggestions tied to a place need an advanced experience |
+| Other apps with Link Presentation | Rich link metadata can surface the experience |
+| Other apps opening a URL (`Link`, `UIApplication.open(_:)`) | Works for the default link, links on the associated website and the demo link; this path cannot reach advanced experiences |
+
+## Smart App 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">
+<head>
+  <meta content="app-id=987654321, app-clip-bundle-id=org.example.Tickets.Clip, app-clip-display=card"
+        name="apple-itunes-app">
+</head>
 ```
 
-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
+- With `app-clip-display=card`, iOS 15 and later present the full card, both
+  in Safari and inside `SFSafariViewController`.
+- `app-argument` belongs to full-app Smart App Banners; it is not documented
+  for App Clip launches, so routing must come from the URL itself.
 
-Test the invocation path, not just direct Xcode launch:
+## Local testing
 
-```swift
-// Use the _XCAppClipURL environment variable in the scheme,
-// or register a Local Experience in Settings → Developer → Local Experiences.
-```
+Test the path a real invocation takes. Running the clip scheme directly from
+Xcode can skip it and hide routing bugs. Two options:
 
-A direct Xcode launch can skip the invocation path and hide routing bugs.
+- In the clip scheme's Run settings, add an environment variable named
+  `_XCAppClipURL` whose value is the URL to simulate.
+- Register a Local Experience on the device under Settings > Developer >
+  Local Experiences, then invoke it with a QR code, NFC tag or link.