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.

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

docs/roadmap.md

@@ -135,6 +135,9 @@ Implementation order:
   - `[x]` CLI errors for stale peer cards, missing endpoint bindings, missing
     grants, unavailable relays, unavailable service managers, and unsupported
     platform features tell the operator what command to run next.
+  - `[x]` `geth init --help` and `geth guide <topic>` explain owner setup,
+    enrollment, key roles, service installation, and smoke-test workflows from
+    the binary itself.
   - `[x]` `geth sync status --json` is sufficient for scripts to detect stale
     peers and failed streams.
 
@@ -572,6 +575,29 @@ Goal: add authorized stream-oriented management workflows over Iroh.
     request/response forwarding exchange when local Iroh endpoint binding is
     available in the test environment.
 
+- `[~]` Optional Iroh overlay network.
+  Acceptance criteria:
+  - `[x]` Add a focused `geth-overlay` crate for overlay names, CIDRs,
+    resource IDs, capabilities, status, and plan models.
+  - `[x]` Reserve `/geth/overlay/1` in the daemon-owned Iroh protocol router.
+  - `[x]` Add `overlay` as a resource kind and document capabilities:
+    `overlay.join`, `overlay.route`, and `overlay.admin`.
+  - `[x]` Add CLI/control commands for `geth overlay status`, `plan`, `join`,
+    and `leave`.
+  - `[x]` Prototype commands make clear that no TUN/Wintun interface is created
+    and no packets are routed yet.
+  - `[x]` Tests cover overlay validation and control serialization.
+  - `[ ]` Persist overlay network configuration and membership state as
+    resource metadata.
+  - `[ ]` Implement resource-authorized overlay join using resource secrets
+    without granting node identity.
+  - `[ ]` Add platform-specific, opt-in TUN/Wintun interface management with
+    generated-definition tests and no privileged test requirements.
+  - `[ ]` Route IPv4 packets over `/geth/overlay/1` using the shared daemon
+    Iroh endpoint.
+  - `[ ]` Add live peer/IP coordination over trusted resource metadata and
+    untrusted discovery candidates.
+
 - `[~]` Unix socket forwarding where supported.
   Acceptance criteria:
   - `[x]` Unix socket forwarding is available on Unix platforms through