@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/shared/external/macos-menubar-tuist-app/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: macos-menubar-tuist-app
+description: Build, refactor, or review SwiftUI macOS menubar apps that use Tuist.
+risk: safe
+source: "Dimillian/Skills (MIT)"
+date_added: "2026-03-25"
+---
+
+# macos-menubar-tuist-app
+
+Build and maintain macOS menubar apps with a Tuist-first workflow and stable launch scripts. Preserve strict architecture boundaries so networking, state, and UI remain testable and predictable.
+
+## When to Use
+
+- When working on LSUIElement menubar utilities built with Tuist and SwiftUI.
+- When you need Tuist manifests, launch scripts, or architecture guidance for a menubar app.
+
+## Core Rules
+
+- Keep the app menubar-only unless explicitly told otherwise. Use `LSUIElement = true` by default.
+- Keep transport and decoding logic outside views. Do not call networking from SwiftUI view bodies.
+- Keep state transitions in a store layer (`@Observable` or equivalent), not in row/view presentation code.
+- Keep model decoding resilient to API drift: optional fields, safe fallbacks, and defensive parsing.
+- Treat Tuist manifests as the source of truth. Do not rely on hand-edited generated Xcode artifacts.
+- Prefer script-based launch for local iteration when `tuist run` is unreliable for macOS target/device resolution.
+- Prefer `tuist xcodebuild build` over raw `xcodebuild` in local run scripts when building generated projects.
+
+## Expected File Shape
+
+Use this placement by default:
+
+- `Project.swift`: app target, settings, resources, `Info.plist` keys
+- `Sources/*Model*.swift`: API/domain models and decoding
+- `Sources/*Client*.swift`: requests, response mapping, transport concerns
+- `Sources/*Store*.swift`: observable state, refresh policy, filtering, caching
+- `Sources/*Menu*View*.swift`: menu composition and top-level UI state
+- `Sources/*Row*View*.swift`: row rendering and lightweight interactions
+- `run-menubar.sh`: canonical local restart/build/launch path
+- `stop-menubar.sh`: explicit stop helper when needed
+
+## Workflow
+
+1. Confirm Tuist ownership
+- Verify `Tuist.swift` and `Project.swift` (or workspace manifests) exist.
+- Read existing run scripts before changing launch behavior.
+
+2. Probe backend behavior before coding assumptions
+- Use `curl` to verify endpoint shape, auth requirements, and pagination behavior.
+- If endpoint ignores `limit/page`, implement full-list handling with local trimming in the store.
+
+3. Implement layers from bottom to top
+- Define/adjust models first.
+- Add or update client request/decoding logic.
+- Update store refresh, filtering, and cache policy.
+- Wire views last.
+
+4. Keep app wiring minimal
+- Keep app entry focused on scene/menu wiring and dependency injection.
+- Avoid embedding business logic in `App` or menu scene declarations.
+
+5. Standardize launch ergonomics
+- Ensure run script restarts an existing instance before relaunching.
+- Ensure run script does not open Xcode as a side effect.
+- Use `tuist generate --no-open` when generation is required.
+- When the run script builds the generated project, prefer `TUIST_SKIP_UPDATE_CHECK=1 tuist xcodebuild build ...` instead of invoking raw `xcodebuild` directly.
+
+## Validation Matrix
+
+Run validations after edits:
+
+```bash
+TUIST_SKIP_UPDATE_CHECK=1 tuist xcodebuild build -scheme <TargetName> -configuration Debug
+```
+
+If launch workflow changed:
+
+```bash
+./run-menubar.sh
+```
+
+If shell scripts changed:
+
+```bash
+bash -n run-menubar.sh
+bash -n stop-menubar.sh
+./run-menubar.sh
+```
+
+## Failure Patterns and Fix Direction
+
+- `tuist run` cannot resolve the macOS destination:
+Use run/stop scripts as canonical local run path.
+
+- Menu UI is laggy or inconsistent after refresh:
+Move derived state and filtering into the store; keep views render-only.
+
+- API payload changes break decode:
+Relax model decoding with optional fields and defaults, then surface missing data safely in UI.
+
+- Feature asks for quick UI patch:
+Trace root cause in model/client/store before changing row/menu presentation.
+
+## Completion Checklist
+
+- Preserve menubar-only behavior unless explicitly changed.
+- Keep network and state logic out of SwiftUI view bodies.
+- Keep Tuist manifests and run scripts aligned with actual build/run flow.
+- Run the validation matrix for touched areas.
+- Report concrete commands run and outcomes.

package/pipeline/skills/shared/external/macos-spm-app-packaging/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: macos-spm-app-packaging
+description: Scaffold, build, sign, and package SwiftPM macOS apps without Xcode projects.
+risk: safe
+source: "Dimillian/Skills (MIT)"
+date_added: "2026-03-25"
+---
+
+# macOS SwiftPM App Packaging (No Xcode)
+
+## Overview
+Bootstrap a complete SwiftPM macOS app folder, then build, package, and run it without Xcode. Use `assets/templates/bootstrap/` for the starter layout and `references/packaging.md` + `references/release.md` for packaging and release details.
+
+## When to Use
+
+- When the user needs a SwiftPM-based macOS app without relying on an Xcode project.
+- When you need packaging, signing, notarization, or appcast guidance for a SwiftPM app.
+
+## Two-Step Workflow
+1) Bootstrap the project folder
+   - Copy `assets/templates/bootstrap/` into a new repo.
+   - Rename `MyApp` in `Package.swift`, `Sources/MyApp/`, and `version.env`.
+   - Customize `APP_NAME`, `BUNDLE_ID`, and versions.
+
+2) Build, package, and run the bootstrapped app
+   - Copy scripts from `assets/templates/` into your repo (for example, `Scripts/`).
+   - Build/tests: `swift build` and `swift test`.
+   - Package: `Scripts/package_app.sh`.
+   - Run: `Scripts/compile_and_run.sh` (preferred) or `Scripts/launch.sh`.
+   - Release (optional): `Scripts/sign-and-notarize.sh` and `Scripts/make_appcast.sh`.
+   - Tag + GitHub release (optional): create a git tag, upload the zip/appcast to the GitHub release, and publish.
+
+## Minimum End-to-End Example
+Shortest path from bootstrap to a running app:
+```bash
+# 1. Copy and rename the skeleton
+cp -R assets/templates/bootstrap/ ~/Projects/MyApp
+cd ~/Projects/MyApp
+sed -i '' 's/MyApp/HelloApp/g' Package.swift version.env
+
+# 2. Copy scripts
+cp assets/templates/package_app.sh Scripts/
+cp assets/templates/compile_and_run.sh Scripts/
+chmod +x Scripts/*.sh
+
+# 3. Build and launch
+swift build
+Scripts/compile_and_run.sh
+```
+
+## Validation Checkpoints
+Run these after key steps to catch failures early before proceeding to the next stage.
+
+**After packaging (`Scripts/package_app.sh`):**
+```bash
+# Confirm .app bundle structure is intact
+ls -R build/HelloApp.app/Contents
+
+# Check that the binary is present and executable
+file build/HelloApp.app/Contents/MacOS/HelloApp
+```
+
+**After signing (`Scripts/sign-and-notarize.sh` or ad-hoc dev signing):**
+```bash
+# Inspect signature and entitlements
+codesign -dv --verbose=4 build/HelloApp.app
+
+# Verify the bundle passes Gatekeeper checks locally
+spctl --assess --type execute --verbose build/HelloApp.app
+```
+
+**After notarization and stapling:**
+```bash
+# Confirm the staple ticket is attached
+stapler validate build/HelloApp.app
+
+# Re-run Gatekeeper to confirm notarization is recognised
+spctl --assess --type execute --verbose build/HelloApp.app
+```
+
+## Common Notarization Failures
+| Symptom | Likely Cause | Recovery |
+|---|---|---|
+| `The software asset has already been uploaded` | Duplicate submission for same version | Bump `BUILD_NUMBER` in `version.env` and repackage. |
+| `Package Invalid: Invalid Code Signing Entitlements` | Entitlements in `.entitlements` file don't match provisioning | Audit entitlements against Apple's allowed set; remove unsupported keys. |
+| `The executable does not have the hardened runtime enabled` | Missing `--options runtime` flag in `codesign` invocation | Edit `sign-and-notarize.sh` to add `--options runtime` to all `codesign` calls. |
+| Notarization hangs / no status email | `xcrun notarytool` network or credential issue | Run `xcrun notarytool history` to check status; re-export App Store Connect API key if expired. |
+| `stapler validate` fails after successful notarization | Ticket not yet propagated | Wait ~60 s, then re-run `xcrun stapler staple`. |
+
+## Templates
+- `assets/templates/package_app.sh`: Build binaries, create the .app bundle, copy resources, sign.
+- `assets/templates/compile_and_run.sh`: Dev loop to kill running app, package, launch.
+- `assets/templates/build_icon.sh`: Generate .icns from an Icon Composer file (requires Xcode install).
+- `assets/templates/sign-and-notarize.sh`: Notarize, staple, and zip a release build.
+- `assets/templates/make_appcast.sh`: Generate Sparkle appcast entries for updates.
+- `assets/templates/setup_dev_signing.sh`: Create a stable dev code-signing identity.
+- `assets/templates/launch.sh`: Simple launcher for a packaged .app.
+- `assets/templates/version.env`: Example version file consumed by packaging scripts.
+- `assets/templates/bootstrap/`: Minimal SwiftPM macOS app skeleton (Package.swift, Sources/, version.env).
+
+## Notes
+- Keep entitlements and signing configuration explicit; edit the template scripts instead of reimplementing.
+- Remove Sparkle steps if you do not use Sparkle for updates.
+- Sparkle relies on the bundle build number (`CFBundleVersion`), so `BUILD_NUMBER` in `version.env` must increase for each update.
+- For menu bar apps, set `MENU_BAR_APP=1` when packaging to emit `LSUIElement` in Info.plist.
+```
+
+---
+
+All 22 SKILL.md files have been fetched and presented above with their complete raw content. The content was retrieved via `curl` directly from `raw.githubusercontent.com` to ensure nothing was summarized or truncated. One note: the **firebase** skill file appears to have a truncated sentence in the original source itself ("You advocate for Firebase w") -- that is how it exists in the repository, not a fetch artifact.

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

@@ -0,0 +1,485 @@
+---
+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."
+---
+
+# 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.
+
+See `references/mapkit-patterns.md` for extended MapKit patterns and
+`references/corelocation-patterns.md` for CoreLocation patterns.
+
+## Contents
+
+- [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)
+
+## Workflow
+
+### 1. Add a map with markers or annotations
+
+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.
+
+### 2. Track user location
+
+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.
+
+### 3. Search for places
+
+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.
+
+### 4. Get directions and display a route
+
+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)`.
+
+### 5. Review existing map/location code
+
+Run through the Review Checklist at the end of this file.
+
+## SwiftUI Map View (iOS 17+)
+
+```swift
+import MapKit
+import SwiftUI
+
+struct PlaceMap: View {
+    @State private var position: MapCameraPosition = .automatic
+
+    var body: some View {
+        Map(position: $position) {
+            Marker("Apple Park", coordinate: applePark)
+            Marker("Infinite Loop", systemImage: "building.2",
+                   coordinate: infiniteLoop)
+        }
+        .mapStyle(.standard(elevation: .realistic))
+        .mapControls {
+            MapUserLocationButton()
+            MapCompass()
+            MapScaleView()
+        }
+    }
+}
+```
+
+### Marker and Annotation
+
+```swift
+// Balloon marker -- simplest way to pin a location
+Marker("Cafe", systemImage: "cup.and.saucer.fill", coordinate: cafeCoord)
+    .tint(.brown)
+
+// Annotation -- custom SwiftUI view at a coordinate
+Annotation("You", coordinate: userCoord, anchor: .bottom) {
+    Image(systemName: "figure.wave")
+        .padding(6)
+        .background(.blue.gradient, in: .circle)
+        .foregroundStyle(.white)
+}
+```
+
+### Overlays: Polyline, Polygon, Circle
+
+```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)
+}
+```
+
+### Camera Position
+
+`MapCameraPosition` controls what the map displays. Bind it to let the user
+interact and to programmatically move the camera.
+
+```swift
+// Center on a region
+@State private var position: MapCameraPosition = .region(
+    MKCoordinateRegion(
+        center: CLLocationCoordinate2D(latitude: 37.334, longitude: -122.009),
+        span: MKCoordinateSpan(latitudeDelta: 0.05, longitudeDelta: 0.05)
+    )
+)
+
+// Follow user location
+@State private var position: MapCameraPosition = .userLocation(fallback: .automatic)
+
+// Specific camera angle (3D perspective)
+@State private var position: MapCameraPosition = .camera(
+    MapCamera(centerCoordinate: applePark, distance: 1000, heading: 90, pitch: 60)
+)
+
+// Frame specific items
+position = .item(MKMapItem.forCurrentLocation())
+position = .rect(MKMapRect(...))
+```
+
+### Map Style
+
+```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))
+```
+
+### Map 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)
+```
+
+### Map Selection
+
+```swift
+@State private var selectedMarker: MKMapItem?
+
+Map(selection: $selectedMarker) {
+    ForEach(places) { place in
+        Marker(place.name, coordinate: place.coordinate)
+            .tag(place.mapItem)     // Tag must match selection type
+    }
+}
+.onChange(of: selectedMarker) { _, newValue in
+    guard let item = newValue else { return }
+    // React to selection
+}
+```
+
+## CoreLocation Modern API
+
+### CLLocationUpdate.liveUpdates() (iOS 17+)
+
+Replace `CLLocationManagerDelegate` callbacks with a single async sequence.
+Each iteration yields a `CLLocationUpdate` containing an optional `CLLocation`.
+
+```swift
+import CoreLocation
+
+@Observable
+final class LocationTracker: @unchecked Sendable {
+    var currentLocation: CLLocation?
+    private var updateTask: Task<Void, Never>?
+
+    func startTracking() {
+        updateTask = Task {
+            let updates = CLLocationUpdate.liveUpdates()
+            for try await update in updates {
+                guard let location = update.location else { continue }
+                // Filter by horizontal accuracy
+                guard location.horizontalAccuracy < 50 else { continue }
+                await MainActor.run {
+                    self.currentLocation = location
+                }
+            }
+        }
+    }
+
+    func stopTracking() {
+        updateTask?.cancel()
+        updateTask = nil
+    }
+}
+```
+
+### 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.
+
+```swift
+// When-in-use authorization with full accuracy preference
+let session = CLServiceSession(
+    authorization: .whenInUse,
+    fullAccuracyPurposeKey: "NearbySearchPurpose"
+)
+// 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 Flow
+
+```swift
+// Info.plist keys (required):
+// NSLocationWhenInUseUsageDescription
+// NSLocationAlwaysAndWhenInUseUsageDescription (only if .always needed)
+
+// Check authorization and guide user to Settings when denied
+struct LocationPermissionView: View {
+    @Environment(\.openURL) private var openURL
+
+    var body: some View {
+        ContentUnavailableView {
+            Label("Location Access Denied", systemImage: "location.slash")
+        } description: {
+            Text("Enable location access in Settings to use this feature.")
+        } actions: {
+            Button("Open Settings") {
+                if let url = URL(string: UIApplication.openSettingsURLString) {
+                    openURL(url)
+                }
+            }
+        }
+    }
+}
+```
+
+## Geocoding
+
+### CLGeocoder (iOS 8+)
+
+```swift
+let geocoder = CLGeocoder()
+
+// 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
+}
+
+// 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]
+        .compactMap { $0 }
+        .joined(separator: ", ")
+}
+```
+
+### MKGeocodingRequest and MKReverseGeocodingRequest (iOS 26+)
+
+New MapKit-native geocoding that returns `MKMapItem` with richer data and
+`MKAddress` / `MKAddressRepresentations` for flexible address formatting.
+
+```swift
+@available(iOS 26, *)
+func reverseGeocode(location: CLLocation) async throws -> MKMapItem? {
+    guard let request = MKReverseGeocodingRequest(location: location) else {
+        return nil
+    }
+    let mapItems = try await request.mapItems
+    return mapItems.first
+}
+
+@available(iOS 26, *)
+func forwardGeocode(address: String) async throws -> [MKMapItem] {
+    guard let request = MKGeocodingRequest(addressString: address) else { return [] }
+    return try await request.mapItems
+}
+```
+
+## Search
+
+### MKLocalSearchCompleter (Autocomplete)
+
+```swift
+@Observable
+final class SearchCompleter: NSObject, MKLocalSearchCompleterDelegate {
+    var results: [MKLocalSearchCompletion] = []
+    var query: String = "" { didSet { completer.queryFragment = query } }
+
+    private let completer = MKLocalSearchCompleter()
+
+    override init() {
+        super.init()
+        completer.delegate = self
+        completer.resultTypes = [.address, .pointOfInterest]
+    }
+
+    func completerDidUpdateResults(_ completer: MKLocalSearchCompleter) {
+        results = completer.results
+    }
+
+    func completer(_ completer: MKLocalSearchCompleter, didFailWithError error: Error) {
+        results = []
+    }
+}
+```
+
+### MKLocalSearch (Full Search)
+
+```swift
+func search(for completion: MKLocalSearchCompletion) async throws -> [MKMapItem] {
+    let request = MKLocalSearch.Request(completion: completion)
+    request.resultTypes = [.pointOfInterest, .address]
+    let search = MKLocalSearch(request: request)
+    let response = try await search.start()
+    return response.mapItems
+}
+
+// Search by natural language query within a region
+func searchNearby(query: String, region: MKCoordinateRegion) async throws -> [MKMapItem] {
+    let request = MKLocalSearch.Request()
+    request.naturalLanguageQuery = query
+    request.region = region
+    let search = MKLocalSearch(request: request)
+    let response = try await search.start()
+    return response.mapItems
+}
+```
+
+## Directions
+
+```swift
+func getDirections(from source: MKMapItem, to destination: MKMapItem,
+                   transport: 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
+}
+```
+
+### Display Route on Map
+
+```swift
+@State private var route: MKRoute?
+
+Map {
+    if let route {
+        MapPolyline(route.polyline)
+            .stroke(.blue, lineWidth: 5)
+    }
+    Marker("Start", coordinate: startCoord)
+    Marker("End", coordinate: endCoord)
+}
+.task {
+    route = try? await getDirections(from: startItem, to: endItem)
+}
+```
+
+### ETA Calculation
+
+```swift
+func getETA(from source: MKMapItem, to destination: MKMapItem) async throws -> TimeInterval {
+    let request = MKDirections.Request()
+    request.source = source
+    request.destination = destination
+    let directions = MKDirections(request: request)
+    let response = try await directions.calculateETA()
+    return response.expectedTravelTime
+}
+```
+
+### Cycling Directions (iOS 26+)
+
+```swift
+@available(iOS 26, *)
+func getCyclingDirections(to destination: MKMapItem) async throws -> MKRoute? {
+    let request = MKDirections.Request()
+    request.source = MKMapItem.forCurrentLocation()
+    request.destination = destination
+    request.transportType = .cycling
+    let directions = MKDirections(request: request)
+    let response = try await directions.calculate()
+    return response.routes.first
+}
+```
+
+## PlaceDescriptor (iOS 26+)
+
+Create rich place references from coordinates or addresses without needing a
+Place ID. Requires `import GeoToolbox`.
+
+```swift
+@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
+}
+```
+
+## Common Mistakes
+
+**DON'T:** Request `.authorizedAlways` upfront — users distrust broad permissions.
+**DO:** Start with `.requestWhenInUseAuthorization()`, escalate to `.always` only when the user enables a background feature.
+
+**DON'T:** Use `CLLocationManagerDelegate` for simple location fetches on iOS 17+.
+**DO:** Use `CLLocationUpdate.liveUpdates()` async stream for cleaner, more concise code.
+
+**DON'T:** Keep location updates running when the map/view is not visible (drains battery).
+**DO:** Use `.task { }` in SwiftUI so updates cancel automatically on disappear.
+
+**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.
+
+## 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
+- [ ] Background location uses `CLBackgroundActivitySession`
+- [ ] Map tested with VoiceOver
+- [ ] Map annotation view models and location UI updates are `@MainActor`-isolated
+
+## References
+
+- `references/mapkit-patterns.md` — Map setup, annotations, search, routes, clustering, Look Around, snapshots.
+- `references/corelocation-patterns.md` — CLLocationUpdate, CLMonitor, CLServiceSession, background location, testing.