@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/contacts-framework/SKILL.md

@@ -1,237 +1,204 @@
 ---
 name: contacts-framework
-description: "Read, create, update, and pick contacts using the Contacts and ContactsUI frameworks. Use when fetching contact data, saving new contacts, wrapping CNContactPickerViewController in SwiftUI, handling contact permissions, or working with CNContactStore fetch and save requests."
+description: "Contacts and ContactsUI: CNContactStore authorization and limited access, fetch and save requests, creating, updating and deleting contacts, CNContactPickerViewController in SwiftUI, change observation. Use when fetching, saving or picking contacts or handling permissions."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
-# Contacts Framework
+# Contacts and ContactsUI
 
-Fetch, create, update, and pick contacts from the user's Contacts database using
-`CNContactStore`, `CNSaveRequest`, and `CNContactPickerViewController`. Targets
-Swift 6.3 / iOS 26+.
+`CNContactStore` is the gateway to the user's address book: it answers
+authorization questions, runs fetches and executes save requests.
+ContactsUI adds the system contact picker and the SwiftUI controls for
+limited access. Code here assumes Swift 6.3 and an iOS 26 deployment target.
 
-## Contents
-
-- [Setup](#setup)
-- [Authorization](#authorization)
-- [Fetching Contacts](#fetching-contacts)
-- [Key Descriptors](#key-descriptors)
-- [Creating and Updating Contacts](#creating-and-updating-contacts)
-- [Contact Picker](#contact-picker)
-- [Observing Changes](#observing-changes)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+Not for Swift change-history enumeration: the Contacts Swift API does not
+offer it.
 
 ## Setup
 
-### Project Configuration
-
-1. Add `NSContactsUsageDescription` to Info.plist explaining why the app accesses contacts. The app crashes if it uses contact data APIs without this key.
-2. No additional capability or entitlement is required for ordinary Contacts access.
-3. Add `com.apple.developer.contacts.notes` only when reading or writing `CNContactNoteKey` / `CNContact.note`; this entitlement requires Apple approval before public distribution.
-
-### Imports
+- Info.plist must contain `NSContactsUsageDescription`. Calling the contact
+  data APIs without it terminates the app.
+- Ordinary Contacts access needs no capability or entitlement.
+- The note field is special. Reading or writing `CNContactNoteKey`
+  (`CNContact.note`) requires the `com.apple.developer.contacts.notes`
+  entitlement, and Apple must approve that entitlement before the app can be
+  distributed publicly.
 
 ```swift
-@preconcurrency import Contacts  // CNContactStore, CNSaveRequest, CNContact
-import ContactsUI                // CNContactPickerViewController
+@preconcurrency import Contacts   // store, contacts, save requests
+import ContactsUI                 // picker and limited-access UI
 ```
 
 ## Authorization
 
-Request access before fetching or saving contacts. The picker (`CNContactPickerViewController`)
-does not require authorization -- the system grants access only to the contacts
-the user selects.
+Ask before the first fetch or save. The picker is the exception: it runs
+out of process and hands over only what the user chose, so it needs no
+permission at all.
 
 ```swift
-let store = CNContactStore()
-
-func requestAccess() async throws -> Bool {
-    return try await store.requestAccess(for: .contacts)
-}
-
-// Check current status without prompting
-func checkStatus() -> CNAuthorizationStatus {
-    CNContactStore.authorizationStatus(for: .contacts)
+let book = CNContactStore()   // create once, share across the app
+
+func ensureAccess() async throws -> Bool {
+    switch CNContactStore.authorizationStatus(for: .contacts) {
+    case .authorized, .limited:
+        return true
+    case .notDetermined:
+        return try await book.requestAccess(for: .contacts)
+    case .denied, .restricted:
+        return false          // explain and link to Settings
+    @unknown default:
+        return false
+    }
 }
 ```
 
-### Authorization States
+`authorizationStatus(for:)` reads the state without prompting.
 
 | Status | Meaning |
 |---|---|
-| `.notDetermined` | User has not been prompted yet |
-| `.authorized` | Full read/write access granted |
-| `.denied` | User denied access; direct to Settings |
-| `.restricted` | Parental controls or MDM restrict access |
-| `.limited` | iOS 18+: user granted access to selected contacts only |
+| `.notDetermined` | Never asked |
+| `.authorized` | Full read and write access |
+| `.limited` | iOS 18+: only the contacts the user shared with the app |
+| `.denied` | User said no; point to Settings |
+| `.restricted` | Blocked by parental controls or device management |
 
-Treat both `.authorized` and `.limited` as usable Contacts API states. With
-`.limited`, fetch, edit, and delete operations only apply to contacts the user
-granted or the app created. Use `ContactAccessButton` or
-`contactAccessPicker(isPresented:completionHandler:)` to let users add contacts
-to the app's limited-access set.
+Treat `.authorized` and `.limited` alike as "can proceed". Under `.limited`,
+fetches, edits and deletes only reach contacts the user granted plus contacts
+the app created itself. Let people widen that set with `ContactAccessButton`
+or the `contactAccessPicker(isPresented:completionHandler:)` modifier.
 
-## Fetching Contacts
+## Fetching
 
-Use `unifiedContacts(matching:keysToFetch:)` for predicate-based queries.
-Use `enumerateContacts(with:usingBlock:)` for batch enumeration of all contacts.
-For large cached address books, first fetch identifiers, then fetch detailed
-contacts in batches by identifier.
+- `unifiedContacts(matching:keysToFetch:)` answers a predicate query.
+- `unifiedContact(withIdentifier:keysToFetch:)` loads one known contact.
+- `enumerateContacts(with:usingBlock:)` walks the whole book.
 
-### Fetch by Name
+For big address books, collect identifiers first and then load details in
+batches by identifier.
 
 ```swift
-func fetchContacts(named name: String) throws -> [CNContact] {
-    let predicate = CNContact.predicateForContacts(matchingName: name)
-    let keys: [CNKeyDescriptor] = [
-        CNContactGivenNameKey as CNKeyDescriptor,
-        CNContactFamilyNameKey as CNKeyDescriptor,
-        CNContactPhoneNumbersKey as CNKeyDescriptor
-    ]
-    return try store.unifiedContacts(matching: predicate, keysToFetch: keys)
-}
-```
+let wanted: [CNKeyDescriptor] = [
+    CNContactGivenNameKey as CNKeyDescriptor,
+    CNContactFamilyNameKey as CNKeyDescriptor,
+    CNContactEmailAddressesKey as CNKeyDescriptor
+]
 
-### Fetch by Identifier
+let byName = try book.unifiedContacts(
+    matching: CNContact.predicateForContacts(matchingName: "Okafor"),
+    keysToFetch: wanted
+)
 
-```swift
-func fetchContact(identifier: String) throws -> CNContact {
-    let keys: [CNKeyDescriptor] = [
-        CNContactGivenNameKey as CNKeyDescriptor,
-        CNContactFamilyNameKey as CNKeyDescriptor,
-        CNContactEmailAddressesKey as CNKeyDescriptor
-    ]
-    return try store.unifiedContact(withIdentifier: identifier, keysToFetch: keys)
-}
+let single = try book.unifiedContact(withIdentifier: savedID, keysToFetch: wanted)
 ```
 
-### Enumerate All Contacts
-
-Perform I/O-heavy enumeration off the main thread.
+Enumeration hits storage, so keep it off the main actor:
 
 ```swift
-func fetchAllContacts() throws -> [CNContact] {
-    let keys: [CNKeyDescriptor] = [
-        CNContactGivenNameKey as CNKeyDescriptor,
-        CNContactFamilyNameKey as CNKeyDescriptor
-    ]
-    let request = CNContactFetchRequest(keysToFetch: keys)
-    request.sortOrder = .givenName
-
-    var contacts: [CNContact] = []
-    try store.enumerateContacts(with: request) { contact, _ in
-        contacts.append(contact)
-    }
-    return contacts
+func everyone(in book: CNContactStore) async throws -> [CNContact] {
+    try await Task.detached {
+        let request = CNContactFetchRequest(keysToFetch: [
+            CNContactGivenNameKey as CNKeyDescriptor,
+            CNContactFamilyNameKey as CNKeyDescriptor
+        ])
+        request.sortOrder = .familyName
+        var found: [CNContact] = []
+        try book.enumerateContacts(with: request) { person, _ in found.append(person) }
+        return found
+    }.value
 }
 ```
 
-## Key Descriptors
-
-Only fetch the properties you need. Accessing an unfetched property throws
-`CNContactPropertyNotFetchedException`.
+## Choosing keys
 
-### Common Keys
+Ask only for the properties the screen shows. Reading a property that was
+not fetched raises `CNContactPropertyNotFetchedException`.
 
-| Key | Property |
+| Key | Gives you |
 |---|---|
-| `CNContactGivenNameKey` | First name |
-| `CNContactFamilyNameKey` | Last name |
-| `CNContactPhoneNumbersKey` | Phone numbers array |
-| `CNContactEmailAddressesKey` | Email addresses array |
-| `CNContactPostalAddressesKey` | Mailing addresses array |
-| `CNContactImageDataKey` | Full-resolution contact photo |
-| `CNContactThumbnailImageDataKey` | Thumbnail contact photo |
-| `CNContactBirthdayKey` | Birthday date components |
-| `CNContactOrganizationNameKey` | Company name |
-
-### Composite Key Descriptors
-
-Use `CNContactFormatter.descriptorForRequiredKeys(for:)` to fetch all keys needed
-for formatting a contact's name.
+| `CNContactGivenNameKey`, `CNContactFamilyNameKey` | Name parts |
+| `CNContactPhoneNumbersKey` | Phone numbers |
+| `CNContactEmailAddressesKey` | Email addresses |
+| `CNContactPostalAddressesKey` | Postal addresses |
+| `CNContactImageDataKey` | Full-resolution photo |
+| `CNContactThumbnailImageDataKey` | Small photo for lists |
+| `CNContactBirthdayKey` | Birthday as date components |
+| `CNContactOrganizationNameKey` | Company |
+
+To display a formatted name, let the formatter tell you what it needs and
+mix that descriptor into the key list:
 
 ```swift
-let nameKeys = CNContactFormatter.descriptorForRequiredKeys(for: .fullName)
-let keys: [CNKeyDescriptor] = [nameKeys, CNContactPhoneNumbersKey as CNKeyDescriptor]
+let listKeys: [CNKeyDescriptor] = [
+    CNContactFormatter.descriptorForRequiredKeys(for: .fullName),
+    CNContactThumbnailImageDataKey as CNKeyDescriptor
+]
 ```
 
-## Creating and Updating Contacts
+## Writing
 
-Use `CNMutableContact` to build new contacts and `CNSaveRequest` to persist changes.
+`CNContact` is immutable. Build or copy a `CNMutableContact`, describe the
+change in a `CNSaveRequest`, then run it with `execute(_:)`.
 
-### Creating a New Contact
+### Create
 
 ```swift
-func createContact(givenName: String, familyName: String, phone: String) throws {
-    let contact = CNMutableContact()
-    contact.givenName = givenName
-    contact.familyName = familyName
-    contact.phoneNumbers = [
-        CNLabeledValue(
-            label: CNLabelPhoneNumberMobile,
-            value: CNPhoneNumber(stringValue: phone)
-        )
-    ]
-
-    let saveRequest = CNSaveRequest()
-    saveRequest.add(contact, toContainerWithIdentifier: nil) // nil = default container
-    try store.execute(saveRequest)
-}
+let fresh = CNMutableContact()
+fresh.givenName = "Imani"
+fresh.familyName = "Okafor"
+fresh.phoneNumbers = [
+    CNLabeledValue(label: CNLabelPhoneNumberMobile,
+                   value: CNPhoneNumber(stringValue: "+44 20 7946 0018"))
+]
+
+let create = CNSaveRequest()
+create.add(fresh, toContainerWithIdentifier: nil)   // nil means the default container
+try book.execute(create)
 ```
 
-### Updating an Existing Contact
+### Update
 
-You must fetch the contact with the properties you intend to modify, create a
-mutable copy, change the properties, then save.
+Fetch with every key you intend to change, copy, edit, save:
 
 ```swift
-func updateContactEmail(identifier: String, email: String) throws {
-    let keys: [CNKeyDescriptor] = [
-        CNContactEmailAddressesKey as CNKeyDescriptor
-    ]
-    let contact = try store.unifiedContact(withIdentifier: identifier, keysToFetch: keys)
-    guard let mutable = contact.mutableCopy() as? CNMutableContact else { return }
-
-    mutable.emailAddresses.append(
-        CNLabeledValue(label: CNLabelWork, value: email as NSString)
-    )
-
-    let saveRequest = CNSaveRequest()
-    saveRequest.update(mutable)
-    try store.execute(saveRequest)
-}
+let current = try book.unifiedContact(
+    withIdentifier: savedID,
+    keysToFetch: [CNContactEmailAddressesKey as CNKeyDescriptor]
+)
+guard let editable = current.mutableCopy() as? CNMutableContact else { return }
+editable.emailAddresses.append(
+    CNLabeledValue(label: CNLabelWork, value: "imani@studio.example" as NSString)
+)
+let change = CNSaveRequest()
+change.update(editable)
+try book.execute(change)
 ```
 
-### Deleting a Contact
+### Delete
 
 ```swift
-func deleteContact(identifier: String) throws {
-    let keys: [CNKeyDescriptor] = [CNContactIdentifierKey as CNKeyDescriptor]
-    let contact = try store.unifiedContact(withIdentifier: identifier, keysToFetch: keys)
-    guard let mutable = contact.mutableCopy() as? CNMutableContact else { return }
-
-    let saveRequest = CNSaveRequest()
-    saveRequest.delete(mutable)
-    try store.execute(saveRequest)
+let target = try book.unifiedContact(
+    withIdentifier: savedID,
+    keysToFetch: [CNContactIdentifierKey as CNKeyDescriptor]
+)
+if let doomed = target.mutableCopy() as? CNMutableContact {
+    let removal = CNSaveRequest()
+    removal.delete(doomed)
+    try book.execute(removal)
 }
 ```
 
-## Contact Picker
-
-`CNContactPickerViewController` lets users pick contacts without granting full
-Contacts access. The app receives only the selected contact data.
+## The contact picker
 
-### SwiftUI Wrapper
+`CNContactPickerViewController` returns the chosen contact without the app
+ever holding Contacts permission.
 
 ```swift
-import SwiftUI
 import ContactsUI
+import SwiftUI
 
-struct ContactPicker: UIViewControllerRepresentable {
-    @Binding var selectedContact: CNContact?
+struct ContactChooser: UIViewControllerRepresentable {
+    var onPick: (CNContact?) -> Void
 
     func makeUIViewController(context: Context) -> CNContactPickerViewController {
         let picker = CNContactPickerViewController()
@@ -239,209 +206,93 @@ struct ContactPicker: UIViewControllerRepresentable {
         return picker
     }
 
-    func updateUIViewController(_ uiViewController: CNContactPickerViewController, context: Context) {}
+    func updateUIViewController(_ picker: CNContactPickerViewController, context: Context) { }
 
-    func makeCoordinator() -> Coordinator {
-        Coordinator(self)
-    }
+    func makeCoordinator() -> Coordinator { Coordinator(onPick: onPick) }
 
     final class Coordinator: NSObject, CNContactPickerDelegate {
-        let parent: ContactPicker
-
-        init(_ parent: ContactPicker) {
-            self.parent = parent
-        }
+        let onPick: (CNContact?) -> Void
+        init(onPick: @escaping (CNContact?) -> Void) { self.onPick = onPick }
 
         func contactPicker(_ picker: CNContactPickerViewController, didSelect contact: CNContact) {
-            parent.selectedContact = contact
+            onPick(contact)
         }
 
         func contactPickerDidCancel(_ picker: CNContactPickerViewController) {
-            parent.selectedContact = nil
+            onPick(nil)
         }
     }
 }
-```
-
-### Using the Picker
 
-```swift
-struct ContactSelectionView: View {
-    @State private var selectedContact: CNContact?
-    @State private var showPicker = false
-
-    var body: some View {
-        VStack {
-            if let contact = selectedContact {
-                Text("\(contact.givenName) \(contact.familyName)")
-            }
-            Button("Select Contact") {
-                showPicker = true
-            }
-        }
-        .sheet(isPresented: $showPicker) {
-            ContactPicker(selectedContact: $selectedContact)
-        }
-    }
-}
+// .sheet(isPresented: $choosing) { ContactChooser { chosen = $0 } }
 ```
 
-### Filtering the Picker
-
-Use predicates to control which contacts appear and what the user can select.
+Set the picker's predicates before it is presented:
 
 ```swift
-let picker = CNContactPickerViewController()
-// Only show contacts that have an email address
-picker.predicateForEnablingContact = NSPredicate(format: "emailAddresses.@count > 0")
-// Selecting a contact returns it directly (no detail card)
-picker.predicateForSelectionOfContact = NSPredicate(value: true)
+picker.predicateForEnablingContact = NSPredicate(format: "phoneNumbers.@count > 0")
+picker.predicateForSelectionOfContact = NSPredicate(value: true)   // return at once, no detail card
 ```
 
-## Observing Changes
+## Watching for changes
 
-Listen for external contact database changes to refresh cached data.
+Other apps and sync can change the address book at any time. Cached
+`CNContact` values go stale, so listen for `.CNContactStoreDidChange` and
+fetch again:
 
 ```swift
-func observeContactChanges() {
-    NotificationCenter.default.addObserver(
-        forName: .CNContactStoreDidChange,
-        object: nil,
-        queue: .main
-    ) { _ in
-        // Refetch contacts -- cached CNContact objects are stale
-        refreshContacts()
-    }
-}
-```
-
-## Common Mistakes
-
-### DON'T: Fetch all keys when you only need a name
-
-Over-fetching wastes memory and slows queries, especially for contacts with
-large photos.
-
-```swift
-// WRONG: Fetches far more than the UI displays, including full-resolution photos
-let keys: [CNKeyDescriptor] = [
-    CNContactFormatter.descriptorForRequiredKeys(for: .fullName),
-    CNContactImageDataKey as CNKeyDescriptor,
-    CNContactPhoneNumbersKey as CNKeyDescriptor,
-    CNContactEmailAddressesKey as CNKeyDescriptor,
-    CNContactPostalAddressesKey as CNKeyDescriptor,
-    CNContactBirthdayKey as CNKeyDescriptor
-]
-
-// CORRECT: Fetch only what you display
-let keys: [CNKeyDescriptor] = [
-    CNContactGivenNameKey as CNKeyDescriptor,
-    CNContactFamilyNameKey as CNKeyDescriptor
-]
-```
-
-### DON'T: Access unfetched properties
-
-Accessing a property that was not in `keysToFetch` throws
-`CNContactPropertyNotFetchedException` at runtime.
-
-```swift
-// WRONG: Only fetched name keys, now accessing phone
-let keys: [CNKeyDescriptor] = [CNContactGivenNameKey as CNKeyDescriptor]
-let contact = try store.unifiedContact(withIdentifier: id, keysToFetch: keys)
-let phone = contact.phoneNumbers.first // CRASH
-
-// CORRECT: Include the key you need
-let keys: [CNKeyDescriptor] = [
-    CNContactGivenNameKey as CNKeyDescriptor,
-    CNContactPhoneNumbersKey as CNKeyDescriptor
-]
-```
-
-### DON'T: Mutate a CNContact directly
-
-`CNContact` is immutable. You must call `mutableCopy()` to get a `CNMutableContact`.
-
-```swift
-// WRONG: CNContact has no setter
-let contact = try store.unifiedContact(withIdentifier: id, keysToFetch: keys)
-contact.givenName = "New Name" // Compile error
-
-// CORRECT: Create mutable copy
-guard let mutable = contact.mutableCopy() as? CNMutableContact else { return }
-mutable.givenName = "New Name"
-```
-
-### DON'T: Skip authorization and assume access
-
-Do not let fetch or save calls be the first place the user sees authorization.
-If status is `.notDetermined`, request access; if access was denied, contact
-operations fail with an authorization error.
-
-```swift
-// WRONG: Jump straight to fetch
-let contacts = try store.unifiedContacts(matching: predicate, keysToFetch: keys)
-
-// CORRECT: Check or request access first
-let granted = try await store.requestAccess(for: .contacts)
-guard granted else { return }
-let contacts = try store.unifiedContacts(matching: predicate, keysToFetch: keys)
-```
-
-### DON'T: Run heavy fetches on the main thread
-
-`enumerateContacts` performs I/O. Running it on the main thread blocks the UI.
-When strict concurrency checks complain about `CNContact` crossing task or actor
-boundaries, use `@preconcurrency import Contacts` in that file or map contacts
-into Sendable view models before returning them.
-
-```swift
-// WRONG: Main thread enumeration
-func loadContacts() {
-    try store.enumerateContacts(with: request) { contact, _ in ... }
-}
-
-// CORRECT: Run on a background thread
-func loadContacts() async throws -> [CNContact] {
-    try await Task.detached {
-        var results: [CNContact] = []
-        try store.enumerateContacts(with: request) { contact, _ in
-            results.append(contact)
-        }
-        return results
-    }.value
+let token = NotificationCenter.default.addObserver(
+    forName: .CNContactStoreDidChange, object: nil, queue: .main
+) { _ in
+    Task { @MainActor in await reloadVisibleContacts() }
 }
 ```
 
-## Review Checklist
-
-- [ ] `NSContactsUsageDescription` added to Info.plist
-- [ ] `requestAccess(for: .contacts)` called before fetch or save operations
-- [ ] `.limited` treated as usable access with selected-contact caveats
-- [ ] `ContactAccessButton` or `contactAccessPicker` offered when users need to expand limited access
-- [ ] Authorization denial handled gracefully (guide user to Settings)
-- [ ] Only needed `CNKeyDescriptor` keys included in fetch requests
-- [ ] `CNContactFormatter.descriptorForRequiredKeys(for:)` used when formatting names
-- [ ] Mutable copy created via `mutableCopy()` before modifying contacts
-- [ ] `CNSaveRequest` used for all create/update/delete operations
-- [ ] Heavy fetches (`enumerateContacts`) run off the main thread
-- [ ] `CNContactStoreDidChange` observed to refresh cached contacts
-- [ ] `CNContactPickerViewController` used when full Contacts access is unnecessary
-- [ ] Picker predicates set before presenting the picker view controller
-- [ ] Single `CNContactStore` instance reused across the app
+## Common mistakes
+
+- **Fetching too much.** Loading `CNContactImageDataKey`, postal addresses
+  and birthdays for a list that shows names costs memory and time. Fetch the
+  keys the screen uses.
+- **Reading a key you did not fetch.** Asking for `phoneNumbers` after a
+  name-only fetch crashes at runtime.
+- **Mutating a `CNContact`.** It does not compile; take a `mutableCopy()`.
+- **Letting a fetch be the first permission touchpoint.** Request access when
+  the status is `.notDetermined`; otherwise the fetch simply fails with an
+  authorization error.
+- **Enumerating on the main actor.** It blocks the UI; use
+  `Task.detached { ... }.value` or another background context.
+- **Strict-concurrency errors about `CNContact` crossing actors.** Use
+  `@preconcurrency import Contacts`, or map contacts into small `Sendable`
+  view models before they leave the background task.
+
+## Review checklist
+
+- [ ] `NSContactsUsageDescription` present
+- [ ] `requestAccess(for: .contacts)` happens before any fetch or save
+- [ ] `.limited` handled as usable, with its narrower scope in mind
+- [ ] `ContactAccessButton` or `contactAccessPicker` offered to grow limited access
+- [ ] Denial handled with a path to Settings
+- [ ] Only the needed keys fetched
+- [ ] Names formatted with `descriptorForRequiredKeys(for:)` keys
+- [ ] `mutableCopy()` taken before any change
+- [ ] Every create, update and delete goes through `CNSaveRequest`
+- [ ] Heavy fetches run off the main actor
+- [ ] `CNContactStoreDidChange` observed
+- [ ] Picker used whenever full access is not needed
+- [ ] Picker predicates set before presentation
+- [ ] One `CNContactStore` shared by the whole app
 
 ## References
 
-- Extended patterns (multi-select picker, vCard export, search optimization): [references/contacts-patterns.md](references/contacts-patterns.md)
-- [Contacts framework](https://sosumi.ai/documentation/contacts)
-- [CNContactStore](https://sosumi.ai/documentation/contacts/cncontactstore)
-- [CNContactFetchRequest](https://sosumi.ai/documentation/contacts/cncontactfetchrequest)
-- [CNSaveRequest](https://sosumi.ai/documentation/contacts/cnsaverequest)
-- [CNMutableContact](https://sosumi.ai/documentation/contacts/cnmutablecontact)
-- [CNContactPickerViewController](https://sosumi.ai/documentation/contactsui/cncontactpickerviewcontroller)
-- [CNContactPickerDelegate](https://sosumi.ai/documentation/contactsui/cncontactpickerdelegate)
-- [Accessing the contact store](https://sosumi.ai/documentation/contacts/accessing-the-contact-store)
-- [NSContactsUsageDescription](https://sosumi.ai/documentation/bundleresources/information-property-list/nscontactsusagedescription)
-- [ContactAccessButton](https://sosumi.ai/documentation/contactsui/contactaccessbutton)
-- [contactAccessPicker(isPresented:completionHandler:)](https://sosumi.ai/documentation/swiftui/view/contactaccesspicker(ispresented:completionhandler:))
-- [Contact Keys](https://sosumi.ai/documentation/contacts/contact-keys)
+- [contacts patterns](references/contacts-patterns.md): observable manager and list with limited access, multi-select and email pickers, predicates, vCard, groups, change-notification limits
+- https://developer.apple.com/documentation/contacts
+- https://developer.apple.com/documentation/contacts/cncontactstore
+- https://developer.apple.com/documentation/contacts/cncontactfetchrequest
+- https://developer.apple.com/documentation/contacts/cnsaverequest
+- https://developer.apple.com/documentation/contacts/cnmutablecontact
+- https://developer.apple.com/documentation/contacts/contact-keys
+- https://developer.apple.com/documentation/contactsui/cncontactpickerviewcontroller
+- https://developer.apple.com/documentation/contactsui/cncontactpickerdelegate
+- https://developer.apple.com/documentation/contactsui/contactaccessbutton
+- https://developer.apple.com/documentation/bundleresources/information-property-list/nscontactsusagedescription
+- Apple article "Accessing the contact store" and the `contactAccessPicker(isPresented:completionHandler:)` modifier page in the ContactsUI documentation