@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/mapkit-location/SKILL.md

@@ -1,87 +1,109 @@
 ---
 name: mapkit-location
-description: "Implement, review, or improve maps and location features in iOS/macOS apps using MapKit and CoreLocation. Use when working with Map views, annotations, markers, polylines, user location tracking, geocoding, reverse geocoding, search/autocomplete, directions and routes, geofencing, region monitoring, CLLocationUpdate async streams, or location authorization flows. Also use when working with maps, coordinates, addresses, places, directions, distance calculations, or location-based features in Swift apps."
+description: "MapKit and CoreLocation on iOS and macOS: SwiftUI Map, markers, annotations, polylines and overlays, camera control, user location tracking, CLLocationUpdate streams, location authorization, geocoding and reverse geocoding, search and autocomplete, directions, routes and ETA, CLMonitor geofencing and region monitoring, background location, distance math. Use when implementing, reviewing or improving anything built on maps, coordinates, addresses, places, directions or distances."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
-# MapKit
+# MapKit and CoreLocation
 
-Build map-based and location-aware features targeting iOS 17+ with SwiftUI
-MapKit and modern CoreLocation async APIs. Use `Map` with `MapContentBuilder`
-for views, `CLLocationUpdate.liveUpdates()` for streaming location, and
-`CLMonitor` for geofencing.
+Two frameworks do the work here. MapKit draws the map and answers questions
+about places (search, geocoding, routes). CoreLocation tells you where the
+device is and when it crosses a boundary. Since iOS 17 both have a Swift-first
+surface: a SwiftUI `Map` whose content is written in a `MapContentBuilder`
+closure, the async sequence `CLLocationUpdate.liveUpdates()` for position, and
+the `CLMonitor` actor for geofences. Write new code against those; reach for
+`MKMapView` or `CLLocationManager` only for the gaps named below.
 
-Read [references/mapkit-patterns.md](references/mapkit-patterns.md) when you need full map setup, search,
-routes, Look Around, snapshots, or iOS 26 place APIs. Read
-[references/mapkit-corelocation-patterns.md](references/mapkit-corelocation-patterns.md) when the task involves
-location update lifecycle, geofencing, background location, testing, or privacy keys.
+Baseline: iOS 17. Sections that need a later release say so, and code that
+needs it carries `@available`.
 
-## Contents
+Longer material lives in two references:
 
-- [Workflow](#workflow)
-- [SwiftUI Map View (iOS 17+)](#swiftui-map-view-ios-17)
-- [CoreLocation Modern API](#corelocation-modern-api)
-- [Geocoding](#geocoding)
-- [Search](#search)
-- [Directions](#directions)
-- [PlaceDescriptor (iOS 26+)](#placedescriptor-ios-26)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+- [Map patterns](references/mapkit-patterns.md): a complete
+  map screen, custom annotations, camera control, search with autocomplete,
+  routes, Look Around, snapshots, dense annotations, iOS 26 place APIs,
+  coordinate helpers, accessibility.
+- [Location patterns](references/mapkit-corelocation-patterns.md):
+  the location update lifecycle, diagnostics, `CLServiceSession`, `CLMonitor`
+  geofencing, background location, legacy `CLLocationManager` cases, accuracy,
+  simulator testing, Info.plist privacy keys.
 
-## Workflow
+## Scope
 
-### 1. Add a map with markers or annotations
+In scope: maps, markers and annotations, overlays, routes, search and
+geocoding, the user's position, `CLMonitor` geofencing and the rules for
+location in the background.
 
-1. Import `MapKit`.
-2. Create a `Map` view with optional `MapCameraPosition` binding.
-3. Add `Marker`, `Annotation`, `MapPolyline`, `MapPolygon`, or `MapCircle`
-   inside the `MapContentBuilder` closure.
-4. Configure map style with `.mapStyle()`.
-5. Add map controls with `.mapControls { }`.
-6. Handle selection with a `selection:` binding.
+Neighbouring work belongs elsewhere. MapKit does not draw CarPlay templates,
+launch App Clips or pair Bluetooth hardware, so never claim it does. What this
+skill owns is the handoff point: a geofence event, a search result or a route
+that the other framework then acts on.
 
-### 2. Track user location
+| Topic | Where it goes |
+|-------|---------------|
+| CarPlay map templates, navigation alerts, CarPlay UI | CarPlay framework guidance (no skill in this collection) |
+| App Clip invocation from a place card, size limits, handoff to the full app | `app-clips` |
+| Pairing a beacon or accessory when a geofence fires | `core-bluetooth`, or AccessorySetupKit |
+| A Live Activity used to keep background location alive | `live-activities` |
 
-1. Add `NSLocationWhenInUseUsageDescription` to Info.plist.
-2. On iOS 18+, create a `CLServiceSession` to manage authorization.
-3. Iterate `CLLocationUpdate.liveUpdates()` in a `Task`.
-4. Filter updates by distance or accuracy before updating the UI.
-5. Stop the task when location tracking is no longer needed.
+## Workflows
 
-### 3. Search for places
+### 1. Put places on a map
 
-1. Configure `MKLocalSearchCompleter` for autocomplete suggestions.
-2. Debounce user input (at least 300ms) before setting the query.
-3. Convert selected completion to `MKLocalSearch.Request` for full results.
-4. Display results as markers or in a list.
+1. `import MapKit` (and `SwiftUI`).
+2. Create a `Map`. Bind a `MapCameraPosition` if code needs to move the camera.
+3. Inside the content closure add `Marker`, `Annotation`, `MapPolyline`,
+   `MapPolygon` or `MapCircle`.
+4. Pick a look with `.mapStyle(...)`.
+5. Add controls with `.mapControls { ... }`.
+6. For tap-to-select, pass a `selection:` binding.
 
-### 4. Get directions and display a route
+### 2. Follow the user's position
 
-1. Create an `MKDirections.Request` with source and destination `MKMapItem`.
-2. Set `transportType` (`.automobile`, `.walking`, `.transit`, `.cycling`).
-3. Await `MKDirections.calculate()`.
-4. Draw the route with `MapPolyline(route.polyline)`.
+1. Put a `NSLocationWhenInUseUsageDescription` string in Info.plist.
+2. On iOS 18 and later, create a `CLServiceSession` when the feature starts
+   and keep it until the feature ends; it drives the authorization prompt.
+3. Iterate `CLLocationUpdate.liveUpdates()` inside a `Task` that you keep.
+4. Drop samples that are inaccurate, old or implausible before the UI sees them.
+5. Cancel the task as soon as the feature no longer needs position.
 
-### 5. Review existing map/location code
+### 3. Find places
 
-Run through the Review Checklist at the end of this file.
+1. Feed typed text to an `MKLocalSearchCompleter` for suggestions.
+2. Wait at least 300 ms after the last keystroke before updating the query.
+3. Turn the picked suggestion into an `MKLocalSearch.Request` for full results.
+4. Show the `MKMapItem` results as markers, a list, or both.
 
-## SwiftUI Map View (iOS 17+)
+### 4. Route between two places
+
+1. Build an `MKDirections.Request` with a source and destination `MKMapItem`.
+2. Choose a mode in `transportType` (car, walking, transit or cycling).
+3. `try await MKDirections(request:).calculate()`.
+4. Draw `MapPolyline(route.polyline)`.
+
+### 5. Review existing code
+
+Go through the [Review Checklist](#review-checklist) below.
+
+## SwiftUI Map (iOS 17+)
+
+A SwiftUI map file imports both `SwiftUI` and `MapKit`.
 
 ```swift
-import MapKit
 import SwiftUI
+import MapKit
 
-struct PlaceMap: View {
-    @State private var position: MapCameraPosition = .automatic
+struct TrailheadMap: View {
+    @State private var camera: MapCameraPosition = .automatic
+
+    private let lot = CLLocationCoordinate2D(latitude: 46.852, longitude: -121.760)
+    private let summit = CLLocationCoordinate2D(latitude: 46.853, longitude: -121.727)
 
     var body: some View {
-        Map(position: $position) {
-            Marker("Apple Park", coordinate: applePark)
-            Marker("Infinite Loop", systemImage: "building.2",
-                   coordinate: infiniteLoop)
+        Map(position: $camera) {
+            Marker("Parking", coordinate: lot)
+            Marker("Summit", systemImage: "mountain.2.fill", coordinate: summit)
         }
         .mapStyle(.standard(elevation: .realistic))
         .mapControls {
@@ -93,173 +115,175 @@ struct PlaceMap: View {
 }
 ```
 
-### Marker and Annotation
+### Marker or Annotation
 
-```swift
-// Balloon marker -- simplest way to pin a location
-Marker("Cafe", systemImage: "cup.and.saucer.fill", coordinate: cafeCoord)
-    .tint(.brown)
+- `Marker(_:systemImage:coordinate:)` draws the system balloon. It is the
+  cheapest way to flag a spot, VoiceOver reads its title, and `.tint(_:)`
+  recolours it.
+- `Annotation(_:coordinate:anchor:content:)` puts any SwiftUI view at a
+  coordinate. `anchor` is a `UnitPoint`; `.bottom` makes the bottom edge of
+  the view touch the coordinate, which suits pin-shaped content.
 
-// Annotation -- custom SwiftUI view at a coordinate
-Annotation("You", coordinate: userCoord, anchor: .bottom) {
-    Image(systemName: "figure.wave")
+```swift
+Annotation("Ranger station", coordinate: station, anchor: .bottom) {
+    Image(systemName: "house.fill")
         .padding(6)
-        .background(.blue.gradient, in: .circle)
         .foregroundStyle(.white)
+        .background(Circle().fill(.green.gradient))
 }
 ```
 
-### Overlays: Polyline, Polygon, Circle
+### Overlays
 
-```swift
-Map {
-    // Polyline from coordinates
-    MapPolyline(coordinates: routeCoords)
-        .stroke(.blue, lineWidth: 4)
-
-    // Polygon (area highlight)
-    MapPolygon(coordinates: parkBoundary)
-        .foregroundStyle(.green.opacity(0.3))
-        .stroke(.green, lineWidth: 2)
-
-    // Circle (radius around a point)
-    MapCircle(center: storeCoord, radius: 500)
-        .foregroundStyle(.red.opacity(0.15))
-        .stroke(.red, lineWidth: 1)
-}
-```
+| Content | Draws | Styling |
+|---------|-------|---------|
+| `MapPolyline(coordinates:)` | a line through the points | `.stroke(.orange, lineWidth: 4)` |
+| `MapPolygon(coordinates:)` | a filled area | `.foregroundStyle(.teal.opacity(0.25))` plus `.stroke(...)` for the edge |
+| `MapCircle(center:radius:)` | a circle, radius in metres | `.foregroundStyle(...)` and `.stroke(...)` |
 
-### Camera Position
+### Camera position
 
-`MapCameraPosition` controls what the map displays. Bind it to let the user
-interact and to programmatically move the camera. Initialize it with `.region`,
-`.userLocation(fallback:)`, `.camera`, `.item`, `.rect`, or `.automatic`. See
-[references/mapkit-patterns.md](references/mapkit-patterns.md) ("Camera Control") for the position
-initializers, animated fly-to, framing content, and reading the visible region.
+`MapCameraPosition` is what the map is showing. Bound to the map, it moves
+when the user pans and moves the map when code assigns it. Its constructors:
+`.region`, `.userLocation(fallback:)`, `.camera`, `.item`, `.rect`,
+`.automatic`. Animated moves, framing all content and reading the visible
+region are in [Camera Control](references/mapkit-patterns.md#camera-control).
 
-### Map Style
+### Map styles
 
-```swift
-.mapStyle(.standard)                                        // Default road map
-.mapStyle(.standard(elevation: .realistic, showsTraffic: true))
-.mapStyle(.imagery)                                         // Satellite
-.mapStyle(.imagery(elevation: .realistic))                  // 3D satellite
-.mapStyle(.hybrid)                                          // Satellite + labels
-.mapStyle(.hybrid(elevation: .realistic, showsTraffic: true))
-```
+| Modifier | Result |
+|----------|--------|
+| `.mapStyle(.standard)` | default road map |
+| `.mapStyle(.standard(elevation: .realistic, showsTraffic: true))` | roads, 3D terrain, live traffic |
+| `.mapStyle(.imagery)` | satellite |
+| `.mapStyle(.imagery(elevation: .realistic))` | satellite in 3D |
+| `.mapStyle(.hybrid)` | satellite with labels |
+| `.mapStyle(.hybrid(elevation: .realistic, showsTraffic: true))` | labelled satellite, 3D terrain, live traffic |
 
-### Map Interaction Modes
+### Interaction modes
 
-```swift
-.mapInteractionModes(.all)           // Default: pan, zoom, rotate, pitch
-.mapInteractionModes(.pan)           // Pan only
-.mapInteractionModes([.pan, .zoom])  // Pan and zoom
-.mapInteractionModes([])             // Static map (no interaction)
-```
+| Modifier | Allows |
+|----------|--------|
+| `.mapInteractionModes(.all)` | pan, zoom, rotate, pitch (the default) |
+| `.mapInteractionModes(.pan)` | panning only |
+| `.mapInteractionModes([.pan, .zoom])` | moving and zooming, no rotation or tilt |
+| `.mapInteractionModes([])` | nothing; a static picture |
+
+### Selection
 
-### Map Selection
+The value in `.tag(_:)` must have the same type as the `selection` binding,
+or taps select nothing.
 
 ```swift
-@State private var selectedMarker: MKMapItem?
+struct CampsiteMap: View {
+    let sites: [Campsite]
+    @State private var chosen: MKMapItem?
+    @State private var headline = ""
 
-Map(selection: $selectedMarker) {
-    ForEach(places) { place in
-        Marker(place.name, coordinate: place.coordinate)
-            .tag(place.mapItem)     // Tag must match selection type
+    var body: some View {
+        Map(selection: $chosen) {
+            ForEach(sites) { site in
+                Marker(site.name, coordinate: site.coordinate)
+                    .tag(site.mapItem)
+            }
+        }
+        .onChange(of: chosen) { _, item in
+            guard let item else { return }
+            headline = item.name ?? ""
+        }
     }
 }
-.onChange(of: selectedMarker) { _, newValue in
-    guard let item = newValue else { return }
-    // React to selection
-}
 ```
 
-## CoreLocation Modern API
+## CoreLocation
 
 ### CLLocationUpdate.liveUpdates() (iOS 17+)
 
-Replace `CLLocationManagerDelegate` callbacks with a single async sequence.
-Each iteration yields a `CLLocationUpdate` containing an optional `CLLocation`.
-On iOS 18+, handle diagnostic states such as denied authorization, globally
-disabled Location Services, unavailable location, and insufficient in-use
-conditions with a visible degraded path instead of silently waiting forever.
-Store the task so the feature can cancel it, and reject invalid, inaccurate,
-stale, or unusable movement data before driving map UI or background work.
+One async sequence replaces the `CLLocationManagerDelegate` callbacks. Each
+element is a `CLLocationUpdate` whose `location` is optional. Rules:
+
+- Store the iterating `Task` in a property; cancelling it is how tracking stops.
+- Throw away samples with invalid or poor accuracy, old timestamps or
+  impossible jumps before they touch map UI or background work.
+- On iOS 18 and later the update also carries diagnostics (authorization
+  denied, Location Services off system-wide, location unavailable, app not
+  sufficiently in use). React with a visible fallback instead of waiting on a
+  sequence that will not deliver.
 
 ```swift
 import CoreLocation
+import Observation
 
 @MainActor
 @Observable
-final class LocationTracker {
-    var currentLocation: CLLocation?
-    private var updateTask: Task<Void, Never>?
+final class RunTracker {
+    private(set) var lastFix: CLLocation?
+    private var stream: Task<Void, Never>?
 
-    func startTracking() {
-        updateTask = Task {
+    func begin() {
+        stream?.cancel()
+        stream = Task {
             do {
-                let updates = CLLocationUpdate.liveUpdates()
-                for try await update in updates {
-                    guard let location = update.location else { continue }
-                    // Filter by horizontal accuracy
-                    guard location.horizontalAccuracy >= 0,
-                          location.horizontalAccuracy < 50 else { continue }
-                    currentLocation = location
+                for try await reading in CLLocationUpdate.liveUpdates() {
+                    guard let fix = reading.location,
+                          fix.horizontalAccuracy >= 0,
+                          fix.horizontalAccuracy < 50 else { continue }
+                    lastFix = fix
                 }
             } catch is CancellationError {
-                // Expected when tracking stops.
             } catch {
-                currentLocation = nil
+                lastFix = nil
             }
         }
     }
 
-    func stopTracking() {
-        updateTask?.cancel()
-        updateTask = nil
+    func end() {
+        stream?.cancel()
+        stream = nil
     }
 }
 ```
 
+Diagnostics, the full filter set and a mapping from each state to UI are in
+the [location reference](references/mapkit-corelocation-patterns.md#diagnostics-and-fallbacks-ios-18).
+
 ### CLServiceSession (iOS 18+)
 
-Declare authorization requirements for a feature's lifetime. Hold a reference
-to the session for as long as you need location services.
+A `CLServiceSession` states what authorization a feature needs, for as long
+as the feature runs. Store it in a property and release it when the feature
+ends. On iOS 18 `liveUpdates()` and `CLMonitor` create a session implicitly
+when you have not; create one yourself when you need `.always` or full
+accuracy. It is not available on macOS.
 
 ```swift
-// When-in-use authorization with full accuracy preference
-let session = CLServiceSession(
+@available(iOS 18, *)
+let nearbySession = CLServiceSession(
     authorization: .whenInUse,
-    fullAccuracyPurposeKey: "NearbySearchPurpose"
+    fullAccuracyPurposeKey: "NearbyTrails"
 )
-// Hold `session` as a stored property; release it when done.
 ```
 
-On iOS 18+, `CLLocationUpdate.liveUpdates()` and `CLMonitor` take an implicit
-`CLServiceSession` if you do not create one explicitly. Create one explicitly
-when you need `.always` authorization or full accuracy.
+### Authorization
 
-### Authorization Flow
+- `NSLocationWhenInUseUsageDescription` is required for any location use.
+- `NSLocationAlwaysAndWhenInUseUsageDescription` only when the feature truly
+  needs `.always`.
 
-```swift
-// Info.plist keys (required):
-// NSLocationWhenInUseUsageDescription
-// NSLocationAlwaysAndWhenInUseUsageDescription (only if .always needed)
+A denied user should see why the feature is empty and a way out:
 
-// Check authorization and guide user to Settings when denied
-struct LocationPermissionView: View {
+```swift
+struct LocationOffView: View {
     @Environment(\.openURL) private var openURL
 
     var body: some View {
         ContentUnavailableView {
-            Label("Location Access Denied", systemImage: "location.slash")
+            Label("Location is off", systemImage: "location.slash")
         } description: {
-            Text("Enable location access in Settings to use this feature.")
+            Text("Allow location access to see trails near you.")
         } actions: {
             Button("Open Settings") {
-                if let url = URL(string: UIApplication.openSettingsURLString) {
-                    openURL(url)
-                }
+                guard let settings = URL(string: UIApplication.openSettingsURLString) else { return }
+                openURL(settings)
             }
         }
     }
@@ -268,164 +292,168 @@ struct LocationPermissionView: View {
 
 ## Geocoding
 
-### CLGeocoder (iOS 8+)
+### MKGeocodingRequest and MKReverseGeocodingRequest (iOS 26+)
+
+MapKit now geocodes by itself and returns `MKMapItem`, which carries more than
+a placemark: an `MKAddress` and `MKAddressRepresentations` for formatting.
+Both initializers are failable; `mapItems` is an async throwing property.
 
 ```swift
-let geocoder = CLGeocoder()
+@available(iOS 26, *)
+func lookUp(_ text: String) async throws -> MKMapItem? {
+    guard let request = MKGeocodingRequest(addressString: text) else { return nil }
+    return try await request.mapItems.first
+}
+```
+
+Reverse lookup is `MKReverseGeocodingRequest(location:)`. Formatting and
+batch lookups are in [Geocoding and Places on iOS 26](references/mapkit-patterns.md#geocoding-and-places-on-ios-26).
+
+### CLGeocoder (iOS 5 to iOS 25, deprecated in iOS 26)
 
-// Forward geocoding: address string -> coordinates
-let placemarks = try await geocoder.geocodeAddressString("1 Apple Park Way, Cupertino")
-if let location = placemarks.first?.location {
-    print(location.coordinate) // CLLocationCoordinate2D
+Use it only while the deployment target is below iOS 26. Every `CLPlacemark`
+field is optional. `CLGeocoder` is not `Sendable`, so Swift 6 rejects one
+shared global instance; make a geocoder for each lookup instead.
+
+```swift
+func coordinate(for address: String) async throws -> CLLocationCoordinate2D? {
+    try await CLGeocoder().geocodeAddressString(address).first?.location?.coordinate
 }
 
-// Reverse geocoding: coordinates -> placemark
-let location = CLLocation(latitude: 37.3349, longitude: -122.0090)
-let placemarks = try await geocoder.reverseGeocodeLocation(location)
-if let placemark = placemarks.first {
-    let address = [placemark.name, placemark.locality, placemark.administrativeArea]
+func label(for spot: CLLocation) async throws -> String {
+    let marks = try await CLGeocoder().reverseGeocodeLocation(spot)
+    guard let mark = marks.first else { return "" }
+    return [mark.name, mark.locality, mark.administrativeArea]
         .compactMap { $0 }
         .joined(separator: ", ")
 }
 ```
 
-### MKGeocodingRequest and MKReverseGeocodingRequest (iOS 26+)
-
-New MapKit-native geocoding returns `MKMapItem` with richer data and `MKAddress`
-/ `MKAddressRepresentations` for flexible address formatting. Construct
-`MKGeocodingRequest(addressString:)` or `MKReverseGeocodingRequest(location:)` and
-await `.mapItems`. See [references/mapkit-patterns.md](references/mapkit-patterns.md) ("iOS 26 New
-APIs") for both, plus `MKAddressRepresentations` formatting.
-
 ## Search
 
-### MKLocalSearchCompleter (Autocomplete)
-
-Set `queryFragment` on an `MKLocalSearchCompleter` and read `results` from its
-delegate for suggestions. Debounce input (300ms+) and constrain `completer.region`
-to the visible map region.
+### MKLocalSearchCompleter (autocomplete)
 
-### MKLocalSearch (Full Search)
+Set `queryFragment` and read `results` from the delegate. Debounce input by
+300 ms or more and set `completer.region` to the visible map region so
+suggestions stay local.
 
-Convert a selected completion (or a natural-language query) into full `MKMapItem`
-results:
+### MKLocalSearch (full results)
 
 ```swift
-func search(for completion: MKLocalSearchCompletion) async throws -> [MKMapItem] {
-    let request = MKLocalSearch.Request(completion: completion)
+func places(for pick: MKLocalSearchCompletion) async throws -> [MKMapItem] {
+    let request = MKLocalSearch.Request(completion: pick)
     request.resultTypes = [.pointOfInterest, .address]
-    let response = try await MKLocalSearch(request: request).start()
-    return response.mapItems
+    let reply = try await MKLocalSearch(request: request).start()
+    return reply.mapItems
 }
 ```
 
-For a natural-language query, set `request.naturalLanguageQuery` and
-`request.region` instead. See [references/mapkit-patterns.md](references/mapkit-patterns.md) ("Search
-with Autocomplete") for the full completer delegate class and a `.searchable`
-view integration.
+For free text, set `request.naturalLanguageQuery` and `request.region`
+instead of passing a completion. The delegate-based service and the
+`.searchable` screen are in
+[Autocomplete Search](references/mapkit-patterns.md#autocomplete-search).
 
 ## Directions
 
+`MKMapItem` and `MKRoute` are not `Sendable`. Keep the helper on the main
+actor, where the SwiftUI view that calls it already runs, so the items never
+cross an isolation boundary:
+
 ```swift
-func getDirections(from source: MKMapItem, to destination: MKMapItem,
-                   transport: MKDirectionsTransportType = .automobile) async throws -> MKRoute? {
+@MainActor
+func fastestRoute(
+    from start: MKMapItem,
+    to end: MKMapItem,
+    by mode: MKDirectionsTransportType = .automobile
+) async throws -> MKRoute? {
     let request = MKDirections.Request()
-    request.source = source
-    request.destination = destination
-    request.transportType = transport
-    let directions = MKDirections(request: request)
-    let response = try await directions.calculate()
-    return response.routes.first
+    request.source = start
+    request.destination = end
+    request.transportType = mode
+    let reply = try await MKDirections(request: request).calculate()
+    return reply.routes.first
 }
 ```
 
-### Display Route on Map
+### Drawing the route
 
 ```swift
-@State private var route: MKRoute?
+struct FerryRouteMap: View {
+    let pier: MKMapItem
+    let island: MKMapItem
+    @State private var route: MKRoute?
 
-Map {
-    if let route {
-        MapPolyline(route.polyline)
-            .stroke(.blue, lineWidth: 5)
+    var body: some View {
+        Map {
+            if let route {
+                MapPolyline(route.polyline).stroke(.teal, lineWidth: 5)
+            }
+            Marker(item: pier)
+            Marker(item: island)
+        }
+        .task { route = try? await fastestRoute(from: pier, to: island) }
     }
-    Marker("Start", coordinate: startCoord)
-    Marker("End", coordinate: endCoord)
-}
-.task {
-    route = try? await getDirections(from: startItem, to: endItem)
 }
 ```
 
-### ETA and Cycling Directions
+### Travel time only, and cycling
 
-For travel time only, use `MKDirections.calculateETA()` (returns
-`expectedTravelTime` without route geometry). For bike routes, set
-`request.transportType = .cycling` (iOS 14+). See
-[references/mapkit-patterns.md](references/mapkit-patterns.md) ("ETA Calculation" and "Cycling
-Directions") for both.
+- `MKDirections.calculateETA()` returns `expectedTravelTime` without route
+  geometry; use it when a label is all you need
+  ([ETA Calculation](references/mapkit-patterns.md#eta-calculation)).
+- Bike routes: `request.transportType = .cycling`, iOS 14 and later
+  ([Cycling Directions](references/mapkit-patterns.md#cycling-directions-ios-14)).
 
 ## PlaceDescriptor (iOS 26+)
 
-Create rich place references from coordinates or addresses without needing a
-Place ID. Requires `import GeoToolbox`.
+`PlaceDescriptor`, from `GeoToolbox`, describes a place by coordinate or
+address when you have no MapKit place ID. `MKMapItemRequest` resolves it into
+a full `MKMapItem`.
 
 ```swift
 import GeoToolbox
+import MapKit
 
 @available(iOS 26, *)
-func lookupPlace(name: String, coordinate: CLLocationCoordinate2D) async throws -> MKMapItem {
-    let descriptor = PlaceDescriptor(
-        representations: [.coordinate(coordinate)],
-        commonName: name
-    )
-    let request = MKMapItemRequest(placeDescriptor: descriptor)
-    return try await request.mapItem
+func mapItem(near point: CLLocationCoordinate2D, named name: String) async throws -> MKMapItem {
+    let place = PlaceDescriptor(representations: [.coordinate(point)], commonName: name)
+    return try await MKMapItemRequest(placeDescriptor: place).mapItem
 }
 ```
 
 ## Common Mistakes
 
-**DON'T:** Request always authorization upfront.
-**DO:** Start with when-in-use authorization. On iOS 18+, hold a `CLServiceSession`
-for the feature lifetime; request `.always` only for background features that
-need system relaunch after termination.
-
-**DON'T:** Use `CLLocationManagerDelegate` for simple location fetches on iOS 17+.
-**DO:** Use `CLLocationUpdate.liveUpdates()` async stream for cleaner, more concise code.
-
-**DON'T:** Ignore `CLLocationUpdate` diagnostics such as denied, globally denied, or unavailable location.
-**DO:** Stop or degrade the feature, show recovery UI such as Settings guidance, and keep search/manual flows usable.
-
-**DON'T:** Let `liveUpdates()` run from an unowned task after the map/view is gone.
-**DO:** Store the `Task`, cancel it when the feature stops, and filter invalid, inaccurate, stale, or impossible movement fixes.
-
-**DON'T:** Force-unwrap `CLPlacemark` properties  -  they are all optional.
-**DO:** Use nil-coalescing: `placemark.locality ?? "Unknown"`.
-
-**DON'T:** Fire `MKLocalSearchCompleter` queries on every keystroke.
-**DO:** Debounce with `.task(id: searchText)` + `Task.sleep(for: .milliseconds(300))`.
-
-**DON'T:** Silently fail when location authorization is denied.
-**DO:** Detect `.denied` status and show an alert with a Settings deep link.
-
-**DON'T:** Assume geocoding always succeeds  -  handle empty results and network errors.
+| Mistake | Do instead |
+|---------|-----------|
+| Asking for Always authorization at launch | Start with when-in-use; ask for `.always` only for a background feature that needs relaunch after termination |
+| No `CLServiceSession` on iOS 18+ | Hold one for the life of the feature |
+| A `CLLocationManagerDelegate` just to read position on iOS 17+ | Iterate `liveUpdates()`; less code, same result |
+| Ignoring diagnostics (denied, off system-wide, unavailable) | Switch to a reduced mode, point the user at Settings, and leave search and manual entry usable |
+| `liveUpdates()` in a task nobody owns | Keep the `Task` in a property and cancel it with the screen; filter bad fixes |
+| Force-unwrapping `CLPlacemark` fields | They are all optional: `mark.locality ?? "Unknown"` |
+| Querying the completer on every keystroke | `.task(id: text)` plus `Task.sleep(for: .milliseconds(300))` |
+| Silent failure when denied | Detect `.denied` and offer a Settings link |
+| Assuming geocoding returns something | Plan for zero matches and for being offline |
 
 ## Review Checklist
 
-- [ ] Info.plist has `NSLocationWhenInUseUsageDescription` with specific reason
-- [ ] Authorization denial handled with Settings deep link
-- [ ] `CLLocationUpdate` task cancelled when not needed (battery)
-- [ ] Location accuracy appropriate for the use case
-- [ ] Map annotations use `Identifiable` data with stable IDs
-- [ ] Geocoding errors handled (network failure, no results)
-- [ ] Search completer input debounced
-- [ ] `CLMonitor` limited to 20 conditions, instance kept alive
+- [ ] `NSLocationWhenInUseUsageDescription` is present and names a concrete benefit
+- [ ] A denied user gets an explanation and a Settings deep link
+- [ ] The `CLLocationUpdate` task is cancelled when not needed, to save battery
+- [ ] Requested accuracy matches what the feature needs
+- [ ] Annotation data is `Identifiable` with stable IDs
+- [ ] Geocoding handles network failure and empty results
+- [ ] Completer input is debounced
+- [ ] `CLMonitor` stays at or under 20 conditions and the instance is kept alive
 - [ ] Background location uses `CLBackgroundActivitySession`
-- [ ] Map tested with VoiceOver
-- [ ] Map annotation view models and location UI updates are `@MainActor`-isolated
+- [ ] The map has been tried with VoiceOver
+- [ ] Annotation models and location-driven UI state are `@MainActor`
 
 ## References
 
-- [references/mapkit-patterns.md](references/mapkit-patterns.md)  -  Map setup, annotations, search, routes, clustering, Look Around, snapshots.
-- [references/mapkit-corelocation-patterns.md](references/mapkit-corelocation-patterns.md)  -  CLLocationUpdate, CLMonitor, CLServiceSession, background location, testing.
+- [Map patterns](references/mapkit-patterns.md): map setup,
+  annotations, camera, search, routes, dense maps and clustering, Look Around,
+  snapshots, iOS 26 APIs.
+- [Location patterns](references/mapkit-corelocation-patterns.md):
+  `CLLocationUpdate`, `CLServiceSession`, `CLMonitor`, background location,
+  testing, privacy keys.