refactor: simplify architecture and improve documentation

- Extract orchestration logic from `internal/cli` into a new `internal/manager` package for better composability.
- Migrate technical implementation details from README.md to package-level godoc strings.
- Rewrite README.md to be more user-centric, focusing on quick start and usage.
- Add comprehensive documentation for exported structs and fields across the project.
- Verify all changes with `go fmt`, `go vet`, `golangci-lint`, and full E2E test suite.

1 files changed, 21 insertions, 0 deletions

diff --git a/internal/namespace/namespace.go b/internal/namespace/namespace.go
index 54414a9..b05dea2 100644
--- a/internal/namespace/namespace.go
+++ b/internal/namespace/namespace.go
@@ -1,3 +1,24 @@
+// Package namespace provides primitives for managing Linux user and network
+// namespaces, including bootstrapping and pinning.
+//
+// Rootless Bootstrap Loop & Host-Socket Preservation:
+// To achieve rootless network isolation without interfering with the Go runtime's multi-threaded
+// scheduler, and to maintain encrypted UDP socket connectivity over the host's network,
+// wg-wrap employs an advanced bootstrap loop:
+//
+// 1. Host-Bound Socket Creation: During the initial host-level start, a UDP socket is opened
+//    on 0.0.0.0:0 on the host, and its FD is stored in the environment (WG_WRAP_HOST_SOCKET_FD).
+// 2. Helper Deployment: An embedded single-threaded C launcher is used to bridge the transition.
+// 3. Namespace Transition: The process replaces itself with the C launcher via syscall.Exec.
+// 4. Isolation: The launcher performs the unshare(CLONE_NEWUSER | CLONE_NEWNS | CLONE_NEWNET)
+//    sequence to isolate Mount, User, and Network environments.
+// 5. Re-entry: The launcher then execvp's the original wg-wrap binary.
+// 6. FDBind Tunnel Initialization: The second instance of wg-wrap wraps the host socket FD
+//    inside a custom FDBind struct to initialize wireguard-go.
+//
+// User Namespace Sequence:
+// To create a network namespace without root, wg-wrap follows the sequence:
+// CLONE_NEWUSER -> CLONE_NEWNET -> Setuid/Setgid -> Configure Interfaces.
 package namespace
 
 import (