@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

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

@@ -1,169 +1,269 @@
 ---
 name: app-clips
-description: "Build iOS App Clips with invocation URLs, App Clip Codes, NFC, QR codes, Safari banners, Maps, Messages, target setup, App Store Connect experiences, size/capability constraints, NSUserActivity routing, SKOverlay promotion, App Group/keychain handoff, ephemeral notifications, location confirmation, and full-app migration. Use when creating App Clips or wiring App Clip invocation, experience configuration, or full-app handoff."
+description: "iOS App Clips: target setup, invocation from NFC, App Clip Codes, QR, Messages, Maps and Safari banners, App Store Connect experiences, size limits and capability constraints, NSUserActivity routing, SKOverlay promotion, App Group or keychain handoff, ephemeral notifications, location confirmation, migration to the full app. Use when building a clip, wiring invocation, configuring experiences or handing off to the full app."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
 # App Clips
 
-Lightweight, instantly available versions of your iOS app for in-the-moment experiences or demos. Targets iOS 26+ / Swift 6.3 unless noted.
-
-## Contents
-
-- [App Clip Target Setup](#app-clip-target-setup)
-- [Invocation and Experience Routing](#invocation-and-experience-routing)
-- [Size and Capability Decisions](#size-and-capability-decisions)
-- [Data, Notifications, and Location](#data-notifications-and-location)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
-
-## App Clip Target Setup
-
-An App Clip is a **separate target** in the same Xcode project as your full app:
-
-1. **File → New → Target → App Clip**  -  Xcode creates the App Clip target, adds the **Embed App Clip** build phase to the full app target, and wires the association entitlements.
-2. The App Clip bundle ID **must** be prefixed by the full app's bundle ID: `com.example.MyApp.Clip`.
-3. Verify raw entitlement keys when diagnosing archive, signing, or App Store Connect failures:
-   - App Clip target: `com.apple.developer.on-demand-install-capable`
-   - App Clip target parent app link: `com.apple.developer.parent-application-identifiers`
-   - Full app target associated App Clip link: `com.apple.developer.associated-appclip-app-identifiers`
-
-Use Swift packages or shared source files for code needed by both targets. Add App Clip-specific compile branches with the `APPCLIP` active compilation condition, and avoid linking full-app-only frameworks into the App Clip target.
-
-## Invocation and Experience Routing
-
-Read [`references/routing-and-experiences.md`](references/routing-and-experiences.md) when implementing invocation URL routing, App Store Connect experiences, Local Experiences, Safari Smart App Banners, QR/NFC/App Clip Codes, AASA, or associated domains.
-
-App Clips receive `NSUserActivityTypeBrowsingWeb` activities. Keep the invocation router shared with the full app because, after installation, the full app replaces the App Clip and receives future invocations.
-
-- SwiftUI: use `.onContinueUserActivity(NSUserActivityTypeBrowsingWeb)`.
-- UIKit cold launch: inspect `connectionOptions.userActivities` in `scene(_:willConnectTo:options:)`.
-- UIKit continuation: handle the actual `NSUserActivity` in `scene(_:continue:)`.
-- `scene(_:willContinueUserActivityWithType:)` is only advance notice and does not provide the URL.
-
-Configure the required default App Clip experience in App Store Connect. Use advanced experiences for Maps integration, location association, production App Clip Codes, per-location cards, and precise physical-place routing; demo App Clip Codes can use the short demo App Clip link.
-
-For custom URLs, add `appclips:example.com` to Associated Domains on both the full app and App Clip targets, and host an AASA file with the App Clip app identifier. For Safari banners, use `app-id`, `app-clip-bundle-id`, and optional `app-clip-display=card`; do not rely on `app-argument` for App Clip launches.
-
-## Size and Capability Decisions
-
-Read [`references/size-capabilities-and-promotion.md`](references/size-capabilities-and-promotion.md) before feasibility reviews or capability audits, and when checking size budgets, measurement, Background Assets, SKOverlay, Live Activities App Clip extension constraints, CloudKit limits, or unsupported capabilities.
-
-Always measure App Clip size with the App Thinning Size Report. In feasibility reviews, explicitly choose the size limit from deployment target, invocation support, and connectivity: the larger iOS 17+ limit applies to digital-only App Clips where reliable internet is likely; physical invocation or iOS 16 support uses a smaller budget; demo links can use the current 100 MB limit while supporting NFC/QR test invocations, and demo App Clip Codes require the short demo link. Apple has changed App Clip size policy over time, so re-check current App Store Connect and App Clip documentation before release-blocking size decisions.
-
-Use Background Assets only for content that can arrive after launch without blocking the in-the-moment task, and do not mark App Clip background asset downloads as essential. Large bundled media, ML models, catalogs, or downloads that must finish before useful work are poor App Clip fits; state that required pre-task downloads are not acceptable for in-the-moment App Clips, and check download size plus whether any required download blocks useful work. Move those flows to streaming/server-backed content, post-task assets, or the full app. Show `SKOverlay.AppClipConfiguration` or SwiftUI `appStoreOverlay` only after task completion, never as a gate.
-
-App Clips can use CloudKit public database reads on iOS 16+ with `CloudKit-Anonymous`, but cannot write the public database or use iCloud Documents, key-value storage, private containers, or shared containers. App Clips can offer Live Activities through an App Clip-only widget extension starting in iOS 16. That extension can include only Live Activities and needs the App Clip Extension capability; always include the raw entitlement key `com.apple.developer.on-demand-install-capable` when reviewing this boundary.
-
-In feasibility reviews, explicitly name unsupported App Clip runtime features instead of summarizing them generically. Always list `SKAdNetwork`, `App Tracking Transparency`, and custom URL schemes when discussing excluded runtime features, alongside App Intents, Background Tasks, background URL sessions, in-app purchases, durable persistent local state, and background/persistent assumptions. Route detailed ActivityKit/WidgetKit Live Activity work, StoreKit purchase/full-app monetization, BackgroundTasks processing, CloudKit schema or sync beyond public reads, durable credentials, and long-term state to sibling or full-app domains without implementation detail. For product/PM feasibility reviews, stay at the App Clip boundary level: capability fit, size basis, invocation constraints, and handoff destinations. Describe location confirmation, install promotion, App Group/keychain handoff, and Live Activities conceptually. Do not add Swift package decomposition, API symbols such as `APActivationPayload`, `CLCircularRegion`, or `SKOverlay.AppClipConfiguration`, App Group/keychain implementation recipes, or other API-level implementation guidance unless the user asks for implementation.
-
-## Data, Notifications, and Location
-
-Read [`references/data-handoff-notifications-location.md`](references/data-handoff-notifications-location.md) when implementing App Group/full-app migration, keychain or Sign in with Apple handoff, ephemeral notifications, notification relaunch routing, or physical location confirmation.
-
-Use App Groups/shared containers for non-secret handoff data only. Any target provisioned with the App Group entitlement can read and write the shared container/defaults suite, so it is not a trust boundary. Do not put passwords, refresh tokens, payment credentials, or other secrets there.
-
-Starting in iOS 15.4, the full app can access keychain items created by its corresponding App Clip only when the App Clip and full app have the correct association entitlements, including the full app's `com.apple.developer.associated-appclip-app-identifiers`. The App Clip cannot read keychain items created by the full app.
-
-For Sign in with Apple handoff, store the `ASAuthorizationAppleIDCredential.user` identifier and have the full app verify `ASAuthorizationAppleIDProvider.getCredentialState(forUserID:) == .authorized`.
-
-For ephemeral notifications, set `NSAppClipRequestEphemeralUserNotification` under the App Clip target's `NSAppClip` `Info.plist` dictionary. Authorization can last up to 8 hours after each launch, but users can disable it on the App Clip card, so check notification settings for `.ephemeral` before scheduling. Notification taps relaunch without the original invocation URL, so route multi-experience notifications with APNs `target-content-id` for remote notifications or `UNNotificationContent.targetContentIdentifier` for local notifications. Use a URL matching the relevant App Store Connect advanced App Clip experience, not an arbitrary opaque ID.
-
-For physical-location confirmation, use `NSUserActivity.appClipActivationPayload` / `APActivationPayload.confirmAcquired(in:)` with a `CLCircularRegion` radius up to 500 meters, and set `NSAppClipRequestLocationConfirmation` under the App Clip target's `NSAppClip` `Info.plist` dictionary, not the full app's. This confirms eligible physical invocations without granting continuous location access.
-
-## Common Mistakes
-
-### Exceeding the applicable App Clip size limit
-
-Choose the limit based on deployment target and invocation support. A physically invoked App Clip that supports iOS 16 has a much smaller budget than an iOS 17+ digital-only App Clip. Measure with the App Thinning Size Report after meaningful target changes.
-
-### Mixing up App Clip entitlement names
-
-```text
-App Clip target:
-com.apple.developer.on-demand-install-capable
-com.apple.developer.parent-application-identifiers
-
-Full app target:
-com.apple.developer.associated-appclip-app-identifiers
+A clip is a tiny, instantly launched piece of an app. Someone scans a code,
+taps a tag or follows a link, finishes one job, and leaves without installing
+anything. This skill is about building one, sending people to the right
+screen, staying under its limits, and passing them on to the full app.
+Baseline: iOS 26 and Swift 6.3; lower floors are noted where they apply.
+
+Deeper material:
+
+- `references/routing-and-experiences.md`: URL handling in SwiftUI and UIKit,
+  the three kinds of App Store Connect experience, every launch source, Smart
+  App Banners, and testing locally.
+- `references/data-handoff-notifications-location.md`: shared containers,
+  keychain direction, Sign in with Apple, the 8-hour notification window, and
+  proving a physical visit.
+- `references/size-capabilities-and-promotion.md`: an outline for feasibility
+  answers, the size tiers, Background Assets, `SKOverlay`, and what the
+  platform switches off.
+
+## Setting up the target
+
+Add the clip through File > New > Target > App Clip, inside the project that
+already holds the full app. Xcode creates the target, gives the full app an
+"Embed App Clip" build phase, and fills in the entitlements that link the two.
+
+The clip's bundle identifier must extend the parent's: `org.example.Tickets`
+pairs with `org.example.Tickets.Clip`.
+
+When archiving, signing or App Store Connect validation fails, look at the raw
+keys rather than Xcode's display names:
+
+| Holder | Raw entitlement |
+|---|---|
+| Clip | `com.apple.developer.on-demand-install-capable` |
+| Clip | `com.apple.developer.parent-application-identifiers` |
+| Full app | `com.apple.developer.associated-appclip-app-identifiers` |
+
+Share logic through Swift packages or source files that both targets compile,
+and fence clip-only code with `#if APPCLIP`. Frameworks that only the full app
+uses stay out of the clip's link phase.
+
+## Routing an invocation
+
+Launches arrive as an `NSUserActivity` whose type is
+`NSUserActivityTypeBrowsingWeb`; its `webpageURL` identifies what to show.
+Keep that parsing in shared code. After installation the full app takes the
+clip's place, and the very same links then open the full app.
+
+| UI stack | Where the URL shows up |
+|---|---|
+| SwiftUI | `.onContinueUserActivity(NSUserActivityTypeBrowsingWeb)` |
+| UIKit, first launch | `connectionOptions.userActivities`, read in `scene(_:willConnectTo:options:)` |
+| UIKit, already running | the activity passed to `scene(_:continue:)` |
+
+The callback `scene(_:willContinueUserActivityWithType:)` is merely a heads-up that an
+activity is on its way; it has no URL, so nothing should route from it.
+
+```swift
+import SwiftUI
+
+@main
+struct TicketsClip: App {
+    @State private var router = VisitRouter()
+
+    var body: some Scene {
+        WindowGroup {
+            VisitScreen(router: router)
+                .onContinueUserActivity(NSUserActivityTypeBrowsingWeb) { launch in
+                    if let link = launch.webpageURL {
+                        router.open(link)
+                    }
+                }
+        }
+    }
+}
 ```
 
-Display names in Xcode differ from raw entitlement keys; use raw keys when debugging signing output or archived entitlements.
-
-### Treating UIKit continuation notification as URL handling
-
-`scene(_:willContinueUserActivityWithType:)` does not include the `NSUserActivity`. Handle the URL in `scene(_:willConnectTo:options:)` for cold launch and `scene(_:continue:)` for activity continuation.
-
-### Not testing invocation URLs locally
-
-A direct Xcode launch can skip the invocation path and hide routing bugs. Use the `_XCAppClipURL` scheme environment variable or register a Local Experience in Settings → Developer → Local Experiences.
-
-### Not handling the full app replacing the App Clip
-
-Share invocation routing with the full app. After install, all future invocations go to the full app.
-
-### Storing secrets in App Group storage
-
-Use App Groups for non-secret handoff state only. Use keychain or server-side verification for credentials.
-
-### Designing a marketing-only or web-view-heavy App Clip
-
-App Clips should let people complete a focused task or full demo without installing the app. Avoid marketing-only clips, ad-heavy flows, splash screens, launch-blocking downloads, repeated install prompts, and web-view-heavy experiences that would work better as a website.
-
-### Missing associated domains configuration
-
-Add `appclips:example.com` to Associated Domains on both the full app and App Clip targets, and host `/.well-known/apple-app-site-association` with the App Clip app identifier for custom URL invocations and advanced experiences.
-
-## Review Checklist
-
-- [ ] App Clip target bundle ID is prefixed by the full app's bundle ID.
-- [ ] App Clip target has `com.apple.developer.on-demand-install-capable`.
-- [ ] App Clip target has `com.apple.developer.parent-application-identifiers`.
-- [ ] Full app target has `com.apple.developer.associated-appclip-app-identifiers`.
-- [ ] Shared code uses Swift packages or compilation conditions (`APPCLIP`).
-- [ ] SwiftUI uses `.onContinueUserActivity(NSUserActivityTypeBrowsingWeb)` for invocation routing.
-- [ ] UIKit cold launch checks `connectionOptions.userActivities` and continuation handles `scene(_:continue:)`.
-- [ ] Full app handles every invocation URL the App Clip supports.
-- [ ] App Thinning Size Report confirms the binary is within the limit for deployment target and invocation support; size reviews name the 10 MB, 15 MB, and current 100 MB tiers when size is at issue.
-- [ ] Associated Domains entitlement includes `appclips:yourdomain.com` on both full app and App Clip targets when using custom URLs.
-- [ ] AASA file is hosted at `/.well-known/apple-app-site-association` when using custom URLs.
-- [ ] Default App Clip experience is configured in App Store Connect.
-- [ ] Production App Clip Codes, Maps, or per-location cards use advanced experiences; demo App Clip Codes use the short demo link.
-- [ ] Live Activities, when mentioned, are limited to an App Clip-only widget extension with only Live Activities and the raw `com.apple.developer.on-demand-install-capable` entitlement.
-- [ ] Shared App Group storage contains only non-secret data the full app needs, never credentials or payment secrets.
-- [ ] Keychain handoff states the one-way rule: the full app can read App Clip-created items on iOS 15.4+ with correct association entitlements, but the App Clip cannot read full-app keychain items.
-- [ ] Sign in with Apple migration verifies credential state in the full app.
-- [ ] `SKOverlay` / `appStoreOverlay` appears after task completion, never as a gate.
-- [ ] `NSAppClipRequestLocationConfirmation` is set only in the App Clip target if using location confirmation.
-- [ ] Ephemeral notification code checks for `.ephemeral` authorization before scheduling because the card permission can be disabled.
-- [ ] Ephemeral notification routing handles relaunch without an invocation URL.
-- [ ] HIG review rejects marketing-only, ad-heavy, web-view-heavy, install-gated, or launch-blocking App Clip designs.
-- [ ] Unsupported runtime features are named explicitly, including durable persistent local state and background/persistent assumptions, not just unavailable frameworks.
-- [ ] No reliance on background processing, restricted frameworks, custom URL schemes, in-app purchases, or persistent local storage.
-- [ ] Sibling handoff is boundary-only, with no ActivityKit, StoreKit, BackgroundTasks, CloudKit, Swift package, App Group/keychain recipe, location-confirmation API symbol, `SKOverlay`, or framework-snippet implementation detail in App Clip feasibility answers.
-- [ ] Tested with Local Experiences and `_XCAppClipURL`.
-
-## References
-
-- [Routing and experiences](references/routing-and-experiences.md)
-- [Data handoff, notifications, and location](references/data-handoff-notifications-location.md)
-- [Size, capabilities, and promotion](references/size-capabilities-and-promotion.md)
-- [App Clips framework](https://sosumi.ai/documentation/appclip/)
-- [Creating an App Clip with Xcode](https://sosumi.ai/documentation/appclip/creating-an-app-clip-with-xcode/)
-- [Configuring App Clip experiences](https://sosumi.ai/documentation/appclip/configuring-the-launch-experience-of-your-app-clip/)
-- [Responding to invocations](https://sosumi.ai/documentation/appclip/responding-to-invocations/)
-- [Choosing the right functionality](https://sosumi.ai/documentation/appclip/choosing-the-right-functionality-for-your-app-clip/)
-- [Confirming a person's physical location](https://sosumi.ai/documentation/appclip/confirming-a-person-s-physical-location/)
-- [Sharing data between App Clip and full app](https://sosumi.ai/documentation/appclip/sharing-data-between-your-app-clip-and-your-full-app/)
-- [Enabling notifications in App Clips](https://sosumi.ai/documentation/appclip/enabling-notifications-in-app-clips/)
-- [Supporting invocations from your website and the Messages app](https://sosumi.ai/documentation/appclip/supporting-invocations-from-your-website-and-the-messages-app/)
-- [Offering Live Activities with your App Clip](https://sosumi.ai/documentation/appclip/offering-live-activities-with-your-app-clip/)
-- [Recommending your app to App Clip users](https://sosumi.ai/documentation/appclip/recommending-your-app-to-app-clip-users/)
-- [APActivationPayload](https://sosumi.ai/documentation/appclip/apactivationpayload/)
-- [SKOverlay.AppClipConfiguration](https://sosumi.ai/documentation/storekit/skoverlay/appclipconfiguration/)
-- [NSUserActivityTypeBrowsingWeb](https://sosumi.ai/documentation/foundation/nsuseractivitytypebrowsingweb/)
-- [Creating App Clip Codes](https://sosumi.ai/documentation/appclip/creating-app-clip-codes/)
-- [Distributing your App Clip](https://sosumi.ai/documentation/appclip/distributing-your-app-clip/)
-- [App Clips HIG](https://sosumi.ai/design/human-interface-guidelines/app-clips/)
+`VisitRouter` and `VisitScreen` are shared types; see the routing reference.
+
+App Store Connect side:
+
+- Every clip needs a default experience.
+- Advanced experiences exist for Maps placement, tying the clip to a place,
+  App Clip Codes used in production, a card per location, and precise routing
+  at a venue.
+- Demo App Clip Codes are generated from the short variant of the demo link.
+- For your own domain, list `appclips:example.com` under Associated Domains in
+  the clip and in the full app, and publish an `apple-app-site-association`
+  file there that names the clip.
+- A Safari banner's meta tag names the app through `app-id`, the clip through
+  `app-clip-bundle-id`, and asks for the card with `app-clip-display=card`.
+  `app-argument` is defined for full-app banners, so clip routing cannot
+  depend on it.
+
+## Size and capability decisions
+
+Size:
+
+- Read the number from the App Thinning Size Report; never estimate.
+- In a feasibility answer, say which limit applies and why, based on the
+  oldest supported iOS version, the launch sources, and whether the setting
+  offers dependable internet.
+- 100 MB is available only on iOS 17 and later, for clips launched digitally
+  where a good connection is expected. Physical launch sources or iOS 16
+  support shrink the budget, and iOS 15 support shrinks it further.
+- Through the demo link, a clip may still use 100 MB and accept NFC and QR
+  tests; demo codes must be generated from the short demo link.
+- These figures have moved before. Re-read the current App Clip and App Store
+  Connect pages before a size ruling holds up a release.
+
+Downloads:
+
+- Background Assets are for material that can land after launch while the
+  task proceeds, and the clip may not flag any of it as essential.
+- Big bundled media, ML models, product catalogs, and anything required before
+  the task can begin are a bad match. State plainly that a mandatory download
+  in front of the task is not acceptable, and check both how large downloads
+  are and whether one blocks the task. Serve that content from a server or
+  stream, fetch it after the task, or leave it to the full app.
+
+Promotion: show `SKOverlay.AppClipConfiguration` (UIKit) or `appStoreOverlay`
+(SwiftUI) once the task has succeeded. It must never stand between the person
+and the task.
+
+Platform boundaries:
+
+- CloudKit: from iOS 16 the clip may read the public database using the
+  `CloudKit-Anonymous` service. Writing to it, document storage in iCloud,
+  the iCloud key-value store, and private or shared containers are all
+  unavailable.
+- Live Activities: supported from iOS 16 (ActivityKit's own APIs start at
+  16.1) through a widget extension embedded only in the clip. That extension
+  holds Live Activities and nothing else, and it must carry the App Clip
+  Extension capability; in a review, name its raw key,
+  `com.apple.developer.on-demand-install-capable`.
+- In any feasibility answer, list as unavailable: App Intents,
+  `SKAdNetwork`, custom URL schemes, `App Tracking Transparency`, Background
+  Tasks, in-app purchase, background URL sessions, state that must persist
+  locally, and anything that assumes background or long-lived execution.
+
+Depth for product reviews:
+
+- Send these elsewhere without implementation detail: Live Activity code
+  (ActivityKit, WidgetKit), purchasing and monetization (StoreKit), background
+  work (BackgroundTasks), CloudKit schema or sync past public reads, long-lived
+  credentials and long-term state (the full app).
+- A PM feasibility answer covers capability fit, which size tier and why,
+  invocation limits, and who owns each handoff. Confirming location, promoting
+  the install, App Group or keychain handoff and Live Activities are explained
+  as concepts.
+- Such an answer leaves out package structure, type names like
+  `APActivationPayload`, `CLCircularRegion` and
+  `SKOverlay.AppClipConfiguration`, App Group or keychain code, and other
+  API-level material, unless someone asks for the implementation.
+
+## Data, notifications, location
+
+- **Shared container.** App Groups carry only data that may be read by anyone
+  holding the group entitlement, because every such target can read and write
+  both the container and the shared defaults suite. It is a convenience, not a
+  security boundary: no passwords, refresh tokens, payment data or other
+  secrets.
+- **Keychain.** Items the clip wrote become readable by the full app on iOS
+  15.4 and later, as long as the linking entitlements are in place (on the
+  full app's side that means `com.apple.developer.associated-appclip-app-identifiers`). The reverse
+  never works: the clip cannot see the full app's items.
+- **Sign in with Apple.** Keep the credential's `user` identifier
+  (`ASAuthorizationAppleIDCredential.user`) in the shared container; the full
+  app asks `ASAuthorizationAppleIDProvider.getCredentialState(forUserID:)` and
+  proceeds only on `.authorized`.
+- **Ephemeral notifications.** Put `NSAppClipRequestEphemeralUserNotification`
+  inside the `NSAppClip` dictionary of the clip's Info.plist. The permission
+  covers a window of up to 8 hours following every launch, and the person may
+  disable it from the card, so read the settings and require `.ephemeral`
+  before scheduling anything.
+- **Relaunch from a notification.** The clip comes back with no invocation
+  URL. To steer to the correct experience, give remote pushes a
+  `target-content-id` and local ones a
+  `UNNotificationContent.targetContentIdentifier` whose value is a URL
+  matching an advanced experience, never a made-up identifier.
+- **Location confirmation.** Read `NSUserActivity.appClipActivationPayload`,
+  build a `CLCircularRegion`, and pass it to
+  `APActivationPayload.confirmAcquired(in:)`; the region's radius is 500 m or less. The flag
+  `NSAppClipRequestLocationConfirmation` belongs in the clip target's
+  `NSAppClip` dictionary, never the full app's. The check verifies that an
+  eligible physical launch happened at the place; it does not grant ongoing
+  location access.
+
+## Common mistakes
+
+1. **Exceeding the budget.** A clip launched from physical codes that still
+   runs on iOS 16 has a fraction of the room of an iOS 17+, link-only clip.
+   Measure again after every substantial change.
+2. **Confusing entitlements.** Xcode's labels hide the raw keys. Two belong on
+   the clip (install-capable, parent identifiers) and one on the full app
+   (associated clip identifiers); see the table above.
+3. **Routing from the advance notice.**
+   `scene(_:willContinueUserActivityWithType:)` has no activity to read.
+4. **Never testing a real invocation.** Running the scheme straight from
+   Xcode may bypass the launch path and mask routing faults. Use the
+   `_XCAppClipURL` scheme variable or a Local Experience (Settings > Developer
+   > Local Experiences).
+5. **Ignoring the replacement.** Once installed, the full app answers the
+   clip's links; give it the same router.
+6. **Secrets in the group container.** Credentials go to the keychain or are
+   verified on the server.
+7. **A clip that only advertises.** People should complete a focused task, or
+   try a complete demo, without installing. Skip ads, splash screens,
+   downloads that hold up launch, repeated install nags, and flows that are
+   really a website in a web view.
+8. **No associated domains.** Custom URLs and advanced experiences fail
+   without an `appclips:` entry in each target and a published association
+   file (path `/.well-known/apple-app-site-association`) naming the clip.
+
+## Review checklist
+
+- [ ] Clip bundle ID extends the parent app's bundle ID
+- [ ] Both clip entitlements and the full app's association entitlement present (table above)
+- [ ] Shared logic lives in packages or behind `APPCLIP`
+- [ ] SwiftUI uses `.onContinueUserActivity(NSUserActivityTypeBrowsingWeb)`
+- [ ] UIKit covers cold launch via `connectionOptions.userActivities` and warm launch via `scene(_:continue:)`
+- [ ] Every clip URL also opens correctly in the full app
+- [ ] Size confirmed in the thinning report for the chosen OS floor and launch sources; the answer names all three tiers (10, 15 and 100 MB)
+- [ ] `appclips:` domain entry in both targets when custom URLs are used
+- [ ] Association file served from `/.well-known/apple-app-site-association`
+- [ ] Default experience set up in App Store Connect
+- [ ] Advanced experiences behind production codes, Maps and per-place cards; demo codes built from the short demo link
+- [ ] Any Live Activity lives in a clip-only widget extension containing only Live Activities, with the install-capable key
+- [ ] Group container holds nothing secret
+- [ ] Keychain direction spelled out (full app reads clip items from iOS 15.4 with the entitlements; never the other way)
+- [ ] Full app checks the Apple ID credential state before trusting a clip sign-in
+- [ ] Install overlay shown only after success, never as a gate
+- [ ] Location-confirmation flag only in the clip's Info.plist
+- [ ] Notification code requires `.ephemeral` before scheduling
+- [ ] Notification relaunches without a URL are routed correctly
+- [ ] Design review turns down marketing-only, ad-filled, web-view, install-first and launch-blocking flows
+- [ ] Unavailable runtime features listed, including local persistence and background or long-running assumptions
+- [ ] Nothing relies on background execution, restricted frameworks, custom schemes, IAP or durable local storage
+- [ ] Feasibility answers keep sibling work at the boundary (no code for ActivityKit, StoreKit, BackgroundTasks, CloudKit, packages, App Groups, keychain, location checks or overlays)
+- [ ] Verified with a Local Experience and with `_XCAppClipURL`
+
+## Apple documentation
+
+All under https://developer.apple.com/documentation/appclip unless noted:
+
+- `creating-an-app-clip-with-xcode` (target setup)
+- `configuring-the-launch-experience-of-your-app-clip` (experiences)
+- `responding-to-invocations` (URL handling)
+- `choosing-the-right-functionality-for-your-app-clip` (limits and frameworks)
+- `confirming-a-person-s-physical-location` (activation payload)
+- `sharing-data-between-your-app-clip-and-your-full-app` (containers, keychain)
+- `enabling-notifications-in-app-clips` (8-hour window)
+- `supporting-invocations-from-your-website-and-the-messages-app` (banners)
+- `offering-live-activities-with-your-app-clip` (widget extension)
+- `recommending-your-app-to-app-clip-users` (overlay)
+- `apactivationpayload` (API)
+- `creating-app-clip-codes` (codes)
+- `distributing-your-app-clip` (release)
+- https://developer.apple.com/documentation/storekit/skoverlay/appclipconfiguration
+- https://developer.apple.com/documentation/foundation/nsuseractivitytypebrowsingweb
+- HIG: https://developer.apple.com/design/human-interface-guidelines/app-clips

package/pipeline/skills/shared/external/app-clips/evals/evals.json

@@ -3,47 +3,47 @@
   "evals": [
     {
       "id": 0,
-      "name": "invocation-entitlements-review",
-      "prompt": "Review this App Clip setup plan before my team implements it. The full app bundle ID is com.example.cafe and the App Clip is com.example.cafe.Clip. We want a default App Clip experience plus per-store advanced experiences, SwiftUI for the App Clip UI, UIKit scene delegates in an older shared module, and we need the full app to handle the same QR/NFC URLs after install. What target setup, entitlements, associated domains, and invocation routing should we require?",
-      "expected_output": "A review that gives App Clip-specific setup and routing guidance without drifting into unrelated full-app implementation detail.",
+      "name": "entitlements-and-routing",
+      "prompt": "Check our App Clip setup before we build it. Parent app: com.example.bakery; clip: com.example.bakery.Clip. Experiences: the default one, plus an advanced one for each shop. Clip screens are SwiftUI; the URL routing sits in a UIKit module shared with the parent app. Which entitlements, domain settings and URL entry points do we need?",
+      "expected_output": "Lists the three raw entitlements and which target holds each, confirms the bundle ID prefix rule, shows SwiftUI and UIKit routing entry points correctly, requires the full app to handle every clip URL, and covers associated domains on both targets plus the association file.",
       "files": [],
       "expectations": [
-        "Names the App Clip target entitlement `com.apple.developer.on-demand-install-capable` and the parent/full-app association entitlements `com.apple.developer.parent-application-identifiers` and `com.apple.developer.associated-appclip-app-identifiers`.",
-        "Explains that the App Clip bundle ID must be prefixed by the full app bundle ID.",
-        "Recommends SwiftUI `.onContinueUserActivity(NSUserActivityTypeBrowsingWeb)` for App Clip URL handling.",
-        "Distinguishes UIKit cold launch via `scene(_:willConnectTo:options:)` connection options from URL handling in `scene(_:continue:)`, and does not treat `scene(_:willContinueUserActivityWithType:)` as the handler that provides the URL.",
-        "States that the full app must handle every App Clip invocation URL after installation.",
-        "Mentions `appclips:` associated domains on both full app and App Clip targets plus AASA hosting for custom URLs or advanced experiences."
+        "Assigns two raw keys to the clip (on-demand-install-capable and parent-application-identifiers, with their com.apple.developer. prefix) and associated-appclip-app-identifiers to the parent app",
+        "Says the clip identifier has to begin with the parent's identifier, which com.example.bakery.Clip does",
+        "Names .onContinueUserActivity(NSUserActivityTypeBrowsingWeb) as the SwiftUI hook",
+        "For the UIKit module, takes the cold-launch URL from connectionOptions.userActivities and the warm-launch URL from scene(_:continue:), and explains that the willContinueUserActivityWithType callback carries no URL",
+        "Requires the parent app to open every clip link, since it takes the clip's place once installed",
+        "Adds appclips: to Associated Domains in both targets and hosts the association file on the domain with the clip listed"
       ]
     },
     {
       "id": 1,
-      "name": "data-notifications-location",
-      "prompt": "We're designing a parking-meter App Clip. It should remember a pending session when the user installs the full app, use Sign in with Apple if available, remind the user by notification shortly after launch, and confirm they're physically near the meter without asking for continuous location. What should we put in the App Clip skill-level implementation checklist?",
-      "expected_output": "A checklist that covers secure handoff, Sign in with Apple verification, ephemeral notifications, and App Clip location confirmation with correct plist/API boundaries.",
+      "name": "handoff-notify-locate",
+      "prompt": "We are building a parking-meter App Clip. People pay at a meter by tapping an NFC tag, we want to remind them before the meter runs out, sign-in is via Sign in with Apple, and when they install the full app their account and active session should carry over. We also want to be sure they are really at the meter. How should this work?",
+      "expected_output": "Uses App Groups only for non-secret data, migrates Sign in with Apple via the stored user ID and a credential-state check, explains the one-way keychain rule, configures ephemeral notifications correctly, handles relaunch without a URL, and uses location confirmation rather than continuous tracking.",
       "files": [],
       "expectations": [
-        "Recommends App Groups/shared container or shared UserDefaults only for non-secret handoff data, and explicitly says not to store passwords, refresh tokens, or credential secrets there.",
-        "Explains Sign in with Apple handoff using the shared user identifier plus full-app `ASAuthorizationAppleIDProvider.getCredentialState(forUserID:)` verification for `.authorized`.",
-        "States that full-app keychain access to App Clip-created items is available only with the right association entitlements on iOS 15.4+ and that the App Clip cannot read full-app keychain items.",
-        "Names `NSAppClipRequestEphemeralUserNotification` under the App Clip target's `NSAppClip` Info.plist dictionary, notes the up-to-8-hour ephemeral authorization window, and checks for `.ephemeral` authorization before scheduling.",
-        "Explains that notification relaunch does not include the original invocation URL and should use APNs `target-content-id` or `UNNotificationContent.targetContentIdentifier` for multi-experience routing.",
-        "Names `NSAppClipRequestLocationConfirmation` under the App Clip target's `NSAppClip` Info.plist dictionary and uses `APActivationPayload`/`appClipActivationPayload` location confirmation rather than continuous location tracking."
+        "Keeps only non-sensitive values in the App Group and rules out credentials or secrets there in so many words",
+        "Saves the Apple ID user identifier for the parent app, which calls getCredentialState(forUserID:) and proceeds only when the result is .authorized",
+        "Explains the keychain is one-directional: the parent app reads items the clip wrote (iOS 15.4 and later, with the linking entitlements), never the reverse",
+        "Configures NSAppClipRequestEphemeralUserNotification in the clip's NSAppClip dictionary, notes the permission lasts at most 8 hours from each launch, and tests for .ephemeral status first",
+        "Handles relaunches from a notification, which carry no URL, using target-content-id for pushes or targetContentIdentifier for local notifications",
+        "Verifies presence at the meter with NSAppClipRequestLocationConfirmation plus the activation payload (appClipActivationPayload, APActivationPayload) rather than tracking location continuously"
       ]
     },
     {
       "id": 2,
-      "name": "size-capability-boundary",
-      "prompt": "A product manager wants an App Clip for venue check-in that includes Live Activities, CloudKit, App Intents, in-app purchases, BackgroundTasks, big bundled media, and maybe a demo link. Write a concise feasibility review that says what belongs in the App Clip, what belongs in sibling/full-app work, and what size/invocation constraints matter.",
-      "expected_output": "A feasibility review that applies App Clip size and capability limits while preserving sibling-skill boundaries.",
+      "name": "feasibility-boundaries",
+      "prompt": "PM question about an event check-in App Clip: people scan a QR code on a poster, view the day's schedule and check in. We'd like a Live Activity for the event and some cloud-hosted data; a few people also want in-app upgrade purchases and background refresh. Can this work? Please stay non-technical.",
+      "expected_output": "A boundary-level feasibility answer: size tier by iOS version and invocation type, measurement and download warnings, CloudKit read-only scope, Live Activities via a clip-only extension, the excluded capabilities named, and sibling work routed elsewhere without implementation detail.",
       "files": [],
       "expectations": [
-        "States the current App Clip size limits by iOS generation and distinguishes the larger iOS 17+ reliable-internet/digital-only limit from physical invocation and demo-link constraints.",
-        "Recommends measuring with the App Thinning Size Report and warns against large bundled media or large pre-task downloads.",
-        "Says CloudKit is limited to public database reads with `CloudKit-Anonymous` on iOS 16+ for App Clips, with no public writes, iCloud Documents, key-value storage, private containers, or shared containers.",
-        "Explains that App Clip Live Activities require an App Clip-only widget extension that can include only Live Activities and needs the App Clip Extension capability / `com.apple.developer.on-demand-install-capable`.",
-        "Identifies App Intents, BackgroundTasks, in-app purchases, SKAdNetwork, App Tracking Transparency, custom URL schemes, and persistent/background assumptions as not App Clip runtime features.",
-        "Routes detailed ActivityKit, WidgetKit, BackgroundTasks, StoreKit purchase, CloudKit schema, and full-app implementation work to sibling/full-app skills instead of expanding App Clip guidance into implementation-level Swift package, App Group/keychain, location-confirmation API symbol, SKOverlay, or framework API details."
+        "Walks through the size tiers by iOS version and explains that a QR launch counts as physical, so the 100 MB tier (iOS 17+, digital launches only) does not apply unless the demo link is used",
+        "Asks for a thinning-report measurement and cautions against bundling heavy media or requiring downloads before check-in",
+        "Keeps CloudKit to reading the public database (iOS 16+, CloudKit-Anonymous) and rules out writes, document or key-value iCloud storage, and private or shared containers",
+        "Permits a Live Activity only via a clip-owned widget extension that holds nothing else and has the App Clip Extension capability, naming the on-demand-install-capable key",
+        "Lists as unavailable: in-app purchases, Background Tasks, App Intents, custom URL schemes, SKAdNetwork, App Tracking Transparency, and any persistent or background behavior",
+        "Hands ActivityKit, WidgetKit, StoreKit, BackgroundTasks, CloudKit and full-app work to their owners with no API names or code"
       ]
     }
   ]