@mmerterden/multi-agent-pipeline 8.6.2 → 10.0.6

package/pipeline/skills/shared/external/live-activities/references/{live-activity-patterns.md → activitykit-patterns.md}

@@ -2,7 +2,7 @@
 
 Complete implementation patterns for ActivityKit Live Activities, Dynamic
 Island, push-to-update, and lifecycle management. All patterns use modern
-Swift async/await and target iOS 16.1+ unless noted.
+Swift async/await and `ActivityContent`, so they target iOS 16.2+ unless noted.
 
 ## Contents
 
@@ -41,7 +41,9 @@ struct RideAttributes: ActivityAttributes {
         var driverName: String
         var driverPhoto: String        // SF Symbol name or asset name
         var vehicleDescription: String
-        var eta: ClosedRange<Date>
+        var etaStartSeconds: Int
+        var etaEndSeconds: Int
+        // For server pushes, prefer scalar fields or coordinated custom Codable keys.
         var status: RideStatus
         var distanceRemaining: Double   // miles
     }
@@ -55,12 +57,20 @@ enum RideStatus: String, Codable, Hashable {
     case arriving
     case completed
     case cancelled
+    case failed
+}
+
+extension RideAttributes.ContentState {
+    var etaRange: ClosedRange<Date> {
+        Date(timeIntervalSince1970: TimeInterval(etaStartSeconds))...
+            Date(timeIntervalSince1970: TimeInterval(etaEndSeconds))
+    }
 }
 ```
 
-Keep `ContentState` lightweight. Every update serializes the entire struct, and
-push payloads have a 4 KB size limit. Avoid storing images, large strings, or
-deeply nested objects.
+Keep `ContentState` lightweight. ActivityKit attributes and content-state data
+must fit within the framework's 4 KB data limit. Avoid storing images, large
+strings, or deeply nested objects.
 
 ## Starting a Live Activity with All Parameters
 
@@ -91,7 +101,8 @@ func startRideActivity(
         driverName: driver,
         driverPhoto: "car.fill",
         vehicleDescription: vehicle,
-        eta: Date()...Date().addingTimeInterval(600),
+        etaStartSeconds: Int(Date().timeIntervalSince1970),
+        etaEndSeconds: Int(Date().addingTimeInterval(600).timeIntervalSince1970),
         status: .driverAssigned,
         distanceRemaining: 2.5
     )
@@ -145,19 +156,31 @@ let activity = try Activity.request(
     attributes: attributes,
     content: content,
     pushType: .token,
+    style: .standard,
+    alertConfiguration: AlertConfiguration(
+        title: "Game Starting",
+        body: "The live score is ready.",
+        sound: .default
+    ),
     start: gameTime  // iOS 26+
 )
 ```
 
-### Starting with ActivityStyle (iOS 16.1+ type, `style:` parameter iOS 26+)
+### Starting with ActivityStyle (iOS 18+ request parameter)
+
+Use `.standard` for persistent Live Activities that should remain visible until
+the app, push, user, or system duration limit ends them. `.transient` is only
+for short-lived expanded Dynamic Island presentations that can auto-end when the
+user locks the device, collapses or shrinks the expanded presentation, leaves
+the app, or does other work outside Dynamic Island; it is wrong for persistent
+Live Activities.
 
 ```swift
-// Transient: system may auto-dismiss after a period
 let activity = try Activity.request(
     attributes: attributes,
     content: content,
     pushType: .token,
-    style: .transient  // style: parameter requires iOS 26+
+    style: .standard
 )
 ```
 
@@ -175,7 +198,8 @@ func updateRideActivity(
         driverName: activity.content.state.driverName,
         driverPhoto: activity.content.state.driverPhoto,
         vehicleDescription: activity.content.state.vehicleDescription,
-        eta: eta,
+        etaStartSeconds: Int(eta.lowerBound.timeIntervalSince1970),
+        etaEndSeconds: Int(eta.upperBound.timeIntervalSince1970),
         status: newStatus,
         distanceRemaining: distance
     )
@@ -220,10 +244,8 @@ private func alertMessage(for status: RideStatus) -> String {
             "driverName": "Maria",
             "driverPhoto": "car.fill",
             "vehicleDescription": "White Toyota Camry",
-            "eta": {
-                "lowerBound": 1700000000,
-                "upperBound": 1700000300
-            },
+            "etaStartSeconds": 1700000000,
+            "etaEndSeconds": 1700000300,
             "status": "driverArrived",
             "distanceRemaining": 0.0
         },
@@ -250,10 +272,8 @@ private func alertMessage(for status: RideStatus) -> String {
             "driverName": "Maria",
             "driverPhoto": "car.fill",
             "vehicleDescription": "White Toyota Camry",
-            "eta": {
-                "lowerBound": 1700002000,
-                "upperBound": 1700002000
-            },
+            "etaStartSeconds": 1700002000,
+            "etaEndSeconds": 1700002000,
             "status": "completed",
             "distanceRemaining": 0.0
         }
@@ -263,7 +283,7 @@ private func alertMessage(for status: RideStatus) -> String {
 
 ### Push-to-Start Payload (iOS 17.2+)
 
-Send to the push-to-start token to remotely create an activity:
+Send to the push-to-start token to remotely create an activity. The `alert` field is required for push-to-start:
 
 ```json
 {
@@ -280,10 +300,8 @@ Send to the push-to-start token to remotely create an activity:
             "driverName": "Maria",
             "driverPhoto": "car.fill",
             "vehicleDescription": "White Toyota Camry",
-            "eta": {
-                "lowerBound": 1700000000,
-                "upperBound": 1700000600
-            },
+            "etaStartSeconds": 1700000000,
+            "etaEndSeconds": 1700000600,
             "status": "driverAssigned",
             "distanceRemaining": 3.2
         },
@@ -301,12 +319,35 @@ Send to the push-to-start token to remotely create an activity:
 |---|---|
 | `apns-push-type` | `liveactivity` |
 | `apns-topic` | `<bundle-id>.push-type.liveactivity` |
-| `apns-priority` | `5` (silent) or `10` (alert, updates with sound/banner) |
+| `apns-priority` | `5` (lower priority) or `10` (immediate, counts against budget) |
 | `authorization` | `bearer <jwt>` (token auth) or use certificate auth |
 
-The `content-state` JSON keys and value types must match the `ContentState`
-Codable representation exactly. A type mismatch (e.g., sending a string where
-a number is expected) causes the update to fail silently.
+The `aps.alert` payload controls visible alert/banner/sound behavior; priority
+alone does not create an alert. The `content-state` JSON must decode into
+`ActivityAttributes.ContentState`. Use the default synthesized `Codable` key and
+value shape unless the Swift model declares custom `CodingKeys`; then coordinate
+those exact keys and value shapes server-side. Do not assume `Date` or
+`ClosedRange<Date>` values are Unix timestamp dictionaries unless your Swift
+model explicitly encodes them that way. A type mismatch (e.g., sending a string
+where a number is expected) can prevent ActivityKit from applying the update.
+
+### Channel / Broadcast Updates (iOS 18+)
+
+Use channel-based push only with a valid APNs-created channel ID. Enable the
+broadcast capability outside Xcode, have the server create the channel, and pass
+that channel ID to the app:
+
+```swift
+let activity = try Activity.request(
+    attributes: attributes,
+    content: content,
+    pushType: .channel(channelIDFromServer)
+)
+```
+
+Channel pushes can update or end Live Activities, but cannot start them. Use
+`apns-channel-id` and expiration for channel requests instead of the device-token
+`apns-topic` header.
 
 ## Ending with Different Dismissal Policies
 
@@ -319,7 +360,8 @@ func endRideActivity(
         driverName: activity.content.state.driverName,
         driverPhoto: activity.content.state.driverPhoto,
         vehicleDescription: activity.content.state.vehicleDescription,
-        eta: Date()...Date(),
+        etaStartSeconds: Int(Date().timeIntervalSince1970),
+        etaEndSeconds: Int(Date().timeIntervalSince1970),
         status: finalStatus,
         distanceRemaining: 0
     )
@@ -342,6 +384,37 @@ func endRideActivity(
 }
 ```
 
+When reviewing duration claims, distinguish the active lifetime (up to 8 hours
+unless the app or user ends it sooner), system-ended Lock Screen presence (up to
+4 additional hours, for 12 hours total from start), and app-ended `.default`
+dismissal linger (up to 4 hours after ending).
+
+### Ending on Terminal Server Failure
+
+When a server reports that the tracked event failed or can no longer be
+represented accurately, publish a terminal state and end the activity instead of
+leaving stale progress visible.
+
+```swift
+func handleTerminalServerFailure(
+    _ activity: Activity<RideAttributes>,
+    message: String
+) async {
+    let failedState = RideAttributes.ContentState(
+        driverName: activity.content.state.driverName,
+        driverPhoto: activity.content.state.driverPhoto,
+        vehicleDescription: message,
+        etaStartSeconds: Int(Date().timeIntervalSince1970),
+        etaEndSeconds: Int(Date().timeIntervalSince1970),
+        status: .failed,
+        distanceRemaining: 0
+    )
+
+    let content = ActivityContent(state: failedState, staleDate: nil, relevanceScore: 0)
+    await activity.end(content, dismissalPolicy: .immediate)
+}
+```
+
 ### Ending All Activities (cleanup on sign-out)
 
 ```swift
@@ -364,7 +437,7 @@ struct RideActivityWidget: Widget {
             DynamicIsland {
                 // EXPANDED: shown on long-press
                 DynamicIslandExpandedRegion(.leading) {
-                    VStack(alignment: .leading, spacing: 4) {
+                    VStack(alignment: .leading) {
                         Image(systemName: context.state.driverPhoto)
                             .font(.title2)
                         Text(context.state.driverName)
@@ -374,8 +447,8 @@ struct RideActivityWidget: Widget {
                 }
 
                 DynamicIslandExpandedRegion(.trailing) {
-                    VStack(alignment: .trailing, spacing: 4) {
-                        Text(timerInterval: context.state.eta, countsDown: true)
+                    VStack(alignment: .trailing) {
+                        Text(timerInterval: context.state.etaRange, countsDown: true)
                             .font(.title3.monospacedDigit())
                         Text(String(format: "%.1f mi", context.state.distanceRemaining))
                             .font(.caption2)
@@ -390,7 +463,7 @@ struct RideActivityWidget: Widget {
                 }
 
                 DynamicIslandExpandedRegion(.bottom) {
-                    VStack(spacing: 8) {
+                    VStack {
                         ProgressView(
                             value: context.state.status.progress,
                             total: 1.0
@@ -415,7 +488,7 @@ struct RideActivityWidget: Widget {
                     .foregroundStyle(.green)
             } compactTrailing: {
                 // COMPACT TRAILING: one key value
-                Text(timerInterval: context.state.eta, countsDown: true)
+                Text(timerInterval: context.state.etaRange, countsDown: true)
                     .frame(width: 44)
                     .monospacedDigit()
             } minimal: {
@@ -436,7 +509,7 @@ struct RideLockScreenView: View {
     let context: ActivityViewContext<RideAttributes>
 
     var body: some View {
-        VStack(spacing: 12) {
+        VStack {
             // Header
             HStack {
                 VStack(alignment: .leading) {
@@ -448,7 +521,7 @@ struct RideLockScreenView: View {
                 }
                 Spacer()
                 // Live countdown timer (auto-updating, no code needed)
-                Text(timerInterval: context.state.eta, countsDown: true)
+                Text(timerInterval: context.state.etaRange, countsDown: true)
                     .font(.title2.monospacedDigit().bold())
                     .foregroundStyle(.green)
             }
@@ -555,7 +628,7 @@ func observeActivityState(_ activity: Activity<RideAttributes>) {
                 // iOS 26+: scheduled but not yet displayed
                 print("Activity is pending start")
             case .stale:
-                // The staleDate passed without an update
+                // iOS 16.2+: staleDate passed without an update
                 print("Content is stale -- update or end")
             case .ended:
                 // Ended but may still be visible on Lock Screen
@@ -601,7 +674,8 @@ func observePushToken(for activity: Activity<RideAttributes>) {
     }
 }
 
-/// Observe the push-to-start token for remote activity creation (iOS 17.2+)
+/// Observe the ActivityKit push-to-start token for remote activity creation (iOS 17.2+).
+/// This token is distinct from ordinary app/device APNs tokens and per-activity update tokens.
 func observePushToStartToken() {
     Task {
         for await token in Activity<RideAttributes>.pushToStartTokenUpdates {
@@ -620,13 +694,11 @@ Live Activities in Settings at any time.
 ```swift
 func checkLiveActivityAuthorization() async -> Bool {
     let authInfo = ActivityAuthorizationInfo()
+    return authInfo.areActivitiesEnabled
+}
 
-    // Synchronous check
-    guard authInfo.areActivitiesEnabled else {
-        return false
-    }
-
-    return true
+func checkFrequentPushAuthorization() -> Bool {
+    ActivityAuthorizationInfo().frequentPushesEnabled
 }
 
 /// Observe authorization changes to react when user toggles the setting
@@ -635,14 +707,19 @@ func observeAuthorization() {
         let authInfo = ActivityAuthorizationInfo()
         for await enabled in authInfo.activityEnablementUpdates {
             if enabled {
-                // Re-register push-to-start token
                 observePushToStartToken()
             } else {
-                // Inform server to stop sending push updates
                 try? await ServerAPI.shared.disableActivityPush()
             }
         }
     }
+
+    Task {
+        let authInfo = ActivityAuthorizationInfo()
+        for await frequentPushesEnabled in authInfo.frequentPushEnablementUpdates {
+            try? await ServerAPI.shared.setFrequentPushesEnabled(frequentPushesEnabled)
+        }
+    }
 }
 ```
 
@@ -666,7 +743,7 @@ func startActivitySafely(
             // User disabled Live Activities in Settings
             print("Live Activities disabled by user")
         case .globalMaximumExceeded:
-            // Too many Live Activities across all apps (system limit ~5)
+            // Device-level ongoing Live Activity maximum reached
             print("System-wide activity limit reached")
         case .targetMaximumExceeded:
             // Too many Live Activities for this app
@@ -683,9 +760,10 @@ func startActivitySafely(
 ## Background Handling Considerations
 
 Live Activities continue to display when the app is backgrounded or suspended.
-Push-to-update is the primary mechanism for background updates. When the app
-returns to foreground, reconcile local state with the activity's current
-content.
+The Live Activity UI runs in a widget extension sandbox and cannot fetch network
+data or receive location updates directly. Push-to-update is the primary
+mechanism for background updates. When the app returns to foreground, reconcile
+local state with the activity's current content.
 
 ```swift
 @MainActor
@@ -731,17 +809,17 @@ func handleAppBecameActive() {
 ```
 
 For truly background-driven updates, rely on push-to-update rather than
-Background App Refresh. Push updates are delivered reliably even when the app
-is suspended, while Background App Refresh has limited and unpredictable
-scheduling.
+Background App Refresh. Push updates can arrive while the app is suspended, but
+APNs delivery, priority, budget, and throttling still apply; use `staleDate` and
+foreground reconciliation for missed updates.
 
 ## Testing in Simulator and on Device
 
 ### Simulator
 
 The Simulator supports Live Activity rendering on the Lock Screen and displays
-the Dynamic Island on iPhone 14 Pro+ simulator models. Use Xcode previews for
-rapid iteration:
+the Dynamic Island on simulator models that include Dynamic Island. Use Xcode
+previews for rapid iteration:
 
 ```swift
 #Preview("Lock Screen", as: .content, using: RideAttributes.preview) {
@@ -751,7 +829,8 @@ rapid iteration:
         driverName: "Alex",
         driverPhoto: "car.fill",
         vehicleDescription: "White Toyota Camry",
-        eta: Date()...Date().addingTimeInterval(300),
+        etaStartSeconds: Int(Date().timeIntervalSince1970),
+        etaEndSeconds: Int(Date().addingTimeInterval(300).timeIntervalSince1970),
         status: .driverEnRoute,
         distanceRemaining: 1.5
     )
@@ -759,7 +838,8 @@ rapid iteration:
         driverName: "Alex",
         driverPhoto: "car.fill",
         vehicleDescription: "White Toyota Camry",
-        eta: Date()...Date().addingTimeInterval(60),
+        etaStartSeconds: Int(Date().timeIntervalSince1970),
+        etaEndSeconds: Int(Date().addingTimeInterval(60).timeIntervalSince1970),
         status: .arriving,
         distanceRemaining: 0.1
     )
@@ -772,7 +852,8 @@ rapid iteration:
         driverName: "Alex",
         driverPhoto: "car.fill",
         vehicleDescription: "White Toyota Camry",
-        eta: Date()...Date().addingTimeInterval(300),
+        etaStartSeconds: Int(Date().timeIntervalSince1970),
+        etaEndSeconds: Int(Date().addingTimeInterval(300).timeIntervalSince1970),
         status: .driverEnRoute,
         distanceRemaining: 1.5
     )
@@ -785,7 +866,8 @@ rapid iteration:
         driverName: "Alex",
         driverPhoto: "car.fill",
         vehicleDescription: "White Toyota Camry",
-        eta: Date()...Date().addingTimeInterval(300),
+        etaStartSeconds: Int(Date().timeIntervalSince1970),
+        etaEndSeconds: Int(Date().addingTimeInterval(300).timeIntervalSince1970),
         status: .driverEnRoute,
         distanceRemaining: 1.5
     )
@@ -798,7 +880,8 @@ rapid iteration:
         driverName: "Alex",
         driverPhoto: "car.fill",
         vehicleDescription: "White Toyota Camry",
-        eta: Date()...Date().addingTimeInterval(300),
+        etaStartSeconds: Int(Date().timeIntervalSince1970),
+        etaEndSeconds: Int(Date().addingTimeInterval(300).timeIntervalSince1970),
         status: .driverEnRoute,
         distanceRemaining: 1.5
     )
@@ -833,15 +916,16 @@ curl -v \
   --header "apns-topic: com.example.app.push-type.liveactivity" \
   --header "apns-priority: 10" \
   --header "authorization: bearer $JWT_TOKEN" \
-  --data '{"aps":{"timestamp":1700000000,"event":"update","content-state":{"driverName":"Alex","driverPhoto":"car.fill","vehicleDescription":"White Toyota Camry","eta":{"lowerBound":1700000000,"upperBound":1700000300},"status":"driverArrived","distanceRemaining":0.0},"alert":{"title":"Driver Arrived","body":"Your driver is here!"}}}' \
+  --data '{"aps":{"timestamp":1700000000,"event":"update","content-state":{"driverName":"Alex","driverPhoto":"car.fill","vehicleDescription":"White Toyota Camry","etaStartSeconds":1700000000,"etaEndSeconds":1700000300,"status":"driverArrived","distanceRemaining":0.0},"alert":{"title":"Driver Arrived","body":"Your driver is here!"}}}' \
   https://api.push.apple.com/3/device/$DEVICE_PUSH_TOKEN
 ```
 
 ### Debugging Tips
 
 - Check Console.app for `ActivityKit` log messages when activities fail to start.
-- Verify `content-state` JSON keys match `ContentState` property names exactly
-  (including camelCase). Mismatches cause silent failures.
+- Verify `content-state` JSON keys match the default `ContentState` `Codable`
+  shape or coordinated `CodingKeys`. Mismatches can prevent ActivityKit from
+  applying updates.
 - Use `Activity<T>.activities` to inspect all running activities in the debugger.
 - Set a breakpoint in `pushTokenUpdates` to verify tokens are being delivered.
 - If activities do not appear, confirm `NSSupportsLiveActivities = YES` is in
@@ -852,7 +936,7 @@ curl -v \
 | Key | Value | Purpose |
 |---|---|---|
 | `NSSupportsLiveActivities` | `YES` | Enable Live Activities (required) |
-| `NSSupportsLiveActivitiesFrequentUpdates` | `YES` | Increase push update budget |
+| `NSSupportsLiveActivitiesFrequentUpdates` | `YES` | Increase the system-managed push update budget |
 
 Both keys belong in the host app's Info.plist, not the widget extension.
 
@@ -866,3 +950,4 @@ Both keys belong in the host app's Info.plist, not the widget extension.
 - [DynamicIsland](https://sosumi.ai/documentation/widgetkit/dynamicisland)
 - [ActivityConfiguration](https://sosumi.ai/documentation/widgetkit/activityconfiguration)
 - [Starting and updating with push notifications](https://sosumi.ai/documentation/activitykit/starting-and-updating-live-activities-with-activitykit-push-notifications)
+- [Sending broadcast push notifications](https://sosumi.ai/documentation/usernotifications/sending-broadcast-push-notification-requests-to-apns)

package/pipeline/skills/shared/external/mapkit-location/SKILL.md

@@ -3,15 +3,17 @@ name: mapkit-location
 description: "Implement, review, or improve maps and location features in iOS/macOS apps using MapKit and CoreLocation. Use when working with Map views, annotations, markers, polylines, user location tracking, geocoding, reverse geocoding, search/autocomplete, directions and routes, geofencing, region monitoring, CLLocationUpdate async streams, or location authorization flows. Also use when working with maps, coordinates, addresses, places, directions, distance calculations, or location-based features in Swift apps."
 ---
 
-# MapKit and CoreLocation
+# MapKit
 
 Build map-based and location-aware features targeting iOS 17+ with SwiftUI
 MapKit and modern CoreLocation async APIs. Use `Map` with `MapContentBuilder`
 for views, `CLLocationUpdate.liveUpdates()` for streaming location, and
 `CLMonitor` for geofencing.
 
-See `references/mapkit-patterns.md` for extended MapKit patterns and
-`references/corelocation-patterns.md` for CoreLocation patterns.
+Read [references/mapkit-patterns.md](references/mapkit-patterns.md) when you need full map setup, search,
+routes, Look Around, snapshots, or iOS 26 place APIs. Read
+[references/mapkit-corelocation-patterns.md](references/mapkit-corelocation-patterns.md) when the task involves
+location update lifecycle, geofencing, background location, testing, or privacy keys.
 
 ## Contents
 
@@ -195,25 +197,36 @@ Map(selection: $selectedMarker) {
 
 Replace `CLLocationManagerDelegate` callbacks with a single async sequence.
 Each iteration yields a `CLLocationUpdate` containing an optional `CLLocation`.
+On iOS 18+, handle diagnostic states such as denied authorization, globally
+disabled Location Services, unavailable location, and insufficient in-use
+conditions with a visible degraded path instead of silently waiting forever.
+Store the task so the feature can cancel it, and reject invalid, inaccurate,
+stale, or unusable movement data before driving map UI or background work.
 
 ```swift
 import CoreLocation
 
+@MainActor
 @Observable
-final class LocationTracker: @unchecked Sendable {
+final class LocationTracker {
     var currentLocation: CLLocation?
     private var updateTask: Task<Void, Never>?
 
     func startTracking() {
         updateTask = Task {
-            let updates = CLLocationUpdate.liveUpdates()
-            for try await update in updates {
-                guard let location = update.location else { continue }
-                // Filter by horizontal accuracy
-                guard location.horizontalAccuracy < 50 else { continue }
-                await MainActor.run {
-                    self.currentLocation = location
+            do {
+                let updates = CLLocationUpdate.liveUpdates()
+                for try await update in updates {
+                    guard let location = update.location else { continue }
+                    // Filter by horizontal accuracy
+                    guard location.horizontalAccuracy >= 0,
+                          location.horizontalAccuracy < 50 else { continue }
+                    currentLocation = location
                 }
+            } catch is CancellationError {
+                // Expected when tracking stops.
+            } catch {
+                currentLocation = nil
             }
         }
     }
@@ -411,10 +424,9 @@ func getETA(from source: MKMapItem, to destination: MKMapItem) async throws -> T
 }
 ```
 
-### Cycling Directions (iOS 26+)
+### Cycling Directions (iOS 14+)
 
 ```swift
-@available(iOS 26, *)
 func getCyclingDirections(to destination: MKMapItem) async throws -> MKRoute? {
     let request = MKDirections.Request()
     request.source = MKMapItem.forCurrentLocation()
@@ -432,6 +444,8 @@ Create rich place references from coordinates or addresses without needing a
 Place ID. Requires `import GeoToolbox`.
 
 ```swift
+import GeoToolbox
+
 @available(iOS 26, *)
 func lookupPlace(name: String, coordinate: CLLocationCoordinate2D) async throws -> MKMapItem {
     let descriptor = PlaceDescriptor(
@@ -445,16 +459,21 @@ func lookupPlace(name: String, coordinate: CLLocationCoordinate2D) async throws
 
 ## Common Mistakes
 
-**DON'T:** Request `.authorizedAlways` upfront — users distrust broad permissions.
-**DO:** Start with `.requestWhenInUseAuthorization()`, escalate to `.always` only when the user enables a background feature.
+**DON'T:** Request always authorization upfront.
+**DO:** Start with when-in-use authorization. On iOS 18+, hold a `CLServiceSession`
+for the feature lifetime; request `.always` only for background features that
+need system relaunch after termination.
 
 **DON'T:** Use `CLLocationManagerDelegate` for simple location fetches on iOS 17+.
 **DO:** Use `CLLocationUpdate.liveUpdates()` async stream for cleaner, more concise code.
 
-**DON'T:** Keep location updates running when the map/view is not visible (drains battery).
-**DO:** Use `.task { }` in SwiftUI so updates cancel automatically on disappear.
+**DON'T:** Ignore `CLLocationUpdate` diagnostics such as denied, globally denied, or unavailable location.
+**DO:** Stop or degrade the feature, show recovery UI such as Settings guidance, and keep search/manual flows usable.
+
+**DON'T:** Let `liveUpdates()` run from an unowned task after the map/view is gone.
+**DO:** Store the `Task`, cancel it when the feature stops, and filter invalid, inaccurate, stale, or impossible movement fixes.
 
-**DON'T:** Force-unwrap `CLPlacemark` properties — they are all optional.
+**DON'T:** Force-unwrap `CLPlacemark` properties  -  they are all optional.
 **DO:** Use nil-coalescing: `placemark.locality ?? "Unknown"`.
 
 **DON'T:** Fire `MKLocalSearchCompleter` queries on every keystroke.
@@ -463,7 +482,7 @@ func lookupPlace(name: String, coordinate: CLLocationCoordinate2D) async throws
 **DON'T:** Silently fail when location authorization is denied.
 **DO:** Detect `.denied` status and show an alert with a Settings deep link.
 
-**DON'T:** Assume geocoding always succeeds — handle empty results and network errors.
+**DON'T:** Assume geocoding always succeeds  -  handle empty results and network errors.
 
 ## Review Checklist
 
@@ -481,5 +500,5 @@ func lookupPlace(name: String, coordinate: CLLocationCoordinate2D) async throws
 
 ## References
 
-- `references/mapkit-patterns.md` — Map setup, annotations, search, routes, clustering, Look Around, snapshots.
-- `references/corelocation-patterns.md` — CLLocationUpdate, CLMonitor, CLServiceSession, background location, testing.
+- [references/mapkit-patterns.md](references/mapkit-patterns.md)  -  Map setup, annotations, search, routes, clustering, Look Around, snapshots.
+- [references/mapkit-corelocation-patterns.md](references/mapkit-corelocation-patterns.md)  -  CLLocationUpdate, CLMonitor, CLServiceSession, background location, testing.

package/pipeline/skills/shared/external/mapkit-location/evals/evals.json

@@ -0,0 +1,47 @@
+{
+  "skill_name": "mapkit",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "I'm building a SwiftUI store locator for iOS 18. Sketch the MapKit implementation for a searchable map with autocomplete, markers for results, marker selection that shows details, a route overlay to the selected store, and a user-location button. Include the privacy and cancellation details that matter.",
+      "expected_output": "A SwiftUI MapKit implementation plan that uses Map, Marker or Annotation, MapCameraPosition, MKLocalSearchCompleter plus MKLocalSearch, Map selection tags, MKDirections and MapPolyline, UserAnnotation or MapUserLocationButton, and CoreLocation authorization/task cancellation guidance.",
+      "files": [],
+      "expectations": [
+        "Uses SwiftUI MapKit APIs such as Map, Marker or Annotation, MapCameraPosition, map controls, and MapPolyline rather than defaulting to MKMapView.",
+        "Describes MKLocalSearchCompleter for autocomplete and MKLocalSearch.Request(completion:) or naturalLanguageQuery for full search results, with debounced input.",
+        "Handles map selection with a binding and tags whose type matches the selected value.",
+        "Builds directions with MKDirections.Request and displays the selected route with MapPolyline(route.polyline).",
+        "Includes NSLocationWhenInUseUsageDescription and a denied-location UI path such as a Settings deep link.",
+        "Cancels or scopes live location/search tasks to the view lifecycle and avoids running location updates indefinitely."
+      ]
+    },
+    {
+      "id": 1,
+      "prompt": "Review this location feature plan: create a CLMonitor every time the view appears, monitor 45 circular regions for coupons, request Always location on launch, start liveUpdates forever, and use background location without a Live Activity or CLBackgroundActivitySession. What should I change for iOS 18+?",
+      "expected_output": "A correction-focused CoreLocation review that uses CLServiceSession only for active user-facing features, limits CLMonitor conditions, keeps monitor/event subscriptions stable, uses CLLocationUpdate.liveUpdates with filtering and cancellation, and explains the background-location requirements.",
+      "files": [],
+      "expectations": [
+        "Rejects requesting Always authorization on launch and recommends when-in-use first, with CLServiceSession scoped to the feature lifetime on iOS 18+.",
+        "States that CLMonitor condition monitoring is limited to 20 conditions per app and the app must prioritize or rotate regions.",
+        "Warns against rapidly recreating CLMonitor instances with the same name and recommends a long-lived monitor plus add/remove diffing.",
+        "Uses CLLocationUpdate.liveUpdates() as an async sequence and filters invalid or inaccurate locations while cancelling the task when not needed.",
+        "Explains that background updates require the Location updates background mode and either a CLBackgroundActivitySession or Live Activity, with active update or monitor subscriptions.",
+        "Mentions handling denied/global-denied/location-unavailable diagnostics or degraded behavior instead of silently failing."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "I need a navigation experience that shows a map inside CarPlay, opens a small App Clip from a place card, and pairs a BLE beacon when the user enters a geofence. Which parts belong in this MapKit skill, and where should the other pieces go?",
+      "expected_output": "A boundary-aware answer that keeps MapKit/CoreLocation responsibilities in scope while routing CarPlay templates, App Clip invocation, and BLE accessory setup to the appropriate sibling skills or frameworks.",
+      "files": [],
+      "expectations": [
+        "Keeps MapKit/CoreLocation scope to maps, annotations, routes, geocoding/search, user location, CLMonitor geofencing, and background location constraints.",
+        "Routes CarPlay map templates, navigation alerts, and CarPlay-specific UI to the CarPlay skill or CarPlay framework guidance.",
+        "Routes App Clip invocation, size limits, and handoff behavior to the App Clips skill.",
+        "Routes BLE beacon pairing or accessory onboarding to Core Bluetooth or AccessorySetupKit rather than expanding MapKit scope.",
+        "Does not claim MapKit handles CarPlay templates, App Clip launch infrastructure, or BLE pairing directly.",
+        "Still explains the handoff points between geofence events, routes/search results, and the adjacent frameworks."
+      ]
+    }
+  ]
+}