@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

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

@@ -1,497 +1,379 @@
 ---
 name: permissionkit
-description: "Create child communication safety experiences using PermissionKit to request parental permission for children. Use when building apps that involve child-to-contact communication, need to check communication limits, request parent/guardian approval, or handle permission responses for minors."
+description: "PermissionKit parental approval for minors: CommunicationLimits handle checks, PermissionQuestion, AskCenter requests and responses, PermissionButton, AskError, pending or expired requests. Use when building child communication safety, a child asking to allow a contact, or handling approvals."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
 # PermissionKit
 
-> **Note:** PermissionKit APIs span multiple 26.x releases. Verify signatures
-> and availability against the current Xcode 26 SDK before shipping.
-
-Request permission from a parent or guardian to modify a child's communication
-rules. PermissionKit creates communication safety experiences that let children
-ask for exceptions to communication limits set by their parents. Targets
-Swift 6.3 / iOS 26+.
-
-PermissionKit communication experiences are available only through iMessage.
-Use it for parent/guardian approval flows, not as a general in-app contact
-permission, moderation, or chat-safety framework.
-
-## Contents
-
-- [Setup](#setup)
-- [Core Concepts](#core-concepts)
-- [Checking Communication Limits](#checking-communication-limits)
-- [Creating Permission Questions](#creating-permission-questions)
-- [Requesting Permission with AskCenter](#requesting-permission-with-askcenter)
-- [SwiftUI Integration with PermissionButton](#swiftui-integration-with-permissionbutton)
-- [Handling Responses](#handling-responses)
-- [Significant App Update Topic](#significant-app-update-topic)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
-
-## Setup
+PermissionKit lets a child ask a parent or guardian to change the child's
+communication rules for your app. The typical case: a parent has set
+communication limits, the child wants to talk to someone new, and your app
+turns that wish into a question the parent can approve or decline. The same
+machinery also covers asking a parent to approve a significant app update.
+
+What it is not:
+
+- It is not a way to ask for in-app contact permission in general, and it is
+  not a moderation or chat-safety framework. Use it only when the answer has
+  to come from a parent or guardian.
+- The request travels through iMessage and nothing else. Your own chat, DM or
+  notification channel cannot carry it.
+- It does not tell you what counts legally as a significant update in a given
+  country. That call belongs to the developer, with qualified legal counsel.
+
+Examples use Swift 6.3 against the iOS 26 SDK family. The API surface grew
+across three point releases, so check every signature and `@available` line
+against the Xcode 26 SDK you ship with before relying on it.
+
+## Setup and availability
+
+Add `@preconcurrency import PermissionKit`. The SwiftUI and UIKit/AppKit
+pieces (`PermissionButton`, `AskCenter.ask(_:in:)`) come in through
+cross-import overlays, so importing SwiftUI or UIKit next to PermissionKit is
+enough. The framework's types carry no `Sendable` annotations, so under Swift 6
+a plain import turns every `ask(_:in:)` call from the main actor into a
+"sending 'question' risks causing data races" error; `@preconcurrency` is what
+lets the examples below compile.
+
+Do not add made-up entitlement keys for PermissionKit. If a signing
+requirement exists, it will be in Apple's documentation and in the Xcode
+capabilities list; confirm it there first.
+
+When you review code or write guidance, name the exact tier instead of saying
+"iOS 26+". Platforms for every tier: iOS, iPadOS, Mac Catalyst, macOS and
+visionOS.
+
+| Tier | What becomes available |
+|---|---|
+| 26.0 | `CommunicationTopic`, `CommunicationHandle`, `PermissionQuestion`, `PermissionResponse`, `PermissionChoice`, `CommunicationLimits` |
+| 26.1 | `AskError` |
+| 26.2 | `AskCenter`, `AskCenter.ask(_:in:)`, `AskCenter.responses(for:)`, `PermissionButton`, `SignificantAppUpdateTopic` (and the `AskError.notAvailable` case) |
 
-Import `PermissionKit`. Do not invent PermissionKit entitlement keys; verify
-current Apple documentation and Xcode capabilities before adding signing
-requirements.
+Gate the 26.2 path explicitly:
 
 ```swift
-import PermissionKit
+if #available(iOS 26.2, macOS 26.2, visionOS 26.2, *) {
+    try await AskCenter.shared.ask(question, in: hostController)
+} else {
+    showUpdateRequiredNotice()
+}
 ```
 
-**Platform availability:**
-
-When reviewing or correcting code, state these exact tiers instead of collapsing
-PermissionKit to "iOS 26+":
-
-- Core topic, handle, question, response, choice, and `CommunicationLimits`
-  APIs: iOS 26.0+, iPadOS 26.0+, Mac Catalyst 26.0+, macOS 26.0+,
-  visionOS 26.0+.
-- `AskError`: iOS 26.1+, iPadOS 26.1+, Mac Catalyst 26.1+, macOS 26.1+,
-  visionOS 26.1+.
-- `AskCenter`, `AskCenter.ask(_:in:)`, `AskCenter.responses(for:)`,
-  `PermissionButton`, and `SignificantAppUpdateTopic`: iOS/iPadOS/
-  Mac Catalyst/macOS/visionOS 26.2+.
-
-## Core Concepts
-
-PermissionKit manages a flow where:
+## How a request flows
 
-1. A child encounters a communication limit in your app
-2. Your app creates a `PermissionQuestion` describing the request
-3. The system presents the question to the child for them to send to their parent
-4. The parent reviews and approves or denies the request
-5. Your app receives a `PermissionResponse` with the parent's decision
+1. Inside your app, the child runs into a communication limit (for example,
+   tries to message a player they have not been allowed to contact).
+2. Your app builds a `PermissionQuestion`.
+3. The system shows the question to the child, who can send it to a parent.
+4. The parent approves or declines.
+5. Your app later receives a `PermissionResponse` carrying that decision.
 
-### Key Types
+Types involved:
 
 | Type | Role |
 |---|---|
-| `AskCenter` | Singleton that manages permission requests and responses |
-| `PermissionQuestion` | Describes the permission being requested |
-| `PermissionResponse` | The parent's decision (approval or denial) |
-| `PermissionChoice` | The specific answer (approve/decline) |
-| `PermissionButton` | SwiftUI button that triggers the permission flow |
-| `CommunicationTopic` | Topic for communication-related permission requests |
-| `CommunicationHandle` | A phone number, email, or custom identifier |
-| `CommunicationLimits` | Checks which communication handles are known to the system |
-| `SignificantAppUpdateTopic` | Topic for significant app update permission requests |
-
-## Checking Communication Limits
-
-Use `CommunicationLimits.current` to check whether the system already knows a
-communication handle for your app. This is not an "are communication limits
-enabled?" probe. If limits are not enabled, `AskCenter.shared.ask(_:in:)`
-throws `AskError.communicationLimitsNotEnabled`; handle that path when asking.
-
-`knownHandles(in:)` also requires the calling app to have a non-nil, nonempty
-bundle identifier. Corrected code should guard `Bundle.main.bundleIdentifier`
-before calling it.
+| `AskCenter` | Shared object (`AskCenter.shared`) that sends questions and delivers answers |
+| `PermissionQuestion<Topic>` | What is being asked; has a `UUID` `id` |
+| `PermissionResponse<Topic>` | The parent's decision, with `question` and `choice` |
+| `PermissionChoice` | The concrete answer: approve or decline |
+| `PermissionButton` | SwiftUI control that starts the ask flow when tapped |
+| `CommunicationTopic` | Topic for communication requests |
+| `CommunicationHandle` | Phone number, email address or custom identifier of a contact |
+| `CommunicationLimits` | Tells you which handles the system already knows for your app |
+| `SignificantAppUpdateTopic` | Topic for approving a significant app update |
+
+## Known handles are not a limits check
+
+`CommunicationLimits.current` answers one narrow question: does the system
+already know this handle for my app? It does not tell you whether the parent
+has turned communication limits on. The only reliable signal for "limits are
+off" is `AskError.communicationLimitsNotEnabled`, thrown by
+`AskCenter.shared.ask(_:in:)`, so that path always needs handling.
+
+`knownHandles(in:)` needs a bundle identifier that is present and not empty.
+Guard `Bundle.main.bundleIdentifier` before you call it.
 
 ```swift
-import PermissionKit
+@preconcurrency import PermissionKit
 
-func needsPermissionPrompt(for handle: CommunicationHandle) async -> Bool {
-    let limits = CommunicationLimits.current
-    let isKnown = await limits.isKnownHandle(handle)
-    return !isKnown
+func unknownPlayers(_ ids: [String]) async -> Set<CommunicationHandle> {
+    guard let bundleID = Bundle.main.bundleIdentifier, !bundleID.isEmpty else {
+        return []
+    }
+    let handles = Set(ids.map { CommunicationHandle(value: $0, kind: .custom) })
+    let known = await CommunicationLimits.current.knownHandles(in: handles)
+    return handles.subtracting(known)
 }
 
-// Check multiple handles at once.
-func filterKnownHandles(_ handles: Set<CommunicationHandle>) async -> Set<CommunicationHandle> {
-    guard Bundle.main.bundleIdentifier?.isEmpty == false else { return [] }
-
-    let limits = CommunicationLimits.current
-    return await limits.knownHandles(in: handles)
+func isAlreadyKnown(email: String) async -> Bool {
+    let handle = CommunicationHandle(value: email, kind: .emailAddress)
+    return await CommunicationLimits.current.isKnownHandle(handle)
 }
 ```
 
-### Creating Communication Handles
+- `isKnownHandle(_:)` is async and returns `Bool` for one handle.
+- `knownHandles(in:)` takes a `Set<CommunicationHandle>` and returns the
+  subset the system knows.
+- `CommunicationHandle(value:kind:)` kinds: `.phoneNumber`, `.emailAddress`,
+  `.custom` (your own account or player id). Pick the kind that matches the
+  value.
 
-```swift
-let phoneHandle = CommunicationHandle(
-    value: "+1234567890",
-    kind: .phoneNumber
-)
+## Building a question
 
-let emailHandle = CommunicationHandle(
-    value: "friend@example.com",
-    kind: .emailAddress
-)
+Quick forms, when a handle is all you have:
 
-let customHandle = CommunicationHandle(
-    value: "user123",
-    kind: .custom
+```swift
+let single = PermissionQuestion<CommunicationTopic>(
+    handle: CommunicationHandle(value: "+15550100", kind: .phoneNumber)
 )
+let group = PermissionQuestion<CommunicationTopic>(handles: [
+    CommunicationHandle(value: "coach-17", kind: .custom),
+    CommunicationHandle(value: "coach-18", kind: .custom),
+])
 ```
 
-## Creating Permission Questions
-
-Build a `PermissionQuestion` with the contact information and communication
-action type.
+A richer prompt shows the parent a name and, optionally, an avatar
+(`CGImage`). Wrap each contact in `CommunicationTopic.PersonInformation`,
+list the actions you actually support, then build the question from the
+topic:
 
 ```swift
-// Question for a single contact
-let handle = CommunicationHandle(value: "+1234567890", kind: .phoneNumber)
-let question = PermissionQuestion<CommunicationTopic>(handle: handle)
-
-// Question for multiple contacts
-let handles = [
-    CommunicationHandle(value: "+1234567890", kind: .phoneNumber),
-    CommunicationHandle(value: "friend@example.com", kind: .emailAddress)
-]
-let multiQuestion = PermissionQuestion<CommunicationTopic>(handles: handles)
-```
-
-### Using CommunicationTopic with Person Information
+var name = PersonNameComponents()
+name.givenName = "Rosa"
+name.familyName = "Lindqvist"
 
-Provide display names and avatars for a richer permission prompt.
-
-```swift
-let personInfo = CommunicationTopic.PersonInformation(
-    handle: CommunicationHandle(value: "+1234567890", kind: .phoneNumber),
-    nameComponents: {
-        var name = PersonNameComponents()
-        name.givenName = "Alex"
-        name.familyName = "Smith"
-        return name
-    }(),
+let rosa = CommunicationTopic.PersonInformation(
+    handle: CommunicationHandle(value: "player-4410", kind: .custom),
+    nameComponents: name,
     avatarImage: nil
 )
-
-let topic = CommunicationTopic(
-    personInformation: [personInfo],
-    actions: [.message, .audioCall]
-)
-
+let topic = CommunicationTopic(personInformation: [rosa], actions: [.chat, .friend])
 let question = PermissionQuestion<CommunicationTopic>(communicationTopic: topic)
 ```
 
-### Communication Actions
+`CommunicationTopic.Action` values:
 
-| Action | Description |
+| Action | Meaning |
 |---|---|
 | `.message` | Text messaging |
 | `.audioCall` | Voice call |
 | `.videoCall` | Video call |
-| `.call` | Generic call |
-| `.chat` | Chat communication |
-| `.follow` | Follow a user |
-| `.beFollowed` | Allow being followed |
+| `.call` | A call of unspecified type |
+| `.chat` | Chat |
+| `.follow` | Follow someone |
+| `.beFollowed` | Let someone follow the child |
 | `.friend` | Friend request |
 | `.connect` | Connection request |
-| `.communicate` | Generic communication |
+| `.communicate` | Communication in general |
 
-## Requesting Permission with AskCenter
+Only list actions your app really offers; the parent is approving exactly
+those.
 
-Use `AskCenter.shared` to request that the child send the permission question
-to their parent or guardian. The async `ask` call starts the send flow; parent
-decisions arrive later through `responses(for:)`. If the child cancels the send
-flow, the system does not deliver a `PermissionResponse` for that question.
+## Asking through AskCenter
 
-```swift
-import PermissionKit
+`AskCenter.shared.ask(_:in:)` is `async throws`. It presents the system flow
+in which the child sends the question; it does not return the parent's
+answer. Decisions arrive later on `responses(for:)`. If the child backs out of
+the send sheet, no `PermissionResponse` ever arrives, so a pending request
+needs its own expiry or retry.
 
-func requestPermission(
-    for question: PermissionQuestion<CommunicationTopic>,
-    in viewController: UIViewController
-) async {
+```swift
+@available(iOS 26.2, *)
+@MainActor
+func requestContact(_ question: PermissionQuestion<CommunicationTopic>,
+                    from host: UIViewController) async {
     do {
-        try await AskCenter.shared.ask(question, in: viewController)
-        // Question send flow was started; wait for responses(for:) separately.
+        try await AskCenter.shared.ask(question, in: host)
+        pending.markPending(question.id)
     } catch let error as AskError {
         switch error {
         case .communicationLimitsNotEnabled:
-            // Communication limits not active -- continue with normal app flow.
-            break
+            unlockChat()                      // no limits: carry on normally
         case .contactSyncNotSetup:
-            // Contact sync not configured
-            break
+            promptForContactSync()
         case .invalidQuestion:
-            // Question is malformed
-            break
+            reportBrokenQuestion()            // e.g. no handles at all
         case .notAvailable:
-            // PermissionKit not available on this device
-            break
+            explainUnavailableOnDevice()
         case .systemError(let underlying):
-            print("System error: \(underlying)")
+            showFailure(underlying.localizedDescription)
         case .unknown:
-            break
+            showRetryLater()
         @unknown default:
-            break
+            showRetryLater()
         }
+    } catch {
+        showFailure(error.localizedDescription)
     }
 }
 ```
 
-## SwiftUI Integration with PermissionButton
+In the 26.2 SDK `.systemError` is deprecated because the underlying error is
+now thrown directly; keep the generic `catch` for that reason.
 
-`PermissionButton` is a SwiftUI view that triggers the permission flow when
-tapped. It uses the same response model as `AskCenter`: observe responses and
-model a pending/canceled state instead of assuming every tap produces a parent
-decision.
+## PermissionButton in SwiftUI
 
-```swift
-import SwiftUI
-import PermissionKit
+`PermissionButton(question:label:)` starts the same flow when tapped:
 
-struct ContactPermissionView: View {
-    let handle = CommunicationHandle(value: "+1234567890", kind: .phoneNumber)
-
-    var body: some View {
-        let question = PermissionQuestion<CommunicationTopic>(handle: handle)
-
-        PermissionButton(question: question) {
-            Label("Ask to Message", systemImage: "message")
-        }
-    }
+```swift
+PermissionButton(question: question) {
+    Label("Ask to play with Rosa", systemImage: "person.badge.plus")
 }
 ```
 
-For richer SwiftUI flows, custom topics, and long-lived managers, read
-[references/permissionkit-patterns.md](references/permissionkit-patterns.md).
+It uses the same response model as `AskCenter`. Keep observing
+`responses(for:)`, and keep pending and cancelled states in your model,
+because a tap does not guarantee that any decision comes back. Full screen
+examples are in the
+[patterns reference](references/permissionkit-patterns.md#swiftui-full-flow).
 
-## Handling Responses
+## Handling responses
 
-Listen for permission responses asynchronously. Track pending questions by
-`question.id`, and give the UI a retry or expiration path because a child can
-cancel the iMessage send flow without producing a response.
-When combining known-handle checks with response handling, carry forward the
-bundle-identifier guard from `knownHandles(in:)`.
+Track each question by `question.id` (a `UUID`). Since a cancelled send
+produces nothing, give every pending entry a way out: a retry, an expiry, or
+both. When a flow combines known-handle checks with responses, keep the
+bundle-identifier guard from the section above.
 
 ```swift
-enum PermissionRequestState {
-    case pending, approved, denied, expired
-}
+enum RequestState { case pending, approved, denied, expired }
 
-var requestStates: [UUID: PermissionRequestState] = [:]
+@MainActor @Observable
+final class ContactRequests {
+    private(set) var states: [UUID: RequestState] = [:]
 
-func expireIfStillPending(_ id: UUID) {
-    guard requestStates[id] == .pending else { return }
-    requestStates[id] = .expired
-    // Re-enable asking or show retry/canceled UI.
-}
+    func markPending(_ id: UUID) { states[id] = .pending }
 
-func observeResponses() async {
-    let responses = AskCenter.shared.responses(for: CommunicationTopic.self)
-
-    for await response in responses {
-        let choice = response.choice
-        let question = response.question
-
-        switch choice.answer {
-        case .approval:
-            // Parent approved -- enable communication
-            requestStates[question.id] = .approved
-            print("Approved for topic: \(question.topic)")
-        case .denial:
-            // Parent denied -- keep restriction
-            requestStates[question.id] = .denied
-            print("Denied")
-        @unknown default:
-            break
-        }
+    func expire(_ id: UUID) {
+        guard states[id] == .pending else { return }
+        states[id] = .expired              // lets the child ask again
     }
-}
-```
-
-### PermissionChoice Properties
-
-```swift
-let choice: PermissionChoice = response.choice
-print("Answer: \(choice.answer)")  // .approval or .denial
-print("Choice ID: \(choice.id)")
-print("Title: \(choice.title)")
-
-// Convenience statics
-let approved = PermissionChoice.approve
-let declined = PermissionChoice.decline
-```
-
-## Significant App Update Topic
-
-Request permission for significant app updates that require parental approval.
-Your app determines what counts as significant based on applicable regulations
-and should consult qualified legal counsel for compliance interpretation.
-Use concise, understandable descriptions that state the concrete change parents
-are approving.
-
-```swift
-let updateTopic = SignificantAppUpdateTopic(
-    description: "This update adds multiplayer chat features"
-)
 
-let question = PermissionQuestion<SignificantAppUpdateTopic>(
-    significantAppUpdateTopic: updateTopic
-)
-
-// Present the question
-try await AskCenter.shared.ask(question, in: viewController)
-requestStates[question.id] = .pending
-scheduleExpiration(for: question.id)
-
-// Listen for responses
-for await response in AskCenter.shared.responses(for: SignificantAppUpdateTopic.self) {
-    switch response.choice.answer {
-    case .approval:
-        // Proceed with update
-        requestStates[response.question.id] = .approved
-    case .denial:
-        // Skip update
-        requestStates[response.question.id] = .denied
-    @unknown default:
-        break
+    @available(iOS 26.2, *)
+    func listen() async {
+        for await response in AskCenter.shared.responses(for: CommunicationTopic.self) {
+            let id = response.question.id
+            switch response.choice.answer {
+            case .approval: states[id] = .approved
+            case .denial: states[id] = .denied
+            @unknown default: states[id] = .denied
+            }
+            let people = response.question.topic.personInformation
+            refreshContacts(people.map(\.handle))
+        }
     }
-}
-
-// If no response arrives before your pending window expires, keep the update
-// blocked or offer a retry. Child cancellation produces no denial response.
-```
-
-## Common Mistakes
-
-### DON'T: Treat known-handle checks as enabled-limits checks
 
-`isKnownHandle(_:)` and `knownHandles(in:)` only classify handles. They do not
-replace handling `.communicationLimitsNotEnabled` from `ask(_:in:)`.
-
-```swift
-// WRONG: Assuming a handle lookup proves active limits
-let isKnown = await CommunicationLimits.current.isKnownHandle(handle)
-if !isKnown {
-    try await AskCenter.shared.ask(question, in: viewController)
-}
-
-// CORRECT: Handle the case where limits are not enabled
-do {
-    try await AskCenter.shared.ask(question, in: viewController)
-} catch AskError.communicationLimitsNotEnabled {
-    // Communication limits not active -- continue with normal app flow.
-    allowCommunication()
-} catch {
-    handleError(error)
+    private func refreshContacts(_ handles: [CommunicationHandle]) {}
 }
 ```
 
-### DON'T: Ignore AskError cases
+- `responses(for:)` is an async sequence of `PermissionResponse<Topic>`; each
+  element has `.question` and `.choice`.
+- `response.question.topic` gives back the topic you asked about.
+- `choice.answer` is `.approval` (allow the communication) or `.denial` (keep
+  the restriction).
+- `PermissionChoice` also exposes `id` and `title`, and the statics
+  `PermissionChoice.approve` and `PermissionChoice.decline`.
 
-Each error case requires different handling.
+## Significant app updates
 
-```swift
-// WRONG: Catch-all with no user feedback
-do {
-    try await AskCenter.shared.ask(question, in: viewController)
-} catch {
-    print(error)
-}
-
-// CORRECT: Handle each case
-do {
-    try await AskCenter.shared.ask(question, in: viewController)
-} catch let error as AskError {
-    switch error {
-    case .communicationLimitsNotEnabled:
-        allowCommunication()
-    case .contactSyncNotSetup:
-        showContactSyncPrompt()
-    case .invalidQuestion:
-        showInvalidQuestionAlert()
-    case .notAvailable:
-        showUnavailableMessage()
-    case .systemError(let underlying):
-        showSystemError(underlying)
-    case .unknown:
-        showGenericError()
-    @unknown default:
-        break
-    }
-}
-```
-
-### DON'T: Create questions with empty handles
-
-A question with no handles or person information is invalid.
+`SignificantAppUpdateTopic` asks a parent to approve a significant change to
+the app. You decide what is significant according to the regulations that
+apply to you; get interpretation from qualified legal counsel, not from this
+skill. The description should be short and name the concrete change the
+parent is agreeing to, for example "Adds voice chat with players outside
+your child's friend list", not "We updated our app".
 
 ```swift
-// WRONG: Empty handles array
-let question = PermissionQuestion<CommunicationTopic>(handles: [])  // Invalid
-
-// CORRECT: Provide at least one handle
-let handle = CommunicationHandle(value: "+1234567890", kind: .phoneNumber)
-let question = PermissionQuestion<CommunicationTopic>(handle: handle)
-```
-
-### DON'T: Forget to observe responses and pending states
-
-Presenting a question without listening for the response means you never know
-if the parent approved. A child can also cancel the send flow, so do not wait
-forever for a response to every question.
-
-```swift
-// WRONG: Fire and forget
-try await AskCenter.shared.ask(question, in: viewController)
-
-// CORRECT: Observe responses
-Task {
-    for await response in AskCenter.shared.responses(for: CommunicationTopic.self) {
-        handleResponse(response)
-    }
-}
-try await AskCenter.shared.ask(question, in: viewController)
-```
-
-### DON'T: Use deprecated CommunicationLimitsButton
-
-Use `PermissionButton` instead of the deprecated `CommunicationLimitsButton`.
-
-```swift
-// WRONG: Deprecated
-CommunicationLimitsButton(question: question) {
-    Text("Ask Permission")
+@available(iOS 26.2, *)
+@MainActor
+func askAboutVoiceChat(from host: UIViewController) async throws {
+    let topic = SignificantAppUpdateTopic(
+        description: "Adds voice chat with players outside your child's friend list."
+    )
+    let question = PermissionQuestion<SignificantAppUpdateTopic>(significantAppUpdateTopic: topic)
+    try await AskCenter.shared.ask(question, in: host)
+    updateGate.markPending(question.id)
+    updateGate.scheduleExpiry(for: question.id, after: .seconds(72 * 3600))
 }
 
-// CORRECT: Use PermissionButton
-PermissionButton(question: question) {
-    Text("Ask Permission")
+@available(iOS 26.2, *)
+@MainActor
+func watchUpdateDecisions() async {
+    for await response in AskCenter.shared.responses(for: SignificantAppUpdateTopic.self) {
+        switch response.choice.answer {
+        case .approval: updateGate.enableVoiceChat()
+        case .denial: updateGate.keepVoiceChatOff()
+        @unknown default: updateGate.keepVoiceChatOff()
+        }
+    }
 }
 ```
 
-## Review Checklist
-
-- [ ] iMessage-only routing understood before choosing PermissionKit
-- [ ] Corrected guidance states exact availability tiers: core communication
-  types/limits 26.0+, `AskError` 26.1+, and `AskCenter`/`PermissionButton`/
-  responses/significant-update topics 26.2+
-- [ ] `AskError.communicationLimitsNotEnabled` handled to allow fallback
-- [ ] `AskError` cases handled individually with appropriate user feedback
-- [ ] `CommunicationHandle` created with correct `Kind` (phone, email, custom)
-- [ ] Known-handle examples guard a non-nil, nonempty bundle identifier before
-  `knownHandles(in:)`
-- [ ] Known-handle checks are not treated as active-limits checks
-- [ ] `PermissionQuestion` includes at least one handle or person information
-- [ ] `AskCenter.shared.responses(for:)` observed to receive parent decisions
-- [ ] `PermissionButton` used instead of deprecated `CommunicationLimitsButton`
-- [ ] Person information includes name components for a clear permission prompt
-- [ ] Communication actions match the app's actual communication capabilities
-- [ ] Pending/canceled/expired question states handled when no response arrives
-- [ ] Response handling updates UI on the main actor
-- [ ] Error states provide clear guidance to the user
+If the pending window closes with no answer, keep the update blocked or offer
+another request. A child cancelling the send flow is not a denial; it simply
+produces no response.
+
+## Common mistakes
+
+- Reading `isKnownHandle(_:)` or `knownHandles(in:)` as "limits are on".
+  Those calls only classify handles. Still catch the limits-off case:
+
+  ```swift
+  do { try await AskCenter.shared.ask(question, in: host) }
+  catch AskError.communicationLimitsNotEnabled { unlockChat() }
+  ```
+
+- One catch-all that shows nothing. Give each `AskError` case its own
+  outcome: allow communication, prompt for contact sync, flag an invalid
+  question, explain that the device cannot do it, surface a system error, or
+  show a generic retry message.
+- Empty handles. `PermissionQuestion(handles: [])` is an invalid question.
+  Provide at least one handle or one `PersonInformation`.
+- Fire-and-forget asking. Start the task that observes `responses(for:)`
+  before or next to the `ask` call, and never wait forever: the child can
+  cancel.
+- Using `CommunicationLimitsButton`, or the `CommunicationLimits` ask and
+  `updates` APIs. They are deprecated; use `PermissionButton`,
+  `AskCenter.ask(_:in:)` and `AskCenter.responses(for:)`.
+
+## Review checklist
+
+- [ ] The team knows the request goes through iMessage only before picking
+      PermissionKit.
+- [ ] Availability is stated per tier: 26.0 core types and limits, 26.1
+      `AskError`, 26.2 `AskCenter`, `PermissionButton`, responses and
+      `SignificantAppUpdateTopic`.
+- [ ] `.communicationLimitsNotEnabled` falls back to normal communication;
+      every other `AskError` case has its own user feedback.
+- [ ] Each `CommunicationHandle` uses the right `Kind`.
+- [ ] Known-handle code guards a nonempty bundle identifier and is not used
+      as a limits-enabled check.
+- [ ] Every question has at least one handle or person information, and
+      person information carries name components.
+- [ ] `responses(for:)` is observed; `PermissionButton` is used, not the
+      deprecated button.
+- [ ] Listed actions match what the app really lets people do.
+- [ ] Pending, cancelled and expired requests are handled when no answer
+      arrives.
+- [ ] Response handling updates UI on the main actor and errors tell the user
+      what to do next.
 
 ## References
 
-- Extended patterns (response handling, multi-topic, UIKit): [references/permissionkit-patterns.md](references/permissionkit-patterns.md)
-- [PermissionKit framework](https://sosumi.ai/documentation/permissionkit)
-- [AskCenter](https://sosumi.ai/documentation/permissionkit/askcenter)
-- [PermissionQuestion](https://sosumi.ai/documentation/permissionkit/permissionquestion)
-- [PermissionButton](https://sosumi.ai/documentation/permissionkit/permissionbutton)
-- [PermissionResponse](https://sosumi.ai/documentation/permissionkit/permissionresponse)
-- [CommunicationTopic](https://sosumi.ai/documentation/permissionkit/communicationtopic)
-- [CommunicationHandle](https://sosumi.ai/documentation/permissionkit/communicationhandle)
-- [CommunicationLimits](https://sosumi.ai/documentation/permissionkit/communicationlimits)
-- [SignificantAppUpdateTopic](https://sosumi.ai/documentation/permissionkit/significantappupdatetopic)
-- [AskError](https://sosumi.ai/documentation/permissionkit/askerror)
-- [Creating a communication experience](https://sosumi.ai/documentation/permissionkit/creating-a-communication-experience)
+- [Patterns reference](references/permissionkit-patterns.md): UIKit
+  controller, response manager, multi-contact questions, limits-check view
+  model, SwiftUI full flow, macOS, error recovery.
+- Apple documentation:
+  - https://developer.apple.com/documentation/permissionkit
+  - https://developer.apple.com/documentation/permissionkit/askcenter
+  - https://developer.apple.com/documentation/permissionkit/permissionquestion
+  - https://developer.apple.com/documentation/permissionkit/permissionbutton
+  - https://developer.apple.com/documentation/permissionkit/permissionresponse
+  - https://developer.apple.com/documentation/permissionkit/communicationtopic
+  - https://developer.apple.com/documentation/permissionkit/communicationhandle
+  - https://developer.apple.com/documentation/permissionkit/communicationlimits
+  - https://developer.apple.com/documentation/permissionkit/significantappupdatetopic
+  - https://developer.apple.com/documentation/permissionkit/askerror
+  - https://developer.apple.com/documentation/permissionkit/creating-a-communication-experience