Implement opt-in overlay TUN runtime

README.md

@@ -117,10 +117,22 @@ The bootstrap implementation provides:
   `geth overlay status`,
   `geth overlay plan <name> [--cidr 172.22.0.0/24]`,
   `geth overlay join <name> --secret <resource-secret> [--cidr 172.22.0.0/24]`,
-  and `geth overlay leave <name>`. These commands expose the resource,
-  capability, and ALPN shape for a future Iroh-carried packet overlay inspired
-  by iroh-lan. The prototype does not create TUN/Wintun interfaces or route
-  packets yet.
+  `geth overlay interface-plan <name> [--platform linux|macos|windows]`,
+  `geth overlay up <name> [--bearer-secret <route-token>] [--mtu 1280]`,
+  `geth overlay down <name>`,
+  `geth overlay peers <name>`, `geth overlay send <name> <node>
+  --packet-base64 <ipv4-packet>`, `geth overlay recv <name>`, and
+  `geth overlay leave <name>`. Join persists local overlay membership, creates
+  the overlay resource when needed, assigns a deterministic virtual IP, and
+  stores only a BLAKE3 fingerprint of the supplied secret. If the overlay
+  resource already has bearer invites, join requires a bearer token with
+  `overlay.join`. Packet send validates IPv4 packets and carries them over the
+  dedicated `/geth/overlay/1` Iroh ALPN after `overlay.route` authorization.
+  `overlay up` creates a real L3 TUN/Wintun-style interface through `tun-rs`,
+  reads IPv4 packets from that interface, maps destination overlay IPs to
+  imported peer cards, and routes packets over `/geth/overlay/1`. Creating the
+  interface is explicit opt-in and may require `CAP_NET_ADMIN`, sudo, or
+  platform-specific network entitlements.
 - `geth resource list`
 - `geth resource create <kind> <name>`
 - `geth keychain init [--admin-key <path>] [--signing-key <path>]`