@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/push-notifications/SKILL.md

@@ -1,276 +1,281 @@
 ---
 name: push-notifications
-description: "Implement, review, or debug push notifications in iOS/macOS apps  -  local notifications, remote (APNs) notifications, rich notifications, notification actions, silent pushes, and notification service/content extensions. Use when working with UNUserNotificationCenter, registering for remote notifications, handling notification payloads, setting up notification categories and actions, creating rich notification content, or debugging notification delivery. Also use when working with alerts, badges, sounds, background pushes, or user notification permissions in Swift apps."
+description: "UserNotifications and APNs on iOS and macOS, local and remote: permission (standard, provisional, critical), device-token registration, triggers, payloads (alert, background, mutable, localized), foreground presentation, tap handling and deep links, categories and actions, grouping, service and content extensions, media attachments, communication notifications, delivery debugging. Use when building, reviewing or debugging notifications, badges, sounds, silent pushes or notification permission. Not for Live Activity, VoIP or App Clip pushes, or post-push background work."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
 # Push Notifications
 
-Implement, review, and debug local and remote notifications on iOS/macOS using `UserNotifications` and APNs. Covers permission flow, token registration, payload structure, foreground handling, notification actions, grouping, and rich notifications. Targets iOS 26+ with Swift 6.3, backward-compatible to iOS 16 unless noted.
-
-Keep adjacent domains separate: Live Activity `content-state` payloads belong in `activitykit`; PushKit/VoIP call pushes belong in `callkit`; App Clip ephemeral notification setup belongs in `app-clips`; long-running or scheduled background work after a silent push belongs in `background-processing`.
-
-## Contents
-
-- [Correction Reviews](#correction-reviews)
-- [Permission Flow](#permission-flow)
-- [APNs Registration](#apns-registration)
-- [Local Notifications](#local-notifications)
-- [Remote Notification Payload](#remote-notification-payload)
-- [Notification Handling](#notification-handling)
-- [Notification Actions and Categories](#notification-actions-and-categories)
-- [Notification Grouping](#notification-grouping)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
-
-## Correction Reviews
-
-When reviewing flawed notification proposals, explicitly name the violated contract. APNs token reviews must say token registration is independent from alert authorization, upload on every `didRegister` callback, avoid local-cache-as-truth logic, never assume token length, and treat Simulator registration failure as expected while noting `.apns` files or `simctl push` can simulate delivery. Background-push reviews must say `content-available` only, `apns-push-type: background`, `apns-priority: 5`, Remote notifications background mode, low priority, throttled, not guaranteed, not every few minutes, and bounded `didReceiveRemoteNotification` returning the correct `UIBackgroundFetchResult`. Rich-notification reviews must say service extensions require `mutable-content: 1` plus an alert payload, silent pushes do not trigger them, attachments are supported on-disk files that the system validates and stores, secrets use Keychain Sharing while App Groups are for shared files/UserDefaults, communication notifications require capability + `NSUserActivityTypes` + `INInteraction` donation + `content.updating(from:)`, and every service-extension path including attachment/download failures and `serviceExtensionTimeWillExpire()` must call the content handler exactly once with original, best-attempt, or updated content.
-
-## Permission Flow
-
-Request notification authorization before scheduling or displaying user-visible alerts, sounds, or badges. The system prompt appears only once; subsequent calls return the stored decision. APNs token registration is separate: call `registerForRemoteNotifications()` when the app needs a device token, even if the user hasn't granted alert authorization.
+Notifications on Apple platforms come from two places: the device itself
+(local notifications scheduled through `UserNotifications`) and a server that
+talks to the Apple Push Notification service (APNs). Both end up in the same
+`UNUserNotificationCenter`, so permission, presentation, actions and grouping
+work the same way for each.
+
+Baseline: iOS 26 and Swift 6.3. Everything here also works back to iOS 16
+unless a section names a newer release.
+
+Hand these to their own skills:
+
+| Topic | Skill |
+|-------|-------|
+| Live Activity `content-state` pushes | `live-activities` |
+| PushKit and VoIP call pushes | `callkit-voip` |
+| Ephemeral App Clip notifications | `app-clips` |
+| Scheduled or long background work triggered by a push | `background-processing` |
+
+Longer material:
+the [app-side patterns](references/notification-patterns.md) (launch wiring,
+the delegate, routing taps to screens, silent-push handling, a scheduler, the
+token lifecycle, testing, badges) and the
+[extensions guide](references/rich-notifications.md) (service and content
+extensions, attachments, communication notifications).
+
+## Reviewing Someone Else's Design
+
+When a proposal is wrong, say which contract it breaks, then give the fix.
+"Move this call" is not enough; "registration does not depend on alert
+permission, so this gate blocks silent pushes" is. The contracts that come up
+most often:
+
+**Device token**
+- Getting an APNs token and getting alert permission are two separate things.
+- Send the token to the server from every `didRegister` callback.
+- A token saved on the device is a cache, never the truth.
+- Token length is not fixed; never hard-code or validate a size.
+- On Simulator, registration fails by design. Pushes can still be simulated
+  with a `.apns` file or `xcrun simctl push`.
+
+**Background (silent) push**
+- Payload carries `content-available: 1` and nothing that alerts: no alert, sound or badge.
+- Send it at priority 5 (`apns-priority: 5`) with the header `apns-push-type: background`.
+- Turn on Remote notifications under the app's Background Modes capability.
+- APNs treats it as low priority and throttles it; it may never arrive. It is
+  not a scheduler, so a cadence of one every few minutes will not happen.
+- `didReceiveRemoteNotification` does short, bounded work and returns the
+  `UIBackgroundFetchResult` that matches what actually happened.
+
+**Rich notifications**
+- A service extension runs only for an alerting push with `mutable-content: 1`.
+  A silent push never reaches it.
+- Attachments must be supported files already on disk; the system checks them
+  and moves them into its own store.
+- Secrets such as decryption keys live in a shared Keychain access group. App
+  Groups are for shared files and `UserDefaults` only.
+- Communication notifications need four things: the capability, an
+  `NSUserActivityTypes` entry, a donated `INInteraction`, and a call to
+  `content.updating(from:)`.
+- The content handler is called exactly once on every path: success, failed
+  download, failed decryption, and `serviceExtensionTimeWillExpire()`. It
+  receives the updated content, the best attempt so far, or the original.
+
+## Permission
+
+Ask before scheduling anything the user will see or hear, or before setting a
+badge. iOS shows the system prompt a single time; after that the call returns
+whatever the user chose. Registering with APNs is a different path and may
+happen even if the user said no to alerts.
 
 ```swift
-import UserNotifications
-
 @MainActor
-func requestNotificationPermission() async -> Bool {
-    let center = UNUserNotificationCenter.current()
+func askForAlertPermission() async -> Bool {
     do {
-        let granted = try await center.requestAuthorization(
-            options: [.alert, .sound, .badge]
-        )
-        return granted
+        return try await UNUserNotificationCenter.current()
+            .requestAuthorization(options: [.alert, .sound, .badge])
     } catch {
-        print("Authorization request failed: \(error)")
         return false
     }
 }
 ```
 
-### Checking Current Status
+### Reading the current setting
 
-Always check status before assuming permissions. The user can change settings at any time.
+The user can change the setting in Settings at any moment, so read it instead
+of remembering an old answer.
 
 ```swift
-@MainActor
-func checkNotificationStatus() async -> UNAuthorizationStatus {
-    let settings = await UNUserNotificationCenter.current().notificationSettings()
-    return settings.authorizationStatus
-    // .notDetermined, .denied, .authorized, .provisional, .ephemeral
+let center = UNUserNotificationCenter.current()
+let current = await center.notificationSettings()
+switch current.authorizationStatus {
+case .notDetermined: break   // never asked
+case .denied: break          // user said no
+case .authorized: break
+case .provisional: break     // quiet delivery, no prompt shown
+case .ephemeral: break       // App Clip
+@unknown default: break
 }
 ```
 
-### Provisional Notifications
-
-Provisional notifications deliver quietly to the notification center without interrupting the user. The user can then choose to keep or turn them off. Use for onboarding flows where you want to demonstrate value before asking for full permission.
+### Provisional authorization
 
-```swift
-// Delivers silently -- no permission prompt shown to the user
-try await center.requestAuthorization(options: [.alert, .sound, .badge, .provisional])
-```
+Adding `.provisional` to the options skips the prompt. Notifications go
+straight to Notification Center without sound or banner, and the user decides
+later whether to keep them. It suits onboarding: show value first, ask for full
+permission afterwards.
 
-### Critical Alerts
+### Critical alerts
 
-Critical alerts bypass Do Not Disturb and the mute switch. Requires a special entitlement from Apple (request via developer portal). Use only for health, safety, or security scenarios.
-
-```swift
-// Requires com.apple.developer.usernotifications.critical-alerts entitlement
-try await center.requestAuthorization(
-    options: [.alert, .sound, .badge, .criticalAlert]
-)
-```
+`.criticalAlert` plays through Do Not Disturb and the ring/silent switch. It
+needs the `com.apple.developer.usernotifications.critical-alerts` entitlement,
+which Apple grants on request through the developer portal. Reserve it for
+health, safety and security situations.
 
-### Handling Denied Permissions
+### When the user said no
 
-When the user has denied notifications, guide them to Settings with `UIApplication.openSettingsURLString`. Do not repeatedly prompt or nag.
+Do not ask again and do not nag. Offer a button that opens the app's page in
+Settings through `UIApplication.openSettingsURLString`.
 
-## APNs Registration
+## Registering with APNs
 
-Use `UIApplicationDelegateAdaptor` to receive the device token in a SwiftUI app. The AppDelegate callbacks are the only way to receive APNs tokens.
+A SwiftUI app still needs an app delegate for this: the device token is only
+delivered to `UIApplicationDelegate` callbacks. Attach one with
+`@UIApplicationDelegateAdaptor`.
 
 ```swift
-@main
-struct MyApp: App {
-    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
-
-    var body: some Scene {
-        WindowGroup {
-            ContentView()
-        }
-    }
-}
-
-class AppDelegate: NSObject, UIApplicationDelegate {
+final class AppDelegate: NSObject, UIApplicationDelegate {
     func application(
         _ application: UIApplication,
-        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
+        didFinishLaunchingWithOptions options: [UIApplication.LaunchOptionsKey: Any]? = nil
     ) -> Bool {
-        UNUserNotificationCenter.current().delegate = NotificationDelegate.shared
+        UNUserNotificationCenter.current().delegate = InboxNotificationDelegate.shared
         return true
     }
 
-    func application(
-        _ application: UIApplication,
-        didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
-    ) {
-        let token = deviceToken.map { String(format: "%02x", $0) }.joined()
-        print("APNs token: \(token)")
-        // Send token to your server
-        Task { await TokenService.shared.upload(token: token) }
+    func application(_ application: UIApplication,
+                     didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
+        let hex = deviceToken.reduce(into: "") { $0 += String(format: "%02x", $1) }
+        Task { await DeviceTokenUploader.shared.send(hex) }
     }
 
-    func application(
-        _ application: UIApplication,
-        didFailToRegisterForRemoteNotificationsWithError error: Error
-    ) {
-        print("APNs registration failed: \(error.localizedDescription)")
-        // Simulator can simulate pushes, but it does not register with APNs.
+    func application(_ application: UIApplication,
+                     didFailToRegisterForRemoteNotificationsWithError error: Error) {
+        // Expected on Simulator: it can show simulated pushes but never gets an APNs token.
     }
 }
 ```
 
-### Registration Order
+### Order of calls
 
-Configure delegates and categories at launch. Then request user-notification authorization in context for visible notifications, and register with APNs whenever the app needs a device token. Do not gate APNs registration on `.authorized`; without alert authorization, remote notifications are delivered silently.
+1. At launch: set the delegate and register categories.
+2. At a moment that makes sense to the user: ask for alert permission.
+3. Whenever a token is needed: call `registerForRemoteNotifications()`.
+
+Do not wait for `.authorized` before step 3. An app without alert permission
+still receives remote notifications, just silently, and the server still needs
+the token.
 
 ```swift
 @MainActor
-func configureNotifications() async {
+func prepareNotifications() async {
     let center = UNUserNotificationCenter.current()
-    let settings = await center.notificationSettings()
-
-    if settings.authorizationStatus == .notDetermined {
-        _ = await requestNotificationPermission()
+    if await center.notificationSettings().authorizationStatus == .notDetermined {
+        _ = try? await center.requestAuthorization(options: [.alert, .badge, .sound])
     }
-
-    // Needed for APNs token delivery and silent remote notifications.
-    UIApplication.shared.registerForRemoteNotifications()
+    UIApplication.shared.registerForRemoteNotifications()   // token + silent pushes
 }
 ```
 
-### Token Handling
+### Token rules
 
-Device tokens change. Re-send the token to your server every time `didRegisterForRemoteNotificationsWithDeviceToken` fires, not just the first time. Do not persist tokens locally as a source of truth or assume a fixed token length.
+The token can change (restore, reinstall, new device, OS update). Upload it
+from every `didRegisterForRemoteNotificationsWithDeviceToken` call, not only the
+first one. Do not keep a local copy as the source of truth, and do not assume a
+length.
 
 ## Local Notifications
 
-Schedule notifications directly from the device without a server. Useful for reminders, timers, and location-based alerts.
-
-### Creating Content
+Local notifications need no server: the device schedules and shows them.
+Reminders, timers and arriving at a place are the usual cases.
 
 ```swift
 let content = UNMutableNotificationContent()
-content.title = "Workout Reminder"
-content.subtitle = "Time to move"
-content.body = "You have a scheduled workout in 15 minutes."
+content.title = "Plants"
+content.subtitle = "Balcony"
+content.body = "The basil has not been watered for three days."
 content.sound = .default
 content.badge = NSNumber(value: 1)
-content.userInfo = ["workoutId": "abc123"]
-content.threadIdentifier = "workouts"  // groups in notification center
+content.userInfo = ["plantID": "basil-01"]
+content.threadIdentifier = "garden"   // groups these together in Notification Center
 ```
 
-### Trigger Types
+### Triggers
 
 ```swift
-// Fire after a time interval (minimum 60 seconds for repeating)
-let timeTrigger = UNTimeIntervalNotificationTrigger(timeInterval: 300, repeats: false)
-
-// Fire at a specific date/time
-var dateComponents = DateComponents()
-dateComponents.hour = 8
-dateComponents.minute = 30
-let calendarTrigger = UNCalendarNotificationTrigger(
-    dateMatching: dateComponents, repeats: true  // daily at 8:30 AM
-)
-
-// Fire when entering a geographic region
-let region = CLCircularRegion(
-    center: CLLocationCoordinate2D(latitude: 37.33, longitude: -122.01),
-    radius: 100,
+// Once, 15 minutes from now. A repeating interval must be at least 60 seconds.
+let soon = UNTimeIntervalNotificationTrigger(timeInterval: 900, repeats: false)
+
+// Every day at 07:30.
+var morning = DateComponents()
+morning.hour = 7
+morning.minute = 30
+let daily = UNCalendarNotificationTrigger(dateMatching: morning, repeats: true)
+
+// On arriving at a place. Needs at least When In Use location permission.
+let gym = CLCircularRegion(
+    center: CLLocationCoordinate2D(latitude: 52.37, longitude: 4.89),
+    radius: 150,
     identifier: "gym"
 )
-region.notifyOnEntry = true
-region.notifyOnExit = false
-let locationTrigger = UNLocationNotificationTrigger(region: region, repeats: false)
-// Requires "When In Use" location permission at minimum
+gym.notifyOnEntry = true
+gym.notifyOnExit = false
+let arrival = UNLocationNotificationTrigger(region: gym, repeats: false)
 ```
 
-### Scheduling and Managing
+### Scheduling and cleanup
 
 ```swift
-let request = UNNotificationRequest(
-    identifier: "workout-reminder-abc123",
-    content: content,
-    trigger: timeTrigger
-)
-
 let center = UNUserNotificationCenter.current()
+let request = UNNotificationRequest(identifier: "water-basil", content: content, trigger: daily)
 try await center.add(request)
 
-// Remove specific pending notifications
-center.removePendingNotificationRequests(withIdentifiers: ["workout-reminder-abc123"])
+let waiting = await center.pendingNotificationRequests()
 
-// Remove all pending
+center.removePendingNotificationRequests(withIdentifiers: ["water-basil"])
 center.removeAllPendingNotificationRequests()
-
-// Remove delivered notifications from notification center
-center.removeDeliveredNotifications(withIdentifiers: ["workout-reminder-abc123"])
+center.removeDeliveredNotifications(withIdentifiers: ["water-basil"])
 center.removeAllDeliveredNotifications()
-
-// List all pending requests
-let pending = await center.pendingNotificationRequests()
 ```
 
-## Remote Notification Payload
+## Remote Payloads
 
-### Standard APNs Payload
+### Alert push
 
 ```json
 {
-    "aps": {
-        "alert": {
-            "title": "New Message",
-            "subtitle": "From Alice",
-            "body": "Hey, are you free for lunch?"
-        },
-        "badge": 3,
-        "sound": "default",
-        "thread-id": "chat-alice",
-        "category": "MESSAGE_CATEGORY"
-    },
-    "messageId": "msg-789",
-    "senderId": "user-alice"
+  "aps": {
+    "alert": { "title": "Order shipped", "subtitle": "#4821", "body": "Arrives Thursday." },
+    "badge": 2,
+    "sound": "default",
+    "thread-id": "orders",
+    "category": "ORDER_UPDATE"
+  },
+  "orderID": "4821"
 }
 ```
 
-### Silent / Background Push
+App-specific keys go beside `aps`, never inside it.
 
-Set `content-available: 1` with no alert, sound, or badge. Requires "Background Modes > Remote notifications" plus APNs headers `apns-push-type: background` and `apns-priority: 5`. The system treats these as low priority, throttled, and not guaranteed; do not send them every few minutes or rely on them for immediate freshness. In `didReceiveRemoteNotification`, do bounded work and return a `UIBackgroundFetchResult` promptly, within the background execution window.
+### Background push
 
 ```json
-{
-    "aps": {
-        "content-available": 1
-    },
-    "updateType": "new-data"
-}
+{ "aps": { "content-available": 1 }, "syncScope": "inbox" }
 ```
 
-Handle in AppDelegate:
+- No `alert`, `sound` or `badge`.
+- Background Modes > Remote notifications must be on.
+- Header `apns-push-type: background`, priority `apns-priority: 5`.
+- Expect throttling and occasional drops. A push every few minutes will be
+  held back, and data freshness must not hinge on one arriving.
+- Finish quickly and return a result inside the short background window.
+
 ```swift
-func application(
-    _ application: UIApplication,
-    didReceiveRemoteNotification userInfo: [AnyHashable: Any]
-) async -> UIBackgroundFetchResult {
-    guard let updateType = userInfo["updateType"] as? String else {
-        return .noData
-    }
+func application(_ application: UIApplication,
+                 didReceiveRemoteNotification userInfo: [AnyHashable: Any]) async
+    -> UIBackgroundFetchResult {
+    guard let scope = userInfo["syncScope"] as? String else { return .noData }
     do {
-        try await DataSyncService.shared.sync(trigger: updateType)
+        try await MailboxSync.shared.refresh(scope: scope)
         return .newData
     } catch {
         return .failed
@@ -278,223 +283,190 @@ func application(
 }
 ```
 
-### Mutable Content
+### Mutable content
 
-Set `mutable-content: 1` plus an `alert` dictionary to let a Notification Service Extension modify an alerting remote notification before display. Silent pushes do not trigger the service extension. Use service extensions for bounded work such as downloading supported on-disk attachments, decrypting display text, or configuring communication notifications; call the content handler on every success, failure, and timeout path. For communication notifications, enable the capability, add `NSUserActivityTypes`, donate the `INInteraction`, then call `content.updating(from:)`.
+Adding `mutable-content: 1` to an alerting payload hands it to your
+Notification Service Extension before it is shown. Silent pushes do not start
+the extension.
 
 ```json
 {
-    "aps": {
-        "alert": { "title": "Photo", "body": "Alice sent a photo" },
-        "mutable-content": 1
-    },
-    "imageUrl": "https://example.com/photo.jpg"
+  "aps": {
+    "alert": { "title": "New photo", "body": "Ada shared a picture." },
+    "mutable-content": 1
+  },
+  "mediaURL": "https://media.example.com/p/77.jpg"
 }
 ```
 
-### Localized Notifications
+Good jobs for the extension, all kept short: fetch a supported attachment to
+disk, decrypt the visible text, and turn the push into a communication
+notification (capability, `NSUserActivityTypes`, `INInteraction` donation, then
+`content.updating(from:)`). Every outcome, including timeout, ends with exactly
+one call to the content handler. See the
+[extensions guide](references/rich-notifications.md#service-extension).
 
-Use localization keys so the notification displays in the user's language:
+### Localized payloads
+
+Let the device pick the language by sending keys instead of text:
 
 ```json
-{
-    "aps": {
-        "alert": {
-            "title-loc-key": "NEW_MESSAGE_TITLE",
-            "loc-key": "NEW_MESSAGE_BODY",
-            "loc-args": ["Alice"]
-        }
-    }
-}
+{ "aps": { "alert": { "title-loc-key": "SHIPPED_TITLE", "loc-key": "SHIPPED_BODY", "loc-args": ["Thursday"] } } }
 ```
 
-## Notification Handling
+## Handling Notifications
 
-### UNUserNotificationCenterDelegate
+### The delegate
 
-Implement the delegate to control foreground display and handle user taps. Set the delegate as early as possible -- in `application(_:didFinishLaunchingWithOptions:)` or `App.init`.
+Install `UNUserNotificationCenter.current().delegate` before launch finishes,
+from `App.init` or from `application(_:didFinishLaunchingWithOptions:)`.
 
 ```swift
 @MainActor
-final class NotificationDelegate: NSObject, UNUserNotificationCenterDelegate {
-    static let shared = NotificationDelegate()
-
-    // Called when notification arrives while app is in FOREGROUND
-    func userNotificationCenter(
-        _ center: UNUserNotificationCenter,
-        willPresent notification: UNNotification
-    ) async -> UNNotificationPresentationOptions {
-        // Return which presentation elements to show
-        // Without this, foreground notifications are silently suppressed
-        return [.banner, .sound, .badge]
+final class InboxNotificationDelegate: NSObject, UNUserNotificationCenterDelegate {
+    static let shared = InboxNotificationDelegate()
+
+    nonisolated func userNotificationCenter(_ center: UNUserNotificationCenter,
+                                            willPresent notification: UNNotification) async
+        -> UNNotificationPresentationOptions {
+        [.banner, .sound, .badge]
     }
 
-    // Called when user TAPS the notification
-    func userNotificationCenter(
-        _ center: UNUserNotificationCenter,
-        didReceive response: UNNotificationResponse
-    ) async {
-        let userInfo = response.notification.request.content.userInfo
-        let actionIdentifier = response.actionIdentifier
+    nonisolated func userNotificationCenter(_ center: UNUserNotificationCenter,
+                                            didReceive response: UNNotificationResponse) async {
+        let action = response.actionIdentifier
+        let threadID = response.notification.request.content.userInfo["threadID"] as? String
+        let typed = (response as? UNTextInputNotificationResponse)?.userText
+        await route(action: action, threadID: threadID, typed: typed)
+    }
 
-        switch actionIdentifier {
+    private func route(action: String, threadID: String?, typed: String?) async {
+        switch action {
         case UNNotificationDefaultActionIdentifier:
-            // User tapped the notification body
-            await handleNotificationTap(userInfo: userInfo)
+            AppRouter.shared.openThread(threadID)       // tapped the notification
         case UNNotificationDismissActionIdentifier:
-            // User dismissed the notification
-            break
+            break                                       // swiped away
         default:
-            // Custom action button tapped
-            await handleCustomAction(actionIdentifier, userInfo: userInfo)
+            await handleChatAction(action, threadID: threadID, typed: typed)
         }
     }
 }
 ```
 
-### Deep Linking from Notifications
+The system does not promise to call these methods on the main thread, and
+`UNNotification` and `UNNotificationResponse` are not `Sendable`. Mark the
+protocol methods `nonisolated`, copy the plain values you need out of the
+response (all payload data sits in `content.userInfo`), then hop to the main
+actor.
 
-Route notification taps to the correct screen using a shared `@Observable` router. The delegate writes a pending destination; the SwiftUI view observes and consumes it.
+Leave out `willPresent` and anything that arrives while your app is frontmost
+is dropped without a banner.
 
-```swift
-@Observable @MainActor
-final class DeepLinkRouter {
-    static let shared = DeepLinkRouter()
+### Deep links from a tap
 
-    var pendingDestination: AppDestination?
-}
-
-// In NotificationDelegate:
-func handleNotificationTap(userInfo: [AnyHashable: Any]) async {
-    guard let id = userInfo["messageId"] as? String else { return }
-    DeepLinkRouter.shared.pendingDestination = .chat(id: id)
-}
-
-// In SwiftUI -- observe and consume:
-.onChange(of: router.pendingDestination) { _, destination in
-    if let destination {
-        path.append(destination)
-        router.pendingDestination = nil
-    }
-}
-```
+Keep a single `@Observable @MainActor` router with an optional
+`pendingDestination`. The delegate sets it; the root view watches it with
+`.onChange(of:)`, pushes the destination onto its navigation path and then sets
+it back to `nil`. A version that also switches tabs lives in the
+[patterns reference](references/notification-patterns.md#routing-a-tap-to-a-screen).
 
-See [references/notification-patterns.md](references/notification-patterns.md) for the full deep-linking handler with tab switching.
+## Actions and Categories
 
-## Notification Actions and Categories
+Register categories at launch, before any notification can arrive.
 
-Define interactive actions that appear as buttons on the notification. Register categories at launch.
+```swift
+let reply = UNTextInputNotificationAction(
+    identifier: "REPLY",
+    title: "Reply",
+    options: [],
+    textInputButtonTitle: "Send",
+    textInputPlaceholder: "Message"
+)
+let archive = UNNotificationAction(identifier: "ARCHIVE", title: "Archive", options: [.destructive])
+let open = UNNotificationAction(identifier: "OPEN", title: "Open", options: [.foreground])
+let approve = UNNotificationAction(identifier: "APPROVE", title: "Approve", options: [.authenticationRequired])
 
-### Defining Categories and Actions
+let chat = UNNotificationCategory(
+    identifier: "CHAT",
+    actions: [reply, archive],
+    intentIdentifiers: [],
+    options: [.customDismissAction]    // dismissal also reaches didReceive
+)
+let request = UNNotificationCategory(identifier: "EXPENSE", actions: [approve, open], intentIdentifiers: [])
 
-```swift
-func registerNotificationCategories() {
-    let replyAction = UNTextInputNotificationAction(
-        identifier: "REPLY_ACTION",
-        title: "Reply",
-        options: [],
-        textInputButtonTitle: "Send",
-        textInputPlaceholder: "Type a reply..."
-    )
-
-    let likeAction = UNNotificationAction(
-        identifier: "LIKE_ACTION",
-        title: "Like",
-        options: []
-    )
-
-    let deleteAction = UNNotificationAction(
-        identifier: "DELETE_ACTION",
-        title: "Delete",
-        options: [.destructive, .authenticationRequired]
-    )
-
-    let messageCategory = UNNotificationCategory(
-        identifier: "MESSAGE_CATEGORY",
-        actions: [replyAction, likeAction, deleteAction],
-        intentIdentifiers: [],
-        options: [.customDismissAction]  // fires didReceive on dismiss too
-    )
-
-    UNUserNotificationCenter.current().setNotificationCategories([messageCategory])
-}
+UNUserNotificationCenter.current().setNotificationCategories([chat, request])
 ```
 
-### Handling Action Responses
+| Option | Effect |
+|--------|--------|
+| `.authenticationRequired` | Runs only after the device is unlocked |
+| `.destructive` | Shown in red; for delete or remove |
+| `.foreground` | Tapping it opens the app |
+
+A text action's response arrives as a `UNTextInputNotificationResponse`; its
+`userText` is what the delegate above passes on as `typed`:
 
 ```swift
-func handleCustomAction(_ identifier: String, userInfo: [AnyHashable: Any]) async {
-    switch identifier {
-    case "REPLY_ACTION":
-        // response is UNTextInputNotificationResponse for text input actions
-        break
-    case "LIKE_ACTION":
-        guard let messageId = userInfo["messageId"] as? String else { return }
-        await MessageService.shared.likeMessage(id: messageId)
-    case "DELETE_ACTION":
-        guard let messageId = userInfo["messageId"] as? String else { return }
-        await MessageService.shared.deleteMessage(id: messageId)
+@MainActor
+func handleChatAction(_ action: String, threadID: String?, typed: String?) async {
+    guard let threadID else { return }
+    switch action {
+    case "REPLY":
+        guard let typed, !typed.isEmpty else { return }
+        await ChatService.shared.send(typed, to: threadID)
+    case "ARCHIVE":
+        await ChatService.shared.archive(threadID)
     default:
         break
     }
 }
 ```
 
-Action options:
-- `.authenticationRequired` -- device must be unlocked to perform the action
-- `.destructive` -- displayed in red; use for delete/remove actions
-- `.foreground` -- launches the app to the foreground when tapped
-
-## Notification Grouping
+## Grouping
 
-Group related notifications with `threadIdentifier` (or `thread-id` in the APNs payload). Each unique thread becomes a separate group in Notification Center.
+Notifications with the same `threadIdentifier` (local) or `thread-id` (APNs)
+stack into one group; each distinct value is its own group. `summaryArgument`
+and `summaryArgumentCount` on the content feed the group's summary line, and a
+category can shape that line:
 
 ```swift
-content.threadIdentifier = "chat-alice"  // all messages from Alice group together
-content.summaryArgument = "Alice"
-content.summaryArgumentCount = 3         // "3 more notifications from Alice"
-```
-
-Customize the summary format string in the category:
-
-```swift
-let category = UNNotificationCategory(
-    identifier: "MESSAGE_CATEGORY",
-    actions: [replyAction],
+let chat = UNNotificationCategory(
+    identifier: "CHAT",
+    actions: [],
     intentIdentifiers: [],
-    categorySummaryFormat: "%u more messages from %@",
+    hiddenPreviewsBodyPlaceholder: nil,
+    categorySummaryFormat: "%u new messages from %@",
     options: []
 )
 ```
 
 ## Common Mistakes
 
-**DON'T:** Gate APNs token registration on alert authorization when the app needs silent pushes or server token binding.
-**DO:** Request authorization for alerts/sounds/badges, and register with APNs whenever a device token is needed.
-**DON'T:** Convert device token with `String(data: deviceToken, encoding: .utf8)`.
-**DO:** Use hex: `deviceToken.map { String(format: "%02x", $0) }.joined()`.
-**DON'T:** Promise every-few-minutes silent refresh or immediate background delivery.
-**DO:** Say background pushes are low priority, throttled, not guaranteed, limited to a few per hour in practice, and require bounded `didReceiveRemoteNotification` work that returns the correct `UIBackgroundFetchResult`.
-**DON'T:** Expect a silent push to run a Notification Service Extension, or leave the extension without calling its content handler.
-**DO:** Use `mutable-content: 1` with an alert payload, supported on-disk attachments that the system validates and stores, `INInteraction` donation plus `content.updating(from:)` for communication notifications, and original or best-attempt content on every success, failure, and timeout path.
-**DON'T:** Forget foreground handling. Without `willPresent`, notifications are silently suppressed.
-**DO:** Implement `willPresent` and return `.banner`, `.sound`, `.badge`.
-**DON'T:** Set delegate too late or register from SwiftUI views without AppDelegate adaptor.
-**DO:** Set delegate in `App.init`; use `UIApplicationDelegateAdaptor` for APNs.
-**DON'T:** Upload APNs tokens only when they "change" or assume a fixed token length. **DO:** Upload on every `didRegister` callback and treat the token as opaque data converted to hex.
-**DON'T:** Put Live Activity, VoIP, or App Clip-specific notification rules here. **DO:** Route those to `activitykit`, `callkit`, and `app-clips`.
+| Mistake | Instead |
+|---------|---------|
+| Calling `registerForRemoteNotifications()` only after `.authorized` | Register anyway; silent pushes and server token binding need it |
+| `String(data: token, encoding: .utf8)` | Hex-encode each byte |
+| Promising frequent silent refreshes | Expect a few per hour at most |
+| Expecting a silent push to run the service extension | Only `mutable-content: 1` alert pushes do |
+| A service-extension path that never calls the handler | Call it once on every path, timeout included |
+| No `willPresent` | Implement it or foreground notifications vanish |
+| Setting the delegate late, or registering from a view without the adaptor | Set it in `App.init`, use `@UIApplicationDelegateAdaptor` |
+| Uploading the token only when it "changes" | Treat it as opaque hex and upload on every callback |
+| Mixing in rules for Live Activities, VoIP calls or App Clips | Hand those to `live-activities`, `callkit-voip`, `app-clips` |
 
 ## Review Checklist
 
-- [ ] Authorization requested before visible alerts/sounds/badges; denied case handled (Settings link)
-- [ ] APNs registration not incorrectly blocked by alert authorization status
-- [ ] Device token converted to hex, uploaded on every callback, and not treated as a locally cached or fixed-length constant
-- [ ] `UNUserNotificationCenterDelegate` set in `App.init` or `application(_:didFinishLaunching:)`
-- [ ] Foreground (`willPresent`) and tap (`didReceive`) handling implemented
-- [ ] Categories/actions registered at launch if interactive notifications needed
-- [ ] Silent push uses `content-available: 1`, no alert/sound/badge, `apns-push-type: background`, `apns-priority: 5`, Background Modes > Remote notifications, throttling caveats, and correct `UIBackgroundFetchResult`
-
-## References
-- [references/notification-patterns.md](references/notification-patterns.md)  -  AppDelegate setup, APNs callbacks, deep-link router, silent push, debugging
-- [references/rich-notifications.md](references/rich-notifications.md)  -  Service Extension, Content Extension, attachments, communication notifications
-- Apple docs: [APNs registration](https://sosumi.ai/documentation/usernotifications/registering-your-app-with-apns), [permission](https://sosumi.ai/documentation/usernotifications/asking-permission-to-use-notifications), [payloads](https://sosumi.ai/documentation/usernotifications/generating-a-remote-notification), [background pushes](https://sosumi.ai/documentation/usernotifications/pushing-background-updates-to-your-app)
+- [ ] Permission is requested before any alert, sound or badge, and a denied user gets a link to Settings
+- [ ] APNs registration does not depend on alert authorization
+- [ ] Token is hex-encoded, uploaded on every callback, not cached as truth, no fixed length
+- [ ] The center delegate is installed from `App.init` or `application(_:didFinishLaunchingWithOptions:)`
+- [ ] Both `willPresent` and `didReceive` are implemented
+- [ ] Categories and actions are registered at launch when notifications are interactive
+- [ ] Silent pushes carry only `content-available: 1` (nothing that alerts), use the `background` push type at priority 5, rely on the Remote notifications mode, accept throttling, and report an honest `UIBackgroundFetchResult`
+
+## Apple Documentation
+
+- [APNs registration](https://developer.apple.com/documentation/usernotifications/registering-your-app-with-apns)
+- [Requesting permission](https://developer.apple.com/documentation/usernotifications/asking-permission-to-use-notifications)
+- [Building a remote payload](https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification)
+- [Background updates by push](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app)