@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/skills/shared/external/app-intents/references/appintents-advanced.md

@@ -1,13 +1,13 @@
 # App Intents Advanced Reference
 
 Extended App Intents patterns beyond the basics covered in the main skill.
-Covers @Parameter variants, EntityPropertyQuery, assistant schemas, focus
+Covers `@Parameter` variants, EntityPropertyQuery, assistant schemas, focus
 filters, SiriKit migration, error handling, confirmation flows, authentication,
 URL-representable types, and Spotlight indexing.
 
 ## Contents
 
-- [@Parameter Initializer Variants](#parameter-initializer-variants)
+- [`@Parameter Initializer Variants`](#parameter-initializer-variants)
 - [EntityPropertyQuery (Filter and Sort)](#entitypropertyquery-filter-and-sort)
 - [Assistant Schemas (iOS 18+)](#assistant-schemas-ios-18)
 - [Focus Filter Intents](#focus-filter-intents)
@@ -17,12 +17,12 @@ URL-representable types, and Spotlight indexing.
 - [Authentication Policies](#authentication-policies)
 - [URLRepresentableIntent / Entity / Enum (iOS 18+)](#urlrepresentableintent-entity-enum-ios-18)
 - [IndexedEntity for Spotlight (iOS 18+)](#indexedentity-for-spotlight-ios-18)
-- [@ComputedProperty(indexingKey:) for Spotlight (iOS 26+)](#computedpropertyindexingkey-for-spotlight-ios-26)
+- [`@ComputedProperty(indexingKey:) for Spotlight (iOS 26+)`](#computedpropertyindexingkey-for-spotlight-ios-26)
 - [Onscreen Content for Siri (iOS 26+)](#onscreen-content-for-siri-ios-26)
 - [Parameter Summary Builder](#parameter-summary-builder)
 - [Core Spotlight Direct Usage](#core-spotlight-direct-usage)
 
-## @Parameter Initializer Variants
+## `@Parameter` Initializer Variants
 
 ### 1. Basic (String, Bool, URL, Date)
 
@@ -43,8 +43,8 @@ var url: URL?
 ### 2. Numeric with Range and Control Style
 
 ```swift
-@Parameter(title: "Volume", controlStyle: .slider, inclusiveRange: (0, 100))
-var volume: Int
+@Parameter(title: "Volume", controlStyle: .slider, inclusiveRange: (0.0, 100.0))
+var volume: Double
 
 @Parameter(title: "Rating", controlStyle: .stepper, inclusiveRange: (1, 5))
 var rating: Int
@@ -53,7 +53,8 @@ var rating: Int
 var temperature: Double
 ```
 
-Control styles: `.field` (default text field), `.slider`, `.stepper`.
+Numeric controls default to `.stepper`. `Int` supports `.stepper` and `.field`;
+`Double` also supports `.slider`.
 
 ### 3. With Options Provider (Dynamic List)
 
@@ -94,26 +95,29 @@ var contact: ContactEntity
 
 ### 6. Entity Parameter with Query
 
-Specify a custom query for entity resolution:
+Specify one custom query for entity resolution when the entity's `defaultQuery`
+is not the right search behavior:
 
 ```swift
-@Parameter(title: "Trail", query: [TrailStringQuery(), TrailPropertyQuery()])
+@Parameter(title: "Trail", query: TrailStringQuery())
 var trail: TrailEntity
 ```
 
-### 7. Array Parameters with Size Constraints
+### 7. Array Parameters
 
 ```swift
-// Fixed size
-@Parameter(title: "Items", size: 3)
+@Parameter(title: "Items")
 var items: [ItemEntity]
+```
 
-// Per-widget-family size
-@Parameter(
-    title: "Items",
-    size: [.systemSmall: 1, .systemMedium: 3, .systemLarge: 6]
-)
-var items: [ItemEntity]
+Current Apple docs list the old `size:` entity-array initializers as
+deprecated. Prefer a normal array parameter and validate count in `perform()`
+when the action needs a fixed number of values.
+
+```swift
+guard items.count == 3 else {
+    throw $items.needsValueError("Choose exactly three items.")
+}
 ```
 
 ### 8. File Parameters
@@ -186,16 +190,26 @@ The most powerful query variant. Declare filterable properties and sortable
 fields for structured Siri and Shortcuts queries.
 
 ```swift
+enum TrailComparator: Sendable {
+    case nameContains(String)
+    case nameEquals(String)
+    case lengthGreaterThan(Measurement<UnitLength>)
+    case lengthLessThan(Measurement<UnitLength>)
+    case lengthEquals(Measurement<UnitLength>)
+}
+
 struct TrailPropertyQuery: EntityPropertyQuery {
+    typealias ComparatorMappingType = TrailComparator
+
     static var properties = QueryProperties {
         Property(\TrailEntity.$name) {
-            ContainsComparator()
-            EqualToComparator()
+            ContainsComparator { TrailComparator.nameContains($0) }
+            EqualToComparator { TrailComparator.nameEquals($0) }
         }
         Property(\TrailEntity.$trailLength) {
-            GreaterThanComparator()
-            LessThanComparator()
-            EqualToComparator()
+            GreaterThanComparator { TrailComparator.lengthGreaterThan($0) }
+            LessThanComparator { TrailComparator.lengthLessThan($0) }
+            EqualToComparator { TrailComparator.lengthEquals($0) }
         }
     }
 
@@ -205,22 +219,30 @@ struct TrailPropertyQuery: EntityPropertyQuery {
     }
 
     func entities(
-        matching comparators: [EntityQueryComparator],
+        matching comparators: [TrailComparator],
         mode: ComparatorMode,
         sortedBy: [EntityQuerySort<TrailEntity>],
         limit: Int?
     ) async throws -> [TrailEntity] {
         var results = TrailStore.shared.allTrails.map { TrailEntity(from: $0) }
 
-        for comparator in comparators {
-            switch comparator {
-            case let comparator as ContainsComparator<String>:
-                results = results.filter { $0.name.localizedCaseInsensitiveContains(comparator.value) }
-            case let comparator as GreaterThanComparator<Measurement<UnitLength>>:
-                results = results.filter { $0.trailLength > comparator.value }
-            default:
-                break
+        results = results.filter { trail in
+            let matches = comparators.map { comparator in
+                switch comparator {
+                case .nameContains(let value):
+                    trail.name.localizedCaseInsensitiveContains(value)
+                case .nameEquals(let value):
+                    trail.name.localizedStandardCompare(value) == .orderedSame
+                case .lengthGreaterThan(let value):
+                    trail.trailLength > value
+                case .lengthLessThan(let value):
+                    trail.trailLength < value
+                case .lengthEquals(let value):
+                    trail.trailLength == value
+                }
             }
+            guard !matches.isEmpty else { return true }
+            return mode == .and ? matches.allSatisfy { $0 } : matches.contains(true)
         }
 
         if let limit {
@@ -242,20 +264,24 @@ struct TrailPropertyQuery: EntityPropertyQuery {
 }
 ```
 
+The comparator closures map user-supplied values into a query-specific
+`ComparatorMappingType`; `entities(matching:)` receives those mapped values, not
+raw `EntityQueryComparator` objects.
+
 ### Available comparators
 
 | Comparator | Supported Types |
 |---|---|
-| `EqualToComparator` | All comparable types |
-| `NotEqualToComparator` | All comparable types |
-| `ContainsComparator` | `String` |
+| `EqualToComparator` | Equatable properties |
+| `NotEqualToComparator` | Equatable properties |
+| `ContainsComparator` | Sequence properties |
 | `HasPrefixComparator` | `String` |
 | `HasSuffixComparator` | `String` |
-| `GreaterThanComparator` | Numeric, `Date`, `Measurement` |
-| `LessThanComparator` | Numeric, `Date`, `Measurement` |
-| `GreaterThanOrEqualToComparator` | Numeric, `Date`, `Measurement` |
-| `LessThanOrEqualToComparator` | Numeric, `Date`, `Measurement` |
-| `IsBetweenComparator` | Numeric, `Date`, `Measurement` |
+| `GreaterThanComparator` | Comparable properties |
+| `LessThanComparator` | Comparable properties |
+| `GreaterThanOrEqualToComparator` | Comparable properties |
+| `LessThanOrEqualToComparator` | Comparable properties |
+| `IsBetweenComparator` | Comparable properties supported by Shortcuts |
 
 ## Assistant Schemas (iOS 18+)
 
@@ -265,14 +291,10 @@ understands natively. Annotate conforming types with schema macros.
 ### Declaration
 
 ```swift
-// PREFERRED: Newer macro (iOS 18+)
+// Preferred macro (iOS 18+)
 @AppIntent(schema: .photos.openAsset)
 struct OpenPhotoIntent: AppIntent { ... }
 
-// ALSO VALID: @AssistantIntent(schema:) still works but @AppIntent(schema:) is preferred
-@AssistantIntent(schema: .photos.openAsset)
-struct OpenPhotoIntent: AppIntent { ... }
-
 // CORRECT: Using preferred macro
 @AppIntent(schema: .photos.openAsset)
 struct OpenPhotoIntent: AppIntent {
@@ -310,25 +332,31 @@ enum PhotoType: String, AppEnum {
 }
 ```
 
-### Domain catalog (14+ domains)
+Avoid the deprecated `AssistantIntent(schema:)`, `AssistantEntity(schema:)`, and
+`AssistantEnum(schema:)` macros in new code.
+
+### Domain catalog
 
-| Domain | Example Intents | Example Entities |
+Use Xcode completion and the current domain docs for exact schema cases. The
+major Apple domains are:
+
+| Domain | Example actions | Example content |
 |---|---|---|
-| `.books` | openBook, createBookmark | book, audiobook |
-| `.browser` | openTab, createBookmark, searchWeb | tab, bookmark, window |
-| `.camera` | capturePhoto, captureVideo | -- |
-| `.reader` | openDocument, goToPage | document, page |
-| `.files` | openFile, createFile | file |
-| `.assistant` | activate | -- |
-| `.journal` | createEntry, openEntry | entry |
-| `.mail` | openMailbox, sendDraft | account, draft, mailbox, message |
-| `.photos` | openAsset, createAlbum, searchAssets | album, asset, recognizedPerson |
-| `.presentation` | openDocument, addSlide | document, slide, template |
-| `.spreadsheet` | openDocument, addSheet | document, sheet, template |
-| `.system` | search | -- |
-| `.whiteboard` | openBoard, createItem | board, item |
-| `.wordProcessor` | openDocument, addPage | document, page, template |
-| `.visualIntelligence` | semanticContentSearch | -- |
+| Assistant | side-button conversational app launch | -- |
+| Books | open book, create bookmark | book, audiobook |
+| Browser | open tab, create bookmark, search web | tab, bookmark, window |
+| Camera | capture photo, capture video | -- |
+| File management | open, create, move, rename, delete file | file |
+| Journaling | create, update, delete, search entry | journal entry |
+| Mail | open mailbox, send draft | account, draft, mailbox, message |
+| Photos | open asset, create album, search assets | album, asset, person |
+| Presentations | open document, add slide | document, slide, template |
+| Reader | open document, go to page | document, page |
+| Spreadsheet | open document, add sheet | document, sheet, template |
+| System and in-app search | search | -- |
+| Visual intelligence | semantic content search | -- |
+| Whiteboard | open board, create item | board, item |
+| Word processor | open document, add page | document, page, template |
 
 ### isAssistantOnly
 
@@ -338,7 +366,7 @@ also available through other system surfaces:
 ```swift
 @AppIntent(schema: .photos.openAsset)
 struct OpenPhotoIntent: AppIntent {
-    static var isAssistantOnly: Bool { false }  // Also available in Shortcuts
+    static let isAssistantOnly = false  // Also available in Shortcuts
     // ...
 }
 ```
@@ -450,18 +478,15 @@ struct OldSearchIntent: DeprecatedAppIntent {
 ```swift
 func perform() async throws -> some IntentResult {
     guard await PermissionManager.hasPhotoAccess else {
-        throw PermissionRequired(
-            "Photo library access is required.",
-            recoverySuggestion: "Grant access in Settings > Privacy."
-        )
+        throw AppIntentError.PermissionRequired.photos
     }
 
     guard let item = try await fetchItem() else {
-        throw Unrecoverable("The item no longer exists.")
+        throw AppIntentError.Unrecoverable.entityNotFound
     }
 
     guard !requiresManualSetup else {
-        throw UserActionRequired("Open the app to complete setup.")
+        throw AppIntentError.UserActionRequired.accountSetup
     }
 
     return .result()
@@ -470,9 +495,9 @@ func perform() async throws -> some IntentResult {
 
 | Error Type | When to Use |
 |---|---|
-| `PermissionRequired` | Missing OS-level permission |
-| `Unrecoverable` | Fatal -- intent cannot proceed |
-| `UserActionRequired` | User must act in the app |
+| `AppIntentError.PermissionRequired` | Missing OS-level permission |
+| `AppIntentError.Unrecoverable` | Fatal state with no immediate remedy |
+| `AppIntentError.UserActionRequired` | User must sign in, confirm, or set up an account |
 
 ### Parameter-level errors
 
@@ -646,10 +671,8 @@ struct OpenRecipeIntent: URLRepresentableIntent {
 }
 
 extension OpenRecipeIntent {
-    static var urlRepresentation: some URLRepresentation {
-        URLRepresentation {
-            "https://myapp.com/recipes/\(\.$target)"
-        }
+    static var urlRepresentation: URLRepresentation {
+        "https://myapp.com/recipes/\(\.$target)"
     }
 }
 ```
@@ -660,10 +683,8 @@ extension OpenRecipeIntent {
 struct RecipeEntity: URLRepresentableEntity {
     // ... standard AppEntity members ...
 
-    static var urlRepresentation: some URLRepresentation {
-        URLRepresentation {
-            "https://myapp.com/recipes/\(\.id)"
-        }
+    static var urlRepresentation: URLRepresentation {
+        "https://myapp.com/recipes/\(.id)"
     }
 }
 ```
@@ -674,16 +695,16 @@ struct RecipeEntity: URLRepresentableEntity {
 enum RecipeCategory: String, URLRepresentableEnum {
     case breakfast, lunch, dinner
 
-    static var urlRepresentation: some URLRepresentation {
-        URLRepresentation {
-            "https://myapp.com/category/\(\.self)"
-        }
+    static var urlRepresentation: URLRepresentation {
+        "https://myapp.com/category/\(.rawValue)"
     }
 
     // ... standard AppEnum members ...
 }
 ```
 
+URL representations must be universal links, not custom URL schemes.
+
 ## IndexedEntity for Spotlight (iOS 18+)
 
 Conform to `IndexedEntity` to make entities searchable in Spotlight.
@@ -705,16 +726,30 @@ struct ArticleEntity: IndexedEntity {
         DisplayRepresentation(title: "\(title)", subtitle: "\(author)")
     }
 
-    // Custom attribute set for improved search accuracy
-    var attributeSet: CSSearchableItemAttributeSet? {
-        let attrs = CSSearchableItemAttributeSet(contentType: .text)
-        attrs.title = title
+    // Start with defaultAttributeSet to keep displayRepresentation metadata
+    var attributeSet: CSSearchableItemAttributeSet {
+        let attrs = defaultAttributeSet
         attrs.authorNames = [author]
         return attrs
     }
 }
 ```
 
+After creating entities, add instances to a named Spotlight index:
+
+```swift
+try await CSSearchableIndex(name: "Articles").indexAppEntities(articleEntities)
+```
+
+If you return a fresh `CSSearchableItemAttributeSet` from `attributeSet`, add
+the contents of `defaultAttributeSet` yourself when you still need the title,
+subtitle, or image from `displayRepresentation`.
+
+If your app already creates `CSSearchableItem` values, call
+`associateAppEntity(_:priority:)` on the item's attribute set and provide an
+`OpenIntent` for the entity type so Spotlight results can open the right app
+content.
+
 ### Hide specific entities from Spotlight UI
 
 ```swift
@@ -725,10 +760,11 @@ extension ArticleEntity {
 }
 ```
 
-## @ComputedProperty(indexingKey:) for Spotlight (iOS 26+)
+## `@ComputedProperty(indexingKey:)` for Spotlight (iOS 26+)
 
-Use indexing keys on `@Property` and `@ComputedProperty` for structured Spotlight
-metadata without manual `CSSearchableItemAttributeSet` configuration.
+Use indexing keys on `@Property` and `@ComputedProperty` for structured
+Spotlight metadata. The value is a Swift key path into
+`CSSearchableItemAttributeSet`.
 
 ```swift
 struct RecipeEntity: IndexedEntity {
@@ -737,18 +773,18 @@ struct RecipeEntity: IndexedEntity {
 
     var id: String
 
-    @Property(title: "Name", indexingKey: .title)
+    @Property(title: "Name", indexingKey: \.title)
     var name: String
 
     @Property(title: "Cuisine")
     var cuisine: String
 
-    @ComputedProperty(indexingKey: .description)
+    @ComputedProperty(indexingKey: \.contentDescription)
     var summary: String {
         "\(name) -- \(cuisine) cuisine"
     }
 
-    @ComputedProperty(indexingKey: .thumbnailURL)
+    @ComputedProperty(indexingKey: \.thumbnailURL)
     var imageURL: URL? {
         URL(string: "https://myapp.com/images/\(id).jpg")
     }
@@ -760,21 +796,21 @@ struct RecipeEntity: IndexedEntity {
 ```
 
 ```swift
-// WRONG: Manual attributeSet when indexing keys are available (iOS 26+)
+// Avoid duplicating a wrapped property's indexing key in attributeSet
 struct RecipeEntity: IndexedEntity {
-    @Property(title: "Name")
+    @Property(title: "Name", indexingKey: \.title)
     var name: String
 
-    var attributeSet: CSSearchableItemAttributeSet? {
+    var attributeSet: CSSearchableItemAttributeSet {
         let attrs = CSSearchableItemAttributeSet(contentType: .text)
-        attrs.title = name  // Redundant on iOS 26
+        attrs.title = name  // Redundant: @Property already supplies this key
         return attrs
     }
 }
 
-// CORRECT: Use indexingKey for structured metadata (iOS 26+)
+// Prefer indexingKey for metadata already exposed on the entity
 struct RecipeEntity: IndexedEntity {
-    @Property(title: "Name", indexingKey: .title)
+    @Property(title: "Name", indexingKey: \.title)
     var name: String
 }
 ```
@@ -783,11 +819,11 @@ struct RecipeEntity: IndexedEntity {
 
 | Key | Property Type | Purpose |
 |---|---|---|
-| `.title` | `String` | Primary searchable title |
-| `.description` | `String` | Detailed description |
-| `.thumbnailURL` | `URL?` | Thumbnail image |
-| `.keywords` | `[String]` | Additional search terms |
-| `.contentURL` | `URL?` | Content location |
+| `\.title` | `String` | Primary searchable title |
+| `\.contentDescription` | `String` | Detailed description |
+| `\.thumbnailURL` | `URL?` | Thumbnail image |
+| `\.keywords` | `[String]` | Additional search terms |
+| `\.contentURL` | `URL?` | Content location |
 
 ## Onscreen Content for Siri (iOS 26+)
 
@@ -869,14 +905,15 @@ static var parameterSummary: some ParameterSummary {
 Use Core Spotlight directly when you need full control over indexing without
 adopting App Intents, or when targeting iOS versions before IndexedEntity
 (pre-iOS 18). For apps already using App Intents, prefer `IndexedEntity`
-(iOS 18+) or `@ComputedProperty(indexingKey:)` (iOS 26+) instead.
+(iOS 18+) plus `@Property(indexingKey:)` / `@ComputedProperty(indexingKey:)`
+(iOS 26+) where possible.
 
 ### When to Use Core Spotlight Directly vs IndexedEntity
 
 | Approach | When to Use |
 |---|---|
 | `IndexedEntity` (iOS 18+) | App already uses App Intents; entities are also Siri/Shortcuts-visible |
-| `@ComputedProperty(indexingKey:)` (iOS 26+) | Cleaner metadata mapping without manual `CSSearchableItemAttributeSet` |
+| `@ComputedProperty(indexingKey:)` (iOS 26+) | Adds derived metadata to an `IndexedEntity` |
 | Core Spotlight directly | No App Intents adoption; pre-iOS 18 targets; standalone indexing; fine-grained control over expiration, domain grouping, or batch operations |
 
 ### CSSearchableItem and CSSearchableItemAttributeSet
@@ -912,17 +949,17 @@ func makeSearchableItem(
         domainIdentifier: "com.myapp.recipes",
         attributeSet: attributes
     )
-    // Items expire after 30 days by default; customize if needed
+    // Set an expiration date when the default automatic expiration is wrong
     item.expirationDate = Date.now.addingTimeInterval(60 * 60 * 24 * 90)
     return item
 }
 ```
 
-### CSSearchableIndex — Indexing and Deletion
+### CSSearchableIndex  -  Indexing and Deletion
 
-Use `CSSearchableIndex` to add, update, and remove items. The `default()`
-index works for most apps. Use a named index with a protection class for
-sensitive content.
+Use `CSSearchableIndex` to add, update, and remove items. Use a named index in
+production, and add a protection class when indexing sensitive content. Reserve
+`default()` for prototyping and testing.
 
 Docs: [CSSearchableIndex](https://sosumi.ai/documentation/corespotlight/cssearchableindex)
 
@@ -931,26 +968,30 @@ import CoreSpotlight
 
 // Index a single item (add or update)
 func indexItem(_ item: CSSearchableItem) async throws {
-    try await CSSearchableIndex.default().indexSearchableItems([item])
+    let index = CSSearchableIndex(name: "recipes")
+    try await index.indexSearchableItems([item])
 }
 
 // Delete specific items by identifier
 func deleteItems(identifiers: [String]) async throws {
-    try await CSSearchableIndex.default().deleteSearchableItems(
+    let index = CSSearchableIndex(name: "recipes")
+    try await index.deleteSearchableItems(
         withIdentifiers: identifiers
     )
 }
 
 // Delete all items in a domain (e.g., after user deletes a category)
 func deleteItemsInDomain(_ domain: String) async throws {
-    try await CSSearchableIndex.default().deleteSearchableItems(
+    let index = CSSearchableIndex(name: "recipes")
+    try await index.deleteSearchableItems(
         withDomainIdentifiers: [domain]
     )
 }
 
 // Delete everything (e.g., on logout)
 func deleteAllItems() async throws {
-    try await CSSearchableIndex.default().deleteAllSearchableItems()
+    let index = CSSearchableIndex(name: "recipes")
+    try await index.deleteAllSearchableItems()
 }
 ```
 
@@ -987,8 +1028,10 @@ func batchIndexWithState(_ recipes: [Recipe]) async throws {
     let index = CSSearchableIndex(name: "recipes")
 
     // Check where we left off
-    let lastState = try await index.fetchLastClientState()
-    let startOffset = lastState.flatMap { Int(String(data: $0, encoding: .utf8) ?? "") } ?? 0
+    let lastState = try? await index.fetchLastClientState()
+    let startOffset = lastState
+        .flatMap { String(data: $0, encoding: .utf8) }
+        .flatMap(Int.init) ?? 0
 
     let batchSize = 100
     for batch in stride(from: startOffset, to: recipes.count, by: batchSize) {