@mmerterden/multi-agent-pipeline 20.1.0 → 20.2.0

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

@@ -122,10 +122,6 @@ types. Framework: `IntentPerson`, `IntentFile`. Custom: any `AppEntity` or
 ### Common initializer patterns
 
 ```swift
-// Basic
-@Parameter(title: "Name")
-var name: String
-
 // With default
 @Parameter(title: "Count", default: 5)
 var count: Int
@@ -137,17 +133,11 @@ var volume: Int
 // Options provider (dynamic list)
 @Parameter(title: "Category", optionsProvider: CategoryOptionsProvider())
 var category: Category
-
-// File with content types
-@Parameter(title: "Document", supportedContentTypes: [.pdf, .plainText])
-var document: IntentFile
-
-// Measurement with unit
-@Parameter(title: "Distance", defaultUnit: .miles, supportsNegativeNumbers: false)
-var distance: Measurement<UnitLength>
 ```
 
-See [references/appintents-advanced.md](references/appintents-advanced.md) for all initializer variants.
+Options providers, files, measurements, resolvers, disambiguation dialogs, and
+input-connection behavior follow the same shape. See
+[references/appintents-advanced.md](references/appintents-advanced.md) for all initializer variants.
 
 ## AppEntity
 
@@ -195,52 +185,19 @@ struct SoupEntityQuery: EntityQuery {
 
 ### 2. EntityStringQuery (free-text search)
 
-```swift
-struct SoupStringQuery: EntityStringQuery {
-    func entities(matching string: String) async throws -> [SoupEntity] {
-        SoupStore.shared.search(string).map { SoupEntity(from: $0) }
-    }
-    func entities(for identifiers: [String]) async throws -> [SoupEntity] {
-        SoupStore.shared.soups.filter { identifiers.contains($0.id) }.map { SoupEntity(from: $0) }
-    }
-}
-```
+Add `entities(matching string:)` alongside ID resolution for free-text search.
 
 ### 3. EnumerableEntityQuery (finite set)
 
-```swift
-struct AllSoupsQuery: EnumerableEntityQuery {
-    func allEntities() async throws -> [SoupEntity] {
-        SoupStore.shared.allSoups.map { SoupEntity(from: $0) }
-    }
-    func entities(for identifiers: [String]) async throws -> [SoupEntity] {
-        SoupStore.shared.soups.filter { identifiers.contains($0.id) }.map { SoupEntity(from: $0) }
-    }
-}
-```
+Implement `allEntities()` when the full set is small and enumerable.
 
 ### 4. UniqueAppEntityQuery (singleton, iOS 18+)
 
-Use for single-instance entities like app settings.
+Use for single-instance entities like app settings; implement `uniqueEntity()`.
 
-```swift
-struct AppSettingsEntity: UniqueAppEntity {
-    static let defaultQuery = AppSettingsQuery()
-    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Settings"
-    var displayRepresentation: DisplayRepresentation { "App Settings" }
-
-    var id: String { "app-settings" }
-}
-
-struct AppSettingsQuery: UniqueAppEntityQuery {
-    func uniqueEntity() async throws -> AppSettingsEntity {
-        AppSettingsEntity()
-    }
-}
-```
-
-See [references/appintents-advanced.md](references/appintents-advanced.md) for `EntityPropertyQuery` with
-filter/sort support.
+See [references/appintents-advanced.md](references/appintents-advanced.md) for full `EntityStringQuery`,
+`EnumerableEntityQuery`, and `UniqueAppEntityQuery` examples, plus `EntityPropertyQuery` with
+filter and sort support.
 
 ## AppEnum
 
@@ -377,36 +334,17 @@ struct LightControlConfig: ControlConfigurationIntent {
     static var title: LocalizedStringResource = "Light Control"
     @Parameter(title: "Light", default: .livingRoom) var light: LightEntity
 }
-
-struct ToggleLightIntent: AppIntent {
-    static var title: LocalizedStringResource = "Toggle Light"
-    static var authenticationPolicy: IntentAuthenticationPolicy = .requiresAuthentication
-
-    @Parameter(title: "Light") var light: LightEntity
-
-    func perform() async throws -> some IntentResult {
-        try await requestConfirmation(
-            actionName: .toggle,
-            dialog: "Toggle \(light.name)?"
-        )
-        try await LightService.shared.toggle(light.id)
-        return .result()
-    }
-}
-
-struct LightControl: ControlWidget {
-    var body: some ControlWidgetConfiguration {
-        AppIntentControlConfiguration(kind: "LightControl", intent: LightControlConfig.self) { config in
-            ControlWidgetToggle(config.light.name, isOn: config.light.isOn, action: ToggleLightIntent(light: config.light))
-        }
-    }
-}
 ```
 
+See [references/appintents-advanced.md](references/appintents-advanced.md) ("Control Center Widget
+Implementation") for the full `ControlWidget` + action-intent wiring with
+confirmation and authentication.
+
 ## Spotlight and IndexedEntity (iOS 18+)
 
 Conform to `IndexedEntity` for Spotlight search. On iOS 26+, use `indexingKey`
-for structured metadata:
+to map a property to a `CSSearchableItemAttributeSet` key path for structured
+metadata:
 
 ```swift
 struct RecipeEntity: IndexedEntity {
@@ -421,116 +359,43 @@ struct RecipeEntity: IndexedEntity {
     var displayRepresentation: DisplayRepresentation {
         DisplayRepresentation(title: "\(name)")
     }
-
-    var attributeSet: CSSearchableItemAttributeSet {
-        let attrs = defaultAttributeSet
-        attrs.keywords = ["recipe"]
-        return attrs
-    }
-}
-
-struct RecipeQuery: EntityQuery {
-    func entities(for identifiers: [RecipeEntity.ID]) async throws -> [RecipeEntity] {
-        identifiers.compactMap { id in
-            RecipeStore.shared.recipe(id: id).map(RecipeEntity.init)
-        }
-    }
-}
-
-struct OpenRecipeIntent: OpenIntent {
-    static var title: LocalizedStringResource = "Open Recipe"
-    @Parameter(title: "Recipe") var target: RecipeEntity
 }
 ```
 
 `IndexedEntity` describes metadata; still index instances in a named Spotlight
-index, e.g. `CSSearchableIndex(name: "...").indexAppEntities(entities)`.
-If you customize `attributeSet`, start from `defaultAttributeSet`; returning a
-fresh attribute set replaces display representation and property-derived
-metadata. Prefer `indexingKey` for metadata already exposed on the entity.
-Update and delete changed records in that same named index:
-
-```swift
-let recipeIndex = CSSearchableIndex(name: "Recipes")
-try await recipeIndex.indexAppEntities(changedRecipes)
-try await recipeIndex.deleteAppEntities(
-    identifiedBy: deletedRecipeIDs,
-    ofType: RecipeEntity.self
-)
-```
+index, e.g. `CSSearchableIndex(name: "...").indexAppEntities(entities)`. Provide
+an `OpenIntent` for the type so results open the right content. If you customize
+`attributeSet`, start from `defaultAttributeSet`; returning a fresh attribute set
+replaces display representation and property-derived metadata. Prefer
+`indexingKey` for metadata already exposed on the entity.
 
-For large syncs, use `beginBatch()`, `endBatch(withClientState:)`, and
-`fetchLastClientState()` so indexing can resume after a crash or jetsam.
+See [references/appintents-advanced.md](references/appintents-advanced.md) for the full entity plus query,
+the available `@Property` / `@ComputedProperty` indexing keys, updating and
+deleting indexed entities, batch indexing with client state for crash recovery,
+and direct Core Spotlight usage.
 
 ## iOS 26 Additions
 
 ### SnippetIntent
 
-Display interactive snippets in system UI:
-
-```swift
-struct OrderStatusSnippet: SnippetIntent {
-    static var title: LocalizedStringResource = "Order Status"
-    func perform() async throws -> some IntentResult & ShowsSnippetView {
-        let status = await OrderTracker.currentStatus()
-        return .result(view: OrderStatusSnippetView(status: status))
-    }
-}
-
-struct CheckOrderStatusIntent: AppIntent {
-    static var title: LocalizedStringResource = "Check Order Status"
-    func perform() async throws -> some IntentResult & ShowsSnippetIntent {
-        .result(snippetIntent: OrderStatusSnippet())
-    }
-}
-```
-
-The system may call `perform()` multiple times, including after snippet button
-or toggle actions; keep `SnippetIntent.perform()` side-effect-free and do
-mutations in the calling action intent or a separate button/toggle action. A
-snippet-only intent is not discoverable in Shortcuts or Spotlight unless
-`isDiscoverable` is `true`.
+Display interactive snippets in system UI. The system may call `perform()`
+multiple times, including after snippet button or toggle actions; keep
+`SnippetIntent.perform()` side-effect-free and do mutations in the calling action
+intent or a separate button/toggle action. A snippet-only intent is not
+discoverable in Shortcuts or Spotlight unless `isDiscoverable` is `true`. See
+[references/appintents-advanced.md](references/appintents-advanced.md) ("SnippetIntent Implementation")
+for the `ShowsSnippetView` / `ShowsSnippetIntent` example.
 
 ### IntentValueQuery (Visual Intelligence)
 
-```swift
-@available(iOS 26, *)
-@UnionValue
-enum ShoppingVisualResult {
-    case product(ProductEntity)
-    case store(StoreEntity)
-}
-
-@available(iOS 26, *)
-struct ShoppingVisualQuery: IntentValueQuery {
-    func values(for input: SemanticContentDescriptor) async throws -> [ShoppingVisualResult] {
-        try Task.checkCancellation()
-        async let productMatches = ProductStore.shared.matches(
-            labels: input.labels,
-            pixelBuffer: input.pixelBuffer,
-            limit: 5
-        )
-        async let storeMatches = StoreStore.shared.matches(
-            labels: input.labels,
-            pixelBuffer: input.pixelBuffer,
-            limit: 3
-        )
-        let ranked = await rank(productMatches, storeMatches)
-        return Array(ranked.prefix(8))
-    }
-}
-```
-
-Only one `IntentValueQuery` can take `SemanticContentDescriptor`; use
-`@UnionValue` when one query must return multiple app entity types. Treat
-`labels` as high-level English descriptors, not exhaustive synonyms or app
-taxonomy; combine them with `pixelBuffer` when available. Return small, ranked,
-cancellation-friendly results, and provide an `OpenIntent`, URL representation,
-or in-app search handoff for details and more results. Do not implement camera
-capture, Vision `VN*` requests, barcode classification, or Spotlight indexing
-inside the App Intents query; call an existing bounded app search or image-match
-service instead, with explicit result caps and timeouts when work may exceed a
-system UI budget.
+Return app entities for a Visual Intelligence `SemanticContentDescriptor`. Only
+one `IntentValueQuery` can take `SemanticContentDescriptor`; use `@UnionValue`
+when one query must return multiple app entity types. Return small, ranked,
+cancellation-friendly results and provide an opening path (`OpenIntent`, URL, or
+in-app search). Do not run camera capture, Vision `VN*` requests, or Spotlight
+indexing inside the query; call a bounded app search or image-match service
+instead. See [references/appintents-advanced.md](references/appintents-advanced.md) ("Visual Intelligence
+IntentValueQuery") for the full `@UnionValue` + query example and guidance.
 
 ## Common Mistakes
 

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

@@ -8,7 +8,11 @@ URL-representable types, and Spotlight indexing.
 ## Contents
 
 - [`@Parameter Initializer Variants`](#parameter-initializer-variants)
+- [EntityQuery Variants (Full Examples)](#entityquery-variants-full-examples)
 - [EntityPropertyQuery (Filter and Sort)](#entitypropertyquery-filter-and-sort)
+- [Control Center Widget Implementation](#control-center-widget-implementation)
+- [SnippetIntent Implementation (iOS 26+)](#snippetintent-implementation-ios-26)
+- [Visual Intelligence IntentValueQuery (iOS 26+)](#visual-intelligence-intentvaluequery-ios-26)
 - [Assistant Schemas (iOS 18+)](#assistant-schemas-ios-18)
 - [Focus Filter Intents](#focus-filter-intents)
 - [SiriKit Migration (CustomIntentMigratedAppIntent)](#sirikit-migration-customintentmigratedappintent)
@@ -184,6 +188,57 @@ func perform() async throws -> some IntentResult {
 }
 ```
 
+## EntityQuery Variants (Full Examples)
+
+Full implementations of the query variants summarized in the main skill. Variant
+1 (base `EntityQuery`) is shown in the skill; variants 2-4 are below.
+
+### EntityStringQuery (free-text search)
+
+```swift
+struct SoupStringQuery: EntityStringQuery {
+    func entities(matching string: String) async throws -> [SoupEntity] {
+        SoupStore.shared.search(string).map { SoupEntity(from: $0) }
+    }
+    func entities(for identifiers: [String]) async throws -> [SoupEntity] {
+        SoupStore.shared.soups.filter { identifiers.contains($0.id) }.map { SoupEntity(from: $0) }
+    }
+}
+```
+
+### EnumerableEntityQuery (finite set)
+
+```swift
+struct AllSoupsQuery: EnumerableEntityQuery {
+    func allEntities() async throws -> [SoupEntity] {
+        SoupStore.shared.allSoups.map { SoupEntity(from: $0) }
+    }
+    func entities(for identifiers: [String]) async throws -> [SoupEntity] {
+        SoupStore.shared.soups.filter { identifiers.contains($0.id) }.map { SoupEntity(from: $0) }
+    }
+}
+```
+
+### UniqueAppEntityQuery (singleton, iOS 18+)
+
+Use for single-instance entities like app settings.
+
+```swift
+struct AppSettingsEntity: UniqueAppEntity {
+    static let defaultQuery = AppSettingsQuery()
+    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Settings"
+    var displayRepresentation: DisplayRepresentation { "App Settings" }
+
+    var id: String { "app-settings" }
+}
+
+struct AppSettingsQuery: UniqueAppEntityQuery {
+    func uniqueEntity() async throws -> AppSettingsEntity {
+        AppSettingsEntity()
+    }
+}
+```
+
 ## EntityPropertyQuery (Filter and Sort)
 
 The most powerful query variant. Declare filterable properties and sortable
@@ -283,6 +338,114 @@ raw `EntityQueryComparator` objects.
 | `LessThanOrEqualToComparator` | Comparable properties |
 | `IsBetweenComparator` | Comparable properties supported by Shortcuts |
 
+## Control Center Widget Implementation
+
+Full `ControlConfigurationIntent` + `ControlWidget` wiring. The configuration
+intent is a parameter contract; state changes run from a separate action intent
+with an appropriate `authenticationPolicy` and `requestConfirmation`.
+
+```swift
+struct LightControlConfig: ControlConfigurationIntent {
+    static var title: LocalizedStringResource = "Light Control"
+    @Parameter(title: "Light", default: .livingRoom) var light: LightEntity
+}
+
+struct ToggleLightIntent: AppIntent {
+    static var title: LocalizedStringResource = "Toggle Light"
+    static var authenticationPolicy: IntentAuthenticationPolicy = .requiresAuthentication
+
+    @Parameter(title: "Light") var light: LightEntity
+
+    func perform() async throws -> some IntentResult {
+        try await requestConfirmation(
+            actionName: .toggle,
+            dialog: "Toggle \(light.name)?"
+        )
+        try await LightService.shared.toggle(light.id)
+        return .result()
+    }
+}
+
+struct LightControl: ControlWidget {
+    var body: some ControlWidgetConfiguration {
+        AppIntentControlConfiguration(kind: "LightControl", intent: LightControlConfig.self) { config in
+            ControlWidgetToggle(config.light.name, isOn: config.light.isOn, action: ToggleLightIntent(light: config.light))
+        }
+    }
+}
+```
+
+Parameters without defaults must be optional on a `ControlConfigurationIntent`.
+
+## SnippetIntent Implementation (iOS 26+)
+
+Display interactive snippets in system UI. The system may call `perform()`
+multiple times, including after snippet button or toggle actions, so keep
+`SnippetIntent.perform()` side-effect-free and do mutations in the calling
+action intent or a separate button/toggle action.
+
+```swift
+struct OrderStatusSnippet: SnippetIntent {
+    static var title: LocalizedStringResource = "Order Status"
+    func perform() async throws -> some IntentResult & ShowsSnippetView {
+        let status = await OrderTracker.currentStatus()
+        return .result(view: OrderStatusSnippetView(status: status))
+    }
+}
+
+struct CheckOrderStatusIntent: AppIntent {
+    static var title: LocalizedStringResource = "Check Order Status"
+    func perform() async throws -> some IntentResult & ShowsSnippetIntent {
+        .result(snippetIntent: OrderStatusSnippet())
+    }
+}
+```
+
+A snippet-only intent is not discoverable in Shortcuts or Spotlight unless
+`isDiscoverable` is `true`.
+
+## Visual Intelligence IntentValueQuery (iOS 26+)
+
+Only one `IntentValueQuery` can take `SemanticContentDescriptor`; use
+`@UnionValue` when one query must return multiple app entity types.
+
+```swift
+@available(iOS 26, *)
+@UnionValue
+enum ShoppingVisualResult {
+    case product(ProductEntity)
+    case store(StoreEntity)
+}
+
+@available(iOS 26, *)
+struct ShoppingVisualQuery: IntentValueQuery {
+    func values(for input: SemanticContentDescriptor) async throws -> [ShoppingVisualResult] {
+        try Task.checkCancellation()
+        async let productMatches = ProductStore.shared.matches(
+            labels: input.labels,
+            pixelBuffer: input.pixelBuffer,
+            limit: 5
+        )
+        async let storeMatches = StoreStore.shared.matches(
+            labels: input.labels,
+            pixelBuffer: input.pixelBuffer,
+            limit: 3
+        )
+        let ranked = await rank(productMatches, storeMatches)
+        return Array(ranked.prefix(8))
+    }
+}
+```
+
+Treat `labels` as high-level English descriptors, not exhaustive synonyms or app
+taxonomy; combine them with `pixelBuffer` when available. Return small, ranked,
+cancellation-friendly results, and provide an `OpenIntent`, URL representation,
+or in-app search handoff for details and more results. Do not implement camera
+capture, Vision `VN*` requests, barcode classification, or Spotlight indexing
+inside the App Intents query; call an existing bounded app search or image-match
+service instead, with explicit result caps and timeouts when work may exceed a
+system UI budget.
+
 ## Assistant Schemas (iOS 18+)
 
 Assistant schemas define domain-specific intents that Apple Intelligence
@@ -750,6 +913,21 @@ If your app already creates `CSSearchableItem` values, call
 `OpenIntent` for the entity type so Spotlight results can open the right app
 content.
 
+### Updating and Deleting Indexed Entities
+
+Update and delete changed records in the same named index. For large syncs, use
+`beginBatch()`, `endBatch(withClientState:)`, and `fetchLastClientState()` so
+indexing can resume after a crash or jetsam.
+
+```swift
+let recipeIndex = CSSearchableIndex(name: "Recipes")
+try await recipeIndex.indexAppEntities(changedRecipes)
+try await recipeIndex.deleteAppEntities(
+    identifiedBy: deletedRecipeIDs,
+    ofType: RecipeEntity.self
+)
+```
+
 ### Hide specific entities from Spotlight UI
 
 ```swift

package/pipeline/skills/shared/external/compose-components/SKILL.md

@@ -20,6 +20,9 @@ Material 3 (androidx.compose.material3).
 - [Typography Tokens](#typography-tokens)
 - [Shape Tokens](#shape-tokens)
 - [Color Token Mapping](#color-token-mapping)
+- [Two-Layer Design Tokens](#two-layer-design-tokens)
+- [Bridging Tokens to Material 3](#bridging-tokens-to-material-3)
+- [Component Catalog](#component-catalog)
 - [Modifier Ordering](#modifier-ordering)
 - [Do's and Don'ts](#dos-and-donts)
 - [Troubleshooting](#troubleshooting)
@@ -362,6 +365,46 @@ Card(shape = MaterialTheme.shapes.medium) { /* content */ }
 | `outline` | `colorScheme.outline` | Borders, dividers |
 | `outlineVariant` | `colorScheme.outlineVariant` | Subtle borders |
 
+## Two-Layer Design Tokens
+
+Scale token management with two layers. Layer 1 is a machine-generated raw-token
+source: one file, never hand-edited, the single source of truth for every
+primitive color, size, and font value. Layer 2 is a hand-authored semantic
+wrapper: `@Immutable` color and typography data classes that name each role and
+reference the raw tokens by name, never a literal hex or `sp`. Each semantic
+model exposes a `light()` and a `dark()` variant.
+
+The codegen pipeline that produces Layer 1 is a separate concern; see the
+`android-design-tokens-codegen` skill. This skill covers the consumption side:
+the semantic wrappers and how components read them.
+
+Full `RawTokens`, `@Immutable AppColors`/`AppTypography` with `light()`/`dark()`:
+[references/patterns.md#two-layer-design-tokens](references/patterns.md#two-layer-design-tokens).
+
+## Bridging Tokens to Material 3
+
+Bridge the semantic tokens to both worlds. Select an M3 `light`/`darkColorScheme`
+built from the tokens so stock Material components inherit the brand colors, and
+expose the richer token set through `CompositionLocalProvider`
+(`staticCompositionLocalOf`). Read the rich set through a `Theme.colors` /
+`Theme.typography` accessor marked `@ReadOnlyComposable`, so custom components
+reach tokens Material's `colorScheme` cannot express while stock components still
+theme correctly.
+
+Full `LocalAppColors`, `toMaterialColorScheme`, `AppTheme`, `Theme` accessor:
+[references/patterns.md#bridging-tokens-to-material-3](references/patterns.md#bridging-tokens-to-material-3).
+
+## Component Catalog
+
+Add a component-catalog module (for example Showkase) that renders every
+annotated composable and token in a browsable in-app gallery. Keep the annotation
+cheap and universal so it can sit on previews across every module, but gate the
+KSP processor behind a build flag so the browser codegen costs nothing on normal
+builds; build the catalog on demand with a `-P` flag.
+
+Full annotated preview, flag-gated `ksp` wiring, catalog entry point:
+[references/patterns.md#component-catalog](references/patterns.md#component-catalog).
+
 ## Modifier Ordering
 
 Modifier order matters. Modifiers are applied outside-in, so the order
@@ -439,3 +482,8 @@ Box(
 - [ ] Collapsible TopAppBar has `nestedScroll` modifier
 - [ ] Dynamic color has API 31 guard with static fallback
 - [ ] No mixing of M2 and M3 imports in the same screen
+- [ ] Raw tokens come from the generated single source; semantic wrappers reference them by name, no literal hex/`sp` in the wrapper
+- [ ] Semantic color/typography models are `@Immutable` with `light()` and `dark()` variants
+- [ ] Rich tokens exposed via `CompositionLocalProvider` and read through a `@ReadOnlyComposable` `Theme.colors`/`Theme.typography` accessor
+- [ ] M3 `light`/`darkColorScheme` derived from the tokens so stock Material components inherit brand colors
+- [ ] Catalog KSP processor gated behind a build flag, annotation kept universal