function wgctl::help() {
cat <<EOF
$(log::section "wgctl — WireGuard Management" 2>/dev/null || printf "\n  wgctl — WireGuard Management\n")

Usage: wgctl <command> [options]

  Client Commands:
    add, new          Add a new client
    remove, rm        Remove a client
    rename, mv        Rename a client
    list, ls          List all clients
    inspect           Show detailed client info
    config            Show client config
    qr                Show QR code for a client

  Access Control:
    block, ban        Block a client entirely
    unblock, unban    Restore client access
    rule              Manage firewall rules (list, show, add, assign...)

  Organization:
    group             Manage peer groups (list, show, block, watch...)

  Monitoring:
    watch             Live monitor of WireGuard activity
    logs              Show activity and firewall logs
    audit             Verify firewall rules are correctly applied
    fw                Inspect firewall rules

  Service:
    service           Manage WireGuard service (start/stop/restart/status)
    restart           Restart WireGuard
    shell             Start interactive wgctl shell

  Development:
    test              Run the wgctl test suite

  Common examples:
    wgctl add --name nuno --type phone
    wgctl add --name visitor --type guest --subtype phone --group family
    wgctl list --blocked
    wgctl list --group family
    wgctl block --name phone-nuno
    wgctl inspect --name phone-nuno
    wgctl rule assign --name admin --peer laptop-nuno
    wgctl group block --name family
    wgctl logs --follow
    wgctl audit

Run 'wgctl <command> --help' for command-specific help.
EOF
}

function cmd::logs::help() {
  cat <<EOF
Usage: wgctl logs [subcommand] [options]

Show or manage WireGuard and firewall activity logs.

Subcommands:
  show (default)    Show activity logs
  remove, rm        Remove log entries

Options for show:
  --name <name>     Filter by client name
  --type <type>     Filter by device type
  --limit <n>       Max results per source (default: 50)
  --fw              Show only firewall drops
  --wg              Show only WireGuard events
  --follow, -f      Follow logs in real time

Options for remove:
  --name <name>     Remove entries for specific peer
  --all             Remove all log entries
  --fw              Remove only firewall events
  --wg              Remove only WireGuard events
  --before <days>   Remove entries older than N days
  --force           Skip confirmation

Examples:
  wgctl logs
  wgctl logs --name phone-nuno
  wgctl logs --fw --limit 100
  wgctl logs --follow
  wgctl logs remove --name phone-nuno
  wgctl logs remove --all --force
  wgctl logs remove --before 7
  wgctl logs remove --fw --before 1
EOF
}

function cmd::rule::help() {
  cat <<EOF
Usage: wgctl rule <subcommand> [options]

Manage firewall rules for peers.

Subcommands:
  list, ls                    List all rules
  show                        Show rule details
  inspect                     Show full inheritance tree
  add, new, create            Create a new rule
  update, edit                Update a rule and re-apply to all peers
  remove, rm, del             Remove a rule
  assign                      Assign a rule to a peer
  unassign                    Remove rule from a peer
  migrate                     Apply default rules to all unassigned peers
  reapply                     Re-apply a rule to all assigned peers

Options for list:
  --base                      Show base rules section
  --no-base                   Hide base rules section (default shows them)
  --group <name>              Filter by group name
  --tree                      Show full inheritance tree inline

Options for add/update:
  --name <name>               Rule name
  --desc <description>        Human readable description
  --group <group>             Display group (e.g. vm-rules, user-rules)
  --extends <rule,...>        Inherit from base rules (add only)
  --add-extends <rule,...>    Add base rules (update only)
  --remove-extends <rule,...> Remove base rules (update only)
  --allow-ip <ip/cidr>        Allow IP or subnet (repeatable)
  --allow-port <ip:port:proto> Allow specific port (repeatable)
  --block-ip <ip/cidr>        Block IP or subnet (repeatable)
  --block-port <ip:port:proto> Block specific port (repeatable)
  --dns-redirect              Force DNS through Pi-hole
  --remove-allow-ip <ip>      Remove allow IP entry
  --remove-allow-port <entry> Remove allow port entry
  --remove-block-ip <ip>      Remove block IP entry
  --remove-block-port <entry> Remove block port entry

Options for inspect:
  --name <name>               Rule name
  --peers                     Show assigned peers
  --resolved                  Show resolved/merged rule entries

Options for assign/unassign:
  --name <rule>               Rule name
  --peer <peer>               Peer name
  --type <type>               Peer device type (optional)

Examples:
  wgctl rule list
  wgctl rule list --base
  wgctl rule list --group vm-rules
  wgctl rule list --tree
  wgctl rule show --name guest
  wgctl rule inspect --name moonlight-02
  wgctl rule inspect --name moonlight-02 --resolved --peers
  wgctl rule add --name dev-01 --desc "Dev VM" --group vm-rules --extends no-lan
  wgctl rule update --name dev-01 --add-extends no-nginx
  wgctl rule update --name dev-01 --remove-extends no-nginx
  wgctl rule update --name dev-01 --group infra-rules
  wgctl rule assign --name dev-01 --peer laptop-nuno
  wgctl rule unassign --peer laptop-nuno
EOF
}

function cmd::inspect::help() {
  cat <<EOF
Usage: wgctl inspect --name <name> [--type <type>]
       wgctl inspect <full-name>

Show detailed information for a single client.

Options:
  --name <name>     Client name
  --type <type>     Device type (optional, combines with --name)
  --config          Show raw client config
  --qr              Show QR code

Examples:
  wgctl inspect --name phone-nuno
  wgctl inspect --name nuno --type phone
  wgctl inspect --name phone-nuno --config
  wgctl inspect --name phone-nuno --qr
EOF
}

function cmd::group::help() {
  cat <<EOF
Usage: wgctl group <subcommand> [options]

Manage peer groups.

Subcommands:
  list, ls                    List all groups
  show                        Show group details and members
  add, new, create            Create a new group
  remove, rm, del             Remove a group definition
  rename                      Rename a group
  peer add                    Add a peer to a group
  peer remove, peer rm        Remove a peer from a group
  rm-peers                    Remove all peers from WireGuard server
  block                       Block all peers in group
  unblock                     Unblock all peers in group
  rule assign                 Assign a rule to all peers in group
  audit                       Audit all peers in group
  logs                        Show logs for all peers in group
  watch                       Live monitor for all peers in group

Options:
  --name <name>               Group name
  --desc <description>        Group description
  --peer <peer>               Peer name
  --type <type>               Peer device type (for peer resolution)
  --rule <rule>               Rule name (for rule assign)
  --new-name <name>           New name (for rename)
  --force                     Skip confirmation prompts

Examples:
  wgctl group add --name family --desc "Family devices"
  wgctl group peer add --name family --peer phone-nuno
  wgctl group block --name family
  wgctl group rule assign --name family --rule user
  wgctl group audit --name family
EOF
}

function cmd::audit::help() {
  cat <<EOF
Usage: wgctl audit [options]

Verify WireGuard and firewall state matches expected configuration.

Options:
  --fix           Attempt to fix detected issues
  --peer <name>   Audit specific peer only
  --type <type>   Audit peers of specific type only

Examples:
  wgctl audit
  wgctl audit --peer phone-nuno
  wgctl audit --fix
EOF
}

function cmd::fw::help() {
  cat <<EOF
Usage: wgctl fw [subcommand] [options]

Inspect and manage firewall rules.

Subcommands:
  list                        Show FORWARD chain rules (default)
  nat                         Show NAT/PREROUTING rules
  flush-nat                   Flush NAT rules for a subnet
  count                       Show rule counts by type

Options for list:
  --peer <name>               Filter by peer name
  --rule <rule>               Filter by rule name (shows all peers with that rule)
  --no-nflog                  Hide NFLOG rules
  --no-accept                 Hide ACCEPT rules
  --no-drop                   Hide DROP rules

Examples:
  wgctl fw list
  wgctl fw list --peer phone-nuno
  wgctl fw list --rule guest
  wgctl fw list --no-nflog
  wgctl fw nat
  wgctl fw count
  wgctl fw flush-nat --subnet 10.1.103.0/24
EOF
}

function cmd::watch::help() {
  cat <<EOF
Usage: wgctl watch [options]

Live monitor of WireGuard activity.
Shows handshakes from active clients and connection attempts from blocked clients.

Options:
  --type <type>     Filter by device type
  --name <name>     Filter by client name
  --peers <list>    Filter by comma-separated peer names (used by group watch)
  --allowed         Show only allowed client handshakes
  --restricted      Show only restricted client events
  --blocked         Show only blocked client attempts

Examples:
  wgctl watch
  wgctl watch --blocked
  wgctl watch --allowed
  wgctl watch --type phone
  wgctl watch --name phone-nuno
EOF
}