@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/alarmkit/references/alarmkit-patterns.md

@@ -1,591 +1,541 @@
-# AlarmKit Patterns
+# AlarmKit patterns
 
-Complete implementation patterns for AlarmKit alarms, countdown timers,
-authorization, state observation, and Live Activity integration. All patterns
-target iOS 26+ / iPadOS 26+ with Swift 6.3. The alerting UI is system-managed;
-countdown and paused states use a widget extension for custom Live Activity UI.
+Longer, end-to-end examples. Everything here targets iOS 26 and iPadOS 26 with
+Swift 6.3. Code that uses the stopButton-free
+`AlarmPresentation.Alert(title:secondaryButton:secondaryButtonBehavior:)`
+initializer is marked `@available(iOS 26.1, *)`.
 
 ## Contents
-- Complete Alarm Scheduling Flow
-- Complete Countdown Timer Flow
-- Authorization Manager
-- State Observation with Async Sequences
-- Live Activity Widget Extension for Alarms
-- Recurring Alarm Patterns
-- Snooze and Dismiss Handling
-- Info.plist Configuration
-- Error Handling
-- Apple Documentation Links
 
-## Complete Alarm Scheduling Flow
+- [Full alarm flow with intents](#full-alarm-flow-with-intents)
+- [Full timer flow](#full-timer-flow)
+- [Authorization manager](#authorization-manager)
+- [State store with async sequences](#state-store-with-async-sequences)
+- [Widget extension for countdown and paused UI](#widget-extension-for-countdown-and-paused-ui)
+- [Recurrence](#recurrence)
+- [Snooze and custom secondary actions](#snooze-and-custom-secondary-actions)
+- [Info.plist](#infoplist)
+- [Error handling](#error-handling)
+- [Apple documentation](#apple-documentation)
 
-End-to-end pattern for scheduling a wake-up alarm with snooze support.
+## Full alarm flow with intents
+
+Stop and snooze intents are `LiveActivityIntent` types from AppIntents. Each one
+receives the alarm ID as a string parameter and calls back into `AlarmManager`.
 
 ```swift
 import AlarmKit
 import AppIntents
+import SwiftUI
+
+struct DismissMedicineAlarm: LiveActivityIntent {
+    static let title: LocalizedStringResource = "Dismiss medicine reminder"
+
+    @Parameter(title: "Alarm ID")
+    var alarmID: String
 
-struct StopAlarmIntent: LiveActivityIntent {
-    static var title: LocalizedStringResource = "Stop Alarm"
-    @Parameter(title: "Alarm ID") var alarmID: String
     init() {}
-    init(alarmID: String) { self.alarmID = alarmID }
+    init(alarmID: UUID) { self.alarmID = alarmID.uuidString }
+
     func perform() async throws -> some IntentResult {
-        try AlarmManager.shared.stop(id: UUID(uuidString: alarmID)!)
+        if let id = UUID(uuidString: alarmID) {
+            try AlarmManager.shared.stop(id: id)
+        }
         return .result()
     }
 }
 
-struct SnoozeAlarmIntent: LiveActivityIntent {
-    static var title: LocalizedStringResource = "Snooze Alarm"
-    @Parameter(title: "Alarm ID") var alarmID: String
+struct RemindAgainIntent: LiveActivityIntent {
+    static let title: LocalizedStringResource = "Remind again"
+
+    @Parameter(title: "Alarm ID")
+    var alarmID: String
+
     init() {}
-    init(alarmID: String) { self.alarmID = alarmID }
+    init(alarmID: UUID) { self.alarmID = alarmID.uuidString }
+
     func perform() async throws -> some IntentResult {
-        try AlarmManager.shared.countdown(id: UUID(uuidString: alarmID)!)
+        if let id = UUID(uuidString: alarmID) {
+            try AlarmManager.shared.countdown(id: id)
+        }
         return .result()
     }
 }
 
-struct WakeUpMetadata: AlarmMetadata {
-    var label: String
+struct DoseInfo: AlarmMetadata {
+    var medicine: String
+    var doseLabel: String
 }
 
+enum DoseAlarmError: Error {
+    case accessNotGranted
+}
+
+@available(iOS 26.1, *)
 @MainActor
-func scheduleWakeUpAlarm(
-    hour: Int, minute: Int, label: String
-) async throws -> Alarm {
-    let manager = AlarmManager.shared
-    let authState = try await manager.requestAuthorization()
-    guard authState == .authorized else { throw AlarmSchedulingError.notAuthorized }
+func scheduleDoseReminder(hour: Int, minute: Int, medicine: String) async throws -> Alarm {
+    let center = AlarmManager.shared
+    guard try await center.requestAuthorization() == .authorized else {
+        throw DoseAlarmError.accessNotGranted
+    }
 
     let alert = AlarmPresentation.Alert(
-        title: LocalizedStringResource(stringLiteral: label),
-        secondaryButton: AlarmButton(
-            text: "Snooze", textColor: .white, systemImageName: "bell.slash"
-        ),
+        title: LocalizedStringResource(stringLiteral: "Time for \(medicine)"),
+        secondaryButton: AlarmButton(text: "In 5 min", textColor: .white, systemImageName: "clock.arrow.circlepath"),
         secondaryButtonBehavior: .countdown
     )
-    let presentation = AlarmPresentation(alert: alert)
     let attributes = AlarmAttributes(
-        presentation: presentation,
-        metadata: WakeUpMetadata(label: label),
+        presentation: AlarmPresentation(alert: alert),
+        metadata: DoseInfo(medicine: medicine, doseLabel: "1 tablet"),
         tintColor: .indigo
     )
 
+    let doseTime = Alarm.Schedule.Relative.Time(hour: hour, minute: minute)
     let id = UUID()
-    let snooze = Alarm.CountdownDuration(preAlert: nil, postAlert: 300)
     let config = AlarmManager.AlarmConfiguration(
-        countdownDuration: snooze,
-        schedule: .relative(.init(
-            time: .init(hour: hour, minute: minute), repeats: .never
-        )),
+        countdownDuration: Alarm.CountdownDuration(preAlert: nil, postAlert: 5 * 60),
+        schedule: .relative(.init(time: doseTime)),
         attributes: attributes,
-        stopIntent: StopAlarmIntent(alarmID: id.uuidString),
-        secondaryIntent: SnoozeAlarmIntent(alarmID: id.uuidString),
+        stopIntent: DismissMedicineAlarm(alarmID: id),
+        secondaryIntent: RemindAgainIntent(alarmID: id),
         sound: .default
     )
-    return try await manager.schedule(id: id, configuration: config)
-}
-
-enum AlarmSchedulingError: Error {
-    case notAuthorized
+    return try await center.schedule(id: id, configuration: config)
 }
 ```
 
-## Complete Countdown Timer Flow
+Generate the `UUID` first. Both intents need to carry the same ID string that
+`schedule(id:configuration:)` will use, so the ID must exist before the intents
+are built. Remember the intents themselves are optional; this example passes
+them only to show the wiring. Declare the intent's `title` with `static let`:
+in the Swift 6 language mode a `static var` is rejected as unprotected global
+mutable state.
 
-End-to-end pattern for a countdown timer with pause/resume support.
+## Full timer flow
 
 ```swift
 import AlarmKit
-import AppIntents
-
-struct StopTimerIntent: LiveActivityIntent {
-    static var title: LocalizedStringResource = "Stop Timer"
-    @Parameter(title: "Timer ID") var timerID: String
-    init() {}
-    init(timerID: String) { self.timerID = timerID }
-    func perform() async throws -> some IntentResult {
-        try AlarmManager.shared.stop(id: UUID(uuidString: timerID)!)
-        return .result()
-    }
-}
+import SwiftUI
 
-struct CookingTimerMetadata: AlarmMetadata {
-    var recipeName: String
-    var stepDescription: String
+struct BakeStep: AlarmMetadata {
+    var loafName: String
+    var stage: String
 }
 
+@available(iOS 26.1, *)
 @MainActor
-func startCookingTimer(
-    durationSeconds: TimeInterval, recipeName: String, step: String
-) async throws -> Alarm {
-    let manager = AlarmManager.shared
-    let authState = try await manager.requestAuthorization()
-    guard authState == .authorized else { throw AlarmSchedulingError.notAuthorized }
-
-    let alert = AlarmPresentation.Alert(
-        title: LocalizedStringResource(stringLiteral: "\(recipeName): \(step)"),
-        secondaryButton: nil, secondaryButtonBehavior: nil
-    )
-    let countdown = AlarmPresentation.Countdown(
-        title: LocalizedStringResource(stringLiteral: recipeName),
-        pauseButton: AlarmButton(
-            text: "Pause", textColor: .orange, systemImageName: "pause.fill"
-        )
-    )
-    let paused = AlarmPresentation.Paused(
-        title: "Paused",
-        resumeButton: AlarmButton(
-            text: "Resume", textColor: .green, systemImageName: "play.fill"
-        )
-    )
+func startProofingTimer(minutes: Double) async throws -> Alarm {
     let presentation = AlarmPresentation(
-        alert: alert, countdown: countdown, paused: paused
+        alert: AlarmPresentation.Alert(title: "Dough has proofed", secondaryButton: nil, secondaryButtonBehavior: nil),
+        countdown: AlarmPresentation.Countdown(
+            title: "Proofing",
+            pauseButton: AlarmButton(text: "Pause", textColor: .brown, systemImageName: "pause.fill")
+        ),
+        paused: AlarmPresentation.Paused(
+            title: "Proofing paused",
+            resumeButton: AlarmButton(text: "Resume", textColor: .brown, systemImageName: "play.fill")
+        )
     )
     let attributes = AlarmAttributes(
         presentation: presentation,
-        metadata: CookingTimerMetadata(recipeName: recipeName, stepDescription: step),
+        metadata: BakeStep(loafName: "Rye", stage: "Second rise"),
         tintColor: .orange
     )
-
-    let id = UUID()
     let config = AlarmManager.AlarmConfiguration.timer(
-        duration: durationSeconds,
+        duration: minutes * 60,
         attributes: attributes,
-        stopIntent: StopTimerIntent(timerID: id.uuidString),
+        stopIntent: nil,
         sound: .default
     )
-    return try await manager.schedule(id: id, configuration: config)
+    let center = AlarmManager.shared
+    return try await center.schedule(id: UUID(), configuration: config)
 }
 ```
 
-## Authorization Manager
-
-Observable pattern for centralized authorization management.
+## Authorization manager
 
 ```swift
 import AlarmKit
 import Observation
+import SwiftUI
 
 @Observable
 @MainActor
-final class AlarmAuthorizationManager {
-    private let manager = AlarmManager.shared
-    private(set) var isAuthorized = false
-    private(set) var authState: AlarmManager.AuthorizationState = .notDetermined
+final class AlarmAccess {
+    private let center = AlarmManager.shared
+    private(set) var state: AlarmManager.AuthorizationState
 
     init() {
-        authState = manager.authorizationState
-        isAuthorized = authState == .authorized
+        state = AlarmManager.shared.authorizationState
     }
 
-    func requestIfNeeded() async throws -> Bool {
-        guard authState == .notDetermined else { return isAuthorized }
-        let state = try await manager.requestAuthorization()
-        authState = state
-        isAuthorized = state == .authorized
-        return isAuthorized
+    func askIfNeeded() async {
+        guard state == .notDetermined else { return }
+        if let answer = try? await AlarmManager.shared.requestAuthorization() {
+            state = answer
+        }
     }
 
-    func observeAuthorizationChanges() async {
-        for await state in manager.authorizationUpdates {
-            authState = state
-            isAuthorized = state == .authorized
+    func follow() async {
+        for await next in center.authorizationUpdates {
+            state = next
         }
     }
 }
 
-// Usage in SwiftUI
-struct AlarmSettingsView: View {
-    @State private var authManager = AlarmAuthorizationManager()
+struct AlarmAccessView: View {
+    @State private var access = AlarmAccess()
 
     var body: some View {
         Group {
-            if authManager.isAuthorized {
-                Text("Alarms are enabled")
-            } else if authManager.authState == .denied {
+            switch access.state {
+            case .authorized:
+                Text("Alarms are on")
+            case .denied:
                 ContentUnavailableView(
-                    "Alarms Disabled", systemImage: "alarm.waves.left.and.right",
-                    description: Text("Enable in Settings > Your App > Alarms & Timers.")
+                    "Alarms are off",
+                    systemImage: "alarm",
+                    description: Text("Turn them on in Settings > this app > Alarms & Timers.")
                 )
-            } else {
-                Button("Enable Alarms") {
-                    Task { try? await authManager.requestIfNeeded() }
+            default:
+                Button("Allow alarms") {
+                    Task { await access.askIfNeeded() }
                 }
             }
         }
-        .task { await authManager.observeAuthorizationChanges() }
+        .task { await access.follow() }
     }
 }
 ```
 
-## State Observation with Async Sequences
+The path users follow to recover from a denial is Settings, then the app's own
+page, then Alarms & Timers.
 
-Pattern for tracking all alarms and reacting to state changes.
+`askIfNeeded()` reads `AlarmManager.shared` at the call instead of the stored
+`center`. `AlarmManager` is a non-`Sendable` class and `requestAuthorization()`
+is a nonisolated `async` method, so calling it on a property of a main-actor
+object sends main-actor state off the actor, and Swift 6 rejects that in its
+region-isolation pass ("sending 'self.center' risks causing data races").
+
+## State store with async sequences
 
 ```swift
 import AlarmKit
 import Observation
+import SwiftUI
 
 @Observable
 @MainActor
-final class AlarmStore {
-    private let manager = AlarmManager.shared
-    private(set) var alarms: [Alarm] = []
+final class AlarmBoard {
+    private let center = AlarmManager.shared
+    private(set) var items: [Alarm] = []
 
-    func refreshAlarms() throws {
-        alarms = try manager.alarms
+    func reload() throws {
+        items = try center.alarms
     }
 
-    func startObserving() async {
-        for await updatedAlarms in manager.alarmUpdates {
-            alarms = updatedAlarms
+    func observe() async {
+        for await snapshot in center.alarmUpdates {
+            items = snapshot
         }
     }
 
-    func alarm(for id: UUID) -> Alarm? { alarms.first { $0.id == id } }
-    func alarms(in state: Alarm.State) -> [Alarm] { alarms.filter { $0.state == state } }
+    func item(for id: Alarm.ID) -> Alarm? {
+        items.first { $0.id == id }
+    }
 
-    func cancel(_ id: Alarm.ID) throws { try manager.cancel(id: id) }
-    func pause(_ id: Alarm.ID) throws { try manager.pause(id: id) }
-    func resume(_ id: Alarm.ID) throws { try manager.resume(id: id) }
-    func stop(_ id: Alarm.ID) throws { try manager.stop(id: id) }
-    func snooze(_ id: Alarm.ID) throws { try manager.countdown(id: id) }
+    func items(in state: Alarm.State) -> [Alarm] {
+        items.filter { $0.state == state }
+    }
+
+    func cancel(_ alarmID: Alarm.ID) throws { try center.cancel(id: alarmID) }
+    func pause(_ alarmID: Alarm.ID) throws { try center.pause(id: alarmID) }
+    func resume(_ alarmID: Alarm.ID) throws { try center.resume(id: alarmID) }
+    func stop(_ alarmID: Alarm.ID) throws { try center.stop(id: alarmID) }
+    func snooze(_ alarmID: Alarm.ID) throws { try center.countdown(id: alarmID) }
 }
 
-// Usage in SwiftUI
-struct AlarmListView: View {
-    @State private var store = AlarmStore()
+struct AlarmBoardView: View {
+    @State private var board = AlarmBoard()
 
     var body: some View {
-        List(store.alarms, id: \.id) { alarm in
+        List(board.items) { alarm in
             HStack {
-                Text(alarm.id.uuidString.prefix(8)).font(.headline)
+                Text(alarm.id.uuidString.prefix(6))
                 Spacer()
                 switch alarm.state {
                 case .scheduled:
-                    Button("Cancel", role: .destructive) { try? store.cancel(alarm.id) }
+                    Button("Cancel") { try? board.cancel(alarm.id) }
                 case .countdown:
-                    Button("Pause") { try? store.pause(alarm.id) }
+                    Button("Pause") { try? board.pause(alarm.id) }
                 case .paused:
-                    Button("Resume") { try? store.resume(alarm.id) }
+                    Button("Resume") { try? board.resume(alarm.id) }
                 case .alerting:
-                    Button("Stop") { try? store.stop(alarm.id) }
+                    Button("Stop") { try? board.stop(alarm.id) }
                 @unknown default:
                     EmptyView()
                 }
             }
         }
         .task {
-            try? store.refreshAlarms()
-            await store.startObserving()
+            try? board.reload()
+            await board.observe()
         }
     }
 }
 ```
 
-## Live Activity Widget Extension for Alarms
+## Widget extension for countdown and paused UI
 
-Widget extension that renders countdown and paused states. AlarmKit expects this
-when your alarm uses countdown presentation; the system fallback countdown UI is
-limited to cases such as after restart before first unlock.
+The system only falls back to its own countdown UI in narrow situations, such as
+a device that restarted and has not been unlocked yet. Anything that shows a
+countdown should ship this extension.
 
 ```swift
-import WidgetKit
-import SwiftUI
+import ActivityKit
 import AlarmKit
+import SwiftUI
+import WidgetKit
 
-// MARK: - Widget bundle
-
-struct AlarmWidgetBundle: WidgetBundle {
-    var body: some Widget {
-        AlarmLiveActivityWidget()
-    }
+struct LapInfo: AlarmMetadata {
+    var routeName: String
+    var segment: String
 }
 
-// MARK: - Live Activity configuration
-
-struct AlarmLiveActivityWidget: Widget {
+struct LapAlarmActivity: Widget {
     var body: some WidgetConfiguration {
-        ActivityConfiguration(for: AlarmAttributes<CookingTimerMetadata>.self) { context in
-            AlarmLockScreenView(context: context)
+        ActivityConfiguration(for: AlarmAttributes<LapInfo>.self) { context in
+            LapLockScreenView(context: context)
         } dynamicIsland: { context in
             DynamicIsland {
                 DynamicIslandExpandedRegion(.leading) {
-                    Image(systemName: "alarm.fill")
-                        .font(.title2)
+                    Image(systemName: "figure.run")
                         .foregroundStyle(context.attributes.tintColor)
                 }
                 DynamicIslandExpandedRegion(.trailing) {
-                    AlarmCountdownText(state: context.state)
-                        .font(.title3.monospacedDigit())
+                    remainingLabel(for: context.state.mode)
+                        .monospacedDigit()
                 }
                 DynamicIslandExpandedRegion(.center) {
-                    Text(context.attributes.metadata?.recipeName ?? "Timer")
-                        .font(.headline)
+                    Text(context.attributes.metadata?.routeName ?? "Run")
                 }
                 DynamicIslandExpandedRegion(.bottom) {
-                    if let step = context.attributes.metadata?.stepDescription {
-                        Text(step).font(.subheadline).foregroundStyle(.secondary)
-                    }
+                    Text(context.attributes.metadata?.segment ?? "")
+                        .font(.caption)
                 }
             } compactLeading: {
-                Image(systemName: "alarm.fill").foregroundStyle(context.attributes.tintColor)
+                Image(systemName: "figure.run")
             } compactTrailing: {
-                AlarmCountdownText(state: context.state)
-                    .frame(width: 44).monospacedDigit()
+                remainingLabel(for: context.state.mode)
+                    .monospacedDigit()
+                    .frame(maxWidth: 44)
             } minimal: {
-                Image(systemName: "alarm.fill").foregroundStyle(context.attributes.tintColor)
+                Image(systemName: "figure.run")
             }
             .keylineTint(context.attributes.tintColor)
         }
     }
 }
 
-// MARK: - Lock Screen view
-
-struct AlarmLockScreenView: View {
-    let context: ActivityViewContext<AlarmAttributes<CookingTimerMetadata>>
+struct LapLockScreenView: View {
+    let context: ActivityViewContext<AlarmAttributes<LapInfo>>
 
     var body: some View {
-        VStack(alignment: .leading) {
-            HStack {
-                Image(systemName: "alarm.fill")
-                    .foregroundStyle(context.attributes.tintColor)
-                Text(context.attributes.metadata?.recipeName ?? "Timer")
-                    .font(.headline)
-                Spacer()
-                AlarmCountdownText(state: context.state)
-                    .font(.title3.monospacedDigit().bold())
-            }
-
-            switch context.state.mode {
-            case .countdown(let info):
-                ProgressView(
-                    value: info.previouslyElapsedDuration,
-                    total: info.totalCountdownDuration
-                )
-                .tint(context.attributes.tintColor)
-            case .paused:
-                Label("Paused", systemImage: "pause.fill")
-                    .font(.subheadline).foregroundStyle(.secondary)
-            case .alert:
-                EmptyView()  // System handles alerting UI
-            @unknown default:
-                EmptyView()
+        switch context.state.mode {
+        case .countdown(let run):
+            VStack(alignment: .leading) {
+                Text(context.attributes.presentation.countdown?.title ?? "Running")
+                ProgressView(value: run.previouslyElapsedDuration, total: run.totalCountdownDuration)
             }
+            .padding()
+        case .paused:
+            Label("Paused", systemImage: "pause.circle").padding()
+        case .alert:
+            EmptyView()
+        @unknown default:
+            EmptyView()
         }
-        .padding()
     }
 }
 
-// MARK: - Helper views
-
-struct AlarmCountdownText: View {
-    let state: AlarmPresentationState
-
-    var body: some View {
-        switch state.mode {
-        case .countdown(let info):
-            Text(info.fireDate, style: .timer)
-        case .paused(let info):
-            let remaining = info.totalCountdownDuration - info.previouslyElapsedDuration
-            Text(Duration.seconds(remaining), format: .time(pattern: .minuteSecond))
-        case .alert(let info):
-            Text("\(info.time.hour):\(String(format: "%02d", info.time.minute))")
-        @unknown default:
-            Text("--:--")
-        }
+@ViewBuilder
+func remainingLabel(for mode: AlarmPresentationState.Mode) -> some View {
+    switch mode {
+    case .countdown(let run):
+        Text(run.fireDate, style: .timer)
+    case .paused(let hold):
+        let left = hold.totalCountdownDuration - hold.previouslyElapsedDuration
+        Text(Duration.seconds(left).formatted(.time(pattern: .minuteSecond)))
+    case .alert(let ring):
+        Text(String(format: "%02d:%02d", ring.time.hour, ring.time.minute))
+    @unknown default:
+        EmptyView()
     }
 }
 ```
 
-## Recurring Alarm Patterns
+The alert case renders `EmptyView()` on the Lock Screen because the system draws
+the ringing UI itself.
+
+Fields by mode:
+
+| Mode | Fields |
+|---|---|
+| `.countdown` | `fireDate`, `previouslyElapsedDuration`, `totalCountdownDuration` |
+| `.paused` | `previouslyElapsedDuration`, `totalCountdownDuration` |
+| `.alert` | `time` (`hour`, `minute`) |
+
+## Recurrence
 
 ```swift
-// Daily alarm (every day)
-let dailySchedule = Alarm.Schedule.relative(.init(
-    time: .init(hour: 7, minute: 0),
-    repeats: .weekly([.sunday, .monday, .tuesday, .wednesday,
-                      .thursday, .friday, .saturday])
-))
-
-// Weekday-only alarm
-let weekdaySchedule = Alarm.Schedule.relative(.init(
-    time: .init(hour: 6, minute: 30),
-    repeats: .weekly([.monday, .tuesday, .wednesday, .thursday, .friday])
-))
-
-// Weekend alarm
-let weekendSchedule = Alarm.Schedule.relative(.init(
-    time: .init(hour: 9, minute: 0),
-    repeats: .weekly([.saturday, .sunday])
-))
-
-// One-time alarm at a specific Date
-let targetDate = Calendar.current.date(
-    from: DateComponents(year: 2026, month: 6, day: 15, hour: 14, minute: 30)
-)!
-let fixedSchedule = Alarm.Schedule.fixed(targetDate)
+import AlarmKit
+import Foundation
+
+let allWeek: [Locale.Weekday] = [.monday, .tuesday, .wednesday, .thursday, .friday, .saturday, .sunday]
+let officeDays: [Locale.Weekday] = [.monday, .tuesday, .wednesday, .thursday, .friday]
+let restDays: [Locale.Weekday] = [.saturday, .sunday]
+
+let bedtime = Alarm.Schedule.relative(.init(time: .init(hour: 21, minute: 30), repeats: .weekly(allWeek)))
+let commute = Alarm.Schedule.relative(.init(time: .init(hour: 7, minute: 15), repeats: .weekly(officeDays)))
+let lazyMorning = Alarm.Schedule.relative(.init(time: .init(hour: 9, minute: 45), repeats: .weekly(restDays)))
+
+func examMorning() -> Alarm.Schedule? {
+    let parts = DateComponents(calendar: .current, year: 2027, month: 1, day: 8, hour: 6, minute: 50)
+    guard let when = Calendar.current.date(from: parts) else { return nil }
+    return .fixed(when)
+}
 ```
 
-## Snooze and Dismiss Handling
+"Every day" is simply `.weekly` with all seven weekdays. A single calendar date
+is a `Date` built from `DateComponents` and passed to `.fixed`.
 
-Pattern for alarm with snooze (countdown behavior) and custom secondary action.
+## Snooze and custom secondary actions
 
-### Snooze with countdown restart
+For a standard snooze, give the alert a `.countdown` secondary button and set
+`postAlert`; that value is the snooze length. A `Countdown` presentation is
+what the user sees while the snooze runs. Metadata can be `nil`; give the
+compiler the type (`Optional<NapInfo>.none`, or `nil as NapInfo?`) when it
+cannot infer the generic parameter.
 
 ```swift
-func scheduleAlarmWithSnooze(
-    hour: Int, minute: Int, snoozeDurationSeconds: TimeInterval
-) async throws -> Alarm {
-    let id = UUID()
-    let alert = AlarmPresentation.Alert(
-        title: "Good Morning",
-        secondaryButton: AlarmButton(
-            text: "Snooze 5 min", textColor: .white, systemImageName: "zzz"
-        ),
-        secondaryButtonBehavior: .countdown  // tapping Snooze restarts countdown
-    )
-    // postAlert defines the snooze duration
-    let countdown = Alarm.CountdownDuration(
-        preAlert: nil, postAlert: snoozeDurationSeconds
-    )
-    let countdownPresentation = AlarmPresentation.Countdown(
-        title: "Snoozing...", pauseButton: nil
-    )
+import AlarmKit
+import AppIntents
+import SwiftUI
+
+struct NapInfo: AlarmMetadata {}
+
+@available(iOS 26.1, *)
+func napWithSnooze() -> AlarmManager.AlarmConfiguration<NapInfo> {
     let presentation = AlarmPresentation(
-        alert: alert, countdown: countdownPresentation
-    )
-    let attributes = AlarmAttributes(
-        presentation: presentation,
-        metadata: nil as WakeUpMetadata?,
-        tintColor: .purple
+        alert: .init(title: "Nap over",
+                     secondaryButton: AlarmButton(text: "5 more", textColor: .white, systemImageName: "moon.zzz"),
+                     secondaryButtonBehavior: .countdown),
+        countdown: .init(title: "Snoozing", pauseButton: nil)
     )
-    let config = AlarmManager.AlarmConfiguration(
-        countdownDuration: countdown,
-        schedule: .relative(.init(
-            time: .init(hour: hour, minute: minute), repeats: .never
-        )),
+    let attributes = AlarmAttributes(presentation: presentation, metadata: Optional<NapInfo>.none, tintColor: .purple)
+    return AlarmManager.AlarmConfiguration(
+        countdownDuration: .init(preAlert: nil, postAlert: 300),
+        schedule: .fixed(Date(timeIntervalSinceNow: 1_200)),
         attributes: attributes,
-        stopIntent: StopAlarmIntent(alarmID: id.uuidString),
-        secondaryIntent: SnoozeAlarmIntent(alarmID: id.uuidString),
         sound: .default
     )
-    return try await AlarmManager.shared.schedule(id: id, configuration: config)
 }
-```
-
-### Custom secondary action (open app)
 
-Use `.custom` behavior to trigger the `secondaryIntent` instead of restarting
-a countdown. The intent opens the app or performs custom logic.
+struct ShowPackingList: LiveActivityIntent {
+    static let title: LocalizedStringResource = "Show packing list"
+    static let openAppWhenRun = true
 
-```swift
-struct OpenAppIntent: LiveActivityIntent {
-    static var title: LocalizedStringResource = "Open App"
-    func perform() async throws -> some IntentResult { .result() }
+    func perform() async -> some IntentResult {
+        .result()
+    }
 }
 
-func scheduleAlarmWithOpenAction(hour: Int, minute: Int) async throws -> Alarm {
-    let id = UUID()
+@available(iOS 26.1, *)
+func departureAlarm() -> AlarmManager.AlarmConfiguration<NapInfo> {
     let alert = AlarmPresentation.Alert(
-        title: "Medication Reminder",
-        secondaryButton: AlarmButton(
-            text: "Open", textColor: .blue, systemImageName: "pill.fill"
-        ),
-        secondaryButtonBehavior: .custom  // triggers secondaryIntent
-    )
-    let presentation = AlarmPresentation(alert: alert)
-    let attributes = AlarmAttributes<WakeUpMetadata>(
-        presentation: presentation, metadata: nil, tintColor: .blue
+        title: "Leave for the airport",
+        secondaryButton: AlarmButton(text: "Checklist", textColor: .white, systemImageName: "list.bullet"),
+        secondaryButtonBehavior: .custom
     )
-    let config = AlarmManager.AlarmConfiguration.alarm(
-        schedule: .relative(.init(
-            time: .init(hour: hour, minute: minute), repeats: .never
-        )),
+    let attributes = AlarmAttributes<NapInfo>(presentation: .init(alert: alert), tintColor: .blue)
+    return .alarm(
+        schedule: .fixed(Date(timeIntervalSinceNow: 7_200)),
         attributes: attributes,
-        stopIntent: StopAlarmIntent(alarmID: id.uuidString),
-        secondaryIntent: OpenAppIntent(),
+        stopIntent: nil,
+        secondaryIntent: ShowPackingList(),
         sound: .default
     )
-    return try await AlarmManager.shared.schedule(id: id, configuration: config)
 }
 ```
 
-## Info.plist Configuration
+With `.custom`, pressing the secondary button runs `secondaryIntent` instead of
+starting a countdown.
 
-### Required key
-
-```xml
-<key>NSAlarmKitUsageDescription</key>
-<string>We schedule alerts for alarms and timers you create.</string>
-```
+## Info.plist
 
-This key is **mandatory**. If missing or empty, `schedule(id:configuration:)`
-will fail and no alarms can be created by the app.
+| Key | Type | Notes |
+|---|---|---|
+| `NSAlarmKitUsageDescription` | String | Required. Without a non-empty value every `schedule(id:configuration:)` call fails, so the app cannot create alarms at all. |
 
-### Countdown UI setup
+- Put it in the containing app's Info.plist, not the extension's.
+- Apple does not list `NSSupportsLiveActivities` as part of AlarmKit setup.
+- Using countdown presentation means adding a widget extension target.
 
-If you support countdown presentation, add a widget extension target for the
-custom Live Activity UI. Keep `NSAlarmKitUsageDescription` in the host app's
-Info.plist; Apple does not document `NSSupportsLiveActivities` as an AlarmKit
-setup key.
+## Error handling
 
-## Error Handling
+`AlarmManager.AlarmConfiguration` is generic over the metadata type, written in
+full as `AlarmManager.AlarmConfiguration<Metadata>`.
 
 ```swift
 import AlarmKit
 
-func scheduleAlarmSafely<Metadata: AlarmMetadata>(
-    id: UUID,
-    configuration: AlarmManager.AlarmConfiguration<Metadata>
-) async {
-    guard AlarmManager.shared.authorizationState == .authorized else {
-        print("Not authorized -- request authorization first")
-        return
-    }
+enum ScheduleOutcome {
+    case scheduled(Alarm)
+    case needsAccess
+    case tooMany
+    case failed(Error)
+}
+
+func trySchedule<M: AlarmMetadata>(_ config: AlarmManager.AlarmConfiguration<M>) async -> ScheduleOutcome {
+    let center = AlarmManager.shared
+    guard center.authorizationState == .authorized else { return .needsAccess }
     do {
-        let alarm = try await AlarmManager.shared.schedule(
-            id: id, configuration: configuration
-        )
-        print("Scheduled alarm: \(alarm.id), state: \(alarm.state)")
-    } catch let error as AlarmManager.AlarmError {
-        switch error {
+        return .scheduled(try await center.schedule(id: UUID(), configuration: config))
+    } catch let limitError as AlarmManager.AlarmError {
+        switch limitError {
         case .maximumLimitReached:
-            print("Too many alarms -- cancel an existing one first")
+            return .tooMany
         @unknown default:
-            print("AlarmKit error: \(error)")
+            return .failed(limitError)
         }
     } catch {
-        print("Unexpected error: \(error)")
+        return .failed(error)
     }
 }
 
-// State transition helpers -- each throws if alarm is in wrong state
-func cancelAlarmSafely(id: Alarm.ID) {
-    do { try AlarmManager.shared.cancel(id: id) }
-    catch { print("Failed to cancel: \(error)") }
-}
-
-func pauseAlarmSafely(id: Alarm.ID) {
-    // Only valid when alarm is in .countdown state
-    do { try AlarmManager.shared.pause(id: id) }
-    catch { print("Cannot pause: \(error)") }
+func holdCountdown(_ alarmID: Alarm.ID) {
+    do {
+        try AlarmManager.shared.pause(id: alarmID)
+    } catch {
+        // pause(id:) only succeeds while the alarm is in .countdown
+    }
 }
 ```
 
-## Apple Documentation Links
-
-- [AlarmKit](https://sosumi.ai/documentation/alarmkit)
-- [AlarmManager](https://sosumi.ai/documentation/alarmkit/alarmmanager)
-- [AlarmAttributes](https://sosumi.ai/documentation/alarmkit/alarmattributes)
-- [AlarmPresentation](https://sosumi.ai/documentation/alarmkit/alarmpresentation)
-- [AlarmPresentationState](https://sosumi.ai/documentation/alarmkit/alarmpresentationstate)
-- [AlarmButton](https://sosumi.ai/documentation/alarmkit/alarmbutton)
-- [Alarm](https://sosumi.ai/documentation/alarmkit/alarm)
-- [Alarm.Schedule](https://sosumi.ai/documentation/alarmkit/alarm/schedule-swift.enum)
-- [Alarm.CountdownDuration](https://sosumi.ai/documentation/alarmkit/alarm/countdownduration-swift.struct)
-- [Scheduling an alarm with AlarmKit](https://sosumi.ai/documentation/alarmkit/scheduling-an-alarm-with-alarmkit)
+When `.maximumLimitReached` comes back, ask the user to remove an existing
+alarm before adding another. The transition calls (`cancel`, `pause`,
+`resume`, `stop`, `countdown`) throw when the alarm is in the wrong state, so
+wrap them in `do/catch`; for example `pause` is valid only in `.countdown`.
+
+## Apple documentation
+
+- [AlarmKit](https://developer.apple.com/documentation/alarmkit)
+- [AlarmManager](https://developer.apple.com/documentation/alarmkit/alarmmanager)
+- [AlarmAttributes](https://developer.apple.com/documentation/alarmkit/alarmattributes)
+- [AlarmPresentation](https://developer.apple.com/documentation/alarmkit/alarmpresentation)
+- [AlarmPresentationState](https://developer.apple.com/documentation/alarmkit/alarmpresentationstate)
+- [AlarmButton](https://developer.apple.com/documentation/alarmkit/alarmbutton)
+- [Alarm](https://developer.apple.com/documentation/alarmkit/alarm)
+- [Alarm.Schedule](https://developer.apple.com/documentation/alarmkit/alarm/schedule)
+- [Alarm.CountdownDuration](https://developer.apple.com/documentation/alarmkit/alarm/countdownduration)
+- [Apple sample: scheduling alarms](https://developer.apple.com/documentation/alarmkit/scheduling-an-alarm-with-alarmkit)