Document long-term homelab overlay goal

docs/roadmap.md

@@ -9,6 +9,87 @@ Status markers:
 - `[~]` In progress
 - `[x]` Done
 
+## Long-Term Goal: Distributed Homelab Overlay
+
+Goal: evolve geth into a distributed, fault-tolerant homelab overlay runtime in
+the spirit of NetBird/Tailscale, while preserving geth's core invariants: Iroh
+is the only remote geth transport, discovery is untrusted, SSH keys are trust
+anchors rather than transport keys, and authorization remains resource-scoped
+and capability-based.
+
+This is a long-term product direction, not a claim about the current prototype.
+The target is a usable personal/family/lab mesh that can survive intermittent
+nodes, changing network locations, partial discovery failures, and offline
+admin devices without depending on one always-online coordination server.
+
+- `[ ]` Distributed overlay control plane.
+  Acceptance criteria:
+  - `[ ]` Overlay membership, virtual IP assignment, route advertisements,
+    node capabilities, and revocations are represented as signed replicated
+    resource data.
+  - `[ ]` The control plane has documented conflict semantics for concurrent
+    joins, renames, IP conflicts, route changes, and revocations.
+  - `[ ]` Nodes can converge from static sigchain publication, peer live-sync,
+    and Iroh-connected peers without requiring a central coordinator.
+  - `[ ]` Stale or partitioned nodes are detectable in `geth overlay status`
+    and `geth sync status --json`.
+
+- `[ ]` Fault-tolerant peer and path selection.
+  Acceptance criteria:
+  - `[ ]` Nodes maintain multiple candidate addresses from Iroh relays, local
+    discovery, imported peer cards, and static publication.
+  - `[ ]` Packet routing retries healthy paths and backs off failed paths
+    without granting trust from discovery metadata.
+  - `[ ]` Relay use, direct connections, LAN discovery, and path failures are
+    visible in human and JSON status output.
+  - `[ ]` Integration tests simulate peer restart, address rotation, relay-only
+    connectivity, and temporary peer unavailability.
+
+- `[ ]` Production overlay routing features.
+  Acceptance criteria:
+  - `[ ]` Overlay supports stable virtual IPv4 addressing with collision
+    detection and operator-visible remediation.
+  - `[ ]` Subnet-router resources can advertise selected LAN routes with
+    explicit capabilities and revocation behavior.
+  - `[ ]` Exit-node routing is modeled as an explicit resource and requires
+    dedicated capabilities.
+  - `[ ]` MTU selection, packet size limits, and fragmentation/drop behavior
+    are documented and tested.
+
+- `[ ]` Homelab DNS and service discovery.
+  Acceptance criteria:
+  - `[ ]` Nodes can publish signed names and service records into replicated
+    resource metadata.
+  - `[ ]` A local resolver or hosts-file integration can expose overlay names
+    without requiring global DNS changes.
+  - `[ ]` DNS/service data is separated from untrusted LAN discovery and can be
+    explained through auth/keychain state.
+  - `[ ]` Revoked nodes and stale records disappear from the trusted view after
+    verified sync.
+
+- `[ ]` Cross-platform operational polish.
+  Acceptance criteria:
+  - `[ ]` Linux TUN setup documents required user-service permissions,
+    `CAP_NET_ADMIN`, and distro-specific recovery steps.
+  - `[ ]` macOS release builds document required entitlements and user-service
+    launch behavior.
+  - `[ ]` Windows builds package or clearly locate Wintun and install a
+    per-user daemon task.
+  - `[ ]` `geth guide overlay` contains an end-to-end two-machine smoke test
+    for each supported platform class.
+
+- `[ ]` Security and auditability bar for overlay use.
+  Acceptance criteria:
+  - `[ ]` Every packet-forwarding, subnet-routing, exit-node, DNS, and service
+    discovery operation has an explicit resource/capability check.
+  - `[ ]` `auth explain` can answer why a node may or may not route packets,
+    advertise a subnet, use an exit node, or publish a service name.
+  - `[ ]` Bearer secrets can invite limited overlay access without granting
+    trust graph mutation rights.
+  - `[ ]` The docs state what properties geth provides today and avoid claims
+    equivalent to Keyhive/BeeKEM, WireGuard, NetBird, or Tailscale unless those
+    properties are actually implemented and tested.
+
 ## Prototype Viability Closure Plan
 
 These are the remaining gaps that must close before the prototype is a smooth