@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/homekit-matter/SKILL.md

@@ -1,392 +1,325 @@
 ---
 name: homekit-matter
-description: "Control smart-home accessories and commission Matter devices using HomeKit and MatterSupport. Use when managing homes/rooms/accessories, creating action sets or triggers, reading accessory characteristics, onboarding Matter devices, or building a third-party smart-home ecosystem app."
+description: "HomeKit and MatterSupport: managing homes, rooms, zones and accessories, reading characteristics, action sets and triggers, Matter commissioning, MatterSupport extensions. Use when controlling smart-home accessories, onboarding Matter devices or building a third-party ecosystem app."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
-# HomeKit
+# HomeKit and Matter
 
-Control home automation accessories and commission Matter devices. HomeKit manages
-the home/room/accessory model, action sets, and triggers. MatterSupport handles
-device commissioning into your ecosystem. Targets Swift 6.3 / iOS 26+.
-
-## Contents
-
-- [Setup](#setup)
-- [HomeKit Data Model](#homekit-data-model)
-- [Managing Accessories](#managing-accessories)
-- [Reading and Writing Characteristics](#reading-and-writing-characteristics)
-- [Action Sets and Triggers](#action-sets-and-triggers)
-- [Matter Commissioning](#matter-commissioning)
-- [MatterAddDeviceExtensionRequestHandler](#matteradddeviceextensionrequesthandler)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+Two frameworks split the smart-home job. HomeKit is the model of the user's
+house: homes, rooms, accessories, scenes (action sets) and automations
+(triggers). MatterSupport is the onboarding path that brings a Matter device
+into an ecosystem you run yourself. The code here assumes Swift 6.3 and an
+iOS 26 deployment target.
 
 ## Setup
 
-### HomeKit Configuration
+### HomeKit
 
-1. Enable the **HomeKit** capability in Xcode (Signing & Capabilities)
-2. Add `NSHomeKitUsageDescription` to Info.plist:
+1. Turn on the **HomeKit** capability in the target's Signing & Capabilities tab.
+2. Put an `NSHomeKitUsageDescription` string in Info.plist that explains
+   why the app reads and controls the user's home.
 
-```xml
-<key>NSHomeKitUsageDescription</key>
-<string>This app controls your smart home accessories.</string>
-```
+### MatterSupport
 
-### MatterSupport Configuration
+1. Create a **MatterSupport Extension** target. Its principal class must
+   subclass `MatterAddDeviceExtensionRequestHandler`.
+2. Declare three Bonjour types under `NSBonjourServices`: `_matter._tcp`,
+   `_matterc._udp`, plus `_matterd._udp`.
+3. The `com.apple.developer.matter.allow-setup-payload` entitlement is needed
+   only when the app
+   hands a setup payload to the request itself. Apps that let the system
+   scan the code do not need it.
 
-For Matter commissioning into your own ecosystem:
+### Availability and authorization
 
-1. Add a **MatterSupport Extension** target and set its principal class to a
-   `MatterAddDeviceExtensionRequestHandler` subclass
-2. Add `NSBonjourServices` entries for `_matter._tcp`, `_matterc._udp`, and
-   `_matterd._udp`
-3. Add `com.apple.developer.matter.allow-setup-payload` only if the caller
-   supplies a Matter setup payload programmatically
-
-### Availability Check
+HomeKit is available on iPhone, iPad, Mac Catalyst, Apple Watch, Apple TV
+and Apple Vision Pro. There is no explicit permission call: creating a home manager and
+setting its delegate starts the load, and the authorization result arrives on
+the delegate.
 
 ```swift
-import HomeKit
-
-let homeManager = HMHomeManager()
-
-// HomeKit is available on iPhone, iPad, Apple TV, Apple Watch,
-// Mac Catalyst, and Vision Pro.
-// Authorization is handled through the delegate:
-homeManager.delegate = self
+let manager = HMHomeManager()
+manager.delegate = houseModel   // callbacks report homes and authorization
 ```
 
-## HomeKit Data Model
+## The HomeKit object graph
 
-HomeKit organizes home automation in a hierarchy:
-
-```text
+```
 HMHomeManager
-  -> HMHome (one or more)
-       -> HMRoom (rooms in the home)
-            -> HMAccessory (devices in a room)
-                 -> HMService (functions: light, thermostat, etc.)
-                      -> HMCharacteristic (readable/writable values)
-       -> HMZone (groups of rooms)
-       -> HMActionSet (grouped actions)
-       -> HMTrigger (time or event-based triggers)
+ +- HMHome (one or more, one may be primary)
+     +- HMRoom -> HMAccessory -> HMService -> HMCharacteristic
+     +- HMZone        (named group of rooms, e.g. "Upstairs")
+     +- HMActionSet   (scene)
+     +- HMTrigger     (timer or event automation)
 ```
 
-### Initializing the Home Manager
+### Loading homes
 
-Create a single `HMHomeManager` and implement the delegate to know when
-data is loaded. HomeKit loads asynchronously -- do not access `homes` until
-the delegate fires.
+Keep exactly one `HMHomeManager` for the process. The database loads in the
+background, so `homes` is empty until the delegate says otherwise.
+`HMHomeManager.primaryHome` still exists but has been deprecated since
+iOS 16.1, so choose the current home in your own UI instead of relying on it.
 
 ```swift
 import HomeKit
 
-final class HomeStore: NSObject, HMHomeManagerDelegate {
-    let homeManager = HMHomeManager()
+final class HouseModel: NSObject, HMHomeManagerDelegate {
+    let manager = HMHomeManager()
+    private(set) var houses: [HMHome] = []
+    private(set) var mainHouse: HMHome?
+    private(set) var canControl = false
 
     override init() {
         super.init()
-        homeManager.delegate = self
+        manager.delegate = self
     }
 
     func homeManagerDidUpdateHomes(_ manager: HMHomeManager) {
-        // Safe to access manager.homes now
-        let homes = manager.homes
-        let primaryHome = manager.primaryHome
-        print("Loaded \(homes.count) homes")
+        houses = manager.homes
+        mainHouse = houses.first   // let the user pick when there are several
     }
 
-    func homeManager(
-        _ manager: HMHomeManager,
-        didUpdate status: HMHomeManagerAuthorizationStatus
-    ) {
-        if status.contains(.authorized) {
-            print("HomeKit access granted")
-        }
+    func homeManager(_ manager: HMHomeManager,
+                     didUpdate status: HMHomeManagerAuthorizationStatus) {
+        canControl = status.contains(.authorized)
     }
 }
 ```
 
-### Accessing Rooms
+### Rooms
 
 ```swift
-guard let home = homeManager.primaryHome else { return }
+let office = house.rooms.first { $0.name == "Office" }
+let unassigned = house.roomForEntireHome()   // default room for new accessories
+```
 
-let rooms = home.rooms
-let kitchen = rooms.first { $0.name == "Kitchen" }
+## Accessories
 
-// Room for accessories not assigned to a specific room
-let defaultRoom = home.roomForEntireHome()
-```
+### Which framework owns what
 
-## Managing Accessories
+| Task | Owner |
+|---|---|
+| Homes, rooms, services, characteristics, scenes, triggers, automations, HomeKit accessory setup UI, Matter onboarding | HomeKit / MatterSupport |
+| BLE or Wi-Fi discovery descriptors, the accessory picker and its authorization, `ASAccessorySession` events, accessory migration | AccessorySetupKit |
+| Talking to a Bluetooth accessory after it was picked (GATT) | CoreBluetooth |
+| Joining an accessory's temporary Wi-Fi setup network | NetworkExtension |
 
-### Discovering and Adding Accessories
+When a flow starts in AccessorySetupKit, say explicitly where it continues:
+CoreBluetooth for Bluetooth traffic, NetworkExtension for Wi-Fi joins. Neither
+of those is HomeKit automation.
 
-Use HomeKit and MatterSupport for home-model work: homes, rooms, `HMAccessory` services and characteristics, action sets, triggers and automations, HomeKit accessory setup UI, and Matter commissioning. If the same request asks about lower-level Bluetooth or Wi-Fi accessory discovery or authorization, name AccessorySetupKit as the boundary for discovery descriptors, picker authorization, `ASAccessorySession` events, and migration. After AccessorySetupKit setup, explicitly name both post-setup handoff targets: CoreBluetooth/GATT for Bluetooth accessories and NetworkExtension for Wi-Fi accessory network flows; neither handoff is HomeKit automation logic.
+### Adding accessories with the system sheet
+
+`HMHome.addAndSetupAccessories(completionHandler:)` presents the system
+discovery sheet, but it has been deprecated since iOS 15.4. On current
+releases drive the same sheet through `HMAccessorySetupManager`:
 
 ```swift
-// System UI for accessory discovery
-home.addAndSetupAccessories { error in
-    if let error {
-        print("Setup failed: \(error)")
-    }
+let setup = HMAccessorySetupManager()
+let request = HMAccessorySetupRequest()
+request.homeUniqueIdentifier = house.uniqueIdentifier
+setup.performAccessorySetup(using: request) { result, error in
+    if let error { report(error) }
 }
 ```
 
-### Listing Accessories and Services
+### Walking the graph
 
 ```swift
-for accessory in home.accessories {
-    print("\(accessory.name) in \(accessory.room?.name ?? "unassigned")")
-
-    for service in accessory.services {
-        print("  Service: \(service.serviceType)")
-
-        for characteristic in service.characteristics {
-            print("    \(characteristic.characteristicType): \(characteristic.value ?? "nil")")
+for device in house.accessories {
+    print(device.name, "in", device.room?.name ?? "no room")
+    for service in device.services {
+        print("  service", service.serviceType)
+        for trait in service.characteristics {
+            print("    ", trait.characteristicType, String(describing: trait.value))
         }
     }
 }
 ```
 
-### Moving an Accessory to a Room
+### Moving an accessory
 
 ```swift
-guard let accessory = home.accessories.first,
-      let bedroom = home.rooms.first(where: { $0.name == "Bedroom" }) else { return }
-
-home.assignAccessory(accessory, to: bedroom) { error in
-    if let error {
-        print("Failed to move accessory: \(error)")
-    }
+house.assignAccessory(fan, to: bedroom) { error in
+    if let error { report(error) }
 }
 ```
 
-## Reading and Writing Characteristics
-
-### Reading a Value
+## Characteristics
 
 ```swift
-let characteristic: HMCharacteristic = // obtained from a service
-
-characteristic.readValue { error in
+// Read the latest value from the device, then use the cached property.
+powerTrait.readValue { error in
     guard error == nil else { return }
-    if let value = characteristic.value as? Bool {
-        print("Power state: \(value)")
-    }
+    let isOn = powerTrait.value as? Bool ?? false
+    print("Fan running:", isOn)
 }
-```
 
-### Writing a Value
+// Write a new value.
+powerTrait.writeValue(false) { error in
+    if let error { report(error) }
+}
 
-```swift
-// Turn on a light
-characteristic.writeValue(true) { error in
-    if let error {
-        print("Write failed: \(error)")
-    }
+// Ask for push updates.
+powerTrait.enableNotification(true) { error in
+    if let error { report(error) }
 }
 ```
 
-### Observing Changes
+Each of these completion-handler methods also has an `async throws` form,
+for example `try await powerTrait.writeValue(false)`.
 
-Enable notifications for real-time updates:
+Pushed values land in `HMAccessoryDelegate`:
 
 ```swift
-characteristic.enableNotification(true) { error in
-    guard error == nil else { return }
+func accessory(_ accessory: HMAccessory,
+               service: HMService,
+               didUpdateValueFor characteristic: HMCharacteristic) {
+    refreshTile(for: characteristic)
 }
+```
 
-// In HMAccessoryDelegate:
-func accessory(
-    _ accessory: HMAccessory,
-    service: HMService,
-    didUpdateValueFor characteristic: HMCharacteristic
-) {
-    print("Updated: \(characteristic.value ?? "nil")")
-}
+Before writing a number, read `characteristic.metadata` and clamp to its
+range. A brightness write of 500 fails because the device accepts 0 to 100:
+
+```swift
+let requested = 500
+let ceiling = dimmer.metadata?.maximumValue?.intValue ?? 100
+let floor = dimmer.metadata?.minimumValue?.intValue ?? 0
+dimmer.writeValue(min(max(requested, floor), ceiling)) { _ in }
 ```
 
-## Action Sets and Triggers
+## Scenes and automations
 
-### Creating an Action Set
+### Building an action set
 
-An `HMActionSet` groups characteristic writes that execute together:
+An `HMActionSet` bundles several characteristic writes that fire together.
 
 ```swift
-home.addActionSet(withName: "Good Night") { actionSet, error in
-    guard let actionSet, error == nil else { return }
-
-    // Turn off living room light
-    let lightChar = livingRoomLight.powerCharacteristic
-    let action = HMCharacteristicWriteAction(
-        characteristic: lightChar,
-        targetValue: false as NSCopying
-    )
-    actionSet.addAction(action) { error in
-        guard error == nil else { return }
-        print("Action added to Good Night scene")
+house.addActionSet(withName: "Movie Time") { scene, error in
+    guard let scene else { return }
+    let dim = HMCharacteristicWriteAction(characteristic: lampLevel,
+                                          targetValue: 15 as NSCopying)
+    scene.addAction(dim) { error in
+        if let error { report(error) }
     }
 }
 ```
 
-### Executing an Action Set
+### Running it now
 
 ```swift
-home.executeActionSet(actionSet) { error in
-    if let error {
-        print("Execution failed: \(error)")
-    }
+house.executeActionSet(movieScene) { error in
+    if let error { report(error) }
 }
 ```
 
-### Creating a Timer Trigger
+### Timer trigger
+
+The fire date is the first occurrence; `recurrence` is an interval between
+firings. For "every day" pass `DateComponents(day: 1)`, never hour and minute.
 
 ```swift
-var timeOfDay = DateComponents()
-timeOfDay.hour = 22
-timeOfDay.minute = 30
-
-let firstFireDate = Calendar.current.nextDate(
-    after: Date(),
-    matching: timeOfDay,
-    matchingPolicy: .nextTime
-)!
-
-let trigger = HMTimerTrigger(
-    name: "Nightly",
-    fireDate: firstFireDate,
-    recurrence: DateComponents(day: 1)  // Repeat every day after firstFireDate
-)
-
-home.addTrigger(trigger) { error in
-    guard error == nil else { return }
+let morning = DateComponents(hour: 6, minute: 45)
+guard let firstRun = Calendar.current.nextDate(after: .now,
+                                               matching: morning,
+                                               matchingPolicy: .nextTime) else { return }
 
-    // Attach the action set to the trigger
-    trigger.addActionSet(goodNightActionSet) { error in
-        guard error == nil else { return }
+let wakeUp = HMTimerTrigger(name: "Wake Up",
+                            fireDate: firstRun,
+                            recurrence: DateComponents(day: 1))
 
-        trigger.enable(true) { error in
-            print("Trigger enabled: \(error == nil)")
-        }
+house.addTrigger(wakeUp) { error in
+    guard error == nil else { return }
+    wakeUp.addActionSet(sunriseScene) { error in
+        guard error == nil else { return }
+        wakeUp.enable(true) { _ in }
     }
 }
 ```
 
-### Creating an Event Trigger
+The order matters: add the trigger to the home, attach action sets, then enable.
+
+### Event trigger
 
 ```swift
-let motionDetected = HMCharacteristicEvent(
-    characteristic: motionSensorCharacteristic,
-    triggerValue: true as NSCopying
-)
-
-let eventTrigger = HMEventTrigger(
-    name: "Motion Lights",
-    events: [motionDetected],
-    predicate: nil
-)
-
-home.addTrigger(eventTrigger) { error in
-    // Add action sets as above
+let doorOpened = HMCharacteristicEvent(characteristic: contactState,
+                                       triggerValue: 1 as NSCopying)
+let arrival = HMEventTrigger(name: "Hallway On Entry",
+                             events: [doorOpened],
+                             predicate: nil)
+house.addTrigger(arrival) { error in
+    guard error == nil else { return }
+    arrival.addActionSet(hallwayScene) { _ in arrival.enable(true) { _ in } }
 }
 ```
 
-## Matter Commissioning
+## Matter onboarding
 
-Use `MatterAddDeviceRequest` to commission a Matter device into your ecosystem.
-This is separate from the `HMHome` home-automation model; it handles the
-Matter setup flow and calls into your MatterSupport extension.
-
-### Basic Commissioning
+`MatterAddDeviceRequest` runs the system pairing flow for a Matter device and
+calls into your MatterSupport extension so the device joins your fabric. It
+does not create anything in `HMHome`.
 
 ```swift
 import MatterSupport
 
-func addMatterDevice() async throws {
-    guard MatterAddDeviceRequest.isSupported else {
-        print("Matter not supported on this device")
-        return
-    }
-
-    let topology = MatterAddDeviceRequest.Topology(
-        ecosystemName: "My Smart Home",
-        homes: [
-            MatterAddDeviceRequest.Home(displayName: "Main House")
-        ]
-    )
+func pairNewDevice() async throws {
+    guard MatterAddDeviceRequest.isSupported else { return }
 
-    let request = MatterAddDeviceRequest(
-        topology: topology,
-        setupPayload: nil,
-        showing: .allDevices
+    let layout = MatterAddDeviceRequest.Topology(
+        ecosystemName: "Brightside",
+        homes: [MatterAddDeviceRequest.Home(displayName: "Lake Cabin")]
     )
-
-    // Presents system UI for device pairing
-    try await request.perform()
+    let request = MatterAddDeviceRequest(topology: layout,
+                                         setupPayload: nil,
+                                         showing: .allDevices)
+    try await request.perform()   // presents the pairing sheet
 }
 ```
 
-When providing a setup code directly, import Matter and pass an
-`MTRSetupPayload` as `setupPayload`; this is the case that requires the
-setup-payload entitlement.
+If the app already knows the setup code, import `Matter`, build an
+`MTRSetupPayload` and pass it as `setupPayload`. This is the only case that
+needs the setup-payload entitlement.
 
-### Filtering Devices
+### Narrowing the device list
 
 ```swift
-// Only show devices from a specific vendor
-let criteria = MatterAddDeviceRequest.DeviceCriteria.vendorID(0x1234)
-
-let request = MatterAddDeviceRequest(
-    topology: topology,
-    setupPayload: nil,
-    showing: criteria
-)
+let ours = MatterAddDeviceRequest.DeviceCriteria.vendorID(0xFFF1)
+let oursExceptHub = MatterAddDeviceRequest.DeviceCriteria.all([
+    .vendorID(0xFFF1),
+    .not(.productID(0x0042))
+])
+let eitherBrand = MatterAddDeviceRequest.DeviceCriteria.any([.vendorID(0xFFF1), .vendorID(0xFFF2)])
 ```
 
-Combine criteria with `.all([.vendorID(...), .not(.productID(...))])` or use
-`.any(...)` when any one criterion is enough.
-
-## MatterAddDeviceExtensionRequestHandler
+## The extension handler
 
-For full ecosystem support, create a MatterSupport Extension. The extension
-handles commissioning callbacks. Override the needed methods, but do not call
-`super` from those overrides.
+Subclass `MatterAddDeviceExtensionRequestHandler` in the extension and
+override the callbacks you need. Do not call `super` from the overrides.
 
 ```swift
 import MatterSupport
 
-final class MatterHandler: MatterAddDeviceExtensionRequestHandler {
-
+final class PairingHandler: MatterAddDeviceExtensionRequestHandler {
     override func validateDeviceCredential(
-        _ deviceCredential:
-            MatterAddDeviceExtensionRequestHandler.DeviceCredential
+        _ credential: MatterAddDeviceExtensionRequestHandler.DeviceCredential
     ) async throws {
-        // Validate the device attestation certificate
-        // Throw to reject the device
+        // Check attestation; throw to refuse the device.
     }
 
     override func rooms(
         in home: MatterAddDeviceRequest.Home?
     ) async -> [MatterAddDeviceRequest.Room] {
-        // Return rooms in the selected home
-        return [
-            MatterAddDeviceRequest.Room(displayName: "Living Room"),
-            MatterAddDeviceRequest.Room(displayName: "Kitchen")
-        ]
+        [.init(displayName: "Porch"), .init(displayName: "Garage")]
     }
 
     override func configureDevice(
         named name: String,
         in room: MatterAddDeviceRequest.Room?
     ) async {
-        // Save the device configuration to your backend
-        print("Configuring \(name) in \(room?.displayName ?? "no room")")
+        // Save the chosen name and room to your service.
     }
 
     override func commissionDevice(
@@ -394,107 +327,59 @@ final class MatterHandler: MatterAddDeviceExtensionRequestHandler {
         onboardingPayload: String,
         commissioningID: UUID
     ) async throws {
-        // Use the onboarding payload to commission the device
-        // into your fabric using the Matter framework
+        // Commission into your fabric with the Matter framework.
     }
 }
 ```
 
-## Common Mistakes
-
-### DON'T: Access homes before the delegate fires
-
-```swift
-// WRONG -- homes array is empty until delegate is called
-let manager = HMHomeManager()
-let homes = manager.homes  // Always empty here
-
-// CORRECT -- wait for delegate
-func homeManagerDidUpdateHomes(_ manager: HMHomeManager) {
-    let homes = manager.homes  // Now populated
-}
-```
-
-### DON'T: Confuse HomeKit setup with Matter commissioning
-
-```swift
-// WRONG -- using HomeKit accessory setup for a Matter ecosystem app
-home.addAndSetupAccessories { error in }
-
-// CORRECT -- use MatterAddDeviceRequest for Matter ecosystem commissioning
-let request = MatterAddDeviceRequest(
-    topology: topology,
-    setupPayload: nil,
-    showing: .allDevices
-)
-try await request.perform()
-```
-
-### DON'T: Forget required configuration
-
-Matter ecosystem commissioning needs the MatterSupport extension, principal
-handler class, and Matter Bonjour services. Add the setup-payload entitlement
-only when your app provides setup codes directly.
-
-### DON'T: Create multiple HMHomeManager instances
-
-```swift
-// WRONG -- each instance loads the full database independently
-class ScreenA { let manager = HMHomeManager() }
-class ScreenB { let manager = HMHomeManager() }
-
-// CORRECT -- single shared instance
-@Observable
-final class HomeStore {
-    static let shared = HomeStore()
-    let homeManager = HMHomeManager()
-}
-```
-
-### DON'T: Write characteristics without checking metadata
-
-```swift
-// WRONG -- writing a value outside the valid range
-characteristic.writeValue(500) { _ in }
-
-// CORRECT -- check metadata first
-if let metadata = characteristic.metadata,
-   let maxValue = metadata.maximumValue?.intValue {
-    let safeValue = min(brightness, maxValue)
-    characteristic.writeValue(safeValue) { _ in }
-}
-```
-
-## Review Checklist
-
-- [ ] HomeKit capability enabled in Xcode
-- [ ] `NSHomeKitUsageDescription` present in Info.plist
-- [ ] Single `HMHomeManager` instance shared across the app
-- [ ] `HMHomeManagerDelegate` implemented; homes not accessed before `homeManagerDidUpdateHomes`
-- [ ] `HMHomeDelegate` set on homes to receive accessory and room changes
-- [ ] `HMAccessoryDelegate` set on accessories to receive characteristic updates
-- [ ] Characteristic metadata checked before writing values
-- [ ] Error handling in all completion handlers
-- [ ] MatterSupport extension target and principal handler configured
-- [ ] Matter discovery `NSBonjourServices` entries added
-- [ ] `com.apple.developer.matter.allow-setup-payload` used only when providing setup codes
-- [ ] `MatterAddDeviceRequest.isSupported` checked before performing requests
-- [ ] Matter extension handler implements `commissionDevice(in:onboardingPayload:commissioningID:)`
-- [ ] Action sets tested with the HomeKit Accessory Simulator before shipping
-- [ ] Triggers enabled after creation (`trigger.enable(true)`)
+Network selection, attestation details and a fuller handler are in
+the [commissioning recipes](references/matter-commissioning.md).
+
+## Common mistakes
+
+- **Reading `homes` straight after init.** It is empty until
+  `homeManagerDidUpdateHomes(_:)` fires.
+- **Using the HomeKit setup sheet for an ecosystem app.** Neither
+  `addAndSetupAccessories` nor `HMAccessorySetupManager` puts a device in your
+  own fabric; that goes through `MatterAddDeviceRequest`.
+- **Missing extension plumbing.** No extension target, no principal handler
+  class, or missing Bonjour types all break pairing. The setup-payload
+  entitlement is only for apps that pass codes directly.
+- **Several home managers.** Each instance loads the whole home database.
+  Share one, for example an `@Observable` store exposed as `static let shared`.
+- **Writing without metadata.** Out-of-range values fail; clamp to
+  `minimumValue` and `maximumValue` first.
+
+## Review checklist
+
+- [ ] HomeKit capability turned on
+- [ ] `NSHomeKitUsageDescription` present
+- [ ] One shared `HMHomeManager`
+- [ ] `HMHomeManagerDelegate` implemented; nothing reads homes before `homeManagerDidUpdateHomes`
+- [ ] `HMHomeDelegate` set on each home to hear about accessory and room changes
+- [ ] Each accessory has an `HMAccessoryDelegate` so pushed values arrive
+- [ ] Characteristic metadata consulted before writes
+- [ ] Every completion handler handles its error
+- [ ] MatterSupport extension target with a principal handler subclass
+- [ ] Matter `NSBonjourServices` entries listed
+- [ ] Setup-payload entitlement only when the app supplies codes
+- [ ] `MatterAddDeviceRequest.isSupported` checked before `perform()`
+- [ ] Extension implements `commissionDevice(in:onboardingPayload:commissioningID:)`
+- [ ] Scenes exercised against HomeKit Accessory Simulator before release
+- [ ] Triggers enabled with `enable(true)` after creation
 
 ## References
 
-- Extended patterns (Matter extension, delegate wiring, SwiftUI): [references/matter-commissioning.md](references/matter-commissioning.md)
-- [HomeKit framework](https://sosumi.ai/documentation/homekit)
-- [HMHomeManager](https://sosumi.ai/documentation/homekit/hmhomemanager)
-- [HMHome](https://sosumi.ai/documentation/homekit/hmhome)
-- [HMAccessory](https://sosumi.ai/documentation/homekit/hmaccessory)
-- [HMRoom](https://sosumi.ai/documentation/homekit/hmroom)
-- [HMActionSet](https://sosumi.ai/documentation/homekit/hmactionset)
-- [HMTrigger](https://sosumi.ai/documentation/homekit/hmtrigger)
-- [MatterSupport framework](https://sosumi.ai/documentation/mattersupport)
-- [MatterAddDeviceRequest](https://sosumi.ai/documentation/mattersupport/matteradddevicerequest)
-- [MatterAddDeviceExtensionRequestHandler](https://sosumi.ai/documentation/mattersupport/matteradddeviceextensionrequesthandler)
-- [Enabling HomeKit in your app](https://sosumi.ai/documentation/homekit/enabling-homekit-in-your-app)
-- [Adding Matter support to your ecosystem](https://sosumi.ai/documentation/mattersupport/adding-matter-support-to-your-ecosystem)
+- [Commissioning recipes](references/matter-commissioning.md): SwiftUI store and views, full delegate wiring, service and characteristic tables, advanced extension handler, simulator testing
+- https://developer.apple.com/documentation/homekit
+- https://developer.apple.com/documentation/homekit/hmhomemanager
+- https://developer.apple.com/documentation/homekit/hmhome
+- https://developer.apple.com/documentation/homekit/hmaccessory
+- https://developer.apple.com/documentation/homekit/hmroom
+- https://developer.apple.com/documentation/homekit/hmactionset
+- https://developer.apple.com/documentation/homekit/hmtrigger
+- https://developer.apple.com/documentation/mattersupport
+- https://developer.apple.com/documentation/mattersupport/matteradddevicerequest
+- https://developer.apple.com/documentation/mattersupport/matteradddeviceextensionrequesthandler
+- Apple articles worth reading: "Enabling HomeKit in your app" (under the HomeKit
+  documentation) and "Adding Matter support to your ecosystem" (under MatterSupport)