ios-app-intents

# iOS App Intents ## Overview Expose the smallest useful action and entity surface to the system. Start with the verbs and objects people would actually want outside the app, then implement a narrow App Intents layer that can deep-link or hand off cleanly into the main app when needed. Read these references as needed: - `references/first-pass-checklist.md` for choosing the first intent and entity surface - `references/example-patterns.md` for concrete example shapes to copy and adapt - `references/code-templates.md` for generalized App Intents code templates - `references/system-surfaces.md` for how to think about Shortcuts, Siri, Spotlight, widgets, and other system entry points ## Core workflow ### 1) Start with actions, not screens - Identify the requested high-value actions that should work outside the app UI. - Prefer verbs like compose, open, find, filter, continue, inspect, or start. - Do not mirror the entire app navigation tree as intents. ### 2) Define a small entity surface - Add `AppEntity` types only for the objects the system needs to understand or route. - Keep the entity shape narrower than the app's persistence model. - Add `EntityQuery` or other query types only where disambiguation or suggestions are genuinely useful. ### 3) Decide whether the action completes in place or opens the app - Use non-opening intents for actions that can complete directly from the system surface. - Use `openAppWhenRun` or open-style intents when the user should land in a specific in-app workflow. - When the app must react inside the main scene, add one clear runtime handoff path instead of scattering ad hoc routing logic. - If the action can work in both modes, consider shipping both an inline version and an open-app version rather than forcing one compromise. ### 4) Make the actions discoverable - Add `AppShortcutsProvider` entries for the first set of high-value intents. - Choose titles, phrases, and symbols that make sense in Shortcuts, Siri, and Spotlight. - Keep shortcut phrases direct and task-oriented. - Reuse the same action model for widgets and controls when a widget configuration or intent-driven control already needs the same parameters. ### 5) Validate the runtime handoff - Build the app and confirm the intents target compiles cleanly. - Verify the app opens or routes to the expected place when an intent runs. - Summarize which actions are now exposed, which entities back them, and how the app handles invocation. ## Strong defaults - Keep the system-facing layer isolated within the existing structure; add a dedicated target only when required. - Keep intent types thin; business logic should stay in app services or domain models. - Keep app entities small and display-friendly. - Use `AppEnum` for fixed app choices such as tabs, modes, or visibility levels before reaching for a full entity type. - Prefer one predictable app-intent routing surface in the main app scene or root router. - Treat App Intents as system integration infrastructure, not only as a Shortcuts feature. ## Anti-patterns - Exposing every screen or tab as its own intent without a real user value. - Mirroring the entire model graph as `AppEntity` types. - Hiding runtime handoff in global side effects with no clear app entry path. - Adding App Shortcuts with vague phrases or generic titles. - Treating the first App Intents pass as a broad taxonomy project instead of a small useful release. ## Notes - Apple documentation to use as primary references: - `https://developer.apple.com/documentation/appintents/making-actions-and-content-discoverable-and-widely-available` - `https://developer.apple.com/documentation/appintents/creating-your-first-app-intent` - `https://developer.apple.com/documentation/appintents/adopting-app-intents-to-support-system-experiences` - In addition to the links above, use web search to consult current Apple Developer documentation when App Intents APIs or platform behavior may have changed. - A good first pass often includes one open-app intent, one action intent, one or two entity types, and a small `AppShortcutsProvider`. - Good example families to cover are: - open a destination or editor in the app - perform a lightweight action inline without opening the app - choose from a fixed enum such as a tab or mode - resolve one or more entities through `EntityQuery` - power widget configuration or controls from the same entity surface