@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/tipkit/references/tipkit-patterns.md

@@ -1,122 +1,107 @@
-# TipKit Patterns Reference
+# TipKit Patterns
 
-Complete implementation patterns for TipKit including custom styles, event-based
-rules, tip groups, testing strategies, onboarding flows, and SwiftUI previews.
-All examples target iOS 17+ with Swift 6.3 conventions.
+Longer worked patterns for the `tipkit` skill. Every example targets iOS 17 or
+later and follows Swift 6.3 conventions; a heading says so when a newer
+release is needed.
 
 ## Contents
 
-- [Complete Tip with Rules and Events](#complete-tip-with-rules-and-events)
-- [TipView and popoverTip Placement](#tipview-and-popovertip-placement)
-- [Event-Based Rule with Donation Counting](#event-based-rule-with-donation-counting)
+- [A tip with both a parameter and an event rule](#a-tip-with-both-a-parameter-and-an-event-rule)
+- [Placing TipView and popoverTip](#placing-tipview-and-popovertip)
+- [Counting a manual action to suggest a shortcut](#counting-a-manual-action-to-suggest-a-shortcut)
+- [Events that carry a value](#events-that-carry-a-value)
 - [Custom TipViewStyle](#custom-tipviewstyle)
-- [TipGroup Sequencing](#tipgroup-sequencing)
-- [Testing Strategies](#testing-strategies)
-- [Tip with Action Buttons](#tip-with-action-buttons)
-- [Integration with Onboarding Flow](#integration-with-onboarding-flow)
-- [Full App Integration Example](#full-app-integration-example)
+- [Sequencing with TipGroup (iOS 18)](#sequencing-with-tipgroup-ios-18)
+- [Testing](#testing)
+- [Actions that open a feature](#actions-that-open-a-feature)
+- [Working alongside an onboarding flow](#working-alongside-an-onboarding-flow)
+- [A full app](#a-full-app)
 
-## Complete Tip with Rules and Events
+## A tip with both a parameter and an event rule
 
-A full-featured tip combining parameter-based and event-based rules. The tip
-appears only after the user has logged in and opened the app at least three
-times, ensuring they are familiar with the basics before seeing advanced
-feature discovery.
+This tip advertises bulk export. It waits until the person is signed in and
+has exported single recipes a few times, so the advanced feature is offered
+only to someone who already knows the basic one.
 
 ```swift
 import TipKit
 
-struct AdvancedSearchTip: Tip {
-    // Parameter rule: user must be logged in
+struct BulkExportTip: Tip {
     @Parameter
-    static var isLoggedIn: Bool = false
+    static var isSignedIn: Bool = false
 
-    // Event rule: user must have performed searches
-    static let searchPerformed = Tips.Event(id: "searchPerformed")
+    static let recipeExported = Tips.Event(id: "recipeExported")
 
-    var title: Text {
-        Text("Try Advanced Search")
-    }
+    var title: Text { Text("Export a whole cookbook") }
 
     var message: Text? {
-        Text("Filter results by date, category, and location for faster discovery.")
+        Text("Select several recipes and share them as one file.")
     }
 
-    var image: Image? {
-        Image(systemName: "magnifyingglass")
-    }
+    var image: Image? { Image(systemName: "tray.and.arrow.up") }
 
-    // All rules must pass before the tip becomes eligible
-    var rules: [Rule] {
-        #Rule(Self.$isLoggedIn) { $0 == true }
-        #Rule(Self.searchPerformed) { $0.donations.count >= 3 }
+    var options: [TipOption] {
+        Tips.MaxDisplayCount(5)
     }
 
-    var options: [TipOption] {
-        MaxDisplayCount(5)
+    var rules: [Rule] {
+        #Rule(Self.$isSignedIn) { $0 == true }
+        #Rule(Self.recipeExported) { $0.donations.count >= 3 }
     }
 }
 ```
 
-### Donating to Events
+### Where to donate
 
-Place event donations at the point where the user action occurs. Each
-donation increments the internal counter that rules evaluate against.
+Donate at the exact place the action completes, for example in the export
+callback. Every donation raises the count the rule checks.
 
 ```swift
-struct SearchView: View {
-    @State private var query = ""
-
-    var body: some View {
-        SearchBar(text: $query, onSubmit: {
-            performSearch(query)
-            // Donate each time the user searches
-            AdvancedSearchTip.searchPerformed.donate()
-        })
-    }
+func exportRecipe(_ recipe: Recipe) async throws {
+    try await exporter.write(recipe)
+    await BulkExportTip.recipeExported.donate()
 }
 ```
 
-### Setting Parameters
+### Where to set parameters
 
-Set parameter values when the relevant app state changes. Parameters persist
-across launches via the TipKit datastore.
+Set a parameter when the underlying state changes, such as in the sign-in
+success path. The value is stored in the TipKit datastore, so it survives
+relaunches.
 
 ```swift
-func handleLoginSuccess() {
-    AdvancedSearchTip.isLoggedIn = true
+func didFinishSignIn() {
+    BulkExportTip.isSignedIn = true
 }
 ```
 
-## TipView and popoverTip Placement
+## Placing TipView and popoverTip
 
-### Inline TipView in a List
+### A tip as a list row, the same tip as a toolbar popover
 
-Place a `TipView` as a list row for contextual inline discovery. The tip
-appears as part of the list content and animates away when dismissed or
-invalidated.
+An inline `TipView` can be a row of a `List`; it animates away once dismissed
+or invalidated. The toolbar button below also carries the tip as a popover and
+invalidates it when tapped.
 
 ```swift
-struct ItemListView: View {
-    let filterTip = FilterTip()
-    @State private var items: [Item] = []
+struct PantryListView: View {
+    let filterTip = PantryFilterTip()
+    @State private var isFilterSheetShown = false
 
     var body: some View {
         List {
-            TipView(filterTip)
-
-            ForEach(items) { item in
-                ItemRow(item: item)
+            Section {
+                TipView(filterTip)
+            }
+            ForEach(pantryItems) { item in
+                PantryRow(item: item)
             }
         }
-        .navigationTitle("Items")
         .toolbar {
             ToolbarItem(placement: .primaryAction) {
-                Button {
-                    showFilters()
+                Button("Filter", systemImage: "slider.horizontal.3") {
                     filterTip.invalidate(reason: .actionPerformed)
-                } label: {
-                    Image(systemName: "line.3.horizontal.decrease.circle")
+                    isFilterSheetShown = true
                 }
                 .popoverTip(filterTip, arrowEdge: .top)
             }
@@ -125,658 +110,535 @@ struct ItemListView: View {
 }
 ```
 
-### Popover on Navigation Bar Button
+### Pointing at a navigation bar button
 
-Attach a popover tip to a toolbar button. The popover arrow points to the
-button, drawing the user's attention to the exact control.
+A popover on a bar button aims its arrow at exactly that control.
 
 ```swift
-struct EditorView: View {
-    let undoTip = UndoShortcutTip()
-
-    var body: some View {
-        TextEditor(text: $text)
-            .toolbar {
-                ToolbarItem(placement: .primaryAction) {
-                    Button("Undo", systemImage: "arrow.uturn.backward") {
-                        undoLastAction()
-                        undoTip.invalidate(reason: .actionPerformed)
-                    }
-                    .popoverTip(undoTip, arrowEdge: .top)
-                }
-            }
-    }
+Button("Revert", systemImage: "arrow.uturn.backward") {
+    revertLastChange()
 }
+.popoverTip(revertTip, arrowEdge: .top)
 ```
 
-### Popover on Tab Bar Item
+### Introducing a new tab (iOS 18)
 
-Use `popoverTip` on a `Tab` label view inside a `TabView` to highlight a
-new tab.
+TipKit has no `popoverTip` for `Tab`: the modifier is declared on `View`, and a
+`Tab` is `TabContent`, so `.popoverTip` on it does not compile. Put the tip
+inside the new tab's content instead.
 
 ```swift
-struct MainTabView: View {
-    let newTabTip = NewFeatureTabTip()
-
-    var body: some View {
-        TabView {
-            Tab("Home", systemImage: "house") {
-                HomeView()
-            }
-
-            Tab("Discover", systemImage: "sparkles") {
-                DiscoverView()
-            }
-            .popoverTip(newTabTip)
+TabView {
+    Tab("Recipes", systemImage: "book") {
+        RecipesView()
+    }
+    Tab("Meal Plan", systemImage: "calendar") {
+        VStack {
+            TipView(mealPlanTip)
+            MealPlanView()
         }
     }
 }
 ```
 
-## Event-Based Rule with Donation Counting
+## Counting a manual action to suggest a shortcut
 
-Track how many times the user performs an action, then show a tip suggesting
-a more efficient alternative. This pattern is effective for progressive
-disclosure: let users learn the basic workflow first, then reveal shortcuts.
+A progressive-disclosure pattern: count how often someone does something the
+slow way, and after a threshold (five here) suggest the faster path.
 
 ```swift
-struct KeyboardShortcutTip: Tip {
-    static let manualSaveEvent = Tips.Event(id: "manualSave")
-
-    var title: Text {
-        Text("Save Faster with Command-S")
-    }
-
-    var message: Text? {
-        Text("Press Command-S instead of using the menu to save your work instantly.")
-    }
+struct SaveShortcutTip: Tip {
+    var title: Text { Text("Press Command-S to save") }
+    var message: Text? { Text("Works whenever a keyboard is attached.") }
 
-    var image: Image? {
-        Image(systemName: "keyboard")
-    }
+    static let manualSave = Tips.Event(id: "manualSave")
 
     var rules: [Rule] {
-        // Show after user has manually saved 5 times via button
-        #Rule(Self.manualSaveEvent) { $0.donations.count >= 5 }
+        #Rule(Self.manualSave) { $0.donations.count >= 5 }
     }
 }
 
-struct DocumentView: View {
-    let shortcutTip = KeyboardShortcutTip()
+struct NoteEditorView: View {
+    @State private var noteText = ""
+    let keyboardHint = SaveShortcutTip()
 
     var body: some View {
-        VStack {
-            TipView(shortcutTip)
-            DocumentEditor(document: $document)
+        VStack(spacing: 0) {
+            TipView(keyboardHint)
+            TextEditor(text: $noteText)
         }
         .toolbar {
-            ToolbarItem {
-                Button("Save") {
-                    saveDocument()
-                    KeyboardShortcutTip.manualSaveEvent.donate()
-                }
+            Button("Save") {
+                saveDraft()
+                Task { await SaveShortcutTip.manualSave.donate() }
             }
         }
     }
 }
 ```
 
-### Event Donations with Associated Values
+## Events that carry a value
 
-Attach a `DonationValue` to event donations for richer rule evaluation.
-Use `Codable`-conforming types to provide context about each donation.
+An event can record a value with every donation. Declare it as
+`Tips.Event<Value>` where the value type is `Codable` and `Sendable`, filter
+on the value in the rule, and pass the value to `donate`. Inside `#Rule`, give
+`filter` its closure in parentheses: the macro rejects trailing-closure
+syntax with "The filter function is not supported in this rule".
 
 ```swift
-struct DetailedTip: Tip {
-    struct DonationInfo: Codable, Sendable {
-        let category: String
-        let timestamp: Date
-    }
+struct PlaybackInfo: Codable, Sendable {
+    let tier: String
+}
+
+struct OfflineDownloadTip: Tip {
+    static let episodePlayed = Tips.Event<PlaybackInfo>(id: "episodePlayed")
 
-    static let itemViewed = Tips.Event<DonationInfo>(id: "itemViewed")
+    var title: Text { Text("Download for offline listening") }
 
     var rules: [Rule] {
-        #Rule(Self.itemViewed) {
-            $0.donations.filter {
-                $0.category == "premium"
-            }.count >= 3
+        #Rule(Self.episodePlayed) {
+            $0.donations.filter({ $0.tier == "premium" }).count >= 3
         }
     }
-
-    var title: Text { Text("Unlock Premium Content") }
 }
 
-// Donate with associated value
-DetailedTip.itemViewed.donate(
-    DetailedTip.DonationInfo(category: "premium", timestamp: .now)
-)
+Task {
+    await OfflineDownloadTip.episodePlayed.donate(PlaybackInfo(tier: "premium"))
+}
 ```
 
 ## Custom TipViewStyle
 
-Create a branded tip appearance that matches the app's design language.
-The `Configuration` provides access to the tip's title, message, image,
-and actions.
+`Configuration` gives the style `title`, `message`, `image` and `actions`.
+
+### A branded card
 
 ```swift
-struct BrandedTipStyle: TipViewStyle {
+struct BrandCardTipStyle: TipViewStyle {
     func makeBody(configuration: Configuration) -> some View {
-        HStack(alignment: .top) {
-            configuration.image?
-                .font(.system(size: 24))
-                .foregroundStyle(.white)
-                .frame(width: 44, height: 44)
-                .background(.blue.gradient, in: RoundedRectangle(cornerRadius: 10))
-
-            VStack(alignment: .leading) {
-                configuration.title
-                    .font(.headline)
-
-                configuration.message?
-                    .font(.subheadline)
-                    .foregroundStyle(.secondary)
-
-                if !configuration.actions.isEmpty {
-                    HStack {
-                        ForEach(configuration.actions) { action in
-                            Button(action: action.handler) {
-                                action.label
-                                    .font(.subheadline.bold())
-                            }
-                            .buttonStyle(.bordered)
+        VStack(alignment: .leading, spacing: 12) {
+            HStack(alignment: .top, spacing: 12) {
+                configuration.image
+                    .font(.title3)
+                    .frame(width: 44, height: 44, alignment: .center)
+                    .background(
+                        LinearGradient(
+                            colors: [.orange, .pink],
+                            startPoint: .topLeading,
+                            endPoint: .bottomTrailing
+                        ),
+                        in: RoundedRectangle(cornerRadius: 12)
+                    )
+                    .foregroundStyle(.white)
+                VStack(alignment: .leading, spacing: 4) {
+                    configuration.title
+                        .font(.title3.weight(.semibold))
+                    configuration.message
+                        .font(.callout)
+                        .foregroundStyle(.gray)
+                }
+            }
+            if configuration.actions.isEmpty == false {
+                HStack(spacing: 8) {
+                    ForEach(configuration.actions) { tipAction in
+                        Button(action: tipAction.handler) {
+                            tipAction.label()
                         }
+                        .buttonStyle(.bordered)
                     }
-                    .padding(.top)
                 }
             }
         }
         .padding()
-        .background(.regularMaterial, in: RoundedRectangle(cornerRadius: 16))
+        .background(.thinMaterial, in: RoundedRectangle(cornerRadius: 18))
     }
 }
 ```
 
-### Applying the Custom Style
-
-Apply the style to individual `TipView` instances or set it as the
-environment default.
+Apply it to one `TipView`, or set it on a parent such as a `NavigationStack`
+so it becomes the default for everything inside:
 
 ```swift
-// Per view
-TipView(myTip)
-    .tipViewStyle(BrandedTipStyle())
-
-// Environment-wide (apply to a parent container)
 NavigationStack {
-    ContentView()
+    PantryListView()
 }
-.tipViewStyle(BrandedTipStyle())
+.tipViewStyle(BrandCardTipStyle())
 ```
 
-### Minimal Compact Style
+### A compact variant
 
-A stripped-down style for tips in tight layouts like toolbars or sidebars.
+For narrow spaces like toolbars and sidebars, a single line on a tinted
+capsule is enough.
 
 ```swift
-struct CompactTipStyle: TipViewStyle {
+struct SlimTipStyle: TipViewStyle {
     func makeBody(configuration: Configuration) -> some View {
-        HStack {
-            configuration.image?
-                .foregroundStyle(.tint)
-
+        Label {
             configuration.title
                 .font(.caption.bold())
+                .lineLimit(1)
+        } icon: {
+            configuration.image
         }
-        .padding(.horizontal)
-        .padding(.vertical)
-        .background(.tint.opacity(0.1), in: Capsule())
+        .padding(.horizontal, 10)
+        .padding(.vertical, 6)
+        .background(Color.accentColor.opacity(0.15), in: Capsule())
     }
 }
 ```
 
-## TipGroup Sequencing
+## Sequencing with TipGroup (iOS 18)
 
-Use `TipGroup` to present a sequence of onboarding tips. Only the current
-tip displays. When the user dismisses or acts on it, the next tip in the
-group becomes current.
+A group shows only its current tip. Once that tip is dismissed or acted on,
+the next eligible tip takes its place.
 
 ```swift
-struct OnboardingTipA: Tip {
-    var title: Text { Text("Welcome to the App") }
-    var message: Text? { Text("Let's take a quick tour of the main features.") }
-    var image: Image? { Image(systemName: "hand.wave") }
-}
-
-struct OnboardingTipB: Tip {
-    var title: Text { Text("Browse Your Feed") }
-    var message: Text? { Text("Swipe through curated content tailored for you.") }
-    var image: Image? { Image(systemName: "rectangle.stack") }
-}
-
-struct OnboardingTipC: Tip {
-    var title: Text { Text("Customize Your Profile") }
-    var message: Text? { Text("Tap your avatar to set your name and preferences.") }
-    var image: Image? { Image(systemName: "person.crop.circle") }
-}
-
-struct HomeView: View {
-    let tipGroup = TipGroup(.ordered) {
-        OnboardingTipA()
-        OnboardingTipB()
-        OnboardingTipC()
+struct ArticleFeedScreen: View {
+    @State private var onboarding = TipGroup(.ordered) {
+        FollowTopicTip()
+        SaveArticleTip()
+        ReaderModeTip()
     }
 
     var body: some View {
-        VStack {
-            if let currentTip = tipGroup.currentTip {
-                TipView(currentTip) { action in
-                    currentTip.invalidate(reason: .actionPerformed)
+        ScrollView {
+            if let tip = onboarding.currentTip {
+                TipView(tip) { _ in
+                    tip.invalidate(reason: .actionPerformed)
                 }
             }
-
-            FeedView()
+            ArticleFeed()
         }
-        .padding()
     }
 }
 ```
 
-### Tip Group with Popover
+### Popovers that move between controls
 
-Attach the group's current tip as a popover that moves between controls
-as tips advance.
+Give each control a popover for its own tip type by casting
+`currentTip` to that type. As the group advances, the popover jumps to the next control.
 
 ```swift
-struct ToolbarGroupView: View {
-    let group = TipGroup(.ordered) {
-        SearchTip()
-        FilterTip()
-        SortTip()
-    }
-
-    var body: some View {
-        HStack {
-            Button("Search", systemImage: "magnifyingglass") { search() }
-                .popoverTip(group.currentTip as? SearchTip)
-
-            Button("Filter", systemImage: "line.3.horizontal.decrease") { filter() }
-                .popoverTip(group.currentTip as? FilterTip)
-
-            Button("Sort", systemImage: "arrow.up.arrow.down") { sort() }
-                .popoverTip(group.currentTip as? SortTip)
-        }
-    }
+HStack {
+    Button("Follow", systemImage: "plus") { follow() }
+        .popoverTip(onboarding.currentTip as? FollowTopicTip)
+    Button("Save", systemImage: "bookmark") { save() }
+        .popoverTip(onboarding.currentTip as? SaveArticleTip)
 }
 ```
 
-## Testing Strategies
+## Testing
 
-### Previewing Tips in SwiftUI Previews
+### Previews
 
-Configure TipKit in the preview body so tips display in Xcode previews.
-Use `showAllTipsForTesting()` to bypass rules.
+Reset the store and force tips on so they render in Xcode previews:
 
 ```swift
 #Preview {
-    ContentView()
-        .task {
+    PantryListView()
+        .task { @MainActor in
             try? Tips.resetDatastore()
             Tips.showAllTipsForTesting()
         }
 }
 ```
 
-### Previewing a Specific Tip
-
-Show only one tip in a focused preview.
+To look at one tip in isolation, show only that type:
 
 ```swift
-#Preview("Favorite Tip") {
-    VStack {
-        TipView(FavoriteTip())
-        Spacer()
-    }
-    .padding()
-    .task {
-        try? Tips.resetDatastore()
-        Tips.showTipsForTesting([FavoriteTip.self])
-    }
+#Preview("Filter tip only") {
+    PantryListView()
+        .task { @MainActor in
+            try? Tips.resetDatastore()
+            Tips.showTipsForTesting([PantryFilterTip.self])
+        }
 }
 ```
 
-### Unit Testing Tip Rules
+### Unit tests
 
-Verify that parameter and event rules correctly control tip eligibility.
-Reset the datastore before each test to ensure a clean state.
+Reset and configure in `setUp`, and reset again in `tearDown` so tests do not
+leak state into each other. Move a tip toward eligibility by setting its
+parameter and donating its event.
 
 ```swift
 import XCTest
 import TipKit
+@testable import RecipeBox
+
+final class BulkExportTipTests: XCTestCase {
+    private func clearTipStore() throws {
+        try Tips.resetDatastore()
+    }
 
-final class TipRuleTests: XCTestCase {
     override func setUp() async throws {
-        try? Tips.resetDatastore()
-        try? Tips.configure()
+        try clearTipStore()
+        try Tips.configure()
     }
 
     override func tearDown() async throws {
-        try? Tips.resetDatastore()
+        try clearTipStore()
     }
 
-    func testAdvancedSearchTipRequiresLogin() async {
-        let tip = AdvancedSearchTip()
-
-        // Tip should not be eligible before login
-        AdvancedSearchTip.isLoggedIn = false
-        // Verify tip status
-
-        // Tip should become eligible after login + enough events
-        AdvancedSearchTip.isLoggedIn = true
-        for _ in 0..<3 {
-            AdvancedSearchTip.searchPerformed.donate()
+    func testSignedInUserAfterThreeExports_BecomesEligible() async {
+        BulkExportTip.isSignedIn = true
+        for _ in 1...3 {
+            await BulkExportTip.recipeExported.donate()
         }
-        // Verify tip status
+        let tip = BulkExportTip()
+        // Assert on the tip's status here once eligibility is observable.
+        _ = tip
     }
 
-    func testTipInvalidation() async {
-        let tip = FavoriteTip()
+    func testInvalidatedTip_IsNoLongerEligible() async {
+        let tip = BulkExportTip()
         tip.invalidate(reason: .actionPerformed)
-        // Tip should no longer be eligible after invalidation
+        // Assert the tip reports an invalidated status here.
     }
 }
 ```
 
-### UI Testing with Forced Tips
+The status assertions are left as placeholders; how you read a tip's status
+depends on the TipKit API available to the test target.
 
-Pass launch arguments to control tip visibility in UI tests. This ensures
-tests that verify tip UI always see the tip, regardless of rules.
+### UI tests
+
+Force tips on from the test by adding a launch argument before `launch()`.
+`XCUIApplication` is main-actor isolated, so mark the test `@MainActor`:
 
 ```swift
-// In UI test setUp
-let app = XCUIApplication()
-app.launchArguments.append("--show-all-tips")
-app.launch()
+@MainActor
+func testFilterTipAppears() {
+    let app = XCUIApplication()
+    app.launchArguments += ["--show-all-tips"]
+    app.launch()
+}
 ```
 
+Tests that have nothing to do with tips pass `--hide-all-tips` instead so no
+tip covers the controls under test. The app reads both flags in `init`,
+before configuring:
+
 ```swift
-// In App.init
-init() {
-    if ProcessInfo.processInfo.arguments.contains("--show-all-tips") {
+enum TipTestFlag: String {
+    case showAll = "--show-all-tips"
+    case hideAll = "--hide-all-tips"
+}
+
+func applyTipTestFlags() {
+    let arguments = ProcessInfo.processInfo.arguments
+    if arguments.contains(TipTestFlag.showAll.rawValue) {
         Tips.showAllTipsForTesting()
-    }
-    if ProcessInfo.processInfo.arguments.contains("--hide-all-tips") {
+    } else if arguments.contains(TipTestFlag.hideAll.rawValue) {
         Tips.hideAllTipsForTesting()
     }
-    try? Tips.configure()
 }
-```
-
-### UI Testing Without Tips
-
-Suppress all tips in UI tests that are not about tip behavior, so tips
-do not interfere with other test flows.
 
-```swift
-// In UI test setUp for non-tip tests
-let app = XCUIApplication()
-app.launchArguments.append("--hide-all-tips")
-app.launch()
+init() {
+    #if DEBUG
+    applyTipTestFlags()
+    #endif
+    try? Tips.configure()
+}
 ```
 
-## Tip with Action Buttons
+## Actions that open a feature
 
-Add action buttons that deep-link to a feature. Invalidate the tip when
-the user taps the primary action.
+A primary action can take the person straight into the feature: it sets the
+presentation state and invalidates the tip as performed. A "Not Now" style
+secondary action closes the tip with `.tipClosed`.
 
 ```swift
-struct NewEditorTip: Tip {
-    var title: Text {
-        Text("Try the New Editor")
-    }
-
-    var message: Text? {
-        Text("A faster, more powerful editing experience awaits.")
-    }
-
-    var image: Image? {
-        Image(systemName: "pencil.and.outline")
-    }
+struct MealPlanTip: Tip {
+    var title: Text { Text("Plan your week") }
 
     var actions: [Action] {
-        Action(id: "open-editor", title: "Open Editor")
-        Action(id: "later", title: "Maybe Later")
+        Action(id: "start-plan", title: "Start a Plan")
+        Action(id: "not-now", title: "Not Now")
     }
 }
 
-struct HomeView: View {
-    let editorTip = NewEditorTip()
-    @State private var showEditor = false
+struct PlannerEntryView: View {
+    let planTip = MealPlanTip()
+    @State private var isPlannerShown = false
 
     var body: some View {
-        VStack {
-            TipView(editorTip) { action in
-                switch action.id {
-                case "open-editor":
-                    showEditor = true
-                    editorTip.invalidate(reason: .actionPerformed)
-                case "later":
-                    editorTip.invalidate(reason: .tipClosed)
-                default:
-                    break
-                }
+        TipView(planTip) { action in
+            if action.id == "start-plan" {
+                isPlannerShown = true
+                planTip.invalidate(reason: .actionPerformed)
+            } else {
+                planTip.invalidate(reason: .tipClosed)
             }
-
-            MainContentView()
         }
-        .sheet(isPresented: $showEditor) {
-            EditorView()
+        .sheet(isPresented: $isPlannerShown) {
+            MealPlannerView()
         }
     }
 }
 ```
 
-## Integration with Onboarding Flow
+## Working alongside an onboarding flow
 
-Coordinate TipKit with a first-run onboarding flow. Invalidate welcome
-tips after the user completes onboarding so they do not see redundant
-information.
+Give both tips a `didFinishOnboarding` parameter (the has-completed-onboarding
+flag). A welcome tip uses
+`== false`, so it only appears for people who skipped onboarding. A discovery
+tip uses `== true`, so it only appears once onboarding is done.
 
 ```swift
 struct WelcomeTip: Tip {
-    @Parameter
-    static var hasCompletedOnboarding: Bool = false
+    var title: Text { Text("Your recipes, all in one place") }
 
-    var title: Text { Text("Welcome to MyApp") }
-    var message: Text? { Text("Swipe through to learn the basics.") }
+    @Parameter
+    static var didFinishOnboarding: Bool = false
 
     var rules: [Rule] {
-        // Only show if onboarding was NOT completed (user skipped it)
-        #Rule(Self.$hasCompletedOnboarding) { $0 == false }
+        #Rule(Self.$didFinishOnboarding) { $0 == false }
     }
 }
 
-struct FeatureDiscoveryTip: Tip {
-    @Parameter
-    static var hasCompletedOnboarding: Bool = false
+struct CollectionsTip: Tip {
+    var title: Text { Text("Group recipes into collections") }
 
-    var title: Text { Text("Discover Collections") }
-    var message: Text? { Text("Organize your items into collections for easy access.") }
+    @Parameter
+    static var didFinishOnboarding: Bool = false
 
     var rules: [Rule] {
-        // Only show after onboarding completes
-        #Rule(Self.$hasCompletedOnboarding) { $0 == true }
+        #Rule(Self.$didFinishOnboarding) { $0 == true }
     }
 }
+```
 
-struct OnboardingView: View {
-    @Binding var isPresented: Bool
-
-    var body: some View {
-        VStack {
-            // Onboarding pages...
-
-            Button("Get Started") {
-                completeOnboarding()
-            }
-        }
-    }
-
-    func completeOnboarding() {
-        // Invalidate welcome tips since onboarding covered the basics
-        WelcomeTip.hasCompletedOnboarding = true
-        FeatureDiscoveryTip.hasCompletedOnboarding = true
+When onboarding finishes, flip both parameters, invalidate the welcome tip
+explicitly, and close the sheet. The host view below does this in the
+onboarding completion closure.
 
-        // Explicitly invalidate any welcome-specific tips
-        let welcomeTip = WelcomeTip()
-        welcomeTip.invalidate(reason: .actionPerformed)
-
-        isPresented = false
-    }
-}
-
-struct ContentView: View {
-    @AppStorage("hasCompletedOnboarding") private var hasCompletedOnboarding = false
-    @State private var showOnboarding = false
+The host view remembers completion in `@AppStorage`, presents onboarding in a
+sheet on first appearance, and shows both tips:
 
+```swift
+struct RecipeBoxHomeView: View {
+    @AppStorage("onboardingDone") private var onboardingDone = false
+    @State private var isOnboardingShown = false
     let welcomeTip = WelcomeTip()
-    let discoveryTip = FeatureDiscoveryTip()
+    let collectionsTip = CollectionsTip()
 
     var body: some View {
-        NavigationStack {
-            VStack {
-                TipView(welcomeTip)
-
-                CollectionGrid()
-                    .popoverTip(discoveryTip)
-            }
-        }
-        .sheet(isPresented: $showOnboarding) {
-            OnboardingView(isPresented: $showOnboarding)
+        VStack {
+            TipView(welcomeTip)
+            RecipeGrid()
+                .popoverTip(collectionsTip)
         }
         .onAppear {
-            if !hasCompletedOnboarding {
-                showOnboarding = true
+            if onboardingDone == false {
+                isOnboardingShown = true
+            }
+        }
+        .sheet(isPresented: $isOnboardingShown) {
+            OnboardingView {
+                onboardingDone = true
+                WelcomeTip.didFinishOnboarding = true
+                CollectionsTip.didFinishOnboarding = true
+                welcomeTip.invalidate(reason: .actionPerformed)
+                isOnboardingShown = false
             }
         }
     }
 }
 ```
 
-## Full App Integration Example
+## A full app
 
-A complete example showing TipKit configuration, multiple tips with rules,
-a tip group, event donations, and proper invalidation.
+Three tips: one with no rules, one that waits for three "item added"
+donations, and one that waits until a collection exists.
 
 ```swift
 import SwiftUI
 import TipKit
 
-// MARK: - Tips
-
-struct SearchTip: Tip {
-    var title: Text { Text("Search Your Library") }
-    var message: Text? { Text("Tap to find any item by name, tag, or date.") }
-    var image: Image? { Image(systemName: "magnifyingglass") }
+struct ScanBarcodeTip: Tip {
+    var title: Text { Text("Scan to add") }
+    var image: Image? { Image(systemName: "barcode.viewfinder") }
 }
 
-struct CollectionTip: Tip {
-    static let itemAddedEvent = Tips.Event(id: "itemAdded")
+struct BatchEditTip: Tip {
+    var title: Text { Text("Edit several items at once") }
 
-    var title: Text { Text("Create a Collection") }
-    var message: Text? { Text("Group related items together for quick access.") }
-    var image: Image? { Image(systemName: "folder.badge.plus") }
+    static let itemAdded = Tips.Event(id: "itemAdded")
 
     var rules: [Rule] {
-        #Rule(Self.itemAddedEvent) { $0.donations.count >= 3 }
+        #Rule(Self.itemAdded) { $0.donations.count >= 3 }
     }
 }
 
-struct ShareTip: Tip {
-    @Parameter
-    static var hasCreatedCollection: Bool = false
+struct ShareCollectionTip: Tip {
+    var title: Text { Text("Send a collection to a friend") }
 
-    var title: Text { Text("Share Your Collection") }
-    var message: Text? { Text("Invite others to view or collaborate on your collection.") }
-    var image: Image? { Image(systemName: "square.and.arrow.up") }
+    @Parameter
+    static var hasCollection: Bool = false
 
     var rules: [Rule] {
-        #Rule(Self.$hasCreatedCollection) { $0 == true }
+        #Rule(Self.$hasCollection) { $0 == true }
     }
 }
 
-// MARK: - App
-
 @main
-struct LibraryApp: App {
+struct PantryApp: App {
+    var body: some Scene {
+        WindowGroup {
+            NavigationStack {
+                PantryHomeView()
+            }
+        }
+    }
+
     init() {
         #if DEBUG
-        if ProcessInfo.processInfo.arguments.contains("--show-all-tips") {
-            Tips.showAllTipsForTesting()
-        }
-        if ProcessInfo.processInfo.arguments.contains("--hide-all-tips") {
-            Tips.hideAllTipsForTesting()
-        }
+        applyTipTestFlags()
         #endif
-
         try? Tips.configure([
-            .displayFrequency(.daily),
-            .datastoreLocation(.applicationDefault)
+            .datastoreLocation(.applicationDefault),
+            .displayFrequency(.daily)
         ])
     }
-
-    var body: some Scene {
-        WindowGroup { LibraryView() }
-    }
 }
 
-// MARK: - Main View
-
-struct LibraryView: View {
-    let searchTip = SearchTip()
-    let collectionTip = CollectionTip()
-    let shareTip = ShareTip()
-
-    @State private var items: [LibraryItem] = []
+struct PantryHomeView: View {
+    let scanTip = ScanBarcodeTip()
+    let batchTip = BatchEditTip()
+    let shareTip = ShareCollectionTip()
 
     var body: some View {
-        NavigationStack {
-            List {
-                TipView(collectionTip)
-
-                ForEach(items) { item in
-                    Text(item.name)
+        List {
+            TipView(scanTip)
+            PantryItemsSection()
+        }
+        .toolbar {
+            ToolbarItem(placement: .primaryAction) {
+                Button("Edit", systemImage: "checklist") {
+                    batchTip.invalidate(reason: .actionPerformed)
+                    beginBatchEdit()
                 }
+                .popoverTip(batchTip)
             }
-            .navigationTitle("Library")
-            .toolbar {
-                ToolbarItem(placement: .primaryAction) {
-                    Button("Search", systemImage: "magnifyingglass") {
-                        showSearch()
-                        searchTip.invalidate(reason: .actionPerformed)
-                    }
-                    .popoverTip(searchTip)
+            ToolbarItem(placement: .secondaryAction) {
+                Button("Send", systemImage: "person.2") {
+                    shareTip.invalidate(reason: .actionPerformed)
+                    shareCollection()
                 }
-
-                ToolbarItem(placement: .secondaryAction) {
-                    Button("Share", systemImage: "square.and.arrow.up") {
-                        shareCollection()
-                        shareTip.invalidate(reason: .actionPerformed)
-                    }
-                    .popoverTip(shareTip)
-                }
-
-                ToolbarItem(placement: .secondaryAction) {
-                    Button("Add Item", systemImage: "plus") {
-                        addItem()
-                        CollectionTip.itemAddedEvent.donate()
-                    }
+                .popoverTip(shareTip)
+            }
+            ToolbarItem(placement: .bottomBar) {
+                Button("Add Item") {
+                    addItem()
+                    Task { await BatchEditTip.itemAdded.donate() }
                 }
             }
         }
     }
-
-    func addItem() { /* ... */ }
-    func showSearch() { /* ... */ }
-    func shareCollection() { /* ... */ }
 }
 ```
+
+The "Add Item" button carries no tip of its own; it only donates the event
+that eventually makes `BatchEditTip` eligible. `applyTipTestFlags()` is the
+DEBUG helper from the UI tests section.