@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

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

@@ -1,498 +1,348 @@
 ---
 name: core-bluetooth
-description: "Build direct Bluetooth Low Energy workflows with Core Bluetooth. Use when implementing BLE central or peripheral GATT communication, scanning or connecting with CBCentralManager, discovering services and characteristics, reading/writing/subscribing with CBPeripheral, publishing local services with CBPeripheralManager, handling Bluetooth authorization, background BLE modes, state restoration, write flow control, or CBUUID-based workflows. For privacy-preserving accessory setup/picker flows, use accessorysetupkit first and return here for post-setup GATT communication."
+description: "Direct BLE with Core Bluetooth: central and peripheral GATT communication, CBCentralManager scanning and connecting, service and characteristic discovery, CBPeripheral reads, writes and subscriptions, CBPeripheralManager local services, Bluetooth authorization, background BLE modes, state restoration, write flow control, CBUUID workflows. Use when an app talks to BLE accessories or acts as one. Not for privacy-preserving accessory setup or picker flows: AccessorySetupKit first, then GATT here."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
 # Core Bluetooth
 
-Scan for, connect to, and exchange data with Bluetooth Low Energy (BLE) devices.
-Covers the central role (scanning and connecting to peripherals), the peripheral
-role (advertising services), background modes, and state restoration.
-Targets Swift 6.3 / iOS 26+.
-Use `accessorysetupkit` for privacy-preserving accessory discovery and setup;
-use this skill for direct Core Bluetooth GATT communication.
-
-## Contents
-
-- [Setup](#setup)
-- [Central Role: Scanning](#central-role-scanning)
-- [Central Role: Connecting](#central-role-connecting)
-- [Discovering Services and Characteristics](#discovering-services-and-characteristics)
-- [Reading, Writing, and Notifications](#reading-writing-and-notifications)
-- [Peripheral Role: Advertising](#peripheral-role-advertising)
-- [Background BLE](#background-ble)
-- [State Restoration](#state-restoration)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+Core Bluetooth lets an app act as a BLE **central** (scan, connect, read and
+write another device) or as a **peripheral** (publish services others connect
+to). This skill covers both roles, background modes and state restoration, for
+Swift 6.3 and iOS 26.
+
+Finding and pairing an accessory through the system picker, without broad
+Bluetooth permission, is AccessorySetupKit's job. Once the user has picked the
+accessory, the GATT conversation (services, characteristics, reads, writes,
+notifications) happens here.
 
 ## Setup
 
-### Info.plist Keys
+### Info.plist
 
 | Key | Purpose |
-|---|---|
-| `NSBluetoothAlwaysUsageDescription` | Required. Explains why the app uses Bluetooth |
-| `UIBackgroundModes` with `bluetooth-central` | Background scanning and connecting |
-| `UIBackgroundModes` with `bluetooth-peripheral` | Background advertising |
+|-----|---------|
+| `NSBluetoothAlwaysUsageDescription` | Required. Tells the user why the app uses Bluetooth |
+| `UIBackgroundModes` with `bluetooth-central` | Scan and stay connected in the background |
+| `UIBackgroundModes` with `bluetooth-peripheral` | Advertise and serve in the background |
 
-### Bluetooth Authorization
+### Permission and power state
 
-Core Bluetooth has no explicit permission request API. Add
-`NSBluetoothAlwaysUsageDescription`, create the manager when the app is ready for
-Bluetooth access, then check `manager.authorization` and `manager.state`.
-Treat `.denied` and `.restricted` as terminal until the user changes Settings;
-wait for `.poweredOn` before scanning, connecting, advertising, or publishing
-services.
+There is no "request Bluetooth permission" call. The system asks the first
+time the app creates a manager, so create one only when the user reaches the
+feature that needs it. Then look at two things:
 
-## Central Role: Scanning
+- `manager.authorization`: `.denied` and `.restricted` stay that way until the
+  user changes Settings, so show guidance rather than retrying.
+- `manager.state`: do nothing (scan, connect, advertise, add services) until it
+  is `.poweredOn`.
 
-### Creating the Central Manager
+## Central role
 
-Always wait for the `poweredOn` state before scanning.
+### Scanning
 
 ```swift
 import CoreBluetooth
 
-final class BluetoothManager: NSObject, CBCentralManagerDelegate {
-    private var centralManager: CBCentralManager!
-    private var discoveredPeripheral: CBPeripheral?
+final class ScaleLink: NSObject, CBCentralManagerDelegate {
+    static var weightService: CBUUID { CBUUID(string: "181D") }
+
+    private var central: CBCentralManager!
+    private var scale: CBPeripheral?
 
     override init() {
         super.init()
-        centralManager = CBCentralManager(delegate: self, queue: nil)
+        central = CBCentralManager(delegate: self, queue: nil)
     }
 
     func centralManagerDidUpdateState(_ central: CBCentralManager) {
         guard central.state == .poweredOn else { return }
-        startScanning()
+        central.scanForPeripherals(
+            withServices: [Self.weightService],
+            options: [CBCentralManagerScanOptionAllowDuplicatesKey: false]
+        )
+    }
+
+    func centralManager(_ central: CBCentralManager, didDiscover found: CBPeripheral,
+                        advertisementData: [String: Any], rssi: NSNumber) {
+        guard rssi.intValue > -75 else { return }
+        scale = found
+        central.stopScan()
+        central.connect(found)
     }
 }
 ```
 
-### Scanning for Peripherals
+- Scan for the service UUIDs you care about. `withServices: nil` finds
+  everything, burns battery and has no place in a shipping app.
+- Ignoring weak signals (here anything at or below -75 dBm) is optional.
+- Keep a strong reference to the discovered `CBPeripheral`. Core Bluetooth
+  does not, and a released peripheral silently never connects.
+- Stop scanning as soon as the target turns up, then connect.
 
-Scan for specific service UUIDs to save power. Pass `nil` to discover all
-peripherals (not recommended in production).
+The implicitly unwrapped `central` exists only because `self` must be fully
+initialized before it can be the delegate. `CBUUID` is not `Sendable`, and
+Swift 6 rejects a stored `static let` of it on a type without actor isolation,
+so the UUIDs are computed static properties. A `@MainActor` type can keep
+stored ones, as the SwiftUI monitor in the reference does.
 
-```swift
-let heartRateServiceUUID = CBUUID(string: "180D")
-
-func startScanning() {
-    centralManager.scanForPeripherals(
-        withServices: [heartRateServiceUUID],
-        options: [CBCentralManagerScanOptionAllowDuplicatesKey: false]
-    )
-}
-
-func centralManager(
-    _ central: CBCentralManager,
-    didDiscover peripheral: CBPeripheral,
-    advertisementData: [String: Any],
-    rssi RSSI: NSNumber
-) {
-    guard RSSI.intValue > -70 else { return } // Filter weak signals
-
-    // IMPORTANT: Retain the peripheral -- it will be deallocated otherwise
-    discoveredPeripheral = peripheral
-    centralManager.stopScan()
-    centralManager.connect(peripheral, options: nil)
-}
-```
-
-## Central Role: Connecting
+### Connecting and disconnecting
 
 ```swift
-func centralManager(
-    _ central: CBCentralManager,
-    didConnect peripheral: CBPeripheral
-) {
-    peripheral.delegate = self
-    peripheral.discoverServices([heartRateServiceUUID])
-}
+extension ScaleLink {
+    func centralManager(_ central: CBCentralManager, didConnect device: CBPeripheral) {
+        device.delegate = self
+        device.discoverServices([Self.weightService])
+    }
 
-func centralManager(
-    _ central: CBCentralManager,
-    didDisconnectPeripheral peripheral: CBPeripheral,
-    timestamp: CFAbsoluteTime,
-    isReconnecting: Bool,
-    error: Error?
-) {
-    if isReconnecting {
-        // System is automatically reconnecting
-        return
+    func centralManager(_ central: CBCentralManager, didDisconnectPeripheral device: CBPeripheral,
+                        timestamp: CFAbsoluteTime, isReconnecting: Bool, error: (any Error)?) {
+        if isReconnecting { return }
+        scale = nil
     }
-    // Handle disconnection -- optionally reconnect
-    discoveredPeripheral = nil
 }
 ```
 
-## Discovering Services and Characteristics
+Set the peripheral's delegate before asking it for anything. When
+`isReconnecting` is true the system is already reconnecting on your behalf;
+otherwise decide whether to reconnect yourself and release the reference.
 
-Implement `CBPeripheralDelegate` to walk the service/characteristic tree.
+## Discovering services and characteristics
 
 ```swift
-extension BluetoothManager: CBPeripheralDelegate {
-    func peripheral(
-        _ peripheral: CBPeripheral,
-        didDiscoverServices error: Error?
-    ) {
-        guard let services = peripheral.services else { return }
-        for service in services {
-            peripheral.discoverCharacteristics(nil, for: service)
+extension ScaleLink: CBPeripheralDelegate {
+    static var weightMeasurement: CBUUID { CBUUID(string: "2A9D") }
+
+    func peripheral(_ device: CBPeripheral, didDiscoverServices error: (any Error)?) {
+        for service in device.services ?? [] {
+            device.discoverCharacteristics([Self.weightMeasurement, CBUUID(string: "2A19")], for: service)
         }
     }
 
-    func peripheral(
-        _ peripheral: CBPeripheral,
-        didDiscoverCharacteristicsFor service: CBService,
-        error: Error?
-    ) {
-        guard let characteristics = service.characteristics else { return }
-        for characteristic in characteristics {
-            if characteristic.properties.contains(.notify) {
-                peripheral.setNotifyValue(true, for: characteristic)
+    func peripheral(_ device: CBPeripheral, didDiscoverCharacteristicsFor service: CBService, error: (any Error)?) {
+        for trait in service.characteristics ?? [] {
+            if trait.properties.contains(.notify) {
+                device.setNotifyValue(true, for: trait)
             }
-            if characteristic.properties.contains(.read) {
-                peripheral.readValue(for: characteristic)
+            if trait.properties.contains(.read) {
+                device.readValue(for: trait)
             }
         }
     }
 }
 ```
 
-## Reading, Writing, and Notifications
+Check `properties` before each read, write or subscription.
 
-### Reading a Value
+## Reading, writing and notifications
+
+Reads and notifications arrive in the same callback:
 
 ```swift
-func peripheral(
-    _ peripheral: CBPeripheral,
-    didUpdateValueFor characteristic: CBCharacteristic,
-    error: Error?
-) {
-    guard let data = characteristic.value else { return }
-
-    switch characteristic.uuid {
+func peripheral(_ device: CBPeripheral, didUpdateValueFor trait: CBCharacteristic, error: (any Error)?) {
+    guard error == nil, let bytes = trait.value else { return }
+    switch trait.uuid {
     case CBUUID(string: "2A37"):
-        if let heartRate = parseHeartRate(data) {
-            print("Heart rate: \(heartRate) bpm")
-        }
+        pulse = beatsPerMinute(bytes)
     case CBUUID(string: "2A19"):
-        let batteryLevel = data.first.map { Int($0) } ?? 0
-        print("Battery: \(batteryLevel)%")
+        batteryPercent = bytes.first.map(Int.init)
     default:
         break
     }
 }
+```
 
-private func parseHeartRate(_ data: Data) -> Int? {
-    guard data.count >= 2 else { return nil }
-    let flags = data[0]
-    let is16Bit = (flags & 0x01) != 0
-    if is16Bit {
-        guard data.count >= 3 else { return nil }
-        return Int(data[1]) | (Int(data[2]) << 8)
-    } else {
-        return Int(data[1])
+Heart Rate Measurement (`2A37`) needs care with its flags byte:
+
+```swift
+func beatsPerMinute(_ bytes: Data) -> Int? {
+    guard bytes.count >= 2 else { return nil }
+    let wide = bytes[bytes.startIndex] & 0x01 != 0
+    if wide {
+        guard bytes.count >= 3 else { return nil }
+        let low = UInt16(bytes[bytes.startIndex + 1])
+        let high = UInt16(bytes[bytes.startIndex + 2])
+        return Int(low | high << 8)
     }
+    return Int(bytes[bytes.startIndex + 1])
 }
 ```
 
-### Writing a Value
+Bit 0 set means a 16-bit little-endian value in bytes 1 and 2; otherwise the
+value is the single byte 1.
+
+### Choosing a write type
 
 ```swift
-func writeValue(_ data: Data, to characteristic: CBCharacteristic,
-                on peripheral: CBPeripheral,
-                preferResponse: Bool = true) {
+func send(_ payload: Data, to trait: CBCharacteristic, on device: CBPeripheral, confirm: Bool) -> Bool {
     let type: CBCharacteristicWriteType
-    if preferResponse, characteristic.properties.contains(.write) {
+    if confirm, trait.properties.contains(.write) {
         type = .withResponse
-    } else if characteristic.properties.contains(.writeWithoutResponse),
-              peripheral.canSendWriteWithoutResponse {
+    } else if trait.properties.contains(.writeWithoutResponse), device.canSendWriteWithoutResponse {
         type = .withoutResponse
-    } else if characteristic.properties.contains(.write) {
+    } else if trait.properties.contains(.write) {
         type = .withResponse
     } else {
-        return
-    }
-
-    guard data.count <= peripheral.maximumWriteValueLength(for: type) else { return }
-    peripheral.writeValue(data, for: characteristic, type: type)
-}
-
-// Confirmation callback for .withResponse writes.
-func peripheral(
-    _ peripheral: CBPeripheral,
-    didWriteValueFor characteristic: CBCharacteristic,
-    error: Error?
-) {
-    if let error {
-        print("Write failed: \(error.localizedDescription)")
+        return false
     }
+    guard payload.count <= device.maximumWriteValueLength(for: type) else { return false }
+    device.writeValue(payload, for: trait, type: type)
+    return true
 }
-
-// Resume queued .withoutResponse writes here.
-func peripheralIsReady(toSendWriteWithoutResponse peripheral: CBPeripheral) {}
 ```
 
-### Subscribing to Notifications
+- `.withResponse` writes are confirmed in `peripheral(_:didWriteValueFor:error:)`.
+- When `canSendWriteWithoutResponse` is false, queue the data and resume in
+  `peripheralIsReady(toSendWriteWithoutResponse:)`.
+- Payloads longer than `maximumWriteValueLength(for:)` must be split.
 
-```swift
-// Subscribe
-peripheral.setNotifyValue(true, for: characteristic)
-
-// Unsubscribe
-peripheral.setNotifyValue(false, for: characteristic)
-
-// Confirmation
-func peripheral(
-    _ peripheral: CBPeripheral,
-    didUpdateNotificationStateFor characteristic: CBCharacteristic,
-    error: Error?
-) {
-    if characteristic.isNotifying {
-        print("Now receiving notifications for \(characteristic.uuid)")
-    }
-}
-```
+### Subscriptions
 
-## Peripheral Role: Advertising
+`setNotifyValue(true, for:)` subscribes and `setNotifyValue(false, for:)`
+unsubscribes. The outcome arrives in
+`peripheral(_:didUpdateNotificationStateFor:error:)`, where
+`characteristic.isNotifying` tells you the current state.
 
-Publish services from the local device using `CBPeripheralManager`.
+## Peripheral role
 
 ```swift
-final class BLEPeripheralManager: NSObject, CBPeripheralManagerDelegate {
-    private var peripheralManager: CBPeripheralManager!
-    private let serviceUUID = CBUUID(string: "12345678-1234-1234-1234-123456789ABC")
-    private let charUUID = CBUUID(string: "12345678-1234-1234-1234-123456789ABD")
+final class ThermometerBeacon: NSObject, CBPeripheralManagerDelegate {
+    static var service: CBUUID { CBUUID(string: "5E1A7D30-2C4B-4F55-9B0E-7A1C3D2E8F10") }
+    static var reading: CBUUID { CBUUID(string: "5E1A7D31-2C4B-4F55-9B0E-7A1C3D2E8F10") }
+
+    private var manager: CBPeripheralManager!
 
     override init() {
         super.init()
-        peripheralManager = CBPeripheralManager(delegate: self, queue: nil)
-    }
-
-    func peripheralManagerDidUpdateState(_ peripheral: CBPeripheralManager) {
-        guard peripheral.state == .poweredOn else { return }
-        setupService()
+        manager = CBPeripheralManager(delegate: self, queue: nil)
     }
 
-    private func setupService() {
-        let characteristic = CBMutableCharacteristic(
-            type: charUUID,
+    func peripheralManagerDidUpdateState(_ manager: CBPeripheralManager) {
+        guard manager.state == .poweredOn else { return }
+        let reading = CBMutableCharacteristic(
+            type: Self.reading,
             properties: [.read, .notify],
             value: nil,
             permissions: [.readable]
         )
-
-        let service = CBMutableService(type: serviceUUID, primary: true)
-        service.characteristics = [characteristic]
-        peripheralManager.add(service)
+        let service = CBMutableService(type: Self.service, primary: true)
+        service.characteristics = [reading]
+        manager.add(service)
     }
 
-    func peripheralManager(
-        _ peripheral: CBPeripheralManager,
-        didAdd service: CBService,
-        error: Error?
-    ) {
+    func peripheralManager(_ manager: CBPeripheralManager, didAdd service: CBService, error: (any Error)?) {
         guard error == nil else { return }
-        peripheralManager.startAdvertising([
-            CBAdvertisementDataServiceUUIDsKey: [serviceUUID],
-            CBAdvertisementDataLocalNameKey: "MyDevice"
+        manager.startAdvertising([
+            CBAdvertisementDataServiceUUIDsKey: [Self.service],
+            CBAdvertisementDataLocalNameKey: "Porch Thermometer",
         ])
     }
 }
 ```
 
-## Background BLE
-
-### Background Central Mode
+Custom services use full 128-bit UUIDs created with `CBUUID(string:)`. Leaving
+`value` nil makes the characteristic dynamic, so reads reach your delegate.
+Answering read, write and subscription requests is shown in the
+[patterns reference](references/ble-patterns.md).
 
-Add `bluetooth-central` to `UIBackgroundModes`. In the background:
+## Background operation
 
-- Scanning must specify one or more service UUIDs; `nil` scans are foreground-only
-- Scan options, including `CBCentralManagerScanOptionAllowDuplicatesKey`, have no effect
+**Central (`bluetooth-central`):**
 
-### Background Peripheral Mode
+- Background scans must name service UUIDs; a `nil` scan runs only in the
+  foreground.
+- Scan options, `CBCentralManagerScanOptionAllowDuplicatesKey` included, are
+  ignored in the background.
 
-Add `bluetooth-peripheral` to `UIBackgroundModes`. In the background:
+**Peripheral (`bluetooth-peripheral`):**
 
-- Without this mode, published service contents are disabled while suspended
-- The local name is not advertised
-- Service UUIDs move to the overflow area and require explicit service scans
+- Without this mode, the contents of published services are unavailable while
+  the app is suspended.
+- In the background the local name is not advertised.
+- Service UUIDs move to an overflow area that only centrals scanning
+  explicitly for those services can see.
 
-## State Restoration
+## State restoration
 
-State restoration allows the system to re-create your central or peripheral
-manager after your app is terminated and relaunched for a BLE event.
-
-### Central Manager State Restoration
+If the app is terminated, the system can relaunch it for a Bluetooth event and
+hand back the manager it had. Opt in with a restoration identifier:
 
 ```swift
-// 1. Create with a restoration identifier
-centralManager = CBCentralManager(
+central = CBCentralManager(
     delegate: self,
     queue: nil,
-    options: [CBCentralManagerOptionRestoreIdentifierKey: "myCentral"]
+    options: [CBCentralManagerOptionRestoreIdentifierKey: "scale-central"]
 )
 
-// 2. Implement the restoration delegate method
-func centralManager(
-    _ central: CBCentralManager,
-    willRestoreState dict: [String: Any]
-) {
-    if let peripherals = dict[CBCentralManagerRestoredStatePeripheralsKey]
-        as? [CBPeripheral] {
-        for peripheral in peripherals {
-            // Re-assign delegate and retain
-            peripheral.delegate = self
-            discoveredPeripheral = peripheral
+func centralManager(_ central: CBCentralManager, willRestoreState state: [String: Any]) {
+    if let devices = state[CBCentralManagerRestoredStatePeripheralsKey] as? [CBPeripheral] {
+        for device in devices {
+            device.delegate = self
+            scale = device
         }
     }
-    let restoredServices = dict[CBCentralManagerRestoredStateScanServicesKey]
-        as? [CBUUID]
-    let restoredOptions = dict[CBCentralManagerRestoredStateScanOptionsKey]
-        as? [String: Any]
-    // Resume scanning with restoredServices/restoredOptions if still needed.
-}
-```
-
-### Peripheral Manager State Restoration
-
-```swift
-peripheralManager = CBPeripheralManager(
-    delegate: self,
-    queue: nil,
-    options: [CBPeripheralManagerOptionRestoreIdentifierKey: "myPeripheral"]
-)
-
-func peripheralManager(
-    _ peripheral: CBPeripheralManager,
-    willRestoreState dict: [String: Any]
-) {
-    let services = dict[CBPeripheralManagerRestoredStateServicesKey]
-        as? [CBMutableService]
-    let advertisement = dict[CBPeripheralManagerRestoredStateAdvertisementDataKey]
-        as? [String: Any]
-    // Reconnect app state to restored services/advertisement as needed.
-}
-```
-
-## Common Mistakes
-
-### DON'T: Scan or connect before poweredOn
-
-```swift
-// WRONG: Scanning immediately -- manager may not be ready
-let manager = CBCentralManager(delegate: self, queue: nil)
-manager.scanForPeripherals(withServices: nil) // May silently fail
-
-// CORRECT: Wait for poweredOn in the delegate
-func centralManagerDidUpdateState(_ central: CBCentralManager) {
-    if central.state == .poweredOn {
-        central.scanForPeripherals(withServices: [serviceUUID])
-    }
-}
-```
-
-### DON'T: Lose the peripheral reference
-
-Core Bluetooth does not retain discovered peripherals. If you don't hold a
-strong reference, the peripheral is deallocated and the connection fails silently.
-
-```swift
-// WRONG: No strong reference kept
-func centralManager(_ central: CBCentralManager,
-                    didDiscover peripheral: CBPeripheral, ...) {
-    central.connect(peripheral) // peripheral may be deallocated
-}
-
-// CORRECT: Retain the peripheral
-func centralManager(_ central: CBCentralManager,
-                    didDiscover peripheral: CBPeripheral, ...) {
-    self.discoveredPeripheral = peripheral // Strong reference
-    central.connect(peripheral)
-}
-```
-
-### DON'T: Scan for nil services in production
-
-```swift
-// WRONG: Discovers every BLE device in range -- drains battery
-centralManager.scanForPeripherals(withServices: nil)
-
-// CORRECT: Specify the service UUIDs you need
-centralManager.scanForPeripherals(withServices: [targetServiceUUID])
-```
-
-### DON'T: Assume connection order or timing
-
-```swift
-// WRONG: Assuming immediate connection
-centralManager.connect(peripheral)
-discoverServicesNow() // Peripheral not connected yet
-
-// CORRECT: Discover services in the didConnect callback
-func centralManager(_ central: CBCentralManager,
-                    didConnect peripheral: CBPeripheral) {
-    peripheral.delegate = self
-    peripheral.discoverServices([serviceUUID])
-}
-```
-
-### DON'T: Write without checking properties and flow control
-
-```swift
-// WRONG: May fail, report an error, or provide no confirmation
-peripheral.writeValue(data, for: characteristic, type: .withResponse)
-
-// CORRECT: Check properties, length, and .withoutResponse flow control
-if characteristic.properties.contains(.write),
-   data.count <= peripheral.maximumWriteValueLength(for: .withResponse) {
-    peripheral.writeValue(data, for: characteristic, type: .withResponse)
-} else if characteristic.properties.contains(.writeWithoutResponse),
-          peripheral.canSendWriteWithoutResponse,
-          data.count <= peripheral.maximumWriteValueLength(for: .withoutResponse) {
-    peripheral.writeValue(data, for: characteristic, type: .withoutResponse)
+    let services = state[CBCentralManagerRestoredStateScanServicesKey] as? [CBUUID]
+    let options = state[CBCentralManagerRestoredStateScanOptionsKey] as? [String: Any]
+    resumeScanIfNeeded(services: services, options: options)
 }
 ```
 
-## Review Checklist
-
-- [ ] `NSBluetoothAlwaysUsageDescription` added to Info.plist
-- [ ] All BLE operations gated on `centralManagerDidUpdateState` returning `.poweredOn`
-- [ ] Discovered peripherals retained with a strong reference
-- [ ] Scanning uses specific service UUIDs (not `nil`) in production
-- [ ] `CBPeripheralDelegate` set before calling `discoverServices`
-- [ ] Characteristic properties checked before read/write/notify
-- [ ] Write payloads stay within `maximumWriteValueLength(for:)`
-- [ ] `.withoutResponse` writes honor `canSendWriteWithoutResponse`
-- [ ] Background mode (`bluetooth-central` or `bluetooth-peripheral`) added if needed
-- [ ] State restoration identifier set if app needs relaunch-on-BLE-event support
-- [ ] `willRestoreState` delegate method implemented when using state restoration
-- [ ] Scanning stopped after discovering the target peripheral
-- [ ] Disconnection handled with optional automatic reconnect logic
-- [ ] Write type matches characteristic properties (`.withResponse` vs `.withoutResponse`)
+A peripheral manager does the same with
+`CBPeripheralManagerOptionRestoreIdentifierKey`, and its
+`peripheralManager(_:willRestoreState:)` reads
+`CBPeripheralManagerRestoredStateServicesKey` (an array of `CBMutableService`)
+and `CBPeripheralManagerRestoredStateAdvertisementDataKey`.
+
+## Common mistakes
+
+- **Acting before `.poweredOn`.** Scans and connects can fail without a word.
+  Start them from the state callback.
+- **Dropping the peripheral.** Nothing else retains it, and the connection
+  quietly never happens.
+- **`nil` service scans in production.** Heavy on battery; list the UUIDs.
+- **Assuming the connection is instant.** Start service discovery in
+  `didConnect`, not right after `connect`.
+- **Writing blind.** Ignoring properties, the maximum write length or
+  `.withoutResponse` flow control leads to failed or unconfirmed writes.
+
+## Review checklist
+
+- [ ] `NSBluetoothAlwaysUsageDescription` is present
+- [ ] Every operation waits for `.poweredOn`
+- [ ] Discovered peripherals are held strongly
+- [ ] Production scans list specific service UUIDs
+- [ ] `CBPeripheralDelegate` is set before `discoverServices`
+- [ ] Properties are checked before read, write or notify
+- [ ] Writes fit within `maximumWriteValueLength(for:)`
+- [ ] `.withoutResponse` writes respect `canSendWriteWithoutResponse`
+- [ ] Needed background modes are declared
+- [ ] A restoration identifier is set when relaunch on BLE events matters
+- [ ] `willRestoreState` is implemented whenever restoration is on
+- [ ] Scanning stops once the target is found
+- [ ] Disconnects are handled, with reconnection where it makes sense
+- [ ] Write type matches the characteristic's properties
 
 ## References
 
-- Extended patterns (reconnection strategies, data parsing, SwiftUI integration): [references/ble-patterns.md](references/ble-patterns.md)
-- [Core Bluetooth framework](https://sosumi.ai/documentation/corebluetooth)
-- [CBCentralManager](https://sosumi.ai/documentation/corebluetooth/cbcentralmanager)
-- [CBPeripheral](https://sosumi.ai/documentation/corebluetooth/cbperipheral)
-- [CBPeripheralManager](https://sosumi.ai/documentation/corebluetooth/cbperipheralmanager)
-- [CBService](https://sosumi.ai/documentation/corebluetooth/cbservice)
-- [CBCharacteristic](https://sosumi.ai/documentation/corebluetooth/cbcharacteristic)
-- [CBUUID](https://sosumi.ai/documentation/corebluetooth/cbuuid)
-- [CBCentralManagerDelegate](https://sosumi.ai/documentation/corebluetooth/cbcentralmanagerdelegate)
-- [CBPeripheralDelegate](https://sosumi.ai/documentation/corebluetooth/cbperipheraldelegate)
-- [NSBluetoothAlwaysUsageDescription](https://sosumi.ai/documentation/bundleresources/information-property-list/nsbluetoothalwaysusagedescription)
-- [CBManagerAuthorization](https://sosumi.ai/documentation/corebluetooth/cbmanagerauthorization)
-- [scanForPeripherals(withServices:options:)](https://sosumi.ai/documentation/corebluetooth/cbcentralmanager/scanforperipherals(withservices:options:))
-- [startAdvertising(_:)](https://sosumi.ai/documentation/corebluetooth/cbperipheralmanager/startadvertising(_:))
-- [writeValue(_:for:type:)](https://sosumi.ai/documentation/corebluetooth/cbperipheral/writevalue(_:for:type:))
-- [maximumWriteValueLength(for:)](https://sosumi.ai/documentation/corebluetooth/cbperipheral/maximumwritevaluelength(for:))
-- [canSendWriteWithoutResponse](https://sosumi.ai/documentation/corebluetooth/cbperipheral/cansendwritewithoutresponse)
-- [Configuring background execution modes](https://sosumi.ai/documentation/xcode/configuring-background-execution-modes)
+- [BLE patterns](references/ble-patterns.md): SwiftUI manager and view,
+  reconnection, byte parsing, write flow control, several peripherals, L2CAP,
+  answering requests as a peripheral
+- Apple documentation (developer.apple.com):
+  [framework](https://developer.apple.com/documentation/corebluetooth),
+  [central manager](https://developer.apple.com/documentation/corebluetooth/cbcentralmanager),
+  [peripheral](https://developer.apple.com/documentation/corebluetooth/cbperipheral),
+  [peripheral manager](https://developer.apple.com/documentation/corebluetooth/cbperipheralmanager),
+  [service](https://developer.apple.com/documentation/corebluetooth/cbservice),
+  [characteristic](https://developer.apple.com/documentation/corebluetooth/cbcharacteristic),
+  [UUID](https://developer.apple.com/documentation/corebluetooth/cbuuid),
+  [central delegate](https://developer.apple.com/documentation/corebluetooth/cbcentralmanagerdelegate),
+  [peripheral delegate](https://developer.apple.com/documentation/corebluetooth/cbperipheraldelegate),
+  [usage description key](https://developer.apple.com/documentation/bundleresources/information-property-list/nsbluetoothalwaysusagedescription),
+  [authorization values](https://developer.apple.com/documentation/corebluetooth/cbmanagerauthorization),
+  [scanning](https://developer.apple.com/documentation/corebluetooth/cbcentralmanager/scanforperipherals(withservices:options:)),
+  [advertising](https://developer.apple.com/documentation/corebluetooth/cbperipheralmanager/startadvertising(_:)),
+  [writing values](https://developer.apple.com/documentation/corebluetooth/cbperipheral) (`writeValue(_:for:type:)` on the peripheral page),
+  [maximum write length](https://developer.apple.com/documentation/corebluetooth/cbperipheral/maximumwritevaluelength(for:)),
+  [write-without-response readiness](https://developer.apple.com/documentation/corebluetooth/cbperipheral/cansendwritewithoutresponse),
+  [background execution modes](https://developer.apple.com/documentation/xcode/configuring-background-execution-modes)