From 78be4fc6004ac3fd44537a5300609b902acf3db0 Mon Sep 17 00:00:00 2001
From: Stefano Fiorini <stefano@Stefanos-MacBook-Air.local>
Date: Wed, 11 Mar 2026 23:53:15 -0500
Subject: [PATCH] docs: clarify nordvpn mac setup flow

---
 docs/nordvpn-client.md                          |  8 ++++++++
 skills/nordvpn-client/SKILL.md                  | 11 +++++++++++
 skills/nordvpn-client/scripts/nordvpn-client.js |  8 ++++----
 3 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/docs/nordvpn-client.md b/docs/nordvpn-client.md
index 641ecbc..9409b40 100644
--- a/docs/nordvpn-client.md
+++ b/docs/nordvpn-client.md
@@ -39,6 +39,14 @@ node skills/nordvpn-client/scripts/nordvpn-client.js disconnect
 - `NordVPN.app` may stay installed but is only the manual fallback
 - the app login is not reused by the automated WireGuard backend
 
+Quick start:
+
+1. `node skills/nordvpn-client/scripts/nordvpn-client.js install`
+2. set `NORDVPN_TOKEN` or `NORDVPN_TOKEN_FILE`
+3. `node skills/nordvpn-client/scripts/nordvpn-client.js login`
+4. `node skills/nordvpn-client/scripts/nordvpn-client.js connect --country "Italy"` or `--city "Milan"`
+5. `node skills/nordvpn-client/scripts/nordvpn-client.js verify`
+
 ### Linux
 
 - install path follows NordVPN's official installer script
diff --git a/skills/nordvpn-client/SKILL.md b/skills/nordvpn-client/SKILL.md
index 0e72c60..ee45c97 100644
--- a/skills/nordvpn-client/SKILL.md
+++ b/skills/nordvpn-client/SKILL.md
@@ -40,6 +40,7 @@ node scripts/nordvpn-client.js disconnect
 - macOS:
   - preferred backend is NordLynx/WireGuard using `wireguard-go` and `wireguard-tools`
   - `install` bootstraps those tools with Homebrew
+  - equivalent Homebrew command: `brew install wireguard-go wireguard-tools`
   - `login` validates `NORDVPN_TOKEN` / `NORDVPN_TOKEN_FILE` for the WireGuard backend
   - `NordVPN.app` can remain installed, but it is only the manual fallback
 
@@ -73,6 +74,16 @@ Optional credential file env vars:
 Use this skill first, then run the follow-up task under the active VPN session.
 Use `verify` when you want an explicit post-connect location check without changing VPN state.
 
+## macOS Quick Start
+
+For an automated macOS flow:
+
+1. `node scripts/nordvpn-client.js install`
+2. set `NORDVPN_TOKEN` or `NORDVPN_TOKEN_FILE`
+3. `node scripts/nordvpn-client.js login`
+4. `node scripts/nordvpn-client.js connect --country "Italy"` or `--city "Milan"`
+5. `node scripts/nordvpn-client.js verify`
+
 ## Known Boundaries
 
 - Linux country/city connect remains whatever the official `nordvpn` CLI supports.
diff --git a/skills/nordvpn-client/scripts/nordvpn-client.js b/skills/nordvpn-client/scripts/nordvpn-client.js
index 9952ef2..0007330 100644
--- a/skills/nordvpn-client/scripts/nordvpn-client.js
+++ b/skills/nordvpn-client/scripts/nordvpn-client.js
@@ -369,7 +369,7 @@ function buildStateSummary(installProbe, ipInfo) {
     recommendedAction = installProbe.tokenAvailable
       ? installProbe.wireguard.sudoReady
         ? "Use token-based WireGuard automation on macOS."
-        : "WireGuard tooling and token are available, but connect/disconnect require non-interactive sudo for wg-quick."
+        : "WireGuard tooling and token are available, but connect/disconnect require non-interactive sudo for wg-quick. Authorize sudo for wg-quick, then rerun login/connect."
       : "Set NORDVPN_TOKEN or NORDVPN_TOKEN_FILE for automated macOS NordLynx/WireGuard connects.";
   } else if (installProbe.platform === "darwin" && installProbe.appInstalled) {
     controlMode = "app-manual";
@@ -377,14 +377,14 @@ function buildStateSummary(installProbe, ipInfo) {
     loginMode = "app-manual";
     connectMode = "app-manual";
     recommendedAction = installProbe.tokenAvailable
-      ? "NordVPN.app is installed, but automated macOS connects also require wireguard-go and wireguard-tools. Run install to bootstrap them."
-      : "NordVPN.app is installed. Without a PATH-visible CLI or a NordVPN token plus WireGuard tools, login/connect fall back to the app.";
+      ? "NordVPN.app is installed, but automated macOS connects also require wireguard-go and wireguard-tools. Run 'node scripts/nordvpn-client.js install' to install them with Homebrew."
+      : "NordVPN.app is installed. For automated macOS connects, run 'node scripts/nordvpn-client.js install' to install wireguard-go and wireguard-tools with Homebrew, then set NORDVPN_TOKEN or NORDVPN_TOKEN_FILE and run login.";
   } else if (installProbe.platform === "darwin" && installProbe.brewPath) {
     controlMode = "wireguard-bootstrap";
     automaticControl = false;
     loginMode = "wireguard-token";
     connectMode = "wireguard";
-    recommendedAction = "Run install to bootstrap wireguard-go and wireguard-tools for automated macOS NordLynx connects.";
+    recommendedAction = "Run 'node scripts/nordvpn-client.js install' to install wireguard-go and wireguard-tools with Homebrew for automated macOS NordLynx connects.";
   }
 
   return {