feat: add mac wireguard nordvpn backend

docs/README.md

@@ -6,7 +6,7 @@ This folder contains detailed docs for each skill in this repository.
 
 - [`elevenlabs-stt`](elevenlabs-stt.md) — Local audio transcription through ElevenLabs Speech-to-Text
 - [`gitea-api`](gitea-api.md) — REST-based Gitea automation (no `tea` CLI required)
-- [`nordvpn-client`](nordvpn-client.md) — Cross-platform NordVPN install, login, connect, disconnect, and verification
+- [`nordvpn-client`](nordvpn-client.md) — Cross-platform NordVPN install, login, connect, disconnect, and verification with Linux CLI and macOS NordLynx/WireGuard support
 - [`portainer`](portainer.md) — Portainer stack management (list, lifecycle, updates, image pruning)
 - [`searxng`](searxng.md) — Privacy-respecting metasearch via a local or self-hosted SearXNG instance
 - [`web-automation`](web-automation.md) — One-shot extraction plus Playwright-compatible CloakBrowser browser automation and scraping

docs/nordvpn-client.md

@@ -4,9 +4,9 @@ Cross-platform NordVPN lifecycle skill for macOS and Linux.
 
 ## What it does
 
-- Probes whether NordVPN is already installed
-- Bootstraps NordVPN if missing
-- Handles login bootstrap
+- Probes whether NordVPN is already installed or automation-ready
+- Bootstraps the required backend if missing
+- Handles login/bootstrap
 - Connects to a country or city target
 - Disconnects and reports status
 - Verifies public IP and geolocation after connect
@@ -29,12 +29,15 @@ node skills/nordvpn-client/scripts/nordvpn-client.js disconnect
 
 ### macOS
 
-- install path: `brew install --cask nordvpn`
-- probe order:
-  - `nordvpn` CLI if present
-  - `NordVPN.app`
-- if the installed package exposes a usable CLI, the skill uses it
-- otherwise it opens the app and returns a clear manual-action-required result for login/connect/disconnect
+- preferred backend: NordLynx/WireGuard
+- install path: `brew install wireguard-go wireguard-tools`
+- automation requirements:
+  - `NORDVPN_TOKEN` or `NORDVPN_TOKEN_FILE`
+  - `wireguard-go`
+  - `wireguard-tools`
+  - non-interactive `sudo` for `wg-quick`
+- `NordVPN.app` may stay installed but is only the manual fallback
+- the app login is not reused by the automated WireGuard backend
 
 ### Linux
 
@@ -60,7 +63,7 @@ Do not put secrets in the skill docs or repo.
 
 - platform
 - install state
-- control mode (`cli` vs `app-manual`)
+- control mode (`cli`, `wireguard`, `app-manual`)
 - auth state
 - connection state
 - requested target
@@ -74,6 +77,6 @@ After `connect`, the intended workflow is:
 
 ## Limitations
 
-- Linux city targeting is attempted through the CLI target string and then validated by public IP/location checks.
-- macOS app-only fallback cannot guarantee non-interactive control if the app does not expose a CLI.
-- On macOS, the Homebrew cask may install only the GUI app. That is still a supported install state; `status` reports `controlMode: "app-manual"` so agents should continue with the app flow instead of concluding NordVPN is unavailable.
+- Linux behavior still depends on the official `nordvpn` CLI.
+- macOS automated connects require token-based WireGuard setup; GUI-app login alone is insufficient.
+- The Homebrew `nordvpn` app does not need to be uninstalled.

docs/plans/2026-03-11-nordvpn-wireguard-macos-design.md

@@ -0,0 +1,34 @@
+# NordVPN macOS WireGuard Backend Design
+
+## Goal
+Replace the current macOS app-manual fallback in `nordvpn-client` with a scripted WireGuard/NordLynx backend inspired by `wg-nord` and `wgnord`, while preserving the official Linux `nordvpn` CLI backend.
+
+## Key decisions
+- Keep Linux on the official `nordvpn` CLI.
+- Prefer a native macOS WireGuard backend over the GUI app.
+- Do not vendor third-party scripts directly; reimplement the needed logic in our own JSON-based Node skill.
+- Do not require uninstalling the Homebrew `nordvpn` app. The new backend can coexist with it.
+
+## macOS backend model
+- Bootstrap via Homebrew:
+  - `wireguard-tools`
+  - `wireguard-go`
+- Read NordVPN token from existing env/file inputs.
+- Discover a WireGuard-capable NordVPN server via the public Nord API.
+- Generate a private key locally.
+- Exchange the private key for Nord-provided interface credentials using the token.
+- Materialize a temporary WireGuard config under a skill-owned state directory.
+- Connect and disconnect via `wg-quick`.
+- Verify with public IP/geolocation after connect.
+
+## Data/state
+- Keep state under a skill-owned directory in the user's home, not `/etc`.
+- Persist only what is needed for reconnect/disconnect/status.
+- Never store secrets in docs.
+
+## Rollout
+1. Implement the macOS WireGuard backend in the skill.
+2. Update status output so backend selection is explicit.
+3. Update skill docs and repo docs.
+4. Verify non-destructive flows on this host.
+5. Commit, push, and then decide whether to run a live connect test.

docs/plans/2026-03-11-nordvpn-wireguard-macos.md

@@ -0,0 +1,11 @@
+# NordVPN macOS WireGuard Backend Plan
+
+1. Add a backend selector to `nordvpn-client`.
+2. Keep Linux CLI behavior unchanged.
+3. Add macOS WireGuard dependency probing and install guidance.
+4. Implement token-based NordLynx config generation inspired by `wg-nord`/`wgnord`.
+5. Replace the current preferred macOS control mode from `app-manual` to WireGuard when dependencies and token are available.
+6. Keep app-manual as the last fallback only.
+7. Update `status`, `login`, `connect`, `disconnect`, and `verify` JSON to expose the backend in use.
+8. Update repo docs and skill docs to reflect the new model and required token/dependencies.
+9. Verify command behavior locally without forcing a live VPN connection unless requested.