@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/tipkit/SKILL.md

@@ -1,42 +1,34 @@
 ---
 name: tipkit
-description: "Implement, review, or improve in-app tips and onboarding using Apple's TipKit framework. Use when adding feature discovery tooltips, onboarding flows, contextual tips, first-run experiences, coach marks, or working with Tip protocol, TipView, popoverTip, tip rules, tip events, or feature education UI."
+description: "TipKit in-app tips (iOS 17+): Tip protocol, TipView, popoverTip, rules, events, TipGroup, styles, CloudKit sync. Use when building or reviewing feature-discovery tooltips, onboarding flows, first-run experiences, coach marks, contextual tips or other feature-education UI."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
 # TipKit
 
-Add feature discovery tips, contextual hints, and onboarding coach marks to
-iOS 17+ apps using Apple's TipKit framework. TipKit manages display frequency,
-eligibility rules, and persistence so tips appear at the right time and
-disappear once the user has learned the feature.
+TipKit (iOS 17 and later) shows short hints that teach a feature at the
+moment it matters. The framework owns the hard parts: it decides when a tip
+is eligible, throttles how often tips appear, and remembers which tips a
+person has already learned so they stop appearing.
 
-## Contents
-
-- [Setup](#setup)
-- [Defining Tips](#defining-tips)
-- [Displaying Tips](#displaying-tips)
-- [Tip Rules](#tip-rules)
-- [Tip Actions](#tip-actions)
-- [Tip Groups](#tip-groups)
-- [Programmatic Control](#programmatic-control)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+Tips are for discovery and progressive disclosure. They can be dismissed and
+do not come back, so anything critical or safety related goes in an alert or
+an inline warning instead.
 
 ## Setup
 
-Call `Tips.configure()` once in `App.init`, before any views render. This
-initializes the tips datastore and begins rule evaluation. Calling it later
-risks a race where tip views attempt to display before the datastore is ready.
+Configure TipKit once, in the `App` initializer, before the first view is
+built. `Tips.configure` opens the tips datastore and starts evaluating rules;
+if it runs later (in `onAppear` or `.task`), tip views can render against a
+store that is not ready yet.
 
 ```swift
 import SwiftUI
 import TipKit
 
 @main
-struct MyApp: App {
+struct GardenJournalApp: App {
     init() {
         try? Tips.configure([
             .datastoreLocation(.applicationDefault)
@@ -44,99 +36,117 @@ struct MyApp: App {
     }
 
     var body: some Scene {
-        WindowGroup { ContentView() }
+        WindowGroup {
+            JournalHomeView()
+        }
     }
 }
 ```
 
-### DatastoreLocation Options
+### Where the datastore lives
 
-| Option | Use Case |
-|---|---|
-| `.applicationDefault` | Default location, app sandbox (most apps) |
-| `.groupContainer(identifier:)` | Share tips state across app and extensions |
-| `.url(_:)` | Custom file URL for full control over storage location |
+| Option | When to pick it |
+| --- | --- |
+| `.applicationDefault` | The app sandbox default. Correct for most apps. |
+| `.groupContainer(identifier:)` | Tip state shared between the app and its extensions. |
+| `.url(_:)` | A file URL you choose, when you need full control. |
 
-### CloudKit Sync
+### Syncing tip state with CloudKit
 
-Sync tip state across a user's devices so they do not see the same tip on
-every device. Add the CloudKit container option alongside the datastore
-location.
+When the app runs on several devices, sync tip state so a person who learned
+a feature on their iPhone is not taught it again on their iPad. Add a CloudKit
+container next to the datastore option (`cloudKitContainer` needs iOS 18):
 
 ```swift
 try? Tips.configure([
     .datastoreLocation(.applicationDefault),
-    .cloudKitContainer(.named("iCloud.com.example.app"))
+    .cloudKitContainer(.named("iCloud.com.example.gardenjournal"))
 ])
 ```
 
-## Defining Tips
+## Defining a tip
 
-Conform a struct to the `Tip` protocol. Provide a `title` at minimum.
-Add `message` for supporting detail and `image` for a leading icon. Keep
-titles short and action-oriented because the tip appears as a compact callout.
+A tip is a struct that conforms to `Tip`. Only `title` (a `Text`) is
+required. `message` (`Text?`) adds a line of context and `image` (`Image?`)
+adds a leading icon. The callout is small, so write the title as a short
+instruction.
 
 ```swift
-import TipKit
+struct PinPlantTip: Tip {
+    var title: Text {
+        Text("Pin a plant")
+    }
+
+    var message: Text? {
+        Text("Pinned plants stay at the top of your journal.")
+    }
 
-struct FavoriteTip: Tip {
-    var title: Text { Text("Pin Your Favorites") }
-    var message: Text? { Text("Tap the heart icon to save items for quick access.") }
-    var image: Image? { Image(systemName: "heart") }
+    var image: Image? {
+        Image(systemName: "pin")
+    }
 }
 ```
 
-**Properties**: `title` (required), `message` (optional detail), `image` (optional leading icon), `actions` (optional buttons), `rules` (optional eligibility conditions), `options` (display frequency, max count).
+Optional members:
+
+- `actions`: buttons shown inside the tip.
+- `rules`: conditions that must hold before the tip can appear.
+- `options`: per-tip display settings such as a maximum count.
 
-**Lifecycle**: Pending (rules unsatisfied) -> Eligible (all rules pass) -> Invalidated (dismissed, actioned, or programmatically removed). Once invalidated, a tip does not reappear unless the datastore is reset.
+A tip moves through three states. It is pending while its rules are not yet
+satisfied, eligible once every rule passes, and invalidated when it is
+dismissed, acted on, or invalidated in code. An invalidated tip stays hidden
+for good unless the datastore is reset.
 
-## Displaying Tips
+## Showing a tip
 
-### Inline Tips with TipView
+### Inline with TipView
 
-Embed a `TipView` directly in your layout. It renders as a rounded card that
-appears and disappears with animation. Use for tips within scrollable content.
+`TipView(tip)` places the tip in the layout as a rounded card that animates
+in and out. Use it for tips that sit among scrolling content.
 
 ```swift
-let favoriteTip = FavoriteTip()
-var body: some View {
-    VStack {
-        TipView(favoriteTip)
-        ItemListView()
+struct JournalHomeView: View {
+    let pinTip = PinPlantTip()
+
+    var body: some View {
+        VStack {
+            TipView(pinTip)
+            PlantListView()
+        }
     }
 }
 ```
 
-### Popover Tips with .popoverTip()
+### As a popover
 
-Attach a tip as a popover anchored to any view. The framework draws an arrow
-from the popover to the anchor. Use for tips pointing to a specific control.
+`.popoverTip(tip)` attaches the tip to a view and draws an arrow to it. Use it
+when the tip explains one particular control. Pass `arrowEdge:` to choose the
+arrow direction, or leave it out and let the system decide.
 
 ```swift
-Button { toggleFavorite() } label: { Image(systemName: "heart") }
-    .popoverTip(favoriteTip)
-
-// Control arrow direction (omit to let system choose)
-.popoverTip(favoriteTip, arrowEdge: .bottom)
+Button("Water", systemImage: "drop") {
+    logWatering()
+}
+.popoverTip(waterTip, arrowEdge: .bottom)
 ```
 
-### Custom TipViewStyle
+### A custom look with TipViewStyle
 
-Create a custom style to control tip appearance across the app. Conform
-to `TipViewStyle` and implement `makeBody(configuration:)`.
+To restyle tips across the app, adopt `TipViewStyle` and implement
+`makeBody(configuration:)`. The configuration carries `title` plus optional
+`image` and `message`.
 
 ```swift
-struct CustomTipStyle: TipViewStyle {
+struct LeafTipStyle: TipViewStyle {
     func makeBody(configuration: Configuration) -> some View {
-        HStack {
-            configuration.image?
-                .font(.title2)
-                .foregroundStyle(.tint)
-
-            VStack(alignment: .leading) {
+        HStack(alignment: .top, spacing: 10) {
+            configuration.image
+                .foregroundStyle(.green)
+            VStack(alignment: .leading, spacing: 4) {
                 configuration.title
                     .font(.headline)
-                configuration.message?
+                configuration.message
                     .font(.subheadline)
                     .foregroundStyle(.secondary)
             }
@@ -144,353 +154,228 @@ struct CustomTipStyle: TipViewStyle {
         .padding()
     }
 }
-
-// Apply globally or per view
-TipView(favoriteTip)
-    .tipViewStyle(CustomTipStyle())
 ```
 
-## Tip Rules
+Apply it with `.tipViewStyle(LeafTipStyle())` on a single tip view or on a
+container to cover everything below it.
+
+## Rules
 
-Rules control when a tip becomes eligible. All rules in the `rules` array
-must pass before the tip displays. TipKit supports two rule types:
-parameter-based and event-based.
+Rules decide eligibility. Every rule in `rules` has to pass before the tip is
+shown. There are two kinds.
 
-### Parameter-Based Rules
+### Parameter rules (app state)
 
-Use `@Parameter` to track app state. The tip becomes eligible when the
-parameter value satisfies the rule condition.
+Declare a `@Parameter` static on the tip, write a rule against its projected
+value, and assign the static when the state changes.
 
 ```swift
-struct FavoriteTip: Tip {
+struct SortPlantsTip: Tip {
     @Parameter
-    static var hasSeenList: Bool = false
+    static var hasOpenedList: Bool = false
 
-    var title: Text { Text("Pin Your Favorites") }
+    var title: Text { Text("Sort by watering date") }
 
     var rules: [Rule] {
-        #Rule(Self.$hasSeenList) { $0 == true }
+        #Rule(Self.$hasOpenedList) { $0 == true }
     }
 }
 
-// Set the parameter when the user reaches the list
-FavoriteTip.hasSeenList = true
+SortPlantsTip.hasOpenedList = true
 ```
 
-### Event-Based Rules
+### Event rules (user actions)
 
-Use `Tips.Event` to track user actions. Donate to the event each time the
-action occurs. The rule fires when the donation count or timing condition
-is met. This is ideal for tips that should appear after the user has
-performed an action several times without discovering a related feature.
+Declare a `Tips.Event`, donate to it every time the action happens, and write
+a rule on the donations. A rule can look at how many donations there are or
+when they happened.
 
 ```swift
-struct ShortcutTip: Tip {
-    static let appOpenedEvent = Tips.Event(id: "appOpened")
+struct QuickLogTip: Tip {
+    static let entryAdded = Tips.Event(id: "entryAdded")
 
-    var title: Text { Text("Try the Quick Action") }
+    var title: Text { Text("Log faster with a long press") }
 
     var rules: [Rule] {
-        #Rule(Self.appOpenedEvent) { $0.donations.count >= 3 }
+        #Rule(Self.entryAdded) { $0.donations.count >= 3 }
     }
 }
 
-// Donate each time the app opens
-ShortcutTip.appOpenedEvent.donate()
+Task { await QuickLogTip.entryAdded.donate() }
 ```
 
-### Combining Multiple Rules
+Event rules fit tips that should appear only after someone has repeated a
+task several times without finding the shortcut that would help.
 
-Place multiple rules in the array. All must pass (logical AND).
+### Several rules together
 
-```swift
-struct AdvancedTip: Tip {
-    @Parameter
-    static var isLoggedIn: Bool = false
-
-    static let featureUsedEvent = Tips.Event(id: "featureUsed")
-
-    var title: Text { Text("Unlock Advanced Mode") }
+List more than one `#Rule` and all of them must pass (logical AND):
 
-    var rules: [Rule] {
-        #Rule(Self.$isLoggedIn) { $0 == true }
-        #Rule(Self.featureUsedEvent) { $0.donations.count >= 5 }
-    }
+```swift
+var rules: [Rule] {
+    #Rule(Self.$isSignedIn) { $0 == true }
+    #Rule(Self.entryAdded) { $0.donations.count >= 5 }
 }
 ```
 
-### Display Frequency Options
+### How often tips appear
 
-Control how often tips appear using the `options` property.
+Per tip, `options` adjusts display behavior:
 
 ```swift
-struct DailyTip: Tip {
-    var title: Text { Text("Daily Reminder") }
-
-    var options: [TipOption] {
-        MaxDisplayCount(3)                   // Show at most 3 times total
-        IgnoresDisplayFrequency(true)        // Bypass global frequency limit
-    }
+var options: [TipOption] {
+    Tips.MaxDisplayCount(3)
+    Tips.IgnoresDisplayFrequency(true)
 }
 ```
 
-Global display frequency is set at configuration time:
+- `MaxDisplayCount(3)` stops the tip after three showings in total.
+- `IgnoresDisplayFrequency(true)` lets this tip bypass the global limit.
+
+The global limit is set at configuration time with
+`.displayFrequency(...)`, taking `.immediate`, `.hourly`, `.daily`, `.weekly`
+or `.monthly`. With `.daily`, the whole app shows at most one tip per day,
+except for tips that opt out with `IgnoresDisplayFrequency(true)`.
 
 ```swift
-try? Tips.configure([
-    .displayFrequency(.daily)  // .immediate, .hourly, .daily, .weekly, .monthly
-])
+try? Tips.configure([.displayFrequency(.daily)])
 ```
 
-With `.daily`, the system shows at most one tip per day across the entire
-app, unless a specific tip sets `IgnoresDisplayFrequency(true)`.
+## Actions
 
-## Tip Actions
-
-Add action buttons to a tip for direct interaction. Each action has an `id`
-and a label. Handle the action in the tip view's action handler.
+`actions` adds buttons to a tip. Each `Action(id:title:)` gets an identifier
+and a label. Handle taps in the closure passed to `TipView`, switching on the
+identifier.
 
 ```swift
-struct FeatureTip: Tip {
-    var title: Text { Text("Try the New Editor") }
-    var message: Text? { Text("We added a powerful new editing mode.") }
+struct ReminderTip: Tip {
+    var title: Text { Text("Never miss a watering") }
 
     var actions: [Action] {
-        Action(id: "open-editor", title: "Open Editor")
-        Action(id: "learn-more", title: "Learn More")
+        Action(id: "set-reminder", title: "Set Reminder")
+        Action(id: "show-guide", title: "How It Works")
     }
 }
-```
-
-Handle actions in the view:
 
-```swift
-TipView(featureTip) { action in
+TipView(reminderTip) { action in
     switch action.id {
-    case "open-editor":
-        navigateToEditor()
-        featureTip.invalidate(reason: .actionPerformed)
-    case "learn-more":
-        showHelpSheet = true
+    case "set-reminder":
+        reminderTip.invalidate(reason: .actionPerformed)
+        openReminderEditor()
+    case "show-guide":
+        isGuidePresented = true
     default:
         break
     }
 }
 ```
 
-## Tip Groups
+## Tip groups
 
-Use `TipGroup` to coordinate multiple tips within a single view.
-`TipGroup` ensures only one tip from the group displays at a time,
-preventing tip overload. Tips display in priority order.
+When one screen has several tips, put them in a `TipGroup` (iOS 18 and
+later) so only one is visible at a time. The `.ordered` priority shows them in
+the order listed. Render `currentTip` when it is not nil; invalidating it
+makes the next eligible tip current.
 
 ```swift
-struct OnboardingView: View {
-    let tipGroup = TipGroup(.ordered) {
-        WelcomeTip()
-        NavigationTip()
-        ProfileTip()
+struct PlantDetailView: View {
+    @State private var tips = TipGroup(.ordered) {
+        PinPlantTip()
+        SortPlantsTip()
+        QuickLogTip()
     }
 
     var body: some View {
         VStack {
-            if let currentTip = tipGroup.currentTip {
-                TipView(currentTip)
+            if let tip = tips.currentTip {
+                TipView(tip)
             }
-
-            Button("Next") {
-                tipGroup.currentTip?.invalidate(reason: .actionPerformed)
+            Button("Next hint") {
+                tips.currentTip?.invalidate(reason: .actionPerformed)
             }
         }
     }
 }
 ```
 
-### Priority Options
-
-| Initializer | Behavior |
-|---|---|
-| `.ordered` | Tips display in the order they are listed |
-
-When the current tip is invalidated, the next eligible tip in the group
-becomes `currentTip`.
-
-## Programmatic Control
-
-### Invalidating Tips
-
-Call `invalidate(reason:)` when the user performs the discovered action or
-when the tip is no longer relevant.
-
-```swift
-let tip = FavoriteTip()
-tip.invalidate(reason: .actionPerformed)
-```
-
-| Reason | When to Use |
-|---|---|
-| `.actionPerformed` | User performed the action the tip describes |
-| `.displayCountExceeded` | Tip hit its maximum display count |
-| `.tipClosed` | User explicitly dismissed the tip |
-
-### Testing Utilities
-
-TipKit provides static methods to control tip visibility during development
-and testing. Gate these behind `#if DEBUG` or `ProcessInfo` checks so they
-never run in production builds.
+## Controlling tips from code
 
-```swift
-#if DEBUG
-// Show all tips regardless of rules (useful during development)
-Tips.showAllTipsForTesting()
-
-// Show only specific tips
-Tips.showTipsForTesting([FavoriteTip.self, ShortcutTip.self])
-
-// Hide all tips (useful for UI tests that do not involve tips)
-Tips.hideAllTipsForTesting()
+### Invalidation
 
-// Reset the datastore (clears all tip state, invalidations, and events)
-try? Tips.resetDatastore()
-#endif
-```
-
-### Using ProcessInfo for Test Schemes
+Call `tip.invalidate(reason:)` once the person performs the action the tip
+describes, or when the tip no longer applies.
 
-```swift
-if ProcessInfo.processInfo.arguments.contains("--show-all-tips") {
-    Tips.showAllTipsForTesting()
-}
-```
+| Reason | Meaning |
+| --- | --- |
+| `.actionPerformed` | The person did what the tip suggests. |
+| `.displayCountExceeded` | The tip hit its maximum display count. |
+| `.tipClosed` | The person closed the tip. |
 
-Pass `--show-all-tips` as a launch argument in the Xcode scheme for
-development builds.
+### Testing helpers
 
-## Common Mistakes
+| Call | Effect |
+| --- | --- |
+| `Tips.showAllTipsForTesting()` | Shows every tip and ignores rules. |
+| `Tips.showTipsForTesting([PinPlantTip.self, QuickLogTip.self])` | Shows only the listed tip types. |
+| `Tips.hideAllTipsForTesting()` | Hides all tips, for UI tests that are not about tips. |
+| `try? Tips.resetDatastore()` | Clears tip state, invalidations and event donations. |
 
-### DON'T: Call Tips.configure() anywhere except App.init
+None of these may run in production. Put them behind `#if DEBUG` or a
+launch-argument check.
 
-Calling `Tips.configure()` in a view's `onAppear` or `task` modifier
-creates a race condition where tip views try to render before the
-datastore is ready, causing missing or flickering tips.
+### Launch arguments for development schemes
 
 ```swift
-// WRONG
-struct ContentView: View {
-    var body: some View {
-        Text("Hello")
-            .task { try? Tips.configure() }  // Too late, views already rendered
+init() {
+    #if DEBUG
+    if ProcessInfo.processInfo.arguments.contains("--show-all-tips") {
+        Tips.showAllTipsForTesting()
     }
-}
-
-// CORRECT
-@main struct MyApp: App {
-    init() { try? Tips.configure() }
-    var body: some Scene { WindowGroup { ContentView() } }
+    #endif
+    try? Tips.configure()
 }
 ```
 
-### DON'T: Show too many tips at once
-
-Displaying multiple tips simultaneously overwhelms users and dilutes the
-impact of each tip. Users learn to ignore them.
-
-```swift
-// WRONG: Three tips visible at the same time
-VStack {
-    TipView(tipA)
-    TipView(tipB)
-    TipView(tipC)
-}
-
-// CORRECT: Use TipGroup to sequence them
-let group = TipGroup(.ordered) { TipA(); TipB(); TipC() }
-if let currentTip = group.currentTip {
-    TipView(currentTip)
-}
-```
-
-### DON'T: Forget to invalidate tips after the user performs the action
-
-If a tip says "Tap the star to favorite" and the user taps the star but
-the tip remains, it erodes trust in the UI.
-
-```swift
-// WRONG: Tip stays visible after user acts
-Button("Favorite") { toggleFavorite() }
-    .popoverTip(favoriteTip)
-
-// CORRECT: Invalidate on action
-Button("Favorite") {
-    toggleFavorite()
-    favoriteTip.invalidate(reason: .actionPerformed)
-}
-.popoverTip(favoriteTip)
-```
-
-### DON'T: Leave testing tips enabled in production
-
-`Tips.showAllTipsForTesting()` bypasses all rules and frequency limits.
-Shipping this in production means every user sees every tip immediately.
-
-```swift
-// WRONG: Always active
-Tips.showAllTipsForTesting()
-
-// CORRECT: Gated behind DEBUG
-#if DEBUG
-Tips.showAllTipsForTesting()
-#endif
-```
-
-### DON'T: Make tip titles too long
-
-Long titles get truncated or wrap awkwardly in the compact tip callout.
-Put the key action in the title and supporting context in the message.
-
-```swift
-// WRONG
-var title: Text { Text("You can tap the heart button to save this item to your favorites list") }
-
-// CORRECT
-var title: Text { Text("Save to Favorites") }
-var message: Text? { Text("Tap the heart icon to keep items for quick access.") }
-```
-
-### DON'T: Use tips for critical information
-
-Users can dismiss tips at any time and they do not reappear. Never put
-essential instructions or safety information in a tip.
-
-```swift
-// WRONG: Critical info in a dismissible tip
-struct DataLossTip: Tip {
-    var title: Text { Text("Unsaved changes will be lost") }
-}
-
-// CORRECT: Use an alert or inline warning for critical information
-// Reserve tips for feature discovery and progressive disclosure
-```
-
-## Review Checklist
-
-- [ ] `Tips.configure()` called in `App.init`, before any views render
-- [ ] Each tip has a clear, concise title (action-oriented, under ~40 characters)
-- [ ] Tips invalidated when the user performs the discovered action
-- [ ] Rules set so tips appear at the right time (not immediately on first launch for all tips)
-- [ ] `TipGroup` used when multiple tips exist in one view
-- [ ] Testing utilities (`showAllTipsForTesting`, `resetDatastore`) gated behind `#if DEBUG`
-- [ ] CloudKit sync configured if the app supports multiple devices
-- [ ] Display frequency set appropriately (`.daily` or `.weekly` for most apps)
-- [ ] Tips used for feature discovery only, not for critical information
-- [ ] Custom `TipViewStyle` applied consistently if the default style does not match the app design
-- [ ] Tip actions handled and tip invalidated in the action handler
-- [ ] Event donations placed at the correct user action points
-- [ ] Ensure custom Tip types are Sendable; configure Tips on @MainActor
+Add `--show-all-tips` under Arguments Passed On Launch in a development
+scheme.
+
+## Pitfalls
+
+- Configuring in `onAppear` or `.task`. The race leaves tips missing or
+  flickering. Configure in `App.init`.
+- Several `TipView`s on screen at once. People feel swamped and start
+  ignoring tips. Sequence them with `TipGroup(.ordered)` and `currentTip`.
+- Leaving a tip up after the person already did the thing. A stale hint costs
+  trust. Call `invalidate(reason: .actionPerformed)` in the action of the
+  control that carries the `.popoverTip`.
+- Shipping `showAllTipsForTesting()` without a guard. It skips rules and
+  frequency limits, so every user sees every tip at once. Wrap it in
+  `#if DEBUG`.
+- Long titles. They truncate or wrap awkwardly. Keep the action in the title
+  and the explanation in the message.
+- Using a tip for critical or safety information. Tips can be dismissed and
+  never return. Use an alert or an inline warning.
+
+## Review checklist
+
+- [ ] `Tips.configure()` runs in `App.init`, before any view renders.
+- [ ] Titles are short, clear and action oriented, roughly 40 characters or
+      fewer.
+- [ ] Each tip is invalidated when its action is performed.
+- [ ] Rules keep tips from all firing on first launch.
+- [ ] Screens with more than one tip use `TipGroup`.
+- [ ] `showAllTipsForTesting` and `resetDatastore` sit behind `#if DEBUG`.
+- [ ] CloudKit sync is configured when the app runs on more than one device.
+- [ ] Display frequency suits the app; `.daily` or `.weekly` fits most.
+- [ ] Tips are used for feature discovery only, never for critical information.
+- [ ] A custom `TipViewStyle` is applied consistently where the default look
+      clashes with the design.
+- [ ] Tip actions are handled and the tip is invalidated in the handler.
+- [ ] Event donations happen at the right user-action points.
+- [ ] Tip types are `Sendable`, and TipKit is configured on the `@MainActor`.
 
 ## References
 
-- See [references/tipkit-patterns.md](references/tipkit-patterns.md) for complete implementation patterns
-  including custom styles, event-based rules, tip groups, testing strategies,
-  onboarding flows, and SwiftUI preview configuration.
-
+- [references/tipkit-patterns.md](references/tipkit-patterns.md): complete
+  tips with rules and events, placement, donation values, custom styles, tip
+  group sequencing, previews and tests, onboarding and a full app example.