diff --git a/client/netstate/netstate.go b/client/netstate/netstate.go
index f67f863ef..0d7a1268b 100644
--- a/client/netstate/netstate.go
+++ b/client/netstate/netstate.go
@@ -28,7 +28,9 @@ type State struct {
 	changed chan struct{}
 }
 
-// New creates a State that starts online.
+// New creates a State that starts online. Platforms without network tracking
+// pass a nil *State instead: the read methods treat nil as always online and
+// never block, so consumers need no nil guards.
 func New() *State {
 	return &State{
 		online:  true,
@@ -37,7 +39,8 @@ func New() *State {
 }
 
 // Set records whether the OS reports any usable network. Transitions wake up
-// all Wait callers immediately.
+// all Wait callers immediately. Unlike the read methods, Set is not nil-safe:
+// it is only for the platform owner that created the State with New.
 func (s *State) Set(online bool) {
 	s.mu.Lock()
 	defer s.mu.Unlock()