diff --git a/pkg/node/peer.go b/pkg/node/peer.go
index 855261f..0c506d7 100644
--- a/pkg/node/peer.go
+++ b/pkg/node/peer.go
@@ -121,7 +121,8 @@ const (
 	scoreWeight      = 1.2
 )
 
-// NewPeerRegistry creates a new PeerRegistry, loading existing peers if available.
+// registry, err := node.NewPeerRegistry()
+// if err != nil { return err }
 func NewPeerRegistry() (*PeerRegistry, error) {
 	peersPath, err := xdg.ConfigFile("lethean-desktop/peers.json")
 	if err != nil {
@@ -131,8 +132,8 @@ func NewPeerRegistry() (*PeerRegistry, error) {
 	return NewPeerRegistryWithPath(peersPath)
 }
 
-// NewPeerRegistryWithPath creates a new PeerRegistry with a custom path.
-// This is primarily useful for testing to avoid xdg path caching issues.
+// registry, err := node.NewPeerRegistryWithPath("/tmp/test-peers.json")
+// used in tests to avoid xdg path caching
 func NewPeerRegistryWithPath(peersPath string) (*PeerRegistry, error) {
 	pr := &PeerRegistry{
 		peers:             make(map[string]*Peer),
@@ -192,10 +193,8 @@ func (r *PeerRegistry) IsPublicKeyAllowed(publicKey string) bool {
 	return r.allowedPublicKeys[publicKey]
 }
 
-// IsPeerAllowed checks if a peer is allowed to connect based on auth mode.
-// Returns true if:
-// - AuthMode is Open (allow all)
-// - AuthMode is Allowlist AND (peer is pre-registered OR public key is allowlisted)
+// if !registry.IsPeerAllowed(payload.Identity.ID, payload.Identity.PublicKey) { conn.Close(); return }
+// true when Open mode, or Allowlist mode with pre-registered peer or allowlisted key
 func (r *PeerRegistry) IsPeerAllowed(peerID string, publicKey string) bool {
 	r.allowedPublicKeyMutex.RLock()
 	authMode := r.authMode
@@ -220,7 +219,7 @@ func (r *PeerRegistry) IsPeerAllowed(peerID string, publicKey string) bool {
 	return keyAllowed
 }
 
-// ListAllowedPublicKeys returns all allowlisted public keys.
+// keys := registry.ListAllowedPublicKeys() // for display or export
 func (r *PeerRegistry) ListAllowedPublicKeys() []string {
 	r.allowedPublicKeyMutex.RLock()
 	defer r.allowedPublicKeyMutex.RUnlock()
@@ -268,7 +267,7 @@ func (r *PeerRegistry) AddPeer(peer *Peer) error {
 	return r.save()
 }
 
-// UpdatePeer updates an existing peer's information.
+// registry.UpdatePeer(peer) // after handshake completes and real ID is known
 // Note: Persistence is debounced. Call Close() to flush before shutdown.
 func (r *PeerRegistry) UpdatePeer(peer *Peer) error {
 	r.mu.Lock()
@@ -285,7 +284,7 @@ func (r *PeerRegistry) UpdatePeer(peer *Peer) error {
 	return r.save()
 }
 
-// RemovePeer removes a peer from the registry.
+// registry.RemovePeer(peer.ID) // on manual disconnect or ban
 // Note: Persistence is debounced. Call Close() to flush before shutdown.
 func (r *PeerRegistry) RemovePeer(id string) error {
 	r.mu.Lock()
@@ -318,7 +317,7 @@ func (r *PeerRegistry) GetPeer(id string) *Peer {
 	return &peerCopy
 }
 
-// ListPeers returns all registered peers.
+// for _, peer := range registry.ListPeers() { log(peer.ID, peer.Role) }
 func (r *PeerRegistry) ListPeers() []*Peer {
 	r.mu.RLock()
 	defer r.mu.RUnlock()
@@ -331,7 +330,7 @@ func (r *PeerRegistry) ListPeers() []*Peer {
 	return peers
 }
 
-// UpdateMetrics updates a peer's performance metrics.
+// registry.UpdateMetrics(peer.ID, rtt, peer.GeoKM, peer.Hops) // after PingPeer
 // Note: Persistence is debounced. Call Close() to flush before shutdown.
 func (r *PeerRegistry) UpdateMetrics(id string, pingMS, geoKM float64, hops int) error {
 	r.mu.Lock()
@@ -353,7 +352,7 @@ func (r *PeerRegistry) UpdateMetrics(id string, pingMS, geoKM float64, hops int)
 	return r.save()
 }
 
-// UpdateScore updates a peer's reliability score.
+// registry.UpdateScore(peer.ID, 75.0) // clamps to 0-100
 // Note: Persistence is debounced. Call Close() to flush before shutdown.
 func (r *PeerRegistry) UpdateScore(id string, score float64) error {
 	r.mu.Lock()
@@ -378,7 +377,8 @@ func (r *PeerRegistry) UpdateScore(id string, score float64) error {
 	return r.save()
 }
 
-// SetConnected updates a peer's connection state.
+// registry.SetConnected(peer.ID, true)  // on connect
+// registry.SetConnected(peer.ID, false) // on disconnect or error
 func (r *PeerRegistry) SetConnected(id string, connected bool) {
 	r.mu.Lock()
 	defer r.mu.Unlock()
@@ -401,7 +401,7 @@ const (
 	ScoreDefault          = 50.0  // Default score for new peers
 )
 
-// RecordSuccess records a successful interaction with a peer, improving their score.
+// registry.RecordSuccess(peer.ID) // after a successful response
 func (r *PeerRegistry) RecordSuccess(id string) {
 	r.mu.Lock()
 	peer, exists := r.peers[id]
@@ -416,7 +416,7 @@ func (r *PeerRegistry) RecordSuccess(id string) {
 	r.save()
 }
 
-// RecordFailure records a failed interaction with a peer, reducing their score.
+// registry.RecordFailure(peer.ID) // after a failed send or error response
 func (r *PeerRegistry) RecordFailure(id string) {
 	r.mu.Lock()
 	peer, exists := r.peers[id]
@@ -437,7 +437,7 @@ func (r *PeerRegistry) RecordFailure(id string) {
 	})
 }
 
-// RecordTimeout records a timeout when communicating with a peer.
+// registry.RecordTimeout(peer.ID) // after a request deadline exceeded
 func (r *PeerRegistry) RecordTimeout(id string) {
 	r.mu.Lock()
 	peer, exists := r.peers[id]
@@ -458,7 +458,7 @@ func (r *PeerRegistry) RecordTimeout(id string) {
 	})
 }
 
-// GetPeersByScore returns peers sorted by score (highest first).
+// for _, peer := range registry.GetPeersByScore() { log(peer.ID, peer.Score) }
 func (r *PeerRegistry) GetPeersByScore() []*Peer {
 	r.mu.RLock()
 	defer r.mu.RUnlock()
@@ -533,7 +533,7 @@ func (r *PeerRegistry) SelectNearestPeers(n int) []*Peer {
 	return peers
 }
 
-// GetConnectedPeers returns all currently connected peers.
+// for _, peer := range registry.GetConnectedPeers() { ctrl.GetRemoteStats(peer.ID) }
 func (r *PeerRegistry) GetConnectedPeers() []*Peer {
 	r.mu.RLock()
 	defer r.mu.RUnlock()