@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/eventkit-calendar/SKILL.md

@@ -1,499 +1,377 @@
 ---
 name: eventkit-calendar
-description: "Create, read, and manage calendar events and reminders using EventKit and EventKitUI. Use when adding events to the user's calendar, creating reminders, setting recurrence rules, requesting calendar or reminders access, presenting event editors, choosing calendars, handling alarms, observing calendar changes, or working with EKEventStore, EKEvent, EKReminder, EKCalendar, EKRecurrenceRule, EKEventEditViewController, EKCalendarChooser, or EventKitUI views."
+description: "EventKit and EventKitUI: adding events to the user's calendar, creating reminders, recurrence rules, calendar or reminders access, event editors, calendar choosers, alarms, change observation, with EKEventStore, EKEvent, EKReminder, EKCalendar, EKRecurrenceRule, EKEventEditViewController, EKCalendarChooser. Use when an app reads or writes the user's calendars or reminders. Not for app-owned local or push notifications (push-notifications)."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
-# EventKit
+# EventKit: Calendars and Reminders
 
-Create, read, and manage calendar events and reminders. Covers authorization,
-event and reminder CRUD, recurrence rules, alarms, and EventKitUI editors.
-Targets Swift 6.3 / iOS 26+.
+EventKit reads and writes the same calendars and reminder lists the user sees
+in Calendar and Reminders. EventKitUI adds system screens for editing, viewing
+and choosing calendars. Examples assume Swift 6.3 and iOS 26.
 
-## Contents
-
-- [Setup](#setup)
-- [Authorization](#authorization)
-- [Creating Events](#creating-events)
-- [Fetching Events](#fetching-events)
-- [Reminders](#reminders)
-- [Recurrence Rules](#recurrence-rules)
-- [Alarms](#alarms)
-- [EventKitUI Controllers](#eventkitui-controllers)
-- [Observing Changes](#observing-changes)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+Alerts the app itself sends (local notifications, pushes) are not EventKit;
+use `UNUserNotificationCenter` and the `push-notifications` skill for those.
 
 ## Setup
 
-### Info.plist Keys
+### Usage descriptions
 
-Add the required usage description strings based on what access level you need:
+| Key | When |
+|-----|------|
+| `NSCalendarsFullAccessUsageDescription` | The app reads and writes events |
+| `NSCalendarsWriteOnlyAccessUsageDescription` | The app writes events directly but never reads them |
+| `NSRemindersFullAccessUsageDescription` | The app reads or writes reminders |
 
-| Key | Access Level |
-|---|---|
-| `NSCalendarsFullAccessUsageDescription` | Read + write events |
-| `NSCalendarsWriteOnlyAccessUsageDescription` | Direct write-only event creation |
-| `NSRemindersFullAccessUsageDescription` | Read + write reminders |
+- Since iOS 17, creating events solely through
+  `EKEventEditViewController` requires no calendar permission and no calendar
+  usage string.
+- Writing events with EventKit directly needs write-only or full access.
+  Reading or fetching events needs full access.
+- Reminders have a single level: full access.
+- If the app also runs on iOS 10 through 16, add the older
+  `NSCalendarsUsageDescription` and `NSRemindersUsageDescription` too. When
+  EventKitUI on those versions may show contact names or photos, add
+  `NSContactsUsageDescription` as well.
 
-On iOS 17+, an app that only presents `EKEventEditViewController` to let the
-person create an event does not need calendar authorization or calendar usage
-strings. Direct EventKit writes need write-only or full calendar access; any
-event read/fetch needs full calendar access. Reminders have only full access.
+### One store
 
-> For apps also running on iOS 10 through iOS 16, include the legacy
-> `NSCalendarsUsageDescription` / `NSRemindersUsageDescription` keys. If using
-> EventKitUI on those systems, also include `NSContactsUsageDescription` when the
-> UI may need contact display names or avatars.
+Create a single `EKEventStore` and share it. Events, reminders and calendars
+belong to the store that produced them; passing an object from one store to
+another is undefined behaviour.
 
-### Event Store
+## Asking for access
 
-Create a single `EKEventStore` instance and reuse it. Do not mix objects from
-different event stores.
+iOS 17 split calendar access into levels. Ask for the smallest one the feature
+needs.
 
 ```swift
 import EventKit
 
-let eventStore = EKEventStore()
-```
-
-## Authorization
-
-iOS 17+ introduced granular access levels. Request the narrowest access that
-matches the feature. If the deployment target includes earlier OS versions,
-availability-guard the iOS 17+ methods and fall back to `requestAccess(to:)`
-only before iOS 17.
-
-### Full Access to Events
-
-Call `try await eventStore.requestFullAccessToEvents()` when the app needs to
-read, edit, delete, or fetch calendar events.
+@MainActor
+final class Planner {
+    let store = EKEventStore()
 
-### Write-Only Access to Events
-
-Use when your app only creates events (e.g., saving an appointment) and does not
-need to read existing events.
-
-Call `try await eventStore.requestWriteOnlyAccessToEvents()` before direct
-EventKit writes that do not use `EKEventEditViewController`.
-
-With write-only access, EventKit can create events but cannot read calendars or
-events, including events the app created. Calendar reads return a virtual
-calendar and event fetches return no events.
+    func allowReadingSchedule() async throws -> Bool {
+        try await store.requestFullAccessToEvents()
+    }
 
-Use full access instead of write-only if the app must later query, verify,
-modify, or sync saved events.
+    func allowAddingEvents() async throws -> Bool {
+        try await store.requestWriteOnlyAccessToEvents()
+    }
 
-### Full Access to Reminders
+    func allowReminders() async throws -> Bool {
+        try await store.requestFullAccessToReminders()
+    }
+}
+```
 
-Call `try await eventStore.requestFullAccessToReminders()` before reading,
-creating, editing, or deleting reminders.
+`Planner` owns the app's one store. `EKEventStore` is not `Sendable`, so
+Swift 6 rejects it as a plain global; keeping it on a `@MainActor` type is the
+simple fix. Later functions that use `store` are `Planner` methods; the
+EventKitUI snippets run inside a view controller that can reach the same store.
 
-### Checking Authorization Status
+- **Full event access**: required to read, change, delete or fetch
+  events.
+- **Write-only event access**: enough to save events directly without the
+  system editor. It cannot read anything, not even events the app itself
+  saved: calendar lookups return a single virtual calendar and event fetches
+  come back empty. If the app will later need to check, edit or sync what it
+  saved, ask for full access instead.
+- **Full access to reminders**: required for any reminder work.
 
-Use `EKEventStore.authorizationStatus(for: .event)` or `.reminder` before work.
-Handle `.notDetermined`, `.fullAccess`, `.writeOnly`, `.restricted`, `.denied`,
-and `@unknown default`; only `.fullAccess` supports event/reminder reads.
+When the deployment target is below iOS 17, wrap these calls in
+`if #available(iOS 17.0, *)` and use `requestAccess(to:)` only in the `else`
+branch.
 
-## Creating Events
+### Checking the current status
 
 ```swift
-func createEvent(
-    title: String,
-    startDate: Date,
-    endDate: Date,
-    calendar: EKCalendar? = nil
-) throws {
-    let event = EKEvent(eventStore: eventStore)
-    event.title = title
-    event.startDate = startDate
-    event.endDate = endDate
-    event.calendar = calendar ?? eventStore.defaultCalendarForNewEvents
-
-    try eventStore.save(event, span: .thisEvent)
+func canReadEvents() -> Bool {
+    switch EKEventStore.authorizationStatus(for: .event) {
+    case .fullAccess:
+        return true
+    case .writeOnly, .notDetermined, .restricted, .denied:
+        return false
+    @unknown default:
+        return false
+    }
 }
 ```
 
-### Setting a Specific Calendar
+Only `.fullAccess` allows reads. The same call with `.reminder` covers
+reminders.
 
-```swift
-// List writable calendars
-let calendars = eventStore.calendars(for: .event)
-    .filter { $0.allowsContentModifications }
-
-// Use the first writable calendar, or the default
-let targetCalendar = calendars.first ?? eventStore.defaultCalendarForNewEvents
-event.calendar = targetCalendar
-```
+## Events
 
-### Adding Structured Location
+### Saving an event
 
 ```swift
-import CoreLocation
-
-let location = EKStructuredLocation(title: "Apple Park")
-location.geoLocation = CLLocation(latitude: 37.3349, longitude: -122.0090)
-event.structuredLocation = location
+func addRehearsal(start: Date) throws {
+    let rehearsal = EKEvent(eventStore: store)
+    rehearsal.title = "Choir Rehearsal"
+    rehearsal.startDate = start
+    rehearsal.endDate = start.addingTimeInterval(90 * 60)
+    rehearsal.calendar = store.defaultCalendarForNewEvents
+    rehearsal.timeZone = TimeZone(identifier: "Europe/Lisbon")
+
+    let hall = EKStructuredLocation(title: "Parish Hall")
+    hall.geoLocation = CLLocation(latitude: 38.7139, longitude: -9.1334)
+    rehearsal.structuredLocation = hall
+
+    try store.save(rehearsal, span: .thisEvent)
+}
 ```
 
-## Fetching Events
-
-Use a date-range predicate to query events. The `events(matching:)` method
-returns occurrences of recurring events expanded within the range. Fetching
-events requires full calendar access; write-only access returns no events.
-Event predicates are capped to a four-year span, and `events(matching:)` /
-`enumerateEvents(matching:using:)` are synchronous and return only committed
-events.
+Before saving into a calendar other than the default, make sure it accepts
+changes:
 
 ```swift
-func fetchEvents(from start: Date, to end: Date) -> [EKEvent] {
-    let predicate = eventStore.predicateForEvents(
-        withStart: start,
-        end: end,
-        calendars: nil  // nil = all calendars
-    )
-    return eventStore.events(matching: predicate)
-        .sorted { $0.startDate < $1.startDate }
-}
+let writable = store.calendars(for: .event).filter(\.allowsContentModifications)
 ```
 
-### Fetching a Single Event by Identifier
+Setting `timeZone` matters for events tied to a place; without it, a traveller
+sees the wrong local time.
+
+### Fetching events
 
 ```swift
-if let event = eventStore.event(withIdentifier: savedEventID) {
-    print(event.title ?? "No title")
+func upcoming(days: Int) -> [EKEvent] {
+    let today = Calendar.current.startOfDay(for: .now)
+    let horizon = today.addingTimeInterval(TimeInterval(days) * 86_400)
+    let window = store.predicateForEvents(withStart: today, end: horizon, calendars: nil)
+    return store.events(matching: window).sorted { $0.startDate < $1.startDate }
 }
 ```
 
-## Reminders
+- `calendars: nil` means every calendar.
+- Recurring events come back as individual occurrences inside the range.
+- Fetching needs full access; under write-only the result is empty.
+- A predicate can span at most four years.
+- Both `events(matching:)` and `enumerateEvents(matching:using:)` run
+  synchronously, and neither sees uncommitted changes.
+- One event by id: `store.event(withIdentifier:)`.
 
-### Creating a Reminder
+## Reminders
 
 ```swift
-func createReminder(title: String, dueDate: Date) throws {
-    let reminder = EKReminder(eventStore: eventStore)
-    reminder.title = title
-    reminder.calendar = eventStore.defaultCalendarForNewReminders()
-
-    let dueDateComponents = Calendar.current.dateComponents(
-        [.year, .month, .day, .hour, .minute],
-        from: dueDate
-    )
-    reminder.dueDateComponents = dueDateComponents
-
-    try eventStore.save(reminder, commit: true)
+func remindToWater(at due: Date) throws {
+    guard let list = store.defaultCalendarForNewReminders() else { throw PlannerError.noReminderList }
+    let reminder = EKReminder(eventStore: store)
+    reminder.title = "Water the tomatoes"
+    reminder.calendar = list
+    let parts: Set<Calendar.Component> = [.year, .month, .day, .hour, .minute]
+    reminder.dueDateComponents = Calendar.current.dateComponents(parts, from: due)
+    try store.save(reminder, commit: true)
 }
 ```
 
-### Fetching Reminders
-
-Reminder fetches are asynchronous and return through a completion handler.
+Reminder fetches use a completion handler that runs on a background queue.
+`EKReminder` is not `Sendable`, so Swift 6 refuses to pass the array through a
+continuation into a main-actor method. Copy what the caller needs into a
+`Sendable` value inside the callback and keep the identifier for a later
+`store.calendarItem(withIdentifier:)` lookup:
 
 ```swift
-func fetchIncompleteReminders() async -> [EKReminder] {
-    let predicate = eventStore.predicateForIncompleteReminders(
+struct ReminderRow: Sendable {
+    let id: String
+    let title: String
+    let due: DateComponents?
+}
+
+func openReminders(until end: Date) async -> [ReminderRow] {
+    let query = store.predicateForIncompleteReminders(
         withDueDateStarting: nil,
-        ending: nil,
+        ending: end,
         calendars: nil
     )
-
-    return await withCheckedContinuation { continuation in
-        eventStore.fetchReminders(matching: predicate) { reminders in
-            continuation.resume(returning: reminders ?? [])
+    return await withCheckedContinuation { resume in
+        store.fetchReminders(matching: query) { found in
+            let rows = (found ?? []).map {
+                ReminderRow(id: $0.calendarItemIdentifier, title: $0.title, due: $0.dueDateComponents)
+            }
+            resume.resume(returning: rows)
         }
     }
 }
 ```
 
-### Completing a Reminder
-
-```swift
-func completeReminder(_ reminder: EKReminder) throws {
-    reminder.isCompleted = true
-    try eventStore.save(reminder, commit: true)
-}
-```
-
-## Recurrence Rules
+To tick a reminder off, set `isCompleted = true` and save it with
+`commit: true`.
 
-Use `EKRecurrenceRule` to create repeating events or reminders.
-
-### Simple Recurrence
+## Recurrence
 
 ```swift
-// Every week, indefinitely
-let weeklyRule = EKRecurrenceRule(
-    recurrenceWith: .weekly,
-    interval: 1,
-    end: nil
-)
-event.addRecurrenceRule(weeklyRule)
+let everyWeek = EKRecurrenceRule(recurrenceWith: .weekly, interval: 1, end: nil)
+standup.addRecurrenceRule(everyWeek)
 
-// Every 2 weeks, ending after 10 occurrences
-let biweeklyRule = EKRecurrenceRule(
-    recurrenceWith: .weekly,
-    interval: 2,
-    end: EKRecurrenceEnd(occurrenceCount: 10)
-)
-
-// Monthly, ending on a specific date
-let monthlyRule = EKRecurrenceRule(
-    recurrenceWith: .monthly,
-    interval: 1,
-    end: EKRecurrenceEnd(end: endDate)
-)
+let tenTimes = EKRecurrenceEnd(occurrenceCount: 10)
+let untilSummer = EKRecurrenceEnd(end: summerStart)
 ```
 
-### Complex Recurrence
+`end: nil` repeats forever; `EKRecurrenceEnd` stops after a count or on a
+date. For richer patterns, the full initializer takes `daysOfTheWeek`,
+`daysOfTheMonth`, `monthsOfTheYear`, `weeksOfTheYear`, `daysOfTheYear`,
+`setPositions` and `end`:
 
 ```swift
-// Every Monday and Wednesday
-let days = [
-    EKRecurrenceDayOfWeek(.monday),
-    EKRecurrenceDayOfWeek(.wednesday)
-]
-
-let complexRule = EKRecurrenceRule(
-    recurrenceWith: .weekly,
+let lastFridayMonthly = EKRecurrenceRule(
+    recurrenceWith: .monthly,
     interval: 1,
-    daysOfTheWeek: days,
+    daysOfTheWeek: [EKRecurrenceDayOfWeek(.friday)],
     daysOfTheMonth: nil,
     monthsOfTheYear: nil,
     weeksOfTheYear: nil,
     daysOfTheYear: nil,
-    setPositions: nil,
-    end: nil
+    setPositions: [-1],
+    end: tenTimes
 )
-event.addRecurrenceRule(complexRule)
 ```
 
-### Editing Recurring Events
-
-When saving changes to a recurring event, specify the span:
-
-```swift
-// Change only this occurrence
-try eventStore.save(event, span: .thisEvent)
-
-// Change this and all future occurrences
-try eventStore.save(event, span: .futureEvents)
-```
+Saving a recurring event needs an `EKSpan`: `.thisEvent` changes one
+occurrence, `.futureEvents` changes it and every later one.
 
 ## Alarms
 
-Attach alarms to events or reminders to trigger notifications.
-
 ```swift
-// 15 minutes before
-let alarm = EKAlarm(relativeOffset: -15 * 60)
-event.addAlarm(alarm)
-
-// At an absolute date
-let absoluteAlarm = EKAlarm(absoluteDate: alertDate)
-event.addAlarm(absoluteAlarm)
+rehearsal.addAlarm(EKAlarm(relativeOffset: -30 * 60))
+rehearsal.addAlarm(EKAlarm(absoluteDate: dayBefore))
 ```
 
-For reminder geofences, put an `EKStructuredLocation` and `.enter` / `.leave`
-proximity on an `EKAlarm`, then add it to the reminder. See
-[references/eventkit-patterns.md](references/eventkit-patterns.md) for the full
-location-based reminder pattern.
+A relative offset is in seconds from the start (negative means before). An
+absolute alarm fires at a fixed moment. These alarms belong to the user's
+calendar data; the system delivers them, and they do not need the app's
+notification permission.
 
-## EventKitUI Controllers
+Reminders can also fire on arrival or departure: an `EKAlarm` carrying an
+`EKStructuredLocation` and a `.enter` or `.leave` proximity. The full recipe,
+including radius and priority, is in the
+[patterns reference](references/eventkit-patterns.md).
 
-### EKEventEditViewController  -  Create/Edit Events
+## EventKitUI
 
-Present the system event editor for creating or editing events.
+### Event editor
 
-On iOS 17+, `EKEventEditViewController` can let someone create an event without
-the app requesting calendar access. The editor runs out of process with its own
-calendar access, so do not inspect the dismissed controller to learn what was
-saved; refetch only if the app separately has full access.
+`EKEventEditViewController` is the system editor for creating and changing
+events. From iOS 17 it runs in a separate process with its own access, so the
+app can use it without asking for calendar permission. The flip side: the app
+cannot see what the user saved. Reading properties off the dismissed editor
+tells you nothing reliable; a fresh fetch works only when the app has its own
+full access.
 
 ```swift
-import EventKitUI
-
-class EventEditorCoordinator: NSObject, EKEventEditViewDelegate {
-    let eventStore = EKEventStore()
+func presentEditor(from host: UIViewController, delegate: any EKEventEditViewDelegate) {
+    let editor = EKEventEditViewController()
+    editor.eventStore = store
+    editor.editViewDelegate = delegate
+    host.present(editor, animated: true)
+}
 
-    func presentEditor(from viewController: UIViewController) {
-        let editor = EKEventEditViewController()
-        editor.eventStore = eventStore
-        editor.editViewDelegate = self
-        viewController.present(editor, animated: true)
-    }
+final class TripViewController: UIViewController, @preconcurrency EKEventEditViewDelegate {
+    private var lastEditorOutcome: EKEventEditViewAction?
 
-    func eventEditViewController(
-        _ controller: EKEventEditViewController,
-        didCompleteWith action: EKEventEditViewAction
-    ) {
-        switch action {
-        case .saved:
-            // Event saved
-            break
-        case .canceled:
-            break
-        case .deleted:
-            break
-        @unknown default:
-            break
-        }
-        controller.dismiss(animated: true)
+    func eventEditViewController(_ editor: EKEventEditViewController,
+                                 didCompleteWith outcome: EKEventEditViewAction) {
+        lastEditorOutcome = outcome
+        editor.dismiss(animated: true)
     }
 }
 ```
 
-### EKEventViewController  -  View an Event
-
-```swift
-import EventKitUI
-
-let viewer = EKEventViewController()
-viewer.event = existingEvent
-viewer.allowsEditing = true
-navigationController?.pushViewController(viewer, animated: true)
-```
-
-### EKCalendarChooser  -  Select Calendars
+The outcome is `.saved`, `.canceled` or `.deleted`; a `switch` over it needs
+an `@unknown default`. Whatever the outcome, the delegate dismisses the editor.
+`EKEventEditViewDelegate` has no actor annotation, so a view controller, which
+is main-actor isolated, adopts it with `@preconcurrency`. The editor calls the
+delegate on the main thread, which is what that conformance checks at run time.
 
-`EKCalendarChooser` requires write-only or full calendar access. In write-only
-apps, the chooser behaves as writable-calendars-only and only allows a single
-writable calendar selection.
+### Viewer and calendar chooser
 
 ```swift
-let chooser = EKCalendarChooser(
+let detail = EKEventViewController()
+detail.event = selectedEvent
+detail.allowsEditing = true
+navigationController?.pushViewController(detail, animated: true)
+
+let picker = EKCalendarChooser(
     selectionStyle: .multiple,
     displayStyle: .allCalendars,
     entityType: .event,
-    eventStore: eventStore
+    eventStore: store
 )
-chooser.showsDoneButton = true
-chooser.showsCancelButton = true
-chooser.delegate = self
-present(UINavigationController(rootViewController: chooser), animated: true)
-```
-
-## Observing Changes
-
-Register for `EKEventStoreChanged` notifications to keep your UI in sync when
-events are modified outside your app (e.g., by the Calendar app or a sync).
-
-```swift
-NotificationCenter.default.addObserver(
-    forName: .EKEventStoreChanged,
-    object: eventStore,
-    queue: .main
-) { [weak self] _ in
-    self?.refreshEvents()
-}
+picker.showsCancelButton = true
+picker.showsDoneButton = true
+picker.delegate = self
+let wrapper = UINavigationController(rootViewController: picker)
+present(wrapper, animated: true)
 ```
 
-Always re-fetch events after receiving this notification. Previously fetched
-`EKEvent`, `EKReminder`, and `EKCalendar` objects may be stale. The notification
-is posted on the main actor.
-
-On iOS 26+, you can also use the typed `EKEventStore.EventStoreChanged` /
-`.changed` notification message behind availability checks.
+`EKCalendarChooser` needs write-only or full access. Under write-only it lists
+only writable calendars and allows one selection.
 
-## Common Mistakes
+## Staying in sync
 
-### DON'T: Use the deprecated requestAccess(to:) method
+Other apps and sync services change calendars all the time. Listen for
+`.EKEventStoreChanged` and refetch:
 
 ```swift
-// WRONG: Deprecated in iOS 17
-eventStore.requestAccess(to: .event) { granted, error in }
-
-// CORRECT: Use the granular async methods
-let granted = try await eventStore.requestFullAccessToEvents()
-```
-
-On iOS 17+, `requestAccess(to: .event)` does not prompt and throws. Keep it only
-as an availability-guarded fallback for apps that still run on earlier systems.
-
-### DON'T: Save events to a read-only calendar
-
-```swift
-// WRONG: No check -- will throw if calendar is read-only
-event.calendar = someCalendar
-try eventStore.save(event, span: .thisEvent)
-
-// CORRECT: Verify the calendar allows modifications
-guard someCalendar.allowsContentModifications else {
-    event.calendar = eventStore.defaultCalendarForNewEvents
-    return
+let center = NotificationCenter.default
+changeToken = center.addObserver(forName: .EKEventStoreChanged, object: store, queue: .main) { [weak self] _ in
+    Task { @MainActor in self?.reload() }
 }
-event.calendar = someCalendar
-try eventStore.save(event, span: .thisEvent)
-```
-
-### DON'T: Ignore timezone when creating events
-
-```swift
-// WRONG: Event appears at wrong time for traveling users
-event.startDate = Date()
-event.endDate = Date().addingTimeInterval(3600)
-
-// CORRECT: Set the timezone explicitly for location-specific events
-event.timeZone = TimeZone(identifier: "America/New_York")
-event.startDate = startDate
-event.endDate = endDate
-```
-
-### DON'T: Forget to commit batched saves
-
-```swift
-// WRONG: Changes never persisted
-try eventStore.save(event1, span: .thisEvent, commit: false)
-try eventStore.save(event2, span: .thisEvent, commit: false)
-// Missing commit!
-
-// CORRECT: Commit after batching
-try eventStore.save(event1, span: .thisEvent, commit: false)
-try eventStore.save(event2, span: .thisEvent, commit: false)
-try eventStore.commit()
-```
-
-### DON'T: Mix EKObjects from different event stores
-
-```swift
-// WRONG: Event fetched from storeA, saved to storeB
-let event = storeA.event(withIdentifier: id)!
-try storeB.save(event, span: .thisEvent) // Undefined behavior
-
-// CORRECT: Use the same store throughout
-let event = eventStore.event(withIdentifier: id)!
-try eventStore.save(event, span: .thisEvent)
 ```
 
-## Review Checklist
-
-- [ ] Correct `Info.plist` usage description keys added for calendars and/or reminders
-- [ ] Authorization requested with iOS 17+ granular methods, with `requestAccess(to:)` only as a pre-iOS 17 fallback
-- [ ] Write-only calendar access used only for direct event creation, not event/calendar reads
-- [ ] Authorization status checked before fetching or saving
-- [ ] Full access required before any event or reminder fetch
-- [ ] Single `EKEventStore` instance reused across the app
-- [ ] Events saved to a writable calendar (`allowsContentModifications` checked)
-- [ ] Recurring event saves specify correct `EKSpan` (`.thisEvent` vs `.futureEvents`)
-- [ ] Batched saves followed by explicit `commit()`
-- [ ] `EKEventStoreChanged` notification observed to refresh stale data
-- [ ] iOS 26 typed `.changed` notification used only behind availability checks
-- [ ] Timezone set explicitly for location-specific events
-- [ ] EKObjects not shared across different event store instances
-- [ ] EventKitUI delegates dismiss controllers in completion callbacks
+After the notification, treat every `EKEvent`, `EKReminder` and `EKCalendar`
+you hold as possibly stale and fetch again. EventKit posts this notification
+on the main actor. iOS 26 adds a typed message, `EKEventStore.EventStoreChanged`
+(used as `.changed`), for the new Foundation notification API; use it only
+behind an availability check. See the reference for both forms.
+
+## Common mistakes
+
+- **`requestAccess(to:)` on iOS 17 and later.** Deprecated from iOS 17; asking
+  for `.event` that way shows no prompt and fails with an error. It belongs in
+  the pre-17 branch only.
+- **Saving into a read-only calendar.** The save throws. Check
+  `allowsContentModifications`, falling back to the default calendar.
+- **No time zone on place-bound events.** Set `timeZone` explicitly, for
+  example `TimeZone(identifier: "Asia/Tokyo")`.
+- **Batching without committing.** After saves with `commit: false`, call
+  `try store.commit()`, or nothing is stored.
+- **Objects from two stores.** Fetching from one store and saving through
+  another is undefined behaviour.
+
+## Review checklist
+
+- [ ] Usage keys match what the app touches (calendars, reminders or both)
+- [ ] iOS 17 granular requests used; `requestAccess(to:)` only as pre-17 fallback
+- [ ] Write-only used only for direct creation, never for reads
+- [ ] Status is read before any fetch or save
+- [ ] Fetching events or reminders only happens with full access
+- [ ] One `EKEventStore` reused throughout
+- [ ] Target calendar checked for `allowsContentModifications`
+- [ ] Recurring saves pass the intended `EKSpan`
+- [ ] `commit()` follows every batch
+- [ ] `EKEventStoreChanged` observed and data refetched
+- [ ] iOS 26 typed `.changed` message only behind availability checks
+- [ ] Explicit time zone on location-specific events
+- [ ] No EventKit object crosses between stores
+- [ ] EventKitUI delegates dismiss their controllers
 
 ## References
 
-- Extended patterns (SwiftUI wrappers, predicate queries, batch operations): [references/eventkit-patterns.md](references/eventkit-patterns.md)
-- [EventKit framework](https://sosumi.ai/documentation/eventkit)
-- [EKEventStore](https://sosumi.ai/documentation/eventkit/ekeventstore)
-- [EKEvent](https://sosumi.ai/documentation/eventkit/ekevent)
-- [EKReminder](https://sosumi.ai/documentation/eventkit/ekreminder)
-- [EKRecurrenceRule](https://sosumi.ai/documentation/eventkit/ekrecurrencerule)
-- [EKCalendar](https://sosumi.ai/documentation/eventkit/ekcalendar)
-- [EventKit UI](https://sosumi.ai/documentation/eventkitui)
-- [EKEventEditViewController](https://sosumi.ai/documentation/eventkitui/ekeventeditviewcontroller)
-- [EKCalendarChooser](https://sosumi.ai/documentation/eventkitui/ekcalendarchooser)
-- [Accessing the event store](https://sosumi.ai/documentation/eventkit/accessing-the-event-store)
-- [Creating a recurring event](https://sosumi.ai/documentation/eventkit/creating-a-recurring-event)
+- [EventKit patterns](references/eventkit-patterns.md): SwiftUI manager and
+  view, predicates and enumeration, batches, calendar creation, location and
+  priority reminders, SwiftUI editor wrapper, typed change notifications
+- Apple documentation:
+  [EventKit](https://developer.apple.com/documentation/eventkit),
+  [event store](https://developer.apple.com/documentation/eventkit/ekeventstore),
+  [event](https://developer.apple.com/documentation/eventkit/ekevent),
+  [reminder](https://developer.apple.com/documentation/eventkit/ekreminder),
+  [recurrence rule](https://developer.apple.com/documentation/eventkit/ekrecurrencerule),
+  [calendar](https://developer.apple.com/documentation/eventkit/ekcalendar),
+  [EventKitUI framework](https://developer.apple.com/documentation/eventkitui),
+  [event editor](https://developer.apple.com/documentation/eventkitui/ekeventeditviewcontroller),
+  [calendar chooser](https://developer.apple.com/documentation/eventkitui/ekcalendarchooser),
+  [article on store access](https://developer.apple.com/documentation/eventkit/accessing-the-event-store),
+  [article on repeating events](https://developer.apple.com/documentation/eventkit/creating-a-recurring-event)