@mmerterden/multi-agent-pipeline 20.36.0 → 20.37.1

package/pipeline/skills/shared/external/alarmkit/references/alarmkit-code.md

@@ -0,0 +1,257 @@
+# AlarmKit code
+
+<!-- toc -->
+- [Authorization](#authorization)
+- [Countdown timers](#countdown-timers)
+- [Live Activity integration](#live-activity-integration)
+<!-- /toc -->
+
+Code for authorization, scheduling, countdown timers, presentations, metadata and the Live Activity widget. SKILL.md keeps the rules, lifecycle and review guidance.
+
+## Authorization
+
+The user must grant access. The app may ask up front, or AlarmKit will prompt
+the first time something is scheduled. If neither prompt ends in approval, no
+alarm is scheduled and nothing will ring.
+
+```swift
+import AlarmKit
+
+func ensureAlarmAccess() async -> Bool {
+    let center = AlarmManager.shared
+    switch center.authorizationState {
+    case .authorized:
+        return true
+    case .denied:
+        return false
+    case .notDetermined:
+        let answer = try? await center.requestAuthorization()
+        return answer == .authorized
+    @unknown default:
+        return false
+    }
+}
+
+func watchAlarmAccess(onChange: @escaping (Bool) -> Void) async {
+    for await state in AlarmManager.shared.authorizationUpdates {
+        switch state {
+        case .authorized: onChange(true)
+        case .denied, .notDetermined: onChange(false)
+        @unknown default: onChange(false)
+        }
+    }
+}
+```
+
+`AlarmManager.AuthorizationState` has three cases: `.notDetermined`,
+`.denied` and `.authorized`. `authorizationState` is a synchronous read;
+`authorizationUpdates` is an async sequence of changes.
+
+### Configuring and scheduling
+
+```swift
+import AlarmKit
+import SwiftUI
+
+struct ShiftInfo: AlarmMetadata {
+    var shiftName: String
+}
+
+@available(iOS 26.1, *)
+func scheduleShiftAlarm() async throws -> Alarm {
+    let dawn = Alarm.Schedule.Relative.Time(hour: 5, minute: 30)
+    let alert = AlarmPresentation.Alert(
+        title: "Early shift",
+        secondaryButton: AlarmButton(text: "Later", textColor: .white, systemImageName: "zzz"),
+        secondaryButtonBehavior: .countdown
+    )
+    let attributes = AlarmAttributes(
+        presentation: AlarmPresentation(alert: alert),
+        metadata: ShiftInfo(shiftName: "Warehouse A"),
+        tintColor: .teal
+    )
+    let config = AlarmManager.AlarmConfiguration(
+        countdownDuration: Alarm.CountdownDuration(preAlert: nil, postAlert: 9 * 60),
+        schedule: .relative(.init(time: dawn, repeats: .never)),
+        attributes: attributes,
+        sound: .default
+    )
+    let center = AlarmManager.shared
+    return try await center.schedule(id: UUID(), configuration: config)
+}
+```
+
+Here `postAlert` is what makes the secondary button a snooze: pressing it
+starts a nine-minute countdown and then rings again.
+
+`stopIntent` and `secondaryIntent` both default to `nil`, and that is usually
+right:
+
+- Leave `stopIntent` out when the system Stop is all you need. Pass one only
+  when stopping must also clean up app state or trigger some side effect.
+- Leave `secondaryIntent` out for a plain snooze or repeat, which is
+  `secondaryButtonBehavior: .countdown` plus `CountdownDuration.postAlert`.
+  Pass one only with `.custom` behavior or when the app must do its own work.
+
+## Countdown timers
+
+A timer rings once a duration has passed and always shows its countdown.
+
+```swift
+import AlarmKit
+import SwiftUI
+
+struct BrewInfo: AlarmMetadata {
+    var blend: String
+}
+
+@available(iOS 26.1, *)
+func startSteepTimer() async throws {
+    let presentation = AlarmPresentation(
+        alert: .init(title: "Tea is ready"),
+        countdown: .init(title: "Steeping"),
+        paused: .init(title: "Steeping paused",
+                      resumeButton: AlarmButton(text: "Resume", textColor: .white, systemImageName: "play.fill"))
+    )
+    let attributes = AlarmAttributes(presentation: presentation,
+                                     metadata: BrewInfo(blend: "Sencha"),
+                                     tintColor: .green)
+    let threeMinutes = AlarmManager.AlarmConfiguration.timer(duration: 180, attributes: attributes, sound: .default)
+    let center = AlarmManager.shared
+    _ = try await center.schedule(id: UUID(), configuration: threeMinutes)
+}
+```
+
+### AlarmPresentation
+
+`AlarmPresentation` describes the text and buttons per state. The system draws
+the alerting UI from it; the widget extension may draw countdown and paused.
+
+| Type | State | Required |
+|---|---|---|
+| `AlarmPresentation.Alert(title:secondaryButton:secondaryButtonBehavior:)` | alerting | yes |
+| `AlarmPresentation.Countdown(title:pauseButton:)` | counting down | no |
+| `AlarmPresentation.Paused(title:resumeButton:)` | paused | no |
+
+Combine them with `AlarmPresentation(alert:countdown:paused:)`:
+
+```swift
+import AlarmKit
+import SwiftUI
+
+@available(iOS 26.1, *)
+func workoutPresentation() -> AlarmPresentation {
+    let again = AlarmButton(text: "Again", textColor: .white, systemImageName: "repeat")
+    let hold = AlarmButton(text: "Hold", textColor: .orange, systemImageName: "pause.fill")
+    let go = AlarmButton(text: "Go", textColor: .orange, systemImageName: "play.fill")
+    return AlarmPresentation(
+        alert: .init(title: "Rest over", secondaryButton: again, secondaryButtonBehavior: .countdown),
+        countdown: .init(title: "Resting", pauseButton: hold),
+        paused: .init(title: "Rest on hold", resumeButton: go)
+    )
+}
+```
+
+### Metadata
+
+```swift
+import AlarmKit
+import SwiftUI
+
+struct PlantInfo: AlarmMetadata { var plantName: String; var litres: Double }
+struct NoAlarmData: AlarmMetadata {}
+
+@available(iOS 26.1, *)
+func plantAttributes() -> (AlarmAttributes<PlantInfo>, AlarmAttributes<NoAlarmData>) {
+    let look = AlarmPresentation(alert: .init(title: "Water the fern"))
+    let withData = AlarmAttributes(presentation: look, metadata: PlantInfo(plantName: "Fern", litres: 0.5), tintColor: .mint)
+    let plain = AlarmAttributes<NoAlarmData>(presentation: look, metadata: nil, tintColor: .mint)
+    return (withData, plain)
+}
+```
+
+When there is nothing to carry, declare an empty type that conforms to
+`AlarmMetadata` and pass `metadata: nil`.
+
+## Live Activity integration
+
+A ringing alarm is a Live Activity that the system renders on the Lock Screen,
+in the Dynamic Island, in StandBy and on a paired Apple Watch; the app has no
+say over that screen. Countdown and paused are different: the app supplies a widget
+extension whose `ActivityConfiguration` names the same
+`AlarmAttributes<Metadata>` type used at scheduling.
+
+- Plan on the extension whenever countdown presentation is used. The metadata
+  type must be compiled into both the app and the extension, and it should stay
+  small.
+- Leave the extension out and an alarm can vanish early or never ring. The
+  system only draws a fallback countdown in narrow cases, such as after a
+  restart before the first unlock.
+
+AlarmKit is responsible for: permission to schedule alarms, `AlarmManager` scheduling and state,
+`AlarmAttributes`, `AlarmPresentation`, `AlarmPresentationState`, the sound,
+and the system Stop, Repeat and Open App actions. It is not a general surface
+for custom notification UI.
+
+When describing where alarms appear, name Lock Screen, Dynamic Island, StandBy
+and paired Apple Watch together. Smart Stack is not an AlarmKit surface.
+
+Hand-offs:
+
+- Widgets on the Home Screen or in Smart Stack, `WidgetFamily`, timelines,
+  `WidgetCenter` reloads: `widgetkit`.
+- Non-alarm Live Activities (`Activity.request`, `update`, `end`),
+  push-to-start and per-activity update tokens, and remote `content-state`
+  payloads: `live-activities`.
+- APNs, `UNUserNotificationCenter`, notification categories and actions,
+  custom notification UI: `push-notifications`, unless the code ends up
+  calling `AlarmManager`.
+
+Setup stays with what Apple documents: `NSAlarmKitUsageDescription` and
+`AlarmManager` authorization. Do not require extra keys or a
+`com.apple.developer.alarmkit` entitlement unless a current Apple source says so.
+
+```swift
+import ActivityKit
+import AlarmKit
+import SwiftUI
+import WidgetKit
+
+struct CoachInfo: AlarmMetadata {
+    var drill: String
+}
+
+struct CoachAlarmWidget: Widget {
+    var body: some WidgetConfiguration {
+        ActivityConfiguration(for: AlarmAttributes<CoachInfo>.self) { context in
+            Text(context.attributes.metadata?.drill ?? "Timer")
+                .padding()
+        } dynamicIsland: { context in
+            DynamicIsland {
+                DynamicIslandExpandedRegion(.center) {
+                    let heading = context.attributes.presentation.alert.title
+                    Text(heading)
+                }
+                DynamicIslandExpandedRegion(.bottom) {
+                    if case .countdown(let run) = context.state.mode {
+                        Text(timerInterval: Date.now...run.fireDate, countsDown: true)
+                    }
+                }
+            } compactLeading: {
+                Image(systemName: "alarm.fill")
+            } compactTrailing: {
+                Image(systemName: "alarm.fill")
+            } minimal: {
+                Image(systemName: "alarm.fill")
+            }
+        }
+    }
+}
+
+@main
+struct CoachWidgets: WidgetBundle {
+    var body: some Widget {
+        CoachAlarmWidget()
+    }
+}
+```

package/pipeline/skills/shared/external/android-architecture/SKILL.md

@@ -179,32 +179,9 @@ The data layer implements repository interfaces. It coordinates between remote
 
 ### Repository Implementation
 
-```kotlin
-class OrderRepositoryImpl @Inject constructor(
-    private val remoteDataSource: OrderRemoteDataSource,
-    private val localDataSource: OrderLocalDataSource,
-    private val orderMapper: OrderMapper,
-) : OrderRepository {
-
-    override fun getOrders(store: String, region: String): Flow<List<Order>> =
-        localDataSource.getOrders(store, region)
-            .map { entities -> entities.map(orderMapper::toDomain) }
-
-    override fun searchOrders(query: String, date: LocalDate): Flow<List<Order>> = flow {
-        val dtos = remoteDataSource.searchOrders(query, date.toString())
-        localDataSource.insertOrders(dtos.map(orderMapper::toEntity))
-        emitAll(
-            localDataSource.getOrders(query, query)
-                .map { entities -> entities.map(orderMapper::toDomain) }
-        )
-    }
+The implementation is injected, maps entities to domain models through the mapper on every read, exposes reads as `Flow`, and wraps suspend writes in `Result` with `runCatching`.
 
-    override suspend fun payOrder(orderId: String): Result<Payment> = runCatching {
-        val response = remoteDataSource.payOrder(orderId)
-        orderMapper.toPaymentDomain(response)
-    }
-}
-```
+Code: [Repository Implementation](references/code-examples.md#repository-implementation).
 
 ### Data Sources
 
@@ -394,39 +371,7 @@ depending on every `impl`. Full host injection and per-feature contribution:
 
 Mappers isolate layer boundaries. Each layer has its own model type.
 
-```kotlin
-class OrderMapper @Inject constructor() {
-
-    fun toDomain(entity: OrderEntity): Order = Order(
-        id = entity.id,
-        store = Location(entity.storeCode, entity.storeName),
-        region = Location(entity.regionCode, entity.regionName),
-        placedAt = Instant.parse(entity.placedAt),
-        deliveredAt = Instant.parse(entity.deliveredAt),
-        price = Price(entity.priceAmount, entity.priceCurrency),
-        status = OrderStatus.valueOf(entity.status),
-    )
-
-    fun toEntity(dto: OrderDto): OrderEntity = OrderEntity(
-        id = dto.id,
-        storeCode = dto.store.code,
-        storeName = dto.store.name,
-        regionCode = dto.region.code,
-        regionName = dto.region.name,
-        placedAt = dto.placedAt,
-        deliveredAt = dto.deliveredAt,
-        priceAmount = dto.price.amount,
-        priceCurrency = dto.price.currency,
-        status = dto.status,
-    )
-
-    fun toPaymentDomain(response: PaymentResponse): Payment = Payment(
-        id = response.paymentId,
-        confirmationCode = response.confirmationCode,
-        status = PaymentStatus.valueOf(response.status),
-    )
-}
-```
+Code: [Mapper Pattern](references/code-examples.md#mapper-pattern).
 
 ## Do's and Don'ts
 
@@ -487,3 +432,7 @@ class OrderMapper @Inject constructor() {
 - [ ] Feature and data internals are `internal`
 - [ ] Coroutine dispatchers are injectable via `DispatcherProvider`
 - [ ] No `GlobalScope` usage; all coroutines use structured concurrency
+
+## References
+
+- [Code examples](references/code-examples.md): open for the full code behind Repository Implementation, Mapper Pattern.

package/pipeline/skills/shared/external/android-architecture/references/code-examples.md

@@ -0,0 +1,68 @@
+# Android Architecture Code Examples
+
+Full code samples for the SKILL.md sections that link here. The rules and the decision guidance stay in SKILL.md; each heading below matches the SKILL.md section the code belongs to.
+
+## Repository Implementation
+
+```kotlin
+class OrderRepositoryImpl @Inject constructor(
+    private val remoteDataSource: OrderRemoteDataSource,
+    private val localDataSource: OrderLocalDataSource,
+    private val orderMapper: OrderMapper,
+) : OrderRepository {
+
+    override fun getOrders(store: String, region: String): Flow<List<Order>> =
+        localDataSource.getOrders(store, region)
+            .map { entities -> entities.map(orderMapper::toDomain) }
+
+    override fun searchOrders(query: String, date: LocalDate): Flow<List<Order>> = flow {
+        val dtos = remoteDataSource.searchOrders(query, date.toString())
+        localDataSource.insertOrders(dtos.map(orderMapper::toEntity))
+        emitAll(
+            localDataSource.getOrders(query, query)
+                .map { entities -> entities.map(orderMapper::toDomain) }
+        )
+    }
+
+    override suspend fun payOrder(orderId: String): Result<Payment> = runCatching {
+        val response = remoteDataSource.payOrder(orderId)
+        orderMapper.toPaymentDomain(response)
+    }
+}
+```
+
+## Mapper Pattern
+
+```kotlin
+class OrderMapper @Inject constructor() {
+
+    fun toDomain(entity: OrderEntity): Order = Order(
+        id = entity.id,
+        store = Location(entity.storeCode, entity.storeName),
+        region = Location(entity.regionCode, entity.regionName),
+        placedAt = Instant.parse(entity.placedAt),
+        deliveredAt = Instant.parse(entity.deliveredAt),
+        price = Price(entity.priceAmount, entity.priceCurrency),
+        status = OrderStatus.valueOf(entity.status),
+    )
+
+    fun toEntity(dto: OrderDto): OrderEntity = OrderEntity(
+        id = dto.id,
+        storeCode = dto.store.code,
+        storeName = dto.store.name,
+        regionCode = dto.region.code,
+        regionName = dto.region.name,
+        placedAt = dto.placedAt,
+        deliveredAt = dto.deliveredAt,
+        priceAmount = dto.price.amount,
+        priceCurrency = dto.price.currency,
+        status = dto.status,
+    )
+
+    fun toPaymentDomain(response: PaymentResponse): Payment = Payment(
+        id = response.paymentId,
+        confirmationCode = response.confirmationCode,
+        status = PaymentStatus.valueOf(response.status),
+    )
+}
+```

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

@@ -60,29 +60,7 @@ The system builds the intent with `init()`, fills in parameters, then calls
 `perform()`. A static `title` (a `LocalizedStringResource`) and a
 `parameterSummary` shape how Shortcuts shows it.
 
-```swift
-import AppIntents
-
-struct WaterPlantIntent: AppIntent {
-    static let title: LocalizedStringResource = "Water Plant"
-    static let description = IntentDescription("Logs a watering for one of your plants.")
-
-    @Parameter(title: "Plant")
-    var plant: PlantEntity
-
-    @Parameter(title: "Cups", default: 1)
-    var cups: Int
-
-    static var parameterSummary: some ParameterSummary {
-        Summary("Water \(\.$plant)") { \.$cups }
-    }
-
-    func perform() async throws -> some IntentResult & ProvidesDialog {
-        try await CareLog.shared.recordWatering(plantID: plant.id, cups: cups)
-        return .result(dialog: "Logged \(cups) cups for \(plant.name).")
-    }
-}
-```
+Code: [AppIntent](references/code-examples.md#appintent).
 
 Optional members:
 
@@ -330,28 +308,7 @@ Adopt `IndexedEntity` to make entities searchable. `indexingKey` ties a
 property to a `CSSearchableItemAttributeSet` key path: on `@Property` from
 iOS 18.4, on `@ComputedProperty` from iOS 26.
 
-```swift
-import CoreSpotlight
-
-struct CareGuideEntity: IndexedEntity {
-    static let defaultQuery = CareGuideQuery()
-    static let typeDisplayRepresentation: TypeDisplayRepresentation = "Care Guide"
-
-    let id: UUID
-
-    @Property(title: "Title", indexingKey: \.title)
-    var title: String
-
-    var steps: [String]
-
-    @ComputedProperty(indexingKey: \.contentDescription)
-    var overview: String { steps.prefix(2).joined(separator: " ") }
-
-    var displayRepresentation: DisplayRepresentation { DisplayRepresentation(title: "\(title)") }
-}
-
-// try await CSSearchableIndex(name: "guides").indexAppEntities(guides)
-```
+Code: [Spotlight and IndexedEntity (iOS 18+)](references/code-examples.md#spotlight-and-indexedentity-ios-18).
 
 - IDs must be stable: a UUID or slug, never a database row ID that can be
   reused.
@@ -445,3 +402,4 @@ The [advanced guide](references/appintents-advanced.md) covers every
 `@Parameter` form, `EntityPropertyQuery`, assistant schemas, Focus filters,
 SiriKit migration, errors and dialogs, confirmation, authentication, URL
 representations and Spotlight indexing.
+- [Code examples](references/code-examples.md): open for the full code behind AppIntent, Spotlight and IndexedEntity (iOS 18+).

package/pipeline/skills/shared/external/app-intents/references/code-examples.md

@@ -0,0 +1,54 @@
+# App Intents Code Examples
+
+Full code samples for the SKILL.md sections that link here. The rules and the decision guidance stay in SKILL.md; each heading below matches the SKILL.md section the code belongs to.
+
+## AppIntent
+
+```swift
+import AppIntents
+
+struct WaterPlantIntent: AppIntent {
+    static let title: LocalizedStringResource = "Water Plant"
+    static let description = IntentDescription("Logs a watering for one of your plants.")
+
+    @Parameter(title: "Plant")
+    var plant: PlantEntity
+
+    @Parameter(title: "Cups", default: 1)
+    var cups: Int
+
+    static var parameterSummary: some ParameterSummary {
+        Summary("Water \(\.$plant)") { \.$cups }
+    }
+
+    func perform() async throws -> some IntentResult & ProvidesDialog {
+        try await CareLog.shared.recordWatering(plantID: plant.id, cups: cups)
+        return .result(dialog: "Logged \(cups) cups for \(plant.name).")
+    }
+}
+```
+
+## Spotlight and IndexedEntity (iOS 18+)
+
+```swift
+import CoreSpotlight
+
+struct CareGuideEntity: IndexedEntity {
+    static let defaultQuery = CareGuideQuery()
+    static let typeDisplayRepresentation: TypeDisplayRepresentation = "Care Guide"
+
+    let id: UUID
+
+    @Property(title: "Title", indexingKey: \.title)
+    var title: String
+
+    var steps: [String]
+
+    @ComputedProperty(indexingKey: \.contentDescription)
+    var overview: String { steps.prefix(2).joined(separator: " ") }
+
+    var displayRepresentation: DisplayRepresentation { DisplayRepresentation(title: "\(title)") }
+}
+
+// try await CSSearchableIndex(name: "guides").indexAppEntities(guides)
+```

package/pipeline/skills/shared/external/app-store-optimization/SKILL.md

@@ -206,41 +206,7 @@ Keep the brief as text beside the frames so a new locale or size reuses it.
 
 ## Asking for reviews in the app
 
-Use the SwiftUI environment value `RequestReviewAction` or, from UIKit,
-`AppStore.requestReview(in:)`. The full StoreKit surface is covered in
-`storekit`.
-
-```swift
-import StoreKit
-import SwiftUI
-
-struct TripSummaryView: View {
-    @Environment(\.requestReview) private var requestReview
-    let completedTrips: Int
-
-    var body: some View {
-        TripSummaryContent()
-            .onAppear {
-                if completedTrips == 5 { requestReview() }
-            }
-    }
-}
-```
-
-- The system shows the prompt at most three times in 365 days per device for
-  someone who has not rated the app.
-- Calling the API is a request; StoreKit decides whether anything appears.
-- Development builds always show it; TestFlight builds never do.
-- Good moments: a meaningful task just finished, a milestone or streak, a
-  visible success, several active sessions.
-- Bad moments: the very first launch, the onboarding flow, any error or crash,
-  a purchase that failed, or directly after a button tap.
-- Do not put a "Do you like this app?" dialog in front of the system prompt.
-  Apple discourages intercepting it and may reject apps that do.
-
-For a permanent "Write a review" row in settings, open
-`https://apps.apple.com/app/id{APP_ID}?action=write-review`. It goes straight
-to the review sheet and does not count against the three-per-year limit.
+Use `RequestReviewAction` (or `AppStore.requestReview(in:)`) after a meaningful success, never on first launch, onboarding, errors or a failed purchase, and never behind a pre-prompt; the system caps it at three prompts a year. Code, timing rules and the write-review link: [Reviews, events and localized metadata](references/engagement-and-localization.md).
 
 ## Custom Product Pages
 
@@ -267,24 +233,7 @@ URL format, channel mapping and maintenance are in the
 
 ## In-App Events
 
-Events are shown in search, on Today and in recommendations tailored to
-each user. They raise visibility while they run and can bring lapsed
-users back.
-
-- Badges (seven): Challenge, Competition, Live Event, Major Update, New
-  Season, Premiere, Special Event. Pick the one that matches what actually happens in
-  the app, and never create an event without real time-bound content.
-- Text limits in characters: 30 for the name, 50 for the short description,
-  120 for the long one.
-- Media: an event card image or video at 16:9 (1920 x 1080) and an event
-  details page image or video at 9:16 (1080 x 1920).
-- Time them with feature releases, seasonal moments and content drops.
-- Write the name and short description for someone scanning search results;
-  they appear on the event cards in Search and Today.
-- The card is shown on the product page as well, and a well-timed card lifts
-  tap-through.
-- Line events up so a new one starts as the previous one ends, keeping a card
-  in search at all times.
+Seven badges, only for real time-bound content; name 30, short description 50, long description 120 characters; 16:9 card and 9:16 details media; keep one event live at all times. Full rules: [Reviews, events and localized metadata](references/engagement-and-localization.md).
 
 ## Product Page Optimization
 
@@ -313,37 +262,11 @@ default product page.
 
 ## Ratings and reviews
 
-Star ratings and written reviews are visible on the product page and in
-search, and they move both ranking and conversion.
-
-- Earn more recent positive reviews: prompt after successes and answer
-  complaints constructively.
-- Answer critical reviews from App Store Connect. A calm, specific reply
-  improves how the app looks even when the rating does not change: acknowledge
-  the problem, say what is fixed or in progress, keep the tone neutral.
-- Read reviews as research into what users want, what frustrates them and the
-  words they use, then feed that into metadata and captions.
-- Submitting a new version offers the option of resetting the summary rating. Do it only
-  when the shown rating is far below current quality after major fixes. Keep a
-  good rating that reflects the app fairly, skip the reset for routine fixes, and after
-  a risky redesign wait until it has settled.
+Earn recent positive reviews, answer critical ones calmly and specifically, mine reviews for wording, and reset the summary rating only after major fixes. Details: [Reviews, events and localized metadata](references/engagement-and-localization.md).
 
 ## Localized Metadata Optimization
 
-A localized listing is a separate job from translating the app's screens.
-Keywords, descriptions and captions are researched and written per market.
-
-- Research keywords in each market. The term people use to find a photo editor
-  in Japanese is not a word-for-word translation of the English one.
-- Rewrite the description per locale, adapting opening lines, features, proof
-  and close to local expectations.
-- Localize every surface (description, keywords, previews, screenshots), and do
-  not count on literal translations or on one locale's keywords being indexed
-  elsewhere.
-- Caption screenshots in the market's language; native captions convert better
-  than English ones.
-- Localizing strings inside the app (String Catalogs, `FormatStyle`,
-  right-to-left layout) is covered by `ios-localization`.
+Research keywords and rewrite descriptions and captions per market instead of translating; in-app string localization belongs to `ios-localization`. Details: [Reviews, events and localized metadata](references/engagement-and-localization.md).
 
 ## Mistakes to catch
 
@@ -383,6 +306,7 @@ Keywords, descriptions and captions are researched and written per market.
 
 ## References
 
+- [Reviews, events and localized metadata](references/engagement-and-localization.md): review prompt timing and API, In-App Event badges and limits, replying to reviews and rating resets, and per-market metadata.
 - [Keyword research](references/keyword-research-methodology.md):
   what search indexes, the research process, scoring, slot allocation, seasonal
   rotation, before and after examples.