@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

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

@@ -1,1297 +1,997 @@
-# App Intents Advanced Reference
-
-Extended App Intents patterns beyond the basics covered in the main skill.
-Covers `@Parameter` variants, EntityPropertyQuery, assistant schemas, focus
-filters, SiriKit migration, error handling, confirmation flows, authentication,
-URL-representable types, and Spotlight indexing.
+# App Intents: advanced guide
 
 ## Contents
 
-- [`@Parameter Initializer Variants`](#parameter-initializer-variants)
-- [EntityQuery Variants (Full Examples)](#entityquery-variants-full-examples)
-- [EntityPropertyQuery (Filter and Sort)](#entitypropertyquery-filter-and-sort)
-- [Control Center Widget Implementation](#control-center-widget-implementation)
-- [SnippetIntent Implementation (iOS 26+)](#snippetintent-implementation-ios-26)
-- [Visual Intelligence IntentValueQuery (iOS 26+)](#visual-intelligence-intentvaluequery-ios-26)
-- [Assistant Schemas (iOS 18+)](#assistant-schemas-ios-18)
-- [Focus Filter Intents](#focus-filter-intents)
-- [SiriKit Migration (CustomIntentMigratedAppIntent)](#sirikit-migration-customintentmigratedappintent)
-- [Error Handling and Dialog](#error-handling-and-dialog)
-- [Confirmation Flows](#confirmation-flows)
-- [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)
-- [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
-
-### 1. Basic (String, Bool, URL, Date)
-
-```swift
-@Parameter(title: "Name")
-var name: String
+- [Parameter initializers](#parameter-initializers)
+- [Entity queries](#entity-queries)
+- [EntityPropertyQuery: filter and sort](#entitypropertyquery-filter-and-sort)
+- [Controls](#controls)
+- [Snippets](#snippets)
+- [Visual Intelligence](#visual-intelligence)
+- [Assistant schemas (iOS 18+)](#assistant-schemas-ios-18)
+- [Focus filters](#focus-filters)
+- [Moving off SiriKit](#moving-off-sirikit)
+- [Errors and dialogs](#errors-and-dialogs)
+- [Confirmation](#confirmation)
+- [Authentication](#authentication)
+- [URL representations (iOS 18+)](#url-representations-ios-18)
+- [Spotlight](#spotlight)
+- [Visible content for Siri (iOS 26+)](#visible-content-for-siri-ios-26)
+- [Conditional parameter summaries](#conditional-parameter-summaries)
+- [Core Spotlight without App Intents](#core-spotlight-without-app-intents)
 
-@Parameter(title: "Name", description: "The user's full name")
-var name: String
+## Parameter initializers
 
-@Parameter(title: "Enabled", default: true)
-var enabled: Bool
+### Plain values
 
-@Parameter(title: "Website")
-var url: URL?
+```swift
+@Parameter(title: "Note") var note: String
+@Parameter(title: "Note", description: "Text saved with the entry") var describedNote: String
+@Parameter(title: "Pin to Top", default: true) var pinned: Bool
+@Parameter(title: "Link") var link: URL?
 ```
 
-### 2. Numeric with Range and Control Style
+### Numbers with a range and control style
 
 ```swift
-@Parameter(title: "Volume", controlStyle: .slider, inclusiveRange: (0.0, 100.0))
-var volume: Double
-
-@Parameter(title: "Rating", controlStyle: .stepper, inclusiveRange: (1, 5))
-var rating: Int
-
-@Parameter(title: "Temperature", default: 72.0, inclusiveRange: (60.0, 90.0))
-var temperature: Double
+@Parameter(title: "Mix", controlStyle: .slider, inclusiveRange: (0.0, 100.0)) var mixPercent: Double
+@Parameter(title: "Stars", controlStyle: .stepper, inclusiveRange: (1, 5)) var stars: Int
+@Parameter(title: "Rounds", default: 3, inclusiveRange: (1, 10)) var rounds: Int
 ```
 
-Numeric controls default to `.stepper`. `Int` supports `.stepper` and `.field`;
-`Double` also supports `.slider`.
-
-### 3. With Options Provider (Dynamic List)
+Numeric parameters default to `.stepper`. `Int` offers `.stepper` and `.field`;
+`Double` adds `.slider`.
 
-Provide a dynamic set of options at runtime:
+### Options computed at run time
 
 ```swift
-struct CategoryOptionsProvider: DynamicOptionsProvider {
+struct PlaylistNames: DynamicOptionsProvider {
     func results() async throws -> [String] {
-        await CategoryStore.shared.allNames()
+        await Library.shared.playlistTitles()
     }
 }
 
-@Parameter(title: "Category", optionsProvider: CategoryOptionsProvider())
-var category: String
+@Parameter(title: "Playlist", optionsProvider: PlaylistNames()) var playlist: String
 ```
 
-### 4. With Disambiguation Dialog
-
-Request clarification when the system cannot resolve a value:
+### Prompts for missing and ambiguous values
 
 ```swift
 @Parameter(
-    title: "Size",
-    requestValueDialog: "What size would you like?",
-    requestDisambiguationDialog: "Which size did you mean?"
+    title: "Contact",
+    requestValueDialog: "Who should get the invite?",
+    requestDisambiguationDialog: "Which of these did you mean?"
 )
-var size: CupSize
+var contact: ContactEntity
 ```
 
-### 5. With Resolvers
+### Resolvers
 
-Transform raw input into the target type:
+`resolvers:` takes a result-builder closure of resolver specifications that
+turn raw input into the parameter's type:
 
 ```swift
-@Parameter(title: "Contact", resolvers: [ContactResolver()])
-var contact: ContactEntity
+@Parameter(title: "Guests", resolvers: { IntFromStringResolver() })
+var guests: Int
 ```
 
-### 6. Entity Parameter with Query
+Resolvers such as `IntFromStringResolver`, `IntFromDoubleResolver` or
+`URLFromStringResolver` accept a different input type than the parameter
+stores. The builder is a closure, not an array literal.
+
+### Entity parameter with its own query
 
-Specify one custom query for entity resolution when the entity's `defaultQuery`
-is not the right search behavior:
+When `defaultQuery` searches the wrong way for this intent, supply another one:
 
 ```swift
-@Parameter(title: "Trail", query: TrailStringQuery())
-var trail: TrailEntity
+@Parameter(title: "Plant", query: ThirstyPlantQuery()) var plant: PlantEntity
 ```
 
-### 7. Array Parameters
+### Arrays
 
 ```swift
-@Parameter(title: "Items")
-var items: [ItemEntity]
+@Parameter(title: "Plants") var plants: [PlantEntity]
 ```
 
-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.
+The older `size:` initializers for entity arrays are deprecated. When an intent
+needs an exact count, check it in `perform()`:
 
 ```swift
-guard items.count == 3 else {
-    throw $items.needsValueError("Choose exactly three items.")
+guard plants.count == 2 else {
+    throw $plants.needsValueError("Pick exactly two plants to compare.")
 }
 ```
 
-### 8. File Parameters
+### Files
 
 ```swift
-@Parameter(title: "Document", supportedContentTypes: [.pdf, .plainText])
-var document: IntentFile
-
-@Parameter(title: "Image", supportedContentTypes: [.png, .jpeg])
-var image: IntentFile?
+@Parameter(title: "Manual", supportedContentTypes: [.plainText, .pdf]) var manual: IntentFile
+@Parameter(title: "Cover", supportedContentTypes: [.png, .jpeg]) var cover: IntentFile?
 ```
 
-### 9. Measurement Parameters
+### Measurements
 
 ```swift
-@Parameter(
-    title: "Distance",
-    defaultUnit: .miles,
-    defaultUnitAdjustForLocale: true,
-    supportsNegativeNumbers: false
-)
-var distance: Measurement<UnitLength>
+@Parameter(title: "Route", defaultUnit: .kilometers, defaultUnitAdjustForLocale: true, supportsNegativeNumbers: false)
+var route: Measurement<UnitLength>
 
-@Parameter(title: "Weight", defaultUnit: .kilograms)
-var weight: Measurement<UnitMass>
-
-@Parameter(title: "Temperature", defaultUnit: .fahrenheit)
-var temp: Measurement<UnitTemperature>
+@Parameter(title: "Load", defaultUnit: .kilograms) var load: Measurement<UnitMass>
+@Parameter(title: "Oven", defaultUnit: .fahrenheit) var oven: Measurement<UnitTemperature>
 ```
 
-### 10. Input Connection Behavior
-
-Control how parameters connect to Shortcuts input:
+### Connecting to the previous action
 
 ```swift
-@Parameter(title: "Text", inputConnectionBehavior: .connectToPreviousIntentResult)
-var text: String
+@Parameter(title: "Input", inputConnectionBehavior: .connectToPreviousIntentResult)
+var input: IntentFile
 
-@Parameter(title: "File", inputConnectionBehavior: .optionalIfProvided)
-var file: IntentFile?
+@Parameter(title: "Attachment", inputConnectionBehavior: .never)
+var attachment: IntentFile?
 ```
 
-### Runtime Parameter Methods
+`InputConnectionBehavior` has three cases: `.default`,
+`.connectToPreviousIntentResult` (take the previous Shortcuts action's output)
+and `.never` (do not wire it automatically).
 
-Request values, disambiguation, and confirmation at runtime inside `perform()`:
+### Asking while perform() runs
 
 ```swift
 func perform() async throws -> some IntentResult {
-    // Request a missing value
-    if quantity == nil {
-        throw $quantity.needsValueError("How many would you like?")
+    guard let when = reminderDate else {
+        throw $reminderDate.needsValueError("When should I remind you?")
     }
-
-    // Disambiguate among options
-    let resolved = try await $size.requestDisambiguation(
-        among: [.small, .medium, .large],
-        dialog: "Which size?"
-    )
-
-    // Confirm a value
-    try await $amount.requestConfirmation(for: amount, dialog: "Charge \(amount)?")
-
+    let chosen = try await $plant.requestDisambiguation(among: matches, dialog: "Which plant?")
+    let confirmed = try await $plant.requestConfirmation(for: chosen, dialog: "Use \(chosen.name)?")
+    guard confirmed else { return .result() }
+    await Scheduler.shared.remind(chosen.id, at: when)
     return .result()
 }
 ```
 
-## EntityQuery Variants (Full Examples)
-
-Full implementations of the query variants summarized in the main skill. Variant
-1 (base `EntityQuery`) is shown in the skill; variants 2-4 are below.
+## Entity queries
 
-### EntityStringQuery (free-text search)
+### EntityStringQuery
 
 ```swift
-struct SoupStringQuery: EntityStringQuery {
-    func entities(matching string: String) async throws -> [SoupEntity] {
-        SoupStore.shared.search(string).map { SoupEntity(from: $0) }
+struct RecipeQuery: EntityStringQuery {
+    func entities(matching text: String) async throws -> [RecipeEntity] {
+        await Cookbook.shared.search(text).map(RecipeEntity.init(from:))
     }
-    func entities(for identifiers: [String]) async throws -> [SoupEntity] {
-        SoupStore.shared.soups.filter { identifiers.contains($0.id) }.map { SoupEntity(from: $0) }
+
+    func entities(for ids: [RecipeEntity.ID]) async throws -> [RecipeEntity] {
+        await Cookbook.shared.recipes(withIDs: ids).map(RecipeEntity.init(from:))
     }
 }
 ```
 
-### EnumerableEntityQuery (finite set)
+### EnumerableEntityQuery
 
 ```swift
-struct AllSoupsQuery: EnumerableEntityQuery {
-    func allEntities() async throws -> [SoupEntity] {
-        SoupStore.shared.allSoups.map { SoupEntity(from: $0) }
+struct KitchenTimerQuery: EnumerableEntityQuery {
+    func allEntities() async throws -> [KitchenTimerEntity] {
+        KitchenTimerEntity.presets
     }
-    func entities(for identifiers: [String]) async throws -> [SoupEntity] {
-        SoupStore.shared.soups.filter { identifiers.contains($0.id) }.map { SoupEntity(from: $0) }
+
+    func entities(for ids: [KitchenTimerEntity.ID]) async throws -> [KitchenTimerEntity] {
+        KitchenTimerEntity.presets.filter { ids.contains($0.id) }
     }
 }
 ```
 
-### UniqueAppEntityQuery (singleton, iOS 18+)
-
-Use for single-instance entities like app settings.
+### UniqueAppEntityQuery (iOS 18+)
 
 ```swift
-struct AppSettingsEntity: UniqueAppEntity {
-    static let defaultQuery = AppSettingsQuery()
-    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Settings"
-    var displayRepresentation: DisplayRepresentation { "App Settings" }
+struct PreferencesEntity: UniqueAppEntity {
+    static let defaultQuery = PreferencesQuery()
+    static let typeDisplayRepresentation: TypeDisplayRepresentation = "Preferences"
 
-    var id: String { "app-settings" }
+    let id = "app-preferences"
+    var displayRepresentation: DisplayRepresentation { "Preferences" }
 }
 
-struct AppSettingsQuery: UniqueAppEntityQuery {
-    func uniqueEntity() async throws -> AppSettingsEntity {
-        AppSettingsEntity()
+struct PreferencesQuery: UniqueAppEntityQuery {
+    func uniqueEntity() async throws -> PreferencesEntity {
+        PreferencesEntity()
     }
 }
 ```
 
-## EntityPropertyQuery (Filter and Sort)
+## EntityPropertyQuery: filter and sort
 
-The most powerful query variant. Declare filterable properties and sortable
-fields for structured Siri and Shortcuts queries.
+The most capable query. It declares which properties people can filter on and
+which they can sort by, so Siri and Shortcuts can build structured queries
+("books by this author, newest first").
 
 ```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
+struct BookQuery: EntityPropertyQuery {
+    enum Match: Sendable {
+        case authorIs(String)
+        case titleHasPrefix(String)
+        case pagesOver(Int)
+    }
+    typealias ComparatorMappingType = Match
 
-    static var properties = QueryProperties {
-        Property(\TrailEntity.$name) {
-            ContainsComparator { TrailComparator.nameContains($0) }
-            EqualToComparator { TrailComparator.nameEquals($0) }
-        }
-        Property(\TrailEntity.$trailLength) {
-            GreaterThanComparator { TrailComparator.lengthGreaterThan($0) }
-            LessThanComparator { TrailComparator.lengthLessThan($0) }
-            EqualToComparator { TrailComparator.lengthEquals($0) }
+    static var properties: QueryProperties {
+        QueryProperties {
+            Property(\BookEntity.$author) {
+                EqualToComparator { Match.authorIs($0) }
+            }
+            Property(\BookEntity.$title) {
+                HasPrefixComparator { Match.titleHasPrefix($0) }
+            }
+            Property(\BookEntity.$pages) {
+                GreaterThanComparator { Match.pagesOver($0) }
+            }
         }
     }
 
-    static var sortingOptions = SortingOptions {
-        SortableBy(\TrailEntity.$name)
-        SortableBy(\TrailEntity.$trailLength)
+    static var sortingOptions: SortingOptions {
+        SortingOptions {
+            SortableBy(\BookEntity.$title)
+            SortableBy(\BookEntity.$pages)
+        }
     }
 
     func entities(
-        matching comparators: [TrailComparator],
+        matching comparators: [Match],
         mode: ComparatorMode,
-        sortedBy: [EntityQuerySort<TrailEntity>],
+        sortedBy: [EntityQuerySort<BookEntity>],
         limit: Int?
-    ) async throws -> [TrailEntity] {
-        var results = TrailStore.shared.allTrails.map { TrailEntity(from: $0) }
-
-        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)
+    ) async throws -> [BookEntity] {
+        let shelf = await Shelf.shared.allBooks()
+        let hits = shelf.filter { book in
+            guard !comparators.isEmpty else { return true }
+            let results = comparators.map { passes(book, $0) }
+            return mode == .and ? results.allSatisfy { $0 } : results.contains(true)
         }
+        return limit.map { Array(hits.prefix($0)) } ?? hits
+    }
 
-        if let limit {
-            results = Array(results.prefix(limit))
+    private func passes(_ book: BookEntity, _ match: Match) -> Bool {
+        switch match {
+        case .authorIs(let name): book.author == name
+        case .titleHasPrefix(let start): book.title.hasPrefix(start)
+        case .pagesOver(let count): book.pages > count
         }
-
-        return results
     }
 
-    func entities(for identifiers: [Trail.ID]) async throws -> [TrailEntity] {
-        TrailStore.shared.allTrails
-            .filter { identifiers.contains($0.id) }
-            .map { TrailEntity(from: $0) }
+    func entities(for ids: [BookEntity.ID]) async throws -> [BookEntity] {
+        await Shelf.shared.books(withIDs: ids)
     }
 
-    func suggestedEntities() async throws -> [TrailEntity] {
-        TrailStore.shared.featured.map { TrailEntity(from: $0) }
+    func suggestedEntities() async throws -> [BookEntity] {
+        await Shelf.shared.recentlyOpened()
     }
 }
 ```
 
-The comparator closures map user-supplied values into a query-specific
-`ComparatorMappingType`; `entities(matching:)` receives those mapped values, not
-raw `EntityQueryComparator` objects.
+Each comparator closure converts the person's value into your
+`ComparatorMappingType`. The matching method is therefore handed your own
+`Match` cases rather than `EntityQueryComparator` instances. An empty list
+means match everything; `.and` requires every comparator, otherwise any one is
+enough. Apply `limit` last.
+`properties` and `sortingOptions` are computed. Neither `QueryProperties` nor
+`SortingOptions` is `Sendable`, so Swift 6 rejects them as `static let`.
 
-### Available comparators
+Comparators and what they apply to:
 
-| Comparator | Supported Types |
+| Comparator | Property kind |
 |---|---|
-| `EqualToComparator` | Equatable properties |
-| `NotEqualToComparator` | Equatable properties |
-| `ContainsComparator` | Sequence properties |
-| `HasPrefixComparator` | `String` |
-| `HasSuffixComparator` | `String` |
-| `GreaterThanComparator` | Comparable properties |
-| `LessThanComparator` | Comparable properties |
-| `GreaterThanOrEqualToComparator` | Comparable properties |
-| `LessThanOrEqualToComparator` | Comparable properties |
-| `IsBetweenComparator` | Comparable properties supported by Shortcuts |
-
-## Control Center Widget Implementation
-
-Full `ControlConfigurationIntent` + `ControlWidget` wiring. The configuration
-intent is a parameter contract; state changes run from a separate action intent
-with an appropriate `authenticationPolicy` and `requestConfirmation`.
+| `EqualToComparator`, `NotEqualToComparator` | `Equatable` |
+| `ContainsComparator` | sequences |
+| `HasPrefixComparator`, `HasSuffixComparator` | `String` |
+| `GreaterThanComparator`, `LessThanComparator`, `GreaterThanOrEqualToComparator`, `LessThanOrEqualToComparator` | `Comparable` |
+| `IsBetweenComparator` | `Comparable` types that Shortcuts supports |
+
+## Controls
+
+The configuration intent is only a parameter contract. The change of state
+happens in a separate action intent with a suitable `authenticationPolicy` and
+a confirmation step.
 
 ```swift
-struct LightControlConfig: ControlConfigurationIntent {
-    static var title: LocalizedStringResource = "Light Control"
-    @Parameter(title: "Light", default: .livingRoom) var light: LightEntity
+import WidgetKit
+import SwiftUI
+
+enum GreenhouseZone: String, AppEnum {
+    case nursery, tropical, succulents
+    static let typeDisplayRepresentation: TypeDisplayRepresentation = "Zone"
+    static let caseDisplayRepresentations: [GreenhouseZone: DisplayRepresentation] = [
+        .nursery: "Nursery", .tropical: "Tropical", .succulents: "Succulents",
+    ]
+}
+
+struct MisterControlConfig: ControlConfigurationIntent {
+    static let title: LocalizedStringResource = "Mister"
+
+    @Parameter(title: "Zone", default: .nursery)
+    var zone: GreenhouseZone
 }
 
-struct ToggleLightIntent: AppIntent {
-    static var title: LocalizedStringResource = "Toggle Light"
-    static var authenticationPolicy: IntentAuthenticationPolicy = .requiresAuthentication
+struct SetMisterIntent: SetValueIntent {
+    static let title: LocalizedStringResource = "Set Mister"
+    static let authenticationPolicy: IntentAuthenticationPolicy = .requiresAuthentication
 
-    @Parameter(title: "Light") var light: LightEntity
+    @Parameter(title: "Zone") var zone: GreenhouseZone
+    @Parameter(title: "Running") var value: Bool
+
+    init() {}
+    init(zone: GreenhouseZone) { self.zone = zone }
 
     func perform() async throws -> some IntentResult {
-        try await requestConfirmation(
-            actionName: .toggle,
-            dialog: "Toggle \(light.name)?"
-        )
-        try await LightService.shared.toggle(light.id)
+        try await requestConfirmation(actionName: .set, dialog: "Change the mister in \(zone)?")
+        await Irrigation.shared.setMister(value, in: zone)
         return .result()
     }
 }
 
-struct LightControl: ControlWidget {
+struct MisterControl: ControlWidget {
     var body: some ControlWidgetConfiguration {
-        AppIntentControlConfiguration(kind: "LightControl", intent: LightControlConfig.self) { config in
-            ControlWidgetToggle(config.light.name, isOn: config.light.isOn, action: ToggleLightIntent(light: config.light))
+        AppIntentControlConfiguration(kind: "MisterControl", intent: MisterControlConfig.self) { config in
+            ControlWidgetToggle(
+                "Mister",
+                isOn: Irrigation.shared.isMisting(config.zone),
+                action: SetMisterIntent(zone: config.zone)
+            ) { isOn in
+                Label(isOn ? "On" : "Off", systemImage: "humidifier.and.droplets")
+            }
         }
     }
 }
 ```
 
-Parameters without defaults must be optional on a `ControlConfigurationIntent`.
+Any configuration parameter without a default must be optional. The default
+here is an `AppEnum` case because defaults must be compile-time values.
 
-## SnippetIntent Implementation (iOS 26+)
+## Snippets
 
-Display interactive snippets in system UI. The system may call `perform()`
-multiple times, including after snippet button or toggle actions, so keep
-`SnippetIntent.perform()` side-effect-free and do mutations in the calling
-action intent or a separate button/toggle action.
+`SnippetIntent.perform()` can run several times, for example after each tap
+inside the snippet. Keep it free of side effects and mutate elsewhere.
 
 ```swift
-struct OrderStatusSnippet: SnippetIntent {
-    static var title: LocalizedStringResource = "Order Status"
+struct TimerSnippet: SnippetIntent {
+    static let title: LocalizedStringResource = "Timer Status"
+
+    @Parameter(title: "Timer") var timer: KitchenTimerEntity
+
+    init() {}
+    init(timer: KitchenTimerEntity) { self.timer = timer }
+
     func perform() async throws -> some IntentResult & ShowsSnippetView {
-        let status = await OrderTracker.currentStatus()
-        return .result(view: OrderStatusSnippetView(status: status))
+        let remaining = await Timers.shared.remaining(for: timer.id)
+        return .result(view: TimerSnippetView(name: timer.name, remaining: remaining))
     }
 }
 
-struct CheckOrderStatusIntent: AppIntent {
-    static var title: LocalizedStringResource = "Check Order Status"
+struct StartTimerIntent: AppIntent {
+    static let title: LocalizedStringResource = "Start Timer"
+
+    @Parameter(title: "Timer") var timer: KitchenTimerEntity
+
     func perform() async throws -> some IntentResult & ShowsSnippetIntent {
-        .result(snippetIntent: OrderStatusSnippet())
+        await Timers.shared.start(timer.id)
+        return .result(snippetIntent: TimerSnippet(timer: timer))
     }
 }
 ```
 
-A snippet-only intent is not discoverable in Shortcuts or Spotlight unless
-`isDiscoverable` is `true`.
+`TimerSnippet` is not listed in Shortcuts or Spotlight unless it sets
+`isDiscoverable` to `true`. Declaring `init(timer:)` means `init()` must be
+written out too, since the system still creates intents through it.
 
-## Visual Intelligence IntentValueQuery (iOS 26+)
+## Visual Intelligence
 
-Only one `IntentValueQuery` can take `SemanticContentDescriptor`; use
-`@UnionValue` when one query must return multiple app entity types.
+`SemanticContentDescriptor` comes from the VisualIntelligence framework. Only
+one `IntentValueQuery` can take it; return several entity types through a
+`@UnionValue` enum.
 
 ```swift
+import AppIntents
+import VisualIntelligence
+
 @available(iOS 26, *)
 @UnionValue
-enum ShoppingVisualResult {
-    case product(ProductEntity)
-    case store(StoreEntity)
+enum ShelfMatch {
+    case book(BookEntity)
+    case author(AuthorEntity)
 }
 
 @available(iOS 26, *)
-struct ShoppingVisualQuery: IntentValueQuery {
-    func values(for input: SemanticContentDescriptor) async throws -> [ShoppingVisualResult] {
+struct ShelfLookup: IntentValueQuery {
+    func values(for descriptor: SemanticContentDescriptor) async throws -> [ShelfMatch] {
         try Task.checkCancellation()
-        async let productMatches = ProductStore.shared.matches(
-            labels: input.labels,
-            pixelBuffer: input.pixelBuffer,
-            limit: 5
-        )
-        async let storeMatches = StoreStore.shared.matches(
-            labels: input.labels,
-            pixelBuffer: input.pixelBuffer,
-            limit: 3
-        )
-        let ranked = await rank(productMatches, storeMatches)
+        async let books = Catalog.shared.books(forLabels: descriptor.labels, frame: descriptor.pixelBuffer, limit: 5)
+        async let authors = Catalog.shared.authors(forLabels: descriptor.labels, limit: 3)
+        let ranked = try await Ranker.merge(books: books, authors: authors)
         return Array(ranked.prefix(8))
     }
 }
 ```
 
-Treat `labels` as high-level English descriptors, not exhaustive synonyms or app
-taxonomy; combine them with `pixelBuffer` when available. Return small, ranked,
-cancellation-friendly results, and provide an `OpenIntent`, URL representation,
-or in-app search handoff for details and more results. Do not implement camera
-capture, Vision `VN*` requests, barcode classification, or Spotlight indexing
-inside the App Intents query; call an existing bounded app search or image-match
-service instead, with explicit result caps and timeouts when work may exceed a
-system UI budget.
-
-## Assistant Schemas (iOS 18+)
+- `labels` are broad English descriptions of what was seen. They are not a
+  full synonym list and not your app's taxonomy; combine them with
+  `pixelBuffer` when it is present.
+- Give every result a route to details and more results: an `OpenIntent`, a
+  URL representation, or a handoff to in-app search.
+- Keep heavy work out of the query: no capturing from the camera, no `VN*`
+  Vision requests, no barcode classifying, no Spotlight indexing. Call existing search or image-matching services
+  with explicit result caps, plus timeouts when the work can outlast the
+  system UI's time budget.
 
-Assistant schemas define domain-specific intents that Apple Intelligence
-understands natively. Annotate conforming types with schema macros.
+## Assistant schemas (iOS 18+)
 
-### Declaration
+Schemas are domain-specific shapes that Apple Intelligence understands
+directly. Annotate the matching types:
 
 ```swift
-// Preferred macro (iOS 18+)
-@AppIntent(schema: .photos.openAsset)
-struct OpenPhotoIntent: AppIntent { ... }
-
-// CORRECT: Using preferred macro
 @AppIntent(schema: .photos.openAsset)
-struct OpenPhotoIntent: AppIntent {
-    static var title: LocalizedStringResource = "Open Photo"
-
-    @Parameter(title: "Asset")
-    var target: PhotoEntity
+struct OpenSnapshotIntent: OpenIntent {
+    var target: SnapshotEntity
 
     func perform() async throws -> some IntentResult {
-        PhotoViewer.shared.open(target.id)
+        await Navigator.shared.show(snapshot: target.id)
         return .result()
     }
 }
 
 @AppEntity(schema: .photos.asset)
-struct PhotoEntity: AppEntity {
-    var id: String
-    static let defaultQuery = PhotoQuery()
-    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Photo"
-    var displayRepresentation: DisplayRepresentation {
-        DisplayRepresentation(title: "\(name)")
-    }
-    var name: String
+struct SnapshotEntity: IndexedEntity {
+    static let defaultQuery = SnapshotQuery()
+    let id: String
+    var title: String?
+    var assetType: SnapshotKind?
+    // plus the remaining properties the .photos.asset schema requires
+    var displayRepresentation: DisplayRepresentation { DisplayRepresentation(title: "\(title ?? "Snapshot")") }
 }
 
 @AppEnum(schema: .photos.assetType)
-enum PhotoType: String, AppEnum {
-    case photo, video, livePhoto
-    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Photo Type"
-    static var caseDisplayRepresentations: [PhotoType: DisplayRepresentation] = [
-        .photo: "Photo",
-        .video: "Video",
-        .livePhoto: "Live Photo"
+enum SnapshotKind: String, AppEnum {
+    case photo, video
+    static let caseDisplayRepresentations: [SnapshotKind: DisplayRepresentation] = [
+        .photo: "Photo", .video: "Video",
     ]
 }
 ```
 
-Avoid the deprecated `AssistantIntent(schema:)`, `AssistantEntity(schema:)`, and
-`AssistantEnum(schema:)` macros in new code.
+The schema fixes which properties a type must declare; Xcode's diagnostics
+list any that are missing. Do not use the deprecated `AssistantIntent(schema:)`,
+`AssistantEntity(schema:)` or `AssistantEnum(schema:)` in new code.
 
-### Domain catalog
+### Domains
 
-Use Xcode completion and the current domain docs for exact schema cases. The
-major Apple domains are:
+Exact case names change between releases, so rely on Xcode completion and the
+current domain documentation. Broadly:
 
-| Domain | Example actions | Example content |
+| Domain | Content types | Actions |
 |---|---|---|
-| 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
-
-Control whether a schema-conforming type is exclusive to Apple Intelligence or
-also available through other system surfaces:
+| Assistant | | launching the app for a conversation via the side button |
+| Books | audiobooks, books | bookmarking, opening a title |
+| Browser | windows, tabs, bookmarks | web search, bookmarking, opening a tab |
+| Camera | | taking a photo or a video |
+| File management | files | opening, creating, moving, renaming or deleting |
+| Journaling | journal entries | creating, updating, deleting or searching entries |
+| Mail | messages, mailboxes, drafts, accounts | sending a draft, opening a mailbox |
+| Photos | people, assets, albums | searching assets, making an album, opening an asset |
+| Presentations | templates, slides, documents | adding a slide, opening a document |
+| Reader | pages, documents | jumping to a page, opening a document |
+| Spreadsheet | templates, sheets, documents | adding a sheet, opening a document |
+| Search (system and in-app) | | searching |
+| Visual intelligence | | searching by semantic content |
+| Whiteboard | items, boards | adding an item, opening a board |
+| Word processor | templates, pages, documents | adding a page, opening a document |
+
+### Beyond Apple Intelligence
+
+A schema-conforming type is assistant-only by default. Opt out to keep it in
+Shortcuts and elsewhere:
 
 ```swift
-@AppIntent(schema: .photos.openAsset)
-struct OpenPhotoIntent: AppIntent {
-    static let isAssistantOnly = false  // Also available in Shortcuts
-    // ...
-}
+static let isAssistantOnly = false
 ```
 
-## Focus Filter Intents
+## Focus filters
 
-Customize app behavior when a Focus mode activates.
+`SetFocusFilterIntent` lets the app change its behaviour while a Focus is on.
 
 ```swift
-struct WorkFocusFilter: SetFocusFilterIntent {
-    static var title: LocalizedStringResource = "Work Focus"
-    static var description = IntentDescription("Configure app for work mode.")
-
-    @Parameter(title: "Show Only Work Projects", default: true)
-    var workOnly: Bool
+struct QuietGardenFilter: SetFocusFilterIntent {
+    static let title: LocalizedStringResource = "Garden Alerts"
+    static let description: IntentDescription? = "Choose which garden alerts reach you during this Focus."
 
-    @Parameter(title: "Mute Notifications", default: false)
-    var muteNotifications: Bool
+    @Parameter(title: "Watering Reminders", default: true) var watering: Bool
+    @Parameter(title: "Frost Warnings", default: true) var frost: Bool
 
     var displayRepresentation: DisplayRepresentation {
-        "Work Mode"
+        DisplayRepresentation(title: "Watering \(watering ? "on" : "off"), frost \(frost ? "on" : "off")")
     }
 
     func perform() async throws -> some IntentResult {
-        AppSettings.shared.workModeEnabled = workOnly
-        AppSettings.shared.notificationsMuted = muteNotifications
+        AlertPreferences.shared.apply(watering: watering, frost: frost)
         return .result()
     }
-}
-```
-
-### Access current focus filter
-
-```swift
-let currentFilter = try? SetFocusFilterIntent.current
-if let workFilter = currentFilter as? WorkFocusFilter {
-    // Apply work-mode behavior
-}
-```
 
-### Suggest filters for a focus context
-
-```swift
-extension WorkFocusFilter {
-    static func suggestedFocusFilters(
-        for context: FocusFilterSuggestionContext
-    ) async -> [WorkFocusFilter] {
-        [WorkFocusFilter(workOnly: true, muteNotifications: true)]
+    static func suggestedFocusFilters(for situation: FocusFilterSuggestionContext) async -> [QuietGardenFilter] {
+        let sleep = QuietGardenFilter()
+        sleep.watering = false
+        return [sleep]
     }
 }
+
+// Reading the active filter elsewhere:
+// let active = try? await QuietGardenFilter.current
 ```
 
-## SiriKit Migration (CustomIntentMigratedAppIntent)
+## Moving off SiriKit
 
-Replace SiriKit custom intents (`.intentdefinition` files) while preserving
-existing user shortcuts and donations.
+`CustomIntentMigratedAppIntent` replaces a custom intent from an
+`.intentdefinition` file while keeping the shortcuts and donations people
+already have.
 
 ```swift
-struct OrderSoupIntent: CustomIntentMigratedAppIntent {
-    // Map to the old SiriKit intent class name -- must match exactly
-    static var intentClassName: String = "OrderSoupIntent"
-
-    static var title: LocalizedStringResource = "Order Soup"
+struct ReorderSeedsIntent: AppIntent, CustomIntentMigratedAppIntent {
+    static let intentClassName = "ReorderSeedsIntent"
+    static let title: LocalizedStringResource = "Reorder Seeds"
 
-    @Parameter(title: "Soup")
-    var soup: SoupEntity
-
-    @Parameter(title: "Quantity", default: 1)
-    var quantity: Int
+    @Parameter(title: "Variety") var variety: String
 
     func perform() async throws -> some IntentResult {
-        let order = try await OrderService.shared.place(
-            soup: soup.id,
-            quantity: quantity
-        )
-        return .result(dialog: "Ordered \(quantity) bowls.")
+        try await SeedShop.shared.reorder(variety)
+        return .result()
     }
 }
 ```
 
-### Migration steps
-
-1. Create a new `AppIntent` struct conforming to `CustomIntentMigratedAppIntent`.
-2. Set `intentClassName` to the old SiriKit intent class name (exact match).
-3. Recreate parameters using `@Parameter` instead of `.intentdefinition` props.
-4. Implement `perform()` with async/await.
-5. Existing user shortcuts and donations continue working via the class name.
-6. Remove the `.intentdefinition` file once migration is verified.
+1. Create an `AppIntent` struct that adopts `CustomIntentMigratedAppIntent`.
+2. Set `intentClassName` to exactly the class name the old SiriKit intent
+   generated.
+3. Declare the old properties again as `@Parameter` values.
+4. Write `perform()` with async/await.
+5. Existing shortcuts and donations resolve to the new type through that class
+   name.
+6. Delete the `.intentdefinition` file only once the migration is verified.
 
-### DeprecatedAppIntent (versioning within AppIntents)
-
-Replace an old `AppIntent` with a newer version:
+### Retiring an AppIntent
 
 ```swift
-struct OldSearchIntent: DeprecatedAppIntent {
-    typealias ReplacementIntent = NewSearchIntent
-    static var deprecation: IntentDeprecation {
-        .init(message: "Use the new search intent.")
+struct LegacyWaterIntent: DeprecatedAppIntent {
+    typealias ReplacementIntent = WaterPlantIntent
+    static let title: LocalizedStringResource = "Water (Old)"
+    static var deprecation: IntentDeprecation<WaterPlantIntent> {
+        IntentDeprecation(message: "Use Water Plant instead.", replacedBy: WaterPlantIntent.self)
     }
-    static var title: LocalizedStringResource = "Search (Deprecated)"
+
     func perform() async throws -> some IntentResult { .result() }
 }
 ```
 
-## Error Handling and Dialog
+`IntentDeprecation` also has `init(message:)` for an intent with no
+replacement (its `ReplacementIntent` is then `Never`).
+`deprecation` is computed because `IntentDeprecation` is not `Sendable`; a
+`static let` of it is a Swift 6 error.
+
+## Errors and dialogs
 
-### Standard error types (iOS 18+)
+### Standard errors (iOS 18+)
 
 ```swift
 func perform() async throws -> some IntentResult {
-    guard await PermissionManager.hasPhotoAccess else {
-        throw AppIntentError.PermissionRequired.photos
-    }
-
-    guard let item = try await fetchItem() else {
-        throw AppIntentError.Unrecoverable.entityNotFound
-    }
-
-    guard !requiresManualSetup else {
-        throw AppIntentError.UserActionRequired.accountSetup
-    }
-
+    guard PhotoAccess.isGranted else { throw AppIntentError.PermissionRequired.photos }
+    guard let album = await Albums.shared.find(albumID) else { throw AppIntentError.Unrecoverable.entityNotFound }
+    guard Account.shared.isReady else { throw AppIntentError.UserActionRequired.accountSetup }
+    await Albums.shared.pin(album)
     return .result()
 }
 ```
 
-| Error Type | When to Use |
+| Family | Meaning |
 |---|---|
-| `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 |
+| `AppIntentError.PermissionRequired` | an OS permission is missing |
+| `AppIntentError.Unrecoverable` | a fatal state with no immediate fix |
+| `AppIntentError.UserActionRequired` | something is needed from the person first: signing in, confirming, creating an account |
 
-### Parameter-level errors
+### Parameter errors
 
 ```swift
-// Re-prompt for a value
-throw $quantity.needsValueError("How many items?")
-
-// Force disambiguation
-throw $size.needsDisambiguation(among: [.small, .medium, .large])
+throw $album.needsValueError("Which album?")
+throw $album.needsDisambiguationError(among: candidates, dialog: "Several albums match. Pick one.")
 ```
 
-### Foreground continuation
+### Continuing in the app (iOS 26+)
 
 ```swift
-func perform() async throws -> some IntentResult {
-    if needsUserInteraction {
-        try await continueInForeground("Open the app to finish.")
-    }
-    // ...
-    return .result()
-}
+try await continueInForeground("Finish pairing the sensor in the app.")
 ```
 
-### Dialog in results
+### Dialog in the result
 
 ```swift
 func perform() async throws -> some IntentResult & ProvidesDialog {
-    return .result(dialog: "Your soup order has been placed.")
+    .result(dialog: "Done.")
 }
 
-func perform() async throws -> some IntentResult & ProvidesDialog & ReturnsValue<OrderEntity> {
-    let order = try await placeOrder()
-    return .result(
-        value: OrderEntity(from: order),
-        dialog: "Order #\(order.number) is confirmed."
-    )
+func perform() async throws -> some IntentResult & ProvidesDialog & ReturnsValue<PlantEntity> {
+    .result(value: plant, dialog: "Found \(plant.name).")
 }
 ```
 
-## Confirmation Flows
-
-### Basic confirmation
+## Confirmation
 
 ```swift
-func perform() async throws -> some IntentResult {
-    try await requestConfirmation(
-        actionName: .send,
-        dialog: "Send \(quantity) messages?"
-    )
-    // User confirmed -- proceed
-    return .result()
-}
-```
+try await requestConfirmation(actionName: .pay, dialog: "Pay this invoice?")
 
-### Conditional confirmation
+try await requestConfirmation(conditions: .lowConfidenceSource, actionName: .book, dialog: "Reserve the table?")
 
-```swift
-func perform() async throws -> some IntentResult {
-    try await requestConfirmation(
-        conditions: .always,
-        actionName: .order,
-        dialog: "Place order for \(quantity) \(soup.name)?"
-    )
-    return .result()
+try await requestConfirmation(actionName: .order, dialog: "Order these seeds?") {
+    CartPreview(items: cart)
 }
-```
-
-### Confirmation with SwiftUI content
 
-```swift
-func perform() async throws -> some IntentResult {
-    try await requestConfirmation(
-        actionName: .buy,
-        dialog: "Purchase \(item.name) for \(item.price)?",
-        view: OrderPreviewView(item: item)
-    )
-    return .result()
-}
+let pick = try await requestChoice(between: [.init(title: "Morning"), .init(title: "Evening")],
+                                   dialog: "When should I water?")
 ```
 
-### User choice
+- Execution continues past `requestConfirmation` only once the person agrees.
+- `ConfirmationConditions` currently offers `.lowConfidenceSource`, which asks
+  only when the request came from a low-confidence source. The default empty
+  set always asks.
+- The trailing-closure form (iOS 18, SwiftUI overlay) shows a preview view with
+  the prompt. On iOS 26 a `snippetIntent:` variant shows an interactive
+  snippet instead.
+- `requestChoice(between:dialog:)` (iOS 26) returns the option the person picked.
 
-```swift
-func perform() async throws -> some IntentResult {
-    let chosen = try await requestChoice(
-        between: availableOptions,
-        dialog: "Which option would you like?"
-    )
-    // Use chosen value
-    return .result()
-}
-```
+Built-in action names: `.add`, `.addData`, `.book`, `.buy`, `.call`, `.checkIn`,
+`.continue`, `.create`, `.do`, `.download`, `.filter`, `.find`, `.get`, `.go`,
+`.log`, `.open`, `.order`, `.pay`, `.play`, `.playSound`, `.post`, `.request`,
+`.run`, `.search`, `.send`, `.set`, `.share`, `.start`, `.startNavigation`,
+`.toggle`, `.turnOff`, `.turnOn`, `.view`. For anything else use
+`.custom(acceptLabel:acceptAlternatives:denyLabel:denyAlternatives:destructive:)`.
 
-### ConfirmationActionName options
+## Authentication
 
-Built-in: `.add`, `.buy`, `.call`, `.create`, `.send`, `.share`, `.start`,
-`.toggle`, `.turnOn`, `.turnOff`, `.open`, `.play`, `.post`, `.search`,
-`.book`, `.download`, `.pay`, `.order`, `.run`, `.get`, `.go`, `.log`,
-`.set`, `.view`, `.find`, `.filter`, `.continue`, `.do`, `.addData`,
-`.checkIn`, `.request`, `.playSound`, `.startNavigation`.
+Set a static `authenticationPolicy: IntentAuthenticationPolicy`:
 
-Custom:
-
-```swift
-.custom(
-    acceptLabel: "Confirm Purchase",
-    acceptAlternatives: ["Yes", "Buy it"],
-    denyLabel: "Cancel",
-    denyAlternatives: ["No", "Never mind"],
-    destructive: false
-)
-```
-
-## Authentication Policies
+| Policy | Effect |
+|---|---|
+| `.alwaysAllowed` | runs without authentication |
+| `.requiresAuthentication` | the device must be unlocked before `perform()` |
+| `.requiresLocalDeviceAuthentication` | Face ID or Touch ID is required |
 
-Control when device authentication is required:
+An intent that deletes an account but declares no policy can run from a locked
+device. Give it `.requiresLocalDeviceAuthentication`:
 
 ```swift
-struct TransferMoneyIntent: AppIntent {
-    static var authenticationPolicy: IntentAuthenticationPolicy = .requiresAuthentication
-    static var title: LocalizedStringResource = "Transfer Money"
+struct CloseAccountIntent: AppIntent {
+    static let title: LocalizedStringResource = "Close Account"
+    static let authenticationPolicy: IntentAuthenticationPolicy = .requiresLocalDeviceAuthentication
 
     func perform() async throws -> some IntentResult {
-        // Device must be unlocked before this runs
+        try await Account.shared.close()
         return .result()
     }
 }
 ```
 
-| Policy | Behavior |
-|---|---|
-| `.alwaysAllowed` | No authentication required |
-| `.requiresAuthentication` | Device must be unlocked |
-| `.requiresLocalDeviceAuthentication` | Face ID / Touch ID required |
-
-```swift
-// WRONG: Sensitive action without authentication
-struct DeleteAccountIntent: AppIntent {
-    // Missing authenticationPolicy -- runs on locked device
-    func perform() async throws -> some IntentResult { ... }
-}
-
-// CORRECT: Require authentication for sensitive actions
-struct DeleteAccountIntent: AppIntent {
-    static var authenticationPolicy: IntentAuthenticationPolicy = .requiresLocalDeviceAuthentication
-    static var title: LocalizedStringResource = "Delete Account"
-    func perform() async throws -> some IntentResult { ... }
-}
-```
-
-## URLRepresentableIntent / Entity / Enum (iOS 18+)
+## URL representations (iOS 18+)
 
-Represent intents, entities, and enums as URLs for deep linking.
-
-### URLRepresentableIntent
+Intents, entities and enums can map to deep links.
 
 ```swift
-struct OpenRecipeIntent: URLRepresentableIntent {
-    static var title: LocalizedStringResource = "Open Recipe"
+struct ShowRecipeIntent: URLRepresentableIntent {
+    static let title: LocalizedStringResource = "Show Recipe"
+    static var urlRepresentation: URLRepresentation { "https://example.com/recipes/\(\.$target)" }
 
-    @Parameter(title: "Recipe")
-    var target: RecipeEntity
+    @Parameter(title: "Dish") var target: RecipeEntity
 
-    static var parameterSummary: some ParameterSummary {
-        Summary("Open \(\.$target)")
-    }
+    static var parameterSummary: some ParameterSummary { Summary("Show \(\.$target)") }
 
-    func perform() async throws -> some IntentResult & OpensIntent {
-        return .result()
-    }
+    func perform() async throws -> some IntentResult & OpensIntent { .result() }
 }
 
-extension OpenRecipeIntent {
-    static var urlRepresentation: URLRepresentation {
-        "https://myapp.com/recipes/\(\.$target)"
-    }
-}
-```
-
-### URLRepresentableEntity
-
-```swift
-struct RecipeEntity: URLRepresentableEntity {
-    // ... standard AppEntity members ...
-
-    static var urlRepresentation: URLRepresentation {
-        "https://myapp.com/recipes/\(.id)"
-    }
+extension RecipeEntity: URLRepresentableEntity {
+    static var urlRepresentation: URLRepresentation { "https://example.com/recipes/\(.id)" }
 }
-```
-
-### URLRepresentableEnum
-
-```swift
-enum RecipeCategory: String, URLRepresentableEnum {
-    case breakfast, lunch, dinner
 
-    static var urlRepresentation: URLRepresentation {
-        "https://myapp.com/category/\(.rawValue)"
-    }
-
-    // ... standard AppEnum members ...
+extension MealCourse: URLRepresentableEnum {
+    static var urlRepresentation: URLRepresentation { "https://example.com/courses/\(.rawValue)" }
 }
 ```
 
-URL representations must be universal links, not custom URL schemes.
+Only universal links qualify here; a custom URL scheme does not.
+Every `urlRepresentation` is a computed property: `URLRepresentation` is not
+`Sendable`, so Swift 6 rejects it as a `static let`.
 
-## IndexedEntity for Spotlight (iOS 18+)
+## Spotlight
 
-Conform to `IndexedEntity` to make entities searchable in Spotlight.
+### IndexedEntity with a custom attribute set
 
 ```swift
 struct ArticleEntity: IndexedEntity {
     static let defaultQuery = ArticleQuery()
-    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Article"
-
-    var id: String
+    static let typeDisplayRepresentation: TypeDisplayRepresentation = "Article"
 
-    @Property(title: "Title")
-    var title: String
-
-    @Property(title: "Author")
-    var author: String
+    let id: String
+    @Property(title: "Headline") var headline: String
+    @Property(title: "Section") var section: String
+    var writers: [String]
 
     var displayRepresentation: DisplayRepresentation {
-        DisplayRepresentation(title: "\(title)", subtitle: "\(author)")
+        DisplayRepresentation(title: "\(headline)", subtitle: "\(section)")
     }
 
-    // Start with defaultAttributeSet to keep displayRepresentation metadata
     var attributeSet: CSSearchableItemAttributeSet {
-        let attrs = defaultAttributeSet
-        attrs.authorNames = [author]
-        return attrs
+        let attributes = defaultAttributeSet
+        attributes.authorNames = writers
+        return attributes
     }
 }
-```
 
-After creating entities, add instances to a named Spotlight index:
-
-```swift
-try await CSSearchableIndex(name: "Articles").indexAppEntities(articleEntities)
+// try await CSSearchableIndex(name: "newsroom").indexAppEntities(stories)
 ```
 
-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`.
+- Returning a fresh `CSSearchableItemAttributeSet` drops the title, subtitle
+  and image derived from `displayRepresentation` unless you copy the
+  `defaultAttributeSet` values in yourself.
+- If the app already builds `CSSearchableItem` values, call
+  `associateAppEntity(_:priority:)` on each item's attribute set so one result
+  is shown instead of two. The entity type also needs an `OpenIntent`.
 
-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.
+### Updating and removing
 
-### Updating and Deleting Indexed Entities
-
-Update and delete changed records in the same named index. For large syncs, use
-`beginBatch()`, `endBatch(withClientState:)`, and `fetchLastClientState()` so
-indexing can resume after a crash or jetsam.
+Update and delete through the same named index you added to.
 
 ```swift
-let recipeIndex = CSSearchableIndex(name: "Recipes")
-try await recipeIndex.indexAppEntities(changedRecipes)
-try await recipeIndex.deleteAppEntities(
-    identifiedBy: deletedRecipeIDs,
-    ofType: RecipeEntity.self
-)
+let index = CSSearchableIndex(name: "articles")
+try await index.indexAppEntities(changed)
+try await index.deleteAppEntities(identifiedBy: removedIDs, ofType: ArticleEntity.self)
 ```
 
-### Hide specific entities from Spotlight UI
+For large syncs, wrap chunks in `beginBatch()` and
+`endBatch(withClientState:)`, and read `fetchLastClientState()` at launch so
+indexing picks up where it stopped after a crash or a jetsam kill.
 
-```swift
-extension ArticleEntity {
-    var hideInSpotlight: Bool {
-        isDraft  // Draft articles should not appear in search
-    }
-}
-```
+### Keeping entities out of Spotlight UI
 
-## `@ComputedProperty(indexingKey:)` for Spotlight (iOS 26+)
+Implement `hideInSpotlight` (iOS 18.4+), for example returning `true` for
+drafts.
 
-Use indexing keys on `@Property` and `@ComputedProperty` for structured
-Spotlight metadata. The value is a Swift key path into
-`CSSearchableItemAttributeSet`.
+### indexingKey on properties (iOS 18.4 and 26)
 
-```swift
-struct RecipeEntity: IndexedEntity {
-    static let defaultQuery = RecipeQuery()
-    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Recipe"
+Both `@Property` and `@ComputedProperty` accept an `indexingKey`: a key path
+naming a `CSSearchableItemAttributeSet` attribute. The `@Property` form needs
+iOS 18.4, `@ComputedProperty` needs iOS 26.
 
-    var id: String
-
-    @Property(title: "Name", indexingKey: \.title)
-    var name: String
+```swift
+struct TrailEntity: IndexedEntity {
+    static let defaultQuery = TrailQuery()
+    static let typeDisplayRepresentation: TypeDisplayRepresentation = "Trail"
 
-    @Property(title: "Cuisine")
-    var cuisine: String
+    let id: UUID
+    @Property(title: "Trail", indexingKey: \.title) var label: String
+    @Property(title: "Region") var region: String
+    var lengthKilometres: Double
+    var photoPath: String?
 
     @ComputedProperty(indexingKey: \.contentDescription)
-    var summary: String {
-        "\(name) -- \(cuisine) cuisine"
-    }
+    var summary: String { "\(lengthKilometres) km in \(region)" }
 
     @ComputedProperty(indexingKey: \.thumbnailURL)
-    var imageURL: URL? {
-        URL(string: "https://myapp.com/images/\(id).jpg")
-    }
+    var thumbnail: URL? { photoPath.map { URL(filePath: $0) } }
 
-    var displayRepresentation: DisplayRepresentation {
-        DisplayRepresentation(title: "\(name)", subtitle: "\(cuisine)")
-    }
+    var displayRepresentation: DisplayRepresentation { DisplayRepresentation(title: "\(label)") }
 }
 ```
 
-```swift
-// Avoid duplicating a wrapped property's indexing key in attributeSet
-struct RecipeEntity: IndexedEntity {
-    @Property(title: "Name", indexingKey: \.title)
-    var name: String
+Setting `title` again inside a custom `attributeSet` while a `@Property`
+already maps to `\.title` is redundant. Let `indexingKey` do it.
 
-    var attributeSet: CSSearchableItemAttributeSet {
-        let attrs = CSSearchableItemAttributeSet(contentType: .text)
-        attrs.title = name  // Redundant: @Property already supplies this key
-        return attrs
-    }
-}
-
-// Prefer indexingKey for metadata already exposed on the entity
-struct RecipeEntity: IndexedEntity {
-    @Property(title: "Name", indexingKey: \.title)
-    var name: String
-}
-```
-
-### Available indexing keys
-
-| Key | Property Type | Purpose |
+| Key path | Type | Meaning |
 |---|---|---|
-| `\.title` | `String` | Primary searchable title |
-| `\.contentDescription` | `String` | Detailed description |
-| `\.thumbnailURL` | `URL?` | Thumbnail image |
-| `\.keywords` | `[String]` | Additional search terms |
-| `\.contentURL` | `URL?` | Content location |
+| `\.title` | `String` | main searchable title |
+| `\.contentDescription` | `String` | longer description |
+| `\.thumbnailURL` | `URL?` | thumbnail image |
+| `\.keywords` | `[String]` | extra search terms |
+| `\.contentURL` | `URL?` | where the content lives |
 
-## Onscreen Content for Siri (iOS 26+)
+## Visible content for Siri (iOS 26+)
 
-Make onscreen content available to Siri and Apple Intelligence without an
-assistant schema:
+Content the person is looking at can reach Siri and Apple Intelligence without
+an assistant schema. Make the entity `Transferable` and attach it to the
+current user activity:
 
 ```swift
-struct ArticleEntity: AppEntity, Transferable {
-    // Standard AppEntity conformance...
+struct TrailEntityCard: AppEntity, Transferable, Codable {
+    static let defaultQuery = TrailCardQuery()
+    static let typeDisplayRepresentation: TypeDisplayRepresentation = "Trail"
+    let id: UUID
+    var name: String
+    var displayRepresentation: DisplayRepresentation { DisplayRepresentation(title: "\(name)") }
 
     static var transferRepresentation: some TransferRepresentation {
-        CodableRepresentation(contentType: .article)
+        CodableRepresentation(contentType: .json)
     }
 }
 
-// In your view controller or SwiftUI view:
-let activity = NSUserActivity(activityType: "com.myapp.article")
-activity.appEntityIdentifier = AppEntityIdentifier(article)
-// Set as current activity
+// In the detail screen:
+// let activity = NSUserActivity(activityType: "com.example.trail.viewing")
+// activity.appEntityIdentifier = EntityIdentifier(for: card)
+// activity.becomeCurrent()
 ```
 
-## Parameter Summary Builder
+`appEntityIdentifier` needs iOS 18.2 or later, and it takes an
+`EntityIdentifier` built with `init(for:)`.
 
-Use `When`, `Switch`, `Case`, and `DefaultCase` for conditional parameter
-summaries that change based on parameter values:
+## Conditional parameter summaries
 
-```swift
-struct ConfigureWidgetIntent: WidgetConfigurationIntent {
-    static var title: LocalizedStringResource = "Configure Widget"
+`When`, `Switch`, `Case` and `DefaultCase` build summaries that change with the
+parameter values.
 
-    @Parameter(title: "Style")
-    var style: WidgetStyle
-
-    @Parameter(title: "Show Details", default: false)
-    var showDetails: Bool
+```swift
+struct ForecastWidgetConfig: WidgetConfigurationIntent {
+    static let title: LocalizedStringResource = "Forecast"
 
-    @Parameter(title: "Refresh Interval", default: .hourly)
-    var interval: RefreshInterval
+    @Parameter(title: "Use Current Location", default: true) var useCurrent: Bool
+    @Parameter(title: "City") var city: String?
+    @Parameter(title: "Style", default: .compact) var style: ForecastStyle
 
     static var parameterSummary: some ParameterSummary {
-        When(\.$showDetails, .equalTo, true) {
-            Summary("Show \(\.$style) widget") {
-                \.$showDetails
-                \.$interval
-            }
+        When(\.$useCurrent, .equalTo, true) {
+            Summary("Forecast here") { \.$useCurrent; \.$style }
         } otherwise: {
-            Summary("Show \(\.$style) widget") {
-                \.$showDetails
-            }
+            Summary("Forecast for \(\.$city)") { \.$useCurrent; \.$style }
         }
     }
 }
-```
 
-### Switch/Case for multiple conditions
+struct BrewConfig: WidgetConfigurationIntent {
+    static let title: LocalizedStringResource = "Brew"
 
-```swift
-static var parameterSummary: some ParameterSummary {
-    Switch(\.$style) {
-        Case(.compact) {
-            Summary("Compact widget")
-        }
-        Case(.detailed) {
-            Summary("Detailed widget") {
-                \.$interval
-            }
-        }
-        DefaultCase {
-            Summary("Widget") {
-                \.$style
-            }
+    @Parameter(title: "Method", default: .pourOver) var method: BrewMethod
+    @Parameter(title: "Grams", default: 18) var grams: Int
+    @Parameter(title: "Temperature", default: 94) var temperature: Int
+
+    static var parameterSummary: some ParameterSummary {
+        Switch(\.$method) {
+            Case(.espresso) { Summary("Espresso, \(\.$grams) g") }
+            Case(.pourOver) { Summary("Pour over at \(\.$temperature) C") { \.$grams } }
+            DefaultCase { Summary("Brew with \(\.$method)") }
         }
     }
 }
 ```
 
-## Core Spotlight Direct Usage
-
-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+) plus `@Property(indexingKey:)` / `@ComputedProperty(indexingKey:)`
-(iOS 26+) where possible.
+## Core Spotlight without App Intents
 
-### When to Use Core Spotlight Directly vs IndexedEntity
+Talk to Core Spotlight yourself when the app has no App Intents, supports
+releases before iOS 18, or needs every knob. An app that already uses App Intents should
+prefer `IndexedEntity` (iOS 18) and `indexingKey` (iOS 18.4 on `@Property`,
+iOS 26 on `@ComputedProperty`).
 
-| Approach | When to Use |
+| Situation | Tool |
 |---|---|
-| `IndexedEntity` (iOS 18+) | App already uses App Intents; entities are also Siri/Shortcuts-visible |
-| `@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 |
+| Entities already exist for Siri and Shortcuts | `IndexedEntity` |
+| Derived metadata on an `IndexedEntity` | `@ComputedProperty(indexingKey:)` |
+| No App Intents, pre-iOS 18, standalone indexing, or tight control of expiration, domains and batches | Core Spotlight directly |
 
-### CSSearchableItem and CSSearchableItemAttributeSet
+### Items and attributes
 
-A `CSSearchableItem` uniquely identifies searchable content. Attach a
-`CSSearchableItemAttributeSet` to describe the item's metadata.
-
-Docs: [CSSearchableItem](https://sosumi.ai/documentation/corespotlight/cssearchableitem),
-[CSSearchableItemAttributeSet](https://sosumi.ai/documentation/corespotlight/cssearchableitemattributeset)
+A `CSSearchableItem` identifies one piece of searchable content; its
+`CSSearchableItemAttributeSet` holds the metadata.
 
 ```swift
 import CoreSpotlight
 import UniformTypeIdentifiers
 
-func makeSearchableItem(
-    id: String,
-    title: String,
-    description: String,
-    thumbnailData: Data? = nil
-) -> CSSearchableItem {
-    let attributes = CSSearchableItemAttributeSet(contentType: .text)
-    attributes.title = title
-    attributes.contentDescription = description
-    attributes.thumbnailData = thumbnailData
-
-    // Optional: improve search ranking and categorization
-    attributes.keywords = ["recipe", "cooking"]
-    attributes.displayName = title
-    attributes.contentURL = URL(string: "myapp://recipes/\(id)")
-
-    let item = CSSearchableItem(
-        uniqueIdentifier: id,
-        domainIdentifier: "com.myapp.recipes",
-        attributeSet: attributes
-    )
-    // Set an expiration date when the default automatic expiration is wrong
-    item.expirationDate = Date.now.addingTimeInterval(60 * 60 * 24 * 90)
+func searchableItem(for note: FieldNote) -> CSSearchableItem {
+    let details = CSSearchableItemAttributeSet(contentType: .text)
+    details.title = note.heading
+    details.contentDescription = note.body
+    details.thumbnailData = note.sketchPNG
+    details.keywords = note.tags
+    details.displayName = note.heading
+    details.contentURL = note.shareURL
+    let item = CSSearchableItem(uniqueIdentifier: note.id, domainIdentifier: note.notebookID, attributeSet: details)
+    item.expirationDate = .now.addingTimeInterval(90 * 24 * 60 * 60)
     return item
 }
 ```
 
-### CSSearchableIndex  -  Indexing and Deletion
+Set `expirationDate` only when the system's default expiry does not suit you.
 
-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.
+### The index
 
-Docs: [CSSearchableIndex](https://sosumi.ai/documentation/corespotlight/cssearchableindex)
+Use a named index in shipping code; keep `CSSearchableIndex.default()` for
+prototypes and tests. Add a protection class when the content is sensitive.
 
 ```swift
-import CoreSpotlight
-
-// Index a single item (add or update)
-func indexItem(_ item: CSSearchableItem) async throws {
-    let index = CSSearchableIndex(name: "recipes")
-    try await index.indexSearchableItems([item])
-}
-
-// Delete specific items by identifier
-func deleteItems(identifiers: [String]) async throws {
-    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 {
-    let index = CSSearchableIndex(name: "recipes")
-    try await index.deleteSearchableItems(
-        withDomainIdentifiers: [domain]
-    )
-}
-
-// Delete everything (e.g., on logout)
-func deleteAllItems() async throws {
-    let index = CSSearchableIndex(name: "recipes")
-    try await index.deleteAllSearchableItems()
-}
+let notes = CSSearchableIndex(name: "field-notes")
+try await notes.indexSearchableItems(items)
+try await notes.deleteSearchableItems(withIdentifiers: ["note-17"])
+try await notes.deleteSearchableItems(withDomainIdentifiers: ["notebook-archived"])
+try await notes.deleteAllSearchableItems()
 ```
 
-### Batch Indexing Patterns
+Delete by identifier for single items, by domain when a whole category goes
+away, and everything on logout.
 
-For large data sets, index in batches to minimize memory pressure and handle
-errors gracefully. Use `beginBatch()` / `endBatch(withClientState:)` to
-track progress and resume after crashes.
+### Batching
 
-```swift
-import CoreSpotlight
+Index big sets in chunks to keep memory down and contain failures.
 
-func batchIndexRecipes(_ recipes: [Recipe]) async throws {
-    let index = CSSearchableIndex(name: "recipes")
-
-    // Simple batched approach -- chunk into groups
-    let batchSize = 100
-    for batch in stride(from: 0, to: recipes.count, by: batchSize) {
-        let end = min(batch + batchSize, recipes.count)
-        let items = recipes[batch..<end].map { recipe in
-            makeSearchableItem(
-                id: recipe.id,
-                title: recipe.name,
-                description: recipe.summary,
-                thumbnailData: recipe.thumbnailData
-            )
-        }
-        try await index.indexSearchableItems(items)
+```swift
+func indexAll(_ items: [CSSearchableItem], into index: CSSearchableIndex) async throws {
+    for start in stride(from: 0, to: items.count, by: 100) {
+        let chunk = Array(items[start..<min(start + 100, items.count)])
+        try await index.indexSearchableItems(chunk)
     }
 }
 
-// Client-state-based batching for crash recovery
-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 { String(data: $0, encoding: .utf8) }
-        .flatMap(Int.init) ?? 0
-
-    let batchSize = 100
-    for batch in stride(from: startOffset, to: recipes.count, by: batchSize) {
-        let end = min(batch + batchSize, recipes.count)
-        let items = recipes[batch..<end].map { recipe in
-            makeSearchableItem(
-                id: recipe.id,
-                title: recipe.name,
-                description: recipe.summary
-            )
-        }
-
+func resumableIndex(_ items: [CSSearchableItem], into index: CSSearchableIndex) async throws {
+    let saved = try await index.fetchLastClientState()
+    var offset = Int(String(decoding: saved, as: UTF8.self)) ?? 0
+    while offset < items.count {
+        let end = min(offset + 100, items.count)
         index.beginBatch()
-        try await index.indexSearchableItems(items)
-
-        let stateData = "\(end)".data(using: .utf8)!
-        try await index.endBatch(withClientState: stateData)
+        try await index.indexSearchableItems(Array(items[offset..<end]))
+        try await index.endBatch(withClientState: Data(String(end).utf8))
+        offset = end
     }
 }
 ```
 
-### Protected Index for Sensitive Content
+Swift imports `fetchLastClientState()` as returning non-optional `Data`, so
+there is no optional to unwrap; state that does not parse as a number starts
+the run at 0.
 
-Use a named index with a data protection class to encrypt indexed content:
+### Protected index
 
 ```swift
-let protectedIndex = CSSearchableIndex(
-    name: "secure-notes",
-    protectionClass: .complete  // Only accessible when device is unlocked
-)
-
-try await protectedIndex.indexSearchableItems(sensitiveItems)
+let vault = CSSearchableIndex(name: "health-notes", protectionClass: .complete)
 ```
 
-### Handling Search Results (NSUserActivity)
+Content in a `.complete` index is encrypted and readable only while the device
+is unlocked.
+
+### Opening a tapped result
 
-When a user taps a Spotlight result, the system delivers an `NSUserActivity`
-with `activityType` set to `CSSearchableItemActionType`. Extract the item
-identifier from `userInfo` to navigate to the correct content.
+A tapped result arrives as an `NSUserActivity` whose `activityType` is
+`CSSearchableItemActionType`; the item ID is in
+`userInfo[CSSearchableItemActivityIdentifier]`.
 
 ```swift
-import CoreSpotlight
-import UIKit
-
-// UIKit: In AppDelegate or SceneDelegate
-func application(
-    _ application: UIApplication,
-    continue userActivity: NSUserActivity,
-    restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
-) -> Bool {
-    if userActivity.activityType == CSSearchableItemActionType,
-       let identifier = userActivity.userInfo?[CSSearchableItemActivityIdentifier] as? String {
-        navigateToItem(withIdentifier: identifier)
-        return true
-    }
-    return false
+// UIKit
+func application(_ app: UIApplication, continue activity: NSUserActivity,
+                 restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
+    guard activity.activityType == CSSearchableItemActionType,
+          let noteID = activity.userInfo?[CSSearchableItemActivityIdentifier] as? String else { return false }
+    Router.shared.openNote(noteID)
+    return true
 }
 
-// SwiftUI: Use onContinueUserActivity
-struct ContentView: View {
-    var body: some View {
-        NavigationStack {
-            RecipeListView()
-        }
-        .onContinueUserActivity(CSSearchableItemActionType) { activity in
-            if let id = activity.userInfo?[CSSearchableItemActivityIdentifier] as? String {
-                navigateToRecipe(id: id)
-            }
+// SwiftUI
+NotesRoot()
+    .onContinueUserActivity(CSSearchableItemActionType) { activity in
+        if let noteID = activity.userInfo?[CSSearchableItemActivityIdentifier] as? String {
+            router.openNote(noteID)
         }
     }
-}
 ```
 
-### Query Continuation
+### Search in App
 
-When a user taps "Search in App" from Spotlight, handle the query string:
+When the person chooses "Search in App" from Spotlight, the activity type is
+`CSQueryContinuationActionType` and the text is in
+`userInfo[CSSearchQueryString]`:
 
 ```swift
-// activityType == CSQueryContinuationActionType
-.onContinueUserActivity(CSQueryContinuationActionType) { activity in
-    if let query = activity.userInfo?[CSSearchQueryString] as? String {
-        searchViewModel.searchText = query
+NotesRoot()
+    .onContinueUserActivity(CSQueryContinuationActionType) { activity in
+        if let text = activity.userInfo?[CSSearchQueryString] as? String {
+            router.search(text)
+        }
     }
-}
 ```
+
+### Documentation
+
+- [CSSearchableItem](https://developer.apple.com/documentation/corespotlight/cssearchableitem)
+- [CSSearchableItemAttributeSet](https://developer.apple.com/documentation/corespotlight/cssearchableitemattributeset)
+- [CSSearchableIndex](https://developer.apple.com/documentation/corespotlight/cssearchableindex)