WatchConnectivity

Two-way communication between an iOS app and its paired watchOS app over a single WCSession. The deep API reference — setup, every transfer method, the delegate, SwiftUI/@Observable integration, async wrappers, complications, troubleshooting — lives in references/guide.md. This file is the decision and discipline layer: read it first, open the guide for specifics.

Dials

Set these explicitly at the start; they change what "correct" means.

1. TRANSFER — interactive-sendMessage (real-time, needs both apps live + isReachable) · background-context (updateApplicationContext, latest-state-only sync) · userInfo-queue (transferUserInfo, ordered guaranteed delivery) · file (transferFile, large payloads). Pick per payload; most apps use several.
2. ACTIVATION — single-watch (activate once, no re-activation needed) · multi-watch (iOS must re-activate() inside sessionDidDeactivate to follow a watch switch). Default to multi-watch on iOS — it costs one line and prevents a dead session.
3. DIRECTION — phone->watch (config/auth push down) · watch->phone (workout/sensor data up; phone is woken in background) · bidirectional (request/reply via sendMessage replyHandler).

When to use

Building or reviewing any code that syncs state, sends messages, queues data, transfers files, or updates complications between an iPhone app and its paired Apple Watch app. The manager type is shared across both targets (#if os(iOS) guards the iOS-only surface). If there is no watchOS target, you don't need this skill.

Core rules