@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

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

@@ -1,567 +1,448 @@
-# WeatherKit Extended Patterns
+# WeatherKit Patterns
 
-Overflow reference for the `weatherkit` skill. Contains advanced patterns that exceed the main skill file's scope.
+Larger building blocks for the `weatherkit` skill. Its SKILL.md covers setup,
+queries, alerts, availability and the attribution rules; this file puts them
+together.
 
 ## Contents
 
-- [WeatherKit SwiftUI Integration](#weatherkit-swiftui-integration)
-- [Charts Integration](#charts-integration)
-- [Historical Weather Statistics](#historical-weather-statistics)
-- [Weather Condition Mapping](#weather-condition-mapping)
-- [Caching Strategy](#caching-strategy)
-- [Location-Based Weather](#location-based-weather)
+- [WeatherKit SwiftUI integration](#weatherkit-swiftui-integration)
+- [Attribution view](#attribution-view)
+- [Charts integration](#charts-integration)
+- [Historical weather statistics](#historical-weather-statistics)
+- [Weather condition mapping](#weather-condition-mapping)
+- [Caching strategy](#caching-strategy)
+- [Location-based weather](#location-based-weather)
 
-## WeatherKit SwiftUI Integration
+## WeatherKit SwiftUI integration
 
-### Weather Manager with `@Observable`
+### A weather model
+
+One `@Observable` type fetches the datasets a dashboard needs in a single call,
+together with the attribution, and exposes loading and error state.
 
 ```swift
-import WeatherKit
 import CoreLocation
+import Observation
+import WeatherKit
 
-@Observable
 @MainActor
-final class WeatherManager {
-    private let service = WeatherService.shared
-
-    var current: CurrentWeather?
-    var hourlyForecast: Forecast<HourWeather>?
-    var dailyForecast: Forecast<DayWeather>?
-    var alerts: [WeatherAlert]?
-    var attribution: WeatherAttribution?
-    var isLoading = false
-    var error: Error?
-
-    func fetchWeather(for location: CLLocation) async {
-        isLoading = true
-        error = nil
-
+@Observable
+final class ForecastBoard {
+    private(set) var now: CurrentWeather?
+    private(set) var hours: Forecast<HourWeather>?
+    private(set) var days: Forecast<DayWeather>?
+    private(set) var alerts: [WeatherAlert] = []
+    private(set) var credit: WeatherAttribution?
+    private(set) var busy = false
+    private(set) var failure: (any Error)?
+
+    private let source = WeatherService.shared
+
+    func load(for place: CLLocation) async {
+        busy = true
+        defer { busy = false }
         do {
-            let (current, hourly, daily, alerts) = try await service.weather(
-                for: location,
-                including: .current, .hourly, .daily, .alerts
-            )
-            self.current = current
-            self.hourlyForecast = hourly
-            self.dailyForecast = daily
-            self.alerts = alerts
-            self.attribution = try await service.attribution
+            let (current, hourly, daily, warnings) = try await source.weather(
+                for: place, including: .current, .hourly, .daily, .alerts)
+            now = current
+            hours = hourly
+            days = daily
+            alerts = warnings ?? []
+            credit = try await source.attribution
+            failure = nil
         } catch {
-            self.error = error
+            failure = error
         }
-
-        isLoading = false
     }
 }
 ```
 
-### Weather Dashboard View
+### Dashboard view
 
 ```swift
-import SwiftUI
-import WeatherKit
-
-struct WeatherDashboardView: View {
-    @Environment(WeatherManager.self) private var manager
-    let location: CLLocation
+struct ForecastScreen: View {
+    @State private var board = ForecastBoard()
+    let place: CLLocation
 
     var body: some View {
-        NavigationStack {
-            ScrollView {
-                VStack {
-                    if manager.isLoading {
-                        ProgressView("Loading weather...")
-                    } else if let current = manager.current {
-                        currentConditionsCard(current)
-                    }
-
-                    if let hourly = manager.hourlyForecast {
-                        hourlyForecastSection(hourly)
-                    }
-
-                    if let daily = manager.dailyForecast {
-                        dailyForecastSection(daily)
-                    }
-
-                    if let alerts = manager.alerts, !alerts.isEmpty {
-                        alertsSection(alerts)
-                    }
-
-                    if let attribution = manager.attribution {
-                        WeatherAttributionView(attribution: attribution)
-                    }
+        ScrollView {
+            if board.busy && board.now == nil {
+                ProgressView().padding(.top, 80)
+            } else {
+                VStack(alignment: .leading, spacing: 24) {
+                    if let now = board.now { NowPanel(now: now) }
+                    if let hours = board.hours { HourStrip(hours: hours) }
+                    if let days = board.days { DayList(days: days) }
+                    if !board.alerts.isEmpty { AlertList(alerts: board.alerts) }
+                    if let credit = board.credit { CreditFooter(credit: credit) }
                 }
                 .padding()
             }
-            .navigationTitle("Weather")
-            .task {
-                await manager.fetchWeather(for: location)
-            }
-            .refreshable {
-                await manager.fetchWeather(for: location)
-            }
         }
+        .task { await board.load(for: place) }
+        .refreshable { await board.load(for: place) }
     }
+}
+```
 
-    private func currentConditionsCard(_ current: CurrentWeather) -> some View {
-        VStack {
-            Image(systemName: current.symbolName)
-                .font(.system(size: 60))
-                .symbolRenderingMode(.multicolor)
+The panels:
+
+```swift
+struct NowPanel: View {
+    let now: CurrentWeather
 
-            Text(current.temperature.formatted())
-                .font(.system(size: 48, weight: .thin))
-
-            Text(current.condition.description)
-                .font(.title3)
-                .foregroundStyle(.secondary)
-
-            HStack {
-                Label(
-                    "Humidity \(current.humidity.formatted(.percent))",
-                    systemImage: "humidity"
-                )
-                Label(
-                    "Wind \(current.wind.speed.formatted())",
-                    systemImage: "wind"
-                )
-                Label(
-                    "UV \(current.uvIndex.value)",
-                    systemImage: "sun.max"
-                )
+    var body: some View {
+        HStack(spacing: 16) {
+            Image(systemName: now.symbolName)
+                .symbolRenderingMode(.multicolor)
+                .font(.system(size: 56))
+            VStack(alignment: .leading) {
+                Text(now.temperature.formatted()).font(.largeTitle.bold())
+                Text(now.condition.description)
+                Text("Humidity \(now.humidity.formatted(.percent))  Wind \(now.wind.speed.formatted())  UV \(now.uvIndex.value)")
+                    .font(.footnote)
+                    .foregroundStyle(.secondary)
             }
-            .font(.caption)
         }
-        .padding()
     }
+}
+
+struct HourStrip: View {
+    let hours: Forecast<HourWeather>
 
-    private func hourlyForecastSection(_ forecast: Forecast<HourWeather>) -> some View {
-        VStack(alignment: .leading) {
-            Text("Hourly Forecast")
-                .font(.headline)
-
-            ScrollView(.horizontal, showsIndicators: false) {
-                HStack {
-                    ForEach(Array(forecast.prefix(12)), id: \.date) { hour in
-                        VStack {
-                            Text(hour.date, format: .dateTime.hour())
-                                .font(.caption)
-                            Image(systemName: hour.symbolName)
-                                .symbolRenderingMode(.multicolor)
-                            Text(hour.temperature.formatted())
-                                .font(.subheadline)
-                        }
+    var body: some View {
+        ScrollView(.horizontal) {
+            LazyHStack(spacing: 18) {
+                ForEach(hours.prefix(12), id: \.date) { slot in
+                    VStack(spacing: 6) {
+                        Text(slot.date, format: .dateTime.hour())
+                        Image(systemName: slot.symbolName).symbolRenderingMode(.multicolor)
+                        Text(slot.temperature.formatted(.measurement(width: .narrow)))
                     }
+                    .font(.caption)
                 }
             }
         }
+        .scrollIndicators(.hidden)
     }
+}
 
-    private func dailyForecastSection(_ forecast: Forecast<DayWeather>) -> some View {
-        VStack(alignment: .leading) {
-            Text("10-Day Forecast")
-                .font(.headline)
-
-            ForEach(Array(forecast), id: \.date) { day in
-                HStack {
-                    Text(day.date, format: .dateTime.weekday(.abbreviated))
-                        .frame(width: 40, alignment: .leading)
-
-                    Image(systemName: day.symbolName)
-                        .symbolRenderingMode(.multicolor)
-                        .frame(width: 30)
-
-                    Text(day.lowTemperature.formatted())
-                        .foregroundStyle(.secondary)
-                        .frame(width: 50, alignment: .trailing)
-
-                    temperatureBar(low: day.lowTemperature, high: day.highTemperature)
+struct DayList: View {
+    let days: Forecast<DayWeather>
 
-                    Text(day.highTemperature.formatted())
-                        .frame(width: 50)
+    var body: some View {
+        Grid(alignment: .leading, verticalSpacing: 10) {
+            ForEach(days.forecast, id: \.date) { entry in
+                GridRow {
+                    Text(entry.date.formatted(.dateTime.weekday(.abbreviated)))
+                    Image(systemName: entry.symbolName).symbolRenderingMode(.multicolor)
+                    Text(entry.lowTemperature.formatted(.measurement(width: .narrow)))
+                    Capsule()
+                        .fill(LinearGradient(colors: [.teal, .orange], startPoint: .leading, endPoint: .trailing))
+                        .frame(maxHeight: 5)
+                        .containerRelativeFrame(.horizontal) { width, _ in width * 0.35 }
+                    Text(entry.highTemperature.formatted(.measurement(width: .narrow)))
                 }
-                .font(.subheadline)
             }
         }
     }
+}
 
-    private func temperatureBar(
-        low: Measurement<UnitTemperature>,
-        high: Measurement<UnitTemperature>
-    ) -> some View {
-        Capsule()
-            .fill(.linearGradient(
-                colors: [.blue, .orange],
-                startPoint: .leading,
-                endPoint: .trailing
-            ))
-            .frame(height: 4)
-            .containerRelativeFrame(.horizontal) { length, _ in
-                length * 0.3
-            }
-    }
+struct AlertList: View {
+    let alerts: [WeatherAlert]
 
-    private func alertsSection(_ alerts: [WeatherAlert]) -> some View {
-        VStack(alignment: .leading) {
-            Text("Weather Alerts")
-                .font(.headline)
-
-            ForEach(alerts, id: \.detailsURL) { alert in
-                HStack {
-                    Image(systemName: "exclamationmark.triangle.fill")
-                        .foregroundStyle(alert.severity == .extreme ? .red : .orange)
-                    VStack(alignment: .leading) {
-                        Text(alert.summary)
-                            .font(.subheadline)
-                        Text(alert.region)
-                            .font(.caption)
-                            .foregroundStyle(.secondary)
-                    }
-                }
-                .padding()
-                .background(.yellow.opacity(0.1))
-                .clipShape(.rect(cornerRadius: 8))
+    var body: some View {
+        ForEach(alerts, id: \.detailsURL) { warning in
+            let isExtreme = warning.severity == .extreme
+            Link(destination: warning.detailsURL) {
+                Label(warning.summary, systemImage: "exclamationmark.octagon.fill")
+                    .foregroundStyle(isExtreme ? Color.red : Color.orange)
             }
         }
     }
 }
 ```
 
-### Attribution View
+## Attribution view
+
+A compact footer: a 12-point mark that falls back to the service name while it
+loads, and a link to the data sources.
 
 ```swift
-struct WeatherAttributionView: View {
-    let attribution: WeatherAttribution
-    @Environment(\.colorScheme) private var colorScheme
+struct CreditFooter: View {
+    let credit: WeatherAttribution
+    @Environment(\.colorScheme) private var scheme
 
     var body: some View {
-        VStack {
-            AsyncImage(url: markURL) { image in
-                image
-                    .resizable()
-                    .scaledToFit()
-                    .frame(height: 12)
+        HStack(spacing: 8) {
+            AsyncImage(url: scheme == .dark ? credit.combinedMarkDarkURL : credit.combinedMarkLightURL) { image in
+                image.resizable().scaledToFit()
             } placeholder: {
-                Text(attribution.serviceName)
-                    .font(.caption2)
+                Text(credit.serviceName)
             }
+            .frame(height: 12)
 
-            Link(destination: attribution.legalPageURL) {
-                Text("Data Sources")
-                    .font(.caption2)
-                    .foregroundStyle(.secondary)
-            }
+            Link("Data Sources", destination: credit.legalPageURL)
         }
-        .padding(.vertical)
-    }
-
-    private var markURL: URL {
-        colorScheme == .dark
-            ? attribution.combinedMarkDarkURL
-            : attribution.combinedMarkLightURL
+        .font(.caption2)
+        .foregroundStyle(.secondary)
     }
 }
 ```
 
-## Charts Integration
+## Charts integration
 
-### Hourly Temperature Chart
+### Hourly temperature line
 
 ```swift
-import SwiftUI
 import Charts
-import WeatherKit
 
-struct HourlyTemperatureChart: View {
-    let forecast: Forecast<HourWeather>
+struct TemperatureTrend: View {
+    let hours: Forecast<HourWeather>
 
     var body: some View {
-        Chart(Array(forecast.prefix(24)), id: \.date) { hour in
-            LineMark(
-                x: .value("Hour", hour.date),
-                y: .value("Temperature", hour.temperature.converted(to: .celsius).value)
-            )
-            .interpolationMethod(.catmullRom)
-            .foregroundStyle(.orange)
-
-            AreaMark(
-                x: .value("Hour", hour.date),
-                y: .value("Temperature", hour.temperature.converted(to: .celsius).value)
-            )
-            .interpolationMethod(.catmullRom)
-            .foregroundStyle(.orange.opacity(0.1))
+        Chart(hours.prefix(24), id: \.date) { slot in
+            let degrees = slot.temperature.converted(to: .celsius).value
+            AreaMark(x: .value("Time", slot.date), y: .value("Temperature", degrees))
+                .foregroundStyle(.orange.opacity(0.2))
+                .interpolationMethod(.catmullRom)
+            LineMark(x: .value("Time", slot.date), y: .value("Temperature", degrees))
+                .foregroundStyle(.orange)
+                .interpolationMethod(.catmullRom)
         }
-        .chartYAxisLabel("Temperature (C)")
         .chartXAxis {
             AxisMarks(values: .stride(by: .hour, count: 3)) { _ in
                 AxisGridLine()
                 AxisValueLabel(format: .dateTime.hour())
             }
         }
-        .frame(height: 200)
+        .frame(minHeight: 160)
     }
 }
 ```
 
-### Daily Precipitation Chart
+Convert to one unit before plotting; mixing units on one axis gives a
+meaningless line. For display text, keep `formatted()` so the user's unit
+applies.
+
+### Daily precipitation bars
 
 ```swift
-struct DailyPrecipitationChart: View {
-    let forecast: Forecast<DayWeather>
+struct RainOutlook: View {
+    let days: Forecast<DayWeather>
 
     var body: some View {
-        Chart(Array(forecast), id: \.date) { day in
-            BarMark(
-                x: .value("Day", day.date, unit: .day),
-                y: .value("Chance", day.precipitationChance)
-            )
-            .foregroundStyle(.blue.gradient)
+        Chart(days.forecast, id: \.date) { entry in
+            let odds = entry.precipitationChance
+            BarMark(x: .value("Date", entry.date, unit: .day), y: .value("Rain", odds))
+                .foregroundStyle(Color.blue.gradient)
         }
         .chartYScale(domain: 0...1)
         .chartYAxis {
-            AxisMarks(format: .percent)
+            AxisMarks { mark in
+                AxisValueLabel {
+                    if let share = mark.as(Double.self) { Text(share, format: .percent) }
+                }
+            }
         }
         .chartXAxis {
             AxisMarks(values: .stride(by: .day)) { _ in
-                AxisGridLine()
-                AxisValueLabel(format: .dateTime.weekday(.abbreviated))
+                AxisValueLabel(format: .dateTime.weekday(.narrow), centered: true)
             }
         }
-        .frame(height: 150)
     }
 }
 ```
 
-## Historical Weather Statistics
+## Historical weather statistics
 
-WeatherKit provides historical weather data through daily and monthly statistics.
-
-### Daily Statistics
+iOS 18 added statistics that describe what is normal for a place, derived from
+long-term records. The methods take variadic queries and return one result per
+query.
 
 ```swift
-func fetchDailyStats(
-    for location: CLLocation,
-    dateRange: DateInterval
-) async throws {
-    let stats = try await WeatherService.shared.dailyStatistics(
-        for: location,
-        forDaysIn: dateRange,
-        including: [.temperature, .precipitation]
+@available(iOS 18.0, *)
+func typicalJune(of year: Int, at place: CLLocation) async throws -> [(day: Int, low: String, high: String)] {
+    let calendar = Calendar(identifier: .gregorian)
+    let juneFirst = DateComponents(year: year, month: 6, day: 1)
+    let julyFirst = DateComponents(year: year, month: 7, day: 1)
+    guard let start = calendar.date(from: juneFirst), let end = calendar.date(from: julyFirst) else { return [] }
+
+    let service = WeatherService.shared
+    let (temperatures, precipitation) = try await service.dailyStatistics(
+        for: place,
+        forDaysIn: DateInterval(start: start, end: end),
+        including: .temperature, .precipitation
     )
+    _ = precipitation.days.map(\.averagePrecipitationProbability)
 
-    for dayStat in stats {
-        print("Date: \(dayStat.date)")
-        if let temp = dayStat.statistics(for: .temperature) {
-            print("  Avg temp: \(temp.mean?.formatted() ?? "N/A")")
-            print("  Min temp: \(temp.minimum?.formatted() ?? "N/A")")
-            print("  Max temp: \(temp.maximum?.formatted() ?? "N/A")")
-        }
+    return temperatures.days.map { stats in
+        (stats.day, stats.averageLowTemperature.formatted(), stats.averageHighTemperature.formatted())
     }
 }
 ```
 
-### Monthly Statistics
+- `DailyWeatherStatistics<T>` is a collection; its `days` array holds
+  `DayTemperatureStatistics` (`day`, `averageLowTemperature`,
+  `averageHighTemperature`) or `DayPrecipitationStatistics` (`day`,
+  `averagePrecipitationProbability`, `averagePrecipitationAmount`,
+  `averageSnowfallAmount`). `day` is a day number, not a `Date`.
+- `monthlyStatistics(for:including:)` returns `MonthlyWeatherStatistics<T>`
+  whose `months` array holds `MonthTemperatureStatistics` (`month`,
+  `averageLowTemperature`, `averageHighTemperature`) or the precipitation
+  equivalent.
+- `hourlyStatistics(for:forHoursIn:including:)` and
+  `dailySummary(for:forDaysIn:including:)` follow the same shape for hourly
+  normals and for observed daily totals.
 
 ```swift
-func fetchMonthlyStats(for location: CLLocation) async throws {
-    let stats = try await WeatherService.shared.monthlyStatistics(
-        for: location,
-        including: [.temperature, .precipitation]
-    )
-
-    for monthStat in stats {
-        print("Month: \(monthStat.month)")
-    }
+@available(iOS 18.0, *)
+func monthlyNormals(at place: CLLocation) async throws -> [Int: String] {
+    let service = WeatherService.shared
+    let normals = try await service.monthlyStatistics(for: place, including: .temperature)
+    return Dictionary(uniqueKeysWithValues: normals.months.map { ($0.month, $0.averageHighTemperature.formatted()) })
 }
 ```
 
-## Weather Condition Mapping
+## Weather condition mapping
 
-### Mapping Conditions to Colors
+`WeatherCondition` has a readable `description`, but apps often want their own
+icon or grouping. Switch over every case and keep `@unknown default` for cases
+added later.
 
 ```swift
-extension WeatherCondition {
-    var themeColor: Color {
-        switch self {
-        case .clear, .mostlyClear:
-            return .yellow
-        case .partlyCloudy, .mostlyCloudy, .cloudy:
-            return .gray
-        case .rain, .heavyRain, .drizzle:
-            return .blue
-        case .snow, .heavySnow, .flurries, .sleet, .freezingRain,
-             .freezingDrizzle, .wintryMix, .blizzard:
-            return .cyan
-        case .thunderstorms, .strongStorms, .tropicalStorm, .hurricane:
-            return .purple
-        case .foggy, .haze, .smoky:
-            return .gray.opacity(0.6)
-        case .breezy, .windy:
-            return .teal
-        case .hot:
-            return .red
-        case .frigid, .blowingDust:
-            return .indigo
-        @unknown default:
-            return .primary
-        }
+func skyGroup(_ condition: WeatherCondition) -> String {
+    switch condition {
+    case .clear, .mostlyClear, .hot:
+        return "sunny"
+    case .partlyCloudy, .mostlyCloudy, .cloudy:
+        return "cloudy"
+    case .drizzle, .rain, .heavyRain, .sunShowers:
+        return "rain"
+    case .snow, .heavySnow, .flurries, .sunFlurries, .blowingSnow, .blizzard:
+        return "snow"
+    case .sleet, .freezingRain, .freezingDrizzle, .wintryMix, .hail, .frigid:
+        return "ice"
+    case .thunderstorms, .isolatedThunderstorms, .scatteredThunderstorms,
+         .strongStorms, .tropicalStorm, .hurricane:
+        return "storm"
+    case .foggy, .haze, .smoky, .blowingDust:
+        return "low visibility"
+    case .breezy, .windy:
+        return "wind"
+    @unknown default:
+        return "unknown"
     }
 }
 ```
 
-### Mapping Severity to Priority
+`WeatherSeverity` orders alerts. Rank it explicitly:
 
 ```swift
-extension WeatherSeverity {
-    var displayPriority: Int {
-        switch self {
-        case .extreme:
-            return 4
-        case .severe:
-            return 3
-        case .moderate:
-            return 2
-        case .minor:
-            return 1
-        case .unknown:
-            return 0
-        @unknown default:
-            return 0
-        }
+func rank(_ severity: WeatherSeverity) -> Int {
+    switch severity {
+    case .extreme:  4
+    case .severe:   3
+    case .moderate: 2
+    case .minor:    1
+    case .unknown:  0
+    @unknown default: 0
     }
 }
 ```
 
-## Caching Strategy
+## Caching strategy
 
-### Actor-Based Weather Cache
+An actor keeps recent results per rounded coordinate and throws them away once
+they are older than the staleness window.
 
 ```swift
-actor WeatherCache {
-    struct CacheEntry {
-        let weather: CurrentWeather
-        let hourly: Forecast<HourWeather>
-        let daily: Forecast<DayWeather>
-        let fetchDate: Date
+actor ForecastCache {
+    struct Snapshot {
+        let now: CurrentWeather
+        let hours: Forecast<HourWeather>
+        let days: Forecast<DayWeather>
+        let fetchedAt: Date
     }
 
-    private var cache: [String: CacheEntry] = [:]
-    private let staleness: TimeInterval
+    private var store: [String: Snapshot] = [:]
+    private let maxAge: TimeInterval
+
+    init(maxAge: TimeInterval = 600) { self.maxAge = maxAge }
 
-    init(staleness: TimeInterval = 600) { // 10 minutes default
-        self.staleness = staleness
+    // Two decimal places is roughly a one-kilometre grid.
+    private func key(for place: CLLocation) -> String {
+        let spot = place.coordinate
+        return String(format: "%.2f|%.2f", spot.latitude, spot.longitude)
     }
 
-    func get(for key: String) -> CacheEntry? {
-        guard let entry = cache[key],
-              Date.now.timeIntervalSince(entry.fetchDate) < staleness else {
-            cache[key] = nil
+    func snapshot(for place: CLLocation) -> Snapshot? {
+        let slot = key(for: place)
+        guard let hit = store[slot] else { return nil }
+        if Date.now.timeIntervalSince(hit.fetchedAt) > maxAge {
+            store[slot] = nil
             return nil
         }
-        return entry
+        return hit
     }
 
-    func set(_ entry: CacheEntry, for key: String) {
-        cache[key] = entry
-    }
-
-    /// Generate a cache key from a location (rounded to ~1km precision)
-    static func key(for location: CLLocation) -> String {
-        let lat = (location.coordinate.latitude * 100).rounded() / 100
-        let lon = (location.coordinate.longitude * 100).rounded() / 100
-        return "\(lat),\(lon)"
+    func keep(_ snapshot: Snapshot, for place: CLLocation) {
+        store[key(for: place)] = snapshot
     }
 }
-```
 
-### Using the Cache
-
-```swift
-@Observable
-@MainActor
-final class CachedWeatherManager {
-    private let service = WeatherService.shared
-    private let cache = WeatherCache()
-
-    var current: CurrentWeather?
-
-    func fetchWeather(for location: CLLocation) async throws {
-        let key = WeatherCache.key(for: location)
-
-        if let cached = await cache.get(for: key) {
-            current = cached.weather
-            return
-        }
-
-        let (current, hourly, daily) = try await service.weather(
-            for: location,
-            including: .current, .hourly, .daily
-        )
-
-        let entry = WeatherCache.CacheEntry(
-            weather: current,
-            hourly: hourly,
-            daily: daily,
-            fetchDate: .now
-        )
-        await cache.set(entry, for: key)
-        self.current = current
-    }
+func freshForecast(at place: CLLocation, cache: ForecastCache) async throws -> ForecastCache.Snapshot {
+    if let cached = await cache.snapshot(for: place) { return cached }
+    let service = WeatherService.shared
+    let (now, hours, days) = try await service.weather(for: place, including: .current, .hourly, .daily)
+    let snapshot = ForecastCache.Snapshot(now: now, hours: hours, days: days, fetchedAt: .now)
+    await cache.keep(snapshot, for: place)
+    return snapshot
 }
 ```
 
-## Location-Based Weather
+## Location-based weather
 
-### Combining CoreLocation with WeatherKit
+A small location provider: ask for when-in-use permission, request one fix at
+kilometre accuracy (plenty for weather), then fetch current conditions.
 
 ```swift
-import CoreLocation
-import WeatherKit
-
-@Observable
 @MainActor
-final class LocationWeatherManager: NSObject, CLLocationManagerDelegate {
-    private let locationManager = CLLocationManager()
-    private let weatherService = WeatherService.shared
-
-    var current: CurrentWeather?
-    var locationError: Error?
+@Observable
+final class LocalConditions: NSObject, CLLocationManagerDelegate {
+    private(set) var now: CurrentWeather?
+    private(set) var problem: String?
+    private let locator = CLLocationManager()
 
     override init() {
         super.init()
-        locationManager.delegate = self
-        locationManager.desiredAccuracy = kCLLocationAccuracyKilometer
+        locator.delegate = self
+        locator.desiredAccuracy = kCLLocationAccuracyKilometer
     }
 
-    func requestWeather() {
-        locationManager.requestWhenInUseAuthorization()
-        locationManager.requestLocation()
+    func start() {
+        locator.requestWhenInUseAuthorization()
+        locator.requestLocation()
     }
 
-    nonisolated func locationManager(
-        _ manager: CLLocationManager,
-        didUpdateLocations locations: [CLLocation]
-    ) {
-        guard let location = locations.last else { return }
-        Task { @MainActor in
-            do {
-                current = try await weatherService.weather(
-                    for: location,
-                    including: .current
-                )
-            } catch {
-                locationError = error
-            }
-        }
+    nonisolated func locationManager(_ source: CLLocationManager, didUpdateLocations fixes: [CLLocation]) {
+        guard let latest = fixes.last else { return }
+        Task { @MainActor in await refresh(at: latest) }
     }
 
-    nonisolated func locationManager(
-        _ manager: CLLocationManager,
-        didFailWithError error: Error
-    ) {
-        Task { @MainActor in
-            locationError = error
+    private func refresh(at spot: CLLocation) async {
+        do {
+            let service = WeatherService.shared
+            now = try await service.weather(for: spot, including: .current)
+        } catch {
+            problem = error.localizedDescription
         }
     }
+
+    nonisolated func locationManager(_ source: CLLocationManager, didFailWithError error: any Error) {
+        let message = error.localizedDescription
+        Task { @MainActor in problem = message }
+    }
 }
 ```