# NordVPN Client Skill Design

## Goal
Create a `nordvpn-client` skill that works on macOS and Linux gateway hosts. It should detect whether NordVPN is already installed, bootstrap it if missing, handle login/auth setup, connect to a requested country or city, verify the VPN state and public IP location, disconnect when requested, and then be usable alongside other skills like `web-automation`.

## Architecture
The skill exposes one logical interface with platform-specific backends. Linux uses the official NordVPN CLI path. macOS probes for a usable CLI first, but falls back to the official app workflow when needed. The skill is responsible only for VPN lifecycle and verification, not for wrapping arbitrary commands inside a VPN session.

## Interface
Single script entrypoint:
- `node scripts/nordvpn-client.js install`
- `node scripts/nordvpn-client.js login`
- `node scripts/nordvpn-client.js connect --country "Italy"`
- `node scripts/nordvpn-client.js connect --city "Milan"`
- `node scripts/nordvpn-client.js disconnect`
- `node scripts/nordvpn-client.js status`

## Platform Model
### Linux
- Probe for `nordvpn`
- If missing, bootstrap official NordVPN package/CLI
- Prefer token-based login for non-interactive auth
- Connect/disconnect/status through official CLI

### macOS
- Probe for `nordvpn` CLI if available
- Otherwise probe/install the official app
- Use CLI when present, otherwise automate the app/login flow
- Verify connection using app/CLI state plus external IP/geolocation

## Auth and Safety
- Do not store raw NordVPN secrets in skill docs
- Read token/credentials from env vars or a local credential file path
- Keep the skill focused on install/login/connect/disconnect/status
- After `connect`, verify both local VPN state and external IP/location before the agent proceeds to tasks like `web-automation`

## Verification
- `status` reports platform, install state, auth state, connection state, and public IP/location check
- `connect` verifies the requested target as closely as available data allows
- Local validation happens first in the OpenClaw workspace, then the proven skill is copied into `stef-openclaw-skills`, documented, committed, and pushed