@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

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

@@ -1,412 +1,254 @@
 ---
 name: weatherkit
-description: "Fetch current, hourly, and daily weather forecasts and display required attribution using WeatherKit. Use when integrating weather data, showing forecasts, handling weather alerts, displaying Apple Weather attribution, or querying historical weather statistics in iOS apps."
+description: "WeatherKit on iOS: current, hourly, daily and minute forecasts, alerts, historical statistics, dataset selection, caching. Use when integrating weather data, showing forecasts, handling severe alerts or displaying the required Apple Weather attribution and legal link."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
 # WeatherKit
 
-Fetch current conditions, hourly and daily forecasts, weather alerts, and
-historical statistics using `WeatherService`. Display required Apple Weather
-attribution. Targets Swift 6.3 / iOS 26+.
+WeatherKit gives an app the same forecast data the system Weather app uses,
+through one async service. The rules that matter most are legal and economic:
+attribution is required wherever the data shows, and every dataset you request
+counts against the app's quota. Code targets Swift 6.3 and iOS 26.
 
-## Contents
-
-- [Setup](#setup)
-- [Fetching Current Weather](#fetching-current-weather)
-- [Forecasts](#forecasts)
-- [Weather Alerts](#weather-alerts)
-- [Selective Queries](#selective-queries)
-- [Attribution](#attribution)
-- [Availability](#availability)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+Dashboard, charts, historical statistics, condition mapping, caching and
+location plumbing are in
+[references/weatherkit-patterns.md](references/weatherkit-patterns.md).
 
 ## Setup
 
-### Project Configuration
+### Project configuration
 
-1. Enable the **WeatherKit** capability in Xcode (adds the entitlement)
-2. Enable WeatherKit for your App ID in the Apple Developer portal
-3. Add `NSLocationWhenInUseUsageDescription` to Info.plist if using device location
-4. WeatherKit requires an active Apple Developer Program membership
+1. In Xcode, add the **WeatherKit** capability. This writes the entitlement.
+2. In the developer portal, enable WeatherKit for the same App ID (both the
+   capability and the service checkbox are needed).
+3. The account must be a paid, currently active developer program membership.
+4. If the app sends the device's own position, add
+   `NSLocationWhenInUseUsageDescription` and get location permission first.
 
-### Import
+### Imports and the service
 
 ```swift
 import WeatherKit
 import CoreLocation
+
+let forecaster = WeatherService.shared   // or WeatherService()
 ```
 
-### Creating the Service
+`WeatherService` is `Sendable`, so one instance can be used from any task or
+actor.
+
+## Fetching current weather
 
-Use the shared singleton or create an instance. The service is `Sendable` and
-thread-safe.
+The plain call returns every dataset in a `Weather` value:
 
 ```swift
-let weatherService = WeatherService.shared
-// or
-let weatherService = WeatherService()
+let site = CLLocation(latitude: 38.42, longitude: 27.14)
+let report = try await forecaster.weather(for: site)
+let now = report.currentWeather
 ```
 
-## Fetching Current Weather
+`CurrentWeather` fields you will use most:
 
-Fetch current conditions for a location. Returns a `Weather` object with all
-available datasets.
+| Property | Type | Note |
+| --- | --- | --- |
+| `temperature` | `Measurement<UnitTemperature>` | Format with `.formatted()` |
+| `condition` | `WeatherCondition` | Enum with a readable `description` |
+| `symbolName` | `String` | An SF Symbol name |
+| `humidity` | `Double` | Fraction from 0 to 1 |
+| `wind` | `Wind` | `speed`, `direction`, `gust` |
+| `uvIndex` | `UVIndex` | `value` and `category` |
 
 ```swift
-func fetchCurrentWeather(for location: CLLocation) async throws -> CurrentWeather {
-    let weather = try await weatherService.weather(for: location)
-    return weather.currentWeather
-}
-
-// Using the result
-func displayCurrent(_ current: CurrentWeather) {
-    let temp = current.temperature  // Measurement<UnitTemperature>
-    let condition = current.condition  // WeatherCondition enum
-    let symbol = current.symbolName  // SF Symbol name
-    let humidity = current.humidity  // Double (0-1)
-    let wind = current.wind  // Wind (speed, direction, gust)
-    let uvIndex = current.uvIndex  // UVIndex
-
-    print("\(condition): \(temp.formatted())")
-}
+headline = "\(now.temperature.formatted()), \(now.condition.description)"
 ```
 
 ## Forecasts
 
-### Hourly Forecast
+### Hourly
 
-Returns 25 contiguous hours starting from the current hour by default.
+By default the hourly forecast covers 25 consecutive hours starting with the
+current hour. `hourlyForecast` is a `Forecast<HourWeather>`:
 
 ```swift
-func fetchHourlyForecast(for location: CLLocation) async throws -> Forecast<HourWeather> {
-    let weather = try await weatherService.weather(for: location)
-    return weather.hourlyForecast
-}
-
-// Iterate hours
-for hour in hourlyForecast {
-    print("\(hour.date): \(hour.temperature.formatted()), \(hour.condition)")
+let timeline = report.hourlyForecast.map { slot in
+    (slot.date.formatted(.dateTime.hour()), slot.temperature.formatted(), slot.condition.description)
 }
 ```
 
-### Daily Forecast
+### Daily
 
-Returns 10 contiguous days starting from the current day by default.
+By default the daily forecast covers 10 consecutive days starting today.
+`dailyForecast` is a `Forecast<DayWeather>`:
 
 ```swift
-func fetchDailyForecast(for location: CLLocation) async throws -> Forecast<DayWeather> {
-    let weather = try await weatherService.weather(for: location)
-    return weather.dailyForecast
-}
-
-// Iterate days
-for day in dailyForecast {
-    print("\(day.date): \(day.lowTemperature.formatted()) - \(day.highTemperature.formatted())")
-    print("  Condition: \(day.condition), Precipitation: \(day.precipitationChance)")
+for day in report.dailyForecast {
+    let range = "\(day.lowTemperature.formatted()) to \(day.highTemperature.formatted())"
+    let rain = day.precipitationChance.formatted(.percent)
+    rows.append("\(day.condition.description), \(range), rain \(rain)")
 }
 ```
 
-### Custom Date Range
-
-Request forecasts for specific date ranges using `WeatherQuery`.
+### A custom range
 
 ```swift
-func fetchExtendedForecast(for location: CLLocation) async throws -> Forecast<DayWeather> {
-    let startDate = Date.now
-    let endDate = Calendar.current.date(byAdding: .day, value: 10, to: startDate)!
-
-    let forecast = try await weatherService.weather(
-        for: location,
-        including: .daily(startDate: startDate, endDate: endDate)
+func nextWeek(at site: CLLocation) async throws -> Forecast<DayWeather>? {
+    let weekStart = Date.now
+    guard let weekEnd = Calendar.current.date(byAdding: DateComponents(day: 7), to: weekStart) else { return nil }
+    let service = WeatherService.shared
+    return try await service.weather(
+        for: site,
+        including: .daily(startDate: weekStart, endDate: weekEnd)
     )
-    return forecast
 }
 ```
 
-## Weather Alerts
+`.hourly(startDate:endDate:)` works the same way for hours.
 
-Fetch active weather alerts for a location. Alerts include severity, summary,
-and affected regions.
+## Weather alerts
 
-```swift
-func fetchAlerts(for location: CLLocation) async throws -> [WeatherAlert]? {
-    let weather = try await weatherService.weather(for: location)
-    return weather.weatherAlerts
-}
+`weatherAlerts` is `[WeatherAlert]?`; it is `nil` where alerts are not
+provided.
 
-// Process alerts
-if let alerts = weatherAlerts {
+```swift
+if let alerts = report.weatherAlerts {
     for alert in alerts {
-        print("Alert: \(alert.summary)")
-        print("Severity: \(alert.severity)")
-        print("Region: \(alert.region)")
-        if let detailsURL = alert.detailsURL {
-            // Link to full alert details
-        }
+        // alert.summary: String, alert.severity: WeatherSeverity,
+        // alert.region: String?, alert.detailsURL: URL, alert.source: String
+        banners.append(alert.summary)
     }
 }
 ```
 
-## Selective Queries
-
-Fetch only the datasets you need to minimize API usage and response size. Each
-`WeatherQuery` type maps to one dataset.
+`detailsURL` is not optional; link to it so users can read the full notice
+from the issuing agency.
 
-### Single Dataset
+## Selective queries
 
-```swift
-let current = try await weatherService.weather(
-    for: location,
-    including: .current
-)
-// current is CurrentWeather
-```
-
-### Multiple Datasets
+Ask only for what the screen shows. Each `WeatherQuery` maps to one dataset,
+and each dataset is a request against the quota and more bytes over the wire.
 
 ```swift
-let (current, hourly, daily) = try await weatherService.weather(
-    for: location,
-    including: .current, .hourly, .daily
-)
-// current: CurrentWeather, hourly: Forecast<HourWeather>, daily: Forecast<DayWeather>
-```
-
-### Minute Forecast
+// One dataset: the return type is the dataset itself.
+let nowOnly: CurrentWeather = try await forecaster.weather(for: site, including: .current)
 
-Available in limited regions. Returns precipitation forecasts at minute
-granularity for the next hour.
+// Several datasets: the results come back as a tuple, in the order requested.
+let (now, hours, days) = try await forecaster.weather(for: site, including: .current, .hourly, .daily)
 
-```swift
-let minuteForecast = try await weatherService.weather(
-    for: location,
-    including: .minute
-)
-// minuteForecast: Forecast<MinuteWeather>?  (nil if unavailable)
+// Next-hour precipitation, minute by minute. Only some regions have it.
+if let nextHour = try await forecaster.weather(for: site, including: .minute) {
+    rainStartsSoon = nextHour.contains { $0.precipitationChance > 0.5 }
+}
 ```
 
-### Available Query Types
-
-| Query | Return Type | Description |
-|---|---|---|
-| `.current` | `CurrentWeather` | Current observed conditions |
-| `.hourly` | `Forecast<HourWeather>` | 25 hours from current hour |
+| Query | Result type | Notes |
+| --- | --- | --- |
+| `.current` | `CurrentWeather` | |
+| `.hourly` | `Forecast<HourWeather>` | 25 hours from now |
 | `.daily` | `Forecast<DayWeather>` | 10 days from today |
-| `.minute` | `Forecast<MinuteWeather>?` | Next-hour precipitation (limited regions) |
-| `.alerts` | `[WeatherAlert]?` | Active weather alerts |
-| `.availability` | `WeatherAvailability` | Dataset availability for location |
+| `.minute` | `Forecast<MinuteWeather>?` | `nil` where unsupported |
+| `.alerts` | `[WeatherAlert]?` | `nil` where unsupported |
+| `.availability` | `WeatherAvailability` | Which region-limited datasets exist here |
 
 ## Attribution
 
-Apple requires apps using WeatherKit to display attribution. This is a
-legal requirement.
-
-### Fetching Attribution
+Showing Apple Weather attribution is a legal requirement of using WeatherKit,
+not a design choice. Fetch it from the service:
 
 ```swift
-func fetchAttribution() async throws -> WeatherAttribution {
-    return try await weatherService.attribution
-}
+let credit = try await forecaster.attribution
 ```
 
-### Displaying Attribution in SwiftUI
+Pick the mark that matches the color scheme and link to the legal page:
 
 ```swift
-import SwiftUI
-import WeatherKit
-
-struct WeatherAttributionView: View {
-    let attribution: WeatherAttribution
-    @Environment(\.colorScheme) private var colorScheme
+struct WeatherCredit: View {
+    let credit: WeatherAttribution
+    @Environment(\.colorScheme) private var scheme
 
     var body: some View {
-        VStack {
-            // Display the Apple Weather mark
-            AsyncImage(url: markURL) { image in
-                image
-                    .resizable()
-                    .scaledToFit()
-                    .frame(height: 20)
+        VStack(spacing: 6) {
+            AsyncImage(url: scheme == .dark ? credit.combinedMarkDarkURL : credit.combinedMarkLightURL) { mark in
+                mark.resizable().scaledToFit()
             } placeholder: {
-                EmptyView()
+                Text(credit.serviceName).font(.caption2)
             }
+            .frame(height: 14)
 
-            // Link to the legal attribution page
-            Link("Weather data sources", destination: attribution.legalPageURL)
+            Link("Other data sources", destination: credit.legalPageURL)
                 .font(.caption2)
-                .foregroundStyle(.secondary)
         }
     }
-
-    private var markURL: URL {
-        colorScheme == .dark
-            ? attribution.combinedMarkDarkURL
-            : attribution.combinedMarkLightURL
-    }
 }
 ```
 
-### Attribution Properties
+`WeatherAttribution` provides:
 
 | Property | Use |
-|---|---|
-| `combinedMarkLightURL` | Apple Weather mark for light backgrounds |
-| `combinedMarkDarkURL` | Apple Weather mark for dark backgrounds |
-| `squareMarkURL` | Square Apple Weather logo |
-| `legalPageURL` | URL to the legal attribution web page |
-| `legalAttributionText` | Text alternative when a web view is not feasible |
-| `serviceName` | Weather data provider name |
+| --- | --- |
+| `combinedMarkLightURL` | Mark for light backgrounds |
+| `combinedMarkDarkURL` | Mark for dark backgrounds |
+| `squareMarkURL` | Compact square mark |
+| `legalPageURL` | Page listing data sources; link to it |
+| `legalAttributionText` | Plain-text alternative when showing a web page is not practical |
+| `serviceName` | The provider name, "Apple Weather" |
 
 ## Availability
 
-Check which weather datasets are available for a given location. Not all datasets
-are available in all countries.
+Minute forecasts and alerts are not offered in every country. Ask before
+building UI around them:
 
 ```swift
-func checkAvailability(for location: CLLocation) async throws {
-    let availability = try await weatherService.weather(
-        for: location,
-        including: .availability
-    )
-
-    // Check specific dataset availability
-    if availability.alertAvailability == .available {
-        // Safe to fetch alerts
-    }
-
-    if availability.minuteAvailability == .available {
-        // Minute forecast available for this region
-    }
-}
-```
-
-## Common Mistakes
-
-### DON'T: Ship without Apple Weather attribution
-
-Omitting attribution violates the WeatherKit terms of service and risks App Review
-rejection.
-
-```swift
-// WRONG: Show weather data without attribution
-VStack {
-    Text("72F, Sunny")
-}
-
-// CORRECT: Always include attribution
-VStack {
-    Text("72F, Sunny")
-    WeatherAttributionView(attribution: attribution)
-}
+let coverage = try await forecaster.weather(for: site, including: .availability)
+let offersAlerts = coverage.alertAvailability == .available
+let offersNextHour = coverage.minuteAvailability == .available
 ```
 
-### DON'T: Fetch all datasets when you only need current conditions
-
-Each dataset query counts against your API quota. Fetch only what you display.
+Each is a `WeatherAvailability.AvailabilityKind`: `.available`,
+`.temporarilyUnavailable`, `.unsupported` or `.unknown`.
 
-```swift
-// WRONG: Fetches everything
-let weather = try await weatherService.weather(for: location)
-let temp = weather.currentWeather.temperature
-
-// CORRECT: Fetch only current conditions
-let current = try await weatherService.weather(
-    for: location,
-    including: .current
-)
-let temp = current.temperature
-```
+## Common mistakes
 
-### DON'T: Ignore minute forecast unavailability
+1. **No attribution.** Leaving it out breaks the WeatherKit terms and is a
+   reason for App Review to reject the app.
+2. **Fetching everything to show one number.** `weather(for:)` returns every
+   dataset and each one counts against the quota. Use
+   `weather(for:including: .current)` when only current conditions appear.
+3. **Force-unwrapping the minute forecast.** It is `nil` in unsupported
+   regions and the app crashes there. Use `if let`.
+4. **Missing capability.** Without the capability and the portal switch,
+   `WeatherService` calls throw at runtime.
+5. **Refetching on every appearance.** Weather does not change second to
+   second. Cache results with a staleness window, for example an actor that
+   keeps entries for 600 seconds (see the reference file).
 
-Minute forecasts return `nil` in unsupported regions. Force-unwrapping crashes.
-
-```swift
-// WRONG: Force-unwrap minute forecast
-let minutes = try await weatherService.weather(for: location, including: .minute)
-for m in minutes! { ... } // Crash in unsupported regions
-
-// CORRECT: Handle nil
-if let minutes = try await weatherService.weather(for: location, including: .minute) {
-    for m in minutes { ... }
-} else {
-    // Minute forecast not available for this region
-}
-```
-
-### DON'T: Forget the WeatherKit entitlement
-
-Without the capability enabled, `WeatherService` calls throw at runtime.
-
-```swift
-// WRONG: No WeatherKit capability configured
-let weather = try await weatherService.weather(for: location) // Throws
-
-// CORRECT: Enable WeatherKit in Xcode Signing & Capabilities
-// and in the Apple Developer portal for your App ID
-```
-
-### DON'T: Make repeated requests without caching
-
-Weather data updates every few minutes, not every second. Cache responses
-to stay within API quotas and improve performance.
-
-```swift
-// WRONG: Fetch on every view appearance
-.task {
-    let weather = try? await fetchWeather()
-}
-
-// CORRECT: Cache with a staleness interval
-actor WeatherCache {
-    private var cached: CurrentWeather?
-    private var lastFetch: Date?
-
-    func current(for location: CLLocation) async throws -> CurrentWeather {
-        if let cached, let lastFetch,
-           Date.now.timeIntervalSince(lastFetch) < 600 {
-            return cached
-        }
-        let fresh = try await WeatherService.shared.weather(
-            for: location, including: .current
-        )
-        cached = fresh
-        lastFetch = .now
-        return fresh
-    }
-}
-```
+## Review checklist
 
-## Review Checklist
-
-- [ ] WeatherKit capability enabled in Xcode and Apple Developer portal
-- [ ] Active Apple Developer Program membership (required for WeatherKit)
-- [ ] Apple Weather attribution displayed wherever weather data appears
-- [ ] Attribution mark uses correct color scheme variant (light/dark)
-- [ ] Legal attribution page linked or `legalAttributionText` displayed
-- [ ] Only needed `WeatherQuery` datasets fetched (not full `weather(for:)` when unnecessary)
-- [ ] Minute forecast handled as optional (nil in unsupported regions)
-- [ ] Weather alerts checked for nil before iteration
-- [ ] Responses cached with a reasonable staleness interval (5-15 minutes)
-- [ ] `WeatherAvailability` checked before fetching region-limited datasets
-- [ ] Location permission requested before passing `CLLocation` to service
-- [ ] Temperature and measurements formatted with `Measurement.formatted()` for locale
+- [ ] WeatherKit capability added in Xcode and enabled in the portal
+- [ ] Active developer program membership
+- [ ] Attribution visible wherever weather data appears
+- [ ] Attribution mark follows light and dark mode
+- [ ] Legal page linked, or `legalAttributionText` shown
+- [ ] Only the datasets the screen needs are requested
+- [ ] Minute forecast treated as optional
+- [ ] Alerts nil-checked
+- [ ] Responses cached for 5 to 15 minutes
+- [ ] `WeatherAvailability` checked before region-limited datasets
+- [ ] Location permission granted before a device `CLLocation` is passed in
+- [ ] Measurements displayed with `formatted()` so units follow the locale
 
 ## References
 
-- Extended patterns (SwiftUI dashboard, charts integration, historical statistics): [references/weatherkit-patterns.md](references/weatherkit-patterns.md)
-- [WeatherKit framework](https://sosumi.ai/documentation/weatherkit)
-- [WeatherService](https://sosumi.ai/documentation/weatherkit/weatherservice)
-- [WeatherAttribution](https://sosumi.ai/documentation/weatherkit/weatherattribution)
-- [WeatherQuery](https://sosumi.ai/documentation/weatherkit/weatherquery)
-- [CurrentWeather](https://sosumi.ai/documentation/weatherkit/currentweather)
-- [Forecast](https://sosumi.ai/documentation/weatherkit/forecast)
-- [HourWeather](https://sosumi.ai/documentation/weatherkit/hourweather)
-- [DayWeather](https://sosumi.ai/documentation/weatherkit/dayweather)
-- [WeatherAlert](https://sosumi.ai/documentation/weatherkit/weatheralert)
-- [WeatherAvailability](https://sosumi.ai/documentation/weatherkit/weatheravailability)
-- [Fetching weather forecasts with WeatherKit](https://sosumi.ai/documentation/weatherkit/fetching_weather_forecasts_with_weatherkit)
+- [references/weatherkit-patterns.md](references/weatherkit-patterns.md)
+- [WeatherKit](https://developer.apple.com/documentation/weatherkit)
+- [WeatherService](https://developer.apple.com/documentation/weatherkit/weatherservice)
+- [WeatherAttribution](https://developer.apple.com/documentation/weatherkit/weatherattribution)
+- [WeatherQuery](https://developer.apple.com/documentation/weatherkit/weatherquery)
+- [CurrentWeather](https://developer.apple.com/documentation/weatherkit/currentweather)
+- [Forecast](https://developer.apple.com/documentation/weatherkit/forecast)
+- [HourWeather](https://developer.apple.com/documentation/weatherkit/hourweather)
+- [DayWeather](https://developer.apple.com/documentation/weatherkit/dayweather)
+- [WeatherAlert](https://developer.apple.com/documentation/weatherkit/weatheralert)
+- [WeatherAvailability](https://developer.apple.com/documentation/weatherkit/weatheravailability)
+- [Fetching weather forecasts with WeatherKit](https://developer.apple.com/documentation/weatherkit/fetching_weather_forecasts_with_weatherkit)