@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

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

@@ -1,500 +1,333 @@
 ---
 name: energykit
-description: "Query grid electricity forecasts and submit load events using EnergyKit to help users optimize home electricity usage. Use when building smart home apps, EV charger controls, HVAC scheduling, or energy management dashboards that guide users to use power during cleaner or cheaper grid periods."
+description: "EnergyKit on iOS 26: grid electricity forecasts via ElectricityGuidance, EnergyVenue, EV and HVAC load events, ElectricityInsightService history. Use when building smart home, EV charging, HVAC scheduling or energy dashboard features that shift home power use to cleaner or cheaper grid periods."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
-# EnergyKit
 
-Provide grid electricity forecasts to help users choose when to use electricity.
-EnergyKit identifies times when grid electricity is relatively cleaner and,
-when cost information is available, less expensive. Apps use that guidance to
-shift or reduce managed device load. Targets Swift 6.3 / iOS 26+.
+# EnergyKit
 
-> **Beta-sensitive.** EnergyKit is new in iOS 26 and may change before GM.
-> Re-check current Apple documentation before relying on specific API details.
+EnergyKit tells an app when grid electricity is expected to be relatively
+cleaner, and cheaper too when the person's rate plan is known, so the app can
+move or trim the load of devices it controls. Examples use Swift 6.3 and
+assume a deployment target of iOS 26.1 unless a snippet shows its own
+availability check.
 
-## Contents
+**Beta-sensitive.** EnergyKit is new in iOS 26 and its API may still shift.
+Check Apple's current documentation before depending on any detail below.
 
-- [Setup](#setup)
-- [Core Concepts](#core-concepts)
-- [Querying Electricity Guidance](#querying-electricity-guidance)
-- [Working with Guidance Values](#working-with-guidance-values)
-- [Energy Venues](#energy-venues)
-- [Submitting Load Events](#submitting-load-events)
-- [Electricity Insights](#electricity-insights)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+A full observable manager, EV and HVAC session managers, a dashboard, chart
+preparation, retries and venue discovery are in the
+[EnergyKit patterns reference](references/energykit-patterns.md).
+Out of scope: HomeKit automation (`homekit-matter`), scheduling background work
+(`background-processing`) and app power diagnostics (`metrickit-diagnostics`).
 
 ## Setup
 
-### Entitlement
+### Entitlement first
 
-EnergyKit requires the `com.apple.developer.energykit` entitlement. Enable the
-EnergyKit capability in Xcode so the entitlement is added to the app target.
-Treat this as a top-level setup prerequisite before writing guidance queries,
-venue lookup, load-event submission, or insight code. Missing permission can
-surface as `EnergyKitError.permissionDenied`.
+Add the **EnergyKit** capability, which writes the
+`com.apple.developer.energykit` entitlement. Do this before writing any
+guidance, venue, load-event or insight code; without it calls fail with errors
+such as `EnergyKitError.permissionDenied`.
 
-### Import
+### Import and availability
 
 ```swift
 import EnergyKit
 ```
 
-**Platform availability:** Core EnergyKit APIs are iOS 26.0+ and iPadOS 26.0+.
-Some insight breakdown APIs, including grid cleanliness categories, are iOS
-26.1+ / iPadOS 26.1+ and need availability guards.
+The core API needs iOS 26.0 or iPadOS 26.0. Some pieces arrived in 26.1 and
+need `if #available(iOS 26.1, *)` when the app still deploys to 26.0 (the `iOS`
+platform name covers iPadOS; there is no separate `iPadOS` availability name):
+
+- the grid-cleanliness insight breakdown (`dataByGridCleanliness`)
+- venue lookup: `EnergyVenue.venues()`, `venue(for:)` and `venue(matchingHomeUniqueIdentifier:)`
+- the error cases `.unsupportedRegion`, `.rateLimitExceeded` and `.locationServicesDenied`
 
-## Core Concepts
+Guidance queries, load-event submission and the insight service itself are 26.0.
 
-EnergyKit provides two main capabilities:
+## Concepts
 
-1. **Electricity Guidance** -- time-weighted forecasts telling apps when
-   electricity is cleaner and, when rate data is available, less expensive
-2. **Load Events** -- telemetry from managed devices (EV chargers, HVAC)
-   submitted by the same device/app that requested guidance so EnergyKit can
-   generate insights
+EnergyKit does two jobs:
 
-### Key Types
+1. **Electricity guidance** - a forecast of weighted time intervals showing
+   when power is cleaner and, with rate data, cheaper.
+2. **Load events** - telemetry from managed devices such as EV chargers and
+   heat pumps. The same device and app that asked for guidance submits them,
+   and EnergyKit turns them into insights.
 
 | Type | Role |
 |---|---|
-| `ElectricityGuidance` | Forecast data with weighted time intervals |
-| `ElectricityGuidance.Service` | Interface for obtaining guidance data |
-| `ElectricityGuidance.Query` | Query specifying shift or reduce action |
-| `ElectricityGuidance.Value` | A time interval with a rating (0.0-1.0) |
-| `EnergyVenue` | A physical location (home) registered for energy management |
-| `ElectricVehicleLoadEvent` | Load event for EV charger telemetry |
-| `ElectricHVACLoadEvent` | Load event for HVAC system telemetry |
-| `ElectricityInsightService` | Service for querying energy/runtime insights |
-| `ElectricityInsightRecord` | Historical energy or runtime data, optionally broken down by tariff or 26.1+ grid cleanliness |
-| `ElectricityInsightQuery` | Query for historical insight data |
-
-### Suggested Actions
-
-| Action | Use Case |
-|---|---|
-| `.shift` | Devices that can move consumption to a different time (EV charging) |
-| `.reduce` | Devices that can lower consumption without stopping (HVAC setback) |
+| `ElectricityGuidance` | Forecast made of weighted intervals |
+| `ElectricityGuidance.Service` | Delivers guidance |
+| `ElectricityGuidance.Query` | Declares whether you will shift or reduce load |
+| `ElectricityGuidance.Value` | One interval with a 0.0 to 1.0 rating |
+| `EnergyVenue` | A home registered for energy management |
+| `ElectricVehicleLoadEvent` | EV charger telemetry |
+| `ElectricHVACLoadEvent` | Heating and cooling telemetry |
+| `ElectricityInsightService` | Answers energy and runtime history queries |
+| `ElectricityInsightRecord` | Historical energy or runtime, optionally split by tariff or (26.1) cleanliness |
+| `ElectricityInsightQuery` | Describes the history you want |
 
-## Querying Electricity Guidance
+Suggested actions:
 
-Use `ElectricityGuidance.Service` to get a forecast stream for a venue.
+- `.shift` - the device can move its consumption to another time (EV charging).
+- `.reduce` - the device can use less without stopping (a thermostat setback).
 
-```swift
-import EnergyKit
+## Getting guidance
 
-func observeGuidance(venueID: UUID) async throws {
+```swift
+@MainActor
+func watchChargingWindows(for venueID: UUID) async throws {
     let query = ElectricityGuidance.Query(suggestedAction: .shift)
     let service = ElectricityGuidance.sharedService
 
-    let guidanceStream = service.guidance(using: query, at: venueID)
-
-    for try await guidance in guidanceStream {
-        print("Guidance token: \(guidance.guidanceToken)")
-        print("Interval: \(guidance.interval)")
-        print("Venue: \(guidance.energyVenueID)")
-
-        // Check if rate plan information is available
-        if guidance.options.contains(.guidanceIncorporatesRatePlan) {
-            print("Rate plan data incorporated")
-        }
-        if guidance.options.contains(.locationHasRatePlan) {
-            print("Location has a rate plan")
-        }
-
-        processGuidanceValues(guidance.values)
+    for try await forecast in service.guidance(using: query, at: venueID) {
+        ChargePlanner.shared.token = forecast.guidanceToken      // keep the real token
+        ChargePlanner.shared.update(with: forecast.values)
+        let ratePlanUsed = forecast.options.contains(.guidanceIncorporatesRatePlan)
+        let hasRatePlan = forecast.options.contains(.locationHasRatePlan)
+        ChargePlanner.shared.showsCostHint = ratePlanUsed || hasRatePlan
     }
 }
 ```
 
-## Working with Guidance Values
+An `ElectricityGuidance` exposes `guidanceToken`, `interval`, `energyVenueID`,
+`options` and `values`.
 
-Each `ElectricityGuidance.Value` contains a time interval and a rating
-from 0.0 to 1.0. Lower ratings indicate better times to use electricity.
+### Reading the values
 
-```swift
-func processGuidanceValues(_ values: [ElectricityGuidance.Value]) {
-    for value in values {
-        let interval = value.interval
-        let rating = value.rating  // 0.0 (best) to 1.0 (worst)
+Each value has an `interval` and a `rating` from 0.0 (best) to 1.0 (worst).
+Lower is better.
 
-        print("From \(interval.start) to \(interval.end): rating \(rating)")
+```swift
+extension Array where Element == ElectricityGuidance.Value {
+    var bestSlot: ElectricityGuidance.Value? { self.min { $0.rating < $1.rating } }
+    func slots(atOrBelow limit: Double = 0.3) -> [ElectricityGuidance.Value] {
+        filter { $0.rating <= limit }
     }
 }
-
-// Find the best time to charge
-func bestChargingWindow(
-    in values: [ElectricityGuidance.Value]
-) -> ElectricityGuidance.Value? {
-    values.min(by: { $0.rating < $1.rating })
-}
-
-// Find all "good" windows below a threshold
-func goodWindows(
-    in values: [ElectricityGuidance.Value],
-    threshold: Double = 0.3
-) -> [ElectricityGuidance.Value] {
-    values.filter { $0.rating <= threshold }
-}
 ```
 
-### Displaying Guidance in SwiftUI
+### Showing it in SwiftUI
 
 ```swift
-import SwiftUI
-import EnergyKit
-
-struct GuidanceTimelineView: View {
+struct ForecastList: View {
     let values: [ElectricityGuidance.Value]
 
     var body: some View {
-        List(values, id: \.interval.start) { value in
+        List(values, id: \.interval.start) { slot in
             HStack {
-                VStack(alignment: .leading) {
-                    Text(value.interval.start, style: .time)
-                    Text(value.interval.end, style: .time)
-                        .foregroundStyle(.secondary)
-                }
+                Text(slot.interval.start, style: .time)
+                Text("to")
+                Text(slot.interval.end, style: .time)
                 Spacer()
-                RatingIndicator(rating: value.rating)
+                RatingBadge(rating: slot.rating)
             }
         }
     }
 }
 
-struct RatingIndicator: View {
+struct RatingBadge: View {
     let rating: Double
 
-    var color: Color {
-        if rating <= 0.3 { return .green }
-        if rating <= 0.6 { return .yellow }
-        return .red
-    }
-
-    var label: String {
-        if rating <= 0.3 { return "Good" }
-        if rating <= 0.6 { return "Fair" }
-        return "Avoid"
+    private var style: (label: String, tint: Color) {
+        switch rating {
+        case ...0.3: ("Good", .green)
+        case ...0.6: ("Fair", .yellow)
+        default:     ("Avoid", .red)
+        }
     }
 
     var body: some View {
-        Text(label)
-            .padding(.horizontal)
-            .padding(.vertical)
-            .background(color.opacity(0.2))
-            .foregroundStyle(color)
-            .clipShape(Capsule())
+        Text(style.label)
+            .font(.caption.bold())
+            .padding(.horizontal, 8)
+            .background(style.tint.opacity(0.2), in: .capsule)
+            .foregroundStyle(style.tint)
     }
 }
 ```
 
-## Energy Venues
-
-An `EnergyVenue` represents a physical location registered for energy management.
+## Venues
 
 ```swift
-// List all venues
-func listVenues() async throws -> [EnergyVenue] {
-    try await EnergyVenue.venues()
-}
-
-// Get a specific venue by ID
-func getVenue(id: UUID) async throws -> EnergyVenue {
-    try await EnergyVenue.venue(for: id)
-}
-
-// Get a venue matching a HomeKit home
-func getVenueForHome(homeID: UUID) async throws -> EnergyVenue {
-    try await EnergyVenue.venue(matchingHomeUniqueIdentifier: homeID)
-}
+let homes = try await EnergyVenue.venues()                             // every venue
+let remembered = try await EnergyVenue.venue(for: savedVenueID)        // by UUID
+let fromHomeKit = try await EnergyVenue.venue(matchingHomeUniqueIdentifier: home.uniqueIdentifier)
+VenueMenu.shared.show(homes.map(\.name) + [remembered.name, fromHomeKit.name])
 ```
 
-### Venue Properties
+Always discover venues first. A hardcoded or invented venue UUID fails, and the
+person may have no venue at all.
 
-```swift
-let venue = try await EnergyVenue.venue(for: venueID)
-print("Venue ID: \(venue.id)")
-print("Venue name: \(venue.name)")
-```
-
-## Submitting Load Events
+## Load events
 
-Report device consumption data back to the system. This helps the system
-generate electricity insights. The same EnergyKit-capable device/app that
-requested electricity guidance must submit the corresponding load events, using
-the guidance token returned by EnergyKit. Do not invent a token.
+Load events report actual consumption so the system can build insights. Only
+the device and app that requested guidance submit them, and they carry the
+`guidanceToken` EnergyKit returned. Never make one up.
 
-### EV Charger Load Events
+### EV charging
 
 ```swift
-func submitEVChargingEvent(
-    at venue: EnergyVenue,
-    guidanceToken: UUID,
-    deviceID: String
-) async throws {
+func reportCharging(state: ElectricVehicleLoadEvent.Session.State,
+                    sessionID: UUID, kilowatts: Double, kilowattHours: Double,
+                    percent: Int, followingGuidance: Bool,
+                    token: UUID, charger: String, venue: EnergyVenue) async throws {
     let session = ElectricVehicleLoadEvent.Session(
-        id: UUID(),
-        state: .begin,
-        guidanceState: ElectricVehicleLoadEvent.Session.GuidanceState(
-            wasFollowingGuidance: true,
-            guidanceToken: guidanceToken
-        )
+        id: sessionID,
+        state: state,
+        guidanceState: .init(wasFollowingGuidance: followingGuidance, guidanceToken: token)
     )
-
-    let measurement = ElectricVehicleLoadEvent.ElectricalMeasurement(
-        stateOfCharge: 45,
+    let reading = ElectricVehicleLoadEvent.ElectricalMeasurement(
+        stateOfCharge: percent,
         direction: .imported,
-        power: Measurement(value: 7.2, unit: .kilowatts),
-        energy: Measurement(value: 0, unit: .kilowattHours)
+        power: Measurement(value: kilowatts, unit: .kilowatts),
+        energy: Measurement(value: kilowattHours, unit: .kilowattHours)
     )
-
-    let event = ElectricVehicleLoadEvent(
-        timestamp: Date(),
-        measurement: measurement,
-        session: session,
-        deviceID: deviceID
-    )
-
+    let event = ElectricVehicleLoadEvent(timestamp: .now, measurement: reading,
+                                         session: session, deviceID: charger)
     try await venue.submitEvents([event])
 }
 ```
 
-### HVAC Load Events
+### Heating and cooling
 
 ```swift
-func submitHVACEvent(
-    at venue: EnergyVenue,
-    guidanceToken: UUID,
-    stage: Int,
-    deviceID: String
-) async throws {
-    let session = ElectricHVACLoadEvent.Session(
-        id: UUID(),
-        state: .active,
-        guidanceState: ElectricHVACLoadEvent.Session.GuidanceState(
-            wasFollowingGuidance: true,
-            guidanceToken: guidanceToken
-        )
-    )
-
-    let measurement = ElectricHVACLoadEvent.ElectricalMeasurement(stage: stage)
-
-    let event = ElectricHVACLoadEvent(
-        timestamp: Date(),
-        measurement: measurement,
-        session: session,
-        deviceID: deviceID
-    )
-
-    try await venue.submitEvents([event])
-}
+let hvacSession = ElectricHVACLoadEvent.Session(
+    id: runID, state: .active,
+    guidanceState: .init(wasFollowingGuidance: true, guidanceToken: token))
+let stageReading = ElectricHVACLoadEvent.ElectricalMeasurement(stage: 2)
+let hvacEvent = ElectricHVACLoadEvent(timestamp: .now, measurement: stageReading,
+                                      session: hvacSession, deviceID: thermostatID)
+try await venue.submitEvents([hvacEvent])
 ```
 
-### Session States
+### Session lifecycle and cadence
 
-| State | When to Use |
+| State | When |
 |---|---|
-| `.begin` | Device starts consuming electricity |
-| `.active` | Device is actively consuming (periodic updates) |
-| `.end` | Device stops consuming electricity |
-
-For EV charging, record begin/end, one steady sample about every 15 minutes,
-and extra samples for user actions, pauses, new guidance, or rapid power
-changes. For HVAC, submit separate events when equipment starts, when heating
-or cooling stage changes (heat stage 1 -> 2, heat -> cool, cool -> idle), and
-when equipment stops. Batch events when practical for performance. Insights
-are only available for submitted events, and load events for an `EnergyVenue`
-are visible to people who share the associated Home in the Home app.
-
-## Electricity Insights
-
-Query historical energy and runtime data for devices using
-`ElectricityInsightService`. An empty `ElectricityInsightQuery.Options` option
-set returns totals only; it does not populate cleanliness or tariff breakdowns.
-Request `.cleanliness` and/or `.tariff` only when the UI needs those breakdowns.
-Do not substitute MetricKit app power metrics for EnergyKit insights; EnergyKit
-insights depend on EnergyKit load events submitted for the managed device.
-
-Choose insight granularity from the requested range. For a seven-day view,
-query `.hourly`; use `.daily` only when the query covers at least a calendar
-month.
-
-```swift
-func queryEnergyInsights(deviceID: String, venueID: UUID) async throws {
-    let sevenDaysAgo = Calendar.current.date(
-        byAdding: .day,
-        value: -7,
-        to: Date()
-    )!
-
-    let query = ElectricityInsightQuery(
-        options: [.cleanliness, .tariff],
-        range: DateInterval(
-            start: sevenDaysAgo,
-            end: Date()
-        ),
-        granularity: .hourly,
-        flowDirection: .imported
-    )
+| `.begin` | The device starts drawing power |
+| `.active` | Periodic updates while it runs |
+| `.end` | The device stops |
+
+- **EV**: a begin and an end event, a steady sample roughly every 15 minutes,
+  and extra samples when the user acts, charging pauses, new guidance arrives,
+  or power changes quickly.
+- **HVAC**: separate events when equipment starts, at every heating or cooling
+  stage change (heat stage 1 to 2, heat to cool, cool to idle), and when it stops.
+- Batch events when you can for performance.
+- Insights exist only for events you submitted.
+- Everyone who shares the associated home in the Home app can see that venue's
+  load events. Tell users.
+
+## Insights
+
+`ElectricityInsightService` returns energy or runtime history. An empty
+`ElectricityInsightQuery.Options` means totals only; add `.cleanliness`,
+`.tariff` or both only when the interface shows those splits. MetricKit power
+metrics are not a replacement: insights come from the EnergyKit load events
+of the managed device.
+
+Match granularity to the range. A seven-day chart uses `.hourly`; `.daily`
+needs at least a calendar month.
+
+| Granularity | Shortest allowed range |
+|---|---|
+| `.hourly` | One calendar week |
+| `.daily` | One calendar month |
+| `.weekly` | Six months |
+| `.monthly`, `.yearly` | One calendar year |
 
-    let service = ElectricityInsightService.shared
-    let stream = try await service.energyInsights(
-        forDeviceID: deviceID, using: query, atVenue: venueID
-    )
+`ElectricityInsightService` is an actor and `ElectricityInsightRecord` is not
+`Sendable`, so in Swift 6 the returned stream cannot leave the actor: a call
+from a nonisolated or main-actor function fails to compile. Run the loop on the
+service's own isolation with an `isolated` parameter and hand back only
+`Sendable` values.
 
+```swift
+func lastWeekUsage(charger: String, venueID: UUID,
+                   service: isolated ElectricityInsightService = .shared) async throws -> [Double] {
+    let week = DateInterval(start: .now.addingTimeInterval(-7 * 86_400), end: .now)
+    let query = ElectricityInsightQuery(options: [], range: week,
+                                        granularity: .hourly, flowDirection: .imported)
+    var totals: [Double] = []
+    let stream = try await service.energyInsights(forDeviceID: charger, using: query,
+                                                  atVenue: venueID)
     for await record in stream {
-        if let total = record.totalEnergy { print("Total: \(total)") }
-
-        if #available(iOS 26.1, iPadOS 26.1, *),
-           let cleaner = record.dataByGridCleanliness?.cleaner {
-            print("Cleaner: \(cleaner)")
+        totals.append(record.totalEnergy?.converted(to: .kilowattHours).value ?? 0)
+        if #available(iOS 26.1, *) {           // only needed when deploying to 26.0
+            _ = record.dataByGridCleanliness?.cleaner   // needs .cleanliness in options
         }
     }
+    return totals
 }
 ```
 
-Use `runtimeInsights(forDeviceID:using:atVenue:)` for runtime data instead
-of energy. Granularity options: `.hourly`, `.daily`, `.weekly`, `.monthly`,
-`.yearly`. Choose a range that matches Apple's minimum aggregation windows:
-hourly for at least a calendar week, daily for at least a calendar month,
-weekly for at least six months, and monthly or yearly for at least a calendar
-year. See [references/energykit-patterns.md](references/energykit-patterns.md) for full insight examples.
-
-## Common Mistakes
-
-### DON'T: Forget the EnergyKit entitlement
-
-Without the entitlement, EnergyKit APIs can fail with permission errors such as
-`EnergyKitError.permissionDenied`. Treat the EnergyKit capability as setup, not
-as an implementation detail to discover after writing queries.
+For time running rather than energy, call
+`runtimeInsights(forDeviceID:using:atVenue:)` in the same isolated way.
 
-### DON'T: Ignore unsupported regions
-
-EnergyKit is not available in all regions. Handle the `.unsupportedRegion`
-and `.guidanceUnavailable` errors.
+## Errors
 
 ```swift
-// WRONG: Assume guidance is always available
-for try await guidance in service.guidance(using: query, at: venueID) {
-    updateUI(guidance)
-}
-
-// CORRECT: Handle region-specific errors
 do {
-    for try await guidance in service.guidance(using: query, at: venueID) {
-        updateUI(guidance)
-    }
+    try await watchChargingWindows(for: venueID)
 } catch let error as EnergyKitError {
     switch error {
-    case .unsupportedRegion:
-        showUnsupportedRegionMessage()
-    case .guidanceUnavailable:
-        showGuidanceUnavailableMessage()
-    case .venueUnavailable:
-        showNoVenueMessage()
-    case .permissionDenied:
-        showPermissionDeniedMessage()
-    case .serviceUnavailable:
-        retryLater()
-    case .rateLimitExceeded:
-        backOff()
-    default:
-        break
+    case .unsupportedRegion:   showMessage("Grid forecasts aren't offered where you live yet.")
+    case .guidanceUnavailable: showMessage("No forecast right now.")
+    case .venueUnavailable:    showMessage("Set up your home in the Home app first.")
+    case .permissionDenied:    showMessage("EnergyKit access is off.")
+    case .serviceUnavailable:  scheduleRetry()
+    case .rateLimitExceeded:   backOff()
+    default:                   showMessage("Something went wrong.")
     }
 }
 ```
 
-### DON'T: Discard the guidance token
-
-The `guidanceToken` links load events to the guidance that was in effect. Store
-the token returned from EnergyKit on the device that fetched it and pass that
-real token to load event submissions.
-
-```swift
-// WRONG: Ignore the guidance token
-for try await guidance in guidanceStream {
-    startCharging(followingGuidanceToken: UUID())  // fabricated token
-}
-
-// CORRECT: Store the token for load events
-for try await guidance in guidanceStream {
-    let token = guidance.guidanceToken
-    startCharging(followingGuidanceToken: token)
-}
-```
-
-### DON'T: Submit load events without a session lifecycle
-
-Always submit `.begin`, then `.active` updates, then `.end` events.
-
-```swift
-// WRONG: Only submit one event
-let event = ElectricVehicleLoadEvent(/* state: .active */)
-try await venue.submitEvents([event])
-
-// CORRECT: Full session lifecycle
-try await venue.submitEvents([beginEvent])
-// ... periodic active events ...
-try await venue.submitEvents([activeEvent])
-// ... when done ...
-try await venue.submitEvents([endEvent])
-```
-
-### DON'T: Query guidance without a venue
-
-EnergyKit requires a venue ID. List venues first and select the appropriate one.
-
-```swift
-// WRONG: Use a hardcoded UUID
-let fakeID = UUID()
-service.guidance(using: query, at: fakeID)  // Will fail
-
-// CORRECT: Discover venues first
-let venues = try await EnergyVenue.venues()
-guard let venue = venues.first else {
-    showNoVenueSetup()
-    return
-}
-let guidanceStream = service.guidance(using: query, at: venue.id)
-```
-
-## Review Checklist
-
-- [ ] `com.apple.developer.energykit` entitlement added to the project
-- [ ] `EnergyKitError.unsupportedRegion` handled with user-facing message
-- [ ] `EnergyKitError.permissionDenied` handled gracefully
-- [ ] Guidance token stored and passed to load event submissions
-- [ ] No placeholder or fabricated guidance tokens are used in load events
-- [ ] The same EnergyKit-capable device/app that requested guidance submits the corresponding load events
-- [ ] Venues discovered via `EnergyVenue.venues()` before querying guidance
-- [ ] Load event sessions follow `.begin` -> `.active` -> `.end` lifecycle
-- [ ] EV/HVAC event cadence follows Apple guidance and events are batched when practical
-- [ ] `ElectricityGuidance.Value.rating` interpreted correctly (lower is better)
-- [ ] `SuggestedAction` matches the device type (`.shift` for EV, `.reduce` for HVAC)
-- [ ] Insight queries use appropriate minimum ranges for their granularity
-- [ ] Empty insight query options are treated as totals-only, not as cleanliness or tariff requests
-- [ ] MetricKit power telemetry is not used as a substitute for EnergyKit load events or insights
-- [ ] Grid cleanliness insight fields are guarded for iOS/iPadOS 26.1+
-- [ ] Users understand load events are shared with people who share the Home
-- [ ] Rate limiting handled via `EnergyKitError.rateLimitExceeded`
-- [ ] Service unavailability handled with retry logic
+## Common mistakes
+
+- Missing entitlement, which surfaces as `permissionDenied`. Treat the capability as setup.
+- Assuming every region is supported. Handle `.unsupportedRegion` and `.guidanceUnavailable`.
+- Dropping the guidance token, or passing `UUID()` instead of the stored `guidanceToken` from the device that fetched guidance.
+- Sending one event with no lifecycle. Send `.begin`, then `.active` updates, then `.end`.
+- Querying with a fixed or fake venue UUID instead of calling `EnergyVenue.venues()` and handling an empty result.
+
+## Review checklist
+
+- [ ] EnergyKit entitlement present
+- [ ] `.unsupportedRegion` shown to the user clearly
+- [ ] `.permissionDenied` handled
+- [ ] Guidance token kept and attached to load events
+- [ ] No placeholder or invented tokens
+- [ ] Load events come from the device and app that requested guidance
+- [ ] Venues discovered before guidance is requested
+- [ ] Sessions go `.begin`, `.active`, `.end`
+- [ ] EV and HVAC cadence follow Apple's guidance; events batched where practical
+- [ ] Ratings treated as lower-is-better
+- [ ] `.shift` for EV, `.reduce` for HVAC
+- [ ] Insight ranges meet the granularity minimums
+- [ ] Empty options understood as totals only
+- [ ] No MetricKit stand-in for insights
+- [ ] Grid-cleanliness fields, venue lookup and the newer error cases behind a 26.1 check when the target is 26.0
+- [ ] Users told that Home members can see load events
+- [ ] `.rateLimitExceeded` backs off
+- [ ] `.serviceUnavailable` retried later
 
 ## References
 
-- Extended patterns (full app architecture, SwiftUI dashboard): [references/energykit-patterns.md](references/energykit-patterns.md)
-- [EnergyKit framework](https://sosumi.ai/documentation/energykit)
-- [ElectricityGuidance](https://sosumi.ai/documentation/energykit/electricityguidance)
-- [ElectricityGuidance.Service](https://sosumi.ai/documentation/energykit/electricityguidance/service)
-- [ElectricityGuidance.Query](https://sosumi.ai/documentation/energykit/electricityguidance/query)
-- [ElectricityGuidance.Value](https://sosumi.ai/documentation/energykit/electricityguidance/value)
-- [EnergyVenue](https://sosumi.ai/documentation/energykit/energyvenue)
-- [ElectricVehicleLoadEvent](https://sosumi.ai/documentation/energykit/electricvehicleloadevent)
-- [ElectricHVACLoadEvent](https://sosumi.ai/documentation/energykit/electrichvacloadevent)
-- [ElectricityInsightService](https://sosumi.ai/documentation/energykit/electricityinsightservice)
-- [ElectricityInsightRecord](https://sosumi.ai/documentation/energykit/electricityinsightrecord)
-- [ElectricityInsightQuery](https://sosumi.ai/documentation/energykit/electricityinsightquery)
-- [EnergyKitError](https://sosumi.ai/documentation/energykit/energykiterror)
-- [Optimizing home electricity usage](https://sosumi.ai/documentation/energykit/optimizing-home-electricity-usage)
+- [EnergyKit patterns](references/energykit-patterns.md) - managers, dashboard, charts, retries, venue discovery
+- [EnergyKit](https://developer.apple.com/documentation/energykit)
+- [ElectricityGuidance](https://developer.apple.com/documentation/energykit/electricityguidance),
+  [Service](https://developer.apple.com/documentation/energykit/electricityguidance/service),
+  [Query](https://developer.apple.com/documentation/energykit/electricityguidance/query),
+  [Value](https://developer.apple.com/documentation/energykit/electricityguidance/value)
+- [EnergyVenue](https://developer.apple.com/documentation/energykit/energyvenue)
+- [ElectricVehicleLoadEvent](https://developer.apple.com/documentation/energykit/electricvehicleloadevent)
+- [ElectricHVACLoadEvent](https://developer.apple.com/documentation/energykit/electrichvacloadevent)
+- [ElectricityInsightService](https://developer.apple.com/documentation/energykit/electricityinsightservice)
+- [ElectricityInsightRecord](https://developer.apple.com/documentation/energykit/electricityinsightrecord)
+- [ElectricityInsightQuery](https://developer.apple.com/documentation/energykit/electricityinsightquery)
+- [EnergyKitError](https://developer.apple.com/documentation/energykit/energykiterror)
+- Apple's article on optimizing home electricity usage