Deliver the first watchOS companion experience

[altaywtf]

Parent

#123

What this delivers

A useful native watchOS companion for the new iOS app, built as a separate SwiftUI executable over the shared Apple core rather than a miniature phone UI. The shell and pairing identity start in #124; this child turns that foundation into a launchable companion experience.

Decisions and constraints

• The Watch app is paired with the new iOS app and shares its product family, session model, SDK boundary, design tokens, and reusable feature logic.
• The Watch app owns a watch-native UI; iOS, tvOS, and watchOS remain separate executable shells rather than one universal UI target.
• Its bundle identity derives from the iOS identifier as required by Apple; signing and TestFlight packaging belong to Establish the new Apple app identity, signing, and TestFlight lanes #127.
• Do not duplicate system Now Playing controls as the entire product. Before implementation, settle the smallest distinctly useful Watch surface in this issue and update the acceptance criteria with that observable contract.

Scope

• Paired-session handoff and recovery states without asking the user to re-enter credentials on Watch.
• One focused, useful Watch read/action loop selected and recorded here before implementation.
• Watch-native loading, empty, offline, unpaired, expired-session, and error behavior for that loop.
• Deterministic fixtures, simulator coverage, snapshots, and proof through Agent-readiness harness: autonomous bootstrap, run, and proof environment #146.
• Shared-core changes only where they are genuinely platform-neutral; Watch-only behavior stays in the Watch shell.

Acceptance criteria

• The exact first useful Watch surface and its non-goals are recorded in this issue before feature implementation begins
• A signed-in iOS user can establish and recover the Watch companion session without entering put.io credentials on Watch
• The selected Watch loop works end to end with watch-native navigation and state handling
• The Watch app builds, tests, and captures visual proof through the shared harness
• The companion is included in an installable iOS TestFlight build

Verification

• Unit tests over session handoff and the selected feature state
• Watch simulator exercise with screenshot or recording attached to the PR
• Physical iPhone + Apple Watch acceptance for cross-device session transfer before launch
• Successful CI archive and TestFlight installation through Establish the new Apple app identity, signing, and TestFlight lanes #127

Blocked by

• Scaffold the next-generation iOS, tvOS, and watchOS workspace on the permanent next branch #124
• Generate the Swift design-token adapter from @putdotio/design #125
• Establish the new Apple app identity, signing, and TestFlight lanes #127
• Build the core SwiftUI component kit from the design contract #128
• iOS auth: OAuth sign-in, keychain session, and account bootstrap #129
• Agent-readiness harness: autonomous bootstrap, run, and proof environment #146

Boundaries

No attempt to reproduce the full iOS or tvOS parity bars on Watch. No watch-only App Store product, workouts, HealthKit, widgets/complications, or background behavior unless the selected first surface genuinely requires a separately approved expansion.