diff --git a/pkg/node/identity.go b/pkg/node/identity.go
index 68df778..4660066 100644
--- a/pkg/node/identity.go
+++ b/pkg/node/identity.go
@@ -49,7 +49,9 @@ func VerifyChallenge(challenge, response, sharedSecret []byte) bool {
 	return hmac.Equal(response, expected)
 }
 
-// NodeRole defines the operational mode of a node.
+// nm.GenerateIdentity("my-worker", RoleWorker)
+// nm.GenerateIdentity("controller-1", RoleController)
+// nm.GenerateIdentity("fleet-node", RoleDual)
 type NodeRole string
 
 const (
@@ -61,7 +63,8 @@ const (
 	RoleDual NodeRole = "dual"
 )
 
-// NodeIdentity represents the public identity of a node.
+// identity := manager.GetIdentity()
+// log(identity.ID, identity.Name, identity.PublicKey, identity.Role)
 type NodeIdentity struct {
 	ID        string    `json:"id"`        // Derived from public key (first 16 bytes hex)
 	Name      string    `json:"name"`      // Human-friendly name
diff --git a/pkg/node/peer.go b/pkg/node/peer.go
index ceb6a07..3539699 100644
--- a/pkg/node/peer.go
+++ b/pkg/node/peer.go
@@ -14,7 +14,8 @@ import (
 	"github.com/adrg/xdg"
 )
 
-// Peer represents a known remote node.
+// peer := registry.GetPeer("abc123def456")
+// registry.AddPeer(&Peer{ID: "abc123", Name: "worker-1", Address: "10.0.0.2:9091", Role: RoleWorker})
 type Peer struct {
 	ID        string    `json:"id"`
 	Name      string    `json:"name"`
diff --git a/pkg/node/transport.go b/pkg/node/transport.go
index fd65607..8e8f85a 100644
--- a/pkg/node/transport.go
+++ b/pkg/node/transport.go
@@ -23,10 +23,12 @@ var debugLogCounter atomic.Int64
 // debugLogInterval controls how often we log debug messages in hot paths (1 in N)
 const debugLogInterval = 100
 
-// DefaultMaxMessageSize is the default maximum message size (1MB)
+// DefaultMaxMessageSize is 1MB; conn.SetReadLimit(DefaultMaxMessageSize) protects against oversized messages.
 const DefaultMaxMessageSize int64 = 1 << 20 // 1MB
 
-// TransportConfig configures the WebSocket transport.
+// cfg := node.DefaultTransportConfig()
+// cfg.ListenAddr = ":9095"
+// cfg.MaxConns = 50
 type TransportConfig struct {
 	ListenAddr     string // ":9091" default
 	WSPath         string // "/ws" - WebSocket endpoint path
@@ -55,7 +57,9 @@ func DefaultTransportConfig() TransportConfig {
 // transport.OnMessage(func(conn *PeerConnection, msg *Message) { worker.HandleMessage(conn, msg) })
 type MessageHandler func(conn *PeerConnection, msg *Message)
 
-// MessageDeduplicator tracks seen message IDs to prevent duplicate processing
+// dedup := node.NewMessageDeduplicator(5 * time.Minute)
+// if dedup.IsDuplicate(msg.ID) { continue }
+// dedup.Mark(msg.ID)
 type MessageDeduplicator struct {
 	seen  map[string]time.Time
 	mutex sync.RWMutex
@@ -100,7 +104,9 @@ func (deduplicator *MessageDeduplicator) Cleanup() {
 	}
 }
 
-// Transport manages WebSocket connections with SMSG encryption.
+// t := node.NewTransport(nodeManager, peerRegistry, node.DefaultTransportConfig())
+// if err := t.Start(); err != nil { return err }
+// defer t.Stop()
 type Transport struct {
 	config       TransportConfig
 	server       *http.Server
@@ -117,7 +123,8 @@ type Transport struct {
 	waitGroup    sync.WaitGroup
 }
 
-// PeerRateLimiter implements a simple token bucket rate limiter per peer
+// limiter := node.NewPeerRateLimiter(100, 50) // 100 burst capacity, 50 tokens/sec refill
+// if !limiter.Allow() { continue } // drop message from rate-limited peer
 type PeerRateLimiter struct {
 	tokens     int
 	maxTokens  int
@@ -159,7 +166,9 @@ func (limiter *PeerRateLimiter) Allow() bool {
 	return false
 }
 
-// PeerConnection represents an active connection to a peer.
+// pc := transport.connections[peer.ID]
+// if err := pc.Send(msg); err != nil { logging.Error("send failed", ...) }
+// pc.GracefulClose("shutdown", DisconnectShutdown)
 type PeerConnection struct {
 	Peer         *Peer
 	Conn         *websocket.Conn
@@ -855,7 +864,8 @@ func (pc *PeerConnection) Close() error {
 	return err
 }
 
-// DisconnectPayload contains reason for disconnect.
+// pc.GracefulClose("server shutdown", DisconnectShutdown)
+// msg, _ := NewMessage(MsgDisconnect, from, to, DisconnectPayload{Reason: "shutdown", Code: DisconnectShutdown})
 type DisconnectPayload struct {
 	Reason string `json:"reason"`
 	Code   int    `json:"code"` // Optional disconnect code