From be847f9260dc35786567aabe9de83bfb3224f002 Mon Sep 17 00:00:00 2001
From: Nicolas Rabault <nicolas.rabault@huggingface.co>
Date: Fri, 19 Jun 2026 10:20:08 +0200
Subject: [PATCH] docs: note macOS multicast fallback for D2D discovery

Zenoh D2D multicast scouting does not reliably connect two local processes
on macOS (loopback), leaving discover() empty and invoke() with no responders.
Add a collapsed note documenting the ZENOH_LISTEN / ZENOH_CONNECT TCP-link
fallback.
---
 README.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/README.md b/README.md
index 96e1168..db6563b 100644
--- a/README.md
+++ b/README.md
@@ -74,6 +74,27 @@ The device starts in D2D mode automatically — no URLs needed. Any other Device
 
 > **Note:** `DEVICE_CONNECT_ALLOW_INSECURE=true` skips TLS and is intended for local development only.
 
+<details>
+<summary>Not seeing the device? (macOS / multicast)</summary>
+
+D2D mode discovers peers over Zenoh UDP multicast. On some setups — notably
+macOS over loopback — multicast scouting doesn't connect two local processes, so
+`discover(...)` comes back empty and `invoke(...)` reports no responders. Give
+the peers an explicit TCP link instead: have the device listen, and point the
+agent at it.
+
+```bash
+# device — listen on a local endpoint
+DEVICE_CONNECT_ALLOW_INSECURE=true DEVICE_CONNECT_DISCOVERY_MODE=d2d \
+  ZENOH_LISTEN=tcp/localhost:7447 python sensor.py
+
+# agent — connect to that endpoint
+DEVICE_CONNECT_ALLOW_INSECURE=true DEVICE_CONNECT_DISCOVERY_MODE=d2d \
+  ZENOH_CONNECT=tcp/localhost:7447 python your_agent.py
+```
+
+</details>
+
 ### 4. Discover and invoke from an agent
 
 ```bash