docs: add gRPC remote access section with diagrams + security disclaimer

Author: xaionaro@dx.center

README.md

@@ -278,6 +278,59 @@ flowchart TD
 
 4. **gRPC Layer** (`grpc/`) — Remote proxy for Android APIs over gRPC. A companion app runs the gRPC server on-device; clients call Android APIs from any machine. Generated by `grpcgen`.
 
+### gRPC Remote Access
+
+The gRPC layer turns any Android phone into a remotely accessible API server. A companion service (`jniservice`) runs on the device — either as an APK (non-rooted) or a Magisk module (rooted, auto-starts on boot). Clients on any machine connect over the network using `jnicli`.
+
+```mermaid
+sequenceDiagram
+    participant Client as jnicli (host)
+    participant Server as jniservice (phone)
+    participant Android as Android APIs
+
+    Client->>Server: auth register (CSR)
+    Server-->>Client: signed client cert + CA cert
+
+    Client->>Server: auth request-permission
+    Server->>Android: launch approval dialog
+    Note over Android: User taps "Approve"
+    Server-->>Client: status: approved
+
+    Client->>Server: location get (mTLS)
+    Server->>Android: LocationManager.getLastKnownLocation()
+    Android-->>Server: Location object
+    Server-->>Client: {lat, lon, alt, accuracy}
+```
+
+Each client registers with a unique certificate (mTLS). Method access is controlled by per-service ACLs — the device owner approves which services each client can use through an on-screen dialog:
+
+```mermaid
+flowchart LR
+    subgraph Client
+        CLI["jnicli"]
+    end
+
+    subgraph "jniservice (on device)"
+        TLS["mTLS gateway"]
+        ACL["Per-service ACL"]
+        SVC["31 Android API\nservices"]
+        RAW["Raw JNI surface"]
+        PROXY["Callback proxy\n(Camera2, etc.)"]
+    end
+
+    CLI -->|client cert| TLS
+    TLS --> ACL
+    ACL -->|"camera.*"| SVC
+    ACL -->|"admin only"| RAW
+    SVC --> Android["Android\nFramework"]
+    RAW --> Android
+    PROXY --> Android
+```
+
+**Available services** include camera, location, bluetooth, WiFi, telephony, battery, power, alarm, vibrator, audio, NFC, notifications, and more (31 services total, ~2000 RPCs). Callback-based APIs (like Camera2) work through a bidirectional streaming proxy with build-time generated adapter classes.
+
+> **Security disclaimer:** This is a hobby/research project. The mTLS + ACL system provides basic access control, but it has not been audited and should not be relied upon for security-critical deployments. The self-signed CA, handle-based object references, and raw JNI surface all have inherent attack surface. Use it on trusted networks for development, testing, and experimentation.
+
 ## Project Layout
 
 ```