@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

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

@@ -5,7 +5,7 @@ description: "Read, write, and query Apple Health data using HealthKit. Covers H
 
 # HealthKit
 
-Read and write health and fitness data from the Apple Health store. Covers authorization, queries, writing samples, background delivery, and workout sessions. Targets Swift 6.2 / iOS 26+.
+Read and write health and fitness data from the Apple Health store. Covers authorization, queries, writing samples, background delivery, and workout sessions. Targets Swift 6.3 / iOS 26+.
 
 ## Contents
 
@@ -33,20 +33,26 @@ Read and write health and fitness data from the Apple Health store. Covers autho
 
 ### Availability Check
 
-Always check availability before accessing HealthKit. iPad and some devices do not support it.
+Always check availability before calling other HealthKit APIs. Health data is
+available on iOS, watchOS, visionOS, iPadOS 17+, and iOS apps running on
+Vision Pro. It is unavailable on iPadOS 16 or earlier and may be restricted by
+managed device policy.
 
 ```swift
 import HealthKit
 
-let healthStore = HKHealthStore()
-
 guard HKHealthStore.isHealthDataAvailable() else {
-    // HealthKit not available on this device (e.g., iPad)
+    // Health data is unavailable or restricted on this device.
     return
 }
+
+let healthStore = HKHealthStore()
 ```
 
-Create a single `HKHealthStore` instance and reuse it throughout your app. It is thread-safe.
+Create a single `HKHealthStore` instance and reuse it throughout your app. It
+is thread-safe. If HealthKit is optional, review Xcode's generated
+`UIRequiredDeviceCapabilities` `healthkit` entry so unsupported devices are not
+excluded unintentionally.
 
 ## Authorization
 
@@ -75,7 +81,10 @@ func requestAuthorization() async throws {
 
 ### Checking Authorization Status
 
-The app can only determine if it has **not yet requested** authorization. If the user denied access, HealthKit returns empty results rather than an error -- this is a privacy design.
+`authorizationStatus(for:)` reports write/share authorization. HealthKit does
+not reveal whether read permission was granted or denied. If the user denies
+read access, queries return only samples your app successfully saved, which may
+look like empty or partial data.
 
 ```swift
 let status = healthStore.authorizationStatus(
@@ -266,11 +275,23 @@ healthStore.execute(observerQuery)
 
 **Frequencies:** `.immediate`, `.hourly`, `.daily`, `.weekly`
 
-Call `enableBackgroundDelivery` once (e.g., at app launch). The system persists the registration.
+Set up observer queries as soon as the app launches, then call
+`enableBackgroundDelivery` once for the same sample type. The system persists
+the registration, wakes the app at most once per requested frequency, and
+enforces tighter caps for some types such as hourly step-count delivery on iOS.
+Background delivery is not supported on Simulator; test it on device.
 
 ## Workout Sessions
 
-Use `HKWorkoutSession` and `HKLiveWorkoutBuilder` to track live workouts. Available on watchOS 2+ and iOS 17+.
+Use `HKWorkoutSession` and `HKLiveWorkoutBuilder` to track live workouts.
+`HKWorkoutSession` is available on iOS/iPadOS 17+, visionOS 1+, and watchOS 2+.
+`HKLiveWorkoutBuilder` is available on iOS/iPadOS 26+ and watchOS 5+, so gate
+live-builder code if supporting older iOS/iPadOS releases.
+
+On iPhone and iPad, live heart-rate collection requires a paired external heart
+rate sensor. Apple Watch sessions can collect high-frequency heart-rate data.
+For locked iPhone workouts, plan for the system's workout-data access flow
+before showing health metrics on the Lock Screen.
 
 ```swift
 func startWorkout() async throws {
@@ -304,7 +325,7 @@ func endWorkout(
 }
 ```
 
-For full workout lifecycle management including pause/resume, delegate handling, and multi-device mirroring, see `references/healthkit-patterns.md`.
+For full workout lifecycle management including pause/resume, delegate handling, and multi-device mirroring, see [references/healthkit-patterns.md](references/healthkit-patterns.md).
 
 ## Common Data Types
 
@@ -331,7 +352,8 @@ Common category types: `.sleepAnalysis`, `.mindfulSession`, `.appleStandHour`
 
 ### HKCharacteristicType
 
-Read-only user characteristics: `.dateOfBirth`, `.biologicalSex`, `.bloodType`, `.fitzpatrickSkinType`
+Read-only user characteristics include `.dateOfBirth`, `.biologicalSex`,
+`.bloodType`, `.fitzpatrickSkinType`, `.wheelchairUse`, and `.activityMoveMode`.
 
 ## HKUnit Reference
 
@@ -357,116 +379,22 @@ HKUnit.literUnit(with: .deci)               // Deciliters
 
 ## Common Mistakes
 
-### 1. Over-requesting data types
-
-DON'T -- request everything:
-```swift
-// App Review will reject this
-let allTypes: Set<HKObjectType> = [
-    HKQuantityType(.stepCount),
-    HKQuantityType(.heartRate),
-    HKQuantityType(.bloodGlucose),
-    HKQuantityType(.bodyMass),
-    HKQuantityType(.oxygenSaturation),
-    // ...20 more types the app never uses
-]
-```
-
-DO -- request only what you use:
-```swift
-let neededTypes: Set<HKObjectType> = [
-    HKQuantityType(.stepCount),
-    HKQuantityType(.activeEnergyBurned)
-]
-```
-
-### 2. Not handling authorization denial
-
-DON'T -- assume data will be returned:
-```swift
-func getSteps() async throws -> Double {
-    let result = try await query.result(for: healthStore)
-    return result!.sumQuantity()!.doubleValue(for: .count()) // Crashes if denied
-}
-```
-
-DO -- handle nil gracefully:
-```swift
-func getSteps() async throws -> Double {
-    let result = try await query.result(for: healthStore)
-    return result?.sumQuantity()?.doubleValue(for: .count()) ?? 0
-}
-```
-
-### 3. Assuming HealthKit is always available
-
-DON'T -- skip the check:
-```swift
-let store = HKHealthStore() // Crashes on iPad
-try await store.requestAuthorization(toShare: types, read: types)
-```
-
-DO -- guard availability:
-```swift
-guard HKHealthStore.isHealthDataAvailable() else {
-    showUnsupportedDeviceMessage()
-    return
-}
-```
-
-### 4. Running heavy queries on the main thread
-
-DON'T -- use old callback-based queries on main thread. DO -- use async descriptors:
-```swift
-// Bad: HKSampleQuery with callback on main thread
-// Good: async descriptor
-func loadAllData() async throws -> [HKQuantitySample] {
-    let descriptor = HKSampleQueryDescriptor(
-        predicates: [.quantitySample(type: stepType)],
-        sortDescriptors: [SortDescriptor(\.endDate, order: .reverse)],
-        limit: 100
-    )
-    return try await descriptor.result(for: healthStore)
-}
-```
-
-### 5. Forgetting to call completionHandler in observer queries
-
-DON'T -- skip the completion handler:
-```swift
-let query = HKObserverQuery(sampleType: type, predicate: nil) { _, handler, _ in
-    processNewData()
-    // Forgot to call handler() -- system won't schedule next delivery
-}
-```
-
-DO -- always call it:
-```swift
-let query = HKObserverQuery(sampleType: type, predicate: nil) { _, handler, _ in
-    defer { handler() }
-    processNewData()
-}
-```
-
-### 6. Using wrong statistics options for the data type
-
-DON'T -- use cumulative sum on discrete types:
-```swift
-// Heart rate is discrete, not cumulative -- this returns nil
-let query = HKStatisticsQueryDescriptor(
-    predicate: heartRatePredicate,
-    options: .cumulativeSum
-)
-```
-
-DO -- match options to data type:
-```swift
-// Use discrete options for discrete types
-let query = HKStatisticsQueryDescriptor(
-    predicate: heartRatePredicate,
-    options: .discreteAverage
-)
-```
+1. **Over-requesting data types.** Request only the read/write types the feature
+   actually uses; broad HealthKit permission sheets are an App Review risk.
+2. **Treating read authorization like write authorization.** You can check
+   `.sharingAuthorized` before saving, but read denial is privacy-protected and
+   looks like app-owned-only, empty, or partial results.
+3. **Skipping `isHealthDataAvailable()`.** Check before HealthKit access and
+   handle unavailable or restricted stores without crashing.
+4. **Using callback queries for new async code.** Prefer async descriptors for
+   one-shot reads and statistics, and keep broad queries off the main actor.
+5. **Forgetting observer completion handlers.** Always call the handler; missed
+   completions can delay or stop future background deliveries.
+6. **Assuming `.immediate` means immediate.** Background delivery is capped by
+   the system and must be tested on device.
+7. **Using cumulative stats for discrete values.** Match statistics options to
+   the data type: cumulative sums for steps/energy, discrete average/min/max for
+   heart rate, weight, and similar samples.
 
 ## Review Checklist
 
@@ -474,19 +402,23 @@ let query = HKStatisticsQueryDescriptor(
 - [ ] Only necessary data types requested in authorization
 - [ ] `Info.plist` includes `NSHealthShareUsageDescription` and/or `NSHealthUpdateUsageDescription`
 - [ ] HealthKit capability enabled in Xcode project
-- [ ] Authorization denial handled gracefully (nil results, not crashes)
+- [ ] Write authorization checked before saving; read denial handled as partial
+      or empty query results
 - [ ] Single `HKHealthStore` instance reused (not created per query)
 - [ ] Async query descriptors used instead of callback-based queries
 - [ ] Heavy queries not blocking main thread
 - [ ] Statistics options match data type (cumulative vs. discrete)
-- [ ] Background delivery paired with `HKObserverQuery` and `completionHandler` called
+- [ ] Background delivery paired with app-launch `HKObserverQuery` setup and
+      `completionHandler` called
 - [ ] Background delivery entitlement enabled if using `enableBackgroundDelivery`
+- [ ] Background delivery tested on device and frequency caps considered
 - [ ] Workout sessions properly ended and builder finalized
+- [ ] Workout API availability and live heart-rate sensor requirements handled
 - [ ] Write operations only for sample types the app created
 
 ## References
 
-- Extended patterns (workouts, anchored queries, SwiftUI integration): `references/healthkit-patterns.md`
+- Extended patterns (workouts, anchored queries, SwiftUI integration): [references/healthkit-patterns.md](references/healthkit-patterns.md)
 - [HealthKit framework](https://sosumi.ai/documentation/healthkit)
 - [HKHealthStore](https://sosumi.ai/documentation/healthkit/hkhealthstore)
 - [HKSampleQueryDescriptor](https://sosumi.ai/documentation/healthkit/hksamplequerydescriptor)
@@ -496,3 +428,4 @@ let query = HKStatisticsQueryDescriptor(
 - [HKLiveWorkoutBuilder](https://sosumi.ai/documentation/healthkit/hkliveworkoutbuilder)
 - [Setting up HealthKit](https://sosumi.ai/documentation/healthkit/setting-up-healthkit)
 - [Authorizing access to health data](https://sosumi.ai/documentation/healthkit/authorizing-access-to-health-data)
+- [Configuring HealthKit access](https://sosumi.ai/documentation/xcode/configuring-healthkit-access)

package/pipeline/skills/shared/external/healthkit/evals/evals.json

@@ -0,0 +1,46 @@
+{
+  "skill_name": "healthkit",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "Review this HealthKit setup plan for an iOS 26/iPadOS app: the team says HealthKit never works on iPad, creates HKHealthStore before any availability check, treats authorizationStatus as proof that read permission was denied, and assumes denied reads always return empty arrays. Give concise corrected guidance.",
+      "expected_output": "A correction-focused review that explains current platform availability, availability checks, write-vs-read authorization privacy, and partial app-owned results after read denial.",
+      "files": [],
+      "assertions": [
+        "States that HealthKit data is available on iPadOS 17 or later, not categorically unsupported on iPad.",
+        "Requires HKHealthStore.isHealthDataAvailable() before using other HealthKit APIs.",
+        "Explains that authorizationStatus(for:) reports write/share authorization, not whether read access was granted.",
+        "Explains that denied read access can return only samples the app saved, so results may be empty or partial rather than a reliable denial signal.",
+        "Mentions required HealthKit capability and NSHealthShareUsageDescription or NSHealthUpdateUsageDescription as appropriate."
+      ]
+    },
+    {
+      "id": 1,
+      "prompt": "Review this background step-count sync plan: enableBackgroundDelivery(.immediate) is called after the first dashboard screen appears, the HKObserverQuery is created only when the screen is visible, the completion handler is skipped on errors, and QA plans to validate the behavior only in Simulator. What should change?",
+      "expected_output": "A review that fixes HealthKit background delivery setup, launch-time observer registration, completion handling, device testing, entitlement, and frequency expectations.",
+      "files": [],
+      "assertions": [
+        "Requires the HealthKit Background Delivery capability or com.apple.developer.healthkit.background-delivery entitlement.",
+        "Says observer queries should be set up as the app launches, not only when a screen appears.",
+        "Pairs enableBackgroundDelivery with an HKObserverQuery for the same sample type.",
+        "Requires calling the observer completion handler even when processing fails.",
+        "States that Simulator is not a valid background-delivery test target.",
+        "Explains that requested frequency is a maximum and some types such as iOS step count may be capped hourly."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "A team is building an iOS 26 workout recorder with HKWorkoutSession and HKLiveWorkoutBuilder. They also want the same code path to support iOS 17 devices, assume iPhone has live heart-rate samples like Apple Watch, and mirror Apple Watch workouts to iPhone whenever possible. Review the plan and identify HealthKit pitfalls.",
+      "expected_output": "A workout-session review that distinguishes HKWorkoutSession and HKLiveWorkoutBuilder availability, handles live heart-rate collection on iPhone/iPad, and outlines correct mirroring setup.",
+      "files": [],
+      "assertions": [
+        "Distinguishes HKWorkoutSession availability from HKLiveWorkoutBuilder availability.",
+        "States that HKLiveWorkoutBuilder requires iOS/iPadOS 26 or watchOS 5 and should be availability-gated for older iOS/iPadOS targets.",
+        "States that iPhone and iPad need a paired external heart-rate sensor for live heart-rate collection.",
+        "Mentions that Apple Watch can collect high-frequency heart-rate samples during workouts.",
+        "For mirroring, starts mirroring from the watchOS session and assigns workoutSessionMirroringStartHandler early on the iOS app.",
+        "Mentions lock-screen or locked-device workout data access considerations when showing live iPhone metrics."
+      ]
+    }
+  ]
+}

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

@@ -5,6 +5,8 @@ Overflow reference for the `healthkit` skill. Contains advanced patterns that ex
 ## Contents
 
 - [Workout Session Lifecycle](#workout-session-lifecycle)
+- [Platform and Authorization Edge Cases](#platform-and-authorization-edge-cases)
+- [Background Delivery Details](#background-delivery-details)
 - [Anchored Object Queries](#anchored-object-queries)
 - [Predicate-Based Filtering](#predicate-based-filtering)
 - [Statistics Collection for Charts](#statistics-collection-for-charts)
@@ -13,6 +15,18 @@ Overflow reference for the `healthkit` skill. Contains advanced patterns that ex
 
 ## Workout Session Lifecycle
 
+`HKWorkoutSession` is available on iOS/iPadOS 17+, visionOS 1+, and watchOS
+2+. `HKLiveWorkoutBuilder` is available on iOS/iPadOS 26+ and watchOS 5+.
+When supporting iOS or iPadOS earlier than 26, gate live-builder code and use a
+non-live workout save path where appropriate.
+
+iPhone and iPad do not provide built-in live heart-rate samples. They require a
+paired external heart-rate sensor for live heart-rate collection, while Apple
+Watch workout sessions collect high-frequency heart-rate samples. iPhone also
+often locks during workouts; if the app shows health metrics on the Lock
+Screen, design around the system's workout-data access prompt and Live Activity
+surface.
+
 ### Full Workout Manager
 
 ```swift
@@ -157,6 +171,12 @@ extension WorkoutManager: HKLiveWorkoutBuilderDelegate {
 
 ### Multi-Device Mirroring (watchOS + iOS)
 
+Start mirroring from the primary watchOS session. In the iOS companion app,
+assign `workoutSessionMirroringStartHandler` as the app launches so it can
+receive mirrored sessions even when launched in the background. The handler runs
+on an arbitrary background queue and may be called more than once if the devices
+disconnect and reconnect during a workout.
+
 ```swift
 // On watchOS: start mirroring to companion iPhone
 func startMirroring() async throws {
@@ -179,6 +199,67 @@ func sendDataToRemote(_ data: Data) async throws {
 }
 ```
 
+## Platform and Authorization Edge Cases
+
+- Call `HKHealthStore.isHealthDataAvailable()` before any other HealthKit API.
+  Current Apple docs say Health data is available on iOS, watchOS, visionOS,
+  iPadOS 17+, and iOS apps running on Vision Pro. It is unavailable on iPadOS
+  16 or earlier and may be restricted by managed device policy.
+- Enabling the HealthKit capability for an iOS app can add `healthkit` to
+  `UIRequiredDeviceCapabilities`, preventing installation on unsupported
+  devices. Remove that entry only when HealthKit is optional and the app has a
+  useful non-HealthKit mode.
+- `authorizationStatus(for:)` is for write/share authorization. HealthKit does
+  not reveal whether read access was granted or denied. If read access is
+  denied, queries return samples your app saved successfully, which can look
+  like partial or empty data.
+- People can change HealthKit permissions later in Settings or the Health app.
+  Refresh permission-sensitive UI and write paths instead of assuming the
+  original authorization outcome still applies.
+- In Vision Pro Guest User sessions, previously authorized data may be readable,
+  but new authorization and writes can fail. Treat HealthKit writes as
+  best-effort unless the user explicitly initiated a save action that needs an
+  explanation.
+
+## Background Delivery Details
+
+Background delivery requires the HealthKit Background Delivery capability
+(`com.apple.developer.healthkit.background-delivery` on current Apple docs) and
+an executed `HKObserverQuery` for the same sample type. Set up observer queries
+when the app launches, then call `enableBackgroundDelivery` once; the system
+persists the registration.
+
+```swift
+func configureHealthKitBackgroundDelivery() async throws {
+    let stepType = HKQuantityType(.stepCount)
+
+    let query = HKObserverQuery(
+        sampleType: stepType,
+        predicate: nil
+    ) { _, completionHandler, error in
+        defer { completionHandler() }
+        guard error == nil else { return }
+        Task {
+            // Run an anchored query or statistics refresh here.
+        }
+    }
+
+    healthStore.execute(query)
+
+    try await healthStore.enableBackgroundDelivery(
+        for: stepType,
+        frequency: .hourly
+    )
+}
+```
+
+Treat `HKUpdateFrequency` as a maximum delivery rate, not a guarantee. Some
+types have tighter system caps; for example, iOS step-count background delivery
+is capped at hourly even if `.immediate` is requested. Background server queries
+are not supported on Simulator, so validate delivery on real hardware. If the
+observer completion handler is not called, HealthKit backs off and can stop
+sending background updates after repeated failures.
+
 ## Anchored Object Queries
 
 Use `HKAnchoredObjectQuery` for incremental updates -- only fetches samples added or deleted since the last anchor.
@@ -391,7 +472,7 @@ func fetchHourlyHeartRate(for date: Date) async throws -> [(hour: Date, bpm: Dou
 
 ## HealthKit + SwiftUI Integration
 
-### HealthKit Manager with @Observable
+### HealthKit Manager with `@Observable`
 
 ```swift
 import HealthKit

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

@@ -3,11 +3,11 @@ 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."
 ---
 
-# HomeKit + MatterSupport
+# HomeKit
 
 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.2 / iOS 26+.
+device commissioning into your ecosystem. Targets Swift 6.3 / iOS 26+.
 
 ## Contents
 
@@ -38,10 +38,12 @@ device commissioning into your ecosystem. Targets Swift 6.2 / iOS 26+.
 
 For Matter commissioning into your own ecosystem:
 
-1. Enable the **MatterSupport** capability
-2. Add a **MatterSupport Extension** target to your project
-3. Add the `com.apple.developer.matter.allow-setup-payload` entitlement if
-   your app provides the setup code directly
+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
 
@@ -50,7 +52,8 @@ import HomeKit
 
 let homeManager = HMHomeManager()
 
-// HomeKit is available on iPhone, iPad, Apple TV, Apple Watch, Mac, and Vision Pro.
+// HomeKit is available on iPhone, iPad, Apple TV, Apple Watch,
+// Mac Catalyst, and Vision Pro.
 // Authorization is handled through the delegate:
 homeManager.delegate = self
 ```
@@ -122,6 +125,8 @@ let defaultRoom = home.roomForEntireHome()
 
 ### Discovering and Adding Accessories
 
+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.
+
 ```swift
 // System UI for accessory discovery
 home.addAndSetupAccessories { error in
@@ -241,20 +246,20 @@ home.executeActionSet(actionSet) { error in
 ### Creating a Timer Trigger
 
 ```swift
-var dateComponents = DateComponents()
-dateComponents.hour = 22
-dateComponents.minute = 30
+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: Calendar.current.nextDate(
-        after: Date(),
-        matching: dateComponents,
-        matchingPolicy: .nextTime
-    )!,
-    timeZone: .current,
-    recurrence: dateComponents,  // Repeats daily at 22:30
-    recurrenceCalendar: .current
+    fireDate: firstFireDate,
+    recurrence: DateComponents(day: 1)  // Repeat every day after firstFireDate
 )
 
 home.addTrigger(trigger) { error in
@@ -293,7 +298,8 @@ home.addTrigger(eventTrigger) { error in
 ## Matter Commissioning
 
 Use `MatterAddDeviceRequest` to commission a Matter device into your ecosystem.
-This is separate from HomeKit -- it handles the pairing flow.
+This is separate from the `HMHome` home-automation model; it handles the
+Matter setup flow and calls into your MatterSupport extension.
 
 ### Basic Commissioning
 
@@ -324,6 +330,10 @@ func addMatterDevice() async throws {
 }
 ```
 
+When providing a setup code directly, import Matter and pass an
+`MTRSetupPayload` as `setupPayload`; this is the case that requires the
+setup-payload entitlement.
+
 ### Filtering Devices
 
 ```swift
@@ -337,19 +347,14 @@ let request = MatterAddDeviceRequest(
 )
 ```
 
-### Combining Device Criteria
-
-```swift
-let criteria = MatterAddDeviceRequest.DeviceCriteria.all([
-    .vendorID(0x1234),
-    .not(.productID(0x0001))  // Exclude a specific product
-])
-```
+Combine criteria with `.all([.vendorID(...), .not(.productID(...))])` or use
+`.any(...)` when any one criterion is enough.
 
 ## MatterAddDeviceExtensionRequestHandler
 
 For full ecosystem support, create a MatterSupport Extension. The extension
-handles commissioning callbacks:
+handles commissioning callbacks. Override the needed methods, but do not call
+`super` from those overrides.
 
 ```swift
 import MatterSupport
@@ -357,7 +362,8 @@ import MatterSupport
 final class MatterHandler: MatterAddDeviceExtensionRequestHandler {
 
     override func validateDeviceCredential(
-        _ deviceCredential: DeviceCredential
+        _ deviceCredential:
+            MatterAddDeviceExtensionRequestHandler.DeviceCredential
     ) async throws {
         // Validate the device attestation certificate
         // Throw to reject the device
@@ -422,17 +428,11 @@ let request = MatterAddDeviceRequest(
 try await request.perform()
 ```
 
-### DON'T: Forget required entitlements
-
-```swift
-// WRONG -- calling Matter APIs without the MatterSupport entitlement
-// Results in runtime error
+### DON'T: Forget required configuration
 
-// CORRECT -- ensure these are set up:
-// 1. HomeKit capability for HMHomeManager access
-// 2. MatterSupport Extension target for ecosystem commissioning
-// 3. com.apple.developer.matter.allow-setup-payload if providing setup codes
-```
+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
 
@@ -473,7 +473,9 @@ if let metadata = characteristic.metadata,
 - [ ] `HMAccessoryDelegate` set on accessories to receive characteristic updates
 - [ ] Characteristic metadata checked before writing values
 - [ ] Error handling in all completion handlers
-- [ ] MatterSupport capability and extension target added for Matter commissioning
+- [ ] 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
@@ -481,7 +483,7 @@ if let metadata = characteristic.metadata,
 
 ## References
 
-- Extended patterns (Matter extension, delegate wiring, SwiftUI): `references/matter-commissioning.md`
+- 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)

package/pipeline/skills/shared/external/homekit-matter/evals/evals.json

@@ -0,0 +1,45 @@
+{
+  "skill_name": "homekit",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "I'm building a HomeKit app that should create a nightly Good Night automation at 10:30 PM. Sketch the Swift guidance for creating the action set, adding a timer trigger that repeats daily, attaching the scene, and enabling the trigger. Call out the HomeKit setup prerequisites and any timing gotchas.",
+      "expected_output": "HomeKit automation guidance that uses a single HMHomeManager, creates an HMActionSet, creates an HMTimerTrigger with a first fire date at 22:30 and a daily recurrence interval, attaches the action set, enables the trigger, and lists HomeKit capability/usage-description prerequisites.",
+      "files": [],
+      "expectations": [
+        "Uses HomeKit/HMHomeManager, HMHome, HMActionSet, and HMTimerTrigger rather than routing the task to MatterSupport or AccessorySetupKit.",
+        "Computes the first fire date from hour/minute components such as 22:30.",
+        "Uses a recurrence interval such as DateComponents(day: 1) for daily repeat instead of reusing hour/minute wall-clock components as the recurrence.",
+        "Adds the trigger to the home, adds the action set to the trigger, and enables the trigger.",
+        "Mentions the HomeKit capability and NSHomeKitUsageDescription, and does not access homes before homeManagerDidUpdateHomes."
+      ]
+    },
+    {
+      "id": 1,
+      "prompt": "We need to add Matter lights into our own smart-home ecosystem from an iOS app. Write the setup checklist and Swift-oriented commissioning outline, including discovery configuration, the extension handler callbacks, optional setup-code handling, and what the app should do after perform() succeeds.",
+      "expected_output": "MatterSupport commissioning guidance that adds the MatterSupport extension, declares Matter Bonjour services, uses MatterAddDeviceRequest with topology and isSupported, explains conditional setup-payload entitlement/MTRSetupPayload usage, and outlines the extension handler callbacks for credential validation, rooms, commissioning, configuration, and optional network selection.",
+      "files": [],
+      "expectations": [
+        "Adds or verifies a MatterSupport extension target with a MatterAddDeviceExtensionRequestHandler principal handler.",
+        "Includes NSBonjourServices entries for _matter._tcp, _matterc._udp, and _matterd._udp.",
+        "Checks MatterAddDeviceRequest.isSupported and builds a topology with ecosystem name and homes before perform().",
+        "Limits com.apple.developer.matter.allow-setup-payload to callers that provide setup codes programmatically and mentions MTRSetupPayload from the Matter framework for that case.",
+        "Names extension callbacks such as validateDeviceCredential(_:), rooms(in:), commissionDevice(in:onboardingPayload:commissioningID:), configureDevice(named:in:), and optional Wi-Fi/Thread network selection.",
+        "Does not present MatterSupport commissioning as ordinary HMHome accessory setup or a lower-level AccessorySetupKit picker flow."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "A product proposal says one Apple accessory guide should cover Matter light onboarding, HomeKit rooms and automations, BLE discovery for a setup-only accessory, GATT control after selection, and joining a temporary Wi-Fi setup network. Write a routing note that assigns each part to the right framework domain and explains what belongs in the HomeKit skill.",
+      "expected_output": "A boundary-aware routing note that assigns HomeKit/MatterSupport to homes, rooms, HMAccessory characteristics, action sets, triggers, and Matter onboarding; AccessorySetupKit to Bluetooth/Wi-Fi discovery, picker authorization, session events, and migration; CoreBluetooth/GATT to BLE communication after selection; and NetworkExtension to Wi-Fi setup-network joins.",
+      "files": [],
+      "expectations": [
+        "Identifies HomeKit/MatterSupport as the owner for homes, rooms, HMAccessory services/characteristics, action sets, triggers, automations, and Matter commissioning.",
+        "Limits AccessorySetupKit to Bluetooth/Wi-Fi discovery descriptors, privacy-preserving picker authorization, or ASAccessorySession setup events.",
+        "Routes post-selection BLE service and characteristic communication to CoreBluetooth/GATT.",
+        "Routes joining or configuring a temporary Wi-Fi setup network to NetworkExtension.",
+        "Does not collapse lower-level accessory discovery, GATT communication, or Wi-Fi network joins into HomeKit automation guidance."
+      ]
+    }
+  ]
+}