push notifications: the app-side spec

the 2026-07-31 design promised this document to `officer-suite/COMMS/`, a repo
path that has never existed. writing it where the work is instead, to be
handed to whoever builds the client.

exact contracts rather than prose: the three device routes with real request
and response shapes read off devices.ts, what is required versus defaulted,
and that the server takes the user from the session and ignores a userId in
the body.

most of it is the failure modes that cost a day each and are invisible from
the client — a send with no credentials configured returns success and
delivers nothing; a sandbox token registered as production fails at apple with
no user-visible symptom; the notification extension must not touch the network
or it will pass every test at a desk and fail on cellular with the vpn off.

leaves three questions for the owner: whether apps/mobile has a bundle id and
a provisioning profile at all, its url scheme, and expo managed versus bare —
that last one decides how the extension gets built and is probably the longest
pole in phase 3.

docs/push-notifications.md

@@ -4,6 +4,9 @@
 design. It supersedes the 2026-07-31 one, which is summarised under "What changed and why" so the
 reversals are legible rather than silently overwritten.
 
+The app-side contract and build order is **`docs/push-notifications-app.md`** — hand that to whoever builds
+the client. This file is the design and the reasoning.
+
 ## The shape, in one paragraph
 
 One app on the device — the main Officer app — receives every push and is the only one that can. It is a