docs: expand nordvpn client setup and troubleshooting

docs/plans/2026-03-12-nordvpn-client-docs-refresh.md

@@ -0,0 +1,76 @@
+# NordVPN Client Docs Refresh Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Refresh the `nordvpn-client` documentation so operators and the OpenClaw agent have complete, accurate setup and troubleshooting guidance for the current macOS and Linux backends.
+
+**Architecture:** Expand the canonical repo doc into a full operator guide, tighten the agent-facing `SKILL.md` to match the current behavior, and lightly update summary docs only if their current one-line descriptions are materially incomplete. Sync the updated `SKILL.md` into the installed OpenClaw workspace copy so runtime guidance matches the repo.
+
+**Tech Stack:** Markdown docs, local repo skill docs, OpenClaw workspace skill sync
+
+---
+
+### Task 1: Refresh canonical operator documentation
+
+**Files:**
+- Modify: `docs/nordvpn-client.md`
+
+**Step 1: Rewrite the doc structure**
+- Add sections for overview, platform backends, prerequisites, credential paths, install/bootstrap, macOS sudoers setup, command flows, output model, and troubleshooting.
+
+**Step 2: Add exact operator setup details**
+- Include the exact `visudo` entry for the helper script.
+- Document default token/password file locations.
+- Document Homebrew install commands for macOS tooling.
+
+**Step 3: Add safe troubleshooting guidance**
+- Include only safe operator procedures from the debugging work:
+  - invalid token handling
+  - `sudoReady: false`
+  - Tailscale suspend/resume expectations
+  - what normal redacted output includes
+  - how to use `--debug` when deeper inspection is needed
+
+### Task 2: Refresh agent-facing skill documentation
+
+**Files:**
+- Modify: `skills/nordvpn-client/SKILL.md`
+- Sync: `/Users/stefano/.openclaw/workspace/skills/nordvpn-client/SKILL.md`
+
+**Step 1: Tighten the skill instructions**
+- Keep the doc shorter than the canonical operator guide.
+- Ensure it explicitly covers the default credential paths, macOS sudoers requirement, Tailscale suspend/resume behavior, and `--debug` usage.
+
+**Step 2: Sync installed OpenClaw copy**
+- Copy the updated repo `SKILL.md` into the installed workspace skill path.
+
+### Task 3: Update summary docs if needed
+
+**Files:**
+- Check: `README.md`
+- Check: `docs/README.md`
+- Modify only if current summary text is materially missing the current backend model.
+
+**Step 1: Review summary descriptions**
+- Confirm whether the one-line descriptions already adequately describe Linux CLI + macOS NordLynx/WireGuard.
+
+**Step 2: Update only if necessary**
+- Avoid churn if the existing summaries are already sufficient.
+
+### Task 4: Verify and publish
+
+**Files:**
+- Verify: `docs/nordvpn-client.md`
+- Verify: `skills/nordvpn-client/SKILL.md`
+- Verify: `/Users/stefano/.openclaw/workspace/skills/nordvpn-client/SKILL.md`
+
+**Step 1: Run doc verification checks**
+- Run: `rg -n "sudoers|visudo|--debug|Tailscale|token.txt|wireguard-helper" docs/nordvpn-client.md skills/nordvpn-client/SKILL.md`
+- Expected: all required topics present
+
+**Step 2: Confirm installed workspace skill matches repo skill**
+- Run: `cmp skills/nordvpn-client/SKILL.md /Users/stefano/.openclaw/workspace/skills/nordvpn-client/SKILL.md`
+- Expected: no output
+
+**Step 3: Commit and push**
+- Commit message: `docs: expand nordvpn client setup and troubleshooting`