@mmerterden/multi-agent-pipeline 20.36.0 → 20.37.1

package/pipeline/skills/shared/external/cloudkit-sync/SKILL.md

@@ -43,26 +43,7 @@ let sharedDB = container.sharedCloudDatabase
 A `CKRecord` is a typed dictionary. One record can hold up to 1 MB, not
 counting the files behind any `CKAsset` fields.
 
-```swift
-func plant(named name: String, in db: CKDatabase) async throws -> CKRecord {
-    let plant = CKRecord(recordType: "Plant")
-    plant["name"] = name as CKRecordValue
-    plant["plantedOn"] = Date.now as CKRecordValue
-    plant["tags"] = ["herb", "sunny"] as CKRecordValue
-    return try await db.save(plant)
-}
-
-func rename(_ recordName: String, to newName: String, in db: CKDatabase) async throws {
-    let id = CKRecord.ID(recordName: recordName)
-    let existing = try await db.record(for: id)       // always fetch before editing
-    existing["name"] = newName as CKRecordValue
-    _ = try await db.save(existing)
-}
-
-func uproot(_ recordName: String, in db: CKDatabase) async throws {
-    _ = try await db.deleteRecord(withID: CKRecord.ID(recordName: recordName))
-}
-```
+Code for this section: [CloudKit code](references/cloudkit-code.md).
 
 ### Custom zones
 
@@ -120,38 +101,7 @@ With CloudKit enabled, Xcode manages the push entitlement; no separate App ID
 push setup is needed. Silent pushes still require **Background Modes >
 Remote notifications**.
 
-```swift
-let newPlants = CKQuerySubscription(
-    recordType: "Plant",
-    predicate: NSPredicate(value: true),
-    subscriptionID: "plant-changes",
-    options: [.firesOnRecordCreation, .firesOnRecordUpdate]
-)
-let info = CKSubscription.NotificationInfo()
-info.shouldSendContentAvailable = true      // silent
-newPlants.notificationInfo = info
-_ = try await publicDB.save(newPlants)
-
-let everything = CKDatabaseSubscription(subscriptionID: "private-db")          // any change in the DB
-let oneZone = CKRecordZoneSubscription(zoneID: beds, subscriptionID: "beds")   // changes in one zone
-```
-
-```swift
-import UIKit
-
-// UIApplicationDelegate
-func application(_ application: UIApplication,
-                 didReceiveRemoteNotification userInfo: [AnyHashable: Any]) async -> UIBackgroundFetchResult {
-    guard let note = CKNotification(fromRemoteNotificationDictionary: userInfo),
-          note.subscriptionID == "private-db" else { return .noData }
-    do {
-        try await GardenSync.shared.pullNow()   // CKSyncEngine or CKFetchRecordZoneChangesOperation
-        return .newData
-    } catch {
-        return .failed
-    }
-}
-```
+Code for this section: [CloudKit code](references/cloudkit-code.md).
 
 ## CKSyncEngine (iOS 17+)
 
@@ -164,65 +114,14 @@ Its automatic timing is not predictable. It needs the CloudKit capability plus
 Remote notifications, and works only with private and shared databases, never
 public.
 
-```swift
-actor GardenSync: CKSyncEngineDelegate {
-    static let shared = GardenSync()
-    private var engine: CKSyncEngine?
-
-    func start() {
-        guard engine == nil else { return }
-        let config = CKSyncEngine.Configuration(
-            database: CKContainer.default().privateCloudDatabase,
-            stateSerialization: StateFile.load(),   // CKSyncEngine.State.Serialization?
-            delegate: self
-        )
-        engine = CKSyncEngine(config)
-    }
-
-    func handleEvent(_ event: CKSyncEngine.Event, syncEngine: CKSyncEngine) async {
-        switch event {
-        case .stateUpdate(let update):
-            StateFile.save(update.stateSerialization)      // resume from the right token next launch
-        case .accountChange(let change):
-            await LocalStore.shared.handle(change)
-        case .fetchedRecordZoneChanges(let fetched):
-            for mod in fetched.modifications { await LocalStore.shared.upsert(mod.record) }
-            for gone in fetched.deletions { await LocalStore.shared.remove(gone.recordID) }
-        case .sentRecordZoneChanges(let sent):
-            for saved in sent.savedRecords { await LocalStore.shared.markSynced(saved) }
-            for failure in sent.failedRecordSaves { await resolve(failure, engine: syncEngine) }
-        default:
-            break
-        }
-    }
-
-    func nextRecordZoneChangeBatch(_ context: CKSyncEngine.SendChangesContext,
-                                   syncEngine: CKSyncEngine) async -> CKSyncEngine.RecordZoneChangeBatch? {
-        let scope = context.options.scope
-        let pending = syncEngine.state.pendingRecordZoneChanges.filter { scope.contains($0) }
-        return await CKSyncEngine.RecordZoneChangeBatch(pendingChanges: pending) { id in
-            await LocalStore.shared.record(for: id)
-        }
-    }
-
-    func queueUpload(of id: CKRecord.ID) {
-        engine?.state.add(pendingRecordZoneChanges: [.saveRecord(id)])
-    }
-
-    func pullNow() async throws {
-        guard let engine else { return }
-        try await engine.fetchChanges()     // pull-to-refresh or push arrival
-        try await engine.sendChanges()
-    }
-}
-```
-
 `context.options.scope` says which zones (for example `.zoneIDs([...])`) or
 records this send covers; filter the pending changes to it rather than
 sending everything. Both delegate methods are `async`. Persist
 `stateSerialization` on every `.stateUpdate`; without it the engine starts
 over on the next launch.
 
+Code for this section: [CloudKit code](references/cloudkit-code.md).
+
 ## SwiftData with CloudKit
 
 `ModelConfiguration` can sync a SwiftData store to CloudKit. Any
@@ -317,28 +216,6 @@ coordinated read of a ubiquitous item waits for its contents to download
 unless `.immediatelyAvailableMetadataOnly` is passed. Coordination blocks the
 calling thread, so keep it off the main actor.
 
-```swift
-nonisolated func readCoordinated(_ url: URL) throws -> Data {
-    var coordinationError: NSError?
-    var result: Result<Data, any Error> = .failure(CocoaError(.fileReadUnknown))
-    NSFileCoordinator().coordinate(readingItemAt: url, options: [], error: &coordinationError) { safeURL in
-        result = Result { try Data(contentsOf: safeURL) }
-    }
-    if let coordinationError { throw coordinationError }
-    return try result.get()
-}
-
-nonisolated func writeCoordinated(_ data: Data, to url: URL) throws {
-    var coordinationError: NSError?
-    var writeError: (any Error)?
-    NSFileCoordinator().coordinate(writingItemAt: url, options: .forReplacing, error: &coordinationError) { safeURL in
-        do { try data.write(to: safeURL, options: .atomic) } catch { writeError = error }
-    }
-    if let coordinationError { throw coordinationError }
-    if let writeError { throw writeError }
-}
-```
-
 An object that keeps a file open (an editor, a live preview) adopts
 `NSFilePresenter` so it hears about changes, moves and deletions that iCloud
 makes: implement `presentedItemURL`, return a private `OperationQueue` from
@@ -349,6 +226,8 @@ with `removeFilePresenter(_:)`. Create the presenter's own coordinators with
 `UIDocument` already does all of this, so a document-based app gets
 coordination by subclassing it.
 
+Code for this section: [CloudKit code](references/cloudkit-code.md).
+
 ## Account status
 
 Check the account before any sync, and listen for `.CKAccountChanged`.
@@ -389,25 +268,7 @@ A `.serverRecordChanged` error carries `ancestorRecord`, `clientRecord` and
 `serverRecord`. Always merge **into `serverRecord`**, because it holds the
 current change tag; saving the client copy just fails again.
 
-```swift
-func merged(_ error: CKError) -> CKRecord? {
-    guard let server = error.serverRecord, let mine = error.clientRecord else { return nil }
-    let base = error.ancestorRecord
-    for key in mine.changedKeys() {
-        let serverValue = server[key] as? NSObject
-        let baseValue = base?[key] as? NSObject
-        let myValue = mine[key] as? NSObject
-        if serverValue == baseValue {
-            server[key] = mine[key]                  // only I changed it
-        } else if myValue == baseValue {
-            continue                                 // only the server changed it
-        } else {
-            server[key] = resolveBothChanged(key, mine: mine[key], theirs: server[key])
-        }
-    }
-    return server                                    // save this one
-}
-```
+Code for this section: [CloudKit code](references/cloudkit-code.md).
 
 ## Common mistakes
 
@@ -441,6 +302,7 @@ func merged(_ error: CKError) -> CKRecord? {
 
 ## References
 
+- [CloudKit code](references/cloudkit-code.md): open for the code behind records, subscriptions, CKSyncEngine, coordinated file access and conflict resolution.
 - [CloudKit patterns](references/cloudkit-patterns.md) - incremental fetches, tokens, sharing, zones, assets, batches, QoS, encryption, Dashboard
 - [CloudKit](https://developer.apple.com/documentation/cloudkit)
 - [CKContainer](https://developer.apple.com/documentation/cloudkit/ckcontainer)

package/pipeline/skills/shared/external/cloudkit-sync/references/cloudkit-code.md

@@ -0,0 +1,214 @@
+# CloudKit code
+
+<!-- toc -->
+- [Records](#records)
+- [Subscriptions](#subscriptions)
+- [CKSyncEngine (iOS 17+)](#cksyncengine-ios-17)
+- [Conflict resolution](#conflict-resolution)
+<!-- /toc -->
+
+Code for records, subscriptions, CKSyncEngine, coordinated document access and conflict resolution. SKILL.md keeps the rules and decision guidance.
+
+## Records
+
+A `CKRecord` is a typed dictionary. One record can hold up to 1 MB, not
+counting the files behind any `CKAsset` fields.
+
+```swift
+func plant(named name: String, in db: CKDatabase) async throws -> CKRecord {
+    let plant = CKRecord(recordType: "Plant")
+    plant["name"] = name as CKRecordValue
+    plant["plantedOn"] = Date.now as CKRecordValue
+    plant["tags"] = ["herb", "sunny"] as CKRecordValue
+    return try await db.save(plant)
+}
+
+func rename(_ recordName: String, to newName: String, in db: CKDatabase) async throws {
+    let id = CKRecord.ID(recordName: recordName)
+    let existing = try await db.record(for: id)       // always fetch before editing
+    existing["name"] = newName as CKRecordValue
+    _ = try await db.save(existing)
+}
+
+func uproot(_ recordName: String, in db: CKDatabase) async throws {
+    _ = try await db.deleteRecord(withID: CKRecord.ID(recordName: recordName))
+}
+```
+
+## Subscriptions
+
+A subscription makes CloudKit push a notification when server data changes.
+With CloudKit enabled, Xcode manages the push entitlement; no separate App ID
+push setup is needed. Silent pushes still require **Background Modes >
+Remote notifications**.
+
+```swift
+let newPlants = CKQuerySubscription(
+    recordType: "Plant",
+    predicate: NSPredicate(value: true),
+    subscriptionID: "plant-changes",
+    options: [.firesOnRecordCreation, .firesOnRecordUpdate]
+)
+let info = CKSubscription.NotificationInfo()
+info.shouldSendContentAvailable = true      // silent
+newPlants.notificationInfo = info
+_ = try await publicDB.save(newPlants)
+
+let everything = CKDatabaseSubscription(subscriptionID: "private-db")          // any change in the DB
+let oneZone = CKRecordZoneSubscription(zoneID: beds, subscriptionID: "beds")   // changes in one zone
+```
+
+```swift
+import UIKit
+
+// UIApplicationDelegate
+func application(_ application: UIApplication,
+                 didReceiveRemoteNotification userInfo: [AnyHashable: Any]) async -> UIBackgroundFetchResult {
+    guard let note = CKNotification(fromRemoteNotificationDictionary: userInfo),
+          note.subscriptionID == "private-db" else { return .noData }
+    do {
+        try await GardenSync.shared.pullNow()   // CKSyncEngine or CKFetchRecordZoneChangesOperation
+        return .newData
+    } catch {
+        return .failed
+    }
+}
+```
+
+## CKSyncEngine (iOS 17+)
+
+For custom model data, `CKSyncEngine` is the recommended route. It schedules
+work, retries transient failures, keeps change tokens and manages the
+database subscription for you. It does **not** resolve app-level save
+failures: a `CKError.serverRecordChanged` inside
+`sentRecordZoneChanges.failedRecordSaves` needs your merge and a reschedule.
+Its automatic timing is not predictable. It needs the CloudKit capability plus
+Remote notifications, and works only with private and shared databases, never
+public.
+
+```swift
+actor GardenSync: CKSyncEngineDelegate {
+    static let shared = GardenSync()
+    private var engine: CKSyncEngine?
+
+    func start() {
+        guard engine == nil else { return }
+        let config = CKSyncEngine.Configuration(
+            database: CKContainer.default().privateCloudDatabase,
+            stateSerialization: StateFile.load(),   // CKSyncEngine.State.Serialization?
+            delegate: self
+        )
+        engine = CKSyncEngine(config)
+    }
+
+    func handleEvent(_ event: CKSyncEngine.Event, syncEngine: CKSyncEngine) async {
+        switch event {
+        case .stateUpdate(let update):
+            StateFile.save(update.stateSerialization)      // resume from the right token next launch
+        case .accountChange(let change):
+            await LocalStore.shared.handle(change)
+        case .fetchedRecordZoneChanges(let fetched):
+            for mod in fetched.modifications { await LocalStore.shared.upsert(mod.record) }
+            for gone in fetched.deletions { await LocalStore.shared.remove(gone.recordID) }
+        case .sentRecordZoneChanges(let sent):
+            for saved in sent.savedRecords { await LocalStore.shared.markSynced(saved) }
+            for failure in sent.failedRecordSaves { await resolve(failure, engine: syncEngine) }
+        default:
+            break
+        }
+    }
+
+    func nextRecordZoneChangeBatch(_ context: CKSyncEngine.SendChangesContext,
+                                   syncEngine: CKSyncEngine) async -> CKSyncEngine.RecordZoneChangeBatch? {
+        let scope = context.options.scope
+        let pending = syncEngine.state.pendingRecordZoneChanges.filter { scope.contains($0) }
+        return await CKSyncEngine.RecordZoneChangeBatch(pendingChanges: pending) { id in
+            await LocalStore.shared.record(for: id)
+        }
+    }
+
+    func queueUpload(of id: CKRecord.ID) {
+        engine?.state.add(pendingRecordZoneChanges: [.saveRecord(id)])
+    }
+
+    func pullNow() async throws {
+        guard let engine else { return }
+        try await engine.fetchChanges()     // pull-to-refresh or push arrival
+        try await engine.sendChanges()
+    }
+}
+```
+
+`context.options.scope` says which zones (for example `.zoneIDs([...])`) or
+records this send covers; filter the pending changes to it rather than
+sending everything. Both delegate methods are `async`. Persist
+`stateSerialization` on every `.stateUpdate`; without it the engine starts
+over on the next launch.
+
+### Coordinated reads and writes
+
+The iCloud daemon reads and writes files in the ubiquity container at the same
+time as the app, so every direct access to a ubiquitous file goes through
+`NSFileCoordinator`. Do the file work only inside the accessor block and only
+with the URL it passes in, which can differ from the one requested. A
+coordinated read of a ubiquitous item waits for its contents to download
+unless `.immediatelyAvailableMetadataOnly` is passed. Coordination blocks the
+calling thread, so keep it off the main actor.
+
+```swift
+nonisolated func readCoordinated(_ url: URL) throws -> Data {
+    var coordinationError: NSError?
+    var result: Result<Data, any Error> = .failure(CocoaError(.fileReadUnknown))
+    NSFileCoordinator().coordinate(readingItemAt: url, options: [], error: &coordinationError) { safeURL in
+        result = Result { try Data(contentsOf: safeURL) }
+    }
+    if let coordinationError { throw coordinationError }
+    return try result.get()
+}
+
+nonisolated func writeCoordinated(_ data: Data, to url: URL) throws {
+    var coordinationError: NSError?
+    var writeError: (any Error)?
+    NSFileCoordinator().coordinate(writingItemAt: url, options: .forReplacing, error: &coordinationError) { safeURL in
+        do { try data.write(to: safeURL, options: .atomic) } catch { writeError = error }
+    }
+    if let coordinationError { throw coordinationError }
+    if let writeError { throw writeError }
+}
+```
+
+An object that keeps a file open (an editor, a live preview) adopts
+`NSFilePresenter` so it hears about changes, moves and deletions that iCloud
+makes: implement `presentedItemURL`, return a private `OperationQueue` from
+`presentedItemOperationQueue` (the main queue invites deadlocks), react in
+`presentedItemDidChange()`, and pair `NSFileCoordinator.addFilePresenter(_:)`
+with `removeFilePresenter(_:)`. Create the presenter's own coordinators with
+`NSFileCoordinator(filePresenter:)` so it is not told about its own writes.
+`UIDocument` already does all of this, so a document-based app gets
+coordination by subclassing it.
+
+## Conflict resolution
+
+A `.serverRecordChanged` error carries `ancestorRecord`, `clientRecord` and
+`serverRecord`. Always merge **into `serverRecord`**, because it holds the
+current change tag; saving the client copy just fails again.
+
+```swift
+func merged(_ error: CKError) -> CKRecord? {
+    guard let server = error.serverRecord, let mine = error.clientRecord else { return nil }
+    let base = error.ancestorRecord
+    for key in mine.changedKeys() {
+        let serverValue = server[key] as? NSObject
+        let baseValue = base?[key] as? NSObject
+        let myValue = mine[key] as? NSObject
+        if serverValue == baseValue {
+            server[key] = mine[key]                  // only I changed it
+        } else if myValue == baseValue {
+            continue                                 // only the server changed it
+        } else {
+            server[key] = resolveBothChanged(key, mine: mine[key], theirs: server[key])
+        }
+    }
+    return server                                    // save this one
+}
+```

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

@@ -35,43 +35,7 @@ Material 3 (androidx.compose.material3).
 Scaffold provides the standard Material 3 layout structure with slots for
 top bar, bottom bar, FAB, snackbar, and content.
 
-```kotlin
-@OptIn(ExperimentalMaterial3Api::class)
-@Composable
-fun HomeScreen(
-    onNavigateToSettings: () -> Unit,
-    viewModel: HomeViewModel = hiltViewModel(),
-) {
-    val scrollBehavior = TopAppBarDefaults.pinnedScrollBehavior()
-    val snackbarHostState = remember { SnackbarHostState() }
-
-    Scaffold(
-        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
-        topBar = {
-            TopAppBar(
-                title = { Text("Home") },
-                actions = {
-                    IconButton(onClick = onNavigateToSettings) {
-                        Icon(Icons.Default.Settings, contentDescription = "Settings")
-                    }
-                },
-                scrollBehavior = scrollBehavior,
-            )
-        },
-        snackbarHost = { SnackbarHost(snackbarHostState) },
-        floatingActionButton = {
-            FloatingActionButton(onClick = { /* action */ }) {
-                Icon(Icons.Default.Add, contentDescription = "Add")
-            }
-        },
-    ) { innerPadding ->
-        HomeContent(
-            modifier = Modifier.padding(innerPadding),
-            viewModel = viewModel,
-        )
-    }
-}
-```
+Code: [Scaffold and TopAppBar](references/code-examples.md#scaffold-and-topappbar).
 
 ### TopAppBar Variants
 
@@ -171,49 +135,7 @@ fun ScreenWithSnackbar() {
 Design custom composables with slot parameters (lambdas returning `@Composable`
 content). This follows the Material 3 pattern used by `Scaffold`, `Card`, etc.
 
-```kotlin
-@Composable
-fun InfoCard(
-    modifier: Modifier = Modifier,
-    icon: @Composable () -> Unit,
-    title: @Composable () -> Unit,
-    subtitle: @Composable (() -> Unit)? = null,
-    actions: @Composable RowScope.() -> Unit = {},
-) {
-    Card(modifier = modifier) {
-        Row(
-            modifier = Modifier.padding(16.dp),
-            verticalAlignment = Alignment.CenterVertically,
-        ) {
-            icon()
-            Spacer(modifier = Modifier.width(16.dp))
-            Column(modifier = Modifier.weight(1f)) {
-                ProvideTextStyle(MaterialTheme.typography.titleMedium) {
-                    title()
-                }
-                subtitle?.let {
-                    ProvideTextStyle(MaterialTheme.typography.bodyMedium) {
-                        it()
-                    }
-                }
-            }
-            Row(content = actions)
-        }
-    }
-}
-
-// Usage
-InfoCard(
-    icon = { Icon(Icons.Default.ShoppingCart, contentDescription = null) },
-    title = { Text("London to New York") },
-    subtitle = { Text("Order AB1234") },
-    actions = {
-        IconButton(onClick = { /* bookmark */ }) {
-            Icon(Icons.Default.BookmarkBorder, contentDescription = "Bookmark")
-        }
-    },
-)
-```
+Code: [Slot-Based API Pattern](references/code-examples.md#slot-based-api-pattern).
 
 ### Slot Design Rules
 - First parameter: `modifier: Modifier = Modifier`
@@ -489,3 +411,7 @@ Box(
 - [ ] 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
+
+## References
+
+- [Code examples](references/code-examples.md): open for the full code behind Scaffold and TopAppBar, Slot-Based API Pattern.

package/pipeline/skills/shared/external/compose-components/references/code-examples.md

@@ -0,0 +1,89 @@
+# Compose Components 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.
+
+## Scaffold and TopAppBar
+
+```kotlin
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+fun HomeScreen(
+    onNavigateToSettings: () -> Unit,
+    viewModel: HomeViewModel = hiltViewModel(),
+) {
+    val scrollBehavior = TopAppBarDefaults.pinnedScrollBehavior()
+    val snackbarHostState = remember { SnackbarHostState() }
+
+    Scaffold(
+        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
+        topBar = {
+            TopAppBar(
+                title = { Text("Home") },
+                actions = {
+                    IconButton(onClick = onNavigateToSettings) {
+                        Icon(Icons.Default.Settings, contentDescription = "Settings")
+                    }
+                },
+                scrollBehavior = scrollBehavior,
+            )
+        },
+        snackbarHost = { SnackbarHost(snackbarHostState) },
+        floatingActionButton = {
+            FloatingActionButton(onClick = { /* action */ }) {
+                Icon(Icons.Default.Add, contentDescription = "Add")
+            }
+        },
+    ) { innerPadding ->
+        HomeContent(
+            modifier = Modifier.padding(innerPadding),
+            viewModel = viewModel,
+        )
+    }
+}
+```
+
+## Slot-Based API Pattern
+
+```kotlin
+@Composable
+fun InfoCard(
+    modifier: Modifier = Modifier,
+    icon: @Composable () -> Unit,
+    title: @Composable () -> Unit,
+    subtitle: @Composable (() -> Unit)? = null,
+    actions: @Composable RowScope.() -> Unit = {},
+) {
+    Card(modifier = modifier) {
+        Row(
+            modifier = Modifier.padding(16.dp),
+            verticalAlignment = Alignment.CenterVertically,
+        ) {
+            icon()
+            Spacer(modifier = Modifier.width(16.dp))
+            Column(modifier = Modifier.weight(1f)) {
+                ProvideTextStyle(MaterialTheme.typography.titleMedium) {
+                    title()
+                }
+                subtitle?.let {
+                    ProvideTextStyle(MaterialTheme.typography.bodyMedium) {
+                        it()
+                    }
+                }
+            }
+            Row(content = actions)
+        }
+    }
+}
+
+// Usage
+InfoCard(
+    icon = { Icon(Icons.Default.ShoppingCart, contentDescription = null) },
+    title = { Text("London to New York") },
+    subtitle = { Text("Order AB1234") },
+    actions = {
+        IconButton(onClick = { /* bookmark */ }) {
+            Icon(Icons.Default.BookmarkBorder, contentDescription = "Bookmark")
+        }
+    },
+)
+```

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

@@ -293,70 +293,7 @@ NavHost(
 Integrate `NavigationBar` (Material 3) with NavHost. Each tab maintains its
 own back stack.
 
-```kotlin
-@Serializable
-object HomeRoute
-
-@Serializable
-object SearchRoute
-
-@Serializable
-object ProfileRoute
-
-enum class TopLevelDestination(
-    val label: String,
-    val icon: ImageVector,
-    val route: Any,
-) {
-    HOME("Home", Icons.Default.Home, HomeRoute),
-    SEARCH("Search", Icons.Default.Search, SearchRoute),
-    PROFILE("Profile", Icons.Default.Person, ProfileRoute),
-}
-
-@Composable
-fun MainScreen() {
-    val navController = rememberNavController()
-    val currentBackStackEntry by navController.currentBackStackEntryAsState()
-
-    Scaffold(
-        bottomBar = {
-            NavigationBar {
-                TopLevelDestination.entries.forEach { destination ->
-                    val isSelected = currentBackStackEntry
-                        ?.destination?.hasRoute(destination.route::class) == true
-
-                    NavigationBarItem(
-                        selected = isSelected,
-                        onClick = {
-                            navController.navigate(destination.route) {
-                                popUpTo(navController.graph.findStartDestination().id) {
-                                    saveState = true
-                                }
-                                launchSingleTop = true
-                                restoreState = true
-                            }
-                        },
-                        icon = {
-                            Icon(destination.icon, contentDescription = destination.label)
-                        },
-                        label = { Text(destination.label) },
-                    )
-                }
-            }
-        },
-    ) { innerPadding ->
-        NavHost(
-            navController = navController,
-            startDestination = HomeRoute,
-            modifier = Modifier.padding(innerPadding),
-        ) {
-            composable<HomeRoute> { HomeScreen() }
-            composable<SearchRoute> { SearchScreen() }
-            composable<ProfileRoute> { ProfileScreen() }
-        }
-    }
-}
-```
+Code: [Bottom Navigation](references/code-examples.md#bottom-navigation).
 
 Key points for bottom nav:
 - Use `saveState = true` and `restoreState = true` to preserve tab back stacks
@@ -498,3 +435,7 @@ fun EditScreen(
 - [ ] Predictive back is enabled in manifest for Android 14+
 - [ ] Nested graphs use `navigation<>()` with explicit start destination
 - [ ] No navigation calls inside composable body without guard
+
+## References
+
+- [Code examples](references/code-examples.md): open for the full code behind Bottom Navigation.