docs: comprehensive documentation for HAN-387

- README.md: full project overview, installation, quick start, CLI reference,
  output format descriptions, architecture overview, and dnstraverse comparison
- GoDoc: package-level documentation for traverse, dns, config, output, and
  fingerprint packages
- GoDoc: TraverserConfig and TraversalResult type comments in traverser.go

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: multica-agent <github@multica.ai>

internal/config/config.go

@@ -1,3 +1,5 @@
+// Package config defines the configuration types and defaults for ExploreDNS,
+// along with validation helpers and the CLI usage text.
 package config
 
 import (

internal/dns/query.go

@@ -1,3 +1,9 @@
+// Package dns provides the low-level DNS query primitives used by ExploreDNS.
+//
+// It wraps the github.com/miekg/dns library to provide retrying, TCP fallback,
+// EDNS0 buffer size negotiation, and root server discovery.  The package is
+// intentionally narrow: it sends iterative (non-recursive) queries and returns
+// the raw responses for the traversal engine to interpret.
 package dns
 
 import (

internal/fingerprint/fingerprint.go

@@ -1,3 +1,10 @@
+// Package fingerprint identifies DNS server software by querying the
+// version.bind name in the CHAOS class.  Many authoritative and recursive DNS
+// servers respond with a version string (e.g. "BIND 9.18.1-1") that can be
+// used to identify the software and version in use.
+//
+// Queries are cached per server IP so that repeated lookups within a single
+// traversal run do not incur extra network round-trips.
 package fingerprint
 
 import (

internal/output/formatter.go

@@ -1,3 +1,13 @@
+// Package output renders ExploreDNS traversal results for human consumption or
+// machine processing.
+//
+// Two formats are supported:
+//
+//   - FormatText — a coloured hierarchical tree (default)
+//   - FormatJSON — a JSON array of traversal results
+//
+// Create a Formatter via NewFormatter and call RunTraversal to drive the
+// traversal engine and stream output incrementally.
 package output
 
 import (

internal/traverse/traverse.go

@@ -1 +1,27 @@
+// Package traverse implements the core DNS traversal engine for ExploreDNS.
+//
+// The traversal engine starts from the DNS root servers and iteratively
+// follows every referral it receives, building a complete picture of the
+// delegation path for a domain.  Unlike a standard recursive resolver, which
+// stops at the first authoritative answer, the traversal engine explores every
+// branch so that delegation mismatches, lame delegations, or split authorities
+// are all visible in the output.
+//
+// # Architecture
+//
+// A Traverser maintains a stack of Referral objects.  Each Referral
+// represents a pending query to a specific set of nameservers for a specific
+// name and record type.  The engine pops referrals one at a time, sends the
+// query, classifies the response, and pushes any child referrals back onto the
+// stack.
+//
+// When a referral contains nameserver names but no glue records (IP addresses),
+// the engine resolves them via a secondary traversal before continuing.
+//
+// # Caching
+//
+// An InfoCache stores discovered glue records.  In fast mode (default) a
+// single root cache is shared across all branches so that glue discovered in
+// one branch is immediately available to sibling branches.  Disable fast mode
+// (TraverserConfig.Fast = false) for fully independent branch resolution.
 package traverse

internal/traverse/traverser.go

@@ -11,12 +11,20 @@ import (
 	miekgdns "github.com/miekg/dns"
 )
 
+// TraverserConfig configures the behaviour of a Traverser.
 type TraverserConfig struct {
+	// MaxDepth is the maximum referral depth before the traversal gives up.
 	MaxDepth    int
+	// QueryType is the DNS record type to query (e.g. dns.TypeA).
 	QueryType   uint16
+	// RootConfig controls how root servers are discovered.
 	RootConfig  *dns.RootDiscoveryConfig
+	// QueryConfig controls per-query transport parameters.
 	QueryConfig *dns.QueryConfig
+	// RootAddrs is an optional pre-seeded list of root server IP addresses.
+	// When non-empty, root discovery via RootConfig is skipped.
 	RootAddrs   []net.IP
+	// Hooks provides optional callbacks for traversal events.
 	Hooks       *TraverserHooks
 	// Fast controls cache sharing across branches. When true (default), child
 	// branches inherit glue discovered by earlier branches via the shared root
@@ -37,11 +45,14 @@ func DefaultTraverserConfig() *TraverserConfig {
 	}
 }
 
+// TraversalResult pairs a Referral with the Response received when it was processed.
 type TraversalResult struct {
 	Referral *Referral
 	Response *Response
 }
 
+// Traverser performs an exhaustive iterative DNS traversal starting from the
+// root servers.  Create one via NewTraverser and call Traverse to start a run.
 type Traverser struct {
 	config   *TraverserConfig
 	exchange dns.ExchangeFunc