From 6bc21219a7ba7f291cb959a4c375fddbc9644ee0 Mon Sep 17 00:00:00 2001
From: Stefano Fiorini <stefano@Stefanos-MacBook-Air.local>
Date: Thu, 12 Mar 2026 01:35:32 -0500
Subject: [PATCH] docs: add nordvpn macos dns plan

---
 .../2026-03-12-nordvpn-macos-dns-design.md    | 40 +++++++++++++++++++
 docs/plans/2026-03-12-nordvpn-macos-dns.md    | 11 +++++
 2 files changed, 51 insertions(+)
 create mode 100644 docs/plans/2026-03-12-nordvpn-macos-dns-design.md
 create mode 100644 docs/plans/2026-03-12-nordvpn-macos-dns.md

diff --git a/docs/plans/2026-03-12-nordvpn-macos-dns-design.md b/docs/plans/2026-03-12-nordvpn-macos-dns-design.md
new file mode 100644
index 0000000..f3e071c
--- /dev/null
+++ b/docs/plans/2026-03-12-nordvpn-macos-dns-design.md
@@ -0,0 +1,40 @@
+# NordVPN macOS DNS Design
+
+## Goal
+Keep NordVPN DNS while connected on macOS, but only apply it to active physical services so the WireGuard backend does not break Tailscale or other virtual interfaces.
+
+## Behavior
+- Keep the generated WireGuard config free of `DNS = ...`
+- During `connect` on macOS:
+  - detect active physical network services
+  - snapshot current DNS/search-domain settings
+  - set NordVPN DNS only on those physical services
+- During `disconnect`:
+  - restore the saved DNS/search-domain settings
+- During failed `connect` after DNS changes:
+  - restore DNS before returning the error
+
+## DNS Values
+- IPv4 primary: `103.86.96.100`
+- IPv4 secondary: `103.86.99.100`
+- No IPv6 DNS for now
+
+## Service Selection
+Include only enabled physical services from `networksetup`.
+Exclude names matching:
+- Tailscale
+- Bridge
+- Thunderbolt Bridge
+- Loopback
+- VPN
+- utun
+
+## Persistence
+- Save DNS snapshot under `~/.nordvpn-client`
+- Overwrite on each successful connect
+- Clear after successful disconnect restore
+
+## Verification
+- Unit tests for service selection and DNS snapshot/restore helpers
+- Direct logic/config tests
+- Avoid live connect tests from this session unless explicitly requested because they can drop connectivity
diff --git a/docs/plans/2026-03-12-nordvpn-macos-dns.md b/docs/plans/2026-03-12-nordvpn-macos-dns.md
new file mode 100644
index 0000000..9e702f0
--- /dev/null
+++ b/docs/plans/2026-03-12-nordvpn-macos-dns.md
@@ -0,0 +1,11 @@
+# NordVPN macOS DNS Plan
+
+1. Add macOS DNS state file support under `~/.nordvpn-client`.
+2. Implement helpers to enumerate eligible physical services and snapshot existing DNS/search-domain settings.
+3. Implement helpers to apply NordVPN DNS only to eligible physical services.
+4. Implement helpers to restore previous DNS/search-domain settings on disconnect or failed connect.
+5. Add unit tests for service filtering and DNS state transitions.
+6. Update skill/docs to explain macOS physical-service DNS management.
+7. Sync the installed workspace copy.
+8. Run tests and non-destructive verification.
+9. Commit and push.