@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/app-intents/SKILL.md

@@ -1,449 +1,447 @@
 ---
 name: app-intents
-description: "Implement App Intents for Siri, Shortcuts, Spotlight, widgets, Control Center, and Apple Intelligence on iOS. Covers AppIntent actions, AppEntity and EntityQuery models, AppShortcutsProvider phrases, IndexedEntity Spotlight indexing, WidgetConfigurationIntent, SnippetIntent, and assistant schemas. Use when exposing app actions or entities to system surfaces."
+description: "App Intents for Siri, Shortcuts, Spotlight, widgets, Control Center and Apple Intelligence: AppIntent actions, AppEntity and EntityQuery, AppShortcutsProvider phrases, IndexedEntity indexing, WidgetConfigurationIntent, SnippetIntent, assistant schemas. Use when building or reviewing code that exposes app actions or entities to a system surface."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
 # App Intents (iOS 26+)
 
-Implement, review, and extend App Intents to expose app functionality to Siri,
-Shortcuts, Spotlight, widgets, Control Center, and Apple Intelligence.
+App Intents is the single framework behind Siri, the Shortcuts app, Spotlight,
+configurable and interactive widgets, controls, and Apple Intelligence. The
+deeper material (every `@Parameter` form, all query types, controls, snippets,
+Visual Intelligence, schemas, Core Spotlight) is in the
+[advanced guide](references/appintents-advanced.md).
 
-## Contents
+Also covers `AppEnum`, `ControlConfigurationIntent` and `IntentValueQuery`.
+Not for WidgetKit layout or timeline design beyond choosing the intent
+protocol; that belongs to `widgetkit`.
 
-- [Triage Workflow](#triage-workflow)
-- [AppIntent Protocol](#appintent-protocol)
-- [`@Parameter`](#parameter)
-- [AppEntity](#appentity)
-- [EntityQuery (4 Variants)](#entityquery-4-variants)
-- [AppEnum](#appenum)
-- [AppShortcutsProvider](#appshortcutsprovider)
-- [Siri Integration](#siri-integration)
-- [Interactive Widget Intents](#interactive-widget-intents)
-- [Control Center Widgets (iOS 18+)](#control-center-widgets-ios-18)
-- [Spotlight and IndexedEntity (iOS 18+)](#spotlight-and-indexedentity-ios-18)
-- [iOS 26 Additions](#ios-26-additions)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+## Triage
 
-## Triage Workflow
+### 1. Name the surface
 
-### Step 1: Identify the integration surface
-
-Determine which system feature the intent targets:
-
-| Surface | Protocol | Since |
+| Surface | Protocol or macro | Since |
 |---|---|---|
-| Siri / Shortcuts | `AppIntent` | iOS 16 |
+| Siri and Shortcuts actions | `AppIntent` | iOS 16 |
 | Configurable widget | `WidgetConfigurationIntent` | iOS 17 |
-| Control Center | `ControlConfigurationIntent` | iOS 18 |
-| Spotlight search | `IndexedEntity` | iOS 18 |
-| Apple Intelligence | `@AppIntent(schema:)` | iOS 18 |
-| Interactive snippets | `SnippetIntent` | iOS 26 |
+| Control (Control Center, Lock Screen) | `ControlConfigurationIntent` | iOS 18 |
+| Spotlight | `IndexedEntity` | iOS 18 |
+| Apple Intelligence | `@AppIntent(schema:)` and friends | iOS 18 |
+| Interactive snippet | `SnippetIntent` | iOS 26 |
 | Visual Intelligence | `IntentValueQuery` | iOS 26 |
 
-### Step 2: Define the data model
+### 2. Model the data
 
-- Prefer `AppEntity` shadow models for app data exposed to the system.
-- Create `AppEnum` types for fixed parameter choices.
-- Choose the right `EntityQuery` variant for resolution.
-- Mark searchable entities with `IndexedEntity` and `indexingKey` metadata.
+- Expose app data through `AppEntity` shadow types, not the storage model.
+- Use `AppEnum` for a fixed set of choices.
+- Choose the `EntityQuery` variant that matches how values are looked up.
+- Entities meant for search adopt `IndexedEntity` and describe their metadata
+  with `indexingKey`.
 
-### Step 3: Implement the intent
+### 3. Write the intent
 
-- Conform to `AppIntent` (or a specialized sub-protocol).
-- Declare `@Parameter` properties for all user-facing inputs.
-- Implement `perform() async throws -> some IntentResult`.
-- Add `parameterSummary` for Shortcuts UI.
-- Register phrases via `AppShortcutsProvider`.
+- Adopt `AppIntent` or the sub-protocol the surface needs.
+- Every input the person supplies is a `@Parameter`.
+- Implement `perform()`; it is `async throws` and returns `some IntentResult`.
+- Give Shortcuts a `parameterSummary`.
+- Register spoken phrases in an `AppShortcutsProvider`.
 
-### Step 4: Verify
+### 4. Check it
 
-- Build and run in Shortcuts app to confirm parameter resolution.
-- Test Siri phrases with the intent preview in Xcode.
-- Confirm `IndexedEntity` instances are indexed in a named Spotlight index.
-- Check widget configuration for `WidgetConfigurationIntent` intents.
+- Run the action in the Shortcuts app and confirm each parameter resolves.
+- Try the Siri phrases through the intent preview in Xcode.
+- Confirm `IndexedEntity` values really land in a named Spotlight index.
+- Configure the widget once when a `WidgetConfigurationIntent` is involved.
 
-## AppIntent Protocol
+## AppIntent
 
-The system instantiates the struct via `init()`, sets parameters, then calls
-`perform()`. Declare a `title` and `parameterSummary` for Shortcuts UI.
+The system builds the intent with `init()`, fills in parameters, then calls
+`perform()`. A static `title` (a `LocalizedStringResource`) and a
+`parameterSummary` shape how Shortcuts shows it.
 
 ```swift
-struct OrderSoupIntent: AppIntent {
-    static var title: LocalizedStringResource = "Order Soup"
-    static var description = IntentDescription("Place a soup order.")
+import AppIntents
+
+struct WaterPlantIntent: AppIntent {
+    static let title: LocalizedStringResource = "Water Plant"
+    static let description = IntentDescription("Logs a watering for one of your plants.")
 
-    @Parameter(title: "Soup") var soup: SoupEntity
-    @Parameter(title: "Quantity", default: 1) var quantity: Int
+    @Parameter(title: "Plant")
+    var plant: PlantEntity
+
+    @Parameter(title: "Cups", default: 1)
+    var cups: Int
 
     static var parameterSummary: some ParameterSummary {
-        Summary("Order \(\.$soup)") { \.$quantity }
+        Summary("Water \(\.$plant)") { \.$cups }
     }
 
-    func perform() async throws -> some IntentResult {
-        try await OrderService.shared.place(soup: soup.id, quantity: quantity)
-        return .result(dialog: "Ordered \(quantity) \(soup.name).")
+    func perform() async throws -> some IntentResult & ProvidesDialog {
+        try await CareLog.shared.recordWatering(plantID: plant.id, cups: cups)
+        return .result(dialog: "Logged \(cups) cups for \(plant.name).")
     }
 }
 ```
 
-Optional members: `description` (`IntentDescription`), `openAppWhenRun` (`Bool`),
-`isDiscoverable` (`Bool`), `authenticationPolicy` (`IntentAuthenticationPolicy`).
-
-## `@Parameter`
+Optional members:
 
-Declare each user-facing input with `@Parameter`. Non-optional parameters are
-required; the system requests values when needed. Defaults pre-fill a useful
-value. Optional parameters are not requested automatically, so ask for them in
-`perform()` when the intent cannot continue without a value.
+- `description`: an `IntentDescription` shown in Shortcuts.
+- `openAppWhenRun`: `Bool`. The iOS 26 SDK deprecates it in favour of
+  `supportedModes`; keep it only for older deployment targets.
+- `isDiscoverable`: `Bool`, whether Shortcuts and Spotlight list the intent.
+- `authenticationPolicy`: an `IntentAuthenticationPolicy`.
 
-```swift
-// Required; the system asks for a value when needed
-@Parameter(title: "Count")
-var count: Int
+## Parameters
 
-// Required and pre-filled
-@Parameter(title: "Count", default: 1)
-var count: Int
+- A non-optional parameter is required; the system asks for it when missing.
+- `default:` pre-fills a value.
+- An optional parameter is never requested on its own. If `perform()` cannot go
+  on without it, ask for it there.
 
-// Optional; request it yourself if it becomes necessary
-@Parameter(title: "Count")
-var count: Int?
+```swift
+@Parameter(title: "Servings") var servings: Int
+@Parameter(title: "Servings", default: 1) var defaultedServings: Int
+@Parameter(title: "Servings") var maybeServings: Int?
 ```
 
-### Supported value types
+Supported value types:
 
-Primitives: `Bool`, `Int`, `Double`, `String`, `Duration`, `Date`, `Decimal`,
-`Measurement`, and `URL`. Collections: `Array` and `Set` of supported element
-types. Framework: `IntentPerson`, `IntentFile`. Custom: any `AppEntity` or
-`AppEnum`.
+- Primitives: `String`, `Bool`, `Int`, `Double`, `Decimal`, `Date`, `Duration`,
+  `URL`, `Measurement`.
+- `Array` and `Set` of supported types.
+- `IntentPerson` and `IntentFile`.
+- Any `AppEntity` or `AppEnum` you define.
 
-### Common initializer patterns
+Common initializer shapes:
 
 ```swift
-// With default
-@Parameter(title: "Count", default: 5)
-var count: Int
-
-// Numeric slider
-@Parameter(title: "Volume", controlStyle: .slider, inclusiveRange: (0, 100))
-var volume: Int
-
-// Options provider (dynamic list)
-@Parameter(title: "Category", optionsProvider: CategoryOptionsProvider())
-var category: Category
+@Parameter(title: "Repeat", default: false) var repeats: Bool
+@Parameter(title: "Dim Level", controlStyle: .slider, inclusiveRange: (0.0, 100.0)) var dimLevel: Double
+@Parameter(title: "Playlist", optionsProvider: PlaylistNames()) var playlist: String
 ```
 
-Options providers, files, measurements, resolvers, disambiguation dialogs, and
-input-connection behavior follow the same shape. See
-[references/appintents-advanced.md](references/appintents-advanced.md) for all initializer variants.
+The slider style exists only for `Double`. Options providers, files,
+measurements, resolvers, disambiguation prompts and input connections all use
+the same initializer pattern; the [advanced guide](references/appintents-advanced.md#parameter-initializers)
+lists each one.
 
 ## AppEntity
 
-Prefer shadow models that mirror app data and expose only system-facing fields.
-Direct model conformance is allowed when the model is lightweight, stable, and
-appropriate for App Intents lifecycles.
+Prefer a shadow type that mirrors the app model and carries only what the
+system needs. Conforming the app model itself is fine when it is small, stable
+and happy to live inside the App Intents lifecycle.
 
 ```swift
-struct SoupEntity: AppEntity {
-    static let defaultQuery = SoupEntityQuery()
-    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Soup"
-    var id: String
+struct PlantEntity: AppEntity {
+    static let defaultQuery = PlantQuery()
+    static let typeDisplayRepresentation: TypeDisplayRepresentation = "Plant"
+
+    let id: String
+
+    @Property(title: "Name")
+    var name: String
 
-    @Property(title: "Name") var name: String
-    @Property(title: "Price") var price: Double
+    @Property(title: "Room")
+    var room: String
 
     var displayRepresentation: DisplayRepresentation {
-        DisplayRepresentation(title: "\(name)", subtitle: "$\(String(format: "%.2f", price))")
+        DisplayRepresentation(title: "\(name)", subtitle: "\(room)")
     }
 
-    init(from soup: Soup) {
-        self.id = soup.id; self.name = soup.name; self.price = soup.price
+    init(from plant: Plant) {
+        id = plant.slug
+        name = plant.nickname
+        room = plant.location
     }
 }
 ```
 
-Required: `id`, `defaultQuery` (static), `displayRepresentation`,
-`typeDisplayRepresentation` (static). Mark properties with `@Property(title:)`
-to expose for filtering/sorting. Properties without `@Property` remain internal.
+Required: `id`, a static `defaultQuery`, `displayRepresentation` and a static
+`typeDisplayRepresentation`. Mark a property with `@Property(title:)` to make it
+available for filtering and sorting; anything without it stays private to the
+app.
+`DisplayRepresentation` accepts a plain string literal (`"Preferences"`) but
+not an interpolated one; `"\(name)"` has to go through
+`DisplayRepresentation(title:)`.
 
-## EntityQuery (4 Variants)
-
-### 1. EntityQuery (base -- resolve by ID)
+## EntityQuery variants
 
 ```swift
-struct SoupEntityQuery: EntityQuery {
-    func entities(for identifiers: [String]) async throws -> [SoupEntity] {
-        SoupStore.shared.soups.filter { identifiers.contains($0.id) }.map { SoupEntity(from: $0) }
+struct PlantQuery: EntityQuery {
+    func entities(for identifiers: [PlantEntity.ID]) async throws -> [PlantEntity] {
+        await Greenhouse.shared.plants(withIDs: identifiers).map(PlantEntity.init(from:))
     }
-    func suggestedEntities() async throws -> [SoupEntity] {
-        SoupStore.shared.featured.map { SoupEntity(from: $0) }
+
+    func suggestedEntities() async throws -> [PlantEntity] {
+        await Greenhouse.shared.thirstiest(limit: 5).map(PlantEntity.init(from:))
     }
 }
 ```
 
-### 2. EntityStringQuery (free-text search)
-
-Add `entities(matching string:)` alongside ID resolution for free-text search.
-
-### 3. EnumerableEntityQuery (finite set)
-
-Implement `allEntities()` when the full set is small and enumerable.
-
-### 4. UniqueAppEntityQuery (singleton, iOS 18+)
-
-Use for single-instance entities like app settings; implement `uniqueEntity()`.
+| Variant | Adds | Use when |
+|---|---|---|
+| `EntityQuery` | `entities(for:)` lookup by ID | always the base |
+| `EntityStringQuery` | `entities(matching:)` free-text search | people search by name |
+| `EnumerableEntityQuery` | `allEntities()` | the whole set is small |
+| `UniqueAppEntityQuery` (iOS 18+) | `uniqueEntity()` | exactly one instance, such as app settings |
 
-See [references/appintents-advanced.md](references/appintents-advanced.md) for full `EntityStringQuery`,
-`EnumerableEntityQuery`, and `UniqueAppEntityQuery` examples, plus `EntityPropertyQuery` with
-filter and sort support.
+Full versions of the last three, and `EntityPropertyQuery` with filtering and
+sorting, are in the [advanced guide](references/appintents-advanced.md#entity-queries).
 
 ## AppEnum
 
-Define fixed sets of selectable values. `RawValue` must conform to
-`LosslessStringConvertible`; prefer `String` raw values for readable, stable
-identifiers.
+For a closed set of choices. `RawValue` must be `LosslessStringConvertible`;
+`String` raw values read well and stay stable as identifiers.
 
 ```swift
-enum SoupSize: String, AppEnum {
-    case small, medium, large
-
-    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Size"
-
-    static var caseDisplayRepresentations: [SoupSize: DisplayRepresentation] = [
-        .small: "Small",
-        .medium: "Medium",
-        .large: "Large"
+enum LightLevel: String, AppEnum {
+    case shade, indirect, direct
+
+    static let typeDisplayRepresentation: TypeDisplayRepresentation = "Light Level"
+    static let caseDisplayRepresentations: [LightLevel: DisplayRepresentation] = [
+        .shade: "Shade",
+        .indirect: "Bright Indirect",
+        .direct: "Direct Sun",
     ]
 }
 ```
 
-```swift
-// Valid, but less readable in saved shortcuts and URL representations
-enum Priority: Int, AppEnum {
-    case low = 1, medium = 2, high = 3
-}
-
-// Preferred
-enum Priority: String, AppEnum {
-    case low, medium, high
-    // ...
-}
-```
+An `Int`-backed enum works, but its values are opaque in saved shortcuts and in
+URL representations.
 
 ## AppShortcutsProvider
 
-Register pre-built shortcuts that appear in Siri and the Shortcuts app without
-user configuration.
+Anything registered here is ready to use from Siri and Shortcuts the moment the
+app is installed.
 
 ```swift
-struct MyAppShortcuts: AppShortcutsProvider {
+struct GreenhouseShortcuts: AppShortcutsProvider {
     static var appShortcuts: [AppShortcut] {
         AppShortcut(
-            intent: OrderSoupIntent(),
+            intent: WaterPlantIntent(),
             phrases: [
-                "Order \(\.$soup) in \(.applicationName)",
-                "Get soup from \(.applicationName)"
+                "Water a plant in \(.applicationName)",
+                "Water \(\.$plant) with \(.applicationName)",
             ],
-            shortTitle: "Order Soup",
-            systemImageName: "cup.and.saucer"
+            shortTitle: "Water Plant",
+            systemImageName: "drop.fill"
         )
     }
 
-    static var shortcutTileColor: ShortcutTileColor = .navy
+    static let shortcutTileColor: ShortcutTileColor = .navy
 }
 ```
 
-### Phrase rules
-
-- Every phrase MUST include `\(.applicationName)`.
-- Phrases can reference parameters: `\(\.$soup)`.
-- Call `updateAppShortcutParameters()` when dynamic option values change.
-- Use `negativePhrases` to prevent false Siri activations.
-
-## Siri Integration
+- Every phrase must include `\(.applicationName)`.
+- Phrases may name parameters, such as `\(\.$plant)`.
+- When the values behind a parameter change, call
+  `GreenhouseShortcuts.updateAppShortcutParameters()`.
+- Add `negativePhrases` to stop Siri firing on similar-sounding requests.
 
-### Donating intents
+## Siri
 
-Donate intents so the system learns user patterns and suggests them in Spotlight:
+Donate an intent after the person performs the action in the app, so the system
+learns the habit and can suggest it in Spotlight:
 
 ```swift
-let intent = OrderSoupIntent()
-intent.soup = favoriteSoupEntity
-try await intent.donate()
+let done = WaterPlantIntent()
+done.plant = PlantEntity(from: fern)
+try await done.donate()
 ```
 
-### Predictable intents
+Adopt `PredictableIntent` when Siri should be able to predict the next action.
 
-Conform to `PredictableIntent` for Siri prediction of upcoming actions.
+## Widgets
 
-## Interactive Widget Intents
-
-Use `AppIntent` with `Button`/`Toggle` in widgets. Use
-`WidgetConfigurationIntent` for configurable widget parameters.
-Treat configuration intents as parameter contracts; put mutations in a separate
-action intent. For sensitive actions such as smart-home control, payments, or
-deletion, use an appropriate `authenticationPolicy` and/or
-`requestConfirmation(...)` before changing state.
+Interactive widgets run an `AppIntent` from a `Button` or `Toggle`. A
+`WidgetConfigurationIntent` carries the widget's settings. Treat it as a
+parameter contract; any change of state belongs to its own action intent. Actions that
+unlock doors, move money, delete data and the like need an
+`authenticationPolicy`, a `requestConfirmation(...)` step, or both, before any
+state changes.
 
 ```swift
-struct ToggleFavoriteIntent: AppIntent {
-    static var title: LocalizedStringResource = "Toggle Favorite"
-    @Parameter(title: "Item ID") var itemID: String
+struct MarkWateredIntent: AppIntent {
+    static let title: LocalizedStringResource = "Mark Watered"
+
+    @Parameter(title: "Plant ID")
+    var plantID: String
+
+    init() {}
+    init(plantID: String) { self.plantID = plantID }
 
     func perform() async throws -> some IntentResult {
-        FavoriteStore.shared.toggle(itemID)
+        await Greenhouse.shared.markWatered(plantID)
         return .result()
     }
 }
 
-// In widget view:
-Button(intent: ToggleFavoriteIntent(itemID: entry.id)) {
-    Image(systemName: entry.isFavorite ? "heart.fill" : "heart")
-}
+// Inside the widget view:
+// Button(intent: MarkWateredIntent(plantID: plant.slug)) { Image(systemName: "drop") }
 ```
 
 ### WidgetConfigurationIntent
 
 ```swift
-struct BookWidgetConfig: WidgetConfigurationIntent {
-    static var title: LocalizedStringResource = "Favorite Book"
-    @Parameter(title: "Book", default: "The Swift Programming Language") var bookTitle: String
+import WidgetKit
+
+struct RoomWidgetConfig: WidgetConfigurationIntent {
+    static let title: LocalizedStringResource = "Room"
+
+    @Parameter(title: "Room", default: "Kitchen")
+    var room: String
 }
 
-// Connect to WidgetKit:
-struct MyWidget: Widget {
+struct RoomWidget: Widget {
     var body: some WidgetConfiguration {
-        AppIntentConfiguration(kind: "FavoriteBook", intent: BookWidgetConfig.self, provider: MyTimelineProvider()) { entry in
-            BookWidgetView(entry: entry)
+        AppIntentConfiguration(kind: "RoomWidget", intent: RoomWidgetConfig.self, provider: RoomTimeline()) { entry in
+            RoomWidgetView(entry: entry)
         }
     }
 }
 ```
 
-## Control Center Widgets (iOS 18+)
+## Controls (iOS 18+)
+
+Controls in Control Center and on the Lock Screen pair a
+`ControlConfigurationIntent` with a `ControlWidget`.
 
-Expose controls in Control Center and Lock Screen with `ControlConfigurationIntent`
-and `ControlWidget`. Parameters without defaults must be optional.
-Trigger state changes from a separate `AppIntent` / `SetValueIntent` with
-explicit entity parameters, not from the configuration intent.
+- Give every parameter a default or make it optional. The system renders the
+  control before anyone has configured it.
+- State changes happen in a separate `AppIntent` or `SetValueIntent` that takes
+  explicit parameters, never in the configuration intent.
 
 ```swift
-struct LightControlConfig: ControlConfigurationIntent {
-    static var title: LocalizedStringResource = "Light Control"
-    @Parameter(title: "Light", default: .livingRoom) var light: LightEntity
+struct MisterControlConfig: ControlConfigurationIntent {
+    static let title: LocalizedStringResource = "Mister"
+
+    @Parameter(title: "Zone", default: .nursery)
+    var zone: GreenhouseZone
 }
 ```
 
-See [references/appintents-advanced.md](references/appintents-advanced.md) ("Control Center Widget
-Implementation") for the full `ControlWidget` + action-intent wiring with
-confirmation and authentication.
+The complete control wiring is in the
+[advanced guide](references/appintents-advanced.md#controls).
 
 ## Spotlight and IndexedEntity (iOS 18+)
 
-Conform to `IndexedEntity` for Spotlight search. On iOS 26+, use `indexingKey`
-to map a property to a `CSSearchableItemAttributeSet` key path for structured
-metadata:
+Adopt `IndexedEntity` to make entities searchable. `indexingKey` ties a
+property to a `CSSearchableItemAttributeSet` key path: on `@Property` from
+iOS 18.4, on `@ComputedProperty` from iOS 26.
 
 ```swift
-struct RecipeEntity: IndexedEntity {
-    static let defaultQuery = RecipeQuery()
-    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Recipe"
-    var id: String  // Stable recipe UUID or slug; do not use recycled row IDs
+import CoreSpotlight
 
-    @Property(title: "Name", indexingKey: \.title) var name: String  // iOS 26+
-    @ComputedProperty(indexingKey: \.contentDescription)              // iOS 26+
-    var summary: String { "\(name) -- a delicious recipe" }
+struct CareGuideEntity: IndexedEntity {
+    static let defaultQuery = CareGuideQuery()
+    static let typeDisplayRepresentation: TypeDisplayRepresentation = "Care Guide"
 
-    var displayRepresentation: DisplayRepresentation {
-        DisplayRepresentation(title: "\(name)")
-    }
+    let id: UUID
+
+    @Property(title: "Title", indexingKey: \.title)
+    var title: String
+
+    var steps: [String]
+
+    @ComputedProperty(indexingKey: \.contentDescription)
+    var overview: String { steps.prefix(2).joined(separator: " ") }
+
+    var displayRepresentation: DisplayRepresentation { DisplayRepresentation(title: "\(title)") }
 }
+
+// try await CSSearchableIndex(name: "guides").indexAppEntities(guides)
 ```
 
-`IndexedEntity` describes metadata; still index instances in a named Spotlight
-index, e.g. `CSSearchableIndex(name: "...").indexAppEntities(entities)`. Provide
-an `OpenIntent` for the type so results open the right content. If you customize
-`attributeSet`, start from `defaultAttributeSet`; returning a fresh attribute set
-replaces display representation and property-derived metadata. Prefer
-`indexingKey` for metadata already exposed on the entity.
+- IDs must be stable: a UUID or slug, never a database row ID that can be
+  reused.
+- `IndexedEntity` only describes metadata. The instances still have to be
+  indexed into a named index.
+- Tapped results need somewhere to go: add an `OpenIntent` for the entity
+  type.
+- If you override `attributeSet`, begin from `defaultAttributeSet`. A brand-new
+  attribute set discards the display representation and the property-derived
+  values.
+- When the entity already exposes the value, `indexingKey` is the better tool.
 
-See [references/appintents-advanced.md](references/appintents-advanced.md) for the full entity plus query,
-the available `@Property` / `@ComputedProperty` indexing keys, updating and
-deleting indexed entities, batch indexing with client state for crash recovery,
-and direct Core Spotlight usage.
+Details: [Spotlight section of the advanced guide](references/appintents-advanced.md#spotlight).
 
-## iOS 26 Additions
+## iOS 26 additions
 
 ### SnippetIntent
 
-Display interactive snippets in system UI. The system may call `perform()`
-multiple times, including after snippet button or toggle actions; keep
-`SnippetIntent.perform()` side-effect-free and do mutations in the calling action
-intent or a separate button/toggle action. A snippet-only intent is not
-discoverable in Shortcuts or Spotlight unless `isDiscoverable` is `true`. See
-[references/appintents-advanced.md](references/appintents-advanced.md) ("SnippetIntent Implementation")
-for the `ShowsSnippetView` / `ShowsSnippetIntent` example.
-
-### IntentValueQuery (Visual Intelligence)
-
-Return app entities for a Visual Intelligence `SemanticContentDescriptor`. Only
-one `IntentValueQuery` can take `SemanticContentDescriptor`; use `@UnionValue`
-when one query must return multiple app entity types. Return small, ranked,
-cancellation-friendly results and provide an opening path (`OpenIntent`, URL, or
-in-app search). Do not run camera capture, Vision `VN*` requests, or Spotlight
-indexing inside the query; call a bounded app search or image-match service
-instead. See [references/appintents-advanced.md](references/appintents-advanced.md) ("Visual Intelligence
-IntentValueQuery") for the full `@UnionValue` + query example and guidance.
-
-## Common Mistakes
-
-1. **Exposing too much app model state through AppEntity.** Prefer dedicated
-   shadow models with stable persistent IDs and only system-facing properties.
-
-2. **Missing `\(.applicationName)` in phrases.** Every `AppShortcut` phrase
-   MUST include the application name token. Siri uses it for disambiguation.
-
-3. **Treating optional `@Parameter` as required.** Optional parameters are not
-   requested automatically; call `requestValue` / `needsValueError` when the
-   intent cannot proceed without one.
-
-   ```swift
-   // Optional, so request it yourself if needed
-   @Parameter(title: "Count")
-   var count: Int?
-   ```
-
-4. **Using unstable AppEnum raw values.** `Int` is valid, but `String` raw values
-   are usually clearer for persistence and URL representations.
-
-5. **Forgetting `suggestedEntities()`.** Without it, the Shortcuts picker shows no defaults.
-6. **Throwing for missing entities in `entities(for:)`.** Omit missing entities instead.
-7. **Stale Spotlight index.** Re-index entities with a named `CSSearchableIndex`.
-8. **Missing `typeDisplayRepresentation`.** Both `AppEntity` and `AppEnum` require it.
-9. **Using deprecated `@Assistant*` schema macros.** Use `@AppIntent(schema:)`, `@AppEntity(schema:)`, and `@AppEnum(schema:)`.
-10. **Blocking or side-effecting perform().** Use `await` for I/O; keep `SnippetIntent.perform()` side-effect-free because the system may rerun it.
-11. **Mutating sensitive state from system surfaces without a guard.** Use confirmation and/or authentication for actions such as door locks, lights, purchases, and deletes.
-
-## Review Checklist
-
-- [ ] Every `AppIntent` has a descriptive `title` (verb + noun, title case)
-- [ ] Required `@Parameter` values are non-optional; optional values are requested when needed
-- [ ] `AppEntity` types expose stable IDs and only system-facing properties
-- [ ] `AppEntity` has `displayRepresentation` and `typeDisplayRepresentation`
-- [ ] `EntityQuery.entities(for:)` omits missing IDs; `suggestedEntities()` implemented
-- [ ] `AppEnum` prefers stable `String` raw values with `caseDisplayRepresentations`
-- [ ] `AppShortcutsProvider` phrases include `\(.applicationName)`; `parameterSummary` defined
-- [ ] `IndexedEntity` properties use key-path `indexingKey` values and entities are indexed
-- [ ] Control Center intents conform to `ControlConfigurationIntent`; widget intents to `WidgetConfigurationIntent`; no-default control parameters are optional
-- [ ] Sensitive App Intents request confirmation and/or authentication before mutating state
-- [ ] Visual Intelligence `IntentValueQuery` uses `SemanticContentDescriptor`, bounded results, opening paths, and iOS 26 availability
-- [ ] No deprecated `@AssistantIntent` / `@AssistantEntity` / `@AssistantEnum` schema macros
-- [ ] `perform()` uses async/await (no blocking); runs in expected isolation context; intent types are `Sendable`
+A `SnippetIntent` draws an interactive snippet in system UI. The system may
+call its `perform()` many times, including after each button or toggle inside
+the snippet, so `perform()` must not change anything. Mutate in the intent that
+presented the snippet or in the snippet's button and toggle actions. A
+snippet-only intent is hidden from Shortcuts and Spotlight unless
+`isDiscoverable` is `true`. Example:
+[advanced guide](references/appintents-advanced.md#snippets).
+
+### IntentValueQuery for Visual Intelligence
+
+`IntentValueQuery` answers a Visual Intelligence `SemanticContentDescriptor`
+with app entities.
+
+- Only one `IntentValueQuery` in the app may take `SemanticContentDescriptor`.
+  To return several entity types from it, use a `@UnionValue` type.
+- Return a short, ranked list and honour cancellation.
+- Give each result a way in: an `OpenIntent`, a URL, or in-app search.
+- Do not start camera capture, Vision `VN*` requests or Spotlight indexing
+  inside the query. Call an existing, bounded search or image-matching service.
+
+Example: [advanced guide](references/appintents-advanced.md#visual-intelligence).
+
+## Common mistakes
+
+1. Exposing the whole model through `AppEntity`. Use shadow types with stable,
+   persistent IDs and only the properties the system needs.
+2. Phrases without `\(.applicationName)`. Siri depends on it to tell apps apart.
+3. Treating an optional `@Parameter` as if the system will fill it. Ask with
+   `requestValue` or throw `needsValueError` when you need it.
+4. `AppEnum` raw values that drift. `Int` compiles, but `String` survives in
+   saved shortcuts and URLs.
+5. No `suggestedEntities()`, so the Shortcuts picker opens empty.
+6. Throwing from `entities(for:)` for IDs that no longer exist. Leave them out
+   of the result instead.
+7. A stale Spotlight index. Re-index into the same named `CSSearchableIndex`.
+8. No `typeDisplayRepresentation`. Entities and enums alike must declare one.
+9. Reaching for the old `@Assistant*` macros. Their replacements are `@AppIntent(schema:)`,
+   `@AppEntity(schema:)` and `@AppEnum(schema:)`.
+10. A `perform()` that blocks or has side effects it should not. `await` all
+    I/O, and keep `SnippetIntent.perform()` free of side effects because it
+    reruns.
+11. Changing sensitive state from a system surface with no guard: locks,
+    lights, purchases, deletions. Add confirmation, authentication, or both.
+
+## Review checklist
+
+- [ ] Every `AppIntent` has a verb-plus-noun `title` in title case
+- [ ] Required parameters are non-optional; optional ones are requested when
+      `perform()` needs them
+- [ ] `AppEntity` types have stable IDs and expose only system-facing
+      properties
+- [ ] `AppEntity` types define `displayRepresentation` and
+      `typeDisplayRepresentation`
+- [ ] `entities(for:)` skips unknown IDs, and `suggestedEntities()` exists
+- [ ] `AppEnum` types use stable `String` raw values and define
+      `caseDisplayRepresentations`
+- [ ] Every phrase contains `\(.applicationName)`, and `parameterSummary` is set
+- [ ] Spotlight metadata comes from `indexingKey` key paths on the entity's
+      properties, and the entities are really indexed
+- [ ] Controls use `ControlConfigurationIntent`, widgets use
+      `WidgetConfigurationIntent`, and control parameters without defaults are
+      optional
+- [ ] Sensitive intents confirm, authenticate, or both before mutating
+- [ ] A Visual Intelligence `IntentValueQuery` takes `SemanticContentDescriptor`,
+      caps its results, offers a way to open them and is gated to iOS 26
+- [ ] No `@AssistantIntent`, `@AssistantEntity` or `@AssistantEnum`
+- [ ] `perform()` is async and non-blocking, runs in the isolation you expect,
+      and intent types are `Sendable`
 
 ## References
 
-- See [references/appintents-advanced.md](references/appintents-advanced.md) for `@Parameter` variants, EntityPropertyQuery, assistant schemas, focus filters, SiriKit migration, error handling, confirmation flows, authentication, URL-representable types, and Spotlight indexing details.
+The [advanced guide](references/appintents-advanced.md) covers every
+`@Parameter` form, `EntityPropertyQuery`, assistant schemas, Focus filters,
+SiriKit migration, errors and dialogs, confirmation, authentication, URL
+representations and Spotlight indexing.