# Android Device Link P2P Plan

## Summary
- Bring the existing Device Link foundation into `development` and finish the Android side of the documented P2P/device communication slice.
- Match the MacBook app contract: one shared Device Link model, explicit short-lived pairing, local identity, route probes, relay configuration, and capability controls.
- Add Android-native local-network discovery/advertising using NSD behind the existing Android Device Link store, while keeping Iroh FFI and relay binaries behind a documented future transport adapter.

## Verified Starting Point
- `codex/device-link-worldwide` contains the unmerged secure Device Link foundation:
  - shared contracts in `flow/contracts/src/device-link.ts`;
  - Mac controller/preload/main Device Link bridge;
  - web Devices surface;
  - Android `DeviceLinkSection` and `DeviceLinkStore`;
  - architecture/status docs.
- Current `origin/development` does not include `DeviceLinkSection`, `DeviceLinkStore`, or `docs/architecture/device-link.md`.
- The branch docs list Android follow-up: Kotlin Iroh FFI, Android NSD discovery, Keystore-backed relay-token signing, Android background behavior, and physical Android-to-Mac QA.
- Current official Iroh docs list Kotlin/JVM + Android as supported, but the Kotlin FFI Android setup still requires NDK/Rust build plumbing. That dependency needs a dedicated build/package slice, not a hidden one-file addition.
- Android official NSD docs cover local service broadcast/discovery/resolve for peer-to-peer local network apps, which fits the immediate Android side of same-network pairing and route probes.

## Scope For This Slice
- In scope:
  - integrate the existing Device Link foundation from the preserved branch;
  - add Android NSD-backed local peer advertising/discovery as a bounded, lifecycle-controlled service;
  - expose discovered local peers in the Android Device Link snapshot/routes;
  - keep relay tests truthful and user-owned only;
  - add source/unit tests and Android build validation;
  - update docs and memory so future agents can continue the Iroh/relay transport slice.
- Out of scope for this slice:
  - adding Rust/NDK-generated Iroh FFI binaries to the APK;
  - building or shipping a ZoneGaze-hosted relay;
  - enabling command execution between devices;
  - claiming full remote internet P2P until the native transport and relay are implemented and physically tested.

## Architecture
- `flow/contracts`: owns portable Device Link schema and bridge method names.
- `platforms/desktop`: owns Mac identity persistence through Electron safeStorage and native bridge IPC.
- `platforms/android`: owns Android identity, Android Keystore keys, NSD discovery, bridge JSON, and native Devices UI.
- `flow/web`: owns the shared Matrix Devices surface and calls only the Matrix platform bridge.
- Android NSD stays behind `DeviceLinkLocalDiscovery`; `DeviceLinkStore` consumes snapshots and does not know Android platform callbacks directly.
- Long-running discovery is opt-in and stopped when the app/view no longer needs it. Idle Android behavior must stay quiet.

## Completion Notes
- The existing Device Link foundation was adapted onto the current Android Matrix drawer/bottom-nav structure.
- Android now has `DeviceLinkLocalDiscovery`, a lifecycle-bound `NsdManager` adapter for `_zonegaze-device-link._tcp.` services.
- `DeviceLinkSnapshot` now includes `localPeers`; Android fills it from resolved NSD peers and desktop returns an empty list until its matching local-discovery adapter is added.
- The direct LAN route is now `ready` only when Android has resolved at least one same-network peer; otherwise it is `not-configured` with pairing guidance.
- The direct internet route remains blocked until Kotlin Iroh FFI/Rust/NDK packaging is implemented and physically verified.

## Tasks
1. Merge/adapt Device Link foundation onto current `origin/development`.
2. Add failing Android tests for:
   - Device Link source files and bridge methods exist;
   - Android local discovery exposes NSD service type and lifecycle methods;
   - route probes report same-network discovery truthfully instead of a hardcoded “next slice” blocked message.
3. Implement Android `DeviceLinkLocalDiscovery`:
   - service type `_zonegaze-device-link._tcp`;
   - register this device while pairing is active;
   - discover and resolve matching peers;
   - expose peer id/name/host/port/updated time through store JSON;
   - stop discovery/registration safely.
4. Wire Android UI/bridge:
   - Devices tab/card in the native shell;
   - bridge methods for snapshot, pairing, relay config, route tests, capabilities, and revoke placeholders;
   - copy actions for invite/relay notes.
5. Update docs:
   - architecture doc with implemented Android NSD boundary and remaining Iroh transport work;
   - Android app guide with Device Link behavior;
   - memory status with verification and blockers.
6. Validate:
   - focused Android source/unit tests first;
   - `:app:testDebugUnitTest` and `:app:assembleDebug`;
   - relevant contract/web/desktop checks if the merged foundation touches those packages;
   - emulator install/smoke if native Devices UI changes are reachable.

## Acceptance Criteria
- Android has a real Devices surface, not just docs.
- Android bridge exposes Device Link methods compatible with the shared Matrix bridge.
- Android local discovery is represented by code and tests, not only a future note.
- Snapshot JSON clearly distinguishes ready/not-configured/blocked route states.
- No company-hosted relay, public directory, or command-execution default is introduced.
- All touched checks pass or any skipped check has a concrete environment reason and residual risk.
