@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/live-activities/SKILL.md

@@ -1,216 +1,222 @@
 ---
 name: live-activities
-description: "Implement, review, or improve Live Activities and Dynamic Island experiences in iOS apps using ActivityKit. Use when building real-time updating widgets for the Lock Screen and Dynamic Island  -  delivery tracking, sports scores, ride-sharing status, workout timers, media playback, or any time-sensitive information that updates in real time. Also use when working with ActivityKit, ActivityAttributes, Activity lifecycle (request/update/end), Dynamic Island layouts (compact/minimal/expanded), push-to-update Live Activities, or Lock Screen live widgets."
+description: "ActivityKit Live Activities on the Lock Screen and Dynamic Island: ActivityAttributes and ContentState, request/update/end lifecycle, compact, minimal and expanded layouts, stale dates, push-to-update, push-to-start and channel pushes, update tokens, scheduled starts, ActivityStyle. Use when building, reviewing or improving glanceable live status (delivery tracking, scores, rides, workout timers, media playback) or sending Live Activity APNs payloads. Not for Home Screen or timeline widgets (widgetkit) or generic APNs setup (push-notifications)."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
-# ActivityKit
-
-ActivityKit owns real-time, glanceable Live Activities displayed on the Lock
-Screen and, on supported devices, Dynamic Island. StandBy, CarPlay, and a
-paired Mac can also display Live Activities, but do not blur that core routing:
-ordinary Home Screen/timeline widgets belong in `widgetkit`, and generic APNs
-setup belongs in `push-notifications`. Live Activity push payload shape stays in
-ActivityKit: device-token updates use `apns-push-type: liveactivity` and
-`apns-topic: <bundle-id>.push-type.liveactivity`, while `aps.content-state` must
-decode into the app's actual `ActivityAttributes.ContentState` `Codable` shape.
-Do not assume `Date` or `ClosedRange<Date>` use Unix timestamp
-`lowerBound`/`upperBound` dictionaries unless the Swift model and server
-contract coordinate that encoding. Boundary answers that keep ActivityKit APNs
-payloads, `content-state`, or Live Activity data contracts in scope should
-include these payload-shape invariants even when routing generic APNs setup
-elsewhere. Patterns target iOS 26+ with Swift 6.3;
-modern `ActivityContent` lifecycle examples require iOS 16.2+ unless noted.
-
-See [references/activitykit-patterns.md](references/activitykit-patterns.md) for complete code patterns including push payload formats, concurrent activities, state observation, and testing.
-
-## Contents
-
-- [Workflow](#workflow)
-- [ActivityAttributes Definition](#activityattributes-definition)
-- [Activity Lifecycle](#activity-lifecycle)
-- [Lock Screen Presentation](#lock-screen-presentation)
-- [Dynamic Island](#dynamic-island)
-- [Push-to-Update](#push-to-update)
-- [Recent Additions](#recent-additions)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+# Live Activities (ActivityKit)
+
+A Live Activity is a small, time-boxed status card that ActivityKit keeps on the
+Lock Screen and, on hardware that has one, in the Dynamic Island. A paired
+Mac, CarPlay and StandBy may mirror the same card; none of that changes where
+the work lives. The code and the push contract belong here.
+
+Boundaries:
+
+- Home Screen widgets, `TimelineProvider` and timeline reloads are `widgetkit`
+  work. A Live Activity is driven by the ActivityKit lifecycle, not a timeline.
+- APNs auth keys, certificates and app-level remote-notification registration
+  are `push-notifications` work.
+- The Live Activity payload itself stays here, even in an answer that routes
+  the rest of APNs away. Always state the two invariants:
+  - token pushes carry `apns-push-type: liveactivity` and
+    `apns-topic: BUNDLE_ID.push-type.liveactivity`;
+  - the JSON in `aps.content-state` is decoded with the app's own
+    `ActivityAttributes.ContentState` `Codable` conformance, so it has to
+    match that shape exactly. `Date` and
+    `ClosedRange<Date>` have no universal wire format: do not assume a Unix
+    timestamp or a `lowerBound`/`upperBound` object unless the Swift model and
+    the server were written to agree on it.
+
+Examples target iOS 26 and Swift 6.3. Anything built on `ActivityContent`
+needs iOS 16.2 or later unless a section says otherwise. Longer patterns (a
+full attributes model, server payloads, concurrent activities, state
+observation, errors, testing) are in the
+[patterns reference](references/activitykit-patterns.md).
 
 ## Workflow
 
-### 1. Create a new Live Activity
+### Adding a Live Activity
 
-1. Add `NSSupportsLiveActivities = YES` to the host app's Info.plist.
-2. Define an `ActivityAttributes` struct with a nested `ContentState`.
-3. Create an `ActivityConfiguration` in the widget bundle with Lock Screen
-   content and Dynamic Island closures.
-4. Start the activity with `Activity.request(attributes:content:pushType:)`.
-5. Update with `activity.update(_:)` and end with `activity.end(_:dismissalPolicy:)`.
-6. Forward push tokens to your server for remote updates.
+1. In the main app target's Info.plist, turn on `NSSupportsLiveActivities`
+   (`YES`).
+2. Declare an `ActivityAttributes` type with a nested `ContentState`.
+3. In the widget extension's bundle, add an `ActivityConfiguration` that
+   supplies the Lock Screen view and the Dynamic Island closures.
+4. Start it: `Activity.request(attributes:content:pushType:)`.
+5. Change it with `activity.update(_:)` and finish it with
+   `activity.end(_:dismissalPolicy:)`.
+6. If a server will drive it, send the activity's push token to that server.
 
-### 2. Review existing Live Activity code
+### Reviewing one
 
-Run through the Review Checklist at the end of this document.
+Go through the [Review checklist](#review-checklist) item by item.
 
-## ActivityAttributes Definition
+## Modelling the data
 
-Define both static data (immutable for the activity lifetime) and dynamic
-`ContentState` (changes with each update). Keep `ContentState` small because
-the entire struct is serialized on every update and push payload.
+Two layers, with different lifetimes:
+
+- Properties on the attributes struct are fixed for the whole life of the
+  activity.
+- `ContentState` carries whatever changes. The entire value is encoded on
+  every update and in every push, so keep it lean.
 
 ```swift
 import ActivityKit
 
-struct DeliveryAttributes: ActivityAttributes {
-    // Static -- set once at activity creation, never changes
-    var orderNumber: Int
-    var restaurantName: String
-
-    // Dynamic -- updated throughout the activity lifetime
+struct ChargingAttributes: ActivityAttributes {
     struct ContentState: Codable, Hashable {
-        var driverName: String
-        var estimatedDeliveryTime: ClosedRange<Date>
-        var currentStep: DeliveryStep
+        var batteryPercent: Int
+        var finishWindow: ClosedRange<Date>
+        var phase: ChargePhase
     }
+
+    var stationName: String
+    var connectorLabel: String
 }
 
-enum DeliveryStep: String, Codable, Hashable, CaseIterable {
-    case confirmed, preparing, pickedUp, delivering, delivered
+enum ChargePhase: String, Codable, Hashable, CaseIterable {
+    case queued, connecting, charging, balancing, complete
 
-    var icon: String {
+    var symbolName: String {
         switch self {
-        case .confirmed: "checkmark.circle"
-        case .preparing: "frying.pan"
-        case .pickedUp: "bag.fill"
-        case .delivering: "box.truck.fill"
-        case .delivered: "house.fill"
+        case .queued: "hourglass"
+        case .connecting: "powerplug"
+        case .charging: "bolt.car"
+        case .balancing: "slider.horizontal.3"
+        case .complete: "checkmark.circle.fill"
         }
     }
 }
 ```
 
-### Stale Date
+### Stale date
 
-Set `staleDate` on `ActivityContent` to tell the system when content becomes outdated. The system sets `context.isStale` to `true` after this date; show fallback UI (e.g., "Updating...") in your views.
+`ActivityContent` takes a `staleDate`. Once that moment passes without a newer
+update, the system flips `context.isStale` to `true`, and the view should swap
+in a fallback such as a "Refreshing" label instead of showing a number that may
+be wrong.
 
 ```swift
-let content = ActivityContent(
+let snapshot = ActivityContent(
     state: state,
-    staleDate: Date().addingTimeInterval(300), // stale after 5 minutes
+    staleDate: .now.addingTimeInterval(5 * 60),
     relevanceScore: 75
 )
 ```
 
-## Activity Lifecycle
+## Lifecycle
 
-### Starting
+### Start
 
-Use `Activity.request` to create and display a Live Activity. Pass `.token` as
-the `pushType` to enable remote updates via APNs. The `ActivityContent` request
-shown here requires iOS 16.2+.
+`Activity.request` creates the activity and puts it on screen. Pass
+`pushType: .token` when a server should be able to update it. The
+`ActivityContent` form of `request` is iOS 16.2+.
 
 ```swift
-let attributes = DeliveryAttributes(orderNumber: 42, restaurantName: "Pizza Place")
-let state = DeliveryAttributes.ContentState(
-    driverName: "Alex",
-    estimatedDeliveryTime: Date()...Date().addingTimeInterval(1800),
-    currentStep: .preparing
-)
-let content = ActivityContent(state: state, staleDate: nil, relevanceScore: 75)
-
-do {
-    let activity = try Activity.request(
-        attributes: attributes,
-        content: content,
-        pushType: .token
+func beginCharging(at station: String) {
+    let attributes = ChargingAttributes(stationName: station, connectorLabel: "B2")
+    let window = Date.now...Date.now.addingTimeInterval(30 * 60)
+    let initial = ChargingAttributes.ContentState(
+        batteryPercent: 18, finishWindow: window, phase: .connecting
     )
-    print("Started activity: \(activity.id)")
-} catch {
-    print("Failed to start activity: \(error)")
+    do {
+        let activity = try Activity.request(
+            attributes: attributes,
+            content: ActivityContent(state: initial, staleDate: nil, relevanceScore: 75),
+            pushType: .token
+        )
+        sessionStore.remember(activity.id)
+    } catch {
+        logger.error("Live Activity refused: \(error.localizedDescription)")
+    }
 }
 ```
 
-### Updating
+### Update
 
-Update the dynamic content state from the app. Use `AlertConfiguration` to
-trigger a visible banner and sound alongside the update.
+`await activity.update(content)` changes the card silently. To also light the
+screen with a banner and a sound, use `update(_:alertConfiguration:)`:
 
 ```swift
-let updatedState = DeliveryAttributes.ContentState(
-    driverName: "Alex",
-    estimatedDeliveryTime: Date()...Date().addingTimeInterval(600),
-    currentStep: .delivering
-)
-let updatedContent = ActivityContent(
-    state: updatedState,
-    staleDate: Date().addingTimeInterval(300),
+let next = ActivityContent(
+    state: newState,
+    staleDate: .now.addingTimeInterval(300),
     relevanceScore: 90
 )
-
-// Silent update
-await activity.update(updatedContent)
-
-// Update with an alert
-await activity.update(updatedContent, alertConfiguration: AlertConfiguration(
-    title: "Order Update",
-    body: "Your driver is nearby!",
-    sound: .default
-))
+await activity.update(
+    next,
+    alertConfiguration: AlertConfiguration(
+        title: "Almost full",
+        body: "Battery is at 95 percent.",
+        sound: .default
+    )
+)
 ```
 
-### Ending
+### End
+
+End the activity when the thing it tracks is over. The dismissal policy decides
+how long the ended card lingers on the Lock Screen:
 
-End the activity when the tracked event completes. Choose a dismissal policy
-to control how long the ended activity lingers on the Lock Screen.
+| Policy | Removal |
+|---|---|
+| `.default` | The system chooses, at most 4 hours later |
+| `.immediate` | Right away |
+| `.after(date)` | At `date`, no later than 4 hours from now |
 
 ```swift
-let finalState = DeliveryAttributes.ContentState(
-    driverName: "Alex",
-    estimatedDeliveryTime: Date()...Date(),
-    currentStep: .delivered
+let closing = ChargingAttributes.ContentState(
+    batteryPercent: 100, finishWindow: Date.now...Date.now, phase: .complete
 )
-let finalContent = ActivityContent(state: finalState, staleDate: nil, relevanceScore: 0)
-
-// System decides when to remove (up to 4 hours)
-await activity.end(finalContent, dismissalPolicy: .default)
+await activity.end(
+    ActivityContent(state: closing, staleDate: nil, relevanceScore: 0),
+    dismissalPolicy: .after(.now.addingTimeInterval(3600))
+)
+```
 
-// Remove immediately
-await activity.end(finalContent, dismissalPolicy: .immediate)
+End on every terminal path, not just the happy one: success, cancellation by
+the user or the app, sign-out or session teardown, an app error you cannot
+recover from, and a terminal failure reported by the server. If the backend
+reports that the tracked event is over or that its status is no longer
+reliable, push or apply a
+final terminal state and end; never leave frozen progress on the Lock Screen.
 
-// Remove after a specific time (max 4 hours from now)
-await activity.end(finalContent, dismissalPolicy: .after(Date().addingTimeInterval(3600)))
-```
+Time limits, which are easy to conflate:
 
-Always end activities on all terminal code paths -- success, user/app
-cancellation, sign-out/session stop, unrecoverable app error, and terminal server
-failure. If the server says the tracked event can no longer continue or be
-represented accurately, apply or send a final terminal state and end the activity
-instead of leaving stale progress visible. 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).
+- The active phase lasts at most 8 hours; the app or the user may end it
+  earlier.
+- When the system ends it at that limit, the card may remain on the Lock Screen
+  for up to 4 more hours, 12 hours in total from the start.
+- When the app ends it with `.default`, the card can stay visible for as much
+  as 4 hours past the end call.
 
-## Lock Screen Presentation
+## Lock Screen
 
-The Lock Screen is the primary Live Activity display surface. Every device with
-iOS 16.1+ displays Live Activities here. Design this layout first, then adapt
-for Dynamic Island where available.
+The Lock Screen is the surface that always exists: every device on iOS 16.1 or
+later shows Live Activities there. Lay it out first, then squeeze it into the
+Dynamic Island.
 
 ```swift
-struct DeliveryActivityWidget: Widget {
-    var body: some WidgetConfiguration {
-        ActivityConfiguration(for: DeliveryAttributes.self) { context in
-            VStack(alignment: .leading) {
-                Text(context.attributes.restaurantName).font(.headline)
+import SwiftUI
+import WidgetKit
 
+struct ChargingLiveActivity: Widget {
+    var body: some WidgetConfiguration {
+        ActivityConfiguration(for: ChargingAttributes.self) { context in
+            HStack(spacing: 12) {
+                Image(systemName: context.state.phase.symbolName)
+                VStack(alignment: .leading) {
+                    Text(context.attributes.stationName).font(.headline)
+                    Text("\(context.state.batteryPercent)%")
+                }
+                Spacer()
                 if context.isStale {
-                    Label("Updating...", systemImage: "arrow.trianglehead.2.clockwise")
+                    Label("Refreshing", systemImage: "arrow.trianglehead.2.clockwise")
                         .foregroundStyle(.secondary)
                 } else {
-                    Text(timerInterval: context.state.estimatedDeliveryTime, countsDown: true)
+                    Text(timerInterval: context.state.finishWindow, countsDown: true)
                         .monospacedDigit()
                 }
             }
@@ -218,274 +224,226 @@ struct DeliveryActivityWidget: Widget {
         } dynamicIsland: { context in
             DynamicIsland {
                 DynamicIslandExpandedRegion(.center) {
-                    Text(context.attributes.restaurantName).font(.headline)
+                    Text(context.attributes.stationName)
                 }
                 DynamicIslandExpandedRegion(.trailing) {
-                    Text(timerInterval: context.state.estimatedDeliveryTime, countsDown: true)
+                    Text("\(context.state.batteryPercent)%")
                 }
             } compactLeading: {
-                Image(systemName: "box.truck.fill")
+                Image(systemName: "bolt.car")
             } compactTrailing: {
-                Text(timerInterval: context.state.estimatedDeliveryTime, countsDown: true)
+                Text(timerInterval: context.state.finishWindow, countsDown: true)
+                    .monospacedDigit()
             } minimal: {
-                Image(systemName: "box.truck.fill")
+                Image(systemName: "bolt.car")
             }
         }
     }
 }
 ```
 
-### Supplemental Activity Families
+Static values come from `context.attributes`; changing values from
+`context.state`.
 
-The Lock Screen presentation has limited vertical space. Avoid layouts taller
-than roughly 160 points. On iOS 18+, use `supplementalActivityFamilies` when
-you provide adaptive layouts beyond the default: `.medium` for iOS/macOS
-Live Activity sizing and `.small` for watchOS Live Activity sizing.
+### Height and supplemental families
 
-```swift
-ActivityConfiguration(for: DeliveryAttributes.self) { context in
-    // Lock Screen content
-} dynamicIsland: { context in
-    // Dynamic Island
-}
-.supplementalActivityFamilies([.medium, .small])
-```
+The Lock Screen gives a Live Activity little vertical room; keep the layout
+under roughly 160 points. From iOS 18,
+`.supplementalActivityFamilies([.small, .medium])` on the
+`ActivityConfiguration` opts into adaptive sizes: `.medium` is the iPhone and
+Mac size, `.small` the Apple Watch size.
 
 ## Dynamic Island
 
-Dynamic Island presentations appear only on devices that include Dynamic Island.
-Design all three modes, but treat the Lock Screen as the primary surface since
-not all devices have a Dynamic Island.
-
-### Compact (Leading + Trailing)
-
-Used when one Live Activity occupies Dynamic Island compact space. Space is
-extremely limited -- show only the most critical information.
-
-| Region | Purpose |
-|---|---|
-| `compactLeading` | Icon or tiny label identifying the activity |
-| `compactTrailing` | One key value (timer, score, status) |
-
-### Minimal
-
-Shown when multiple Live Activities compete for space. Only one activity gets
-the minimal slot. Display a single icon or glyph.
-
-### Expanded Regions
-
-Shown when the user long-presses the Dynamic Island.
+Only devices with a Dynamic Island show these presentations. Implement all
+three modes anyway; the Lock Screen remains the main design.
 
-| Region | Position |
-|---|---|
-| `.leading` | Left of the TrueDepth camera; wraps below |
-| `.trailing` | Right of the TrueDepth camera; wraps below |
-| `.center` | Directly below the camera |
-| `.bottom` | Below all other regions |
-
-### Keyline Tint
-
-Apply a subtle tint to the Dynamic Island border:
-
-```swift
-DynamicIsland { /* expanded */ }
-    compactLeading: { /* ... */ }
-    compactTrailing: { /* ... */ }
-    minimal: { /* ... */ }
-    .keylineTint(.blue)
-```
+- **Compact**: one Live Activity owns the island. Show the single most
+  important fact.
+  - `compactLeading`: an icon or a very short label saying what this is.
+  - `compactTrailing`: one value, such as a timer, a score or a status.
+- **Minimal**: several Live Activities compete; one of them gets the minimal
+  slot. Show a single glyph.
+- **Expanded**: appears on a long press of the island. Regions:
+  - `.leading`: the camera's left side; content can wrap below it.
+  - `.trailing`: the camera's right side; content can wrap below it.
+  - `.center`: directly below the camera.
+  - `.bottom`: below everything else.
 
-## Push-to-Update
+`.keylineTint(_:)` on the `DynamicIsland` tints the island's outline subtly.
 
-Push-to-update sends Live Activity updates through APNs, which is more
-efficient than polling from the app and works when the app is suspended, subject
-to APNs delivery, priority, budget, and throttling.
+## Server-driven updates
 
-### Setup
+APNs pushes are cheaper than having the app poll, and they reach an activity
+while the app is suspended. They are still subject to APNs delivery, priority,
+the system budget and throttling.
 
-Pass `.token` as the `pushType` when starting the activity, then forward the
-per-activity update token to your server. Update tokens can rotate, so observe
-`activity.pushTokenUpdates` and re-register every emitted token:
+Setup: request with `pushType: .token`, then give the server the update token
+that belongs to this one activity. Tokens rotate, so consume `activity.pushTokenUpdates` (an async
+sequence of `Data`) for the whole life of the activity and re-register every
+value it emits.
 
 ```swift
-let activity = try Activity.request(
-    attributes: attributes,
-    content: content,
-    pushType: .token
-)
-
-// Observe token changes -- tokens can rotate
 Task {
-    for await token in activity.pushTokenUpdates {
-        let tokenString = token.map { String(format: "%02x", $0) }.joined()
-        try await ServerAPI.shared.registerActivityToken(
-            tokenString, activityID: activity.id
-        )
+    for await tokenData in activity.pushTokenUpdates {
+        let hex = tokenData.reduce(into: "") { $0 += String(format: "%02x", $1) }
+        try? await backend.registerActivityToken(hex, for: activity.id)
     }
 }
 ```
 
-### APNs Payload Format
+### Payload and headers
 
-Send an HTTP/2 POST to APNs with these headers and JSON body:
+Send an HTTP/2 `POST` to APNs carrying these headers:
 
-**Required device-token HTTP headers:**
-- `apns-push-type: liveactivity`
-- `apns-topic: <bundle-id>.push-type.liveactivity`
-- `apns-priority: 5` (lower priority) or `10` (immediate, counts against budget)
+- `apns-push-type: liveactivity` (required)
+- `apns-topic: BUNDLE_ID.push-type.liveactivity` (required)
+- `apns-priority: 5` for low priority, or `10` for immediate delivery that
+  counts against the budget
 
-The `aps.alert` payload controls visible alert/banner/sound behavior; priority
-alone does not create an alert.
+Priority never produces an alert. A visible banner or sound comes only from an
+`aps.alert` object.
 
-**Payload body:** Put `timestamp`, `event`, and the full `content-state` inside `aps`. Use `event: "update"` for updates, `event: "end"` plus optional `dismissal-date` for ending, and `event: "start"` with `attributes-type`, `attributes`, `content-state`, and required `alert` for push-to-start. Add `stale-date`, `relevance-score`, or `alert` when appropriate.
+Everything sits inside `aps`: `timestamp`, `event`, and the full
+`content-state`.
 
-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. Mismatched keys or types can prevent ActivityKit from applying the update.
+- `"event": "update"` changes the activity.
+- `"event": "end"` ends it; `dismissal-date` is optional.
+- `"event": "start"` is push-to-start; it adds `attributes-type` and
+  `attributes` alongside `content-state`, and `alert` is required.
+- Optional on any event: `stale-date`, `relevance-score`, `alert`.
 
-### Push-to-Start
+`content-state` must decode into `ContentState`. With synthesized `Codable`,
+the keys are the property names and the values use the default encodings. If
+the type has custom `CodingKeys` or custom coding, agree on the exact keys and
+value shapes with the server team. A misspelled key, or a number sent as text,
+can be enough for ActivityKit to drop the update.
 
-Start a Live Activity remotely without the app running (iOS 17.2+). Push-to-start tokens are ActivityKit-specific tokens from `Activity<Attributes>.pushToStartTokenUpdates`; they are distinct from ordinary app/device APNs tokens and per-activity update tokens:
+### Push-to-start (iOS 17.2+)
 
-```swift
-Task {
-    for await token in Activity<DeliveryAttributes>.pushToStartTokenUpdates {
-        let tokenString = token.map { String(format: "%02x", $0) }.joined()
-        try await ServerAPI.shared.registerPushToStartToken(tokenString)
-    }
-}
-```
+A server can start an activity while the app is not running. The token comes
+from the static sequence `Activity<ChargingAttributes>.pushToStartTokenUpdates`.
+It is neither the app's ordinary device token nor any activity's update token;
+store and send it separately.
 
-### Frequent Push Updates
+### Frequent updates
 
-Add `NSSupportsLiveActivitiesFrequentUpdates = YES` to Info.plist to increase
-the system-managed push update budget. When cadence matters, check
-`ActivityAuthorizationInfo.frequentPushesEnabled` and observe
-`frequentPushEnablementUpdates`; Apple does not guarantee a fixed update rate.
+`NSSupportsLiveActivitiesFrequentUpdates = YES` in Info.plist raises the
+system-managed push budget. The user can switch it off, so when cadence
+matters read `ActivityAuthorizationInfo().frequentPushesEnabled` and observe
+`frequentPushEnablementUpdates`. There is no guaranteed update rate; do not
+promise one.
 
-## Recent Additions
+## Newer capabilities
 
-### Scheduled Live Activities (iOS 26+)
+### ActivityStyle (iOS 18+)
 
-Schedule a Live Activity to start at a future time. The system starts the
-activity automatically without the app being in the foreground. Use for events
-with known start times (sports games, product launches, scheduled deliveries).
+`Activity.request(...style:)` is available from iOS 18, not only iOS 26.
 
-```swift
-let scheduledDate = Calendar.current.date(
-    from: DateComponents(year: 2026, month: 3, day: 15, hour: 19, minute: 0)
-)!
-
-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: scheduledDate
-)
-```
+- `.standard`: for anything that should persist: deliveries, rides, scores,
+  timers, order boards.
+- `.transient`: only for brief expanded Dynamic Island moments. The system may
+  end it when the device locks, when the expanded view collapses, when the
+  user leaves the app, or when the activity would appear outside the Dynamic
+  Island.
 
-### ActivityStyle (iOS 18+ request parameter)
+### Scheduled start (iOS 26+)
 
-Use the iOS 18+ `style:` request parameter to choose persistence behavior. Use
-`.standard` for persistent Live Activities such as deliveries, rides, sports
-scores, timers, and order-status boards. Use `.transient` only for a
-short-lived expanded Dynamic Island presentation; it 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.
+For events with a known start time (a match, a product launch, a booked
+delivery slot), schedule the activity and let the system start it without the
+app in the foreground:
 
 ```swift
+guard let kickoff = Calendar.current.date(
+    from: DateComponents(year: 2026, month: 11, day: 14, hour: 19, minute: 30)
+) else { return }
 let activity = try Activity.request(
     attributes: attributes,
     content: content,
     pushType: .token,
-    style: .standard
-)
-```
-
-### Paired Mac & CarPlay (iOS 26+)
-
-Live Activities can appear on a paired Mac and on the CarPlay Home Screen. No additional ActivityKit API is required, but validate compact layouts; buttons and toggles in Live Activities do not perform actions in CarPlay.
-
-### Channel-Based Push (iOS 18+)
-
-Broadcast updates to many Live Activities at once with an APNs-created channel
-ID. Enable the broadcast capability outside Xcode, create the channel on the
-server, then subscribe with `.channel(channelID)`. Channel pushes update or end
-Live Activities; they do not start them. Use `apns-channel-id` and expiration
-for channel pushes instead of the device-token `apns-topic` example above.
-
-```swift
-let activity = try Activity.request(
-    attributes: attributes, content: content,
-    pushType: .channel(channelIDFromServer)
+    style: .standard,
+    alertConfiguration: AlertConfiguration(
+        title: "Match starting", body: "Tap to follow live.", sound: .default
+    ),
+    start: kickoff
 )
 ```
 
-## Common Mistakes
-
-**DON'T:** Put too much content in the compact presentation -- it is tiny.
-**DO:** Show only the most critical info (icon + one value) in compact leading/trailing.
-
-**DON'T:** Update Live Activities too frequently from the app (drains battery).
-**DO:** Use push-to-update for server-driven updates. Limit app-side updates to user actions.
-
-**DON'T:** Forget to end the activity when the event reaches any terminal state.
-**DO:** End activities on success, cancellation, sign-out, unrecoverable errors, and terminal server failures. A leaked activity frustrates users.
-
-**DON'T:** Assume every device has Dynamic Island.
-**DO:** Design for the Lock Screen as the primary surface; Dynamic Island is supplementary.
-
-**DON'T:** Treat Lock Screen or Dynamic Island Live Activities as ordinary Home Screen/timeline widgets.
-**DO:** Use ActivityKit for the Live Activity lifecycle and those display surfaces; route ordinary Home Screen/timeline widgets to `widgetkit`.
-
-**DON'T:** Reduce Live Activity payload routing to generic `content-state` matching when the prompt involves APNs payloads.
-**DO:** Include the actual `ContentState` `Codable` contract and coordinated `Date`/`ClosedRange<Date>` encoding caveat; route generic APNs auth and registration to `push-notifications`.
-
-**DON'T:** Store sensitive information in ActivityAttributes (visible on Lock Screen).
-**DO:** Keep sensitive data in the app and show only safe-to-display summaries.
-
-**DON'T:** Forget to handle stale dates.
-**DO:** Check `context.isStale` in views and show fallback UI ("Updating..." or similar).
-
-**DON'T:** Ignore push token rotation. Tokens can change at any time.
-**DO:** Use `activity.pushTokenUpdates` async sequence and re-register on every emission.
-
-**DON'T:** Forget the `NSSupportsLiveActivities` Info.plist key.
-**DO:** Add `NSSupportsLiveActivities = YES` to the host app's Info.plist (not the extension).
-
-**DON'T:** Use the deprecated `contentState`-based API for request/update/end.
-**DO:** Use `ActivityContent` for all lifecycle calls.
-
-**DON'T:** Fetch network data or location directly from Live Activity views.
-**DO:** Pre-compute display values in the app or server and pass them through ActivityKit updates or pushes.
-
-## Review Checklist
-
-- [ ] `ActivityAttributes` defines static properties and `ContentState`
-- [ ] `NSSupportsLiveActivities = YES` in host app Info.plist
-- [ ] Activity uses `ActivityContent` (not deprecated contentState API)
-- [ ] Activity ended in all terminal paths (success, error, cancellation, sign-out, terminal server failure)
-- [ ] ActivityKit lifecycle and Lock Screen/Dynamic Island Live Activity surfaces are separated from ordinary Home Screen/timeline widget work
-- [ ] Lock Screen layout, the primary Live Activity surface, handles `context.isStale`
-- [ ] Dynamic Island compact, expanded, and minimal implemented with Lock Screen fallback
-- [ ] Push update token forwarded to server via `activity.pushTokenUpdates`
-- [ ] Push-to-start token collected via `Activity<Attributes>.pushToStartTokenUpdates`
-- [ ] Push-to-start payload includes required `alert`
-- [ ] `content-state` JSON matches the actual `ContentState` `Codable` shape, including coordinated date/range encoding
-- [ ] Review distinguishes 8-hour active lifetime, 12-hour total system-ended Lock Screen presence, and 4-hour app-ended `.default` linger
+### Paired Mac and CarPlay (iOS 26+)
+
+A paired Mac and the CarPlay Home Screen both show Live Activities, and
+ActivityKit needs no additional code for either. Check that the compact layouts read well there.
+Buttons and toggles inside a Live Activity do nothing in CarPlay.
+
+### Channel pushes (iOS 18+)
+
+One push can update many activities through a channel ID that APNs creates.
+Turn on the broadcast capability for the app in the developer portal (it is not
+an Xcode setting), have the server create the channel, then request with `pushType: .channel(channelID)`. Channel pushes
+update or end activities; they cannot start one. They are addressed with
+`apns-channel-id` and an expiration rather than the device-token `apns-topic`.
+
+## Common mistakes
+
+1. A crowded compact view. One icon and one value is the budget.
+2. Updating from the app too often, which drains battery. Let the server push
+   its own changes; update locally only in response to user actions.
+3. Forgetting to end on some terminal path. A leftover activity is a bug the
+   user has to clear by hand.
+4. Designing for the Dynamic Island first. Many devices have none; the Lock
+   Screen is primary.
+5. Treating a Live Activity as a Home Screen widget with a timeline. Use the
+   ActivityKit lifecycle; send timeline widgets to `widgetkit`.
+6. Reducing payload guidance to "match the content-state". State the real
+   `ContentState` `Codable` contract and the `Date` / `ClosedRange<Date>`
+   caveat; only the generic APNs pieces (auth keys, registration) move to
+   `push-notifications`.
+7. Sensitive values in attributes or state. The card is readable on a locked
+   phone; show a safe summary.
+8. Ignoring `staleDate`. Check `context.isStale` and render a fallback.
+9. Registering the update token once. It can change at any time; re-send it on
+   every `pushTokenUpdates` value.
+10. `NSSupportsLiveActivities` placed in the extension target's plist. The key
+    is read from the main app.
+11. The deprecated `contentState:` variants of request, update and end. Use
+    `ActivityContent` throughout.
+12. Network or location work inside Live Activity views. Compute it in the app
+    or on the server and deliver the result through an update or a push.
+
+## Review checklist
+
+- [ ] `ActivityAttributes` separates static properties from `ContentState`
+- [ ] Host app Info.plist has `NSSupportsLiveActivities = YES`
+- [ ] Request, update and end use `ActivityContent`, not the deprecated
+      `contentState` API
+- [ ] Activity ends on success, error, cancellation, sign-out and terminal
+      server failure
+- [ ] ActivityKit lifecycle and surfaces are kept apart from Home Screen or
+      timeline widget code
+- [ ] Lock Screen view handles `context.isStale`
+- [ ] Compact, expanded and minimal Dynamic Island modes exist, with the Lock
+      Screen as the fallback
+- [ ] Update token forwarded from `activity.pushTokenUpdates`
+- [ ] Push-to-start token collected from
+      `Activity<Attributes>.pushToStartTokenUpdates`
+- [ ] Push-to-start payload carries `alert`
+- [ ] `content-state` JSON matches the real `ContentState` coding, including an
+      agreed date and range encoding
+- [ ] Durations are stated separately: 8 h active, 12 h total after a system
+      end, 4 h linger after an app end with `.default`
 - [ ] `ActivityAuthorizationInfo` checked before starting
-- [ ] `frequentPushesEnabled` checked before assuming high-cadence pushes
-- [ ] ContentState kept small (serialized on every update)
-- [ ] iOS 18+ availability guarded for `style:`, `.channel`, and supplemental families
-- [ ] iOS 18+ `style:` choices are justified: `.standard` for persistent Live Activities, `.transient` only for short-lived expanded Dynamic Island presentations
-- [ ] ActivityKit push priority and `aps.alert` behavior are handled separately
-- [ ] Live Activity views avoid direct network/location work
-- [ ] Tested on device for push delivery and Dynamic Island behavior
+- [ ] `frequentPushesEnabled` checked before relying on high-cadence pushes
+- [ ] `ContentState` is small
+- [ ] `style:`, `.channel` and supplemental families are gated on iOS 18
+- [ ] Each `style:` choice is justified: `.standard` for persistent,
+      `.transient` only for short expanded moments
+- [ ] Push priority and `aps.alert` are handled as separate concerns
+- [ ] Views do no network or location work
+- [ ] Push delivery and Dynamic Island tested on a real device
 
 ## References
 
-- See [references/activitykit-patterns.md](references/activitykit-patterns.md) for patterns and code examples
+- [ActivityKit patterns](references/activitykit-patterns.md): complete
+  attributes model, start/update/end variants, server payloads and headers, channel pushes, concurrent activities, state and token observation,
+  authorization, errors, background behaviour, testing, Info.plist keys and
+  documentation links.