docs: the Android application asks for the local network

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 15 insertions, 0 deletions

diff --git a/docs/MESHBAY_DESIGN.md b/docs/MESHBAY_DESIGN.md
index dc9cde9c..0160b97f 100644
--- a/docs/MESHBAY_DESIGN.md
+++ b/docs/MESHBAY_DESIGN.md
@@ -4168,6 +4168,21 @@ narrow bridge — and Android has all three:
   notification's link is a route in the page, applied as `location.hash`, never
   loaded. No VAPID yet: a distributor that requires it refuses, and the phone
   fetches instead.
+- **The local network is a permission the person grants** (Android 17,
+  `ACCESS_LOCAL_NETWORK`, shown as "Nearby devices"), since the application
+  targets SDK 37. The node is usually on the phone's Wi-Fi and the WebView's
+  WebRTC carries the application's permission: without it the node's
+  addresses on that Wi-Fi are dropped, and the group opens on mobile data and
+  not at home. `shell/LocalNetwork.kt` asks when a group is first opened,
+  never at start; a refusal the connection runs into is named
+  (`local_network_blocked`) and the group page offers the question again
+  while Android will still ask, then the application's settings. Moving to
+  SDK 37 also took the permission back from an installed application, which
+  had it implied before: the first group opened after the update asks.
+- **The page hears when the phone changes network** (`meshbay-default-network`,
+  from the default network callback), mobile data to Wi-Fi or back, and checks
+  the connection it holds (transport.js `onNetworkChange`). The event carries
+  nothing about either network.
 
 Release builds are signed with the release key, distributed as a direct APK;
 the key stays outside the repository and a release build without it fails