docs: rewrite package comments to focus on what/why, not how

Each package doc now explains what problem it solves and why it exists,
with the public interface as the only "how" detail. Implementation
notes removed from doc comments.

internal/buildmeta/buildmeta.go

@@ -1,5 +1,9 @@
-// Package buildmeta defines the canonical constants for OS, architecture,
-// libc, archive format, and release channel used throughout Webi.
+// Package buildmeta is the shared vocabulary for Webi's build targets.
+//
+// Every package that deals with OS, architecture, libc, archive format, or
+// release channel imports these types instead of passing raw strings. This
+// prevents typos like "darwn" from compiling and gives a single place to
+// enumerate what Webi supports.
 package buildmeta
 
 // OS represents a target operating system.

internal/httpclient/httpclient.go

@@ -1,15 +1,12 @@
-// Package httpclient provides a resilient HTTP client with best-practice
-// defaults for making upstream API calls (GitHub, Gitea, etc.).
+// Package httpclient provides a secure, resilient HTTP client for upstream API
+// calls. It exists because [http.DefaultClient] has no timeouts, no retry
+// logic, and follows redirects from HTTPS to HTTP — none of which are
+// acceptable for a server making calls to GitHub, Gitea, etc. on behalf of
+// users.
 //
-// Features:
-//   - Sensible timeouts at every level (connect, TLS, headers, overall)
-//   - Connection pooling with reasonable limits
-//   - TLS 1.2+ minimum
-//   - Limited redirect depth, no HTTPS→HTTP downgrade
-//   - Automatic retries with exponential backoff + jitter for transient errors
-//   - Respects Retry-After headers
-//   - Custom User-Agent identifying Webi
-//   - All calls require context.Context
+// Create a [Client] with [New], then use [Client.Do] or [Client.Get]. All
+// calls require [context.Context] and will automatically retry transient
+// failures (429, 502, 503, 504) with backoff.
 package httpclient
 
 import (

internal/lexver/lexver.go

@@ -1,24 +1,12 @@
-// Package lexver converts version strings into lexicographically sortable
-// representations so that version comparison reduces to string comparison.
+// Package lexver makes version strings comparable via simple string comparison.
 //
-// The core problem: "1.20.3" must sort after "1.2.0", but as raw strings
-// "1.2" > "1.20" because '2' > '.' in ASCII. Lexver solves this by
-// zero-padding each numeric segment to a fixed width.
+// Version strings like "1.20.3" and "1.2.0" can't be compared as raw strings
+// because "1.2" > "1.20" in ASCII. Lexver normalizes them so that standard
+// string ordering matches semantic version ordering — including pre-release
+// channels (alpha < beta < rc < stable).
 //
-// Sorting rules:
-//   - Numeric segments are zero-padded and compared naturally
-//   - Stable releases sort after pre-releases of the same version
-//   - Pre-release channels sort alphabetically (alpha < beta < rc)
-//   - Numeric suffixes within channels sort numerically (rc2 > rc1)
-//
-// Examples:
-//
-//	"1.20.3"       → "0001.0020.0003.0000~"
-//	"1.0.0-beta1"  → "0001.0000.0000.0000-beta.0001"
-//	"1.0.0"        → "0001.0000.0000.0000~"
-//
-// The "~" character sorts after "-" in ASCII, so stable versions always
-// sort after any pre-release of the same numeric version.
+//	lexver.Parse("1.20.3") > lexver.Parse("1.2.0")    // true
+//	lexver.Parse("1.0.0")  > lexver.Parse("1.0.0-rc1") // true
 package lexver
 
 import (

internal/uadetect/uadetect.go

@@ -1,13 +1,10 @@
-// Package uadetect identifies OS, architecture, and libc from a User-Agent
-// string. The input is typically from curl's -A flag:
+// Package uadetect identifies the requesting system's OS, CPU architecture,
+// and libc from its User-Agent string.
 //
-//	curl -fsSA "$(uname -srm)" https://webi.sh/node
-//
-// Which produces something like:
-//
-//	"Darwin 23.1.0 arm64"
-//	"Linux 6.1.0 x86_64"
-//	"CYGWIN_NT-10.0-19045 3.5.3 x86_64"
+// Webi's bootstrap scripts send "$(uname -srm)" as the User-Agent, e.g.
+// "Darwin 23.1.0 arm64" or "Linux 6.1.0 x86_64". This package parses those
+// into [buildmeta.OS], [buildmeta.Arch], and [buildmeta.Libc] values so the
+// server can select the correct release artifact.
 package uadetect
 
 import (