@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/alarmkit/SKILL.md

@@ -1,500 +1,492 @@
 ---
 name: alarmkit
-description: "Implement AlarmKit alarms and countdown timers for iOS and iPadOS with Lock Screen, Dynamic Island, StandBy, and paired Apple Watch system UI. Covers AlarmManager scheduling, AlarmAttributes and AlarmPresentation, AlarmButton stop and snooze actions, authorization, state observation, countdown widget-extension handoff, and Live Activity integration. Use when building wake-up alarms, countdown timers, or alarm-style alerts that need Apple's system alarm experience."
+description: "AlarmKit alarms and countdown timers on iOS and iPadOS 26: AlarmManager scheduling and authorization, AlarmAttributes, AlarmPresentation, AlarmButton stop and snooze, state observation, and the widget extension for countdown Live Activity UI on the Lock Screen, Dynamic Island, StandBy and paired Apple Watch. Use when an app needs wake-up alarms, countdown timers or any alert that needs the system alarm experience. Not for plain widgets or non-alarm Live Activities."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
-# AlarmKit
 
-Schedule prominent alarms and countdown timers that surface on the Lock Screen,
-Dynamic Island, StandBy, and a paired Apple Watch when the alarm fires. AlarmKit
-requires iOS 26+ / iPadOS 26+. Alarms can break through Focus and Silent mode.
+# AlarmKit
 
-AlarmKit uses ActivityKit data models for its Live Activity, but the firing alert
-is system-managed alarm UI, not a general custom notification UI surface. Custom
-UI belongs only to countdown and paused Live Activity states rendered by a Widget
-Extension with the same `AlarmAttributes<Metadata>` and
-`AlarmPresentationState` used when scheduling.
+AlarmKit lets an app hand an alarm or a countdown timer to the system. When it
+fires, the alert shows up on the Lock Screen, in the Dynamic Island, in StandBy
+and on the Apple Watch paired with the phone, and it can sound through Focus
+and the Silent switch. The framework is available on iOS 26 and iPadOS 26 and later.
 
-See [references/alarmkit-patterns.md](references/alarmkit-patterns.md) for complete code patterns including
-authorization, scheduling, countdown timers, snooze handling, and widget setup.
+Under the hood an alarm is a Live Activity built on ActivityKit types, but the
+firing alert itself is drawn by the system and cannot be restyled. The only
+custom UI an app provides is for the countdown and paused states, and that UI
+lives in a widget extension that uses the same `AlarmAttributes<Metadata>` and
+`AlarmPresentationState` the app used when scheduling.
 
 ```swift
 import AlarmKit
 ```
 
-## Contents
-
-- [Workflow](#workflow)
-- [Authorization](#authorization)
-- [Alarm vs Timer Decision](#alarm-vs-timer-decision)
-- [Scheduling Alarms](#scheduling-alarms)
-- [Countdown Timers](#countdown-timers)
-- [Alarm States](#alarm-states)
-- [AlarmAttributes and AlarmPresentation](#alarmattributes-and-alarmpresentation)
-- [AlarmButton](#alarmbutton)
-- [Live Activity Integration](#live-activity-integration)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+Availability note: the `AlarmPresentation.Alert(title:secondaryButton:secondaryButtonBehavior:)`
+initializer used throughout this skill is iOS 26.1+. On a 26.0 deployment target,
+gate it with `if #available(iOS 26.1, *)`; the older initializer with a
+`stopButton:` argument is deprecated from 26.1 and should only appear in that
+fallback branch.
 
-## Workflow
+## Workflows
 
-### 1. Create a new alarm or timer
+### Adding an alarm or timer
 
-1. Add `NSAlarmKitUsageDescription` to Info.plist with a user-facing string.
-2. Request authorization with `AlarmManager.shared.requestAuthorization()` when the app can explain the value, or handle the first-schedule system prompt.
-3. If authorization is `.denied` or not `.authorized`, show recovery UI instead of scheduling.
-4. Configure `AlarmPresentation` (alert, countdown, paused states).
-5. Create `AlarmAttributes` with the presentation, optional metadata, and tint color.
-6. Build an `AlarmManager.AlarmConfiguration` (.alarm or .timer).
-7. Schedule with `AlarmManager.shared.schedule(id:configuration:)`.
-8. Observe state changes via `alarmManager.alarmUpdates`.
-9. If using countdown, add a Widget Extension target with an `ActivityConfiguration` for the same `AlarmAttributes<Metadata>` type.
+1. Put `NSAlarmKitUsageDescription` in the app's Info.plist with a sentence the
+   user will understand.
+2. Ask for permission with `AlarmManager.shared.requestAuthorization()` at a
+   moment where the value is obvious, or let the system ask on the first
+   `schedule` call.
+3. If the state comes back `.denied` (or anything other than `.authorized`),
+   show a recovery screen instead of scheduling.
+4. Describe each state's text and buttons with `AlarmPresentation` (alert, plus
+   countdown and paused if used).
+5. Wrap that in `AlarmAttributes` with optional metadata and a tint color.
+6. Build an `AlarmManager.AlarmConfiguration`, either an alarm or a timer.
+7. Call `AlarmManager.shared.schedule(id:configuration:)`.
+8. Watch `alarmUpdates` to keep the UI in sync.
+9. If a countdown is shown, create a widget extension; its
+   `ActivityConfiguration` must name the identical `AlarmAttributes<Metadata>` type.
 
-### 2. Review existing alarm code
+### Reviewing existing alarm code
 
-Run through the Review Checklist at the end of this document.
+Go through the [Review checklist](#review-checklist) item by item.
 
 ## Authorization
 
-AlarmKit requires user authorization. Request early when the app can explain the
-value, or let AlarmKit prompt automatically on first schedule. If authorization
-is not granted after the explicit or automatic prompt, alarms are not scheduled
-and will not alert.
+The user must grant access. The app may ask up front, or AlarmKit will prompt
+the first time something is scheduled. If neither prompt ends in approval, no
+alarm is scheduled and nothing will ring.
 
 ```swift
-let manager = AlarmManager.shared
-
-// Request authorization explicitly
-let state = try await manager.requestAuthorization()
-guard state == .authorized else { return }
-
-// Check current state synchronously
-let current = manager.authorizationState // .authorized, .denied, .notDetermined
-
-// Observe authorization changes
-for await state in manager.authorizationUpdates {
-    switch state {
-    case .authorized: print("Alarms enabled")
-    case .denied:     print("Alarms disabled")
-    case .notDetermined: break
-    @unknown default: break
+import AlarmKit
+
+func ensureAlarmAccess() async -> Bool {
+    let center = AlarmManager.shared
+    switch center.authorizationState {
+    case .authorized:
+        return true
+    case .denied:
+        return false
+    case .notDetermined:
+        let answer = try? await center.requestAuthorization()
+        return answer == .authorized
+    @unknown default:
+        return false
+    }
+}
+
+func watchAlarmAccess(onChange: @escaping (Bool) -> Void) async {
+    for await state in AlarmManager.shared.authorizationUpdates {
+        switch state {
+        case .authorized: onChange(true)
+        case .denied, .notDetermined: onChange(false)
+        @unknown default: onChange(false)
+        }
     }
 }
 ```
 
-## Alarm vs Timer Decision
+`AlarmManager.AuthorizationState` has three cases: `.notDetermined`,
+`.denied` and `.authorized`. `authorizationState` is a synchronous read;
+`authorizationUpdates` is an async sequence of changes.
+
+## Alarm or timer?
 
-| Feature | Alarm (`.alarm`) | Timer (`.timer`) |
+| | `.alarm` | `.timer` |
 |---|---|---|
-| Fires at | Specific time (schedule) | After duration elapses |
-| Countdown UI | Optional | Always shown |
-| Recurring | Yes (weekly days) | No |
-| Use case | Wake-up, scheduled reminders | Cooking, workout intervals |
+| Fires | at a clock time | when a duration has elapsed |
+| Countdown UI | optional | always shown |
+| Repeats | yes, on chosen weekdays | no, one-shot |
+| Typical use | wake-up, daily reminder | steeping tea, rest between sets |
 
-Use `.alarm(schedule:...)` when firing at a clock time. Use `.timer(duration:...)`
-when firing after a duration from now.
+Rule of thumb: the user picked a time of day, use `.alarm(schedule:...)`; the
+user picked "in N minutes", use `.timer(duration:...)`.
 
-## Scheduling Alarms
+## Scheduling
 
 ### Alarm.Schedule
 
-Alarms use `Alarm.Schedule` to define when they fire.
-
 ```swift
-// Fixed: fire at an exact Date (one-time only)
-let fixed: Alarm.Schedule = .fixed(myDate)
-
-// Relative one-time: fire at 7:30 AM in device time zone, no repeat
-let oneTime: Alarm.Schedule = .relative(.init(
-    time: .init(hour: 7, minute: 30),
-    repeats: .never
-))
-
-// Recurring: fire at 6:00 AM on weekdays
-let weekday: Alarm.Schedule = .relative(.init(
-    time: .init(hour: 6, minute: 0),
-    repeats: .weekly([.monday, .tuesday, .wednesday, .thursday, .friday])
-))
+import AlarmKit
+
+let oneOff = Alarm.Schedule.fixed(Date(timeIntervalSinceNow: 3_600))
+
+let sixAM = Alarm.Schedule.Relative.Time(hour: 6, minute: 0)
+let tomorrowAtSix = Alarm.Schedule.relative(.init(time: sixAM, repeats: .never))
+
+let classDays: [Locale.Weekday] = [.monday, .tuesday, .wednesday, .thursday, .friday]
+let schoolRun = Alarm.Schedule.relative(.init(time: sixAM, repeats: .weekly(classDays)))
 ```
 
-### Schedule and Configure
+- `.fixed(Date)` rings once at that exact instant.
+- `.relative` with `repeats: .never` rings once at a wall-clock time in the
+  device's current time zone.
+- `.relative` with `repeats: .weekly([Locale.Weekday])` repeats on those days.
+
+### Configuring and scheduling
 
 ```swift
-let id = UUID()
-
-let snooze = Alarm.CountdownDuration(preAlert: nil, postAlert: 300)
-let configuration = AlarmManager.AlarmConfiguration(
-    countdownDuration: snooze,
-    schedule: .relative(.init(
-        time: .init(hour: 7, minute: 0),
-        repeats: .never
-    )),
-    attributes: attributes,
-    sound: .default
-)
-
-let alarm = try await AlarmManager.shared.schedule(
-    id: id,
-    configuration: configuration
-)
-```
+import AlarmKit
+import SwiftUI
+
+struct ShiftInfo: AlarmMetadata {
+    var shiftName: String
+}
 
-`stopIntent` and `secondaryIntent` default to `nil`. Omit `stopIntent` for
-AlarmKit's standard system Stop behavior; provide it only when Stop must run app
-cleanup, custom stop behavior, or other side effects. Omit `secondaryIntent` for
-ordinary Snooze/Repeat with `secondaryButtonBehavior: .countdown` and
-`Alarm.CountdownDuration.postAlert`; provide it only for `.custom` secondary
-behavior or app cleanup/custom behavior.
-
-### Alarm State Transitions
-
-```text
-cancel(id:)
-    |
-scheduled --> countdown --> alerting
-    |             |             |
-    |         pause(id:)    stop(id:) / countdown(id:)
-    |             |
-    |         paused ----> countdown (via resume(id:))
-    |
-cancel(id:) removes from system entirely
+@available(iOS 26.1, *)
+func scheduleShiftAlarm() async throws -> Alarm {
+    let dawn = Alarm.Schedule.Relative.Time(hour: 5, minute: 30)
+    let alert = AlarmPresentation.Alert(
+        title: "Early shift",
+        secondaryButton: AlarmButton(text: "Later", textColor: .white, systemImageName: "zzz"),
+        secondaryButtonBehavior: .countdown
+    )
+    let attributes = AlarmAttributes(
+        presentation: AlarmPresentation(alert: alert),
+        metadata: ShiftInfo(shiftName: "Warehouse A"),
+        tintColor: .teal
+    )
+    let config = AlarmManager.AlarmConfiguration(
+        countdownDuration: Alarm.CountdownDuration(preAlert: nil, postAlert: 9 * 60),
+        schedule: .relative(.init(time: dawn, repeats: .never)),
+        attributes: attributes,
+        sound: .default
+    )
+    let center = AlarmManager.shared
+    return try await center.schedule(id: UUID(), configuration: config)
+}
 ```
 
-- `cancel(id:)` -- remove the alarm completely, including repeating alarms
-- `pause(id:)` -- pause a counting-down alarm; throws from other states
-- `resume(id:)` -- resume a paused alarm; throws from other states
-- `stop(id:)` -- stop the alarm; one-shot alarms are removed, repeating alarms reschedule
-- `countdown(id:)` -- restart countdown from alerting state (snooze); throws from other states
+Here `postAlert` is what makes the secondary button a snooze: pressing it
+starts a nine-minute countdown and then rings again.
+
+`stopIntent` and `secondaryIntent` both default to `nil`, and that is usually
+right:
+
+- Leave `stopIntent` out when the system Stop is all you need. Pass one only
+  when stopping must also clean up app state or trigger some side effect.
+- Leave `secondaryIntent` out for a plain snooze or repeat, which is
+  `secondaryButtonBehavior: .countdown` plus `CountdownDuration.postAlert`.
+  Pass one only with `.custom` behavior or when the app must do its own work.
+
+### Lifecycle and transitions
+
+The normal path is scheduled, then countdown, then alerting. From countdown
+`pause(id:)` leads to paused and `resume(id:)` leads back. From alerting,
+`stop(id:)` ends it and `countdown(id:)` snoozes it. `cancel(id:)` works from
+anywhere.
+
+| Call | Valid in | Effect |
+|---|---|---|
+| `cancel(id:)` | any state | deletes the alarm entirely, repeating ones included |
+| `pause(id:)` | `.countdown` | freezes the countdown; throws elsewhere |
+| `resume(id:)` | `.paused` | continues the countdown; throws elsewhere |
+| `stop(id:)` | alerting | a one-shot alarm is deleted; a repeating one moves on to its next occurrence |
+| `countdown(id:)` | `.alerting` | restarts the post-alert countdown (snooze); throws elsewhere |
 
-## Countdown Timers
+## Countdown timers
 
-Timers fire after a duration and always show a countdown UI. Use
-`Alarm.CountdownDuration` to control pre-alert and post-alert durations.
+A timer rings once a duration has passed and always shows its countdown.
 
 ```swift
-// Simple timer: 5-minute countdown, no snooze
-let timerConfig = AlarmManager.AlarmConfiguration.timer(
-    duration: 300,
-    attributes: attributes,
-    stopIntent: StopTimerIntent(timerID: id.uuidString),
-    sound: .default
-)
-
-let alarm = try await AlarmManager.shared.schedule(
-    id: UUID(),
-    configuration: timerConfig
-)
+import AlarmKit
+import SwiftUI
+
+struct BrewInfo: AlarmMetadata {
+    var blend: String
+}
+
+@available(iOS 26.1, *)
+func startSteepTimer() async throws {
+    let presentation = AlarmPresentation(
+        alert: .init(title: "Tea is ready"),
+        countdown: .init(title: "Steeping"),
+        paused: .init(title: "Steeping paused",
+                      resumeButton: AlarmButton(text: "Resume", textColor: .white, systemImageName: "play.fill"))
+    )
+    let attributes = AlarmAttributes(presentation: presentation,
+                                     metadata: BrewInfo(blend: "Sencha"),
+                                     tintColor: .green)
+    let threeMinutes = AlarmManager.AlarmConfiguration.timer(duration: 180, attributes: attributes, sound: .default)
+    let center = AlarmManager.shared
+    _ = try await center.schedule(id: UUID(), configuration: threeMinutes)
+}
 ```
 
 ### CountdownDuration
 
-`Alarm.CountdownDuration` controls the visible countdown phases:
+| Property | Meaning |
+|---|---|
+| `preAlert` | seconds counted down before the alert fires (the main countdown) |
+| `postAlert` | seconds counted down after the alert when the user snoozes or repeats |
 
-- `preAlert` -- seconds to count down before the alarm fires (the main countdown)
-- `postAlert` -- seconds for a repeat/snooze countdown after the alarm fires
+Both can be combined with a schedule. A 7:00 alarm with `preAlert: 900` shows a
+fifteen-minute countdown starting at 6:45; `postAlert: 600` gives a ten-minute
+snooze:
 
 ```swift
-let countdown = Alarm.CountdownDuration(
-    preAlert: 600,   // 10-minute countdown before alert
-    postAlert: 300   // 5-minute snooze countdown if user taps Repeat
-)
-
-let config = AlarmManager.AlarmConfiguration(
-    countdownDuration: countdown,
-    schedule: .relative(.init(
-        time: .init(hour: 8, minute: 0),
-        repeats: .never
-    )),
-    attributes: attributes,
-    sound: .default
-)
+import AlarmKit
+
+func napDurations<M: AlarmMetadata>(_ attrs: AlarmAttributes<M>) -> AlarmManager.AlarmConfiguration<M> {
+    let seven = Alarm.Schedule.Relative.Time(hour: 7, minute: 0)
+    return .init(countdownDuration: .init(preAlert: 900, postAlert: 600),
+                 schedule: .relative(.init(time: seven)), attributes: attrs, sound: .default)
+}
 ```
 
-## Alarm States
+## Alarm states
 
-Each `Alarm` has a `state` property reflecting its current lifecycle position.
+`Alarm.state` says where an alarm is in its lifecycle:
 
 | State | Meaning |
 |---|---|
-| `.scheduled` | Scheduled and ready to alert at the appropriate time |
-| `.countdown` | Actively counting down (timer or pre-alert phase) |
-| `.paused` | Countdown paused by user or app |
-| `.alerting` | Alarm is firing -- sound playing, UI prominent |
+| `.scheduled` | waiting for its time |
+| `.countdown` | counting down (a timer, or an alarm's pre-alert) |
+| `.paused` | countdown frozen by the user or the app |
+| `.alerting` | ringing, with the prominent system UI |
 
-### Observing State Changes
+### Observing changes
 
-`AlarmManager.shared.alarms` is a throwing getter for the current daemon
-snapshot. Use `try`, and either propagate the error or wrap launch refresh in
-`do/catch` before relying on the snapshot.
+Reading `AlarmManager.shared.alarms` can throw; it hands back whatever the
+alarm daemon currently holds, so it needs `try` inside a throwing context or a `do/catch`.
+Changes arrive through `alarmUpdates`:
 
 ```swift
-let manager = AlarmManager.shared
-
-// Get all current alarms
-let alarms = try manager.alarms
-
-// Observe changes as an async sequence
-for await updatedAlarms in manager.alarmUpdates {
-    for alarm in updatedAlarms {
-        switch alarm.state {
-        case .scheduled:  print("\(alarm.id) waiting")
-        case .countdown:  print("\(alarm.id) counting down")
-        case .paused:     print("\(alarm.id) paused")
-        case .alerting:   print("\(alarm.id) alerting!")
-        @unknown default: break
+import AlarmKit
+
+func trackAlarms(render: ([Alarm]) -> Void) async throws {
+    let center = AlarmManager.shared
+    render(try center.alarms)
+    for await batch in center.alarmUpdates {
+        for item in batch {
+            switch item.state {
+            case .scheduled, .countdown, .paused, .alerting: break
+            @unknown default: break
+            }
         }
+        render(batch)
     }
 }
 ```
 
-An alarm that disappears from `alarmUpdates` is no longer scheduled with
-AlarmKit. Compare against app-persisted IDs when you need to distinguish fired,
-cancelled, and rescheduled alarms.
+When an ID disappears from `alarmUpdates`, AlarmKit no longer has it scheduled.
+The sequence does not say why. To tell a fired one-shot from a cancelled alarm
+or a rescheduled one, compare against the IDs the app saved itself.
 
 ## AlarmAttributes and AlarmPresentation
 
-`AlarmAttributes` conforms to `ActivityAttributes` and defines the static
-data for the alarm's Live Activity. It is generic over a `Metadata` type
-conforming to `AlarmMetadata`, which inherits `Decodable`, `Encodable`,
-`Hashable`, and `Sendable`. The `metadata` value itself is optional and defaults
-to `nil`.
+`AlarmAttributes` conforms to `ActivityAttributes` and carries the static part
+of that Live Activity. Its generic parameter is `Metadata: AlarmMetadata`, a
+protocol that refines `Decodable`, `Encodable`, `Hashable` and `Sendable`.
+Passing `metadata` is optional; leave it out and it is `nil`.
 
 ### AlarmPresentation
 
-Defines the UI content for each alarm state. The system renders the alerting UI,
-while a widget extension can customize countdown and paused Live Activity views
-with the same attributes and presentation state.
+`AlarmPresentation` describes the text and buttons per state. The system draws
+the alerting UI from it; the widget extension may draw countdown and paused.
+
+| Type | State | Required |
+|---|---|---|
+| `AlarmPresentation.Alert(title:secondaryButton:secondaryButtonBehavior:)` | alerting | yes |
+| `AlarmPresentation.Countdown(title:pauseButton:)` | counting down | no |
+| `AlarmPresentation.Paused(title:resumeButton:)` | paused | no |
+
+Combine them with `AlarmPresentation(alert:countdown:paused:)`:
 
 ```swift
-// Alert state (required) -- shown when alarm is firing
-let alert = AlarmPresentation.Alert(
-    title: "Wake Up",
-    secondaryButton: AlarmButton(
-        text: "Snooze",
-        textColor: .white,
-        systemImageName: "bell.slash"
-    ),
-    secondaryButtonBehavior: .countdown  // snooze restarts countdown
-)
-
-// Countdown state (optional) -- shown during pre-alert countdown
-let countdown = AlarmPresentation.Countdown(
-    title: "Morning Alarm",
-    pauseButton: AlarmButton(
-        text: "Pause",
-        textColor: .orange,
-        systemImageName: "pause.fill"
-    )
-)
-
-// Paused state (optional) -- shown when countdown is paused
-let paused = AlarmPresentation.Paused(
-    title: "Paused",
-    resumeButton: AlarmButton(
-        text: "Resume",
-        textColor: .green,
-        systemImageName: "play.fill"
+import AlarmKit
+import SwiftUI
+
+@available(iOS 26.1, *)
+func workoutPresentation() -> AlarmPresentation {
+    let again = AlarmButton(text: "Again", textColor: .white, systemImageName: "repeat")
+    let hold = AlarmButton(text: "Hold", textColor: .orange, systemImageName: "pause.fill")
+    let go = AlarmButton(text: "Go", textColor: .orange, systemImageName: "play.fill")
+    return AlarmPresentation(
+        alert: .init(title: "Rest over", secondaryButton: again, secondaryButtonBehavior: .countdown),
+        countdown: .init(title: "Resting", pauseButton: hold),
+        paused: .init(title: "Rest on hold", resumeButton: go)
     )
-)
-
-let presentation = AlarmPresentation(
-    alert: alert,
-    countdown: countdown,
-    paused: paused
-)
+}
 ```
 
-### AlarmAttributes
+### Metadata
 
 ```swift
-struct CookingMetadata: AlarmMetadata {
-    var recipeName: String
-    var stepNumber: Int
-}
-
-let attributes = AlarmAttributes(
-    presentation: presentation,
-    metadata: CookingMetadata(recipeName: "Pasta", stepNumber: 3),
-    tintColor: .blue
-)
+import AlarmKit
+import SwiftUI
 
-let attributesWithoutMetadata = AlarmAttributes<EmptyAlarmMetadata>(
-    presentation: presentation,
-    metadata: nil,
-    tintColor: .blue
-)
+struct PlantInfo: AlarmMetadata { var plantName: String; var litres: Double }
+struct NoAlarmData: AlarmMetadata {}
 
-struct EmptyAlarmMetadata: AlarmMetadata {}
+@available(iOS 26.1, *)
+func plantAttributes() -> (AlarmAttributes<PlantInfo>, AlarmAttributes<NoAlarmData>) {
+    let look = AlarmPresentation(alert: .init(title: "Water the fern"))
+    let withData = AlarmAttributes(presentation: look, metadata: PlantInfo(plantName: "Fern", litres: 0.5), tintColor: .mint)
+    let plain = AlarmAttributes<NoAlarmData>(presentation: look, metadata: nil, tintColor: .mint)
+    return (withData, plain)
+}
 ```
 
+When there is nothing to carry, declare an empty type that conforms to
+`AlarmMetadata` and pass `metadata: nil`.
+
 ### AlarmPresentationState
 
-`AlarmPresentationState` is the system-managed `ContentState` of the alarm
-Live Activity. It contains the alarm ID and a `Mode` enum:
+`AlarmPresentationState` is the alarm Live Activity's `ContentState`, owned and
+updated by the system. It pairs an `alarmID` with a `mode` value:
 
-- `.alert(Alert)` -- alarm is firing, includes the scheduled time
-- `.countdown(Countdown)` -- actively counting down, includes fire date and durations
-- `.paused(Paused)` -- countdown paused, includes elapsed and total durations
+| Mode | When | Carries |
+|---|---|---|
+| `.alert(Alert)` | ringing | the scheduled `time` |
+| `.countdown(Countdown)` | counting down | fire date and durations |
+| `.paused(Paused)` | paused | elapsed and total durations |
 
-The widget extension reads `AlarmPresentationState.mode` to decide which UI to
-render in the Dynamic Island and Lock Screen for non-alerting states.
+The widget extension switches on `context.state.mode` to choose Lock Screen and
+Dynamic Island content for the non-alerting modes.
 
 ## AlarmButton
 
-`AlarmButton` defines the appearance of action buttons in the alarm UI.
-
-```swift
-let stopButton = AlarmButton(
-    text: "Stop",
-    textColor: .red,
-    systemImageName: "stop.fill"
-)
-
-let snoozeButton = AlarmButton(
-    text: "Snooze",
-    textColor: .white,
-    systemImageName: "bell.slash"
-)
-```
-
-### Secondary Button Behavior
+`AlarmButton(text:textColor:systemImageName:)` sets a button's label, color and
+SF Symbol, for example a red `"stop.fill"` look for dismissing and a
+`"bell.slash"` look for snoozing:
+`AlarmButton(text: "Snooze", textColor: .yellow, systemImageName: "bell.slash")`.
 
-The secondary button on the alert UI has two behaviors:
+### Secondary button behavior
 
-| Behavior | Effect |
+| Behavior | What happens |
 |---|---|
-| `.countdown` | Restarts a countdown using `postAlert` duration (snooze) |
-| `.custom` | Triggers the `secondaryIntent` (e.g., open app) |
-
-## Live Activity Integration
-
-AlarmKit alarms appear as Live Activities on the Lock Screen, Dynamic Island,
-StandBy, and on a paired Apple Watch when the alarm fires. The system manages
-the alerting UI. For countdown and paused states, add a Widget Extension target
-whose `ActivityConfiguration` uses the same `AlarmAttributes<Metadata>` type
-used when scheduling the alarm.
-
-A widget extension is expected if your alarm uses countdown presentation. Keep
-that lightweight metadata type available to both the app and widget extension.
-Without the extension, alarms may be dismissed unexpectedly or fail to alert,
-though the system can still show a fallback countdown UI in limited cases such
-as after a device restart before first unlock.
-
-When explaining AlarmKit boundaries, say the ownership line explicitly. AlarmKit
-owns alarm authorization, `AlarmManager` scheduling and state, `AlarmAttributes`,
-`AlarmPresentation`, `AlarmPresentationState`, sound, and system Stop/Repeat/Open
-App alarm actions for alarm and timer experiences. The firing alert remains
-system-rendered alarm UI; do not describe AlarmKit as a general custom
-notification UI surface.
-
-Custom countdown or paused alarm UI belongs in a Widget Extension
-`ActivityConfiguration` for the same `AlarmAttributes<Metadata>` type and
-`AlarmPresentationState`. Name the Apple-sourced alarm surfaces together: Lock
-Screen, Dynamic Island, StandBy, and paired Apple Watch. Do not claim Smart Stack
-as an AlarmKit surface.
-
-Route ordinary Home Screen or Smart Stack widgets, `WidgetFamily` layout choices,
-widget timelines, and `WidgetCenter` reload policy to `widgetkit`. Route non-alarm
-Live Activity lifecycle (`Activity.request`, `update`, `end`), push-to-start
-tokens, per-activity update tokens, and remote Live Activity `content-state`
-payload contracts to `activitykit`. Route generic APNs, `UNUserNotificationCenter`,
-notification categories/actions, and custom notification UI to `push-notifications`
-unless app code ultimately calls `AlarmManager`.
-
-For setup, name Apple-documented `NSAlarmKitUsageDescription` and `AlarmManager`
-authorization. Do not require unsupported AlarmKit setup keys or
-`com.apple.developer.alarmkit` unless a current Apple source documents them.
+| `.countdown` | starts a new countdown of `postAlert` seconds (snooze) |
+| `.custom` | runs `secondaryIntent`, for example to open the app |
+
+## Live Activity integration
+
+A ringing alarm is a Live Activity that the system renders on the Lock Screen,
+in the Dynamic Island, in StandBy and on a paired Apple Watch; the app has no
+say over that screen. Countdown and paused are different: the app supplies a widget
+extension whose `ActivityConfiguration` names the same
+`AlarmAttributes<Metadata>` type used at scheduling.
+
+- Plan on the extension whenever countdown presentation is used. The metadata
+  type must be compiled into both the app and the extension, and it should stay
+  small.
+- Leave the extension out and an alarm can vanish early or never ring. The
+  system only draws a fallback countdown in narrow cases, such as after a
+  restart before the first unlock.
+
+AlarmKit is responsible for: permission to schedule alarms, `AlarmManager` scheduling and state,
+`AlarmAttributes`, `AlarmPresentation`, `AlarmPresentationState`, the sound,
+and the system Stop, Repeat and Open App actions. It is not a general surface
+for custom notification UI.
+
+When describing where alarms appear, name Lock Screen, Dynamic Island, StandBy
+and paired Apple Watch together. Smart Stack is not an AlarmKit surface.
+
+Hand-offs:
+
+- Widgets on the Home Screen or in Smart Stack, `WidgetFamily`, timelines,
+  `WidgetCenter` reloads: `widgetkit`.
+- Non-alarm Live Activities (`Activity.request`, `update`, `end`),
+  push-to-start and per-activity update tokens, and remote `content-state`
+  payloads: `activitykit`.
+- APNs, `UNUserNotificationCenter`, notification categories and actions,
+  custom notification UI: `push-notifications`, unless the code ends up
+  calling `AlarmManager`.
+
+Setup stays with what Apple documents: `NSAlarmKitUsageDescription` and
+`AlarmManager` authorization. Do not require extra keys or a
+`com.apple.developer.alarmkit` entitlement unless a current Apple source says so.
 
 ```swift
-struct AlarmWidgetBundle: WidgetBundle {
-    var body: some Widget {
-        AlarmActivityWidget()
-    }
+import ActivityKit
+import AlarmKit
+import SwiftUI
+import WidgetKit
+
+struct CoachInfo: AlarmMetadata {
+    var drill: String
 }
 
-struct AlarmActivityWidget: Widget {
+struct CoachAlarmWidget: Widget {
     var body: some WidgetConfiguration {
-        ActivityConfiguration(for: AlarmAttributes<CookingMetadata>.self) { context in
-            // Lock Screen presentation for countdown/paused states
-            AlarmLockScreenView(context: context)
+        ActivityConfiguration(for: AlarmAttributes<CoachInfo>.self) { context in
+            Text(context.attributes.metadata?.drill ?? "Timer")
+                .padding()
         } dynamicIsland: { context in
             DynamicIsland {
                 DynamicIslandExpandedRegion(.center) {
-                    Text(context.attributes.presentation.alert.title)
+                    let heading = context.attributes.presentation.alert.title
+                    Text(heading)
                 }
                 DynamicIslandExpandedRegion(.bottom) {
-                    // Show countdown or paused info based on mode
-                    AlarmExpandedView(state: context.state)
+                    if case .countdown(let run) = context.state.mode {
+                        Text(timerInterval: Date.now...run.fireDate, countsDown: true)
+                    }
                 }
             } compactLeading: {
                 Image(systemName: "alarm.fill")
             } compactTrailing: {
-                AlarmCompactTrailing(state: context.state)
+                Image(systemName: "alarm.fill")
             } minimal: {
                 Image(systemName: "alarm.fill")
             }
         }
     }
 }
-```
-
-## Common Mistakes
-
-**DON'T:** Forget `NSAlarmKitUsageDescription` in Info.plist.
-**DO:** Add a descriptive usage string. Without it, AlarmKit cannot schedule alarms at all.
-
-**DON'T:** Skip authorization and assume alarms will schedule.
-**DO:** Call `requestAuthorization()` early and handle `.denied` gracefully.
-
-**DON'T:** Use `.timer` when you need a recurring schedule.
-**DO:** Use `.alarm` with `.weekly([...])` for recurring alarms. Timers are one-shot.
 
-**DON'T:** Omit the widget extension when using countdown presentation.
-**DO:** Add a widget extension target for countdown/paused Live Activity UI.
-**Why:** Without a widget extension, alarms may be dismissed before they alert; the system fallback is limited.
-
-**DON'T:** Ignore `alarmUpdates` and track alarm state manually.
-**DO:** Observe `alarmManager.alarmUpdates` to stay synchronized with the system.
-**Why:** Alarm state can change while your app is backgrounded.
-
-**DON'T:** Treat `stopIntent` and `secondaryIntent` as mandatory for every alarm.
-**DO:** Omit them for standard system Stop/Snooze; provide intents only for app cleanup or custom behavior.
-
-**DON'T:** Fold ordinary widgets, generic Live Activities, or push/local notification behavior into AlarmKit.
-**DO:** Route Home Screen/Smart Stack widgets, `WidgetFamily`, timelines, and `WidgetCenter` reloads to `widgetkit`; route non-alarm `Activity.request`/`update`/`end`, push-to-start, update tokens, and remote `content-state` payloads to `activitykit`; route generic APNs, `UNUserNotificationCenter`, and notification categories/actions to `push-notifications` unless app code ultimately calls `AlarmManager`.
-
-**DON'T:** Store large data in `AlarmMetadata`.
-**DO:** Keep metadata lightweight or pass `nil`. Store large data in your app and reference by ID.
-
-**DON'T:** Use deprecated `stopButton` parameter on `AlarmPresentation.Alert`.
-**DO:** Use the current `init(title:secondaryButton:secondaryButtonBehavior:)` initializer.
-
-## Review Checklist
+@main
+struct CoachWidgets: WidgetBundle {
+    var body: some Widget {
+        CoachAlarmWidget()
+    }
+}
+```
 
-- [ ] `NSAlarmKitUsageDescription` present in Info.plist with non-empty string
-- [ ] Authorization requested and `.denied` state handled in UI
-- [ ] `AlarmPresentation` covers all relevant states (alert, countdown, paused)
-- [ ] Widget Extension target uses `ActivityConfiguration` for the same `AlarmAttributes<Metadata>` type if countdown presentation is used
-- [ ] `AlarmAttributes` metadata is lightweight, optional when unused, and conforms to `AlarmMetadata`
-- [ ] Alarm ID stored for later cancel/pause/resume/stop operations
-- [ ] `alarmUpdates` async sequence observed to track state changes
-- [ ] `stopIntent` and `secondaryIntent` omitted for standard system Stop/Snooze and provided only for cleanup/custom behavior
-- [ ] `postAlert` duration set on `CountdownDuration` if snooze (`.countdown` behavior) is used
-- [ ] AlarmKit ownership is limited to authorization, `AlarmManager` scheduling/state, `AlarmAttributes`, `AlarmPresentation`, `AlarmPresentationState`, sound, and alarm actions
-- [ ] Alerting UI is described as system-managed alarm UI, not a general custom notification UI surface
-- [ ] Custom countdown/paused UI is routed to a Widget Extension `ActivityConfiguration` using the same `AlarmAttributes<Metadata>` and `AlarmPresentationState`
-- [ ] Boundary routing is explicit: Home Screen/Smart Stack widgets, `WidgetFamily`, timelines, and `WidgetCenter` reloads go to `widgetkit`; non-alarm `Activity.request`/`update`/`end`, push-to-start/update tokens, and remote `content-state` payloads go to `activitykit`; generic APNs/`UNUserNotificationCenter` goes to `push-notifications`
-- [ ] Setup is source-grounded: `NSAlarmKitUsageDescription` and authorization are named; unsupported keys such as `com.apple.developer.alarmkit` are not required unless Apple documents them
-- [ ] Tint color set on `AlarmAttributes` to differentiate from other apps
-- [ ] Error handling for `AlarmManager.AlarmError.maximumLimitReached`
-- [ ] Tested on device (alarm sound/vibration differs from Simulator)
+## Common mistakes
+
+- **No `NSAlarmKitUsageDescription`.** Nothing can be scheduled.
+- **Skipping authorization.** Ask early with `requestAuthorization()` and give
+  `.denied` a real screen.
+- **Recurring timers.** Timers are one-shot. Use `.alarm` with
+  `.weekly([...])` for repetition.
+- **Countdown without the widget extension.** Alarms can be dismissed before
+  they ring; the fallback UI covers very little.
+- **Hand-tracking state.** Alarms change state while the app is suspended.
+  Read it from `alarmUpdates`.
+- **Treating `stopIntent` or `secondaryIntent` as required.** Leave both out
+  for the standard Stop and Snooze.
+- **Pulling other features into AlarmKit.** Route them as listed under Hand-offs.
+- **Heavy metadata.** Keep `AlarmMetadata` small or `nil`; keep large data in
+  the app and refer to it by ID.
+- **The deprecated `stopButton` argument.** Use
+  `AlarmPresentation.Alert(title:secondaryButton:secondaryButtonBehavior:)`
+  (iOS 26.1+); keep the `stopButton:` form only in a 26.0 fallback branch.
+
+## Review checklist
+
+- [ ] `NSAlarmKitUsageDescription` is present and not empty
+- [ ] Authorization is requested and `.denied` has UI
+- [ ] `AlarmPresentation` covers every state the app uses (alert, countdown, paused)
+- [ ] Any countdown has a matching widget extension whose `ActivityConfiguration` names the same `AlarmAttributes<Metadata>`
+- [ ] Metadata conforms to `AlarmMetadata`, stays small, and is `nil` if there is none
+- [ ] Each alarm ID is saved for later cancel, pause, resume or stop
+- [ ] `alarmUpdates` is observed
+- [ ] `stopIntent` and `secondaryIntent` are omitted for standard behavior and only passed for cleanup or custom work
+- [ ] `postAlert` is set when `.countdown` snooze is used
+- [ ] AlarmKit is credited only with authorization, `AlarmManager` scheduling and state, attributes, presentation, presentation state, sound and system alarm actions
+- [ ] The ringing screen is described as drawn by the system
+- [ ] Custom countdown and paused UI lives in the widget extension with the same attributes and `AlarmPresentationState`
+- [ ] Hand-offs to `widgetkit`, `activitykit` and `push-notifications` are explicit
+- [ ] Setup cites only documented requirements; no `com.apple.developer.alarmkit` unless Apple documents it
+- [ ] `tintColor` is set on `AlarmAttributes` so the alarm is recognisable
+- [ ] `AlarmManager.AlarmError.maximumLimitReached` is handled
+- [ ] Sound and vibration are tested on a device, not only in Simulator
 
 ## References
 
-- Patterns and code: [references/alarmkit-patterns.md](references/alarmkit-patterns.md)
-- Apple docs: [AlarmKit](https://sosumi.ai/documentation/alarmkit) |
-  [AlarmManager](https://sosumi.ai/documentation/alarmkit/alarmmanager) |
-  [AlarmAttributes](https://sosumi.ai/documentation/alarmkit/alarmattributes) |
-  [Scheduling an alarm](https://sosumi.ai/documentation/alarmkit/scheduling-an-alarm-with-alarmkit)
+- [AlarmKit patterns](references/alarmkit-patterns.md) - complete alarm and timer flows, authorization manager, state store, widget extension, recurrence, snooze and custom actions, Info.plist, errors
+- [AlarmKit](https://developer.apple.com/documentation/alarmkit)
+- [AlarmManager](https://developer.apple.com/documentation/alarmkit/alarmmanager)
+- [AlarmAttributes](https://developer.apple.com/documentation/alarmkit/alarmattributes)
+- [Apple sample: scheduling alarms](https://developer.apple.com/documentation/alarmkit/scheduling-an-alarm-with-alarmkit)