Create Wristivo iPhone and Apple Watch foundation

docs/ARCHITECTURE.md

@@ -0,0 +1,60 @@
+# Architecture
+
+## Decision
+
+Use native SwiftUI applications and a local Swift package. The watch owns motion capture and recognition; the phone owns TV credentials and networking. No backend is required. Gitea stores development source, not user data.
+
+```mermaid
+flowchart LR
+  A[Watch Core Motion] --> B[GestureCore: calibrated discrete intent]
+  C[Watch buttons] --> D[WatchBridge: live message]
+  B --> D
+  D --> E[iPhone session / command admission]
+  F[iPhone buttons] --> E
+  E --> G[TVTransport actor]
+  G --> H[Samsung TV: paired local WebSocket]
+  I[Keychain token + TV trust record] --> G
+  G --> J[Send receipt / failure]
+  J --> D
+```
+
+Apple TN3135 restricts ordinary watch apps' low-level networking, including URLSessionWebSocketTask. A TV remote does not qualify for the audio, VoIP or tvOS discovery exceptions. See PLATFORM-FEASIBILITY. WatchConnectivity may wake the phone, but this does not grant unlimited phone background execution. Phone-lock/relaunch usability is a physical-hardware gate.
+
+## Boundaries
+
+| Location | Responsibility | Current state |
+| --- | --- | --- |
+| Apps/iPhone | Setup, manual remote, status and troubleshooting | Local demo UI |
+| Apps/Watch | Session controls, touch remote, calibration UI | Local demo UI |
+| Apps/Shared | Command presentation | Implemented |
+| Packages/WristivoKit/RemoteCore | Commands, envelopes, admission and receipts | Foundation implementation |
+| Packages/WristivoKit/SamsungProtocol | Key mapping and frame/URL encoding | Pure encoding, no socket |
+| Packages/WristivoKit/GestureCore | Normalized directional excursion state machine | Algorithm seam, no raw sensor classifier |
+| Adapters/TVTransport | iPhone URLSession WebSocket state machine | Planned |
+| Adapters/WatchBridge | WCSession lifecycle and live delivery | Planned |
+| Adapters/MotionCapture | Core Motion, coordinate calibration, normalization | Planned |
+| Adapters/SecureStorage | Keychain token and trust persistence | Planned |
+
+Package target source directories are under Sources. Imported modules use the module names, not the package name. OS adapters stay platform-specific. The integrator adds targets/dependencies or file memberships when implementations arrive.
+
+## States and ownership
+
+TV connection: `disconnected → connecting → awaitingApproval → ready`; errors lead to `denied`, `unauthorized`, `untrusted`, `timedOut` or `unavailable`. Socket-open alone is never `ready`. Require the model's authorization event. Changing target destroys the old connection and control session. Tokens never travel to Watch.
+
+Watch: `idle → calibrating → ready → armed → paused`. A scene phase other than active, sensor error, TV switch, phone unavailability or stop disarms and clears accumulated motion. Resuming requires explicit re-arm and fresh neutral baseline. No automatic gesture on launch.
+
+One iPhone actor serializes commands, session authorization, admission and TV send operations. Avoid holding unbounded work across `await`: actor reentrancy still requires cancellation/generation checks when a TV or session changes. At most one in-flight TV send and a small bounded queue; drop expired items. No backlog in WatchConnectivity transferUserInfo or application context.
+
+## Prototype order
+
+Build a phone-to-TV vertical slice first. Run a watch-button relay slice alongside raw motion capture/calibration work with a fake command sink. Only integrate gesture-to-TV output after each slice passes separately. UI agents work against fake services using shared contracts. The demo never silently becomes a live transport.
+
+## Alternatives and decisions
+
+- ADR-001: phone relay required by watch network constraints.
+- ADR-002: active sessions only; no background mode misuse.
+- ADR-003: no TV app required for initial local controller pairing. Pairing identity is a network controller label, not Bluetooth certification or TV app store registration.
+- ADR-004: manual address first; discovery deferred to avoid blocking the free-account prototype on multicast entitlement work.
+- ADR-005: no runtime third-party libraries in foundation; compatibility protocol remains an isolated replaceable adapter.
+
+Contract changes require an integration decision entry with date, reason, affected agents, migration and tests. Do not maintain different command models in each app.

docs/BRAND-AND-IP.md

@@ -0,0 +1,59 @@
+# Brand and intellectual property
+
+Status: **Wristivo is a provisional working name, not legally cleared or registered.** Official references checked 2026-09-16. These engineering controls reduce avoidable risk; they cannot guarantee freedom from disputes or replace jurisdiction-specific clearance.
+
+## Product identity
+
+Owner-approved working brand (2026-09-16): **Wristivo**. Proposed descriptive subtitle: **Wrist-powered TV remote**. Use an original abstract motion/light identity, original typography treatment, and independently created app screens. This is a naming proposal; name availability, similar marks, app listings, domains, and visual identity still need clearance.
+
+Use `Wristivo` as the protocol client display name where the supported TV pairing mechanism permits it. The user should recognize that name in the TV's access prompt and allowed-device list. Saving a trusted client on a TV is device authorization; it is not trademark registration, Samsung certification, a published Tizen TV application, or a guarantee that every TV retains the same displayed name. Verify actual behavior on each supported model.
+
+Proposed compatibility copy, pending implementation evidence and release review:
+
+> Wristivo is an independent remote-control app for compatible Samsung TVs running Tizen. It is not affiliated with or endorsed by Samsung or Apple. Supported models and setup requirements are listed in the compatibility guide.
+
+Use third-party names only where they explain genuine compatibility. Do not use Samsung, SmartThings, Tizen, Apple, or competing remote-app names in the primary brand, bundle branding, original icon, or a claim of official status. Do not copy manufacturer logos or imply that a disclaimer alone grants usage rights. Samsung's developer-site terms do not grant rights to its marks. Apple provides conditions for referential compatibility statements and prohibits implied endorsement. Check applicable agreements and actual marketing before publication. [Samsung developer terms](https://developer.samsung.com/terms?location=us), [Apple trademark guidelines](https://www.apple.com/legal/intellectual-property/guidelinesfor3rdparties.html).
+
+## Distinct risks require distinct checks
+
+| Area | What the project must examine | Required evidence |
+| --- | --- | --- |
+| Copyright | Source code, icons, illustrations, fonts, audio, documentation, TV screenshots, and copied UI artwork | Original-work provenance or license/permission and preserved notices |
+| Trademark | Wristivo and confusingly similar names, logos, pronunciations, or commercial impressions in target markets | Dated clearance search and decision for actual goods/services and territories |
+| Patents | Relevant gesture recognition, wearable control, and TV-control inventions | Specialist freedom-to-operate review if warranted for commercial launch; original coding alone does not answer patent questions |
+| Contract/platform terms | SDK licenses, sample-code terms, API/service terms, protocol implementation sources, and distribution agreements | Reviewed terms, permitted usage, and unresolved limitations recorded |
+
+The basic distinction is that trademarks identify source, copyright protects original expressive works, and patents protect qualifying inventions. Rights can overlap. [USPTO overview](https://www.uspto.gov/trademarks/basics/trademark-patent-copyright).
+
+## Name clearance release gate
+
+1. Product owner chooses launch territories and intended publisher/legal entity. Do not infer the legal market from a developer's timezone or device locale.
+2. Search exact `Wristivo`, spacing variants such as `Wrist Ivo`, phonetic/spelling neighbors, related marks, and similar visual identities. Search software, remote controls, wearables, and related goods/services, not just identical names.
+3. Check WIPO and each relevant national/regional register, plus app stores, search engines, company names, domains, and relevant marketplace usage. WIPO notes that its coverage does not replace national/regional searches. USPTO describes federal, state, and common-law sources as part of comprehensive US clearance. [WIPO database](https://www.wipo.int/en/web/global-brand-database), [USPTO clearance guidance](https://www.uspto.gov/trademarks/search/comprehensive-clearance-search-similar-trademarks).
+4. Save date, source, exact query, jurisdiction, relevant results, status, goods/services, and reviewer decision. A search-engine no-result page, available domain, or App Store name reservation is not legal clearance.
+5. Have a qualified trademark professional assess material conflicts and filing strategy for the selected territories before major branding expenditure or launch. Do not use a registered-mark symbol unless valid rights justify it.
+6. Only after clearance, finalize the visible name, publisher-controlled reverse-DNS identifiers, domain, icon, legal text, and store metadata. Keep the proposed name configurable until then.
+
+Current clearance record: **not completed**. The integration engineer performed narrow quoted public-web searches for `"Wristivo"` and `"Wristivo" remote app trademark` on 2026-09-16 and reported no returned results. This is preliminary screening only; no trademark-register, phonetic-similarity, domain, or jurisdiction-specific clearance is established. An earlier working-name candidate was dropped after an existing retail-product use was found. No registered-name, domain-ownership, or non-infringement claim is made by this repository.
+
+## Rules for parallel implementation agents
+
+- Write original implementations from the project's interface contracts and independently justified design. Do not clone a commercial remote's screens, icon, copy, calibration tutorial, or proprietary code.
+- Do not treat public GitHub/Gitea code, forum snippets, sample code, or downloaded assets as license-free. Before incorporating any source or dependency, record its origin, version, license, attribution, distribution obligations, and decision.
+- Avoid dependencies with unresolved provenance or obligations incompatible with the intended commercial distribution. If unsure, isolate the issue and ask the integration engineer to decide before merge.
+- Keep a dependency and asset register, including generated assets and fonts. Record author/tool, input/reference rights, modifications, and license. AI-generated work is not automatically free of infringement risk; review similarity and provenance.
+- Use neutral original demo content on a TV or simulated TV. Exclude movie stills, channel logos, streaming-service artwork, personal accounts, and copyrighted broadcast footage unless rights are documented.
+- Use Apple-provided symbols, platform assets, or device frames only within their applicable license/marketing conditions; availability in a tool is not unrestricted redistribution permission.
+- Document protocol observations and authoritative references. Do not copy an entire third-party implementation, bypass TV consent, extract secrets from vendor software, or claim an unofficial endpoint is a supported vendor API.
+- Keep source private on the owner's Gitea until publication/licensing is explicitly decided. A private repository still requires compliance with licenses for incorporated material.
+- Do not apply a blanket open-source license or assign copyright ownership to an unverified legal entity. The owner must select the licensing and contributor-rights model before external contribution or publication.
+
+## Required pre-release artifacts
+
+- Completed name/mark clearance log and final name decision.
+- Dependency and asset inventory, exact licenses, required attributions, and any written permissions.
+- Original design/source provenance notes and review of protocol licensing/terms.
+- Store copy, screenshots, icon, compatibility claims, and disclaimer reviewed together.
+- Applicable rights and permission questions resolved for the intended launch territories.
+
+App Store acceptance does not establish IP ownership or immunize the publisher from claims. Keep these artifacts with the release evidence and repeat relevant checks when the brand, dependencies, features, or launch markets change.

docs/CONTRACTS.md

@@ -0,0 +1,31 @@
+# Command contract v1
+
+Source of truth: `Packages/WristivoKit/Sources/RemoteCore`. The integration owner maintains these types. This document defines production adapter behavior in addition to the foundation types; the scaffold does not yet implement the relay/session handshake.
+
+## Commands and envelope
+
+`RemoteCommand`: up, down, left, right, select, back, home, playPause, volumeUp, volumeDown, mute. Wire values are the enum's raw strings. Unknown values fail decoding. No raw arbitrary Samsung keys from UI or watch.
+
+`CommandEnvelope`: `schemaVersion` (1), `id` (UUID), `sessionID` (UUID), `televisionID` (UUID), `sequence` (UInt64), `issuedAt` (Date), `expiresAt` (Date), `command`. UUIDs identify local opaque records, not TV serial numbers or network addresses. Date encoding on the future bridge is explicitly JSON milliseconds since Unix epoch; both encoders/decoders must set the same strategy. Package round-trip tests alone are not sufficient to validate that adapter.
+
+A session is issued by the phone for one selected paired TV, bound to the currently activated paired WCSession. The watch cannot select an arbitrary target by manufacturing an envelope. Proposed control-plane operations: `beginSession` returns v1, sessionID, televisionID and expiry policy; `endSession` invalidates that exact session; a new phone process, TV switch, re-pair, bridge deactivation or app stop invalidates old authorization. Add typed control-plane DTOs under integration ownership before transport implementation. Starting a session must never issue a TV key.
+
+Sequence starts at 0 or 1 and strictly increases within a session; all senders in a given session must share one counter. At UInt64 exhaustion start a new session rather than wrapping. The receiver rejects wrong target/session/version, invalid/non-finite times, future timestamps beyond 250 ms, messages over one second old, expiry in the past, expiry preceding issue, or a declared lifetime longer than one second. No arbitrary clock-skew widening: report need to resync/start a new session. Test actual paired-device skew. Adapter also maintains a receiver-local monotonic deadline so wall-clock changes cannot extend pending work.
+
+Validate decoded values at every trust boundary; Codable construction alone does not validate invariants. The bridge performs structural validation only and delegates to one authoritative phone command actor. Only that actor consumes CommandAdmission state and owns the authorized session; duplicate checks must not advance a second gate in the bridge. Admit each ID once with bounded storage and monotonic sequence. Consume admission before sending; on ambiguous transport failure do not retry the same action. Check expiry/session again immediately before the live WebSocket send; reject pending work on disconnect, never reconnect-and-flush.
+
+## Receipt semantics
+
+`CommandReceipt` correlates the envelope ID. Status is sentToTransport, rejected, expired, duplicate or unavailable. A successful send only means the adapter completed the socket write; Samsung may provide no per-key execution acknowledgement. Never display "TV confirmed" based only on that receipt. Timeout after possible delivery is uncertain; ask the user to issue a new action if needed rather than replaying.
+
+Planned bridge container: `["schemaVersion": 1, "kind": "command", "payload": Data]` with bounded JSON payload (4 KiB maximum), delivered using sendMessage/replyHandler. Validate container types and payload size before decoding. Reply uses the same versioned container with kind `receipt`. Exactly one reply per incoming request, including errors. No passwords/tokens/raw motion in these messages. Test Codable round trips, invalid payloads, schema mismatches and restart cases.
+
+## Adapter interfaces
+
+Existing `RemoteTransport.send(_ envelope: CommandEnvelope) async -> CommandReceipt` is the command sink. The sender has no implicit retry guarantee. Platform agents propose small lifecycle protocols for connection, session acquisition, token repository and motion source through the integrator; do not hide setup inside `send` or start pairing in response to a gesture.
+
+GestureCore receives normalized inputs from the future MotionCapture adapter. Its thresholds are algorithm fixtures, not physically calibrated degrees or validated human-motion confidence. Sensor coordinate transforms and physical traces are required before claiming wrist-swipe recognition. Watch and phone UI depend on domain contracts, never Samsung frame strings.
+
+## Compatibility change policy
+
+An additive optional field may remain v1 only if existing behavior stays safe. New command semantics, changed time units or altered authorization require a new schema version and explicit negotiation. Unsupported versions fail closed. Mixed-version phone/watch installations must show update guidance and preserve accessible phone control.

docs/DEPENDENCIES-AND-ASSETS.md

@@ -0,0 +1,15 @@
+# Dependency and asset register
+
+Foundation inventory, 2026-09-16. Update before adding any dependency or asset.
+
+| Item | Use | Version/origin | Distribution / review status |
+| --- | --- | --- | --- |
+| Swift / SwiftUI / Foundation | App and pure package | Apple SDK/toolchain; initial Xcode 27 | Platform frameworks, no vendored source |
+| SF Symbols / system fonts | In-app button symbols/type | OS system rendering | Use through Apple frameworks; review final marketing/icon usage separately |
+| Wristivo Swift/docs/scripts | Foundation | Created for this project with AI assistance | Original implementation; final owner/legal entity terms pending |
+| Ruby xcodeproj | Development project generation | 1.27.0, installed host gem | MIT upstream; not linked/shipped with app; no source vendored |
+| actions/checkout | Optional Gitea CI template | v4.2.2 commit 11bd71901bbe5b1630ceea73d27597364c9af683 | MIT upstream; activation/security/runner compatibility review pending |
+| Samsung protocol project references | Research only | Links in SAMSUNG-INTEGRATION | No copied code or runtime dependency; upstream LGPL code not incorporated |
+| Final app icon, screenshots, support site | Not created | Pending | Original/authorized content and provenance required |
+
+There are no third-party runtime packages in Package.swift. This statement must be rechecked after each dependency addition. Record exact version/hash, license, author/source, modifications, attribution requirements, security review and distribution decision for future entries. App signing/provisioning materials are not assets for this inventory and must stay out of git.

docs/GESTURE-SPEC.md

@@ -0,0 +1,93 @@
+# Gesture interaction and recognition specification
+
+Status: proposed MVP requirements and experiment plan, 2026-09-16. Thresholds and performance targets below are hypotheses, not validated recognition results. Follow `PLATFORM-FEASIBILITY.md` for runtime and transport constraints and the shared contract document for command serialization.
+
+## User interaction
+
+The user wears the watch, opens Wristivo, and chooses Gesture Mode. A short guided calibration establishes a comfortable neutral pose and the meaning of right, left, up, and down for that wrist. The watch provides deliberate **wrist flicks**, not finger tracking or spatial tracking of a hand through the room.
+
+Directions are user-relative: right should navigate the TV focus right even if the watch is worn on the other wrist. Avoid requiring a precisely horizontal arm or large movement. Train and validate the mapping for both wrists and supported crown orientations; never infer a universal screen-space direction directly from a single raw sensor axis.
+
+| Input | Proposed output | Scope |
+| --- | --- | --- |
+| Short right wrist flick, then return to neutral | One Right command | MVP after validation |
+| Short left wrist flick, then return to neutral | One Left command | MVP after validation |
+| Short upward wrist flick, then return to neutral | One Up command | MVP after validation |
+| Short downward wrist flick, then return to neutral | One Down command | MVP after validation |
+| Select button | One Select command | Required fallback |
+| System double tap on supported hardware/OS | Activate visible Select primary action | Optional enhancement; test separately |
+| Back, Home, volume and playback controls | Explicit accessible watch buttons | No motion mapping in initial release |
+| Stop button or loss of active scene | Disarm and cancel candidate | Required |
+
+Do not map ordinary wrist shaking, finger pinching, clenches, a return-to-neutral movement, or prolonged tilt to additional commands in the MVP. Avoid motion-based power, purchase, delete, or reset actions. The optional system primary action is public SwiftUI behavior, not an API exposing raw double-tap recognition. [Apple double-tap documentation](https://developer.apple.com/documentation/watchos-apps/enabling-double-tap)
+
+## State machine
+
+```text
+disarmed -> calibrating -> ready -> candidate -> cooldown -> ready
+    ^            |          |          |            |
+    +------------+----------+----------+------------+
+         stop / inactive scene / target change / failure
+```
+
+- **Disarmed:** no sensor updates, no motion commands. Touch controls remain available when the transport permits them.
+- **Calibrating:** collect a stable neutral pose and guided labeled examples. Do not send TV commands. Show progress, Retry, and Cancel.
+- **Ready:** only entered when scene active, calibration valid, selected TV identified, and relay available. Low-confidence or mixed-axis movement produces no command.
+- **Candidate:** observe a bounded motion window and classify at most one direction. Reject stale samples, discontinuities, and conflicting movements. On accepted classification, ask the shared command gate to send one command.
+- **Cooldown:** suppress the return motion. Require both elapsed cooldown and a stable return to the neutral zone before recognizing again.
+- Any transition to disarmed clears candidate buffers and pending local intent. Foreground return requires explicit Start/Resume. A completed cooldown does not re-arm an inactive app.
+
+One gesture means one button press. Disable held-key repeat in MVP. Recognition acceptance produces a short haptic only when the command gate accepts the intent; errors use a distinct, rate-limited cue. Describe this as command feedback, not a guarantee that the TV changed state.
+
+## Motion pipeline for the implementing agent
+
+Use a platform-independent recognizer over timestamped motion samples and a small watch-only Core Motion adapter. `CMMotionManager` provides processed motion and availability checks; stop its updates when disarmed. [CMMotionManager](https://developer.apple.com/documentation/coremotion/cmmotionmanager)
+
+1. Request an initial 50 Hz sample interval and record actual monotonic sample intervals. Rate is a tuning parameter; it is not guaranteed delivery. Process off the main actor and bound the buffer.
+2. Work from relative orientation, rotation rate, and user acceleration. Prefer a short-session neutral reference over compass-dependent global heading. Do not integrate acceleration into a claim of accurate hand position.
+3. Normalize using a tested device/wrist orientation transform and the calibration record. Document quaternion multiplication order, units, handedness, and timestamp clock in the recognizer interface.
+4. Establish stability from a rolling neutral window, initially 500 ms. Capture at least three labeled examples per direction during engineering trials; simplify consumer calibration only after evidence supports it.
+5. Segment deliberate departures from neutral and score dominant direction. Start experiments with a 120–650 ms candidate window, roughly 15–35 degree relative rotation, and a dominant-axis ratio of at least 1.5. These values are not production defaults until tested.
+6. Reject ambiguous movement, slow posture drift, bad sample gaps, non-finite values, and implausible jumps. Keep confidence and thresholds tunable and versioned.
+7. Begin with 400 ms cooldown plus 200 ms stable-neutral dwell. Neither timer alone permits a second press. A rapid reverse movement used to return to neutral must not become an opposite command.
+
+No health, movement-disorder, private sensor, or private gesture API is needed. Include an accurate motion purpose string and test denied/unavailable data states using the exact chosen SDK and OS. Do not promise a system permission prompt will appear for every Core Motion call. [Core Motion privacy and availability guidance](https://developer.apple.com/documentation/coremotion/)
+
+## Interfaces and ownership boundaries
+
+The motion agent owns Core Motion acquisition, deterministic sample-to-intent logic, calibration records, and replay fixtures. The watch-shell agent owns SwiftUI state, native buttons and haptics, and calls the motion adapter start/stop lifecycle interface. The relay agent owns immediate Watch Connectivity messaging. The integration owner approves shared protocol changes.
+
+The recognizer output is semantic direction plus recognition timing/confidence; it must not contain TV key strings, URLs, pairing tokens, transport retries, or UI objects. Use the shared command type when creating the outgoing command. The transport gate handles target binding, request identity, freshness, and duplicate handling as defined centrally.
+
+Use injected monotonic clocks in tests. Serialize only what the shared protocol defines: clocks on different devices cannot be assumed to have identical monotonic origins. Do not invent cross-device timestamp arithmetic inside the recognizer.
+
+## Privacy and calibration
+
+Keep raw motion in a bounded, ephemeral in-memory buffer by default. Store only the minimal local calibration values and their algorithm version. Reset calibration when wrist/orientation changes or the user requests it. Never silently upload motion samples.
+
+An engineering recording mode may save labeled samples only after explicit opt-in, with visible recording status and a clear delete/export action. Exclude device identifiers, TV tokens, and household addresses from fixtures. Use original recordings with the participant's permission; do not copy an unlicensed gesture dataset.
+
+## Verification and acceptance
+
+Unit tests must cover useful behavioral failures: return-to-neutral suppression, noisy samples, ambiguous diagonals, gaps/out-of-order samples, opposite wrist transforms, cooldown boundaries, scene deactivation mid-gesture, and no replay after resume. A synthetic trace only proves logic consistency; record real samples before claiming recognition quality.
+
+For the hardware gate, recruit at least five consenting testers where practical. Include both wrists, varied wrist sizes and comfortable poses, and at least two watch models. Run 20 prompted trials per direction per tested wrist/orientation configuration. Count wrong directions, missing outputs, and duplicate commands separately; do not discard failed trials. Keep tuning participants separate from the final evaluation group when possible.
+
+Proposed pass criteria:
+
+- Per-direction precision >= 98% and recall >= 90%; publish raw counts and a confusion matrix with the result.
+- Zero duplicate presses in the evaluation corpus; every accepted motion emits at most one command.
+- At most one false command per 30 minutes of representative non-command motion while deliberately armed, tested for each configuration. Include conversation gestures, reaching for a cup, posture changes, and resting.
+- Zero commands while disarmed or inactive, including interruptions and resumption.
+- Motion completion to visible TV response p95 <= 700 ms in a connected warm session; measure cold/wake paths separately and report failures.
+- Calibration can be completed without discomfort; each action has a touch and accessibility fallback. Do not gate essential control behind gesture proficiency.
+
+These are minimum engineering targets, not statistical proof of general reliability. Expand trials before public claims. Any persistent false-action pattern blocks gesture-mode release even if average accuracy passes. Follow Apple's recommendation to provide alternatives to required body movements. [Human Interface Guidelines: Gestures](https://developer.apple.com/design/human-interface-guidelines/gestures/)
+
+## Implementation handoff checklist
+
+Submit the recognizer with deterministic tests, a calibration schema/version, documented units and transforms, sample recording procedure, results with device/build metadata, and unresolved limitations. Submit the watch integration with verified disarm behavior outside Xcode and a short video of right/left/up/down control on a physical TV. Mark every absent artifact as pending; never treat the scaffold's demo command screen as motion recognition.
+
+## Foundation implementation boundary
+
+The existing DirectionalGestureGate is an already-normalized excursion gate only. Its unit-test defaults (0.7 activation, 0.25 neutral, 300 ms minimum interval, 10-second maximum arm) are not the production motion pipeline above. Stable-neutral dwell, candidate windows, physical calibration and confidence scoring are still to be implemented by C. The watch UI must explicitly arm the recognizer after calibration; calibration completion never starts live input on its own. Sensor shutdown at the arm deadline needs a lifecycle timer in the adapter, even if no new samples arrive.

docs/GITEA.md

@@ -0,0 +1,32 @@
+# Gitea repository and delivery
+
+Owner-provided account: [gitea.samialabri.com/sami](https://gitea.samialabri.com/sami). The owner approved Wristivo and the `wristivo` slug on 2026-09-16 and will create the repository. **No remote repository has been created or pushed by this foundation task.** Agreed repository slug: `wristivo`; visibility: private. Existing authenticated sessions/SSH agent or the system credential manager should handle authentication; never paste access tokens into agent chat or commit them.
+
+## Owner creates an empty private repository
+
+Create `sami/wristivo` on that server, private, with default branch `main`. Leave README/license/gitignore initialization off because this repository already supplies them. Do not choose an open-source license until the intended rights model is decided. Copy the exact HTTPS or SSH clone URL from Gitea; SSH usernames/ports are deployment-specific.
+
+The integrating engineer then verifies the destination and existing refs, adds `origin` to this local repository, and pushes `main` normally. For the expected HTTPS deployment the candidate URL is `https://gitea.samialabri.com/sami/wristivo.git`, but use the server's displayed clone URL as authoritative.
+
+```sh
+# From the local Wristivo repository, after owner creates it:
+git remote add origin https://gitea.samialabri.com/sami/wristivo.git
+git ls-remote origin
+git push -u origin main
+```
+
+If the remote is not empty, inspect and integrate its existing history first; do not force-push or overwrite it. If origin already exists, inspect it before changing anything. Never put a token in the URL. Remote creation/push are pending, not failed or completed.
+
+## Collaboration controls
+
+Protect main after initial bootstrap: PR-based changes, required successful validation check once configured, no force pushes/deletion, and at least one integration review where the account/team setup permits. Keep the integration role explicit even when a sole owner is both author and reviewer. Feature branches follow docs/agents/README. Use PR template and small milestone labels: foundation, pairing, relay, gestures, experience, release; and needs-hardware, blocked-contract, security-review.
+
+## CI
+
+`.gitea/ci.yml.example` is intentionally a template until server/runner versions and trust settings are confirmed. Enable Actions for the repository, provision a dedicated trusted macOS host runner with Xcode and required runtime tools, label it `macos-wristivo`, validate its checkout/action support, then copy the file to `.gitea/workflows/ci.yml`.
+
+Apple builds require macOS/Xcode; a generic Linux container cannot compile the app targets. A host runner executes code on its machine, so do not give an untrusted fork automatic access to a signing machine or home-network TV. The template runs trusted branch pushes and manual requests. Add PR validation only after reviewing runner isolation and who can submit code. No Apple signing secrets are required for these unsigned tests/builds.
+
+The template pins checkout v4.2.2 to a verified commit rather than a movable tag. Check current security advisories and Gitea compatibility before activating; this is not a claim it is the newest release. Review/record future tool updates. Network access to the action source is required unless mirrored with verified provenance. The runner's registration token belongs in runner configuration/secrets, never git.
+
+Sources checked 2026-09-16: [Gitea runner overview](https://docs.gitea.com/runner/), [Gitea API reference](https://docs.gitea.com/api/1.24/), [pinned checkout commit](https://github.com/actions/checkout/commit/11bd71901bbe5b1630ceea73d27597364c9af683). Use documentation matching the actual server/runner versions; neither version has been inspected on the owner's server.

docs/INTEGRATION.md

@@ -0,0 +1,35 @@
+# Integration runbook
+
+The integrating engineer owns main, dependency direction, shared types, build settings, app composition and evidence quality. Feature agents own implementations within their briefs. Never delegate integration by asking every agent to edit project.pbxproj.
+
+## Before parallel dispatch
+
+1. Agree on the provisional brand/repository slug with the owner. Confirm TV identifier and exact software builds when hardware work starts.
+2. Tag a known baseline locally after checks; record SHA in the task roster. Prepare one worktree/branch per workstream. Shared worktree agents must be restricted to separate paths.
+3. Freeze v1 command types and add typed session handshake, TV connection state and injected storage/motion protocols. Provide fake implementations and representative fixtures first. Review error semantics, cancellation and ownership with A/B/C/E before coding production adapters.
+4. Wire adapter test targets and validate their platform availability. Keep platform-specific frameworks out of pure Swift algorithm modules.
+
+## Per PR
+
+Read the actual diff and test output, not just the agent summary. Confirm module ownership, no copied dependencies, no private APIs, no trust bypass, no replay and no unsupported background modes. Review concurrency around actor reentrancy and TV/session generation changes. Merge into an integration branch, resolve conflicts at the shared contract (never add a second near-identical type), then run `bash Scripts/check.sh --apps` against the combined commit.
+
+Compile success validates type/build integration only. Run actual phone-watch activation and TV pairing checks for adapters, with hardware evidence linked to that SHA. Keep failed checks and environmental limitations visible. Revert the smallest faulty PR or keep the feature explicitly in demo/disabled state until fixed. Do not broaden a tested-TV claim to other years/models.
+
+## Vertical slices
+
+| Milestone | Demonstration required | Exit condition |
+| --- | --- | --- |
+| M0 foundation | Demo apps + domain tests | Both targets compile, documentation consistent |
+| M1 named phone remote | TV prompts for Wristivo; phone right button moves selection | TLS policy, pairing/revocation and tokens verified |
+| M2 watch relay | Watch button moves selection through phone | Deadline/dedup, phone lock/wake and failure states measured |
+| M3 wrist input | Real right/left/up/down movements control menu | Gesture targets and lifecycle stop pass |
+| M4 product prototype | Setup, forget, recovery, accessible controls | Reproducible owner acceptance on named hardware |
+| M5 distribution | Signed beta and review package | Paid membership, rights/privacy/assets and all release gates |
+
+Each milestone is an evidence gate, not a deadline estimate. Do not promise release dates until M1–M3 retire the hardware risks. If phone-background reliability requires keeping the phone app open, make that constraint explicit and reassess product value before release.
+
+## Project and release management
+
+`Scripts/generate-project.rb` uses development-only xcodeproj 1.27.0; the generated project is committed. Keep changes deterministic, review diffs and build both schemes after regeneration. Signing overrides stay in ignored Config/Local.xcconfig. Never commit a developer team, certificate or token. Set owned bundle identifiers before provisioning; the `com.example` prefix is for scaffold builds only.
+
+Before a release tag, read RELEASE-CHECKLIST, compare privacy policy to code, run physical regressions, capture accurate screenshots and review video, then archive with the supported stable Xcode/SDK required at submission time. The currently installed toolchain is not proof of App Store SDK eligibility. Separate unsigned CI checks from signing/distribution jobs with minimal credentials. Gitea source hosting is independent of Apple membership.

docs/PLATFORM-FEASIBILITY.md

@@ -0,0 +1,72 @@
+# Platform feasibility
+
+Status: engineering assessment, researched 2026-09-16. This document does not certify hardware behavior or App Store acceptance. The repository scaffold is not a working TV remote yet.
+
+## Product promise and its boundary
+
+Wristivo is a proposed iPhone remote with an Apple Watch companion that turns deliberate wrist movements into TV navigation commands. The baseline requires a reachable paired iPhone and an active watch app. It does **not** promise continuous gesture recognition while the watch app is suspended, operation with the phone absent, or universal compatibility with every Tizen television.
+
+The highest-risk unknown is whether real-device foreground sessions and phone wake-up latency feel sufficiently convenient for watching television. Resolve that with a small hardware prototype before investing in full screens or marketing. If the experience is unacceptable, retain a conventional watch remote and revisit the product promise rather than hiding platform restrictions.
+
+## Verified platform facts and engineering decisions
+
+| Topic | Verified from Apple documentation | Project decision / remaining evidence |
+| --- | --- | --- |
+| Motion input | Core Motion supplies accelerometer, gyroscope, and processed device-motion data; hardware/service availability must be checked. [Core Motion](https://developer.apple.com/documentation/coremotion/), [CMMotionManager](https://developer.apple.com/documentation/coremotion/cmmotionmanager) | Use public device-motion APIs, classify locally on watch, and prove recognition using physical watches. Sensor APIs do not themselves recognize a TV-navigation gesture. |
+| Runtime | Ordinary watch apps can become suspended after the user lowers their wrist. Extended runtime categories serve specific activities. [Extended runtime](https://developer.apple.com/documentation/watchkit/using-extended-runtime-sessions) | Only arm while active. Immediately disarm on inactive/background transitions. Do not claim always-on or screen-off control. Never start a fake workout, audio stream, location session, or health session to keep this remote alive. |
+| Direct watch WebSocket | Apple classifies `URLSessionWebSocketTask`, Network framework connections, and Bonjour browsing as low-level watch networking with restricted supported uses. Ordinary HTTP(S) requests are a different category. [TN3135](https://developer.apple.com/documentation/technotes/tn3135-low-level-networking-on-watchos), [WebSocket task](https://developer.apple.com/documentation/foundation/urlsessionwebsockettask) | No direct watch-to-TV WebSocket adapter in the baseline. API availability or success under a debugger is not evidence of a supported production path. |
+| Phone relay | Activated Watch Connectivity sessions support immediate messages to reachable counterparts. A message from an active watch app can wake its companion iOS app in the background; messages can still fail. [sendMessage](https://developer.apple.com/documentation/watchconnectivity/wcsession/sendmessage(_:replyhandler:errorhandler:)), [reachability](https://developer.apple.com/documentation/watchconnectivity/wcsession/isreachable) | Watch emits commands; iPhone owns TV connection, credentials, and pairing. A wake-up is not a guarantee of an indefinitely resident phone socket. Test reconnect and deadline behavior with the phone locked and suspended. |
+| Deferred transfer | Watch Connectivity also offers queued background transfers and latest-state synchronization. [WCSession](https://developer.apple.com/documentation/watchconnectivity/wcsession) | Use latest-state synchronization for selected TV and preferences. Never put button presses in deferred background transfers: delayed navigation is incorrect behavior. |
+| System double tap | On supported Apple Watch hardware, watchOS 11+ lets a visible button-like control be designated the scene's primary action. [Double tap](https://developer.apple.com/documentation/watchos-apps/enabling-double-tap) | Optional Select enhancement only. Do not claim access to arbitrary finger-pinch recognition or depend on double tap on all supported watches. |
+| Accessibility | AssistiveTouch can navigate ordinary accessible watch interfaces through system-managed hand gestures. [Accessible watchOS experiences](https://developer.apple.com/videos/play/wwdc2021/10223/), [gesture design](https://developer.apple.com/design/human-interface-guidelines/gestures/) | Keep native accessible buttons for every action. AssistiveTouch is a user-controlled alternative, not an app-owned gesture recognizer or an entitlement to background execution. |
+
+## Baseline data path
+
+```text
+Apple Watch active app
+  -> Core Motion samples
+  -> local calibrated classifier and command gate
+  -> WatchConnectivity immediate message
+  -> iPhone validates command, target, freshness and duplicate status
+  -> iPhone TV transport
+  -> compatible TV
+```
+
+The iPhone returns a correlated result. A transport write is not proof that the TV visibly executed a command. UI and logs must distinguish local recognition, relay acceptance, transport submission, and failure; claim device execution only if the TV protocol provides adequate confirmation. Use the repository's shared contracts rather than creating another wire format.
+
+TV transport compatibility, pairing consent, token storage, and TLS handling are separate integration gates. No motion code may embed Samsung protocol details. No TV credentials or raw motion history need to cross the watch relay.
+
+## Session and lifecycle rules
+
+1. Watch launches into a disarmed state. Show selected TV and phone availability.
+2. User opens gesture mode, calibrates, and explicitly arms. Show persistent armed status and a large Stop control.
+3. Stop sampling and invalidate pending candidates on scene inactivity, lost relay reachability, target change, sensor failure, or user stop.
+4. A foreground return never replays old commands or silently re-arms. Require explicit resumption and a neutral pose.
+5. If the phone cannot process a command before its contract deadline, reject it. Do not accumulate gestures while reconnecting.
+6. Keep iPhone setup and local-network permission interactions in the iPhone UI. During normal watch operation, explain phone or TV disconnection clearly.
+
+An Always On display is not a promise of continuous application execution. Hardware trials must launch from the watch Home Screen without Xcode attached: Apple explicitly notes that debugging changes suspension behavior. [Watch Connectivity sample](https://developer.apple.com/documentation/watchconnectivity/transferring-data-with-watch-connectivity)
+
+## Physical-device feasibility gate
+
+Record watch model, wrist/crown orientation, watchOS version, iPhone model/iOS, TV model/year/firmware, Wi-Fi topology, build commit, and whether a debugger is attached. Start with the user's devices; add at least one watch without system double tap and another TV generation before broad compatibility claims.
+
+Initial user-reported hardware is Apple Watch Ultra 2 and iPhone 13 Pro Max, each on a recently released/latest OS whose exact version must be recorded from Settings. The TV may be a Samsung QA85Q8FAAUXZN, 85-inch non-OLED; that model identification is explicitly unconfirmed. Read the model code and firmware from the TV's Settings before choosing a compatibility fixture. The integration owner verified Xcode 27, Swift 6.4, and SDK 27 on the development Mac. **No physical-device or TV behavior has been tested.**
+
+| Experiment | Proposed acceptance criterion; not a measured result |
+| --- | --- |
+| Active gesture-to-TV navigation | Recognition precision >= 98%, recall >= 90% per direction; measure separately by wrist/orientation. Detailed trial procedure is in `GESTURE-SPEC.md`. |
+| Responsive control | Warm-path motion completion to visible TV action p95 <= 700 ms. Record classifier, relay, and transport timings separately. |
+| Locked phone, background phone, cold reconnect | Each case documented with latency and success rate. No stale command may execute after its deadline. If reliability fails, disclose phone requirements and fix or narrow scope before release. |
+| Lowered wrist, watch face, notification interruption, app switch | Sampling/dispatch cease on inactivity; zero old commands on resume. Measure actual usable session length. |
+| Connection loss and retries | Zero automatic duplicate presses; no command queue drains on reconnection. Result ambiguity must not trigger a blind resend. |
+| Battery | Measure a 30-minute repeated-use script and an idle/disarmed control run on each watch. Proposed target: <= 10 percentage points incremental battery loss per hour; report actual results and revise before advertising endurance. |
+| Accessibility | Every remote action remains reachable with touch and VoiceOver; motion can be disabled. Test AssistiveTouch behavior with the system settings the user chooses. |
+
+Do not equate a simulator, mock TV, or unit-test pass with completion of this gate. Phone relay wake-up and wrist suspension require physical hardware.
+
+## Alternatives and change control
+
+Direct watch-to-TV WebSocket is rejected for the baseline due to documented networking restrictions. A future supported HTTPS remote service would be a separate architecture with its own latency, authentication, privacy, provider-contract, and internet-dependency review; do not silently substitute a cloud service. Request an architecture decision before adding one.
+
+Recheck cited Apple documents at the hardware spike and before submission. If a future OS introduces an applicable public remote-control runtime or network capability, evaluate it explicitly and keep the current fallback until real devices prove it.

docs/PRODUCT.md

@@ -0,0 +1,40 @@
+# Product brief
+
+Status: proposed v1, 2026-09-16. Owner: Sami; integration: coordinating software engineer.
+
+## Outcome
+
+While wearing Apple Watch, intentionally move the wrist right/left/up/down to issue the corresponding TV remote press without picking up a physical remote. Opening the watch app and arming the session may require interaction. A reachable companion iPhone relays the commands on the home network. Prefer predictable control over continuous gesture availability.
+
+## First hardware cohort
+
+- Apple Watch Ultra 2, user reports recently released watchOS; exact version/build pending.
+- iPhone 13 Pro Max, user reports latest iOS; exact version/build pending.
+- Mac with Xcode 27.0 (27A266a), Swift 6.4, iOS/watchOS SDK 27 verified locally.
+- User believes TV is QA85Q8FAAUXZN, 85-inch non-OLED. Samsung lists that exact identifier as the 2025 Q8F QLED. Physical label/settings and firmware are not verified. [Samsung product page](https://www.samsung.com/ae/tvs/qled-tv/q8f-85-inch-qled-4k-smart-tv-qa85q8faauxzn/).
+
+Do not substitute a Tizen version or exact OS version based on the product year or the word "latest". Record these from Settings during testing.
+
+## v1 scope
+
+1. iPhone manual TV address entry; explicit local-network access; pairing prompt with the Wristivo controller name; denial, timeout, revoke and re-pair flows.
+2. Single selected TV; accessible iPhone and Watch D-pads, Select, Back, Home and supported playback/volume buttons.
+3. Watch calibration for left/right wrist and watch orientation. Start/stop session, four discrete directional motions, acknowledgement feedback, visible pause/failure state.
+4. On-device token storage, forget-TV action, no account or cloud dependency, no analytics by default.
+5. Honest demo mode for exploration and review, plus instructions for actual hardware.
+
+Select begins as a touch action. Supported system double tap may activate a primary Select button after separate watchOS 11+ validation. Do not advertise custom finger recognition. The Ultra 2 Action button is not assumed to be available for arbitrary third-party remote actions.
+
+Not in v1: always-on/background wrist sensing, watch-only operation, streaming/mirroring, keyboard entry, voice, TV app installation, Bluetooth HID impersonation, service-menu keys, power gestures, purchases, accounts or subscriptions. Discovery and Wake-on-LAN are follow-up capabilities after manual pairing works; neither is essential to the first hardware milestone.
+
+## User journeys
+
+**First setup:** connect phone and TV to a reachable home network → enter TV address → explain why local access is needed → initiate pairing → approve named controller on TV using an existing remote or TV controls → store token → press a test direction → confirm result. Initial authorization can require the existing TV remote.
+
+**Watch control:** open app → see selected TV and relay state → calibrate if needed → arm → one deliberate movement produces one directional click → return to neutral before another → stop manually or automatically when app becomes inactive. A disconnected phone shows an actionable message; movements are discarded.
+
+**Failure:** distinguish denied permission, TV off, network isolation, phone unreachable, expired pairing, uncertain send and unsupported TV. Never silently queue a movement for later execution.
+
+## Gates
+
+P0: pair and execute physical TV navigation from phone; no trust bypass. P1: physical watch button through phone relay including phone-lock/relaunch cases. P2: calibrated wrist directions meet the recognition and latency targets in GESTURE-SPEC. P3: usability with normal wrist-lowering, battery and interruption tests. P4: accessibility, support, privacy/IP clearance and review evidence. If P1 or P3 fails, resolve the product limitation before expanding features or publishing hands-free claims.

docs/RELEASE-CHECKLIST.md

@@ -0,0 +1,61 @@
+# Release checklist
+
+Status: planning baseline, not submission-ready. Owner: integration/release engineer, with product owner sign-off. Official sources checked 2026-09-16; recheck before submission. A checked list cannot guarantee App Review approval.
+
+## 1. Prototype without paid enrollment
+
+Xcode development and personal-device testing can begin using a free Apple Account. Apple documents Personal Team limits of 10 App IDs, three test devices per platform, and seven-day provisioning; its account help also lists three installed apps per device. Expect to rebuild/reinstall periodically. Multiple app targets consume signing resources: verify this project's actual iPhone/watch installation on the intended devices before allocating more identifiers. [Membership comparison](https://developer.apple.com/support/compare-memberships/), [account help](https://developer.apple.com/help/account/basics/about-your-developer-account).
+
+- [ ] Install a compatible Xcode release and its iOS/watchOS simulator runtimes on a Mac.
+- [ ] Keep signing team and bundle prefix configurable; do not commit a developer's account, certificate, private key, or provisioning profile.
+- [ ] Run shared-package tests and simulator UI checks before device installation.
+- [ ] Install on a paired physical iPhone and Apple Watch; real wrist motion, lifecycle transitions, WatchConnectivity delivery, and local TV access need hardware evidence.
+- [ ] Verify every requested capability is available to the Personal Team; remove nonessential capabilities rather than making a paid feature a prototype dependency.
+- [ ] Keep this stage as personal development. Plan paid enrollment before TestFlight or App Store distribution. Apple's published annual fee is USD 99 or local equivalent where offered. Decide whether the seller should be the individual or a qualifying legal organization before enrollment. [Membership comparison](https://developer.apple.com/support/compare-memberships/).
+
+## 2. Hardware feasibility gate
+
+These are project acceptance criteria, not claims that the prototype already passes:
+
+- [ ] Record tested iPhone model, Watch model, OS versions, TV model/year, Tizen/firmware version, and network conditions.
+- [ ] Demonstrate left/right/up/down wrist gestures reaching the intended TV commands, including left/right wrist configuration and calibration.
+- [ ] Demonstrate neutral motion, return-to-neutral, refractory interval, deliberate arming, visible armed state, and immediate disarm. Ordinary arm motion must not produce repeated commands.
+- [ ] Demonstrate manual button alternatives on both devices. Do not require wrist mobility for essential operation.
+- [ ] Demonstrate pairing approval on the TV under the name **Wristivo**, rejection, token revocation, reconnection, and forgetting a TV. Never simulate successful pairing in live mode.
+- [ ] Measure command latency, false positives, duplicate suppression, battery usage, and thermal behavior against the targets in the test plan; attach the actual results.
+- [ ] Prove behavior when the phone locks, app backgrounds, watch display sleeps, Wi-Fi changes, or TV powers off. Stop gesture capture and clearly report unavailable control when the supported session ends.
+- [ ] No fake workout, audio, location, or other unrelated background activity to keep a remote session alive. Do not promise all-day gesture listening.
+- [ ] Distinguish app-level send success from TV acknowledgement and actual screen response; show honest status.
+- [ ] Publish only tested compatibility claims. A protocol observed on one TV is not proof that every Tizen TV supports it.
+
+Apple requires intended use of public APIs and background modes. Its review rules also address power use and accurate metadata. Check sections 2.4, 2.5, and 2.3 when implementing the above project controls. [App Review Guidelines](https://developer.apple.com/app-store/review/guidelines/).
+
+## 3. Privacy and security gate
+
+The intended baseline is local processing, no account, no advertising SDK, and no developer-operated telemetry backend. Treat this as a design target until verified from the shipping build.
+
+- [ ] Inventory raw motion samples, calibrated thresholds, gesture events, TV names/IPs, pairing tokens, command history, error logs, diagnostics, support messages, and every SDK/network destination.
+- [ ] For each item, document purpose, location, recipients, retention, deletion, and whether it leaves a device. Review Watch-to-phone and phone-to-TV transfers explicitly.
+- [ ] Keep raw motion ephemeral by default. Any development recording requires deliberate opt-in, visible recording state, bounded retention, and a delete/export control; exclude recordings from release bundles.
+- [ ] Keep pairing credentials in appropriate secure storage, redact logs, scope trust decisions to the selected TV, and test reset/revocation. Do not introduce a global TLS certificate bypass.
+- [ ] Verify actual permission usage and localized purpose strings; request local-network/motion permissions only where the chosen API and platform require them. Test denial, later revocation, and recovery.
+- [ ] Produce the privacy policy from the implemented data inventory, identifying operator/contact, uses, sharing, retention/deletion, consent withdrawal, and support-data handling. Host it at a stable public URL and expose it inside the app and App Store Connect. [App Review preparation](https://developer.apple.com/app-store/review/), [guideline 5.1.1](https://developer.apple.com/app-store/review/guidelines/#privacy).
+- [ ] Reconcile App Store privacy answers with the actual behavior of the app and its partners. Apple's collection definition concerns off-device transmission with developer/partner access beyond servicing the request; local storage alone is not automatically collection under that definition. Do not select “Data Not Collected” without auditing diagnostics, support uploads, and dependencies. [App privacy details](https://developer.apple.com/app-store/app-privacy-details/).
+- [ ] Audit each executable target and dependency for required-reason APIs. Common persistence choices, such as UserDefaults, can introduce required declarations; choose approved reasons matching actual usage rather than copying a generic code.
+- [ ] Add accurate `PrivacyInfo.xcprivacy` files to applicable target resources, verify SDK manifests/signatures where required, generate Xcode's privacy report, and inspect the archive. An empty manifest or `tracking=false` is not evidence of compliance. watchOS is included in required-reason API reporting. [Privacy manifests](https://developer.apple.com/documentation/bundleresources/privacy-manifest-files), [data-use declarations](https://developer.apple.com/documentation/bundleresources/describing-data-use-in-privacy-manifests).
+
+## 4. Review package and finished product
+
+- [ ] Paid program enrollment, final identifiers/signing, distribution build, archive validation, current SDK submission requirements, age-rating answers, export-compliance answers, support contact/URL, and territory-specific business disclosures are complete. Resolve these from current App Store Connect requirements at release.
+- [ ] Complete the brand/IP gate in [BRAND-AND-IP.md](BRAND-AND-IP.md).
+- [ ] Verify VoiceOver labels, readable text, non-color status cues, comfortable gesture instructions, haptics alternatives, and manual fallback.
+- [ ] Remove placeholders and debug controls; verify clean installation, upgrades, permission-denied paths, network errors, and both supported minimum/current OS versions.
+- [ ] Provide review notes listing tested TV models/firmware, setup steps, on-TV approval, network prerequisites, gesture calibration/arming, lifecycle limits, and known unsupported behavior.
+- [ ] Supply an unedited demonstration video showing the real phone, worn Watch, wrist motions, and TV response. Arrange hardware access if Apple requests it. A difficult hardware setup may require a video or hardware during review. [App Review preparation](https://developer.apple.com/app-store/review/).
+- [ ] Include a clearly labelled **Demo TV — simulated** mode to let users/reviewers inspect pairing guidance and command feedback without a TV. It must never claim real TV connectivity. Explain it in review notes and preserve the same behavior for reviewers and customers. This does not substitute for a complete working app or requested hardware evidence.
+- [ ] Ensure screenshots and descriptions match measured functionality. Keep hardware demonstration footage for review separate from public App Store preview-format requirements.
+- [ ] Keep monetization out of the prototype. Before adding it, review current payment rules and guideline 4.10: built-in sensor access itself must not be the paid product. Review any later remote-app paid feature proposal separately. [App Review Guidelines](https://developer.apple.com/app-store/review/guidelines/).
+
+## 5. Integration sign-off record
+
+For each release candidate, create a dated record containing commit SHA, build numbers, test artifacts, compatibility matrix, privacy report, dependency/license audit, brand clearance decision, open defects, review notes, and responsible sign-offs. No unchecked hardware, privacy, IP, or signing gate should be disguised by a demo or mocked result. The owner chooses submission timing after the integration engineer reports the evidence and remaining limitations.

docs/SAMSUNG-INTEGRATION.md

@@ -0,0 +1,33 @@
+# Samsung TV integration and controller identity
+
+Status: researched protocol proposal, no physical validation yet. Date: 2026-09-16.
+
+## What "register as a controller" means here
+
+The intended app advertises `Wristivo` as its local network controller name during a pairing request. A compatible TV may show the name in its access prompt and device list, then issue a reconnect token after the user allows it. We must verify the exact behavior on the owner's TV. This is not a Bluetooth HID pairing, Smart Remote certification, Samsung partnership, or registration of a Tizen application. No TV application installation is planned.
+
+Samsung's official TVInputDevice API lets a TV-side app receive key events. It is not a phone API to inject system-wide keys. Smart View documentation describes connected sender/receiver experiences; do not infer that it guarantees a supported universal remote endpoint. [Samsung TVInputDevice API](https://developer.samsung.com/smarttv/develop/api-references/tizen-web-device-api-references/tvinputdevice-api.html), [Samsung Smart View overview](https://developer.samsung.com/smarttv/develop/extension-libraries/smart-view-sdk/introduction.html).
+
+## Compatibility adapter
+
+The planned socket endpoint is `wss://<user-selected-TV>:8002/api/v2/channels/samsung.remote.control` with `name` containing Base64 UTF-8 client name and a URL-encoded optional `token`. Use URLComponents, never concatenate token-bearing URLs into logs. The pure package encoder is a unit-testable protocol seam, not an implemented secure transport.
+
+Community maintainers describe a TLS port 8002, named clients and token reuse; support differs by TV/firmware. Their project is primary evidence for its own implementation, not an official Samsung API guarantee. Do not vendor or copy its LGPL implementation. [Maintainer project](https://github.com/xchwarze/samsung-tv-ws-api), [maintainer command reference](https://github.com/xchwarze/samsung-tv-ws-api/blob/master/COMMANDS.md). This project's JSON encoding is independently written; protocol strings alone do not establish legal clearance for every distribution market.
+
+Typical click frame fields to validate on hardware: method `ms.remote.control`; params Cmd `Click`, DataOfCmd mapped key, Option `false` as string, TypeOfRemote `SendRemoteKey`. Directional keys map to KEY_UP, KEY_DOWN, KEY_LEFT, KEY_RIGHT; Select to KEY_ENTER and Back to KEY_RETURN. Validate playback and volume independently; unsupported buttons must be hidden/disabled by capability evidence. No factory or service keys.
+
+## Pairing implementation sequence
+
+1. User enters an address; validate host-only input (no credentials, path, query or arbitrary scheme). Restrict discovery/connection to the chosen local TV; no subnet brute force. Start with same home network; guest isolation/VLAN routing may block access.
+2. Request iOS Local Network access in context using a meaningful NSLocalNetworkUsageDescription. Denied permission has a recoverable Settings explanation.
+3. Establish a scoped TLS trust policy as specified in SECURITY-PRIVACY. Default trust failure must not be silently ignored. Self-signed TV certs are a hardware investigation item.
+4. Start named pairing only from explicit setup UI. The television must be powered on; keep an existing remote available for the approval prompt. Bound pairing wait to 30 seconds (proposed, configurable).
+5. Parse bounded protocol events. Candidate events to verify: ms.channel.connect, ms.channel.unauthorized, ms.channel.timeOut and ms.error. A socket upgrade is not pairing approval. Do not send keys until authorization is confirmed; token location/format may vary and requires captured redacted fixtures.
+6. Store the token in iPhone Keychain associated with opaque TV identity and its trust record. Reconnect without repeating pairing where supported. Rejected/revoked tokens transition to explicit re-pair UI.
+7. Forget TV deletes token, trust record, selection and active session. Explain separate removal from the TV's device list if the user wants to revoke on the television too; menu labels vary by firmware.
+
+## Proof checklist
+
+Use Tests/Hardware/session-template.md. Confirm actual model/firmware, pairing label, denial, persistence after app relaunch/phone reboot, token revocation, TLS certificate behavior, every offered key, TV off, network drop, selected-TV switch, and repeated one-gesture-one-key behavior. Raw events must be scrubbed of tokens, IPs, identifiers and client lists before fixtures enter git.
+
+Public compatibility starts with only explicitly tested configurations. Do not advertise "all Samsung TVs" or infer working compatibility from Tizen alone. No silent port 8001 plaintext fallback in v1. TV wake is out of scope until network-standby and multicast restrictions are separately tested.

docs/SECURITY-PRIVACY.md

@@ -0,0 +1,42 @@
+# Security and privacy design
+
+Status: policy for production adapters; foundation demo performs no network or sensor access.
+
+## Threats and controls
+
+| Risk | Required design |
+| --- | --- |
+| Accidental motion / unexpected TV actions | Explicit foreground arm; neutral recovery; expiry; no power/purchase gestures |
+| Delayed/duplicated commands | Phone-issued session + target binding, UUID dedup, sequence, short lifetime; no automatic retry |
+| Hostile or malformed TV traffic | Event allowlist, payload limits, typed parser, bounded tasks, timeout; no execution of TV-supplied text |
+| Token leak | iPhone Keychain, no watch transfer or cloud sync, redacted logging including WebSocket URL query |
+| Local network impersonation | Normal TLS validation, or explicitly reviewed device-scoped first-use pinning; no blanket trust exceptions |
+| Old phone/watch pairing | WCSession activation lifecycle, new session on device switch/restart, fail closed on version mismatch |
+| Wrong TV / old connection | Stable local TV UUID, generation checks after awaits, cancel pending commands on switch |
+
+Self-signed certificates may be present on compatible TVs. Default trust must fail closed while that behavior is investigated. If the production design uses explicit first-use pinning, show the selected device and certificate fingerprint, record consent and pin only that device. A fingerprint learned from the same unauthenticated connection does not independently prove identity: first-use interception remains a limitation. Never claim pinning solves that first-contact problem. A changed certificate requires reapproval/re-pairing. Do not set global NSAllowsArbitraryLoads or accept all URLSession challenges. Document narrowly necessary ATS settings with real-device evidence.
+
+## Data inventory and retention
+
+| Data | Location | Retention / deletion |
+| --- | --- | --- |
+| TV nickname, local ID, address, capabilities | Phone local store (planned) | Until forget/reset; prevent unintended cloud sync |
+| TV token and trust pin | iPhone Keychain (planned) | Until forget/revoke/re-pair; device-bound policy |
+| Selected TV label and opaque ID | Watch context (planned) | Replace on selection; clear on forget |
+| Raw motion | Watch memory during active session | Discard immediately after bounded processing; no default recording |
+| Calibration preferences | Local watch/phone (planned) | User-resettable, no cloud sync by default |
+| Diagnostic metrics | Local bounded buffer (planned) | No identifiers/tokens/raw motion; explicit export only |
+
+No backend, account, ads, tracking or analytics SDK is included. Do not declare future data practices as implemented. If motion recordings are required for QA, ask explicit informed consent, store locally outside git, define deletion time and never upload by default. Export only redacted developer-selected evidence.
+
+Keychain accessibility must be chosen against actual locked-phone relay needs. Prefer device-only storage; evaluate WhenUnlockedThisDeviceOnly first and AfterFirstUnlockThisDeviceOnly only if justified by the supported workflow. Locked/unavailable Keychain is a recoverable error, not permission to cache plaintext credentials. Application context is never a credential transport.
+
+## Permissions and manifest
+
+Production phone setup will need NSLocalNetworkUsageDescription. Motion capture needs an accurate motion purpose string where required by the adopted API/platform. Add permission strings when adapters are introduced; the demo requests neither. Manual unicast address entry is the baseline. SSDP/multicast discovery and Wake-on-LAN may need separate Apple networking entitlement review; do not enable blanket capabilities speculatively. NSBonjourServices entries apply only to the actual Bonjour service types used, not generic SSDP.
+
+The current PrivacyInfo.xcprivacy describes the current demo's lack of tracking, collection and required-reason API declarations. It is not a release approval or a blanket policy for future code. Re-audit FileTimestamp/SystemBootTime/DiskSpace/UserDefaults and other required-reason APIs, dependency manifests and data flows after each adapter. Declare truthful approved reasons actually applicable to the implementation. The public privacy policy and App Store answers must match the final binary and include support/contact details before submission.
+
+## Security tests
+
+Test token revocation and deletion; changed/untrusted cert; unauthorized key send; malformed/oversize events; future/stale timestamps; lost/duplicate messages; wrong session/TV; phone reboot/first unlock; permission denied; network isolation. Never run service-menu or destructive raw-key tests. Secrets must be absent from repository history, screenshots and exported logs.

docs/SETUP.md

@@ -0,0 +1,29 @@
+# Developer setup
+
+## Prerequisites
+
+Mac with Xcode and the iOS/watchOS SDKs selected with xcode-select. The initial environment has Xcode 27.0 (27A266a), Swift 6.4, SDKs 27.0. The foundation declares Swift 6, iOS 17/watchOS 10/macOS 14; older supported device OS versions still need runtime QA. Do not interpret the build machine's SDK as the deployment minimum.
+
+The committed Xcode project opens directly. Regeneration only requires Ruby with the `xcodeproj` gem version 1.27.0 (`ruby Scripts/generate-project.rb`). It is a developer tool, not a dependency shipped in the app. The initial host already has that gem. New dependency/tool versions need reviewed lock/version updates.
+
+## Build and run demo
+
+1. Open Wristivo.xcodeproj, select Wristivo for the iPhone app or WristivoWatch for the companion.
+2. Run with a simulator if its runtime is installed. Buttons show local demo feedback; no TV receives anything.
+3. For physical installation, add your Apple Account in Xcode. Copy Config/Local.xcconfig.example to Config/Local.xcconfig, set DEVELOPMENT_TEAM and an owned unique WRISTIVO_BUNDLE_PREFIX. Do not commit that local file.
+4. Connect and trust the iPhone; enable Developer Mode when Xcode requests it. Pair the Ultra 2 normally with the phone and use Xcode's offered watch destination. Ensure both targets use the same team and that the watch's companion bundle ID matches the phone.
+5. Use a Personal Team while prototyping if those targets/capabilities provision successfully. Expect periodic reinstallation due to free provisioning limits; see RELEASE-CHECKLIST. Paid membership is needed for distribution, not to begin the source/simulator prototype.
+
+Development icons and Store metadata are deliberately not supplied as final assets. Do not archive this demo for review as a completed remote.
+
+## Command-line checks
+
+Run `bash Scripts/check.sh` for shared tests or add `--apps` for both unsigned generic-device builds. The script uses a temporary scratch directory to avoid Finder metadata and Swift build-cache permission issues under Documents; it deletes that scratch directory when finished. It disables nested SwiftPM sandboxing for this dependency-free, plugin-free package. Never extend that choice to unreviewed build plugins.
+
+Unsigned device builds do not install, prove runtime behavior, or require paid membership. Actual UI, motion, WatchConnectivity, phone background behavior and TV compatibility need signed physical testing. The first sandboxed environment could not access CoreSimulator services; see VALIDATION for actual checks and limitations.
+
+For this agent host only, `WRISTIVO_AGENT_BUILD=1 bash Scripts/check.sh --apps` opts out of nested Xcode package-manifest and Swift compiler macro sandboxing; the outer tool filesystem restrictions still apply. This was required to run the local package manifest and Apple's SwiftUI macros here. The normal Xcode project and CI do not set these overrides. Xcode also required a narrowly granted write permission to its `~/Library/Caches/org.swift.swiftpm` manifest cache, which ignored its package-cache path override. Do not use the agent override for unreviewed packages, macros or build plugins.
+
+## Future adapter setup
+
+Before implementing live services, the integrator adds their source/test memberships, permission strings, lifecycle composition and any justified capabilities. Avoid adding HealthKit, audio, VoIP, location or multicast entitlements merely to keep the app alive. Start with manual TV address entry and one known device. Keep real addresses/tokens and motion captures outside git.

docs/VALIDATION.md

@@ -0,0 +1,42 @@
+# Foundation validation record
+
+Initial validation: 2026-09-16; final verification: 2026-09-17. Scope: initial Wristivo source foundation, prior to live adapters.
+
+## Passed
+
+| Check | Evidence |
+| --- | --- |
+| RemoteCore tests | 6 Swift Testing tests passed: routing/schema, freshness/lifetime/skew, duplicate/sequence, bounded-memory replay protection, session reset, decoded-input validation |
+| SamsungProtocol tests | 3 tests passed: command frame encoding, safe candidate endpoint/token encoding, invalid host rejection |
+| GestureCore tests | 5 tests passed: direction mapping, disarm/expiry, neutral recovery/debounce, invalid/ambiguous input, invalid configuration |
+| Watch app | Unsigned generic watchOS Debug build succeeded, including RemoteCore + GestureCore |
+| iPhone app | Unsigned generic iOS Debug build succeeded, including SamsungProtocol and embedded watch app |
+| Project generation | Two consecutive regenerations produced identical project and scheme files; final regenerated targets both rebuilt successfully |
+| Privacy manifest | plutil syntax validation passed |
+| Documentation | Local links checked; independent architecture/agent-ownership review completed and admission ownership clarified |
+| CI template | YAML parsed locally; not executed on Gitea |
+
+Toolchain: Xcode 27.0 (27A266a), Apple Swift 6.4, iOS/watchOS SDK 27.0. The app deployment settings are iOS 17 and watchOS 10. Builds are not evidence of runtime behavior on those minimum versions.
+
+Reproduction on this sandboxed host:
+
+```sh
+WRISTIVO_AGENT_BUILD=1 bash Scripts/check.sh --apps
+```
+
+The full check first completed with exit status 0 on September 16. After fixing deterministic project generation on September 17, the 14 package tests passed again and both final app builds completed with exit status 0. The final app-only rerun used the same flags shown in Scripts/check.sh. Tests totaled **14 passing, 0 failures**; Xcode reported BUILD SUCCEEDED for both app checks. The package was also independently tested during its parallel implementation.
+
+## Environment limitations encountered
+
+Xcode required local Swift package manifest-cache write permission. Temporary scratch/cache paths avoided build artifacts carrying Finder metadata under Documents. Nested package-manifest and Apple SwiftUI macro sandbox startup failed inside the agent sandbox, so the documented opt-in developer-host overrides were used. These overrides are not set in the app's release build configuration or CI template. CoreSimulator access was unavailable; generic device SDK builds succeeded without simulator access. See SETUP for details.
+
+## Not performed / not implemented
+
+- No simulator launch, screenshot inspection, accessibility runtime audit or signed device installation.
+- No real iPhone/Watch relay, Core Motion classifier, actual gestures or TV pairing/control.
+- No physical verification of the tentative Samsung TV model, firmware or endpoint/certificate behavior.
+- No latency, battery, thermal, recognition precision/recall or App Store compatibility claims.
+- No distribution archive, TestFlight, paid-account setup, trademark clearance or legal approval.
+- No Gitea remote creation, authentication, push or CI execution. Owner will create the private repository.
+
+Current app behavior is explicitly a local demo. The raw-motion pipeline, live adapters, final signing, icons, privacy policy and submission materials remain future milestones. Use Tests/Hardware/session-template.md for dated evidence when those pieces are implemented. Never convert a pending test to passed because a unit test or compilation succeeded.

docs/agents/README.md

@@ -0,0 +1,65 @@
+# Parallel implementation plan
+
+The coordinating engineer is the integration owner. Agents implement focused branches against the shared package and mocks; they do not independently design whole apps. Copy the common brief plus one assignment below into each agent task.
+
+## Common brief to give every agent
+
+> Implement your assigned workstream for Wristivo. Read AGENTS.md, docs/PRODUCT.md, docs/ARCHITECTURE.md, docs/CONTRACTS.md and the relevant platform, gesture and security documents. Keep to owned paths and use shared domain types. Treat existing app views as explicitly labelled demos. Do not claim TV support or reliable motion recognition without real-device evidence. Propose shared contract/build changes to the integrator before implementing dependent code. Work on your branch, run focused tests, and hand back a reviewable diff, test results, hardware status and integration instructions. Do not push main or publish. No credentials or raw motion captures in git.
+
+## Ownership and deliverables
+
+| ID / branch | Exclusive paths | Deliverable | Depends on |
+| --- | --- | --- | --- |
+| A / feat/tv-transport | Adapters/TVTransport, package SamsungProtocol sources/tests | TV pairing, bounded socket actor, tested parser and click delivery | Agreed connection/trust contracts; owner TV access |
+| B / feat/watch-relay | Adapters/WatchBridge | WCSession activation, control-plane session handshake, live commands/receipts, failure handling | Frozen envelope + session DTOs |
+| C / feat/wrist-motion | Adapters/MotionCapture, package GestureCore sources/tests | Calibrated four-direction classifier, lifecycle stop, trace tests | Motion/gesture contract; physical Ultra 2 |
+| D / feat/phone-experience | Apps/iPhone | Manual setup, permissions, pairing states, accessible remote, forget/troubleshoot | Fake service first, A+E for live integration |
+| E / feat/secure-storage | Adapters/SecureStorage | Keychain token and per-TV trust records, delete/re-pair behavior | Integrator identity/security contract |
+| F / feat/watch-experience | Apps/Watch | Calibration, explicit arm/stop, accessible buttons, status and haptics | Fake service first, B+C for integration |
+| Q / test/hardware-release | Tests/Hardware, docs/test-evidence | Hardware matrix, accessibility, latency/false-positive/battery evidence | Integrated slices |
+| I / integration owner | All shared roots, RemoteCore, Package.swift, Apps/Shared, project, Config, Scripts | Contracts, composition, reviews, CI, combined builds, release gates | Every accepted PR |
+
+Package paths in the table mean `Packages/WristivoKit/Sources/<module>` and `Tests/<module>Tests`. A new adapter needs tests in an adjacent Tests directory; integrator creates target membership before the implementation branch starts. QA may run acceptance planning immediately, but must not edit another agent's tests or report planned cases as passed.
+
+## A — TV transport prompt
+
+> Implement an iPhone-only TV connection actor and pure bounded event parser. Use SamsungRemoteEncoder without copying a community implementation. Support explicit connect/pair/deny/timeout/revoke/disconnect, authorize before ready, serialize commands, consume admission once, recheck deadlines before sends, and cancel old-generation operations on TV/session changes. Integrate injected token/trust storage from E. No blanket TLS trust, arbitrary key API, silent plaintext fallback or replay on reconnect. Use synthetic redacted event fixtures for malformed/oversize/unknown/missing-token responses and fake socket tests for deadline, ordering and cancellation. Deliver a manual physical pairing script showing the name Wristivo, reconnect and revoke. Do not mark the TV compatible until the owner runs it. Begin with a hardware feasibility spike for the candidate endpoint and TLS policy before expanding UI dependencies.
+
+## B — Watch relay prompt
+
+> Implement separate iPhone and watchOS WCSession delegates with explicit main-actor UI updates and an injected reference to the single phone-side command actor owned by A/integration. Negotiate the phone-issued session and selected TV before enabling commands. Use only live sendMessage with bounded JSON payloads and exactly-once reply completion. Implement the documented milliseconds date strategy. Validate container version/types, payload size and structural decoding at the bridge. Delegate semantic version/session/target, expiry, sequence and duplicate admission to that one phone actor; B must not instantiate or consume a second CommandAdmission or maintain an independent authorized session. Do not use transferUserInfo to carry commands. Configuration snapshots may use application context, but carry no token or executable backlog. Provide fake-session tests for reachable/unreachable, activation/deactivation, phone/watch reinstall or switching, duplicate responses, timeouts and lost replies. Verify wake/locked-phone behavior on real hardware; simulator success is insufficient. Do not invent an unlimited iOS background service.
+
+## C — Wrist motion prompt
+
+> Implement Core Motion acquisition and a calibrated normalization/classification layer feeding GestureCore. CMMotionManager hardware availability and permission/error handling are mandatory. Coordinate axes must account for wrist side, crown orientation and neutral pose; don't integrate acceleration to pretend to know absolute hand position. Stop updates when inactive, disconnected, expired or cancelled. Re-arming starts a fresh neutral baseline. Use confidence/ambiguity rejection and one directional event per deliberate excursion. No custom finger pinch/clench or always-on claims. Keep samples in memory by default; use synthetic fixtures and separately consented local physical recordings for evaluation. Report direction-specific precision/recall, incidental-movement false triggers and a confusion matrix. Existing normalized gate is a seam, not proof of a complete classifier.
+
+## D — iPhone experience prompt
+
+> Build the onboarding/manual-address/pairing/status/remote/forget-TV experience with SwiftUI and injected services. Initially use a clearly named fake and explicit Demo mode. Show truthful success and recoverable permission/network/authorization errors. Keep protocol strings, token handling and network state out of Views. Provide accessible labels, sufficient touch targets, Dynamic Type, VoiceOver order, contrast and layout on iPhone 13 Pro Max plus smallest supported phone and iPad compatibility layouts. Ask for local network permission only when setup needs it. Do not add camera, location, tracking or account prompts. Supply UI checks against fake states and document service wiring for the integrator.
+
+## E — Secure storage prompt
+
+> Implement injected Keychain persistence scoped to opaque TV ID. Keep tokens, certificate trust material and pairing state on iPhone, not Watch or cloud. Propose the narrowest Keychain accessibility compatible with tested phone-lock relay; do not assume first-unlock access is always available. Test add/read/update/delete/not-found/locked/error cases with a mock Security client; run true Keychain behavior on a signed device. Implement forget-TV and certificate-change reapproval semantics. Never implement accept-all TLS. Initial self-signed certificate trust must be visibly user-approved and pinned per TV, with an honest first-use trust explanation; when no authenticated fingerprint source exists, record that limitation. Pair with A on the security boundary through frozen protocols.
+
+## F — Watch experience prompt
+
+> Build small-screen setup status, calibration instructions, explicit start/stop, D-pad, Select/Back and haptic feedback. Integrate C's motion service and B's command sink via the integrator's injected view model. Inactive scene/reachability loss/TV switch always stops sensing and disarms. Feedback distinguishes recognized gesture, transmitted command and failed/uncertain send; no false TV confirmation. Touch operation remains usable without motion permission. Add watchOS 11+ system double tap primary Select action only behind availability checks and physical Ultra 2 tests. Avoid arbitrary Action-button or system wrist-flick assumptions. Verify left/right wrists, large text, VoiceOver and the smallest watch supported by the declared deployment target.
+
+## Q — Hardware and release prompt
+
+> Turn Tests/Hardware/session-template.md and the platform/gesture/release gates into dated evidence for the integrated commit. Record exact devices, OS builds, TV model/firmware and network topology. Test pairing denial/revocation, locked/suspended phone, inactive watch, reboot, time skew, duplicates, packet loss and ordinary movements. Report measured failures as well as successes. Audit privacy declarations against actual APIs/SDKs, labels/assets for rights and accessibility, and release notes for unsupported claims. Do not distribute beta builds until developer membership and signing support are available.
+
+## Scheduling and integration
+
+Maximum useful initial parallel work: A, B and C while I freezes seams and validates combined builds. With four total agent slots, do not start six agents at once. E can precede A's production trust/storage phase or replace an idle slot; D and F can develop UI against mocks once seams freeze. Q starts the test plan early and runs physical tests after slices merge. These dependencies are deliberate; "everything in parallel" without fixed contracts increases rework.
+
+Before dispatch, I creates a branch/worktree from the same baseline commit and records owner, base SHA, paths, contract revision, prerequisites and acceptance tests in the coordination table below. Each PR is small enough for one integrated behavior. Merge E/security contracts → A phone slice → B relay slice → C gesture slice → D/F composition → Q release fixes. Pure UI or test fixtures may merge earlier if they do not alter live behavior.
+
+| Workstream | Owner/task | Base SHA | State | Evidence / blockers |
+| --- | --- | --- | --- | --- |
+| A–Q implementation | Unassigned | Set at dispatch | Planned | Requires hardware and agreed contracts |
+| I foundation | Coordinating engineer | Initial repository | Prepared | See VALIDATION.md |
+
+## Merge acceptance
+
+A PR may be merged with explicitly documented hardware gates outstanding, but cannot be tagged as a hardware-complete milestone or release. Required before normal merge: no contract drift, no out-of-scope paths, focused checks pass, no credentials/provenance issues, and the integrator's combined package + both app builds pass. Only the owner and integrator decide product scope changes.

docs/decisions/0001-platform-and-scope.md

@@ -0,0 +1,19 @@
+# ADR-001: paired phone relay and explicit wrist sessions
+
+Date: 2026-09-16. Status: accepted as the architecture baseline; hardware feasibility pending. Owner: integration engineer.
+
+## Context
+
+The user wants wrist movements on Apple Watch to control a Samsung Tizen TV, a native iPhone companion, parallel AI implementation, private Gitea source hosting, and later App Store release. Initial devices are Ultra 2, iPhone 13 Pro Max and a tentative QA85Q8FAAUXZN television. Paid Apple developer membership is deferred until the prototype is useful.
+
+## Decision
+
+Use watch Core Motion while explicitly active, semantic commands over live WatchConnectivity, and an iPhone-only paired TV WebSocket transport. Keep pure protocol/gesture/admission logic in a dependency-free Swift package. First pair by manual TV address. Provide native accessible touch alternatives and an honest demo. The baseline has no server/cloud dependency, TV app, direct watch socket, always-on gesture listener, background-mode workaround, streaming, or subscription.
+
+## Reason and consequences
+
+Apple's low-level watch networking restrictions exclude a general TV-remote WebSocket. Ordinary runtime also cannot guarantee background motion processing. The phone therefore remains required and locked-phone relay responsiveness is a critical experiment. TV protocol support and certificate behavior need physical validation before promising compatibility. Active sessions may be less convenient than the original all-day hands-free idea; measure usability early rather than building around an unsupported promise.
+
+Parallel agents can work through domain contracts and fakes, but the integration owner must freeze session/connection/storage/motion interfaces and build membership before live adapter branches diverge. Firmware or OS discoveries may require a new ADR; no agent may silently replace the relay with a cloud service or fabricate an entitlement.
+
+Evidence: [Apple TN3135](https://developer.apple.com/documentation/technotes/tn3135-low-level-networking-on-watchos), [WatchConnectivity sendMessage](https://developer.apple.com/documentation/watchconnectivity/wcsession/sendmessage(_:replyhandler:errorhandler:)), [watch runtime guidance](https://developer.apple.com/documentation/watchkit/using-extended-runtime-sessions). Detailed limits and hardware experiments are in PLATFORM-FEASIBILITY.md.