@mmerterden/multi-agent-pipeline 8.6.2 → 10.0.6

package/pipeline/skills/shared/external/metrickit-diagnostics/references/metrickit-patterns.md

@@ -0,0 +1,180 @@
+# MetricKit Extended Patterns
+
+Overflow reference for the `metrickit` skill. Contains deeper payload analysis, export patterns, custom signpost metrics, and extended launch measurement.
+
+## Contents
+
+- [Call Stack Trees](#call-stack-trees)
+- [Custom Signpost Metrics](#custom-signpost-metrics)
+- [Exporting and Uploading Payloads](#exporting-and-uploading-payloads)
+- [Past Payloads](#past-payloads)
+- [Extended Launch Measurement](#extended-launch-measurement)
+- [Xcode Organizer Integration](#xcode-organizer-integration)
+
+## Call Stack Trees
+
+`MXCallStackTree` is attached to each diagnostic (crash, hang, CPU exception,
+disk write, app launch). Use `jsonRepresentation()` to extract and symbolicate.
+
+```swift
+func handleCrash(_ crash: MXCrashDiagnostic) {
+    let tree = crash.callStackTree
+    let treeJSON = tree.jsonRepresentation()
+
+    let exceptionType = crash.exceptionType
+    let signal = crash.signal
+    let reason = crash.terminationReason
+
+    uploadDiagnostic(
+        type: "crash",
+        exceptionType: exceptionType,
+        signal: signal,
+        reason: reason,
+        callStack: treeJSON
+    )
+}
+
+func handleHang(_ hang: MXHangDiagnostic) {
+    let tree = hang.callStackTree
+    let duration = hang.hangDuration  // Measurement<UnitDuration>
+    uploadDiagnostic(type: "hang", duration: duration, callStack: tree.jsonRepresentation())
+}
+```
+
+The JSON structure contains an array of call stack frames with binary name,
+offset, and address. Symbolicate using `atos` or upload dSYMs to your
+analytics service.
+
+**Availability**: `MXCallStackTree`  -  iOS 14.0+, iPadOS 14.0+,
+Mac Catalyst 14.0+, macOS 12.0+, visionOS 1.0+
+
+## Custom Signpost Metrics
+
+Use `mxSignpost` with a MetricKit log handle to capture custom performance
+intervals. These appear in the daily `MXMetricPayload` under `signpostMetrics`.
+
+### Creating a Log Handle
+
+```swift
+let metricLog = MXMetricManager.makeLogHandle(category: "Networking")
+```
+
+### Emitting Signposts
+
+```swift
+import os
+
+func fetchData() async throws -> Data {
+    mxSignpost(.begin, log: metricLog, name: "DataFetch")
+    let data = try await URLSession.shared.data(from: url).0
+    mxSignpost(.end, log: metricLog, name: "DataFetch")
+
+    return data
+}
+```
+
+For MetricKit custom metrics, create the log with
+`MXMetricManager.makeLogHandle(category:)` and leave the `mxSignpost` overload's
+advanced `dso`, `signpostID`, and `format` parameters at their documented
+defaults.
+
+### Reading Custom Metrics from Payload
+
+```swift
+if let signposts = payload.signpostMetrics {
+    for metric in signposts {
+        let name = metric.signpostName       // "DataFetch"
+        let category = metric.signpostCategory // "Networking"
+        let count = metric.totalCount
+        if let intervalData = metric.signpostIntervalData {
+            let avgMemory = intervalData.averageMemory
+            let cumulativeCPUTime = intervalData.cumulativeCPUTime
+        }
+    }
+}
+```
+
+> The system limits the number of custom signpost metrics per log to reduce
+> on-device overhead. Reserve custom metrics for critical code paths.
+
+## Exporting and Uploading Payloads
+
+Both payload types conform to `NSSecureCoding` and provide
+`jsonRepresentation()` for easy serialization.
+
+```swift
+func persistPayload(_ jsonData: Data, from: Date? = nil, to: Date? = nil) {
+    let fileName = "metrics_\(ISO8601DateFormatter().string(from: Date())).json"
+    let url = FileManager.default.temporaryDirectory.appending(path: fileName)
+    try? jsonData.write(to: url)
+}
+
+func uploadPayloads(_ jsonData: Data) {
+    Task.detached(priority: .utility) {
+        var request = URLRequest(url: URL(string: "https://api.example.com/metrics")!)
+        request.httpMethod = "POST"
+        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
+        request.httpBody = jsonData
+        _ = try? await URLSession.shared.data(for: request)
+    }
+}
+```
+
+## Past Payloads
+
+If the subscriber was not registered when payloads arrived, retrieve them
+using `pastPayloads` and `pastDiagnosticPayloads`. These return reports
+generated since the last allocation of the shared manager instance.
+
+```swift
+let pastMetrics = MXMetricManager.shared.pastPayloads
+let pastDiags = MXMetricManager.shared.pastDiagnosticPayloads
+```
+
+## Extended Launch Measurement
+
+Track post-first-draw setup work (loading databases, restoring state) as part
+of the launch metric using extended launch measurement on iOS 16+, iPadOS 16+,
+Mac Catalyst 16+, macOS 13+, and visionOS 1+.
+
+```swift
+let taskID = MXLaunchTaskID("com.example.app.loadDatabase")
+
+try MXMetricManager.extendLaunchMeasurement(forTaskID: taskID)
+defer { try? MXMetricManager.finishExtendedLaunchMeasurement(forTaskID: taskID) }
+
+restoreCachedState()
+connectInitialSceneData()
+```
+
+Extended launch times appear under `histogrammedExtendedLaunch` in
+`MXAppLaunchMetric`.
+
+Use these throwing type methods on the main thread. Start the first task before
+or during state restoration, or before the first scene becomes active. The
+system supports up to 16 tasks; task windows need to overlap, and extended
+launch measurement ends when all running tasks finish.
+
+## Xcode Organizer Integration
+
+Xcode Organizer shows the same MetricKit data aggregated across all users
+who have opted in to share diagnostics. Use Organizer for trend analysis:
+
+- **Metrics tab**: Battery, performance, and disk-write metrics over time
+- **Regressions tab**: Automatic detection of metric regressions per version
+- **Crashes tab**: Crash logs with symbolicated stack traces
+
+MetricKit on-device collection complements Organizer by letting you route
+raw data to your own backend for custom dashboards, alerting, and filtering
+by user cohort.
+
+## Apple Documentation Links
+
+- [MetricKit framework](https://sosumi.ai/documentation/metrickit)
+- [MXMetricManager](https://sosumi.ai/documentation/metrickit/mxmetricmanager)
+- [MXMetricManagerSubscriber](https://sosumi.ai/documentation/metrickit/mxmetricmanagersubscriber)
+- [MXCallStackTree](https://sosumi.ai/documentation/metrickit/mxcallstacktree)
+- [MXSignpostMetric](https://sosumi.ai/documentation/metrickit/mxsignpostmetric)
+- [MXAppLaunchMetric](https://sosumi.ai/documentation/metrickit/mxapplaunchmetric)
+- [MXCrashDiagnostic](https://sosumi.ai/documentation/metrickit/mxcrashdiagnostic)
+- [Analyzing the performance of your shipping app](https://sosumi.ai/documentation/xcode/analyzing-the-performance-of-your-shipping-app)

package/pipeline/skills/shared/external/musickit-audio/SKILL.md

@@ -3,11 +3,11 @@ name: musickit-audio
 description: "Integrate Apple Music playback, catalog search, and Now Playing metadata using MusicKit and MediaPlayer. Use when adding music search, Apple Music subscription flows, queue management, playback controls, remote command handling, or Now Playing info to iOS apps."
 ---
 
-# MusicKit + MediaPlayer
+# MusicKit
 
 Search the Apple Music catalog, manage playback with `ApplicationMusicPlayer`,
 check subscriptions, and publish Now Playing metadata via `MPNowPlayingInfoCenter`
-and `MPRemoteCommandCenter`. Targets Swift 6.2 / iOS 26+.
+and `MPRemoteCommandCenter`. Targets Swift 6.3 / iOS 26+.
 
 ## Contents
 
@@ -27,9 +27,9 @@ and `MPRemoteCommandCenter`. Targets Swift 6.2 / iOS 26+.
 
 ### Project Configuration
 
-1. Enable the **MusicKit** capability in Xcode (adds the `com.apple.developer.musickit` entitlement)
-2. Add `NSAppleMusicUsageDescription` to Info.plist explaining why the app accesses Apple Music
-3. For background playback, add the `audio` background mode to `UIBackgroundModes`
+1. Enable the **MusicKit App Service** for the app's explicit bundle ID in the Apple Developer portal so MusicKit can generate developer tokens automatically.
+2. Add `NSAppleMusicUsageDescription` to Info.plist explaining why the app accesses the user's media library.
+3. For background playback, add the `audio` background mode to `UIBackgroundModes`.
 
 ### Imports
 
@@ -40,7 +40,9 @@ import MediaPlayer    // MPRemoteCommandCenter, MPNowPlayingInfoCenter
 
 ## Authorization
 
-Request permission before accessing the user's music data or playing Apple Music content. Authorization is a one-time prompt per app install.
+Request permission before accessing the user's music data or playing Apple Music
+content. `request()` presents Apple's consent dialog when necessary; use
+`currentStatus` to read the current setting without prompting.
 
 ```swift
 func requestMusicAccess() async -> MusicAuthorization.Status {
@@ -66,7 +68,9 @@ let current = MusicAuthorization.currentStatus
 
 ## Catalog Search
 
-Use `MusicCatalogSearchRequest` to search the Apple Music catalog. The user must have an Apple Music subscription for full catalog access.
+Use `MusicCatalogSearchRequest` to search the Apple Music catalog. Catalog lookup
+can fetch Apple Music resources, but playback of subscription catalog content
+must still be gated on `MusicSubscription.current.canPlayCatalogContent`.
 
 ```swift
 func searchCatalog(term: String) async throws -> MusicItemCollection<Song> {
@@ -115,6 +119,8 @@ func observeSubscription() async {
 ### Offering Apple Music
 
 Present the Apple Music subscription offer sheet when the user is not subscribed.
+Check `canBecomeSubscriber` first, and pass `MusicSubscriptionOffer.Options` or
+`onLoadCompletion` when the sheet needs contextual metadata or load-error handling.
 
 ```swift
 import MusicKit
@@ -125,9 +131,21 @@ struct MusicOfferView: View {
 
     var body: some View {
         Button("Subscribe to Apple Music") {
-            showOffer = true
+            Task {
+                let subscription = try? await MusicSubscription.current
+                showOffer = subscription?.canBecomeSubscriber == true
+            }
         }
-        .musicSubscriptionOffer(isPresented: $showOffer)
+        .musicSubscriptionOffer(
+            isPresented: $showOffer,
+            options: .default,
+            onLoadCompletion: { error in
+                if let error {
+                    // Surface loading errors in app UI or diagnostics.
+                    print(error)
+                }
+            }
+        )
     }
 }
 ```
@@ -284,17 +302,18 @@ func enableScrubbing() {
 
 ## Common Mistakes
 
-### DON'T: Skip the MusicKit entitlement or usage description
+### DON'T: Skip MusicKit App Service setup or usage description
 
-Without the MusicKit entitlement your app crashes at authorization. Without
-`NSAppleMusicUsageDescription`, App Review rejects the submission.
+Without the MusicKit App Service on the app's explicit bundle ID, automatic
+developer token generation for Apple Music API requests is not configured.
+Without `NSAppleMusicUsageDescription`, the app cannot access the user's media
+library on Apple platforms that require the purpose string.
 
 ```swift
-// WRONG: No entitlement configured
-let status = await MusicAuthorization.request() // Crashes
+// WRONG: MusicKit App Service not enabled for this bundle ID
 
-// CORRECT: Enable MusicKit capability in Xcode first,
-// then add NSAppleMusicUsageDescription to Info.plist
+// CORRECT: Enable MusicKit App Service in the developer portal,
+// set the matching bundle ID, then add NSAppleMusicUsageDescription.
 let status = await MusicAuthorization.request()
 ```
 
@@ -369,10 +388,12 @@ center.skipForwardCommand.isEnabled = false
 
 ## Review Checklist
 
-- [ ] MusicKit capability enabled in Xcode project
+- [ ] MusicKit App Service enabled for the app's explicit bundle ID
 - [ ] `NSAppleMusicUsageDescription` added to Info.plist
 - [ ] `MusicAuthorization.request()` called before any MusicKit access
 - [ ] Subscription checked before attempting catalog playback
+- [ ] `canBecomeSubscriber` checked before presenting a subscription offer
+- [ ] `hasCloudLibraryEnabled` checked before library writes
 - [ ] `ApplicationMusicPlayer` used (not `SystemMusicPlayer`) for app-scoped playback
 - [ ] Background audio mode enabled if music plays in background
 - [ ] Now Playing info updated on every track change (for custom audio)
@@ -384,12 +405,18 @@ center.skipForwardCommand.isEnabled = false
 
 ## References
 
-- Extended patterns (SwiftUI integration, genre browsing, playlist management): `references/musickit-patterns.md`
+- Extended patterns (SwiftUI integration, genre browsing, playlist management): [references/musickit-patterns.md](references/musickit-patterns.md)
 - [MusicKit framework](https://sosumi.ai/documentation/musickit)
+- [Using automatic developer token generation for Apple Music API](https://sosumi.ai/documentation/musickit/using-automatic-token-generation-for-apple-music-api)
 - [MusicAuthorization](https://sosumi.ai/documentation/musickit/musicauthorization)
 - [ApplicationMusicPlayer](https://sosumi.ai/documentation/musickit/applicationmusicplayer)
 - [MusicCatalogSearchRequest](https://sosumi.ai/documentation/musickit/musiccatalogsearchrequest)
 - [MusicSubscription](https://sosumi.ai/documentation/musickit/musicsubscription)
+- [canPlayCatalogContent](https://sosumi.ai/documentation/musickit/musicsubscription/canplaycatalogcontent)
+- [canBecomeSubscriber](https://sosumi.ai/documentation/musickit/musicsubscription/canbecomesubscriber)
+- [hasCloudLibraryEnabled](https://sosumi.ai/documentation/musickit/musicsubscription/hascloudlibraryenabled)
+- [MusicCatalogChartsRequest initializer](https://sosumi.ai/documentation/musickit/musiccatalogchartsrequest/init(genre:kinds:types:))
+- [musicSubscriptionOffer(isPresented:options:onLoadCompletion:)](https://sosumi.ai/documentation/swiftui/view/musicsubscriptionoffer(ispresented:options:onloadcompletion:))
 - [MPRemoteCommandCenter](https://sosumi.ai/documentation/mediaplayer/mpremotecommandcenter)
 - [MPNowPlayingInfoCenter](https://sosumi.ai/documentation/mediaplayer/mpnowplayinginfocenter)
 - [NSAppleMusicUsageDescription](https://sosumi.ai/documentation/bundleresources/information-property-list/nsapplemusicusagedescription)

package/pipeline/skills/shared/external/musickit-audio/evals/evals.json

@@ -0,0 +1,44 @@
+{
+  "skill_name": "musickit",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Audit this proposed MusicKit setup for an iOS 26 app: the team adds a com.apple.developer.musickit entitlement in Xcode, skips NSAppleMusicUsageDescription, calls MusicAuthorization.request() during launch, and says authorization will crash when the entitlement is missing. Write a concise review with corrected setup and authorization guidance.",
+      "expected_output": "A review that replaces the invented entitlement guidance with MusicKit App Service setup for an explicit bundle ID, requires NSAppleMusicUsageDescription, and explains authorization behavior without overstating crashes.",
+      "files": [],
+      "assertions": [
+        "Recommends enabling the MusicKit App Service for the app's explicit bundle ID so automatic developer token generation is configured.",
+        "Requires NSAppleMusicUsageDescription before accessing the user's music data or media library.",
+        "Explains that MusicAuthorization.request() presents the system consent dialog when necessary and currentStatus can be checked without prompting.",
+        "Does not claim that com.apple.developer.musickit is the required iOS app entitlement or that a missing entitlement causes authorization to crash.",
+        "Mentions UIBackgroundModes audio only when the app needs background playback."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Implement focused SwiftUI snippets for a MusicKit search-and-play flow: search Apple Music songs, play a selected catalog song with ApplicationMusicPlayer, and offer Apple Music subscription signup when playback is unavailable.",
+      "expected_output": "Swift snippets that separate catalog search from subscription playback, gate playback on MusicSubscription.current.canPlayCatalogContent, use ApplicationMusicPlayer, and present the Music subscription offer only when the user can become a subscriber.",
+      "files": [],
+      "assertions": [
+        "Uses MusicCatalogSearchRequest for catalog search and does not require subscription just to fetch catalog search results.",
+        "Checks MusicSubscription.current.canPlayCatalogContent before attempting catalog playback.",
+        "Uses ApplicationMusicPlayer.shared with queue assignment and play() for app-scoped playback.",
+        "Checks canBecomeSubscriber before presenting the Apple Music subscription offer.",
+        "Uses musicSubscriptionOffer(isPresented:options:onLoadCompletion:) or accurately notes the options and load-completion parameters for the offer sheet."
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Review a MusicKit implementation that fetches top songs with MusicCatalogChartsRequest(kinds: [.mostPlayed], types: [Song.self]), adds songs and playlists to the user's library without checking cloud library state, and manually updates MPNowPlayingInfoCenter for Apple Music playback. Explain what should change.",
+      "expected_output": "A review that uses the current chart request initializer shape, gates library writes on authorization and iCloud Music Library availability, and keeps Now Playing guidance scoped to custom audio versus MusicKit playback.",
+      "files": [],
+      "assertions": [
+        "Uses or recommends MusicCatalogChartsRequest(genre:kinds:types:) with an explicit genre argument such as nil.",
+        "Checks MusicAuthorization.currentStatus or requests authorization before library mutations.",
+        "Checks MusicSubscription.current.hasCloudLibraryEnabled before adding songs, albums, or playlist entries to the user's library.",
+        "Explains that ApplicationMusicPlayer handles Now Playing metadata automatically for Apple Music content.",
+        "Keeps MediaPlayer guidance limited to custom audio or remote command handling and does not broaden into unrelated AVKit or CarPlay implementation advice."
+      ]
+    }
+  ]
+}

package/pipeline/skills/shared/external/musickit-audio/references/musickit-patterns.md

@@ -1,6 +1,6 @@
 # MusicKit + MediaPlayer Extended Patterns
 
-Overflow reference for the `musickit-audio` skill. Contains advanced patterns that exceed the main skill file's scope.
+Overflow reference for the `musickit` skill. Contains advanced patterns that exceed the main skill file's scope.
 
 ## Contents
 
@@ -13,7 +13,7 @@ Overflow reference for the `musickit-audio` skill. Contains advanced patterns th
 
 ## MusicKit SwiftUI Integration
 
-### Music Player Manager with @Observable
+### Music Player Manager with `@Observable`
 
 ```swift
 import MusicKit
@@ -84,11 +84,11 @@ struct MiniPlayerView: View {
     @Environment(MusicPlayerManager.self) private var manager
 
     var body: some View {
-        HStack(spacing: 12) {
+        HStack {
             if let song = manager.currentSong {
                 if let artwork = song.artwork {
                     ArtworkImage(artwork, width: 44, height: 44)
-                        .clipShape(RoundedRectangle(cornerRadius: 6))
+                        .clipShape(.rect(cornerRadius: 6))
                 }
 
                 VStack(alignment: .leading) {
@@ -139,7 +139,7 @@ struct MusicSearchView: View {
                     HStack {
                         if let artwork = song.artwork {
                             ArtworkImage(artwork, width: 50, height: 50)
-                                .clipShape(RoundedRectangle(cornerRadius: 4))
+                                .clipShape(.rect(cornerRadius: 4))
                         }
                         VStack(alignment: .leading) {
                             Text(song.title)
@@ -178,7 +178,11 @@ struct MusicSearchView: View {
 
 ```swift
 func fetchTopSongs() async throws -> MusicItemCollection<Song> {
-    var request = MusicCatalogChartsRequest(kinds: [.mostPlayed], types: [Song.self])
+    var request = MusicCatalogChartsRequest(
+        genre: nil,
+        kinds: [.mostPlayed],
+        types: [Song.self]
+    )
     request.limit = 50
     let response = try await request.response()
     return response.songCharts.first?.items ?? []
@@ -198,14 +202,26 @@ func fetchSongsByGenre(_ genre: Genre) async throws -> MusicItemCollection<Song>
 
 ## Library Management
 
+Library writes require MusicKit authorization and an enabled iCloud Music Library.
+Check `MusicSubscription.current.hasCloudLibraryEnabled` before adding items or
+modifying playlists.
+
 ### Adding to Library
 
 ```swift
 func addToLibrary(_ song: Song) async throws {
+    guard MusicAuthorization.currentStatus == .authorized else { return }
+    let subscription = try await MusicSubscription.current
+    guard subscription.hasCloudLibraryEnabled else { return }
+
     try await MusicLibrary.shared.add(song)
 }
 
 func addAlbumToLibrary(_ album: Album) async throws {
+    guard MusicAuthorization.currentStatus == .authorized else { return }
+    let subscription = try await MusicSubscription.current
+    guard subscription.hasCloudLibraryEnabled else { return }
+
     try await MusicLibrary.shared.add(album)
 }
 ```
@@ -239,6 +255,10 @@ func fetchPlaylists() async throws -> MusicItemCollection<Playlist> {
 
 ```swift
 func addToPlaylist(_ playlist: Playlist, songs: [Song]) async throws {
+    guard MusicAuthorization.currentStatus == .authorized else { return }
+    let subscription = try await MusicSubscription.current
+    guard subscription.hasCloudLibraryEnabled else { return }
+
     try await MusicLibrary.shared.add(songs, to: playlist)
 }
 ```

package/pipeline/skills/shared/external/natural-language/SKILL.md

@@ -8,10 +8,17 @@ description: "Tokenize, tag, and analyze natural language text using Apple's Nat
 Analyze natural language text for tokenization, part-of-speech tagging, named
 entity recognition, sentiment analysis, language identification, and word/sentence
 embeddings. Translate text between languages with the Translation framework.
-Targets Swift 6.2 / iOS 26+.
+Targets Swift 6.3 / iOS 26+.
 
 > This skill covers two related frameworks: **NaturalLanguage** (`NLTokenizer`, `NLTagger`, `NLEmbedding`) for on-device text analysis, and **Translation** (`TranslationSession`, `LanguageAvailability`) for language translation.
 
+**Scope boundary:** Use this skill after you already have text. It owns
+tokenization, language identification, POS/NER tagging, sentiment, embeddings,
+custom `NLModel` classifiers/taggers, and in-app translation. Hand off OCR to
+`vision-framework`, speech-to-text to `speech-recognition`, UI strings and
+locale formatting to `ios-localization`, and generative summarization or Apple
+Intelligence workflows to `apple-on-device-ai`.
+
 ## Contents
 
 - [Setup](#setup)
@@ -30,7 +37,12 @@ Targets Swift 6.2 / iOS 26+.
 
 Import `NaturalLanguage` for text analysis and `Translation` for language
 translation. No special entitlements or capabilities are required for
-NaturalLanguage. Translation requires iOS 17.4+ / macOS 14.4+.
+NaturalLanguage. Translation has split availability: system translation
+presentation is iOS 17.4+ / macOS 14.4+, while `TranslationSession`,
+`.translationTask()`, `LanguageAvailability`, and batch translation require
+iOS 18+ / macOS 15+.
+Direct `TranslationSession(installedSource:target:)` is the non-UI option, but
+only when the source and target languages are already installed on device.
 
 ```swift
 import NaturalLanguage
@@ -227,12 +239,14 @@ struct TranslatableView: View {
     let text = "Hello, how are you?"
 
     var body: some View {
-        Text(text)
-            .onTapGesture { showTranslation = true }
-            .translationPresentation(
-                isPresented: $showTranslation,
-                text: text
-            )
+        Button { showTranslation = true } label: {
+            Text(text)
+        }
+        .buttonStyle(.plain)
+        .translationPresentation(
+            isPresented: $showTranslation,
+            text: text
+        )
     }
 }
 ```
@@ -244,6 +258,7 @@ Use `.translationTask()` for programmatic translations within a view context.
 ```swift
 struct TranslatingView: View {
     @State private var translatedText = ""
+    @State private var translationErrorMessage: String?
     @State private var configuration: TranslationSession.Configuration?
 
     var body: some View {
@@ -255,8 +270,18 @@ struct TranslatingView: View {
             }
         }
         .translationTask(configuration) { session in
-            let response = try await session.translate("Hello, world!")
-            translatedText = response.targetText
+            do {
+                let response = try await session.translate("Hello, world!")
+                await MainActor.run {
+                    translatedText = response.targetText
+                    translationErrorMessage = nil
+                }
+            } catch {
+                let message = error.localizedDescription
+                await MainActor.run {
+                    translationErrorMessage = message
+                }
+            }
         }
     }
 }
@@ -268,13 +293,17 @@ Translate multiple strings in a single session.
 
 ```swift
 .translationTask(configuration) { session in
-    let requests = texts.enumerated().map { index, text in
-        TranslationSession.Request(sourceText: text,
-                                    clientIdentifier: "\(index)")
-    }
-    let responses = try await session.translations(from: requests)
-    for response in responses {
-        print("\(response.sourceText) -> \(response.targetText)")
+    do {
+        let requests = texts.enumerated().map { index, text in
+            TranslationSession.Request(sourceText: text,
+                                       clientIdentifier: "\(index)")
+        }
+        let responses = try await session.translations(from: requests)
+        for response in responses {
+            print("\(response.sourceText) -> \(response.targetText)")
+        }
+    } catch {
+        // Handle cancellation, unsupported languages, or download refusal.
     }
 }
 ```
@@ -401,7 +430,7 @@ recognizer.processString("chat")
 
 ## References
 
-- Extended patterns (custom models, contextual embeddings, gazetteers): `references/translation-patterns.md`
+- Extended patterns (custom models, contextual embeddings, gazetteers): [references/translation-patterns.md](references/translation-patterns.md)
 - [Natural Language framework](https://sosumi.ai/documentation/naturallanguage)
 - [NLTokenizer](https://sosumi.ai/documentation/naturallanguage/nltokenizer)
 - [NLTagger](https://sosumi.ai/documentation/naturallanguage/nltagger)
@@ -409,4 +438,5 @@ recognizer.processString("chat")
 - [NLLanguageRecognizer](https://sosumi.ai/documentation/naturallanguage/nllanguagerecognizer)
 - [Translation framework](https://sosumi.ai/documentation/translation)
 - [TranslationSession](https://sosumi.ai/documentation/translation/translationsession)
+- [TranslationSession.Strategy](https://sosumi.ai/documentation/translation/translationsession/strategy)
 - [LanguageAvailability](https://sosumi.ai/documentation/translation/languageavailability)

package/pipeline/skills/shared/external/natural-language/evals/evals.json

@@ -0,0 +1,47 @@
+{
+  "skill_name": "natural-language",
+  "evals": [
+    {
+      "id": 0,
+      "name": "text-analysis-pipeline",
+      "prompt": "I'm adding an iOS 26 inbox feature that detects the message language, tokenizes words, extracts people and organizations, computes a sentiment score, and finds semantically similar keywords for search suggestions. Sketch the NaturalLanguage implementation and review checklist.",
+      "expected_output": "A NaturalLanguage implementation outline that uses NLTokenizer, NLLanguageRecognizer, NLTagger, and NLEmbedding accurately, handles language/support limits, and avoids thread-safety and per-token tagger mistakes.",
+      "files": [],
+      "expectations": [
+        "Uses NLTokenizer with the correct token unit and keeps tokenizer/tagger instances confined to one thread or dispatch queue at a time.",
+        "Uses NLLanguageRecognizer with languageConstraints or languageHints when text is short or expected languages are known.",
+        "Uses NLTagger with .nameType, .sentimentScore, and appropriate options such as .omitWhitespace, .omitPunctuation, and .joinNames.",
+        "Treats sentiment and tags as optional and handles unsupported languages or missing tag schemes instead of force-unwrapping.",
+        "Checks NLEmbedding word or sentence embedding availability and does not assume embeddings exist for every language."
+      ]
+    },
+    {
+      "id": 1,
+      "name": "translation-availability-review",
+      "prompt": "Review this SwiftUI translation plan: use the system translation popover on iOS 17.4, use TranslationSession and .translationTask for programmatic batch translation on the same deployment target, prefer .highFidelity because it can use a server, and ignore errors because the framework downloads languages automatically.",
+      "expected_output": "A correction-focused Translation framework review that splits API availability, keeps translation on-device, handles language availability and throwing APIs, and explains SwiftUI and direct-session usage safely.",
+      "files": [],
+      "expectations": [
+        "Separates translationPresentation availability from TranslationSession, translationTask, LanguageAvailability, and batch translation availability.",
+        "Corrects highFidelity/lowLatency guidance without claiming TranslationSession sends content to a server.",
+        "Uses LanguageAvailability status checks and handles .installed, .supported, and .unsupported.",
+        "Wraps TranslationSession throwing calls such as translate, translations(from:), and prepareTranslation in error handling.",
+        "Explains that direct TranslationSession(installedSource:target:) outside SwiftUI requires installed languages, while SwiftUI translationTask can request downloads."
+      ]
+    },
+    {
+      "id": 2,
+      "name": "sibling-boundary-routing",
+      "prompt": "I have one feature request: scan text from a receipt image, transcribe a spoken note, tokenize and identify the language of the resulting text, detect names and sentiment, find semantically similar keywords with embeddings, maybe add a custom text classifier/tagger, translate a summary to Spanish, localize UI strings with String Catalogs (.xcstrings), plurals, RTL, date and currency formatting, and maybe use Apple Intelligence to generate the summary. Which parts belong in the NaturalLanguage skill and which should be handed to sibling skills?",
+      "expected_output": "A boundary-aware routing answer that keeps NaturalLanguage/Translation responsible for text analysis and translation, and routes OCR, speech transcription, localization, and generative summarization to the appropriate sibling skills.",
+      "files": [],
+      "expectations": [
+        "Keeps tokenization, language identification, named entity recognition, sentiment analysis, embeddings, and in-app translation in the natural-language scope.",
+        "Routes receipt-image OCR to the Vision framework skill rather than treating NaturalLanguage as OCR.",
+        "Routes spoken-note transcription to the Speech framework skill rather than treating NaturalLanguage as speech recognition.",
+        "Routes UI strings, String Catalogs, pluralization, and locale-aware formatting to the iOS localization skill.",
+        "Routes Apple Intelligence or generative summarization to the on-device AI skill rather than presenting NaturalLanguage as a generative LLM framework."
+      ]
+    }
+  ]
+}