docs(chain): add package and symbol doc comments

Cover the three main abstractions (Router, Chain, Transport), route traversal
lifecycle (Dial → Handshake → Connect), and multiplexing sub-route splitting.

chain/chain.go

@@ -1,3 +1,31 @@
+// Package chain implements the core routing infrastructure for GOST.
+//
+// It provides three key abstractions:
+//
+//   - Router: top-level entry point that resolves addresses, selects routes
+//     via a Chainer, retries on failure, and records telemetry.
+//
+//   - Chain: a named sequence of proxy hops (nodes). Each hop selects a node
+//     from its group, and the resulting Route carries traffic through every
+//     selected node in order.
+//
+//   - Transport: bundles a dialer and connector for a single chain node. It
+//     handles Dial, Handshake, Connect, and Bind — the four steps needed to
+//     move traffic through a proxy hop.
+//
+// # Route traversal
+//
+// For a chain of N nodes, the first node is reached via Dial → Handshake,
+// and each subsequent node via Connect → Handshake through the previous
+// connection. On failure, connections are cleaned up and nodes are marked
+// so selectors can deprioritize them.
+//
+// # Multiplexing
+//
+// When a node's transport supports multiplexing, Chain splits the route at
+// that point: nodes before the multiplex-capable node form a sub-route that is
+// copied into the transport, establishing a reusable tunnel for subsequent
+// connections.
 package chain
 
 import (
@@ -45,6 +73,7 @@ type Chain struct {
 	logger   logger.Logger
 }
 
+// NewChain creates a new Chain with the given name and options.
 func NewChain(name string, opts ...ChainOption) *Chain {
 	var options ChainOptions
 	for _, opt := range opts {
@@ -61,11 +90,14 @@ func NewChain(name string, opts ...ChainOption) *Chain {
 	}
 }
 
+// AddHop appends a hop to the chain. Hops are traversed in order during
+// route construction.
 func (c *Chain) AddHop(hop hop.Hop) {
 	c.hops = append(c.hops, hop)
 }
 
-// Metadata implements metadata.Metadatable interface.
+// Metadata returns the chain's metadata.
+// Implements metadata.Metadatable interface.
 func (c *Chain) Metadata() metadata.Metadata {
 	return c.metadata
 }
@@ -79,6 +111,9 @@ func (c *Chain) Name() string {
 	return c.name
 }
 
+// Route builds a route by selecting one node from each hop. If a node
+// supports multiplexing, the route is split — nodes before it form a
+// sub-route that is copied into the transport for reuse.
 func (c *Chain) Route(ctx context.Context, network, address string, opts ...chain.RouteOption) chain.Route {
 	if c == nil || len(c.hops) == 0 {
 		return nil
@@ -117,6 +152,8 @@ type chainGroup struct {
 	selector selector.Selector[chain.Chainer]
 }
 
+// NewChainGroup creates a chain group that selects one Chainer from the
+// given list using the configured selector (round-robin by default).
 func NewChainGroup(chains ...chain.Chainer) *chainGroup {
 	return &chainGroup{chains: chains}
 }