find my device: the design, and what it can never do

sketched the same day push landed, because push is the piece that makes it
possible at all — there is no other way to reach a sleeping phone.

more of it exists than expected: the wake channel, a working maplibre map with
clustering in the photos plugin, and headscale already reporting online and
lastSeen per node, which covers laptops without an app at all. what is missing
is a table, an endpoint, some app code and a panel.

what it can never do is stated up front rather than discovered later. apple's
offline finding works because a billion strangers' devices relay a lost
phone's bluetooth beacon. there is no self-hosted version of a crowd. off-grid
gets you last-known-position; powered-off gets you nothing.

two things i expect someone to get wrong, so they are called out above the
schema:

- do NOT key location on the push token. apns tokens rotate, the registration
  path is already an upsert because of it, and a history keyed to one silently
  forks into two devices. this needs a stable on-device uuid and a `devices`
  table that is not push_devices — which is worth building anyway, since the
  push registry currently has no stable device identity at all.
- store accuracy and draw the circle. ios returns 3km fixes when it is being
  cheap, and rendering one as a confident pin sends someone to the wrong street.

the sharpest open question is not technical: the owner bypasses every
permission check by design, so on a family server the owner can see a member's
location structurally, unless location is given an explicit exception. that
falls out of the architecture rather than out of anyone's intent, so it should
be decided deliberately.

retention likewise. a location table is a complete movement record, apple
deliberately cannot build one, and self-hosting means choosing to. the rule
belongs in the design, not in a settings screen added afterwards.

CLAUDE.md

@@ -421,6 +421,9 @@ explaining why it was safe.
 
 - `docs/navigation-audit.md` — **authoritative** on routing/navigation: the opaque-click anti-pattern,
   a severity-ranked findings table, the channel-selection map and the four-phase plan
+- `docs/find-my-device.md` — **design, not built**: locating your own devices from Officer. What is
+  assembly (most of it), what is impossible (offline finding — there is no crowd to relay it), and the
+  question to settle first, which is retention rather than anything technical
 - `docs/affordances.md` — what an affordance is, the three tests for whether something qualifies (including
   the one that catches most bad ones: _can it be fixed instead?_), the file format, and how they reach the
   agent. Read before writing one