Address PR #12 review feedback

Fixed 8 issues identified in review:

1. Optimization API bug: Removed numeric index fallback, only use 'first'/'any' for source and 'last'/'any' for destination
2. Added missing async keyword to getCachedRoute function in AGENTS.md
3. Added missing 'unknown' congestion value to traffic styling match expression
4. Fixed API Limits table: Changed "Up to 3" to "Max 2 alternatives (3 total routes)", clarified Optimization v1 hard limit
5. Fixed skills README alphabetical ordering: moved mapbox-navigation-patterns between maplibre-migration and search-integration

6. Updated iOS Navigation SDK to v3 API:
   - Changed imports: MapboxNavigation → MapboxNavigationUIKit, MapboxCoreNavigation → MapboxNavigationCore
   - Replaced Directions.shared.calculate() callbacks with async/await routingProvider.calculateRoutes()
   - Updated NavigationViewController initialization with navigationRoutes and navigationOptions
   - Replaced MapboxNavigationService with MapboxNavigationProvider
   - Converted NavigationServiceDelegate callbacks to Combine publishers
   - Updated voice guidance configuration to use CoreConfig.ttsConfig

7. Updated Android Navigation SDK to v3 API:
   - Removed NavigationView examples (dropped in v3)
   - Removed api.startArrival() method (not documented)
   - Removed .accessToken() method (removed in v3)
   - Changed onDestroy() to use MapboxNavigationProvider.destroy()
   - Updated to v3-compatible patterns with requestRoutes() and RouteProgressObserver

8. All code examples now use current v3 SDK APIs for both iOS and Android

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: mattpodwysocki

skills/README.md

@@ -9,6 +9,7 @@ This directory contains [Agent Skills](https://agentskills.io) that provide doma
 | [mapbox-geospatial-operations](./mapbox-geospatial-operations/)       | Choosing between offline geometric tools and routing APIs for geospatial operations          |
 | [mapbox-google-maps-migration](./mapbox-google-maps-migration/)       | Migration guide from Google Maps Platform to Mapbox GL JS with API equivalents and patterns  |
 | [mapbox-maplibre-migration](./mapbox-maplibre-migration/)             | Migration guide between Mapbox GL JS and MapLibre GL JS in both directions                   |
+| [mapbox-navigation-patterns](./mapbox-navigation-patterns/)           | Navigation and routing patterns for Directions API and Navigation SDKs                       |
 | [mapbox-search-integration](./mapbox-search-integration/)             | Complete workflow for implementing Mapbox search with discovery questions and best practices |
 | [mapbox-search-patterns](./mapbox-search-patterns/)                   | Choosing the right search tool and parameters for geocoding and POI search                   |
 | [mapbox-web-performance-patterns](./mapbox-web-performance-patterns/) | Performance optimization for Mapbox GL JS (initialization, markers, data loading, memory)    |
@@ -19,7 +20,6 @@ This directory contains [Agent Skills](https://agentskills.io) that provide doma
 | [mapbox-style-patterns](./mapbox-style-patterns/)                     | Common style patterns and layer configurations                                               |
 | [mapbox-style-quality](./mapbox-style-quality/)                       | Style validation, accessibility, optimization                                                |
 | [mapbox-token-security](./mapbox-token-security/)                     | Security best practices for access tokens                                                    |
-| [mapbox-navigation-patterns](./mapbox-navigation-patterns/)           | Navigation and routing patterns for Directions API and Navigation SDKs                       |
 | [mapbox-store-locator-patterns](./mapbox-store-locator-patterns/)     | Store locator and location finder patterns with markers, filtering, and distance calculation |
 
 ## Documentation

skills/mapbox-navigation-patterns/AGENTS.md

@@ -105,30 +105,44 @@ steps.forEach((step) => {
 ### Basic Navigation
 
 ```swift
-import MapboxNavigation
-
-// Define waypoints
-let origin = Waypoint(coordinate: start, name: "Start")
-let destination = Waypoint(coordinate: end, name: "End")
+import MapboxNavigationCore
+import MapboxNavigationUIKit
+
+// Initialize provider
+let mapboxNavigationProvider = MapboxNavigationProvider(
+    coreConfig: CoreConfig(
+        locationSource: .live,
+        ttsConfig: .default  // Voice guidance enabled
+    )
+)
 
-// Request route
-let options = NavigationRouteOptions(waypoints: [origin, destination])
+// Calculate routes with async/await
+Task {
+    do {
+        let options = NavigationRouteOptions(
+            coordinates: [start, end]
+        )
 
-Directions.shared.calculate(options) { (_, result) in
-    switch result {
-    case .success(let response):
-        let route = response.routes!.first!
+        let navigationRoutes = try await mapboxNavigationProvider
+            .mapboxNavigation
+            .routingProvider()
+            .calculateRoutes(options: options)
+            .value
 
         // Show full navigation UI
+        let navigationOptions = NavigationOptions(
+            mapboxNavigation: mapboxNavigationProvider.mapboxNavigation,
+            voiceController: mapboxNavigationProvider.routeVoiceController,
+            eventsManager: mapboxNavigationProvider.eventsManager()
+        )
+
         let navVC = NavigationViewController(
-            for: route,
-            routeIndex: 0,
-            routeOptions: options
+            navigationRoutes: navigationRoutes,
+            navigationOptions: navigationOptions
         )
-        navVC.delegate = self
         present(navVC, animated: true)
 
-    case .failure(let error):
+    } catch {
         print("Error: \(error)")
     }
 }
@@ -137,91 +151,145 @@ Directions.shared.calculate(options) { (_, result) in
 ### Custom Navigation UI
 
 ```swift
-import MapboxCoreNavigation
+import MapboxNavigationCore
+import Combine
 
-// Core navigation without UI
-let service = MapboxNavigationService(
-    routeResponse: response,
-    routeIndex: 0,
-    routeOptions: options
-)
+class CustomNavigation {
+    private let provider: MapboxNavigationProvider
+    private var subscriptions = Set<AnyCancellable>()
 
-service.delegate = self
-service.start()
-
-// Implement NavigationServiceDelegate
-func navigationService(_ service: NavigationService,
-                      didUpdate progress: RouteProgress,
-                      with location: CLLocation,
-                      rawLocation: CLLocation) {
-    // Update your custom UI
-    let instruction = progress.currentLegProgress.currentStepProgress.step.instructions
-    let distance = progress.currentLegProgress.currentStepProgress.distanceRemaining
+    init() {
+        provider = MapboxNavigationProvider(coreConfig: CoreConfig())
+        setupSubscriptions()
+    }
+
+    func setupSubscriptions() {
+        let navigation = provider.mapboxNavigation.navigation()
+
+        // Subscribe to route progress
+        navigation.routeProgress
+            .sink { [weak self] progressState in
+                guard let progress = progressState?.routeProgress else { return }
+                self?.updateUI(progress)
+            }
+            .store(in: &subscriptions)
+
+        // Subscribe to banner instructions
+        navigation.bannerInstructions
+            .removeDuplicates()
+            .sink { [weak self] state in
+                guard let instruction = state.visualInstruction else { return }
+                self?.showInstruction(instruction.primaryInstruction.text)
+            }
+            .store(in: &subscriptions)
+    }
+
+    func updateUI(_ progress: RouteProgress) {
+        let distance = progress.currentLegProgress?.currentStepProgress.distanceRemaining
+        // Update your custom UI
+    }
+
+    func showInstruction(_ text: String) {
+        // Display instruction in custom UI
+    }
 }
 ```
 
 ### Voice Guidance
 
 ```swift
-let voiceController = navigationService.voiceController
-
-// Configure language
-voiceController.locale = Locale(identifier: "en-US")
+// Configure voice via CoreConfig when creating provider
+let provider = MapboxNavigationProvider(
+    coreConfig: CoreConfig(
+        ttsConfig: .default  // or .localOnly, .custom(synthesizer)
+    )
+)
 
-// Control volume
-voiceController.volume = .normal // or .muted, .custom(0.5)
+// Set language via route options
+var options = NavigationRouteOptions(coordinates: [start, end])
+options.locale = Locale(identifier: "es-ES")  // Spanish
+options.distanceMeasurementSystem = .metric
 ```
 
 ## Navigation SDK for Android
 
 ### Basic Navigation
 
 ```kotlin
-import com.mapbox.navigation.dropin.NavigationView
-
-// NavigationView provides complete UI
-val navigationView = findViewById<NavigationView>(R.id.navigationView)
+import com.mapbox.navigation.core.MapboxNavigationProvider
+import com.mapbox.navigation.base.options.NavigationOptions
+import com.mapbox.navigation.base.route.NavigationRouterCallback
+import com.mapbox.geojson.Point
 
-navigationView.api.startArrival(
-    Waypoint.builder()
-        .coordinate(Point.fromLngLat(lng, lat))
-        .name("Destination")
-        .build()
-)
-```
-
-### Custom Navigation UI
-
-```kotlin
-import com.mapbox.navigation.core.MapboxNavigation
-
-// Core navigation
+// Initialize MapboxNavigation
 val mapboxNavigation = MapboxNavigationProvider.create(
-    NavigationOptions.Builder(context)
-        .accessToken(token)
-        .build()
+    NavigationOptions.Builder(context).build()
 )
 
 // Request route
 val routeOptions = RouteOptions.builder()
     .applyDefaultNavigationOptions()
-    .coordinatesList(listOf(origin, destination))
+    .coordinatesList(listOf(
+        Point.fromLngLat(originLng, originLat),
+        Point.fromLngLat(destLng, destLat)
+    ))
     .build()
 
-mapboxNavigation.requestRoutes(routeOptions, callback)
+mapboxNavigation.requestRoutes(
+    routeOptions,
+    object : NavigationRouterCallback {
+        override fun onRoutesReady(
+            routes: List<NavigationRoute>,
+            routerOrigin: String
+        ) {
+            mapboxNavigation.setNavigationRoutes(routes)
+            mapboxNavigation.startTripSession()
+        }
+
+        override fun onFailure(reasons: List<RouterFailure>, routeOptions: RouteOptions) {
+            // Handle failure
+        }
+
+        override fun onCanceled(routeOptions: RouteOptions, routerOrigin: String) {
+            // Handle cancellation
+        }
+    }
+)
+
+// Cleanup
+override fun onDestroy() {
+    super.onDestroy()
+    MapboxNavigationProvider.destroy()
+}
+```
+
+### Custom Navigation UI
+
+```kotlin
+import com.mapbox.navigation.core.trip.session.RouteProgressObserver
 
-// Start navigation
-mapboxNavigation.registerRouteProgressObserver { routeProgress ->
-    // Update UI
+// Register route progress observer
+private val routeProgressObserver = RouteProgressObserver { routeProgress ->
+    // Update custom UI
     val instruction = routeProgress.currentLegProgress
         ?.currentStepProgress?.step
         ?.bannerInstructions?.firstOrNull()?.primary?.text
 
     val distanceRemaining = routeProgress.currentLegProgress
         ?.currentStepProgress?.distanceRemaining
+
+    val durationRemaining = routeProgress.durationRemaining
+}
+
+override fun onStart() {
+    super.onStart()
+    mapboxNavigation.registerRouteProgressObserver(routeProgressObserver)
 }
 
-mapboxNavigation.startTripSession()
+override fun onStop() {
+    super.onStop()
+    mapboxNavigation.unregisterRouteProgressObserver(routeProgressObserver)
+}
 ```
 
 ## Routing Profiles
@@ -240,7 +308,7 @@ mapboxNavigation.startTripSession()
 ```javascript
 const cache = new Map();
 
-function getCachedRoute(start, end) {
+async function getCachedRoute(start, end) {
   const key = `${start}-${end}`;
   const cached = cache.get(key);
 
@@ -324,12 +392,12 @@ const url = `https://api.mapbox.com/directions/v5/mapbox/cycling/${coords}?...`;
 
 ## API Limits
 
-| Feature                | Limit                                  |
-| ---------------------- | -------------------------------------- |
-| **Waypoints**          | 25 max (including start/end)           |
-| **Alternative routes** | Up to 3                                |
-| **Optimization**       | 12 waypoints (free tier), 25 (premium) |
-| **Rate limit**         | 300 requests/minute (default)          |
+| Feature                | Limit                                         |
+| ---------------------- | --------------------------------------------- |
+| **Waypoints**          | 25 max (including start/end)                  |
+| **Alternative routes** | Max 2 alternatives (3 total routes)           |
+| **Optimization**       | 12 waypoints (v1 API hard limit)              |
+| **Rate limit**         | 300 requests/minute (default)                 |
 
 ## Quick Decisions