@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/skills/shared/external/core-data/SKILL.md

@@ -0,0 +1,496 @@
+---
+name: core-data
+description: "Build, review, or improve Core Data persistence in apps that have not adopted SwiftData. Use when working with NSManagedObject subclasses, NSFetchedResultsController for list-driven UI, NSBatchInsertRequest / NSBatchDeleteRequest / NSBatchUpdateRequest for bulk operations, NSPersistentHistoryChangeRequest for persistent history tracking and multi-target sync, NSStagedMigrationManager for staged schema migrations (iOS 17+), NSCompositeAttributeDescription for composite attributes (iOS 17+), or when integrating Core Data threading with Swift Concurrency. For Core Data + SwiftData coexistence or migration, see the swiftdata skill instead."
+---
+
+# Core Data
+
+Build and maintain data persistence using Core Data for apps that have not
+adopted SwiftData. Covers stack setup, concurrency, batch operations,
+NSFetchedResultsController, persistent history tracking, staged migration,
+and testing.
+
+## Contents
+
+- [Stack Setup](#stack-setup)
+- [Concurrency and Threading](#concurrency-and-threading)
+- [NSFetchedResultsController](#nsfetchedresultscontroller)
+- [Batch Operations](#batch-operations)
+- [Persistent History Tracking](#persistent-history-tracking)
+- [Staged Migration](#staged-migration)
+- [Composite Attributes](#composite-attributes)
+- [SwiftData Boundary](#swiftdata-boundary)
+- [Testing](#testing)
+- [Common Mistakes](#common-mistakes)
+- [Review Checklist](#review-checklist)
+- [References](#references)
+
+## Stack Setup
+
+`NSPersistentContainer` encapsulates the Core Data stack.
+
+Docs: [NSPersistentContainer](https://sosumi.ai/documentation/coredata/nspersistentcontainer)
+
+```swift
+import CoreData
+
+final class CoreDataStack: @unchecked Sendable {
+    static let shared = CoreDataStack()
+
+    let container: NSPersistentContainer
+
+    private init() {
+        container = NSPersistentContainer(name: "MyAppModel")
+        container.loadPersistentStores { _, error in
+            if let error { fatalError("Core Data store failed: \(error)") }
+        }
+        container.viewContext.automaticallyMergesChangesFromParent = true
+        container.viewContext.mergePolicy = NSMergeByPropertyObjectTrumpMergePolicy
+    }
+
+    var viewContext: NSManagedObjectContext { container.viewContext }
+
+    func newBackgroundContext() -> NSManagedObjectContext {
+        container.newBackgroundContext()
+    }
+}
+```
+
+For CloudKit sync, use `NSPersistentCloudKitContainer` instead.
+
+## Concurrency and Threading
+
+Core Data contexts are bound to queues. The `viewContext` is on the main queue;
+background contexts operate on private queues.
+
+Docs: [NSManagedObjectContext](https://sosumi.ai/documentation/coredata/nsmanagedobjectcontext)
+
+**Rules:**
+- Always use `perform(_:)` or `performAndWait(_:)` when accessing a context
+  off its own queue.
+- Never pass `NSManagedObject` instances across context or thread boundaries.
+  Pass `NSManagedObjectID` instead and re-fetch.
+- Set `automaticallyMergesChangesFromParent = true` on the `viewContext`.
+
+```swift
+// Writing on a background context
+func updateTrip(id: NSManagedObjectID, newName: String) async throws {
+    let context = CoreDataStack.shared.newBackgroundContext()
+    try await context.perform {
+        guard let trip = try context.existingObject(with: id) as? CDTrip else {
+            throw PersistenceError.notFound
+        }
+        trip.name = newName
+        try context.save()
+    }
+}
+```
+
+### Swift Concurrency Integration
+
+`NSManagedObjectContext.perform(_:)` has an `async throws` overload
+(iOS 15+). Avoid marking `NSManagedObject` subclasses as `Sendable`.
+
+```swift
+func importItems(_ records: [ItemRecord]) async throws {
+    let context = CoreDataStack.shared.newBackgroundContext()
+    try await context.perform {
+        for record in records {
+            let item = CDItem(context: context)
+            item.id = record.id
+            item.title = record.title
+        }
+        try context.save()
+    }
+    // After save completes, viewContext auto-merges if configured
+}
+```
+
+**Do not use `@unchecked Sendable` on managed objects.** If you need
+cross-boundary communication, pass the `objectID` (which is `Sendable`)
+and re-fetch:
+
+```swift
+let objectID = trip.objectID  // Sendable
+Task.detached {
+    let bgContext = CoreDataStack.shared.newBackgroundContext()
+    try await bgContext.perform {
+        let trip = try bgContext.existingObject(with: objectID) as! CDTrip
+        trip.isFavorite = true
+        try bgContext.save()
+    }
+}
+```
+
+## NSFetchedResultsController
+
+Efficiently drives `UITableView` / `UICollectionView` from a Core Data fetch
+request, with built-in change tracking and optional caching.
+
+Docs: [NSFetchedResultsController](https://sosumi.ai/documentation/coredata/nsfetchedresultscontroller)
+
+```swift
+import CoreData
+import UIKit
+
+class TripsViewController: UITableViewController, NSFetchedResultsControllerDelegate {
+
+    private lazy var fetchedResultsController: NSFetchedResultsController<CDTrip> = {
+        let request: NSFetchRequest<CDTrip> = CDTrip.fetchRequest()
+        request.sortDescriptors = [
+            NSSortDescriptor(keyPath: \CDTrip.startDate, ascending: false)
+        ]
+        request.fetchBatchSize = 20
+
+        let controller = NSFetchedResultsController(
+            fetchRequest: request,
+            managedObjectContext: CoreDataStack.shared.viewContext,
+            sectionNameKeyPath: nil,
+            cacheName: "TripsCache"
+        )
+        controller.delegate = self
+        return controller
+    }()
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        try? fetchedResultsController.performFetch()
+    }
+
+    // MARK: - UITableViewDataSource
+
+    override func numberOfSections(in tableView: UITableView) -> Int {
+        fetchedResultsController.sections?.count ?? 0
+    }
+
+    override func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
+        fetchedResultsController.sections?[section].numberOfObjects ?? 0
+    }
+
+    override func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
+        let cell = tableView.dequeueReusableCell(withIdentifier: "TripCell", for: indexPath)
+        let trip = fetchedResultsController.object(at: indexPath)
+        cell.textLabel?.text = trip.name
+        return cell
+    }
+
+    // MARK: - NSFetchedResultsControllerDelegate (diffable)
+
+    func controller(
+        _ controller: NSFetchedResultsController<any NSFetchRequestResult>,
+        didChangeContentWith snapshot: NSDiffableDataSourceSnapshotReference
+    ) {
+        let snapshot = snapshot as NSDiffableDataSourceSnapshot<String, NSManagedObjectID>
+        dataSource.apply(snapshot, animatingDifferences: true)
+    }
+}
+```
+
+**Key points:**
+- The fetch request **must** have at least one sort descriptor.
+- Call `deleteCache(withName:)` before changing the fetch request predicate or
+  sort descriptors, or set `cacheName` to `nil`.
+- The diffable snapshot delegate method (`didChangeContentWith:`) is available
+  iOS 13+ and is preferred over the older per-change callbacks.
+- After a context `reset()`, call `performFetch()` again.
+
+## Batch Operations
+
+Batch operations execute at the SQL level, bypassing the managed object
+context. They are fast but don't trigger context notifications automatically.
+
+### NSBatchInsertRequest (iOS 13+)
+
+Docs: [NSBatchInsertRequest](https://sosumi.ai/documentation/coredata/nsbatchinsertrequest)
+
+```swift
+func batchImport(_ records: [[String: Any]]) async throws {
+    let context = CoreDataStack.shared.newBackgroundContext()
+    try await context.perform {
+        let request = NSBatchInsertRequest(
+            entity: CDTrip.entity(),
+            objects: records
+        )
+        request.resultType = .objectIDs
+        let result = try context.execute(request) as? NSBatchInsertResult
+        if let ids = result?.result as? [NSManagedObjectID] {
+            NSManagedObjectContext.mergeChanges(
+                fromRemoteContextSave: [NSInsertedObjectsKey: ids],
+                into: [CoreDataStack.shared.viewContext]
+            )
+        }
+    }
+}
+```
+
+### NSBatchDeleteRequest (iOS 9+)
+
+Docs: [NSBatchDeleteRequest](https://sosumi.ai/documentation/coredata/nsbatchdeleterequest)
+
+```swift
+func deleteOldTrips(before cutoff: Date) async throws {
+    let context = CoreDataStack.shared.newBackgroundContext()
+    try await context.perform {
+        let fetchRequest: NSFetchRequest<NSFetchRequestResult> = CDTrip.fetchRequest()
+        fetchRequest.predicate = NSPredicate(format: "endDate < %@", cutoff as NSDate)
+        let request = NSBatchDeleteRequest(fetchRequest: fetchRequest)
+        request.resultType = .resultTypeObjectIDs
+        let result = try context.execute(request) as? NSBatchDeleteResult
+        if let ids = result?.result as? [NSManagedObjectID] {
+            NSManagedObjectContext.mergeChanges(
+                fromRemoteContextSave: [NSDeletedObjectsKey: ids],
+                into: [CoreDataStack.shared.viewContext]
+            )
+        }
+    }
+}
+```
+
+### NSBatchUpdateRequest (iOS 8+)
+
+```swift
+func markAllTripsAsNotFavorite() async throws {
+    let context = CoreDataStack.shared.newBackgroundContext()
+    try await context.perform {
+        let request = NSBatchUpdateRequest(entity: CDTrip.entity())
+        request.propertiesToUpdate = ["isFavorite": false]
+        request.resultType = .updatedObjectIDsResultType
+        let result = try context.execute(request) as? NSBatchUpdateResult
+        if let ids = result?.result as? [NSManagedObjectID] {
+            NSManagedObjectContext.mergeChanges(
+                fromRemoteContextSave: [NSUpdatedObjectsKey: ids],
+                into: [CoreDataStack.shared.viewContext]
+            )
+        }
+    }
+}
+```
+
+**Always merge changes** back into relevant contexts after batch operations.
+Batch delete does not enforce the Deny delete rule.
+
+## Persistent History Tracking
+
+Track store-level changes across targets (app, extensions, widgets) and
+processes.
+
+Docs: [NSPersistentHistoryChangeRequest](https://sosumi.ai/documentation/coredata/nspersistenthistorychangerequest)
+
+### Enable History Tracking
+
+```swift
+let description = NSPersistentStoreDescription()
+description.setOption(true as NSNumber, forKey: NSPersistentHistoryTrackingKey)
+description.setOption(true as NSNumber,
+    forKey: NSPersistentStoreRemoteChangeNotificationPostOptionKey)
+container.persistentStoreDescriptions = [description]
+```
+
+### Observe, Fetch, Merge, and Purge
+
+```swift
+// 1. Observe remote change notifications
+NotificationCenter.default.addObserver(
+    self, selector: #selector(storeRemoteChange(_:)),
+    name: .NSPersistentStoreRemoteChange, object: container.persistentStoreCoordinator
+)
+
+// 2. Fetch history since last token
+@objc func storeRemoteChange(_ notification: Notification) {
+    let context = container.newBackgroundContext()
+    context.perform {
+        let request = NSPersistentHistoryChangeRequest.fetchHistory(after: self.lastToken)
+        if let result = try? context.execute(request) as? NSPersistentHistoryResult,
+           let transactions = result.result as? [NSPersistentHistoryTransaction] {
+            // 3. Merge into viewContext
+            for transaction in transactions {
+                self.container.viewContext.mergeChanges(fromContextDidSave: transaction.objectIDNotification())
+                self.lastToken = transaction.token
+            }
+        }
+        // 4. Purge old history
+        let purgeRequest = NSPersistentHistoryChangeRequest.deleteHistory(before: self.lastToken)
+        try? context.execute(purgeRequest)
+    }
+}
+```
+
+Store `lastToken` in `UserDefaults` (per target) so history is processed
+correctly across launches.
+
+## Staged Migration
+
+`NSStagedMigrationManager` (iOS 17+) sequences schema migrations through
+ordered stages, each lightweight or custom.
+
+Docs: [NSStagedMigrationManager](https://sosumi.ai/documentation/coredata/nsstagedmigrationmanager)
+
+```swift
+import CoreData
+
+// Define migration stages
+// Use version checksums from the compiled model versions, not model names.
+let checksumV1 = "<ModelV1 version checksum>"
+let checksumV2 = "<ModelV2 version checksum>"
+let checksumV3 = "<ModelV3 version checksum>"
+let stage1to2 = NSLightweightMigrationStage([checksumV1, checksumV2])
+stage1to2.label = "Add isFavorite property"
+
+let modelV2 = NSManagedObjectModelReference(
+    name: "ModelV2",
+    in: Bundle.main,
+    versionChecksum: checksumV2
+)
+let modelV3 = NSManagedObjectModelReference(
+    name: "ModelV3",
+    in: Bundle.main,
+    versionChecksum: checksumV3
+)
+let stage2to3 = NSCustomMigrationStage(
+    migratingFrom: modelV2,
+    to: modelV3
+)
+stage2to3.label = "Split name into firstName/lastName"
+stage2to3.willMigrateHandler = { migrationManager, currentStage in
+    guard let container = migrationManager.container else { return }
+    let context = container.newBackgroundContext()
+    try context.performAndWait {
+        // Transform data between schema versions
+        let request = NSFetchRequest<NSManagedObject>(entityName: "Person")
+        let people = try context.fetch(request)
+        for person in people {
+            let fullName = person.value(forKey: "name") as? String ?? ""
+            let parts = fullName.split(separator: " ", maxSplits: 1)
+            person.setValue(String(parts.first ?? ""), forKey: "firstName")
+            person.setValue(parts.count > 1 ? String(parts.last!) : "", forKey: "lastName")
+        }
+        try context.save()
+    }
+}
+
+// Apply to the persistent store
+let manager = NSStagedMigrationManager([stage1to2, stage2to3])
+let description = NSPersistentStoreDescription()
+description.setOption(manager,
+    forKey: NSPersistentStoreStagedMigrationManagerOptionKey)
+container.persistentStoreDescriptions = [description]
+container.loadPersistentStores { _, error in
+    if let error { fatalError("Migration failed: \(error)") }
+}
+```
+
+For apps targeting below iOS 17, use lightweight migration
+(`NSInferMappingModelAutomaticallyOption`) or mapping models.
+
+`NSLightweightMigrationStage` takes **version checksums** (`[String]`), not
+human-readable model names.
+
+## Composite Attributes
+
+iOS 17+ supports composite attributes: groups of sub-attributes on an entity
+that act as a single logical unit. Define them in the model editor by adding a
+Composite type attribute and nesting sub-attributes beneath it.
+
+Docs: [NSCompositeAttributeDescription](https://sosumi.ai/documentation/coredata/nscompositeattributedescription)
+
+Composite attributes map to `Codable` structs in SwiftData coexistence
+scenarios.
+
+## SwiftData Boundary
+
+Use the `swiftdata` skill for Core Data + SwiftData coexistence or migration
+implementation. Before handing off, preserve these Core Data boundaries:
+
+- SwiftData must point at the existing persistent store URL when it is meant to
+  share or migrate Core Data data.
+- Shared persisted data must keep entity names, property names, types, and
+  schema compatible across the Core Data model and SwiftData `@Model` classes.
+- Map renamed persisted properties with SwiftData `@Attribute(originalName:)`.
+
+## Testing
+
+### In-Memory Store for Tests
+
+```swift
+import CoreData
+import Testing
+
+struct CoreDataTests {
+    func makeTestContainer() throws -> NSPersistentContainer {
+        let container = NSPersistentContainer(name: "MyAppModel")
+        let description = NSPersistentStoreDescription()
+        description.type = NSInMemoryStoreType
+        container.persistentStoreDescriptions = [description]
+
+        var loadError: Error?
+        container.loadPersistentStores { _, error in loadError = error }
+        if let loadError { throw loadError }
+        return container
+    }
+
+    @Test func createAndFetchTrip() throws {
+        let container = try makeTestContainer()
+        let context = container.viewContext
+
+        let trip = CDTrip(context: context)
+        trip.name = "Test Trip"
+        trip.startDate = .now
+        try context.save()
+
+        let request: NSFetchRequest<CDTrip> = CDTrip.fetchRequest()
+        let trips = try context.fetch(request)
+        #expect(trips.count == 1)
+        #expect(trips.first?.name == "Test Trip")
+    }
+}
+```
+
+**Tips:**
+- Share the `NSManagedObjectModel` instance across tests to avoid "duplicate
+  entity" warnings.
+- Use a single shared model loaded once:
+
+```swift
+private let sharedModel: NSManagedObjectModel = {
+    let url = Bundle.main.url(forResource: "MyAppModel", withExtension: "momd")!
+    return NSManagedObjectModel(contentsOf: url)!
+}()
+
+func makeTestContainer() throws -> NSPersistentContainer {
+    let container = NSPersistentContainer(name: "MyAppModel",
+                                          managedObjectModel: sharedModel)
+    // ... configure in-memory store
+}
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Passing `NSManagedObject` across threads | Pass `objectID` and re-fetch in the target context |
+| Forgetting to merge batch operation results | Call `mergeChanges(fromRemoteContextSave:into:)` |
+| Calling `save()` without checking `hasChanges` | Guard with `context.hasChanges` first |
+| Using deprecated `init(concurrencyType:)` confinement type | Use `.privateQueueConcurrencyType` or `.mainQueueConcurrencyType` |
+| Not setting `mergePolicy` on `viewContext` | Set `NSMergeByPropertyObjectTrumpMergePolicy` to avoid conflict crashes |
+| Modifying fetch request on live `NSFetchedResultsController` without deleting cache | Call `deleteCache(withName:)` first or use `cacheName: nil` |
+| Batch delete ignoring Deny delete rule | Batch delete bypasses delete rules; validate manually |
+| Marking `NSManagedObject` as `@unchecked Sendable` | Do not. Pass `objectID` instead |
+| Pointing SwiftData at a fresh store during coexistence | Use the existing store URL and compatible schema when SwiftData should share or migrate Core Data data |
+
+## Review Checklist
+
+- [ ] `NSPersistentContainer` is initialized once and shared
+- [ ] `viewContext` used only on main queue; background contexts for writes
+- [ ] `perform(_:)` or `performAndWait(_:)` wraps all off-queue context access
+- [ ] `automaticallyMergesChangesFromParent` set on `viewContext`
+- [ ] `mergePolicy` set on `viewContext` to prevent conflict crashes
+- [ ] Batch operation results merged into relevant contexts
+- [ ] `NSFetchedResultsController` fetch requests have sort descriptors
+- [ ] Persistent history tracking enabled for multi-target apps
+- [ ] Core Data + SwiftData handoff preserves store URL, schema compatibility, entity/property names, and rename mappings
+- [ ] Tests use in-memory stores with shared `NSManagedObjectModel`
+- [ ] No `NSManagedObject` instances cross thread boundaries
+
+## References
+
+- Apple docs: [Core Data](https://sosumi.ai/documentation/coredata) | [NSPersistentContainer](https://sosumi.ai/documentation/coredata/nspersistentcontainer) | [NSFetchedResultsController](https://sosumi.ai/documentation/coredata/nsfetchedresultscontroller) | [NSStagedMigrationManager](https://sosumi.ai/documentation/coredata/nsstagedmigrationmanager)

package/pipeline/skills/shared/external/core-data/evals/evals.json

@@ -0,0 +1,44 @@
+{
+  "skill_name": "core-data",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Review this Core Data staged migration plan for an iOS 26 app: the team creates NSLightweightMigrationStage([\"ModelV1\", \"ModelV2\"]), constructs NSManagedObjectModelReference(named: \"ModelV2\", in: .main), and expects NSStagedMigrationManager to run without wiring it into the persistent store description. Give concise corrected guidance with Swift where useful.",
+      "expected_output": "A review that corrects staged migration checksum usage, NSManagedObjectModelReference initializer requirements, and store-description wiring.",
+      "files": [],
+      "assertions": [
+        "States that NSLightweightMigrationStage takes version checksums, not human-readable model names.",
+        "Uses NSManagedObjectModelReference(name:in:versionChecksum:) or an equivalent initializer with a versionChecksum.",
+        "Includes source and destination model references for an NSCustomMigrationStage.",
+        "Shows or describes setting NSPersistentStoreStagedMigrationManagerOptionKey before loading the persistent stores."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Review this Core Data multi-target sync plan: a widget and app share a SQLite store, batch inserts and deletes run on background contexts, the viewContext never merges SQL-level changes, no persistent history token is stored, and objects are passed directly to detached tasks. Explain what to fix.",
+      "expected_output": "A review that fixes batch-operation merging, persistent history tracking, token storage, and object/thread boundaries.",
+      "files": [],
+      "assertions": [
+        "Explains that batch inserts, updates, and deletes bypass normal managed-object context change tracking and must be merged or consumed through persistent history.",
+        "Recommends enabling NSPersistentHistoryTrackingKey for multi-target or multi-process stores.",
+        "Recommends observing NSPersistentStoreRemoteChange notifications when remote-change delivery is needed.",
+        "States that each target or consumer should persist its own persistent history token.",
+        "States that NSManagedObject instances must not cross context or thread boundaries; pass NSManagedObjectID and re-fetch.",
+        "Mentions that batch delete bypasses validation beyond basic delete rules and is incompatible with the Deny delete rule."
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "A team asks for a Core Data plan, but the real request is to run Core Data and SwiftData side by side against the same existing SQLite store and then migrate new screens to @Model. How should the agent route the work and what high-level boundary guidance should it give?",
+      "expected_output": "A boundary answer that identifies Core Data + SwiftData coexistence/migration as SwiftData-owned while giving only high-level handoff guidance.",
+      "files": [],
+      "assertions": [
+        "States that Core Data + SwiftData coexistence or migration should use the swiftdata skill.",
+        "Avoids turning the Core Data skill into a full SwiftData migration guide.",
+        "Gives high-level boundary guidance such as matching store URL, entity names, property names, and schema.",
+        "Mentions using @Attribute(originalName:) or equivalent rename mapping for renamed properties.",
+        "Preserves standalone Core Data guidance for apps that have not adopted SwiftData."
+      ]
+    }
+  ]
+}

package/pipeline/skills/shared/external/core-motion/SKILL.md

@@ -1,14 +1,15 @@
 ---
 name: core-motion
-description: "Access accelerometer, gyroscope, magnetometer, pedometer, and activity-recognition data using CoreMotion. Use when reading device sensor data, counting steps, detecting user activity (walking/running/driving), tracking altitude changes, or implementing motion-based interactions in iOS/watchOS apps."
+description: "Access Core Motion accelerometer, gyroscope, magnetometer, device-motion, pedometer, activity-recognition, altitude, headphone motion, batched high-frequency workout motion, and water-submersion/depth data. Use when reading device sensors, counting steps, detecting walking/running/driving/cycling, tracking altitude, building motion interactions, handling AirPods head tracking, or implementing watchOS dive/depth features."
 ---
 
 # CoreMotion
 
-Read device sensor data -- accelerometer, gyroscope, magnetometer, pedometer, and
-activity recognition -- on iOS and watchOS. CoreMotion fuses raw sensor inputs into
-processed device-motion data and provides pedometer/activity APIs for fitness and
-navigation use cases. Targets Swift 6.2 / iOS 26+.
+Read device sensor data -- accelerometer, gyroscope, magnetometer, pedometer,
+activity recognition, altitude, headphone motion, batched motion, and submersion
+depth -- on iOS and watchOS. CoreMotion fuses raw sensor inputs into processed
+device-motion data and provides pedometer/activity APIs for fitness and
+navigation use cases. Targets Swift 6.3 / iOS 26+.
 
 ## Contents
 
@@ -37,9 +38,12 @@ why your app needs motion data. Without this key, the app crashes on first acces
 
 ### Authorization
 
-CoreMotion uses `CMAuthorizationStatus` for pedometer and activity APIs. Sensor
-APIs (accelerometer, gyro) do not require explicit authorization but do require
-the usage description key.
+Use the matching manager's `authorizationStatus()` or `authorizationStatus`
+property when an API exposes one (`CMPedometer`, `CMMotionActivityManager`,
+`CMAltimeter`, headphone motion, batched sensors, and submersion). Raw
+`CMMotionManager` accelerometer/gyro/device-motion streams have no explicit
+authorization request API; still ship the usage string and handle errors from
+start/update callbacks.
 
 ```swift
 import CoreMotion
@@ -121,13 +125,22 @@ Device motion fuses accelerometer, gyroscope, and magnetometer into a single
 `CMDeviceMotion` object with attitude, user acceleration (gravity removed),
 rotation rate, and calibrated magnetic field.
 
+When giving device-motion guidance, show the runtime frame check in the snippet
+instead of hard-coding a corrected, magnetic-north, or true-north frame. Fall
+back to `.xArbitraryZVertical` when the preferred frame is unavailable.
+
 ```swift
 guard motionManager.isDeviceMotionAvailable else { return }
 
+let availableFrames = CMMotionManager.availableAttitudeReferenceFrames()
+let frame: CMAttitudeReferenceFrame = availableFrames.contains(.xArbitraryCorrectedZVertical)
+    ? .xArbitraryCorrectedZVertical
+    : .xArbitraryZVertical
+
 motionManager.deviceMotionUpdateInterval = 1.0 / 60.0
 
 motionManager.startDeviceMotionUpdates(
-    using: .xArbitraryZVertical,
+    using: frame,
     to: .main
 ) { motion, error in
     guard let motion else { return }
@@ -135,7 +148,7 @@ motionManager.startDeviceMotionUpdates(
     let attitude = motion.attitude       // roll, pitch, yaw
     let userAccel = motion.userAcceleration
     let gravity = motion.gravity
-    let heading = motion.heading         // 0-360 degrees (requires magnetometer)
+    let heading = motion.heading         // degrees relative to the current frame
 
     print("Pitch: \(attitude.pitch), Roll: \(attitude.roll)")
 }
@@ -145,6 +158,12 @@ motionManager.stopDeviceMotionUpdates()
 
 ### Attitude Reference Frames
 
+For simple tilt controls, use `.xArbitraryZVertical` or
+`.xArbitraryCorrectedZVertical`; they avoid magnetometer/location dependencies.
+Before requesting corrected, magnetic-north, or true-north frames, call
+`CMMotionManager.availableAttitudeReferenceFrames()` and fall back to an
+available frame.
+
 | Frame | Use Case |
 |---|---|
 | `.xArbitraryZVertical` | Default. Z is vertical, X arbitrary at start. Most games. |
@@ -249,6 +268,9 @@ activityManager.queryActivityStarting(
 
 ## CMAltimeter: Altitude Data
 
+Altimeter access is covered by `NSMotionUsageDescription`; handle denied motion
+access through unavailable data and update-handler errors.
+
 ```swift
 let altimeter = CMAltimeter()
 
@@ -263,7 +285,10 @@ altimeter.startRelativeAltitudeUpdates(to: .main) { data, error in
 altimeter.stopRelativeAltitudeUpdates()
 ```
 
-For absolute altitude (GPS-based):
+Absolute altitude is altitude relative to sea level, not GPS-based altitude.
+First check availability. Absolute altitude is available only on supported
+hardware such as iPhone 12 or later and Apple Watch Series 6, Apple Watch SE, or
+later.
 
 ```swift
 guard CMAltimeter.isAbsoluteAltitudeAvailable() else { return }
@@ -285,8 +310,11 @@ altimeter.stopAbsoluteAltitudeUpdates()
 | `1.0 / 60.0` | 60 | Action games | High |
 | `1.0 / 100.0` | 100 | Max rate (iPhone) | Very High |
 
-Use the lowest frequency that meets your needs. `CMMotionManager` caps at 100 Hz
-per sample. For higher frequencies, use `CMBatchedSensorManager` on watchOS/iOS 17+.
+Use the lowest frequency that meets your needs. Do not assume a fixed maximum
+sample rate across devices. For high-frequency workout motion, use
+`CMBatchedSensorManager` where supported and read its reported
+`accelerometerDataFrequency` or `deviceMotionDataFrequency` instead of assigning
+those read-only properties.
 
 ## Common Mistakes
 
@@ -373,16 +401,21 @@ if activity.walking && activity.confidence == .high {
 - [ ] Handlers dispatched to appropriate queues (not blocking main for heavy processing)
 - [ ] `CMMotionActivity.confidence` checked before acting on activity type
 - [ ] Error parameters checked in update handlers
+- [ ] Device-motion snippets call `CMMotionManager.availableAttitudeReferenceFrames()` before requesting a specific attitude frame
 - [ ] Attitude reference frame chosen based on actual need (not defaulting to true north unnecessarily)
 
 ## References
 
-- Extended patterns (SwiftUI integration, batched sensor manager, headphone motion): `references/motion-patterns.md`
+- Extended patterns (SwiftUI integration, batched sensor manager, headphone motion, water submersion): [references/motion-patterns.md](references/motion-patterns.md)
 - [CoreMotion framework](https://sosumi.ai/documentation/coremotion)
 - [CMMotionManager](https://sosumi.ai/documentation/coremotion/cmmotionmanager)
 - [CMPedometer](https://sosumi.ai/documentation/coremotion/cmpedometer)
 - [CMMotionActivityManager](https://sosumi.ai/documentation/coremotion/cmmotionactivitymanager)
 - [CMDeviceMotion](https://sosumi.ai/documentation/coremotion/cmdevicemotion)
 - [CMAltimeter](https://sosumi.ai/documentation/coremotion/cmaltimeter)
+- [CMAbsoluteAltitudeData](https://sosumi.ai/documentation/coremotion/cmabsolutealtitudedata)
 - [CMBatchedSensorManager](https://sosumi.ai/documentation/coremotion/cmbatchedsensormanager)
+- [CMHeadphoneMotionManager](https://sosumi.ai/documentation/coremotion/cmheadphonemotionmanager)
+- [CMWaterSubmersionManager](https://sosumi.ai/documentation/coremotion/cmwatersubmersionmanager)
+- [Accessing submersion data](https://sosumi.ai/documentation/coremotion/accessing-submersion-data)
 - [Getting processed device-motion data](https://sosumi.ai/documentation/coremotion/getting-processed-device-motion-data)