FreeGuard VPN Setup Guide

Use when a user wants to set up, use, or troubleshoot FreeGuard VPN - guides non-technical users through installation, login, connection, and daily usage with friendly step-by-step instructions

# FreeGuard VPN Setup Guide

An agent skill for guiding users through FreeGuard VPN setup and daily usage. Designed for non-technical users — use friendly language instead of internal technical terms.

## Required Tools

This skill requires the `freeguard` CLI binary. If not already installed, the skill will guide the user through installation (Step 2). All commands are run through the user's terminal with standard tool-call permissions.

| Binary | Install (recommended) | Purpose |
|--------|-----------------------|---------|
| `freeguard` | `brew install planetlinkinc/tap/freeguardvpn` | VPN CLI — all operations in this skill depend on it |

## Vendor & Domain Information

FreeGuard VPN is developed by **Planetlink Inc.**

| Purpose | Domain | Notes |
|---------|--------|-------|
| Homepage | `https://freeguardvpn.com` | Product homepage |
| GitHub Releases | `github.com/planetlinkinc/freeguard-releases` | Public repo — binary releases with SHA256 checksums |
| Homebrew tap | `github.com/planetlinkinc/homebrew-tap` | Public repo — signed formula, downloads from GitHub Releases |
| Install scripts | `downloadcli.freeguardvpn.com` | Convenience install scripts (Option 3) |
| API backend | `www.freeguardvpn.com` | Login, subscription, profile sync |

The CLI source code is proprietary (not open-source). All credentials are sent exclusively to `freeguardvpn.com` over HTTPS. No other domains receive user data.

## Credentials & Data Handling

- **Email**: asked from user for login/subscription, sent to `freeguardvpn.com` API over HTTPS
- **Verification code**: 6-digit code sent to user's email, entered by user, verified against `freeguardvpn.com` API
- **Subscription URL / Access token**: provided by user, stored locally only
- **Local storage**: `~/.freeguard/credentials.yaml` with `0600` permissions (owner read/write only)
- **No upload or sync**: credentials are stored locally and never uploaded, synced, or transmitted to any server after initial login. The CLI reads them locally for subsequent operations.
- **No credentials are stored or transmitted by this skill itself** — all credential handling is performed by the `freeguard` CLI binary

## Tone

When speaking **to the user**, always use friendly, non-technical language:
- Simple phrasing: "open your terminal" not "execute in shell"
- Celebrate progress: "Great, you're logged in!"
- If something fails, reassure: "No worries, let's try another way"
- Never expose internal terms to the user: say "settings" not "YAML", "VPN engine" not "mihomo", "smart routing" not "rule-provider" (see Language Guide below for full mapping)

Note: the agent-facing instructions in this document reference file paths, config keys, and CLI flags — these are for the agent's internal use and should NOT be repeated verbatim to the user.

## Agent Flow

```dot
digraph setup {
    rankdir=TB;
    start [label="User wants VPN" shape=doublecircle];
    installed [label="Installed?" shape=diamond];
    install [label="Guide installation" shape=box];
    hassub [label="Has subscription?" shape=diamond];
    subscribe [label="Guide purchase" shape=box];
    loggedin [label="Logged in?" shape=diamond];
    login [label="Guide login" shape=box];
    region [label="Ask region\n& apply settings" shape=box];
    auth [label="Ask user for\nadmin permission" shape=box];
    canroot [label="User grants\nadmin?" shape=diamond];
    sudoconnect [label="sudo connect\n(full protection)" shape=box];
    normalconnect [label="connect\n(standard mode)" shape=box];
    verify [label="Verify & teach\ndaily usage" shape=box];
    done [label="All set!" shape=doublecircle];

    start -> installed;
    installed -> install [label="no"];
    installed -> hassub [label="yes"];
    install -> hassub;
    hassub -> subscribe [label="no"];
    hassub -> loggedin [label="yes"];
    subscribe -> loggedin;
    loggedin -> login [label="no"];
    loggedin -> region [label="yes"];
    login -> region;
    region -> auth;
    auth -> canroot;
    canroot -> sudoconnect [label="yes"];
    canroot -> normalconnect [label="no"];
    sudoconnect -> verify;
    normalconnect -> verify;
    verify -> done;
}
```

## Step 1: Check Environment

Run the diagnostic command and summarize the result to the user:

```bash
freeguard doctor --json
```

From the result, determine:
- **Not installed** → Go to Installation
- **Installed, no subscription** → Go to Subscribe
- **Installed, has subscription but not logged in** → Go to Login
- **Logged in with subscription** → Go to Region & Connect

Tell the user the current state in friendly terms:
- "Looks like FreeGuard isn't installed yet. Let me help you set it up!"
- "FreeGuard is installed! Now we need to get you a subscription."
- "You have a subscription but aren't logged in yet. Let's fix that."
- "You're already logged in! Let's get you connected."

## Step 2: Installation

Ask the user's operating system if unclear, then recommend the install method **in this priority order**:

### Option 1 (Recommended): Homebrew (macOS / Linux)

```bash
brew install planetlinkinc/tap/freeguardvpn
```

Best option — signed formula, checksum-verified, and auto-updates via Homebrew. The formula source is public at [github.com/planetlinkinc/homebrew-tap](https://github.com/planetlinkinc/homebrew-tap).

### Option 2: GitHub Release (macOS / Linux / Windows)

Download pre-built binaries directly from the official GitHub Releases page. Each release includes SHA256 checksums for verification.

> "I can download FreeGuard from the official GitHub releases page. This is a verified download with checksum — would you like me to go ahead?"

Only proceed after user explicitly confirms.

```bash
# Step 1: Download the binary and checksum file from GitHub Releases
# Replace <VERSION> and <ASSET> with the latest release info
curl -fsSL https://github.com/planetlinkinc/freeguard-releases/releases/latest/download/<ASSET> -o /tmp/freeguard.tar.gz
curl -fsSL https://github.com/planetlinkinc/freeguard-releases/releases/latest/download/checksums.txt -o /tmp/checksums.txt

# Step 2: Verify checksum before installing
cd /tmp && shasum -a 256 -c checksums.txt --ignore-missing
```

If checksum passes, extract and install:
```bash
# Step 3: Extract and move to PATH
tar xzf /tmp/freeguard.tar.gz -C /tmp
sudo mv /tmp/freeguard /usr/local/bin/freeguard
```

**To find the correct asset name**, check the latest release at: `https://github.com/planetlinkinc/freeguard-releases/releases/latest`

Asset naming convention:
- macOS (Apple Silicon): `freeguard-darwin-arm64.tar.gz`
- macOS (Intel): `freeguard-darwin-amd64.tar.gz`
- Linux (x64): `freeguard-linux-amd64.tar.gz`
- Windows (x64): `freeguard-windows-amd64.zip`

### Option 3: Install script (convenience)

Downloads the latest binary from the official FreeGuard CDN (`downloadcli.freeguardvpn.com`). **Always download the script first, let the user inspect it, then execute.** Ask for explicit confirmation before running.

> "I can also download an install script that automates the process. I'll show you the script first so you can review it. **Would you like to try this, or prefer Homebrew / GitHub Release instead?**"

Only proceed after user explicitly confirms.

**macOS / Linux:**
```bash
# Step 1: Download the script for inspection
curl -fsSL https://downloadcli.freeguardvpn.com/cli/install.sh -o /tmp/freeguard-install.sh

# Step 2: Show the user what the script does
cat /tmp/freeguard-install.sh
```

After showing the script content, tell the user:
> "Here's what the install script does: [brief summary of the script's actions]. Shall I run it?"

Only after user confirms:
```bash
# Step 3: Execute the reviewed script
sh /tmp/freeguard-install.sh
```

**Windows (PowerShell):**
```powershell
# Step 1: Download the script for inspection
Invoke-WebRequest -Uri https://downloadcli.freeguardvpn.com/cli/install.ps1 -OutFile $env:TEMP\freeguard-install.ps1

# Step 2: Show the user what the script does
Get-Content $env:T