feat: user service

gateway/docs/examples.md

@@ -89,6 +89,26 @@ Example `ExecuteCommandResponse`:
 }
 ```
 
+Example authenticated self-service request metadata:
+
+```json
+{
+  "protocolVersion": "v1",
+  "deviceSessionId": "device-session-123",
+  "messageType": "user.account.get",
+  "timestampMs": "1775121600000",
+  "requestId": "request-account-123",
+  "payloadBytes": "RkxBVEJVRkZFUlNfVVNFUl9SRVFVRVNU",
+  "payloadHash": "5fY6Q8V9mK8x2B7v6v0V0m0i1rQ2QF0rQ8V1Yt1r8Ys=",
+  "signature": "3o4v8f3h0Y6I0x1bS7zY+8m0bV1Lk4D3yq8J2n8F1rD7yK9v8M1Q0w2s4a6f8d0Q0m3L6y8R1t5w7x9z0a2cA=="
+}
+```
+
+The external payload remains FlatBuffers. The current `Gateway -> User`
+self-service adapter decodes that payload, calls the trusted internal
+User Service REST API, then re-encodes the returned account aggregate or error
+envelope back into FlatBuffers before signing the response.
+
 Example bootstrap `GatewayEvent` sent after `SubscribeEvents` opens:
 
 ```json

gateway/docs/flows.md

@@ -52,6 +52,24 @@ sequenceDiagram
     Gateway-->>Client: ExecuteCommandResponse + signature
 ```
 
+## Direct Gateway -> User Self-Service Flow
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Gateway
+    participant User as User Service
+
+    Client->>Gateway: ExecuteCommand(user.account.get | user.profile.update | user.settings.update)
+    Gateway->>Gateway: verify envelope + session + signature + replay
+    Gateway->>Gateway: decode FlatBuffers payload
+    Gateway->>User: trusted REST/JSON internal request
+    User-->>Gateway: JSON account aggregate or JSON error envelope
+    Gateway->>Gateway: encode FlatBuffers success or error payload
+    Gateway->>Gateway: sign response
+    Gateway-->>Client: ExecuteCommandResponse(result_code, payload_bytes, signature)
+```
+
 ## SubscribeEvents Lifecycle
 
 ```mermaid

gateway/docs/runtime.md

@@ -55,5 +55,7 @@ Notes:
 - The admin listener is optional and serves only Prometheus text metrics.
 - Public auth routing stays available without an upstream adapter, but returns
   `503 service_unavailable`.
-- Authenticated gRPC starts with an empty static router; `ExecuteCommand`
-  remains `UNIMPLEMENTED` until downstream routes are injected.
+- The default runtime reserves direct `user.*` authenticated self-service
+  routes. When `GATEWAY_USER_SERVICE_BASE_URL` is unset those routes stay
+  mounted but fail closed as dependency-unavailable instead of returning a
+  route miss.