# `AppEnum` Persistence and Display

An `AppEnum` looks like an ordinary Swift enum, but two of its guarantees are enforced *outside* the compiler: how a value survives being saved into a shortcut, and whether it can be displayed at all. The declaration is `protocol AppEnum: AppValue, StaticDisplayRepresentable, RawRepresentable where RawValue: LosslessStringConvertible` — so it is `RawRepresentable`, and the framework persists the *raw value's string form*, not the case's position. Separately, `StaticDisplayRepresentable` requires a `caseDisplayRepresentations` dictionary that the framework indexes by case with no compiler check that every case is present. Both facts mean an edit that "compiles clean" can silently corrupt a saved shortcut or crash at display time. The two sections below cover each.

## Raw values are persisted by string — assign them explicitly and only ever append

When a shortcut is saved, an `AppEnum` value is serialized as `rawValue.description` — the string form of the raw value, chosen precisely because `LosslessStringConvertible` makes it round-trippable. Deserialization looks the case back up *by that string*. So the identity that persists across saves is the raw value's text, not the case name and not its declaration order. If you let Swift synthesize raw values (implicit `Int`, or `String` defaulting to the case name) and then reorder, rename, or renumber cases, previously-saved shortcuts silently rebind to whatever case now owns that string — a data-corruption bug with no diagnostic.

```swift
// AVOID: synthesized raw values that move when the source changes. These Ints
// are positional (small = 0, medium = 1, large = 2). Inserting `mini` at the
// top — or alphabetizing the cases — shifts every number. A shortcut a user
// saved as "large" (2) now deserializes as whatever case became 2. Silent.
enum DrinkSize: Int, AppEnum {
    case small
    case medium
    case large
    // later edit inserts `case mini` above `small`, or the cases get sorted…
}
```

```swift
// PREFER: explicit, stable raw values that never change once shipped, and only
// ever APPEND new cases. Reordering the source is now cosmetic — the persisted
// string ("small"/"medium"/"large") is pinned to its case regardless of position.
enum DrinkSize: String, AppEnum {
    case small = "small"
    case medium = "medium"
    case large = "large"
    case mini = "mini"      // appended later — safe; existing shortcuts unaffected

    // caseDisplayRepresentations required by AppEnum but omitted here for brevity —
    // see the next section (a missing entry is a runtime fatalError, not a build error).
}
```

Treat shipped raw values like a wire format: renaming a case's *display* text (in `caseDisplayRepresentations`) is fine and localizable, but the raw value is frozen. Deleting a case that older shortcuts may reference orphans those shortcuts. This is the same "identity is persisted, not position" discipline that `AppEntity`/`EntityIdentifier` requires — see `entities-and-queries.md`.

## Every case needs a `caseDisplayRepresentations` entry — a gap is a runtime crash, not a build error

`caseDisplayRepresentations` is `[Self: DisplayRepresentation]`, a plain dictionary — the compiler does not verify it is exhaustive over your cases. When the framework reads a case's title to display it and that case has no entry, it hits a `fatalError`. So adding a case and forgetting its dictionary entry compiles cleanly and then traps the moment that case is displayed (in the Shortcuts value picker, in a disambiguation prompt, anywhere its title is read).

```swift
// AVOID: a case with no dictionary entry. This compiles — the dictionary is not
// checked for exhaustiveness. When `mini` reaches any display path, the framework's
// unsafeDisplayRepresentation force-unwraps a nil lookup and fatalErrors.
enum DrinkSize: String, AppEnum {
    case small = "small"
    case medium = "medium"
    case large = "large"
    case mini = "mini"      // added to the enum…

    static let caseDisplayRepresentations: [DrinkSize: DisplayRepresentation] = [
        .small: "Small",
        .medium: "Medium",
        .large: "Large",
        // …but never added here. Crash at display time, not at build time.
    ]
}
```

```swift
// PREFER: one entry per case. When you append a raw value (section above), add
// its display representation in the same edit — the two changes are inseparable.
enum DrinkSize: String, AppEnum {
    case small = "small"
    case medium = "medium"
    case large = "large"
    case mini = "mini"

    static let caseDisplayRepresentations: [DrinkSize: DisplayRepresentation] = [
        .small: "Small",
        .medium: "Medium",
        .large: "Large",
        .mini: "Mini",      // added alongside the case
    ]
}
```

Because there is no compile-time safety net, make the dictionary edit part of the muscle memory of adding a case: new `case` + new raw value + new `caseDisplayRepresentations` entry, always in one change.

# App Shortcut Phrases

An `AppShortcut` is the zero-configuration entry point to an intent: it ships in the app binary, and the phrases you attach are what a user speaks to Siri or sees in Spotlight without ever opening your app. Because the phrases and the intent identifiers are extracted at build time and indexed by the system, they behave like a **published contract**: once a phrase is installed on a device, renaming or removing it breaks existing voice invocations and the muscle memory built around them. (Automations and saved Shortcuts run the underlying *intent* by its identifier, a separate contract, so they survive a phrase change; it's the spoken phrase that breaks.) Add new phrases; do not silently rewrite or delete shipped ones. The traps below are the ones that don't announce themselves at the call site: a deprecated initializer that still compiles, and an application-name rule that Xcode warns about at build time and the runtime index enforces by dropping non-compliant phrases.

## Give every `AppShortcut` a `shortTitle` and `systemImageName`

`AppShortcut` has an initializer whose `shortTitle` and `systemImageName` are optional — and it is deprecated. The current supported initializer requires both as non-optional. If you omit them, you bind to the deprecated overload, and the App Shortcut has no short title or SF Symbol for the Shortcuts app, Spotlight, and the Action button to render. It compiles and "works," so the gap is invisible until a designer or reviewer notices the blank tile.

```swift
// AVOID: omitting shortTitle/systemImageName. This resolves to the initializer
// that is @available(..., deprecated: iOS 17.0, "Please provide a shortTitle and
// systemImageName"). The shortcut installs, but the system has nothing to draw
// for the tile, and you inherit a deprecation warning you may not read.
struct LibraryShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: OpenLibraryIntent(),
            phrases: ["Open my library in \(.applicationName)"]
        )
    }
}
```

```swift
// PREFER: use the initializer that requires both. shortTitle is what Shortcuts and
// Spotlight display; systemImageName is the SF Symbol on the tile. systemImageName
// must be a compile-time string literal, not a variable or computed value.
struct LibraryShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: OpenLibraryIntent(),
            phrases: ["Open my library in \(.applicationName)"],
            shortTitle: "Open Library",
            systemImageName: "books.vertical"
        )
    }
}
```

The `systemImageName` parameter must be a compile-time string literal — the SF Symbol name is fixed at build time and cannot be a variable or computed value. Choose a symbol that actually exists in SF Symbols; an unknown name renders nothing.

## Put `\(.applicationName)` in every phrase: Xcode warns, then the index drops it

Every App Shortcut phrase should include the `\(.applicationName)` token (the `.applicationName` case of `AppShortcutPhraseToken`, interpolated into the phrase string). At extraction time this token expands to the literal marker `${applicationName}`, which the system later fills with the app's localized name. Anchoring each phrase to the app name is how Siri disambiguates your shortcut from every other app's — a bare "Open my library" is ambiguous across apps and won't reliably route to yours.

If people know your app by more than one name, register synonyms so the app-name token still routes to your app: add an `INAlternativeAppNames` array to your Info.plist (each entry an `INAlternativeAppName`, optionally with a pronunciation hint; at most three per localization). To make one of those synonyms the name App Shortcuts prefer, add the `INPreferredForAppShortcuts` key to that entry. See Apple's [Specifying synonyms for your app name](https://developer.apple.com/documentation/sirikit/specifying-synonyms-for-your-app-name).

The non-obvious part: **the `AppShortcut` initializer never validates your phrases, but the build tooling and the runtime index do.** The initializer passes the phrase strings through untouched, so a phrase missing `\(.applicationName)` still type-checks. Xcode's App Shortcuts extraction, though, **emits a build warning** for a phrase that lacks the app-name token, so watch your build warnings. If you ship past it, the runtime index drops that phrase when it indexes your App Shortcuts (you may see a `Phrase missing \(.applicationName)` note in the device logs), and it never becomes a usable voice trigger.

```swift
// AVOID: a phrase with no application-name token. The initializer accepts it and
// it compiles (with a build warning), and if shipped the index drops it (logging
// "Phrase missing"), so this utterance never routes to your app at all.
AppShortcut(
    intent: PlayMixIntent(),
    phrases: ["Play my daily mix"],   // ambiguous across apps; no ${applicationName}
    shortTitle: "Daily Mix",
    systemImageName: "music.note"
)
```

```swift
// PREFER: interpolate the applicationName token so the phrase is unambiguously
// scoped to this app. Reference a parameter ONLY when it resolves to a finite,
// named set: an AppEnum, an AppEntity, or a Bool with true/false display names.
// Primitive types with no closed set of options CANNOT be referenced in a phrase.
AppShortcut(
    intent: PlayMixIntent(),
    phrases: [
        "Play my daily mix in \(.applicationName)",
        "Play \(\.$genre) in \(.applicationName)",   // genre is an AppEnum
    ],
    shortTitle: "Daily Mix",
    systemImageName: "music.note"
)
```

Two further constraints on parameter interpolation inside a phrase. First, only a parameter whose value resolves to a **finite, named set of options** is usefully referenceable: an `AppEnum` (the phrase expands across its cases, from each case's `caseDisplayRepresentations`), an `AppEntity` (across its query's dynamic options), or a `Bool` (expanded into `true`/`false` spoken variants). The `Bool` case carries an extra requirement that `AppEnum` does not: it produces variants only when the parameter supplies true/false display names via `@Parameter(..., displayName: Bool.IntentDisplayName(true: "On", false: "Off"))`. The parameter `title:` alone does not generate them, and without those two state names the system produces no variants. Interpolating a free-form `String`, number, or date parameter gives Siri no closed set to match against, so it isn't useful. 
Second, on quantity: an app may declare **at most 10 App Shortcuts**, and this is enforced at **build time** — `appintentsmetadataprocessor` fails the build (e.g. *"Found N App Shortcuts, but each app may have at most 10"*), so you can't ship over the cap. Keep the set focused and high-value, and avoid duplicate or semantically similar phrases.

Phrases carry a separate, **per-locale** budget, distinct from the App Shortcut count. The system caps the phrases it serves within a single locale (about 1,000 per locale, counted independently per locale rather than summed across them) and truncates beyond that. It counts *expanded* phrases: a template that interpolates an `AppEnum`/`AppEntity`/`Bool` expands into one phrase per option, so a handful of templates over large option sets can consume the budget quickly. You rarely need to approach it, because the system does flexible phrase matching, so don't enumerate minor wording variants as separate phrases; keep each phrase short and memorable, and note that piling on near-duplicate variations *degrades* Siri's match accuracy rather than widening coverage. To see how your phrases actually match, use Xcode's **Product > App Shortcuts Preview**.
## Refresh dynamic phrase parameters when the underlying options change

If a phrase interpolates an `AppEntity`/`AppEnum` parameter backed by dynamic options, the concrete option values (the "daily mix" names, the library entities) are snapshotted at extraction time into the phrase's substitution values. When your data changes — the user creates a new playlist, deletes an entity — the snapshot goes stale, and Siri keeps matching the old option set. `AppShortcutsProvider` exposes `updateAppShortcutParameters()` for exactly this: call it after the options change to make the system re-extract the current values.

```swift
// AVOID: never signaling that the option set changed. The phrase substitutions
// captured at build/extraction time are all Siri knows about, so a newly created
// playlist is unreachable by voice and a deleted one still matches.
func didCreatePlaylist(_ playlist: PlaylistEntity) async {
    try? await store.save(playlist)
    // ...and nothing tells App Intents the "play <playlist> in MyApp" options moved.
}
```

```swift
// PREFER: after the data behind a dynamic phrase parameter changes, ask the
// system to refresh the App Shortcut parameters so phrase expansion re-snapshots
// the current values.
func didCreatePlaylist(_ playlist: PlaylistEntity) async {
    try? await store.save(playlist)
    LibraryShortcuts.updateAppShortcutParameters()
}
```

This only matters for App Shortcuts whose phrases interpolate a parameter with *dynamic* options; a phrase referencing a static `AppEnum` (whose cases are fixed at compile time) has nothing to refresh.

# Configuration Intents: Describing a Widget or Control, Not Running One

`WidgetConfigurationIntent` (iOS 17) and `ControlConfigurationIntent` (iOS 18 / macOS 26) look like ordinary `AppIntent`s — they conform to `AppIntent`, they carry `@Parameter`s, they have a `title` — but they are *not* actions. They exist so WidgetKit can render a configuration screen: each `@Parameter` becomes one editable field in the widget-editing sheet or the Control Center picker, and the chosen values are handed back to your `TimelineProvider` / control provider to build the view. Nothing "runs." The framework supplies a default `perform()` for both protocols that immediately throws (returning `Never`), precisely so you never write one — the compiler will happily let you add your own, which is the whole trap. The sections below cover the mistakes that follow from treating a configuration intent as if it executed.

## The `@Parameter`s ARE the whole intent — don't add a `perform()` to "make it work"

A configuration intent's job is finished the moment its parameters are declared. The protocol already carries a default `perform()` (its result type is `Never`), so the type compiles and drives the configuration UI with an empty body. Writing your own `perform()` is not required and does not "activate" anything — at best it is dead code the system won't call as an action, at worst it hides real logic somewhere it will never run for a widget.

```swift
// AVOID: adding a perform() because the type "felt incomplete" without one, then
// putting the widget's data-loading in it. This body never runs to render the
// widget — WidgetKit reads the @Parameter values and calls your TimelineProvider;
// it does NOT execute the configuration intent as an action. The fetch here is
// dead on the widget path, and the .result() return type even fights the
// protocol's own Never-returning default. It compiles, so nothing warns you.
struct FavoriteBookConfig: WidgetConfigurationIntent {
    static let title: LocalizedStringResource = "Favorite Book"

    @Parameter(title: "Book") var book: BookEntity?

    func perform() async throws -> some IntentResult {   // ❌ never invoked for the widget
        let cover = try await CoverLoader.load(for: book) // dead code on the render path
        return .result()
    }
}
```

```swift
// PREFER: parameters only. The @Parameters are the configuration surface; the
// framework's default perform() (returning Never) stands in, and WidgetKit passes
// the resolved values to your TimelineProvider, which does the actual data loading.
// Nothing to run, nothing to return.
struct FavoriteBookConfig: WidgetConfigurationIntent {
    static let title: LocalizedStringResource = "Favorite Book"
    static let description = IntentDescription("Shows your favorite book.")

    @Parameter(title: "Book") var book: BookEntity?
    // no perform() — the timeline provider reads `book` and builds the view
}
```

The one legitimate reason to write `perform()` is to *reuse the same type* as a real, runnable action elsewhere. If you are not doing that, leave it off.

## A control that toggles a value is a `SetValueIntent` action — separate from the control's `ControlConfigurationIntent`

Control Center controls have two intents with two different jobs, and conflating them is common. `ControlConfigurationIntent` *describes* the control (which thing it points at — a specific Focus, a particular device); it has no `perform()`. The action the control fires when tapped — flipping a toggle, setting a level — is a real, runnable intent, and for the on/off case that is `SetValueIntent`, which very much *does* implement `perform()`.

```swift
// AVOID: trying to make the configuration intent do the toggling. A
// ControlConfigurationIntent has no perform() the system will run on tap, so the
// side effect below is orphaned — the control configures fine but never toggles.
struct SilentModeControl: ControlConfigurationIntent {
    static let title: LocalizedStringResource = "Silent Mode"
    @Parameter(title: "On") var isOn: Bool
    func perform() async throws -> some IntentResult {   // ❌ not the control's tap action
        SilentMode.shared.set(isOn); return .result()
    }
}
```

```swift
// PREFER: keep the two roles in two types. The SetValueIntent is the runnable
// action WidgetKit ties to the control's value; its perform() carries the real
// logic. If the control needs to point at a specific target, THAT selection is
// what a ControlConfigurationIntent's @Parameters describe.
struct ToggleSilentMode: SetValueIntent {
    static let title: LocalizedStringResource = "Silent Mode"
    @Parameter(title: "Silent") var value: Bool
    func perform() async throws -> some IntentResult {   // ✅ runs on tap
        SilentMode.shared.set(value); return .result()
    }
}
```

`SetValueIntent` is a normal action intent and follows the ordinary execution rules in `execution-model.md`; only the *configuration* half is the no-`perform()` case. Which parameters belong on the configuration intent — optional vs. defaulted so the system can preview the control before setup — is a parameter-design question covered in `parameters.md`, and whether a distinct configuration surface even warrants its own type is the granularity question in `factoring.md`.

# `@Dependency` Registration and Placement

`@Dependency` looks like SwiftUI's `@Environment` — a value that "just appears" — but it is neither injected by a container you can see nor resolved by every type you might attach it to. It is a property wrapper backed by a single global registry (`AppDependencyManager.shared`), and it is only populated on types the framework knows how to prepare. It exists because the system instantiates your intents and queries itself (Siri, the Shortcuts app, Widgets), so there's no initializer of your own to inject through — the shared registry bridges that gap. Three facts break the naive mental model. Two are *runtime* traps: an *unregistered* dependency is a hard `fatalError`, and the wrapper is silently inert on types that don't support it (an `AppEntity`, an `AppEnum`) — both surface at runtime from Siri or an extension, never at compile time. The third bites at *compile* time: the dependency's value type must be `Sendable`.

## Register at launch, in `App.init()` — not lazily, not from a view

Accessing an unregistered `@Dependency` is a `fatalError` and not a catchable Swift error. There is no `try` that saves you: the crash happens inside the wrapper's `wrappedValue` getter the instant `perform()` (or a query) touches it. And intents run *cold*: Siri, Spotlight, an App Shortcut, or a background invocation can launch your app's process, construct the intent, and call `perform()` without your UI ever appearing. So any registration that runs "when the first view loads" or "on first user interaction" has not happened yet.

```swift
// AVOID: registering the dependency from view lifecycle. When the intent is
// invoked cold from Siri, ContentView never appears, so `add(...)` never runs —
// and the FIRST access of `database` inside perform() traps with
// "…was not initialized prior to access". It cannot be caught.
struct ContentView: View {
    var body: some View {
        NoteList()
            .onAppear {
                AppDependencyManager.shared.add(dependency: NoteDatabase.shared)
            }
    }
}

struct DeleteNoteIntent: AppIntent {
    static let title: LocalizedStringResource = "Delete Note"
    @Dependency var database: NoteDatabase   // traps if add(...) never ran

    @Parameter var note: NoteEntity
    func perform() async throws -> some IntentResult {
        try await database.delete(note.id)   // fatalError here on a cold launch
        return .result()
    }
}
```

```swift
// PREFER: register every dependency in App.init(), which runs on every process
// launch — including the cold, headless launches Siri/extensions trigger — before
// any intent or query can resolve it.
@main
struct NotesApp: App {
    init() {
        AppDependencyManager.shared.add(dependency: NoteDatabase.shared)
    }
    var body: some Scene {
        WindowGroup { ContentView() }
    }
}
```

Register from the earliest point that runs on *every* launch of the intent's host process — `App.init()` for an app, or the equivalent one-time setup in an extension that vends the intent. If a dependency genuinely may be absent, give the wrapper a `default:` (an `@Dependency` initializer overload) so resolution has a fallback instead of trapping; do not wrap the access in `do/catch` expecting to recover.

## Put `@Dependency` on the query/intent — never on the entity or enum

`@Dependency` is resolved only on types the framework prepares for it: `AppIntent`, `DynamicOptionsProvider`, and therefore `EntityQuery` (which refines `DynamicOptionsProvider`). `AppEntity` and `AppEnum` are *not* among them. A `@Dependency` stored on an `AppEntity` compiles (the wrapper is a normal property), but the framework never prepares it — it populates `@Dependency` only on the supported types above, never on entities. So a read on an entity is unreliable: it either traps like an unregistered dependency or returns a value only by coincidence, never something to rely on (a `default:` doesn't save it). The fix is placement, not registration: the entity's data access belongs in its `EntityQuery`, and that is where the dependency goes.

```swift
// AVOID: @Dependency stored on the entity. AppEntity does not support dependency
// resolution, so `database` is never prepared by the framework. This compiles and
// looks correct, then fails when touched — the framework never prepares it there,
// so the read is unreliable and a default: won't save it.
struct NoteEntity: AppEntity {
    @Dependency var database: NoteDatabase   // never populated — silently inert

    let id: UUID
    var title: String
    static var defaultQuery = NoteQuery()
    // …displayRepresentation, typeDisplayRepresentation…
}
```

```swift
// PREFER: put the @Dependency on the EntityQuery, which DOES support resolution.
// The query owns data access; the entity stays a plain value type.
struct NoteEntity: AppEntity {
    let id: UUID
    var title: String
    static var defaultQuery = NoteQuery()
    // …displayRepresentation, typeDisplayRepresentation…
}

struct NoteQuery: EntityQuery {
    @Dependency var database: NoteDatabase   // resolved: EntityQuery supports it

    func entities(for identifiers: [UUID]) async throws -> [NoteEntity] {
        try await database.notes(matching: identifiers)
    }
    func suggestedEntities() async throws -> [NoteEntity] {
        try await database.recentNotes()
    }
}
```

The same rule applies to an `AppEnum`: it has no dependency support, so any service it needs must be reached through the intent or the query that uses it, not stored on the enum. If an intent needs the dependency directly, declaring `@Dependency` on the `AppIntent` itself is correct — that is one of the supporting types. Don't try to force dependency support onto an entity or enum — the framework doesn't prepare those types for it; move the dependency to the query or intent instead.

## The dependency's value type must be `Sendable`

`@Dependency` is declared `AppDependency<Value: Sendable>`, and `AppDependencyManager.add(...)` takes a `Dependency: Sendable`. So the type you register and inject **must conform to `Sendable`** — because `AppIntent` and the query types are themselves `Sendable`, a non-`Sendable` stored `@Dependency` makes the enclosing intent/query ill-formed, with the diagnostic *"Stored property '_store' of 'Sendable'-conforming struct '…' contains non-Sendable type '…'."* The trap is that the natural candidate for a dependency — an `@Observable final class` model/store with mutable state — is **not** `Sendable` by default, so the obvious `@Dependency var store: BookStore` fails to compile.

```swift
// AVOID: injecting a non-Sendable store. `BookStore` is an @Observable class with
// mutable state and no Sendable conformance, so storing it as a @Dependency on a
// Sendable AppIntent is a Swift 6 error — "contains non-Sendable type 'BookStore'".
@Observable final class BookStore {        // not Sendable
    var books: [Book] = []
    var selectedBookID: UUID?
}

struct OpenBookIntent: OpenIntent {
    static let title: LocalizedStringResource = "Open Book"
    @Parameter var target: BookEntity
    @Dependency private var store: BookStore   // ❌ non-Sendable dependency

    @MainActor func perform() async throws -> some IntentResult {
        store.selectedBookID = target.id
        return .result()
    }
}
```

```swift
// PREFER: make the dependency Sendable. Isolate the store to the main actor
// (@MainActor implies Sendable for a reference type) so it's safe to hand across
// the concurrency boundary; the intent already hops to @MainActor to touch it.
@MainActor @Observable final class BookStore {   // @MainActor ⇒ Sendable
    var books: [Book] = []
    var selectedBookID: UUID?
}

struct OpenBookIntent: OpenIntent {
    static let title: LocalizedStringResource = "Open Book"
    @Parameter var target: BookEntity
    @Dependency private var store: BookStore   // ✓ Sendable now

    @MainActor func perform() async throws -> some IntentResult {
        store.selectedBookID = target.id
        return .result()
    }
}
```

Prefer isolating the type to `@MainActor` (correct for a UI-facing store an intent mutates) or making it an `actor`. Whatever you choose applies equally whether the `@Dependency` lives on the intent or on the `EntityQuery`.

# Donating Intents for Proactive Suggestions

App Intents power Siri Suggestions, Spotlight prediction, and the proactive "next action" surfaces — but only for actions the system *knows happened*. The non-obvious part, especially coming from SiriKit's automatic `INInteraction` donations: **App Intents does not auto-donate actions a person takes inside your own app's UI.** The system donates only the intents *it* runs — when someone runs your intent from the Shortcuts app or via Siri. A tap in your app that performs the same logical action produces no donation unless you make one. Without donations, prediction has nothing to learn from, and your suggestions stay empty.

## Donate after in-app actions — the system won't do it for you

After a person completes an action in your app's own interface (a tap or gesture in your **UI**, not an intent the system ran), build the matching `AppIntent` and hand it to `IntentDonationManager.shared`. Donate *after* the action succeeds (not before), and put enough detail in the intent to replay the action later; when the intent declares a return value, donate its **result** too (via `donate(intent:result:)`) so prediction learns the outcome, not just the invocation. Don't donate from inside an intent's `perform()`; the system already donates the intents it runs, so a donation there would double-count.

```swift
// AVOID: assuming in-app actions are auto-donated. This action is invisible to
// prediction — Siri Suggestions and Spotlight never learn the user plays this
// playlist every morning, because nothing was ever donated.
func userTappedPlay(_ playlist: PlaylistEntity) async {
    await player.play(playlist)
    // …no donation → no prediction signal
}
```

```swift
// PREFER: donate the matching intent after the action completes.
func userTappedPlay(_ playlist: PlaylistEntity) async {
    await player.play(playlist)
    try? await IntentDonationManager.shared.donate(
        intent: PlayPlaylistIntent(playlist: playlist)
    )
}
```

When the intent declares a return value, hand the system the result alongside the intent:

```swift
// Include the result when the intent returns one, so prediction learns the outcome.
try? await IntentDonationManager.shared.donate(
    intent: PlayPlaylistIntent(playlist: playlist),
    result: .result(value: playlist)
)
```

## Pick the throwing or non-throwing overload deliberately

`donate(intent:)` comes in two shapes: an `async throws` variant that reports whether the donation succeeded, and a synchronous variant that fails quietly. Use the async/throwing form when you need to know a donation landed (tests, production diagnostics); the synchronous form is fire-and-forget. When user data behind a donation is deleted, delete the stale donation too, so prediction quality doesn't degrade.

## `PredictableIntent` is not the donation hook

It is easy to assume `PredictableIntent` is how you feed prediction. It is not — `PredictableIntent` only supplies the *display descriptions* the system shows when it presents a suggestion (via `predictionConfiguration`). It does not donate anything. You still call `IntentDonationManager.shared.donate(...)` for the signal; `PredictableIntent` just makes the resulting suggestion read well.

Donation is the evergreen "teach the system what already happened" signal. On iOS 27+ there is a separate, complementary surface for pushing the entities that matter *right now* into suggestion surfaces (`RelevantEntities`) — for that, see the **relevance-and-context** reference in the sibling `app-intents-whats-new-27` skill.

# Entities and Their Queries

An `AppEntity` is a *reference* the system stores, not a value it copies. When a person builds a shortcut around a `NoteEntity` or Siri fills a parameter with one, what actually gets persisted is the entity's `id` string — the entity is re-fetched later, possibly days later, possibly on a different device, by handing that `id` back to your `EntityQuery`. That indirection is where the non-obvious traps live: the `id` you choose has to survive round-trips you don't control, and the query has two *different* jobs (resolve-by-id vs. suggest-defaults) that look similar but are called in different situations and have different cost profiles. This file covers the identity contract and the query surface. Parameter *resolution* mechanics (the picker prompt, `@Parameter`) live in `parameters.md`.

## The `id` must be stable across launches — and across devices for synced entities

`AppEntity` refines `Identifiable` with `ID: EntityIdentifierConvertible & Sendable`, and the framework serializes that `id` into saved shortcuts and cross-device Siri sessions. It is not an in-memory handle — it is a durable reference the system stores and replays back to your query later. So an `id` derived from anything device-local or run-local breaks resolution the moment the storage outlives the state it was derived from.

```swift
// AVOID: an id sourced from device-local / run-local state. A Photos
// localIdentifier, a DB row id, or an array index is meaningful only in the
// process/device that minted it. Saved in a shortcut it resolves fine today;
// synced to the user's Mac (or after a re-import) the same string points at a
// different row or nothing — entities(for:) returns [] and the shortcut breaks
// with no obvious error.
struct NoteEntity: AppEntity {
    static let defaultQuery = NoteEntityQuery()
    var id: String                       // = String(arrayIndex)  ❌ positional
    // or: var id = asset.localIdentifier ❌ device-local
    @Property(title: "Title") var title: String
    var displayRepresentation: DisplayRepresentation { DisplayRepresentation(title: "\(title)") }
}
```

```swift
// PREFER: a stable, globally meaningful id — a server-assigned key or a UUID
// you mint once and persist with the record. The same note resolves to the same
// entity on every launch and every device.
struct NoteEntity: AppEntity {
    static let defaultQuery = NoteEntityQuery()
    var id: UUID                         // minted once, stored with the record
    @Property(title: "Title") var title: String
    var displayRepresentation: DisplayRepresentation { DisplayRepresentation(title: "\(title)") }
}
```

`String`, `UUID`, and `Int` get `EntityIdentifierConvertible` for free; a custom `id` type must conform and provide `entityIdentifierString` / `entityIdentifier(for:)` (keep the string ≤ 4096 chars — the framework truncates past that). Note that "unique per launch" is not enough: the identifier lands in *persisted* shortcuts and synced sessions, so it must be reproducible without any local index. If your local id genuinely differs per device (Photos `localIdentifier`, local DB row ids), that is a cross-device sync problem the framework addresses separately — evergreen advice is simply: choose a stable id up front.

## Only `@Property`-wrapped members are visible to the system

Wrapping a stored property with `@Property` is not decoration — it is what exposes the value to App Intents. Only `@Property` members are visible to Find intents, `EntityPropertyQuery` filtering, and parameter display; a plain `var` is private to your code and invisible to the system, even though both compile. Nothing warns you — a plain `var` simply never appears where you expected it to be filterable or displayed.

```swift
// AVOID: plain `var`s for data the system should see. `title` and `tagCount`
// look like part of the entity, but the system can't filter or surface them —
// they're invisible to Find intents and property queries.
struct NoteEntity: AppEntity {
    static let defaultQuery = NoteEntityQuery()
    var id: UUID
    var title: String          // ❌ invisible to the system
    var tagCount: Int          // ❌ invisible to the system
    var displayRepresentation: DisplayRepresentation { DisplayRepresentation(title: "\(title)") }
}
```

```swift
// PREFER: wrap the properties the system should query/display with @Property.
// Keep plain `var`s only for values used purely inside your own code (e.g. to
// build displayRepresentation).
struct NoteEntity: AppEntity {
    static let defaultQuery = NoteEntityQuery()
    var id: UUID
    @Property(title: "Title") var title: String
    @Property(title: "Tags")  var tagCount: Int
    var iconName: String       // fine as a plain `var`: only feeds displayRepresentation
    var displayRepresentation: DisplayRepresentation { DisplayRepresentation(title: "\(title)") }
}
```

## `entities(for:)` and `suggestedEntities()` are different jobs — implement both

`EntityQuery` has two entry points that read as near-synonyms but serve opposite directions. `entities(for:)` is a *required* method: given identifiers the system already holds, return the matching entities. `suggestedEntities()` is what populates the picker when the system has *no* id yet and needs to offer choices. Crucially, `suggestedEntities()` has a **default implementation that returns empty** — so if you only implement `entities(for:)`, the query compiles and resolves saved values fine, yet the Shortcuts/Siri parameter picker shows an empty list and users can't choose anything.

```swift
// AVOID: implementing only entities(for:). Compiles, resolves persisted ids —
// but suggestedEntities() falls back to the framework default (empty), so the
// parameter picker is blank and the entity feels "unpickable."
struct NoteEntityQuery: EntityQuery {
    func entities(for identifiers: [UUID]) async throws -> [NoteEntity] {
        try await store.notes(withIDs: identifiers)
    }
    // suggestedEntities() left to default → returns [] → empty picker
}
```

```swift
// PREFER: implement both. entities(for:) resolves known ids; suggestedEntities()
// supplies the initial choices the picker displays.
struct NoteEntityQuery: EntityQuery {
    func entities(for identifiers: [UUID]) async throws -> [NoteEntity] {
        try await store.notes(withIDs: identifiers)
    }

    func suggestedEntities() async throws -> [NoteEntity] {
        try await store.recentNotes(limit: 20)
    }
}
```

If you want the picker to support free-text search (the user typing a name rather than picking from a list), conform to `EntityStringQuery` and implement `entities(matching:)`. That method is a bare protocol requirement with **no default and no framework-side filtering** — the system hands you the raw search string and your implementation must perform the match itself; there is no automatic "filter `suggestedEntities()` by substring" behavior to fall back on.

```swift
// PREFER: EntityStringQuery when the picker should search by name. You own the
// match — the framework does not filter for you.
struct NoteEntityQuery: EntityStringQuery {
    func entities(for identifiers: [UUID]) async throws -> [NoteEntity] {
        try await store.notes(withIDs: identifiers)
    }
    func entities(matching string: String) async throws -> [NoteEntity] {
        try await store.notes(titleContains: string)   // your query does the work
    }
    func suggestedEntities() async throws -> [NoteEntity] {
        try await store.recentNotes(limit: 20)
    }
}
```

## Resolve in one batch; keep suggestions cheap

`entities(for:)` takes an *array* of ids and returns an array by design — it is a batch resolve. The system may hand you many identifiers at once (a shortcut acting on a list of entities, a session referencing several). Treating it as "resolve one id" and looping a per-item fetch inside it turns one query into N round-trips (the classic N+1) — a per-id network or disk call per element. Issue a single query over the whole array instead. It's also valid to return *fewer* entities than requested: the framework silently drops ids with no match (and reorders your result to match the requested order), so an entity that no longer exists just gets omitted — you don't throw for it.

```swift
// AVOID: per-id fetch inside entities(for:). Ten selected notes = ten backend
// round-trips; the resolve is N× slower than it needs to be.
func entities(for identifiers: [UUID]) async throws -> [NoteEntity] {
    var result: [NoteEntity] = []
    for id in identifiers {
        result.append(try await store.note(withID: id))   // N round-trips
    }
    return result
}
```

```swift
// PREFER: one batched query over all ids. Missing ids are simply absent from
// the returned array — that's expected, not an error.
func entities(for identifiers: [UUID]) async throws -> [NoteEntity] {
    try await store.notes(withIDs: identifiers)            // single round-trip
}
```

`suggestedEntities()` sits at the other end of the cost model: the system calls it *opportunistically* to populate pickers, so it can fire when the user hasn't asked for anything expensive. Keep it cheap and bounded — return a recent/likely subset (e.g. a `limit:`), not your entire store — rather than doing heavy work or fetching everything on every invocation.

## `EnumerableEntityQuery` loads *everything* — the wrong query for a large store

`EnumerableEntityQuery` (iOS 17+) is the ergonomic query: implement `allEntities()` and the system auto-generates a Find action and filters for you. The catch is *how* it filters — it calls `allEntities()`, materializing your entire entity set in memory, then filters that. Fine for a small, bounded catalog (a fixed set of categories, a handful of accounts). For a store that grows to thousands of rows, or entities that are individually large, it's a memory/performance trap the compiler never flags.

```swift
// AVOID: EnumerableEntityQuery over an unbounded store. allEntities() loads every
// note into memory on every Find, then the framework filters in-memory.
struct NoteEntityQuery: EnumerableEntityQuery {
    func entities(for ids: [UUID]) async throws -> [NoteEntity] {
        try await store.notes(withIDs: ids)
    }
    func allEntities() async throws -> [NoteEntity] {
        try await store.allNotes()          // could be tens of thousands
    }
}
```

For a large or unbounded store, conform to `EntityPropertyQuery` instead: the system hands your data layer the query comparators, so you materialize only the matching entities rather than loading the whole set. Reserve `EnumerableEntityQuery` for small, bounded collections.

# Property-Based Entity Queries

`EntityQuery` resolves entities by `id` and suggests defaults (see `entities-and-queries.md`). `EntityPropertyQuery` refines it with the next tier up: "find every X *where* some property compares a certain way," sorted and limited. This is what powers the Shortcuts **Find** action — the user builds a filter like "Notes where Title contains 'trip', sorted by date, limit 10," and your query has to answer it. The shape is unusual: you declare *which* properties are queryable and *which* comparators each supports, the framework parses the user's filter into that vocabulary, and then hands you the parsed predicate to execute against your own backend. The framework does not filter for you. This file covers that contract and its traps; it assumes the entity/`@Property`/id material from `entities-and-queries.md`.

## Declare the queryable surface with `properties` and `sortingOptions`

`EntityPropertyQuery` adds two required statics beyond `EntityQuery`: `static var properties: QueryProperties` lists each queryable property and the comparators it supports, and `static var sortingOptions: SortingOptions` lists the properties the user may sort by. Both are result builders. Every keypath is the `$`-projected form (`\.$title`) — the builder needs the `@Property` wrapper, not the underlying value, so a plain-value keypath (`\.title`) fails to compile, and a member that isn't `@Property`-wrapped at all has no `$` projection to reference (that's the `@Property` requirement from `entities-and-queries.md`, now load-bearing at the query layer).

```swift
// AVOID: conforming to EntityPropertyQuery but only carrying over the EntityQuery
// methods. `properties` and `sortingOptions` are required statics with no default
// — this does not compile, and even a `QueryProperties {}` stub with no Property
// entries yields a Find action the user can't filter with at all.
struct NoteQuery: EntityPropertyQuery {
    func entities(for ids: [UUID]) async throws -> [NoteEntity] {
        try await store.notes(withIDs: ids)
    }
    // ❌ no `properties`, no `sortingOptions`, no entities(matching:…)
}
```

```swift
// PREFER: declare the queryable properties with their comparators, and the
// sortable properties. Each comparator's closure maps the user's value into a
// ComparatorMappingType of YOUR choosing (here a predicate struct your store
// understands) — the framework never touches your backend, only this mapping.
struct NoteQuery: EntityPropertyQuery {
    typealias ComparatorMappingType = NotePredicate   // your own type

    static var properties = QueryProperties {
        Property(\.$title) {
            EqualToComparator    { NotePredicate.titleEquals($0) }
            ContainsComparator   { NotePredicate.titleContains($0) }
            HasPrefixComparator  { NotePredicate.titleHasPrefix($0) }
        }
        Property(\.$createdAt) {
            LessThanComparator    { NotePredicate.createdBefore($0) }
            GreaterThanComparator { NotePredicate.createdAfter($0) }
        }
    }

    static var sortingOptions = SortingOptions {
        SortableBy(\.$title)
        SortableBy(\.$createdAt)
    }

    func entities(for ids: [UUID]) async throws -> [NoteEntity] {
        try await store.notes(withIDs: ids)
    }
}
```

## The comparator must fit the property's type

The comparator classes are typed against the property. Equality ones (`EqualToComparator`, `NotEqualToComparator`) need an `Equatable` property; the ordered ones (`GreaterThanComparator`, `GreaterThanOrEqualToComparator`, `LessThanComparator`, `LessThanOrEqualToComparator`) need `Comparable`; `ContainsComparator` needs a `String`/`AttributedString` (substring) or a collection (element membership); `HasPrefixComparator`/`HasSuffixComparator` are `String`-only. `IsBetweenComparator` takes two inputs and is only surfaced for `Date` in Shortcuts. Attaching a comparator a property's type can't satisfy is a compile error, not a silent no-op — but the failure reads as an opaque generic-constraint mismatch, so it's worth getting right up front.

```swift
// AVOID: a comparator the property type doesn't support. `tagCount` is an Int, so
// HasPrefixComparator (String-only) can't apply; `title` is a String, so ordering
// comparators are meaningless on it. Both surface as confusing generic errors.
static var properties = QueryProperties {
    Property(\.$tagCount) {
        HasPrefixComparator { NotePredicate.bogus($0) }   // ❌ Int has no prefix
    }
    Property(\.$title) {
        GreaterThanComparator { NotePredicate.bogus($0) } // ❌ String isn't the ordered case you want
    }
}
```

```swift
// PREFER: match the comparator family to the type. Numeric/comparable → ordered
// comparators; String → contains/prefix/suffix; array → Contains for membership.
static var properties = QueryProperties {
    Property(\.$tagCount) {
        EqualToComparator     { NotePredicate.tagCountEquals($0) }
        GreaterThanComparator { NotePredicate.tagCountAbove($0) }
    }
    Property(\.$title) {
        ContainsComparator  { NotePredicate.titleContains($0) }
        HasPrefixComparator { NotePredicate.titleHasPrefix($0) }
    }
    Property(\.$tags) {   // [String]
        ContainsComparator { NotePredicate.hasTag($0) }   // element membership
    }
}
```

## You execute the predicate — the framework only parses it

The signature is `func entities(matching comparators: [ComparatorMappingType], mode: ComparatorMode, sortedBy: [Sort<Entity>], limit: Int?)`. Every argument is a *parsed instruction you must carry out*, not a filter the framework already applied. `comparators` is the array of values your mapping closures produced; `mode` is `.and` or `.or` (combine the comparators with all-must-match vs. any-match); each `Sort<Entity>` exposes `.by` (a `PartialKeyPath<Entity>`) and `.order` (`.ascending`/`.descending`); `limit` caps the count. Returning your whole store, or ignoring `mode`/`sortedBy`/`limit`, means the Find action returns wrong results — the framework will not re-filter or re-sort behind you.

```swift
// AVOID: ignoring the parsed query. Returning everything (or filtering but
// dropping mode/sort/limit) makes "Notes where title contains X, newest first,
// max 5" return every note in arbitrary order — the predicate was handed to you
// and silently discarded.
func entities(
    matching comparators: [NotePredicate],
    mode: ComparatorMode,
    sortedBy: [Sort<NoteEntity>],
    limit: Int?
) async throws -> [NoteEntity] {
    try await store.allNotes()   // ❌ comparators, mode, sortedBy, limit all ignored
}
```

```swift
// PREFER: translate the parsed query into your backend's own query and let the
// data layer do the filtering/sorting/limiting. Push the predicate down; honor
// mode, sort order, and limit. (Sort<Entity>.by is a PartialKeyPath you read to
// pick the column; .order gives ascending/descending.)
func entities(
    matching comparators: [NotePredicate],
    mode: ComparatorMode,
    sortedBy: [Sort<NoteEntity>],
    limit: Int?
) async throws -> [NoteEntity] {
    try await store.fetchNotes(
        predicates: comparators,
        combine: (mode == .and) ? .all : .any,
        sort: sortedBy,          // read .by / .order per element
        limit: limit
    )
}
```

## Reach for `EntityPropertyQuery` over `EnumerableEntityQuery` when the store is large

`EnumerableEntityQuery` (covered in `entities-and-queries.md`) is the load-everything tier: you implement `allEntities()`, the framework materializes the full set and filters it in memory. That's fine for a small bounded catalog, but for a store of thousands of rows it's the wrong shape — you pay to load the entire set on every Find. `EntityPropertyQuery` is the server-side-predicate alternative: because the framework hands you the parsed comparators, sort, and limit, you can turn them into a bounded database/network query and materialize only the matches. Choose by store size, not by which is easier to type: `EnumerableEntityQuery` for small fixed collections, `EntityPropertyQuery` once the data could grow unbounded or the rows are individually heavy.

```swift
// AVOID: EnumerableEntityQuery over an unbounded store. allEntities() loads every
// note into memory on each Find, then the framework filters in-memory — a
// memory/latency trap that grows with the store and never gets flagged.
struct NoteQuery: EnumerableEntityQuery {
    func entities(for ids: [UUID]) async throws -> [NoteEntity] {
        try await store.notes(withIDs: ids)
    }
    func allEntities() async throws -> [NoteEntity] {
        try await store.allNotes()          // ❌ could be tens of thousands
    }
}
```

```swift
// PREFER: EntityPropertyQuery, so the filter reaches your data layer and only the
// matching rows are fetched. Same Find action for the user; bounded cost for you.
struct NoteQuery: EntityPropertyQuery {
    typealias ComparatorMappingType = NotePredicate
    static var properties = QueryProperties {
        Property(\.$title) { ContainsComparator { NotePredicate.titleContains($0) } }
    }
    static var sortingOptions = SortingOptions { SortableBy(\.$createdAt) }

    func entities(for ids: [UUID]) async throws -> [NoteEntity] {
        try await store.notes(withIDs: ids)
    }
    func entities(
        matching comparators: [NotePredicate],
        mode: ComparatorMode,
        sortedBy: [Sort<NoteEntity>],
        limit: Int?
    ) async throws -> [NoteEntity] {
        try await store.fetchNotes(predicates: comparators, sort: sortedBy, limit: limit)
    }
}
```

# Execution Model of `perform()`

`perform()` does not run the way its name suggests. It is declared `func perform() async throws -> some IntentResult` on a `Sendable` protocol with **no actor isolation**, it runs in whatever process hosts the intent (your app *or* an app extension), and the system may re-invoke it from the top during a single logical run. Each of those three facts contradicts the naive mental model — "an action that runs inside my already-running app, on the main thread, once" — and each has a distinct correctness trap. The sections below cover all three — plus the confirmation primitive that shares the same side-effect-ordering discipline.

## `perform()` is not `@MainActor` — hop before touching main-actor state

`AppIntent` conforms to `Sendable`, not `@MainActor`, and `perform()` carries no actor annotation. So the body may run off the main thread (and in a different process than your UI). Reading or writing `@MainActor`-isolated state directly from `perform()` — an `@Observable` view model, SwiftUI/UIKit/AppKit objects, anything annotated `@MainActor` — is a concurrency violation. It is *not* safe just because the intent "opens the app."

```swift
// AVOID: touching main-actor state directly from perform(). `navigator` and
// `libraryModel` are @MainActor; perform() is not, so these calls hop actors
// implicitly at best and race at worst. Under Swift 6 this won't compile.
struct OpenNoteIntent: AppIntent {
    static let title: LocalizedStringResource = "Open Note"
    @Parameter var note: NoteEntity

    func perform() async throws -> some IntentResult {
        navigator.navigate(to: note)          // @MainActor — called off-main
        libraryModel.lastOpened = note.id     // @MainActor mutation — data race
        return .result()
    }
}
```

```swift
// PREFER: hop to the main actor explicitly for the work that needs it. Do the
// rest (validation, data lookups) where perform() already is.
struct OpenNoteIntent: AppIntent {
    static let title: LocalizedStringResource = "Open Note"
    @Parameter var note: NoteEntity

    func perform() async throws -> some IntentResult {
        await MainActor.run {
            navigator.navigate(to: note)
            libraryModel.lastOpened = note.id
        }
        return .result()
    }
    // Alternatively, since this whole body is main-actor work, annotate the method
    // and drop the wrapper: `@MainActor func perform() async throws -> some IntentResult`.
}
```

Calling an `@MainActor`-isolated method with `await` (e.g. `await navigator.open(note)`) is equally correct — the point is that the actor hop is *explicit*, not assumed. When *most* of `perform()` touches main-actor state, annotating the method — `@MainActor func perform() async throws -> some IntentResult` — is cleaner than wrapping the body in `MainActor.run { }`; keep the narrow `MainActor.run { }` / `await` hop when `perform()` also does heavy async or non-UI work you don't want pinned to the main actor. What you must **not** do is annotate the intent *type* `@MainActor`: `AppIntent`'s requirements are nonisolated, so a `@MainActor` intent type doesn't compile in the straightforward form (Swift 6 flags `#ConformanceIsolation` — e.g. "main actor-isolated static property 'title' cannot satisfy nonisolated requirement"), and forcing it (isolating the conformance to the main actor) would pin the whole intent — construction, parameter resolution, and `perform()` — to the main actor, which is not the framework's model.

## `perform()` can be re-invoked from the top — make side effects idempotent

A single logical run of an intent can execute your `perform()` body **more than once**. Requesting a missing parameter value (`$param.needsValueError(_:)`) and `AppIntentError.restartPerform` both abort the current pass and run `perform()` again from the beginning. The framework does **not** roll back side effects you already committed on the earlier pass — it just re-enters your function.

So a `perform()` written as a linear script — do the irreversible thing, *then* ask for something the system might need to prompt for — replays the irreversible thing on the restart.

```swift
// AVOID: irreversible side effect before a value request. If `recipient` is
// unset, needsValueError restarts perform() from the top — and the charge
// runs again on the second pass. The user is billed twice.
func perform() async throws -> some IntentResult {
    try await paymentService.charge(amount)            // irreversible, runs first
    guard let recipient else {
        throw $recipient.needsValueError("Send to whom?")  // restarts perform()
    }
    try await paymentService.send(amount, to: recipient)
    return .result(value: amount)
}
```

```swift
// PREFER: resolve and validate everything first; do the irreversible work last,
// after there is nothing left that can trigger a restart. If a restart is still
// possible around irreversible work, guard it with an idempotency key / state
// check so a replay is a no-op.
func perform() async throws -> some IntentResult {
    guard let recipient else {
        throw $recipient.needsValueError("Send to whom?")  // restart happens here…
    }
    // …by the time we reach the charge, all value requests are behind us.
    try await paymentService.charge(amount)
    try await paymentService.send(amount, to: recipient)
    return .result(value: amount)
}
```

Distinguish flow control from failure: `restartPerform` and `needsValueError` are *expected* control flow that preserve the run — don't catch and swallow them as if they were errors. Reserve thrown application errors for genuine failures (see `results-and-errors.md`).

## Confirm *before* destructive work — a cancel throws

`requestConfirmation(...)` is the third flow-control primitive, and it runs opposite to a value request: it `await`s inline in the *same* `perform()` pass, returns normally if the user confirms, and **throws** if they cancel. So it belongs immediately *before* the irreversible action — a cancel then propagates out and aborts `perform()` on its own. Confirming *after* the destructive work is theater, and catching the cancel with `try?` makes "confirm" and "cancel" do the same thing.

```swift
// AVOID: confirming after the destructive work, and swallowing the cancel. The
// notes are already gone; the prompt changes nothing, and `try?` makes a cancel
// indistinguishable from a confirm.
func perform() async throws -> some IntentResult {
    try await store.deleteAllNotes()          // irreversible — already happened
    try? await requestConfirmation(dialog: "Delete all notes?")
    return .result()
}
```

```swift
// PREFER: confirm first. A cancel throws and aborts perform() before anything
// destructive runs; the delete executes only on confirm.
func perform() async throws -> some IntentResult {
    try await requestConfirmation(dialog: "Delete all notes? This can't be undone.")
    try await store.deleteAllNotes()          // runs only if the user confirmed
    return .result()
}
```

The dialog-bearing `requestConfirmation(conditions:actionName:dialog:)` is iOS 18+; the parameterless `requestConfirmation()` is available since iOS 16. Either way, do not wrap the call in `do/catch` or `try?` to "handle" a cancel — let the thrown cancel abort the intent, which is exactly the intended behavior.

## Return through the `.result(...)` factories — never a bare value

`perform()`'s return type is `some IntentResult` (its `PerformResult` associated type). You never construct the result container yourself or return a domain type — you use the `IntentResult.result(...)` factory family, and compose optional outputs through the marker protocols `ReturnsValue<Value>`, `ProvidesDialog`, and `OpensIntent`.

```swift
// AVOID: returning a domain value or a hand-built type. It doesn't conform to
// IntentResult, so it won't compile — and reaching for `some IntentResult` while
// returning a custom struct is a common dead end.
func perform() async throws -> NoteSummary {        // ❌ not an IntentResult
    NoteSummary(count: notes.count)
}
```

```swift
// PREFER: return `some IntentResult` and build it with a `.result(...)` factory.
func perform() async throws -> some ReturnsValue<Int> {
    let count = try await store.noteCount()
    return .result(value: count)
}

// No value to return? `.result()` marks completion.
func perform() async throws -> some IntentResult {
    try await store.archiveAll()
    return .result()
}
```

Let the container type be inferred from the factory and the marker composition; declare only the markers you actually use. Do not name `IntentResultContainer` directly, and do not use the deprecated `OpensAppIntent` associated-type spelling — the current marker is `OpensIntent`.

# Factoring: Choosing Types and Intent Granularity

Two modeling decisions get made *before* any `perform()` is written, and both are hard to reverse once a shortcut is saved against them: what kind of type backs each value a user supplies, and where the boundaries between intents fall. Neither is enforced by the compiler — an `AppEnum` stuffed with runtime data compiles exactly like a well-chosen one, and a single intent that branches on an `action` parameter type-checks as cleanly as ten focused intents. The cost shows up later, as stale option lists, bloated build-time metadata, or an action Siri can't phrase. The two sections below cover each decision; the per-symbol traps for each type live in their own files, cross-referenced rather than repeated here.

## Match the value's *nature* to the type — `AppEnum` for fixed sets, `AppEntity` for queryable data, plain `@Parameter` for free-form input

Three type families back a value a user supplies, and the choice is dictated by *where the set of valid values comes from*, not by how you want it to look in the picker:

- **`AppEnum`** — a set that is FIXED and KNOWN AT COMPILE TIME. The protocol is literally built on `CaseIterable` (`StaticDisplayRepresentable` refines `CaseDisplayRepresentable: CaseIterable`), and the framework's options provider just returns `Array(Enum.allCases)`. Sizes, priorities, sort orders, on/off states.
- **`AppEntity` + an `EntityQuery`** — DYNAMIC, queryable data: rows from a database, results from the network, anything the user created. The valid set is discovered at runtime by the query, not baked into the binary.
- **A plain `@Parameter` of a standard type** (`String`, `Int`, `Bool`, `Date`, a `Measurement`) — FREE-FORM input the user types or dictates, with no enumerable "set of choices" at all.

The common mistake is reaching for `AppEnum` because it is the quickest way to get a selectable list, then filling it with data that varies at runtime.

```swift
// AVOID: an AppEnum standing in for dynamic data. Playlists are user data — they
// change constantly. But AppEnum is CaseIterable, so this list is frozen into the
// binary at build time: the metadata processor extracts every case into the
// app's .actionsdata. New playlists never appear; deleted ones linger as stale
// options; the whole set bloats the shipped metadata. It compiles fine — that's
// the trap.
enum Playlist: String, AppEnum {
    case chillVibes
    case workout
    case roadTrip
    // …regenerated by hand every time the user makes a playlist?  ❌

    static let caseDisplayRepresentations: [Playlist: DisplayRepresentation] = [
        .chillVibes: "Chill Vibes", .workout: "Workout", .roadTrip: "Road Trip",
    ]
}
```

```swift
// PREFER: an AppEntity backed by a query for anything queryable. The valid set is
// fetched live, so it is always current, and only the *type shape* — not the data
// — goes into the metadata. Use AppEnum only for genuinely fixed sets like this
// RepeatMode, whose cases are a closed vocabulary the compiler already knows.
struct Playlist: AppEntity {
    static let defaultQuery = PlaylistQuery()   // discovers valid values at runtime
    var id: UUID
    @Property(title: "Name") var name: String
    var displayRepresentation: DisplayRepresentation { DisplayRepresentation(title: "\(name)") }
}

enum RepeatMode: String, AppEnum {              // genuinely fixed → AppEnum is right
    case off, one, all
    static let caseDisplayRepresentations: [RepeatMode: DisplayRepresentation] = [
        .off: "Off", .one: "Repeat One", .all: "Repeat All",
    ]
}
```

The opposite mistake also happens: modeling free-form input as an entity (a `SearchTermEntity`, a `DurationEntity`) when the user is really just typing text or a number. If there is no meaningful "set of instances to pick from," it is a plain `@Parameter var query: String` or `@Parameter var minutes: Int`, not an entity. Reserve `AppEntity` for things the user could *browse and select*. The per-symbol traps — how `AppEnum` raw values persist, how an `AppEntity`'s `id` must be stable, how the two `EntityQuery` entry points differ — are in `app-enum.md` and `entities-and-queries.md`; parameter-resolution mechanics are in `parameters.md`.

## One intent per atomic user task — not a mega-intent that branches on an `action` parameter

The whole system reasons at the *intent* level. Siri phrases, App Shortcut trigger phrases, Shortcuts' action library, and prediction all key off the individual `AppIntent` type and its `title`. A single intent that takes an `action` enum and switches on it inside `perform()` collapses several user-facing actions into one opaque box the system can only offer as one entry with one title — so "create a note" and "delete a note" become indistinguishable to everything upstream of your code.

```swift
// AVOID: a mega-intent multiplexing distinct tasks through an enum. The system
// sees ONE action titled "Manage Note." It cannot surface "Delete Note" as its
// own Shortcuts action, cannot predict it independently, and cannot map a spoken
// "delete my note" phrase to it — because at the intent level there is only the
// umbrella. The `note` parameter is also meaningless for `.create`, so the
// parameter summary can't read cleanly for every branch.
struct ManageNoteIntent: AppIntent {
    static let title: LocalizedStringResource = "Manage Note"

    enum Action: String, AppEnum {
        case create, delete
        static let caseDisplayRepresentations: [Action: DisplayRepresentation] = [
            .create: "Create", .delete: "Delete",
        ]
    }

    @Parameter var action: Action
    @Parameter var note: NoteEntity?      // unused when action == .create

    func perform() async throws -> some IntentResult {
        switch action {                    // branching hides two tasks in one intent
        case .create: /* … */ break
        case .delete: /* … */ break
        }
        return .result()
    }
}
```

```swift
// PREFER: one intent per atomic task. Each has its own title the system can name,
// phrase, predict, and list independently, and each carries only the parameters
// that task actually needs — so every parameter summary reads correctly.
struct CreateNoteIntent: AppIntent {
    static let title: LocalizedStringResource = "Create Note"
    @Parameter(title: "Title") var title: String
    func perform() async throws -> some IntentResult { /* … */ .result() }
}

struct DeleteNoteIntent: AppIntent {
    static let title: LocalizedStringResource = "Delete Note"
    @Parameter var note: NoteEntity
    func perform() async throws -> some IntentResult { /* … */ .result() }
}
```

Split on the *verb the user would say*, not on incidental code sharing. If two intents share logic, factor that into a helper the app owns and call it from both `perform()` bodies — do not merge the intents to avoid duplication. An intent whose title needs "and/or" or whose parameter set is only partly relevant depending on another parameter is usually two intents wearing one.

# Localization of User-Facing Strings

App Intents localizes differently from ordinary UIKit/SwiftUI code, and the difference is invisible at runtime. Every user-facing string on your intent surface — an intent `title`, an `IntentDescription`, a `DisplayRepresentation`, a `TypeDisplayRepresentation.name`, an `IntentDialog`, a `@Parameter(title:)`, an `AppShortcutPhrase` — is typed as `LocalizedStringResource`, and the localization key that ships in your app's string catalog is harvested **from the source literal at build time**, not from the value the type holds at runtime. The practical consequence: a `LocalizedStringResource` assembled from runtime data is a perfectly valid `LocalizedStringResource` — it compiles, it type-checks, it *looks* localized — but it produces **no extractable key**, so it can never be translated. The sections below cover the two ways this bites.

## Feed literals to the string-bearing initializers — not runtime `String`s

Because the key is scraped from the source, the argument you pass to a string slot must be a literal (or a string interpolation of literals). Route a runtime `String` — a stored property, a fetched value, a computed name — through `LocalizedStringResource(stringLiteral:)` or a `DisplayRepresentation(title:)` built from interpolated runtime data, and the build-time extractor sees no literal to key on. The string still displays in your development language, so the bug survives every test you run in English and only surfaces as untranslated UI in other locales.

```swift
// AVOID: static UI text laundered through a runtime String. `sectionName` is a
// stored value, so LocalizedStringResource(stringLiteral:) has nothing for the
// build-time extractor to key on — no catalog entry is generated, and this text
// ships English-only no matter how complete your localizations are.
struct ArchiveNotesIntent: AppIntent {
    let sectionName: String
    static var title: LocalizedStringResource {
        LocalizedStringResource(stringLiteral: "Archive \(sectionName)")   // no key extracted
    }
}

// AVOID: an entity's display title assembled from runtime data. Same failure —
// the interpolation resolves at runtime, so no localizable template is emitted.
struct NoteEntity: AppEntity {
    var name: String
    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "Note: \(name)")   // looks localized, isn't
    }
}
```

```swift
// PREFER: a literal in the string slot. Because `title` is given a source literal,
// the build-time extractor lifts "Archive Notes" into the catalog and translators
// can reach it.
struct ArchiveNotesIntent: AppIntent {
    static var title: LocalizedStringResource { "Archive Notes" }
    static var description = IntentDescription("Archives the current section of notes.")
}

// PREFER: a literal title with the genuine instance name as an interpolated
// argument. `\(name)` is data, not a translatable phrase — see the next section.
struct NoteEntity: AppEntity {
    var name: String
    static var typeDisplayRepresentation = TypeDisplayRepresentation(name: "Note")
    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "\(name)")
    }
}
```

The same rule governs `@Parameter(title:)`, `IntentDialog`, `AppShortcut` `shortTitle`, and every `AppShortcutPhrase` you list — all of them are `LocalizedStringResource` / `ExpressibleByString(Literal|Interpolation)` slots that extract only from source literals. There's no supported way to make a runtime-assembled value extractable after the fact; the literal has to be in your source. (App Shortcut phrases are extracted into their own string catalog, **`AppShortcuts.xcstrings`**, separate from the app's main `Localizable.xcstrings`; that's where those phrases get localized.)

## Interpolate dynamic values into a localized template — don't concatenate

Dynamic *counts and quantities* are still static UI text with a variable inside, and they must stay translatable. The wrong instinct is to build the whole phrase at runtime by concatenation (which loses the key entirely) or to hand-pluralize with string math (which is unlocalizable and wrong for most languages). Instead, interpolate the number into a **literal** `LocalizedStringResource` and let the framework's numeric-format support drive pluralization from a `.stringsdict`. On `TypeDisplayRepresentation`, that is exactly what `numericFormat` is for: you write `numericFormat: "\(placeholder: .int) books"` as a literal and supply a `.stringsdict` with each plural rule (`zero` / `one` / `other`), so "1 note" vs. "3 notes" — and every locale's plural categories — resolve correctly.

```swift
// AVOID: hand-built plural via runtime concatenation. No literal template is
// extracted, so this can't be translated, and "1 items" / "many" pluralization
// is wrong in most languages.
struct DeleteNotesIntent: AppIntent {
    let count: Int
    var confirmationDialog: IntentDialog {
        IntentDialog(stringLiteral: "Delete " + String(count) + " items")   // unlocalizable
    }
}

// AVOID: naming your entity's count through raw string math instead of numericFormat.
static var typeDisplayRepresentation = TypeDisplayRepresentation(name: "Note")
// …and then formatting "\(count) Notes" by hand elsewhere — no plural rules, no key.
```

```swift
// PREFER: a literal template with the count interpolated as an argument; the
// framework keys on the template and applies the .stringsdict plural rules.
struct DeleteNotesIntent: AppIntent {
    let count: Int
    var confirmationDialog: IntentDialog {
        "Delete \(count) items"   // literal template → extractable, pluralizable
    }
}

// PREFER: TypeDisplayRepresentation.numericFormat with a .stringsdict for the
// entity's counted name. Pair the literal placeholder template with plural
// entries so "1 book" / "2 books" resolve per locale.
static var typeDisplayRepresentation = TypeDisplayRepresentation(
    name: "Book",
    numericFormat: "\(placeholder: .int) books"
)
```

A genuine, per-instance proper noun is a different case and needs no template: a user's note title, a song name, or an album name is *data the user authored*, not UI chrome, so interpolating it into a literal title (`DisplayRepresentation(title: "\(name)")`) is correct and expected — that value is legitimately non-translatable. The rule in this file is narrow: never route your app's own static UI text through a fake-localized wrapper. Instance names may flow through interpolation; static phrases may not.

# Parameter Summaries

`static var parameterSummary` builds the sentence the Shortcuts editor renders for your intent, and the DSL is small: `Summary("…\(\.$x)…") { \.$y }` for the static case, `When(\.$p, .equalTo, v) { … } otherwise: { … }` and `Switch(\.$p) { Case(v) { … } }` for the conditional cases. `Summary`, `When`, `Switch`, `Case`, and `DefaultCase` are typealiases the `AppIntent` protocol vends, so you write them unqualified inside the intent. Every trap below comes from the DSL doing something the plain-English reading of it doesn't suggest — the order the editor shows fields, which fields it shows at all, and what a `When` condition is actually allowed to test.

## The visible order follows the summary, not your `@Parameter` declaration order

`ParameterSummaryString` records the key paths in interpolation order, then the trailing `@ParameterKeyPathsBuilder` block appends its key paths after them. That combined list — not the order you declared the `@Parameter`s in — is the order the Shortcuts editor lays out the fields. So reordering properties in the struct changes nothing; reordering the interpolations (and the block) is the only lever. (Which parameters appear at all is `parameters.md`'s subject — this file is about the order and the conditional shape.)

```swift
// AVOID: assuming the editor mirrors declaration order. You declared amount first,
// but the summary interpolates recipient first — so the editor shows recipient
// above amount. Editing the property order to "fix" the layout does nothing.
@Parameter(title: "Amount")    var amount: Double
@Parameter(title: "Recipient") var recipient: PersonEntity
static var parameterSummary: some ParameterSummary {
    Summary("Send \(\.$recipient) \(\.$amount)")
}
```

```swift
// PREFER: drive the layout from the summary. The field order is exactly the
// interpolation order, then the trailing block — this reads "Send <amount> to
// <recipient>" and lays the editor out that way, regardless of declaration order.
static var parameterSummary: some ParameterSummary {
    Summary("Send \(\.$amount) to \(\.$recipient)") {
        \.$memo
    }
}
```

## A `When` condition tests one parameter's value to show or hide others — the tested key path must be a real `@Parameter`

`When(_:_:_:otherwise:)` takes a key path to an `IntentParameter`, a comparison operator, a value, and two `Summary` blocks: the `when` block applies when the condition holds, the `otherwise` block when it doesn't. It is a value test on an existing parameter, not a general predicate — the first argument must be `\.$someParameter` for a parameter that actually exists on this intent, and the comparison value must match that parameter's type. Use it to reveal parameters only when they're relevant, so the editor isn't cluttered with fields that don't apply.

```swift
// AVOID: hand-writing an "if" that the editor can't see, and mutating parameter
// visibility from perform(). The summary is static metadata read at edit time;
// perform() runs far too late to influence which fields Shortcuts drew. Every
// parameter you interpolate here shows unconditionally.
static var parameterSummary: some ParameterSummary {
    Summary("Create \(\.$kind) event \(\.$recurrenceRule)")
}
@Parameter(title: "Kind")     var kind: EventKind      // AppEnum: .single, .repeating
@Parameter(title: "Repeat")   var recurrenceRule: RecurrenceEntity
```

```swift
// PREFER: gate the extra parameter with When, keyed off the parameter that
// decides its relevance. recurrenceRule appears only for repeating events; for a
// single event the otherwise branch omits it, so the editor stays clean.
static var parameterSummary: some ParameterSummary {
    When(\.$kind, .equalTo, .repeating) {
        Summary("Create \(\.$kind) event \(\.$recurrenceRule)")
    } otherwise: {
        Summary("Create \(\.$kind) event")
    }
}
```

## Pick the `When` comparator that matches the parameter's type — the operators are separate enums

The comparison operator is not one big enum; the initializer overloads accept different operator types, so a mismatch fails to compile rather than doing the wrong thing at runtime. `.equalTo` / `.notEqualTo` are `EquatableComparisonOperator` and need a matching value. `.hasNoValue` / `.hasAnyValue` are `HasValueComparisonOperator` and take no value (test presence of an optional parameter). `.oneOf` is `OneOfComparisonOperator` and takes an array. `.lessThan` / `.lessThanOrEqualTo` / `.greaterThan` / `.greaterThanOrEqualTo` are `ComparableComparisonOperator` for `Comparable` values. Reaching for `.equalTo` with an array, or passing a value to `.hasAnyValue`, is a type error — not a silent no-op.

```swift
// AVOID: using an equality comparator to mean "is one of these" or "is set". These
// don't type-check: .equalTo wants a single value, not an array, and .hasAnyValue
// takes no value at all — the presence check has its own no-argument overload.
static var parameterSummary: some ParameterSummary {
    When(\.$priority, .equalTo, [.high, .urgent]) {   // wrong: .equalTo isn't array-shaped
        Summary("Flag \(\.$task)")
    } otherwise: {
        Summary("Add \(\.$task)")
    }
}
```

```swift
// PREFER: .oneOf for membership (takes an array); the no-value overload for
// "is this optional parameter set". Each operator lives in its own enum, so the
// value shape is dictated by the comparator you chose.
static var parameterSummary: some ParameterSummary {
    When(\.$priority, .oneOf, [.high, .urgent]) {
        Summary("Flag \(\.$task) with \(\.$reason)")
    } otherwise: {
        Summary("Add \(\.$task)")
    }
}
```

## `Switch`/`Case` branch a summary over one parameter's discrete values — cover the rest with `DefaultCase`

For a parameter with several discrete values, `Switch(\.$param) { Case(value) { Summary(…) } … }` is clearer than nesting `When`s. Each `Case` takes a single value or an array of values (`Case([.a, .b])`) and a `Summary` block; `DefaultCase { Summary(…) }` covers everything not matched. Because it is a `switch`-style construct, a value that hits no `Case` and has no `DefaultCase` has no summary to render — add a `DefaultCase` so every possible value maps to something.

```swift
// AVOID: a Switch that omits DefaultCase while the Cases don't cover every value.
// mode is an AppEnum with three cases but only two are handled — when mode is the
// third value, no branch matches and the editor has no summary to show for it.
static var parameterSummary: some ParameterSummary {
    Switch(\.$mode) {
        Case(.photo) { Summary("Capture photo \(\.$resolution)") }
        Case(.video) { Summary("Record video \(\.$resolution) \(\.$frameRate)") }
    }
}
@Parameter(title: "Mode") var mode: CaptureMode   // AppEnum: .photo, .video, .timelapse
```

```swift
// PREFER: handle the covered values explicitly and route the rest through
// DefaultCase, so every value of mode maps to a summary. Case also accepts an
// array — Case([.photo, .timelapse]) — when several values share one layout.
static var parameterSummary: some ParameterSummary {
    Switch(\.$mode) {
        Case(.video) { Summary("Record video \(\.$resolution) \(\.$frameRate)") }
        DefaultCase { Summary("Capture \(\.$mode) \(\.$resolution)") }
    }
}
```

## A literal `%` in the summary string is auto-escaped — type it once

The summary format string uses `%`-prefixed tokens internally to mark where each interpolated parameter goes, so a literal percent sign in your text has to be escaped. The string interpolation does this for you: literal segments have `%` doubled to `%%` automatically. So write the percent once, as you'd say it — do not pre-escape it yourself, or you'll get a doubled `%%` in the rendered sentence.

```swift
// AVOID: manually escaping the percent. The literal is already escaped for you, so
// "%%" here becomes "%%" on screen — a stray doubled sign in the shortcut label.
static var parameterSummary: some ParameterSummary {
    Summary("Apply \(\.$discount)%% off")
}
```

```swift
// PREFER: write the percent once. The interpolation doubles it internally so the
// token machinery is unambiguous, and the user sees a single "%".
static var parameterSummary: some ParameterSummary {
    Summary("Apply \(\.$discount)% off")
}
```

# Parameters and Resolution

`@Parameter` looks like a plain stored property, but its resolution is a small state machine the framework drives before and during `perform()` — and four of its behaviors contradict the property-wrapper mental model. A missing value can be resolved *inline* or by *restarting* `perform()`, and the two spellings are not interchangeable. A non-optional parameter does not always throw when unfilled — sometimes the framework silently asks the user to pick. Options that depend on another parameter cannot read that parameter directly. And a parameter you never name in your `Summary` simply does not appear in the Shortcuts editor. Each has a distinct trap; the sections below cover all four. (Restart semantics and flow-control-vs-failure are `execution-model.md`'s domain — this file assumes them.)

## Resolve a missing value inline with `requestValue`, or restart with `needsValueError` — they are not the same

Both `$param.requestValue(_:)` and `$param.needsValueError(_:)` prompt the user for a value, but they run at opposite ends of a spectrum. `requestValue(_:)` is `async` — you `await` it and it returns the resolved value *inline*, so the code after it keeps running in the same `perform()` invocation. `needsValueError(_:)` returns an `AppIntentError` you `throw` — it aborts the current pass and re-runs `perform()` from the top with the value now filled. Reach for the wrong one and you either can't get a value where you need it, or you silently opt into a restart (and its replay hazard).

```swift
// AVOID: throwing needsValueError to get a value you need *right here*. This
// doesn't return the value — it aborts and restarts perform() from the top, so
// the two lines below never run on this pass. Worse, any side effect already
// committed this pass replays on the restart.
func perform() async throws -> some IntentResult {
    try await log.append("starting split")          // committed…
    guard let payer else {
        throw $payer.needsValueError("Who paid?")     // …restart replays the append
    }
    let share = try await splitService.compute(for: payer)
    return .result(value: share)
}
```

```swift
// PREFER: requestValue when you need the value inline. It's async — await it and
// the resolved value flows into the same invocation; nothing restarts, nothing
// replays. Reserve needsValueError for when a restart is what you actually want.
func perform() async throws -> some IntentResult {
    let payer = try await $payer.requestValue("Who paid?")   // returns inline
    try await log.append("starting split")
    let share = try await splitService.compute(for: payer)
    return .result(value: share)
}
```

Do not reach for the old `requestValue(_:) -> Error` spelling that returns an `Error` to throw — it is `@available(*, deprecated)` and its message points you at exactly these two replacements. If a `requestValue` call returns something you `throw` rather than a value you `await`, you are on the deprecated overload.

## A non-optional `AppEnum` parameter auto-disambiguates — it does not throw a needs-value error

The rule "an unfilled non-optional `@Parameter` throws a needs-value error" is only half true. When such a parameter's type is an `AppEnum`, the framework instead gathers the enum's options and *auto-disambiguates*: with more than one option it asks the user to pick; with exactly one option it silently assigns that option and moves on. Only non-enum non-optional parameters fall through to a plain needs-value error. So a summary/dialog you write assuming "the user will be asked to type a value" is wrong for enums — they get a picker, driven by your `requestDisambiguationDialog`, not your `requestValueDialog`.

```swift
// AVOID: relying on a needs-value prompt for a non-optional AppEnum, and leaving
// the disambiguation dialog unset. The framework auto-disambiguates a multi-case
// enum with a *picker*, and falls back to a generic dialog — the user sees no
// useful prompt. (And a single-case enum is auto-assigned with no prompt at all.)
struct SetPriorityIntent: AppIntent {
    static let title: LocalizedStringResource = "Set Priority"
    @Parameter(title: "Priority")
    var priority: TaskPriority        // AppEnum: .low, .medium, .high
    // ...
}
```

```swift
// PREFER: provide requestDisambiguationDialog — that's the prompt the auto-
// disambiguation actually uses for a multi-case AppEnum. requestValueDialog is
// the wrong slot for an enum; it's the fallback for non-enum types.
struct SetPriorityIntent: AppIntent {
    static let title: LocalizedStringResource = "Set Priority"
    @Parameter(
        title: "Priority",
        requestDisambiguationDialog: "Which priority level?"
    )
    var priority: TaskPriority
    // ...
}
```

The single-case corollary matters for review: an `AppEnum` (or dynamic options list) that resolves to exactly one option is assigned with no user interaction, so any UI you expected around "the user chose the priority" never happens.

## Options that depend on another parameter need `@IntentParameterDependency` — you cannot read the sibling `@Parameter`

Inside a `DynamicOptionsProvider` or `EntityQuery`, the enclosing intent's other `@Parameter`s are not yet filled — reading them gives you nothing usable, because option-fetching runs *before* full resolution. To base one parameter's options on another's chosen value, declare an `@IntentParameterDependency<TheIntent>(\.$otherParam)` inside the provider/query and read the depended-on value through its projection. This is the only supported channel for cross-parameter option logic.

```swift
// AVOID: trying to read a sibling parameter's value from inside the query. There
// is no instance of the intent to read here, and the value isn't resolved yet at
// options-fetch time — so this can't compile against the intent's parameters and
// has nothing to read even conceptually.
struct RoomQuery: EntityStringQuery {
    func entities(matching string: String) async throws -> [RoomEntity] {
        let building = /* ??? no access to BookRoomIntent.$building here */
        return try await RoomStore.rooms(in: building, matching: string)
    }
}
```

```swift
// PREFER: declare the dependency; read the other parameter through its projection.
struct RoomQuery: EntityStringQuery {
    @IntentParameterDependency<BookRoomIntent>(\.$building)
    var bookRoom

    func entities(matching string: String) async throws -> [RoomEntity] {
        guard let bookRoom else { return [] }        // building not yet chosen
        return try await RoomStore.rooms(in: bookRoom.building, matching: string)
    }
}
```

Guard the optional projection (`guard let bookRoom else { return [] }`) as shown — if the depended-on parameter is unset, the projection is unavailable and returning empty options is the graceful path. Do not force-unwrap the projected member: the wrapper `fatalError`s if you read a key path you did not list in the `@IntentParameterDependency`, so list every parameter you intend to read.

## Only parameters named in `Summary` show in the Shortcuts editor

`ParameterSummary` is not cosmetic — it is the allowlist for which parameters the Shortcuts editor surfaces. A parameter interpolated into the `ParameterSummaryString` (the `"…\(\.$param)…"` form) is shown; one added through the trailing `@ParameterKeyPathsBuilder` block of `Summary(_:)` is shown; every other `@Parameter` is silently omitted from the editor UI, even though it still exists and still resolves. So a parameter that "isn't editable in Shortcuts" is usually a parameter you forgot to mention in the summary — not a bug.

```swift
// AVOID: a summary that mentions only some parameters. `note` is interpolated so
// it shows; `folder` and `isPinned` are never named anywhere in the summary, so
// they simply don't appear in the Shortcuts editor — users can't set them.
static var parameterSummary: some ParameterSummary {
    Summary("Save \(\.$note)")
}
@Parameter(title: "Note")   var note: String
@Parameter(title: "Folder") var folder: FolderEntity
@Parameter(title: "Pinned") var isPinned: Bool
```

```swift
// PREFER: interpolate the parameters that belong in the sentence, and list the
// rest in the trailing key-path block so they still surface as editable rows.
static var parameterSummary: some ParameterSummary {
    Summary("Save \(\.$note) to \(\.$folder)") {
        \.$isPinned
    }
}
```

If a parameter should be user-configurable in Shortcuts, it must appear in the summary one way or the other. Omission is a valid choice for parameters that are only ever filled programmatically (e.g. from a preceding intent's output) — but make it a deliberate one.

# Designing Errors Thrown from `perform()`

This file is about the *error* side of `perform()` — the `.result(...)` return shapes are covered in `execution-model.md`. The trap here is that throwing feels uniform ("throw an `Error`, the system shows it") but it is not. The framework inspects the *type* of what you throw. On Siri and Shortcuts a plain `Error` is presented to the user as a generic failure; conform to `CustomLocalizedStringResourceConvertible` to give the user a real message. The two subsections below cover the two correct ways to throw a user-meaningful failure: conform your own error type, or throw one of the framework's prebuilt errors.

## A bare `Error` gives the user a generic failure: conform to `CustomLocalizedStringResourceConvertible`

When `perform()` throws, the framework routes the error by type. If your error conforms to `CustomLocalizedStringResourceConvertible`, its `localizedStringResource` is serialized and delivered to Siri/Shortcuts as the failure message. Any other `Error` is sanitized and logged as an unknown error; on Siri and Shortcuts the user then sees a generic "something went wrong" rather than your `errorDescription` / `LocalizedError` text. `LocalizedError` is *not* the protocol the framework keys on here.

```swift
// AVOID: a plain Error (even a LocalizedError). Siri/Shortcuts show the user a
// generic failure, not "Playlist is full."
enum LibraryError: LocalizedError {
    case playlistFull
    var errorDescription: String? { "Playlist is full." }   // not shown by Siri/Shortcuts
}

func perform() async throws -> some IntentResult {
    guard playlist.hasRoom else { throw LibraryError.playlistFull }  // genericized
    // …
    return .result()
}
```

```swift
// PREFER: conform the error to CustomLocalizedStringResourceConvertible. The
// framework reads `localizedStringResource` and surfaces it verbatim.
enum LibraryError: Error, CustomLocalizedStringResourceConvertible {
    case playlistFull

    var localizedStringResource: LocalizedStringResource {
        switch self {
        case .playlistFull: "This playlist is full. Remove a song to add another."
        }
    }
}

func perform() async throws -> some IntentResult {
    guard playlist.hasRoom else { throw LibraryError.playlistFull }  // message preserved
    // …
    return .result()
}
```

Note the asymmetry with parameter resolution: `$param.needsValueError(_:)` and `AppIntentError.restartPerform` are flow control the framework *expects* (see `execution-model.md`), whereas a thrown application error is a terminal failure. Reserve conforming error types for genuine failures; don't reach for them to drive prompting.

## Use the prebuilt `AppIntentError` cases for standard failure shapes

For the common failure categories the system already knows how to present — a permission is missing, the user must take an action first, the operation cannot recover — throw one of the prebuilt `AppIntentError` static values instead of hand-writing a message. They come grouped under three enums: `AppIntentError.PermissionRequired`, `AppIntentError.UserActionRequired`, and `AppIntentError.Unrecoverable`. `AppIntentError` itself conforms to `CustomLocalizedStringResourceConvertible`, so these carry a localized message *and* a system-recognized category, which lets Siri respond appropriately (e.g. surfacing a sign-in affordance). These prebuilt categories — and `AppIntentError`'s `CustomLocalizedStringResourceConvertible` conformance — are available on iOS 18 / macOS 15 and later; the conform-your-own-error approach in the previous section works back to iOS 16.

```swift
// AVOID: a hand-rolled message for a category the system already models. You lose
// the system's built-in presentation/response for "needs sign-in," and you now own
// localization of a string the framework already ships.
enum LibraryError: Error, CustomLocalizedStringResourceConvertible {
    case notSignedIn
    var localizedStringResource: LocalizedStringResource { "You need to sign in." }
}

func perform() async throws -> some IntentResult {
    guard account.isSignedIn else { throw LibraryError.notSignedIn }
    return .result()
}
```

```swift
// PREFER: throw the prebuilt error for the category. Localized + system-recognized.
func perform() async throws -> some IntentResult {
    guard account.isSignedIn else {
        throw AppIntentError.UserActionRequired.signin
    }
    guard hasPhotoAccess else {
        throw AppIntentError.PermissionRequired.photos
    }
    guard let match = try await store.find(query) else {
        throw AppIntentError.Unrecoverable.entityNotFound
    }
    return .result()
}
```

Reach for a custom `CustomLocalizedStringResourceConvertible` error (the previous subsection) only when your failure is domain-specific and *isn't* one of the prebuilt categories. `AppIntentError.Unrecoverable.unknown` is deprecated — prefer a prebuilt case that names the actual failure, or a custom conforming error with a clear description, over the catch-all. The same type-based routing governs errors thrown from an `EntityQuery` method such as `entities(for:)`, not just `perform()`, so apply these rules wherever a user-visible failure escapes your intent code.

# URL Representation & Opening

Three different mechanisms open content, and they are not interchangeable. `OpenIntent` is a marker protocol that names a `target` for the system to open. `OpenURLIntent` is a built-in intent that hands a `URL` to your app's universal-link handler. `URLRepresentableIntent`/`URLRepresentableEntity`/`URLRepresentableEnum` map a type *to* a universal link so the system opens it without running your `perform()` at all. Picking the wrong one — or writing a `perform()` that fights the URL machinery, or letting the URL mapping drift — are the recurring traps. `OpenIntent` is iOS 16+; everything URL-representable (including `OpenURLIntent`) is iOS 18+.

## `OpenIntent` supplies a `target` — don't hand-roll the foregrounding

`OpenIntent` is a marker protocol: it adds one requirement, `var target: Value { get set }`, and the system opens whatever that property holds (an `AppEntity` or `AppEnum`). Adopting it makes `openAppWhenRun` default to `true`, so the app is brought to the foreground for you; the protocol also supplies a default `perform()` that just returns `.result()`. Reimplementing the foregrounding yourself — a plain `AppIntent` with a URL parameter and an ad-hoc open in `perform()` — throws away the marker the system keys off of, and the naming/discovery benefits that come with it.

```swift
// AVOID: a plain AppIntent faking "open" behavior. Nothing marks this as an
// open intent, so Spotlight/Shortcuts can't populate a target, and you're
// manually reaching into app state to foreground — off-actor, in perform().
struct ShowNoteIntent: AppIntent {
    static let title: LocalizedStringResource = "Show Note"
    @Parameter var note: NoteEntity

    func perform() async throws -> some IntentResult {
        AppState.shared.present(note)   // hand-rolled foregrounding
        return .result()
    }
}
```

```swift
// PREFER: conform to OpenIntent and expose `target`. openAppWhenRun becomes
// true automatically; the system foregrounds the app and hands you the item.
struct ShowNoteIntent: OpenIntent {
    static let title: LocalizedStringResource = "Show Note"
    @Parameter var target: NoteEntity

    func perform() async throws -> some IntentResult {
        await MainActor.run { AppState.shared.present(target) }
        return .result()
    }
}
```

`OpenIntent` refines `SystemIntent`, which refines `AppIntent` — it is an ordinary intent with one extra property, not a separate execution path. The `perform()` body still runs under the actor rules in `execution-model.md`: it is not `@MainActor`, so hop explicitly before touching UI state.

## Return `OpenURLIntent` for a URL — don't open URLs off your own bat

`OpenURLIntent` is the built-in intent for opening a universal link. Construct it with a `URL` (`OpenURLIntent(url)`), or from a URL-representable enum/entity via its throwing initializers, and *return* it as the result of another intent's `perform()` through the `OpensIntent` marker. It is also the intent you attach to a widget or Live Activity button to deep-link into your app. It is not a place to call your own URL-opening API from inside `perform()` — doing so bypasses the system's foregrounding and result plumbing.

```swift
// AVOID: opening a URL by side effect inside perform(). There's no opener API
// available to an intent that may run in an extension, and even where one
// exists this races the actor and returns nothing the system can chain on.
func perform() async throws -> some IntentResult {
    let url = URL(string: "https://example.com/notes/\(note.id)")!
    UIApplication.shared.open(url)   // wrong layer; off-actor; not returnable
    return .result()
}
```

```swift
// PREFER: return an OpenURLIntent through the .result(opensIntent:) factory.
// The system foregrounds the app and drives the URL into your universal-link
// handler for you.
func perform() async throws -> some OpensIntent {
    let url = URL(string: "https://example.com/notes/\(note.id)")!
    return .result(opensIntent: OpenURLIntent(url))
}
```

The two entity/enum initializers are `throws`/`async throws` and raise when the value has no valid URL representation — call them with `try`/`try await`, don't force-unwrap around them.

## Adopt `URLRepresentableIntent` and leave `perform()` alone

If your intent already maps cleanly to a universal link, conform to `URLRepresentableIntent` and provide `static var urlRepresentation: URLRepresentation`. The protocol supplies `perform()` for you (it opens the URL and never returns normally), and — critically — combining it with `OpenIntent` flips `openAppWhenRun` to `false` and routes the open entirely through your URL handler. Writing your own `perform()` body next to a URL representation is the trap: the system opens the URL via the URL path, so any work you put in `perform()` either never runs or runs redundantly. The doc guidance is explicit — when a URL is present, `perform()` should do nothing.

```swift
// AVOID: a URL representation AND a hand-written perform() that does real work.
// When a URL representation exists the system opens via the URL, so this body
// is dead code at best and a double-open at worst.
struct OpenPageIntent: URLRepresentableIntent {
    static let title: LocalizedStringResource = "Open Page"
    static var urlRepresentation: URLRepresentation = "https://example.com/\(\.$page)"

    @Parameter(title: "Page") var page: String

    func perform() async throws -> some IntentResult {
        try await Router.shared.navigate(to: page)   // won't run via URL path
        return .result()
    }
}
```

```swift
// PREFER: declare only the URL representation. The default perform() from the
// protocol handles opening; your universal-link code is the single entry point.
struct OpenPageIntent: URLRepresentableIntent {
    static let title: LocalizedStringResource = "Open Page"
    static var urlRepresentation: URLRepresentation = "https://example.com/\(\.$page)"

    @Parameter(title: "Page") var page: String
}
```

This protocol requires real universal-link support (`applinks:` associated domains) — it explicitly does *not* work with custom URL schemes. If you only have a custom scheme, this is the wrong tool; use an `OpenIntent` with a `perform()` that navigates instead.

## Build the URL by interpolating parameter *key paths*, not values

`URLRepresentation` is `IntentURLRepresentation<Self>` (and `EntityURLRepresentation<Self>` / `EnumURLRepresentation<Self>` for entities/enums), an `ExpressibleByStringInterpolation` builder. Its interpolation segment does not accept a value — it accepts a **key path to the parameter** (`\(\.$page)` for an intent parameter, `\(\.$contentID)` for an entity property). The builder records the key path and substitutes the resolved value when the URL is produced. Interpolating a plain expression (or the property's current value) is the subtle failure: it either won't type-check against the key-path overload or bakes in a stale value instead of a live placeholder.

```swift
// AVOID: interpolating a value or a bare property instead of the key path. This
// does not match the key-path interpolation the builder expects; it captures a
// snapshot rather than a placeholder the system fills at resolution time.
static var urlRepresentation: URLRepresentation = "https://example.com/\(page)"
```

```swift
// PREFER: interpolate the key path to the projected parameter. For an intent
// use \(\.$param); for an entity use \(\.$property). The builder substitutes
// the resolved value when it forms the URL.
static var urlRepresentation: URLRepresentation = "https://example.com/\(\.$page)"
```

Only URL-friendly parameter types substitute automatically — `String`, `Int`, and `URL`. For any other type, conform it to `CustomURLRepresentationParameterConvertible` and return a URL-safe string from `urlRepresentationParameter`; otherwise the segment resolves to empty. For an `AppEnum`, `EnumURLRepresentation` interpolates the *case* (`\(.rawValue)` or a specific case) rather than a key path, and takes a `[Enum: EnumSingleURLRepresentation]` dictionary overload when cases need distinct URLs — reach for the dictionary instead of branching inside a single format string.

## Treat the URL mapping as a stable contract, like ids and phrases

A `urlRepresentation` is a promise about how your content is addressed: existing widgets, Live Activities, shared links, and Spotlight results embed URLs built from today's format. Changing the path shape, renaming an interpolated parameter, or dropping a segment silently breaks every already-minted link — the same durability rule that governs entity `id`s and `AppShortcut` phrases. Evolve the mapping additively; keep old URLs resolvable.

```swift
// AVOID: restructuring the URL format in place. Every link already handed to a
// widget, share sheet, or Spotlight result was built on the old shape and now
// 404s in your universal-link handler.
static var urlRepresentation: URLRepresentation = "https://example.com/v2/item/\(\.$id)"
// was: "https://example.com/notes/\(\.$id)"
```

```swift
// PREFER: keep the established path stable so old links keep resolving; layer
// new capability behind additional parameters or new routes your handler also
// understands, rather than rewriting the contract.
static var urlRepresentation: URLRepresentation = "https://example.com/notes/\(\.$id)"
```

The same discipline applies to `URLRepresentableEntity` — its `urlRepresentationParameter` defaults to the entity's identifier string, so the id and the URL are one contract. Keep the entity id stable (see `entities-and-queries.md`) and the URL stays stable with it.