docs: correct macOS/Linux tunnel dependency story

The native sentinel-dvpncli does NOT bundle a tunnel -- it shells out to
the system binary on PATH (wg-quick for WireGuard nodes, v2ray for V2Ray
nodes). Verified against upstream sentinel-go-sdk (development branch):
client_unix.go execFile returns the bare name under //go:build darwin||linux,
so the binary is resolved from PATH and must be installed by the user.
Windows bundles them (execFile returns ".\WireGuard\name.exe") via setup().

Removed the false "WireGuard ships with the OS / nothing to install /
easiest / works out of the box" claims from docs/llms.txt and docs/index.html.
Now instruct: install wireguard-tools (apt/brew/pacman), plus a v2ray binary
for V2Ray nodes, and sudo to bring the interface up. Fedora stays unsupported.

Author: Sentinel-Bluebuilder

docs/index.html

@@ -54,7 +54,7 @@
       "rpcFallbacks": ["https://rpc.sentinel.co:443", "https://sentinel-rpc.polkachu.com", "https://rpc.mathnodes.com", "https://sentinel-rpc.publicnode.com", "https://rpc.sentinel.quokkastake.io", "https://rpc.sentinel.suchnode.net:443"],
       "lcdFallbacks": ["https://lcd.sentinel.co", "https://sentinel-api.polkachu.com", "https://api.sentinel.quokkastake.io", "https://sentinel-rest.publicnode.com", "https://api.sentinel.suchnode.net"],
       "platforms": "Payment is identical everywhere; only the connect step differs by OS.",
-      "connectMacLinux": "EASIEST. WireGuard ships with the OS. Use native CLI sentinel-dvpncli (go install github.com/sentinel-official/sentinel-dvpncli@latest): (1) printf '%s\\n\\n' \"$MNEMONIC\" | sentinel-dvpncli keys add agent --keyring.backend test (keys add is interactive: line 1 = mnemonic, blank line 2 = default passphrase; there is no --recover flag); (2) sentinel-dvpncli tx session-start <nodeAddress> --subscription-id <subscriptionId> --tx.fee-granter-addr <feeGranter> --tx.from-name agent --keyring.backend test; (3) sessionId = sentinel-dvpncli query sessions --account-addr <sent1...> --subscription-id <subscriptionId> --output-format json (newest entry); (4) sentinel-dvpncli connect <sessionId>. Exception: Fedora (SELinux blocks VPNs).",
+      "connectMacLinux": "Native CLI sentinel-dvpncli (go install github.com/sentinel-official/sentinel-dvpncli@latest, needs Go 1.24+). The CLI does NOT bundle a tunnel: it shells out to wg-quick (install wireguard-tools: apt/brew/pacman) for WireGuard nodes, or v2ray on PATH for V2Ray nodes. Most nodes are WireGuard, so install wireguard-tools at minimum; sudo is needed to bring the interface up. Then: (1) printf '%s\\n\\n' \"$MNEMONIC\" | sentinel-dvpncli keys add agent --keyring.backend test (keys add is interactive: line 1 = mnemonic, blank line 2 = default passphrase; there is no --recover flag); (2) sentinel-dvpncli tx session-start <nodeAddress> --subscription-id <subscriptionId> --tx.fee-granter-addr <feeGranter> --tx.from-name agent --keyring.backend test; (3) sessionId = sentinel-dvpncli query sessions --account-addr <sent1...> --subscription-id <subscriptionId> --output-format json (newest entry); (4) sentinel-dvpncli connect <sessionId>. Exception: Fedora (SELinux blocks VPNs).",
       "connectWindows": "Heavier JS path. await setup() from blue-js-sdk/ai-path — run once on a fresh machine; auto-downloads V2Ray (no admin), checks/installs WireGuard (MSI needs admin); returns { ready, capabilities, recommended, issues }",
       "walletCreate": "createWallet() from blue-js-sdk/ai-path → { address, mnemonic }",
       "connect": "Windows JS tunnel: connect({ mnemonic, subscriptionId, feeGranter, nodeAddress }) → { connected, ip, protocol }. On macOS/Linux use connectMacLinux (native CLI) instead.",
@@ -1604,13 +1604,13 @@ <h1 class="fade-in">Private internet<br>for <span class="highlight">AI agents</s
         </span>
         <span class="os-label">Windows <span class="os-status">live</span></span>
       </div>
-      <div class="os-chip live" title="Live — easiest path, connect works out of the box">
+      <div class="os-chip live" title="Live — native CLI connect; install wireguard-tools (wg-quick) first">
         <span class="os-logo" aria-hidden="true">
           <svg viewBox="0 0 24 24" fill="currentColor"><path d="M16.4 1.3c.1 1.1-.3 2.2-1 3-.6.8-1.7 1.4-2.7 1.4-.2-1.1.3-2.2.9-2.9.8-.9 2-1.5 2.8-1.5Zm3.6 16.4c-.5 1.2-.8 1.7-1.4 2.8-.9 1.5-2.2 3.4-3.9 3.5-1.5 0-1.8-.9-3.8-.9-1.9 0-2.3.9-3.8.9-1.6-.1-2.9-1.8-3.8-3.3-2.5-4.3-2.7-9.4-1.2-12.1 1.1-1.9 2.8-3.1 4.4-3.1 1.5 0 2.5.9 3.8.9 1.3 0 2.1-.9 3.9-.9 1.4 0 3 .8 4.1 2.2-3.6 2-3 7.2 1.7 10Z"/></svg>
         </span>
         <span class="os-label">macOS <span class="os-status">live</span></span>
       </div>
-      <div class="os-chip live" title="Live — easiest path, connect works out of the box (except Fedora)">
+      <div class="os-chip live" title="Live — native CLI connect; install wireguard-tools first (except Fedora: SELinux blocks VPNs)">
         <span class="os-logo" aria-hidden="true">
           <svg viewBox="0 0 24 24" fill="currentColor"><path d="M12.5 2c-2 0-3.3 1.6-3.3 4 0 1 .2 1.9.4 2.5-.7.5-1.3 1.4-1.8 2.6-.7 1.6-1 3.8-1.7 5.2-.5 1-1.5 1.5-2 2.2-.4.4-.5 1.3.4 1.6.7.2 1.3-.2 1.9-.6.4-.3.9-.4 1.2-.4.4.1.5.5.6 1 .1 1.3 1 2.2 2.9 2.4 1.8.2 4-.4 5.7-.4 1 0 1.7.1 2.3.1.6 0 1-.5 1-1 0-.5-.4-.9-.9-1.3-1.1-1-1.4-2.3-1.8-4-.4-1.6-.9-3.5-2.3-4.7.4-.8.6-1.7.6-2.7 0-2.3-1.3-4-3.2-4Zm-1 3.3c.4 0 .6.5.6 1s-.3 1-.6 1-.7-.5-.7-1 .3-1 .7-1Zm2.1 0c.4 0 .6.5.6 1s-.3 1-.6 1-.7-.5-.7-1 .3-1 .7-1Z"/></svg>
         </span>
@@ -2061,11 +2061,11 @@ <h3 style="font-size: 13px; color: var(--accent); margin-bottom: 18px; letter-sp
 
     <div class="code-block" style="margin-bottom: 24px;">
       <div class="bar">
-        <div class="label">Step 3 &mdash; macOS &amp; Linux (easiest): connect via native CLI</div>
+        <div class="label">Step 3 &mdash; macOS &amp; Linux: connect via native CLI</div>
       </div>
       <pre><code><span class="cm">// Payment (Steps 0-2 above) is identical. macOS &amp; Linux skip the JS connect()</span>
-<span class="cm">// and use Sentinel's native CLI instead &mdash; WireGuard already ships with the OS,</span>
-<span class="cm">// so there's nothing to install for the tunnel. Four commands, scriptable end to end.</span>
+<span class="cm">// and use Sentinel's native CLI instead. Unlike Windows, the CLI does NOT bundle a tunnel:</span>
+<span class="cm">// it shells out to wg-quick, so install wireguard-tools first (apt/brew/pacman). Four commands.</span>
 <span class="cm">// CLI: https://github.com/sentinel-official/sentinel-dvpncli</span>
 
 <span class="cm">// Install once (Go 1.24+):</span>
@@ -2417,11 +2417,12 @@ <h2>End-to-end: USDC to VPN tunnel</h2>
 }
 
 <span class="cm">// ── Step 5: Connect to VPN (0 gas, 0 P2P) ──</span>
-<span class="cm">// This connect() is the Windows path. On macOS/Linux (easiest) use the native CLI instead:</span>
+<span class="cm">// This connect() is the Windows path. On macOS/Linux use the native CLI instead</span>
+<span class="cm">// (install wireguard-tools first — the CLI shells out to wg-quick, it bundles no tunnel):</span>
 <span class="cm">//   printf '%s\n\n' "$MNEMONIC" | sentinel-dvpncli keys add agent --keyring.backend test</span>
 <span class="cm">//   sentinel-dvpncli tx session-start &lt;nodeAddress&gt; --subscription-id &lt;id&gt; --tx.fee-granter-addr &lt;feeGranter&gt; --tx.from-name agent --keyring.backend test</span>
 <span class="cm">//   sessionId=$(sentinel-dvpncli query sessions --account-addr &lt;sent1...&gt; --subscription-id &lt;id&gt; --output-format json | jq '.result[-1].id')</span>
-<span class="cm">//   sentinel-dvpncli connect &lt;sessionId&gt;   (WireGuard ships with the OS; nothing to install)</span>
+<span class="cm">//   sentinel-dvpncli connect &lt;sessionId&gt;   (needs wg-quick on PATH: install wireguard-tools + sudo)</span>
 <span class="kw">const</span> vpn <span class="op">=</span> <span class="kw">await</span> <span class="fn">connect</span>({
   <span class="prop">mnemonic</span><span class="op">:</span> wallet<span class="op">.</span>mnemonic<span class="op">,</span>
   <span class="prop">nodeAddress</span><span class="op">,</span>

docs/llms.txt

@@ -10,7 +10,7 @@ The agent needs exactly one thing before calling x402: an EVM private key with a
 
 **Payment is identical on every platform.** What differs is *connecting* the tunnel after the server returns 200. There are two equally-supported connect paths — pick by OS:
 
-- **macOS & Linux (easiest):** WireGuard already ships with the OS, so there is nothing to install for the tunnel itself. Use the native `sentinel-dvpncli` (one `go install`), then drive it with three flag-only commands — see **"macOS & Linux — native CLI connect"** below. No admin/sudo for V2Ray; WireGuard may need sudo to bring an interface up, same as any WireGuard client. **Only exception: Fedora** — its SELinux blocks VPN interfaces and cannot be worked around programmatically; macOS, Ubuntu, Debian and other mainstream Linux are fine.
+- **macOS & Linux:** Use the native `sentinel-dvpncli` (one `go install`, Go 1.24+), then drive it with three flag-only commands — see **"macOS & Linux — native CLI connect"** below. The CLI does NOT bundle a tunnel: it shells out to `wg-quick` for WireGuard nodes, so install **wireguard-tools** first (`apt install wireguard-tools` | `brew install wireguard-tools` | `pacman -S wireguard-tools`), or a `v2ray` binary on PATH for V2Ray nodes. Most nodes are WireGuard; bringing the interface up needs sudo. **Only exception: Fedora** — its SELinux blocks VPN interfaces and cannot be worked around programmatically; macOS, Ubuntu, Debian and Arch are fine once the tunnel binary is installed.
 - **Windows (heavier):** run `await setup()` from `blue-js-sdk/ai-path` once on a fresh machine before `connect()`. It auto-downloads V2Ray 5.2.1 to `~/.sentinel-sdk/bin` (no admin) and detects/auto-installs WireGuard (the MSI install needs admin). It returns `{ ready, capabilities, recommended, issues }` — if `capabilities` includes `v2ray`, you can connect with zero manual installs. See **"Windows — JS-SDK connect"** below.
 
 Both paths consume the exact same 200 response (`subscriptionId`, `planId`, `feeGranter`, `nodeAddress`) and end in the same `MsgStartSession` + direct WireGuard/V2Ray handshake.
@@ -112,11 +112,16 @@ const vpn = await connect({
 
 ## macOS & Linux — native CLI connect
 
-This is the easiest connect path. After the `paidFetch` call above returns `provision`
+After the `paidFetch` call above returns `provision`
 (`{ subscriptionId, planId, feeGranter, nodeAddress, ... }`), do NOT call the JS `connect()`.
 Instead drive Sentinel's native `sentinel-dvpncli` — three fully flag-driven commands, no config
-files, no interactive prompts when you pass the flags below. WireGuard already ships with macOS
-and mainstream Linux, so there is nothing to install for the tunnel itself.
+files, no interactive prompts when you pass the flags below.
+
+Unlike the Windows path, the native CLI does NOT bundle a tunnel — it shells out to the system
+binary on your PATH. WireGuard nodes run `wg-quick`, so you must install **wireguard-tools**
+(`apt install wireguard-tools` | `brew install wireguard-tools` | `pacman -S wireguard-tools`).
+V2Ray nodes run `v2ray`, so if you select a V2Ray node you also need a **v2ray** binary on PATH.
+Most nodes are WireGuard, so install wireguard-tools at minimum. Bringing the interface up needs sudo.
 
 **Install once (Go 1.24+):**
 
@@ -157,7 +162,7 @@ SESSION_ID=$(sentinel-dvpncli query sessions \
 
 # 4. Bring the tunnel up. Takes the SESSION id (not the subscription id). No key needed —
 #    connect only queries the session on-chain and builds the tunnel.
-#    WireGuard nodes may need sudo to create the interface — same as any wg client.
+#    Requires wg-quick on PATH (install wireguard-tools) and sudo to create the interface.
 sentinel-dvpncli connect "$SESSION_ID"
 ```
 
@@ -167,16 +172,16 @@ Defaults baked into the CLI (override only if needed): `--rpc.addrs https://rpc.
 `sentinel-dvpncli tx session-cancel <id>` to tear down. `connect` traps SIGINT/SIGTERM and runs a
 clean down sequence on exit.
 
-> **Fedora caveat:** Fedora's SELinux blocks VPN interfaces and an agent cannot bypass it. macOS,
-> Ubuntu, Debian, Arch and other mainstream distros work out of the box. This is the only OS x402
-> cannot connect on.
+> **Fedora caveat:** Fedora's SELinux blocks VPN interfaces and an agent cannot bypass it. This is
+> the only OS x402 cannot connect on. macOS, Ubuntu, Debian and Arch all work once you install the
+> tunnel binary the CLI shells out to (wireguard-tools, plus v2ray for V2Ray nodes) — see above.
 
 ## Packages
 
 - `@x402/fetch` — wraps `fetch`, auto-signs 402 responses
 - `@x402/evm` — `ExactEvmScheme` EIP-3009 signer
 - `blue-js-sdk/ai-path` — Windows connect path: environment setup (`setup` — auto-installs tunnel binaries), Sentinel wallet (`createWallet`, `importWallet`), tunnel (`connect`, `disconnect`), and plan/node discovery (`rpcQueryNodesForPlan`, `createRpcQueryClientWithFallback`) — WireGuard/V2Ray
-- `sentinel-dvpncli` — macOS/Linux connect path: native Go CLI (`go install github.com/sentinel-official/sentinel-dvpncli@latest`). Flag-driven `keys` / `tx session-start` / `connect` — drives the tunnel without the JS SDK. WireGuard ships with the OS.
+- `sentinel-dvpncli` — macOS/Linux connect path: native Go CLI (`go install github.com/sentinel-official/sentinel-dvpncli@latest`, needs Go 1.24+). Flag-driven `keys` / `tx session-start` / `connect` — drives the tunnel without the JS SDK. Does NOT bundle a tunnel: shells out to `wg-quick` (install wireguard-tools) or `v2ray` on PATH.
 
 ## Request schema