Add overlay planning commands

docs/adr/0017-optional-iroh-overlay-network.md

@@ -0,0 +1,66 @@
+# ADR 0017: Optional Iroh Overlay Network
+
+## Status
+
+Accepted for prototype scaffolding.
+
+## Context
+
+`iroh-lan` demonstrates a useful pattern for a private packet overlay carried by
+Iroh connections. That model is attractive for geth because it could make local
+services, scripts, and devices reachable through stable mesh resources without
+exposing host networking directly to untrusted discovery.
+
+Geth must keep its core invariants:
+
+- all remote geth communication is over Iroh
+- the daemon owns the Iroh endpoint
+- discovery is untrusted
+- resource authorization gates access
+- SSH is not a geth transport
+
+Packet overlays also carry host-network risk. TUN/Wintun setup is
+platform-specific, may require privileges, and can route arbitrary traffic if
+misconfigured.
+
+## Decision
+
+Add an optional `overlay` resource kind and reserve `/geth/overlay/1` for a
+future Iroh-carried packet overlay. The initial implementation is a typed model
+and CLI/control planning surface:
+
+- `geth overlay status`
+- `geth overlay plan <name> [--cidr <cidr>]`
+- `geth overlay join <name> --secret <resource-secret> [--cidr <cidr>]`
+- `geth overlay leave <name>`
+
+The prototype does not create TUN/Wintun interfaces, assign virtual IPs, or
+route packets. Join/leave are explicit stubs that describe the intended
+resource, capabilities, ALPN, and security boundaries.
+
+Overlay resources use capabilities:
+
+- `overlay.join`
+- `overlay.route`
+- `overlay.admin`
+
+Future overlay implementation must use the shared daemon-owned Iroh endpoint and
+must not create a second endpoint or non-Iroh transport.
+
+## Consequences
+
+The CLI can now document and test the intended overlay shape without changing
+host networking. This keeps the prototype safe to run on development machines
+while preserving a clear path toward an iroh-lan-inspired overlay.
+
+Future work must add:
+
+- persisted overlay membership/resource metadata
+- resource-secret-backed join authorization
+- platform-specific opt-in TUN/Wintun management
+- packet routing over `/geth/overlay/1`
+- peer/IP coordination through trusted resource metadata and untrusted discovery
+  candidates
+
+No current code claims VPN-grade isolation, forward secrecy, or automatic host
+network security.