Skip to content

Agent Mesh

docs: update mobile app documentation and add to site

Antonio Ojea1fad4583c27b
diff --git a/mobile/sam-node-app/README.md b/mobile/sam-node-app/README.md
index a94946b3..3ad6d771 100644
--- a/mobile/sam-node-app/README.md
+++ b/mobile/sam-node-app/README.md
@@ -69,31 +69,72 @@ Once launched, the app displays a control interface:
---
-## Developer Integration & API Usage
-
-Once the node is **Running**, other applications on the mobile device (or inside the emulator) can connect to its local HTTP API:
-
-### 1. Model Context Protocol (MCP) Client
-Connect a local agent client to the streamable SSE endpoint:
-* **SSE URL**: `http://127.0.0.1:5005/mcp`
-* **Headers**:
- * `Authorization: Bearer <Local-API-Token>`
- * `Accept: text/event-stream`
-
-### 2. Registering Local Tools
-An app on the device can expose its own tools to the mesh by registering them with the sidecar registry:
-* **POST URL**: `http://127.0.0.1:5005/sam/service/register`
-* **Headers**:
- * `Authorization: Bearer <Local-API-Token>`
- * `Content-Type: application/json`
-* **Body Example**:
- ```json
- {
- "service": {
- "type": "SERVICE_TYPE_MCP",
- "name": "my-mobile-tool",
- "description": "Exposes mobile device sensors/actions"
- },
- "targetUrl": "http://127.0.0.1:9090"
- }
+---
+
+## Features & New Capabilities
+
+### πŸ“± 1. Embedded MCP Server & Real Telemetry
+The app now includes an embedded Dart MCP server that exposes real-time telemetry from the device:
+* **Battery Status**: Level and charging state.
+* **Location**: Coarse/Fine coordinates (requires permissions).
+* **Foreground Service**: Keeps the node alive and connected even when the phone is idle or backgrounded (Android 14+ compatible).
+
+### πŸ€– 2. Android 16 AppFunctions (On-Device MCP)
+Exposes capabilities directly to the OS registry, allowing native assistants (like Gemini) to orchestrate tasks without manual app navigation.
+* `getMeshStatus`: Returns node stats and connected peers.
+* `callRemoteMeshTool`: Proxy to invoke tools on remote mesh peers.
+
+---
+
+## How to Use the Application
+
+### πŸ“Έ Screenshots
+
+| Node Status / Dashboard | Services & Telemetry |
+|:---:|:---:|
+| ![Node Logged](../../site/static/images/mobile_node_logged.png) | ![Services Enabled](../../site/static/images/mobile_services_enabled.png) |
+
+1. **Dashboard Tab**: Displays current status, Node ID, connected peers, and DHT size.
+2. **Services Tab**: Allows enabling/disabling embedded sensors (Battery/Location) and bridging external local MCP servers.
+
+---
+
+## Developer Integration & Usage Examples
+
+### Option 1: CLI Usage (Technical Verification)
+
+You can query the phone's telemetry from a remote machine (or another node) using the repository's `mcp-client` utility.
+
+1. **Discover tools on the remote phone service**:
+ ```bash
+ # Query the local SAM node proxy for tools hosted by the phone-sensors peer
+ go run cmd/mcp-client/main.go \
+ -url "http://localhost:8080/sam/<PHONE_PEER_ID>/mcp/phone-sensors" \
+ -token "secret-token" \
+ -list
```
+ *Output:*
+ * `get_battery_status`: Returns the current battery level and charging status of the device.
+ * `get_location`: Returns the current coarse location of the device.
+
+2. **Query the location**:
+ ```bash
+ go run cmd/mcp-client/main.go \
+ -url "http://localhost:8080/sam/<PHONE_PEER_ID>/mcp/phone-sensors" \
+ -token "secret-token" \
+ -tool "get_location"
+ ```
+ *Output:* `{"latitude": 42.2805588, "longitude": -8.6124088}`
+
+---
+
+### Option 2: AI Agent Interaction Flow
+
+Clean, successful flow of an AI agent discovering and querying the mesh.
+
+| Step | Action | Details / Tool | Result |
+|---|---|---|---|
+| 1 | Discover Peers & Tools | `find_remote_tools` | Found peer `<PHONE_PEER_ID>` hosting service `phone-sensors` with tool `mcp://phone-sensors/get_location`. |
+| 2 | Verify Schema | `describe_remote_tool` | Confirmed `get_location` requires no input parameters: `{"input_schema": {"type": "object", "properties": {}}}`. |
+| 3 | Query Location | `call_remote_tool` | Received: `{"latitude": 42.2805588, "longitude": -8.6124088}` |
+| 4 | Resolve Address | Web Search | Geolocated to Vigo / Redondela area, Galicia, Spain. |
diff --git a/site/content/docs/user/_index.md b/site/content/docs/user/_index.md
index d5b66c7f..8770c61b 100644
--- a/site/content/docs/user/_index.md
+++ b/site/content/docs/user/_index.md
@@ -14,5 +14,11 @@ Welcome to the User & Operator Guides. This section provides detailed documentat
2. **[Agent Usage & Connectivity](agent-usage/)**
Understand how nodes connect to the mesh via OIDC login, secure credentials, run local Model Context Protocol (MCP) servers, and expose secure remote tool access to agents (like Google Gemini and Claude).
-3. **[Production Kubernetes Deployment](kubernetes-deployment/)**
+3. **[Node Configuration](node-configuration/)**
+ Learn how to configure the local node, set up binding addresses, and manage local storage.
+
+4. **[Production Kubernetes Deployment](kubernetes-deployment/)**
Deploy a production-grade mesh cluster in Kubernetes, including Dex OIDC setups, StatefulSet P2P hubs, DNS A-record synchronizers, and Workload Identity ServiceAccount token projections.
+
+5. **[SAM Mobile App](mobile-app/)**
+ Turn your mobile device into a SAM node, exposing sensors and telemetry securely to the mesh, and integrating with native OS assistants.
diff --git a/site/content/docs/user/mobile-app.md b/site/content/docs/user/mobile-app.md
new file mode 100644
index 00000000..26e4310e
--- /dev/null
+++ b/site/content/docs/user/mobile-app.md
@@ -0,0 +1,92 @@
+---
+title: "SAM Mobile App (Android/iOS)"
+linkTitle: "Mobile App"
+weight: 5
+---
+
+# SAM Node Mobile (Flutter Client)
+
+The SAM Mobile App is a Flutter application that packages and runs the native Go-based `sam-node` mesh client on mobile devices using Go's CGO compiler and Dart FFI (Foreign Function Interface).
+
+It allows you to turn your phone into a fully functional node in the Sovereign Agent Mesh, exposing device sensors and capabilities securely to AI agents.
+
+---
+
+## Features & Capabilities
+
+### πŸ“± 1. Embedded MCP Server & Real Telemetry
+The app includes an embedded MCP server that exposes real-time telemetry from your device:
+* **Battery Status**: Level and charging state.
+* **Location**: Coarse/Fine coordinates (requires permissions).
+* **Foreground Service**: Keeps the node alive and connected even when the phone is idle or backgrounded (Android 14+ compatible).
+
+### πŸ€– 2. Android 16 AppFunctions (On-Device MCP)
+Exposes capabilities directly to the OS registry, allowing native assistants (like Gemini) to orchestrate tasks without manual app navigation.
+* `getMeshStatus`: Returns node stats and connected peers.
+* `callRemoteMeshTool`: Proxy to invoke tools on remote mesh peers.
+
+---
+
+## Screenshots
+
+| Node Status / Dashboard | Services & Telemetry |
+|:---:|:---:|
+| ![Node Logged](/images/mobile_node_logged.png) | ![Services Enabled](/images/mobile_services_enabled.png) |
+
+---
+
+## How to Use the Application
+
+1. **Enrollment**: Enter the **Hub URL** (e.g., `https://bananas.sam-mesh.dev`) and your **Enrollment JWT**.
+2. **API Token**: Set a local API token (defaults to `secret-token`) to secure local access.
+3. **Start Node**: Launches the background Go node runtime.
+4. **Dashboard**: Monitor connected peers and DHT size.
+5. **Services Tab**: Enable/Disable embedded sensors (Battery/Location) to expose them to the mesh.
+
+---
+
+## Developer Integration & Usage Examples
+
+### Option 1: CLI Usage (Technical Verification)
+
+You can query the phone's telemetry from a remote machine (or another node) using the repository's `mcp-client` utility.
+
+1. **Discover tools on the remote phone service**:
+ ```bash
+ # Query the local SAM node proxy for tools hosted by the phone-sensors peer
+ go run cmd/mcp-client/main.go \
+ -url "http://localhost:8080/sam/<PHONE_PEER_ID>/mcp/phone-sensors" \
+ -token "secret-token" \
+ -list
+ ```
+ *Output:*
+ * `get_battery_status`: Returns the current battery level and charging status of the device.
+ * `get_location`: Returns the current coarse location of the device.
+
+2. **Query the location**:
+ ```bash
+ go run cmd/mcp-client/main.go \
+ -url "http://localhost:8080/sam/<PHONE_PEER_ID>/mcp/phone-sensors" \
+ -token "secret-token" \
+ -tool "get_location"
+ ```
+ *Output:* `{"latitude": 42.2805588, "longitude": -8.6124088}`
+
+---
+
+### Option 2: AI Agent Interaction Flow
+
+Clean, successful flow of an AI agent discovering and querying the mesh.
+
+| Step | Action | Details / Tool | Result |
+|---|---|---|---|
+| 1 | Discover Peers & Tools | `find_remote_tools` | Found peer `<PHONE_PEER_ID>` hosting service `phone-sensors` with tool `mcp://phone-sensors/get_location`. |
+| 2 | Verify Schema | `describe_remote_tool` | Confirmed `get_location` requires no input parameters: `{"input_schema": {"type": "object", "properties": {}}}`. |
+| 3 | Query Location | `call_remote_tool` | Received: `{"latitude": 42.2805588, "longitude": -8.6124088}` |
+| 4 | Resolve Address | Web Search | Geolocated to Vigo / Redondela area, Galicia, Spain. |
+
+---
+
+## Compilation Instructions
+
+For instructions on how to build the application from source, please refer to the [Mobile App README](https://github.com/google/sam/tree/main/mobile/sam-node-app).
diff --git a/site/static/images/mobile_node_logged.png b/site/static/images/mobile_node_logged.png
new file mode 100644
index 00000000..c28e50df
Binary files /dev/null and b/site/static/images/mobile_node_logged.png differ
diff --git a/site/static/images/mobile_services_enabled.png b/site/static/images/mobile_services_enabled.png
new file mode 100644
index 00000000..a0c658b3
Binary files /dev/null and b/site/static/images/mobile_services_enabled.png differ