Implement platform compatibility stubs and update AGENTS.md

5 files changed, 30 insertions, 1 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 8f80242..65d75ac 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -43,7 +43,14 @@ To maintain a high-velocity development cycle without sacrificing correctness, w
 - **Test Stubs**: Any test that is planned but not yet implementable must use `t.Skip("not implemented")` and include a comment describing the specific scenario the test is intended to verify.
 - **Hermetic Configuration**: Tests involving profiles, settings, or filesystem state must not touch the actual user home directory. Use the `ConfigDir` injection pattern in the `App` struct combined with `t.TempDir()` to create isolated, temporary test environments.
 
-### 3. Testing Strategy
+### 3. Platform Compatibility & Build Constraints
+`wg-wrap` is fundamentally a Linux system tool. To ensure the module remains compilable on other platforms while restricting Linux-specific syscalls, we use the following patterns:
+
+- **Build Tags**: All files interacting with `golang.org/x/sys/unix`, network namespaces, or TUN devices must start with `//go:build linux`.
+- **The Stub Pattern**: For any platform-specific logic in `internal/`, we provide a matching stub file tagged with `//go:build !linux`. This allows the project to compile on non-Linux OSs, returning "not supported" errors at runtime rather than failing at build time.
+- **Platform Agnosticism**: `pkg/` libraries (e.g., `pkg/wgconf`) must remain platform-agnostic and avoid any OS-specific imports to ensure they are reusable across all environments.
+
+### 4. Testing Strategy
 We employ a three-tier testing approach to balance speed and reliability:
 
 | Tier | Location | Type | Scope | Requirement |
diff --git a/internal/namespace/namespace.go b/internal/namespace/namespace.go
new file mode 100644
index 0000000..ed9c468
--- /dev/null
+++ b/internal/namespace/namespace.go
@@ -0,0 +1,6 @@
+//go:build linux
+
+package namespace
+
+// The namespace package handles the creation and management of
+// Linux network and user namespaces.
diff --git a/internal/namespace/namespace_stub.go b/internal/namespace/namespace_stub.go
new file mode 100644
index 0000000..352ec13
--- /dev/null
+++ b/internal/namespace/namespace_stub.go
@@ -0,0 +1,5 @@
+//go:build !linux
+
+package namespace
+
+// The namespace package provides stubs for non-Linux platforms.
diff --git a/internal/wireguard/wireguard.go b/internal/wireguard/wireguard.go
new file mode 100644
index 0000000..bd7124a
--- /dev/null
+++ b/internal/wireguard/wireguard.go
@@ -0,0 +1,6 @@
+//go:build linux
+
+package wireguard
+
+// The wireguard package manages the userspace WireGuard device
+// and its binding to the Linux TUN interface.
diff --git a/internal/wireguard/wireguard_stub.go b/internal/wireguard/wireguard_stub.go
new file mode 100644
index 0000000..a6b8dac
--- /dev/null
+++ b/internal/wireguard/wireguard_stub.go
@@ -0,0 +1,5 @@
+//go:build !linux
+
+package wireguard
+
+// The wireguard package provides stubs for non-Linux platforms.