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, 13 insertions, 1 deletions

diff --git a/internal/paths/paths.go b/internal/paths/paths.go
index c7bdd94..67f6da6 100644
--- a/internal/paths/paths.go
+++ b/internal/paths/paths.go
@@ -1,3 +1,13 @@
+// Package paths handles the resolution of configuration and runtime directories,
+// providing a consistent way to locate profile and PID tracking files.
+//
+// Profile Storage:
+// Profiles are stored as standard .conf files in ~/.config/wg-wrap/profiles/.
+//
+// PID Tracking:
+// To manage namespace lifecycles and shared sessions, wg-wrap tracks active processes
+// using PID files located in the runtime base directory:
+// /run/user/$UID/wg-wrap/profiles/<profile-name>/pids/
 package paths
 
 import (
@@ -9,7 +19,9 @@ import (
 // PathManager handles the resolution of configuration and runtime directories.
 // By using a struct, we can instantiate different managers for parallel tests.
 type PathManager struct {
-	ConfigDirOverride   string
+	// ConfigDirOverride allows overriding the default config directory (usually XDG_CONFIG_HOME/wg-wrap/profiles).
+	ConfigDirOverride string
+	// RuntimeBaseOverride allows overriding the default runtime directory (usually XDG_RUNTIME_DIR).
 	RuntimeBaseOverride string
 }