Add overlay planning commands

docs/architecture.md

@@ -16,7 +16,8 @@ as a privileged system service.
 
 Remote geth node-to-node communication is Iroh-only. The daemon will own one
 shared Iroh endpoint and register module protocols on ALPNs such as
-`/geth/cas/1`, `/geth/kv/1`, `/geth/pipe/1`, and `/geth/ssh-proxy/1`.
+`/geth/cas/1`, `/geth/kv/1`, `/geth/pipe/1`, `/geth/ssh-proxy/1`, and
+`/geth/overlay/1`.
 
 The pinned Iroh integration uses `iroh = 0.95.1`. `geth-iroh` wraps
 `iroh::Endpoint::builder()`, configures geth ALPNs with `Builder::alpns`, uses
@@ -150,6 +151,7 @@ Resource kinds:
 - `pubsub`: lossy notifications and presence
 - `cas`: content-addressed blobs
 - `ssh-proxy`: SSH/admin proxying over Iroh
+- `overlay`: optional Iroh-carried packet overlay planning
 
 ## Module Overview
 
@@ -244,6 +246,20 @@ message and broadcasting it through a deterministic native `iroh-gossip` topic.
 the gossip topic when the caller has `pubsub.subscribe`, and returns the peer's
 current daemon-lifetime snapshot. Private topics remain future work.
 
+`geth-overlay` defines an optional packet-overlay plan inspired by `iroh-lan`.
+The target runtime is a private L3-style overlay where packets from an explicit
+TUN/Wintun interface are carried over the daemon-owned Iroh endpoint on
+`/geth/overlay/1`. The overlay is a geth resource (`resource:overlay:<name>`)
+with `overlay.join`, `overlay.route`, and `overlay.admin` capabilities. The
+prototype exposes `geth overlay status`, `geth overlay plan <name>`,
+`geth overlay join <name> --secret <resource-secret>`, and `geth overlay leave
+<name>` as planning/control stubs only. They validate names, CIDRs, resource
+IDs, capabilities, and security notes, but they do not create host network
+interfaces, assign virtual IPs, or route packets yet. Future implementation must
+remain explicitly opt-in because TUN/Wintun setup may need platform-specific
+privileges. Overlay discovery can use mDNS, peer exchange, and resource
+metadata, but discovery remains untrusted and cannot grant overlay access.
+
 `geth-pipe` currently supports `pipe listen/connect/send/recv` against a
 daemon-lifetime runtime. `geth pipe connect <name> --node <node-id>` sends an
 authorized remote connect request over the protected Iroh control ALPN. The