docs: add nordvpn client plan

docs/plans/2026-03-11-nordvpn-client.md

@@ -0,0 +1,127 @@
+# NordVPN Client Skill Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Build a cross-platform `nordvpn-client` skill for macOS and Linux that can install/bootstrap NordVPN, log in, connect to a target country or city, verify the VPN session, disconnect, and report status.
+
+**Architecture:** Implement one skill with one script entrypoint and platform-specific backends. Linux uses the official NordVPN CLI. macOS uses a CLI path when present and otherwise falls back to the NordVPN app workflow. The skill manages VPN state only, leaving follow-up operations like `web-automation` to separate agent steps.
+
+**Tech Stack:** Node.js, shell/OS commands, NordVPN CLI/app integration, OpenClaw skills, git
+
+---
+
+### Task 1: Create isolated worktree
+
+**Files:**
+- Modify: repo git metadata only
+
+**Step 1: Create worktree**
+
+Run:
+```bash
+git -C /Users/stefano/.openclaw/workspace/projects/stef-openclaw-skills worktree add /Users/stefano/.openclaw/workspace/projects/stef-openclaw-skills/.worktrees/nordvpn-client -b feature/nordvpn-client
+```
+
+**Step 2: Verify baseline**
+
+Run:
+```bash
+git -C /Users/stefano/.openclaw/workspace/projects/stef-openclaw-skills/.worktrees/nordvpn-client status --short --branch
+```
+Expected: clean feature branch
+
+### Task 2: Create the local skill runtime
+
+**Files:**
+- Create: `skills/nordvpn-client/SKILL.md`
+- Create: `skills/nordvpn-client/scripts/nordvpn-client.js`
+- Optional Create: helper files under `skills/nordvpn-client/scripts/`
+
+**Step 1: Write the failing checks**
+- Missing command/action should fail with clear usage output
+- Unsupported platform should fail clearly
+
+**Step 2: Implement platform detection and install probe**
+- detect `darwin` vs `linux`
+- detect whether NordVPN CLI/app is already present
+- expose `status` with install/auth/connect fields
+
+### Task 3: Implement install and auth bootstrap
+
+**Files:**
+- Modify: `skills/nordvpn-client/scripts/nordvpn-client.js`
+
+**Step 1: Linux install/login path**
+- implement official CLI probe/install path
+- implement token-based login path
+
+**Step 2: macOS install/login path**
+- probe CLI first
+- if absent, probe/install NordVPN app path
+- implement login/bootstrap state verification for the app workflow
+
+**Step 3: Keep secrets external**
+- env vars or local credential path only
+- no raw secrets in docs or skill text
+
+### Task 4: Implement connect/disconnect/status/verification
+
+**Files:**
+- Modify: `skills/nordvpn-client/scripts/nordvpn-client.js`
+
+**Step 1: Connect**
+- support `--country` and `--city`
+- normalize target handling per platform
+
+**Step 2: Verify**
+- report local connection state
+- run public IP / geolocation verification
+- fail if connection target cannot be reasonably verified
+
+**Step 3: Disconnect and status**
+- implement clean disconnect
+- ensure `status` emits machine-readable output for agent use
+
+### Task 5: Validate locally in OpenClaw workspace
+
+**Files:**
+- Test: local workspace copy of `nordvpn-client`
+
+**Step 1: Direct command validation**
+- usage errors are correct
+- install probe works on this host
+- status output is coherent before login/connect
+
+**Step 2: One real connect flow**
+- connect to a test country/city if credentials are available
+- verify local state + external IP/location
+- disconnect cleanly
+
+### Task 6: Promote to repo docs and publish
+
+**Files:**
+- Modify: `README.md`
+- Modify: `docs/README.md`
+- Create: `docs/nordvpn-client.md`
+- Create/Modify: `skills/nordvpn-client/...`
+
+**Step 1: Document the skill**
+- install/bootstrap behavior
+- auth expectations
+- connect/disconnect/status commands
+- macOS vs Linux notes
+
+**Step 2: Commit and push**
+
+Run:
+```bash
+git add skills/nordvpn-client docs README.md
+git commit -m "feat: add nordvpn client skill"
+git push -u origin feature/nordvpn-client
+```
+
+**Step 3: Merge and cleanup**
+- fast-forward or merge to `main`
+- push `main`
+- remove the worktree
+- delete the feature branch