hivectl: wireguard mesh setup verbs (#1756)

One-time-setup convenience for the inter-hive WireGuard mesh
(services.hyperhive.swarm) so nobody has to remember the wg dance:

- hivectl wg init [--address X] — generate (if absent) the hive's
  private key at /etc/wireguard/hive.key (0400, never clobbered),
  derive + print the public key, and print the swarm.wireguard nix
  snippet to enable the mesh.
- hivectl wg peer <domain> --pubkey --address [--endpoint] — print the
  swarm.peers.<domain> nix snippet to add a remote hive.
- hivectl wg status — wrap wg show wg-hive.

Hybrid model per the design: the verb owns the imperative state (the
key file), the operator pastes the printed nix into host config (kept
in git) — nothing mutates declarative config behind their back.
hivectl-only (root host ops, like the gateway htpasswd verbs); no
priv/wire/c0re changes.

flake: wrap hivectl with wireguard-tools on PATH so wg resolves even
before the mesh config (which would otherwise pull it in) exists —
wg init is the first setup step. Add clippy.toml doc-valid-idents for
the WireGuard proper noun. Regenerate hivectl-cli.md.

docs/tools/hivectl-cli.md

@@ -20,6 +20,10 @@ This document contains the help content for the `hivectl` command-line program.
 * [`hivectl agents`↴](#hivectl-agents)
 * [`hivectl agents restart`↴](#hivectl-agents-restart)
 * [`hivectl agents restart-all`↴](#hivectl-agents-restart-all)
+* [`hivectl wg`↴](#hivectl-wg)
+* [`hivectl wg init`↴](#hivectl-wg-init)
+* [`hivectl wg peer`↴](#hivectl-wg-peer)
+* [`hivectl wg status`↴](#hivectl-wg-status)
 * [`hivectl choom`↴](#hivectl-choom)
 * [`hivectl stop`↴](#hivectl-stop)
 * [`hivectl start`↴](#hivectl-start)
@@ -38,6 +42,7 @@ Sibling to the `hive-c0re` daemon binary. Covers host-side admin operations that
 * `matrix` — matrix-tuwunel user provisioning. Manual entry point to the same idempotent flow c0re runs automatically at boot (`matrix::ensure_all`) — useful when the boot-time sweep skipped an agent (e.g. matrix container wasn't up yet) or to re-register after wiping a token file
 * `gateway` — Gateway htpasswd user management. Add, remove, or list users in an htpasswd file used by the gateway's HTTP Basic auth (`services.hyperhive.gateway.auth`). Credentials are stored as `BCrypt` hashes — no extra service or PAM required
 * `agents` — Agent container management. Requires the hive-c0re daemon to be running (connects to the host admin socket)
+* `wg` — WireGuard inter-hive mesh setup helpers (`services.hyperhive.swarm`)
 * `choom` — Open an interactive Claude session inside an agent container
 * `stop` — Stop containers hive-wide in one operator action. Bare `hivectl stop` stops **everything** — all sub-agents plus the ci, forge, gateway, and matrix infra containers. Narrow it with scope flags: `--agents` (all sub-agents), `--ci` / `--forge` / `--gateway` / `--matrix` (named infra), and `--agent <name>` (repeatable) for specific sub-agents. Flags are additive (e.g. `--agents --matrix`). Requires the hive-c0re daemon (connects to the host admin socket). hive-c0re itself is never stopped — it services the request
 * `start` — Start containers hive-wide — the inverse of `hivectl stop`. Bare `hivectl start` starts everything back up; the same scope flags as `stop` narrow it (`--agents`, `--ci`, `--forge`, `--gateway`, `--matrix`, `--agent <name>`). Requires the hive-c0re daemon
@@ -277,6 +282,60 @@ Stop and restart ALL managed agent containers in sequence. Iterates the live con
 
 
 
+## `hivectl wg`
+
+WireGuard inter-hive mesh setup helpers (`services.hyperhive.swarm`).
+
+One-time-setup convenience so nobody has to remember the `wg` dance: `wg init` generates + stores this hive's private key and prints the public key plus the nix snippet to enable the mesh; `wg peer` prints the snippet to add a remote hive; `wg status` wraps `wg show`. The verbs own the imperative state (the key file); the printed nix goes into the operator's host config (kept in git), so nothing here mutates declarative config behind the operator's back.
+
+**Usage:** `hivectl wg <COMMAND>`
+
+###### **Subcommands:**
+
+* `init` — Generate (if absent) this hive's WireGuard private key, print its public key, and print the nix snippet to enable the mesh. Idempotent: an existing key is reused, never clobbered (clobbering would break a live mesh). Share the printed public key with peer hives
+* `peer` — Print the nix snippet to add a peer hive to the mesh. Pure output — paste it into this hive's config. Get `<pubkey>` from the peer's `hivectl wg init`
+* `status` — Show the live mesh interface state (`wg show wg-hive`). Requires the mesh to be enabled + up
+
+
+
+## `hivectl wg init`
+
+Generate (if absent) this hive's WireGuard private key, print its public key, and print the nix snippet to enable the mesh. Idempotent: an existing key is reused, never clobbered (clobbering would break a live mesh). Share the printed public key with peer hives
+
+**Usage:** `hivectl wg init [OPTIONS]`
+
+###### **Options:**
+
+* `--address <ADDRESS>` — This hive's mesh address (e.g. `10.42.0.1/32`) to bake into the printed snippet. Omit to get a placeholder you fill in
+
+
+
+## `hivectl wg peer`
+
+Print the nix snippet to add a peer hive to the mesh. Pure output — paste it into this hive's config. Get `<pubkey>` from the peer's `hivectl wg init`
+
+**Usage:** `hivectl wg peer [OPTIONS] --pubkey <PUBKEY> --address <ADDRESS> <DOMAIN>`
+
+###### **Arguments:**
+
+* `<DOMAIN>` — Peer hive's DNS domain (the `swarm.peers` attrset key)
+
+###### **Options:**
+
+* `--pubkey <PUBKEY>` — Peer's WireGuard public key (from its `hivectl wg init`)
+* `--address <ADDRESS>` — Peer's mesh address (e.g. `10.42.0.2/32`)
+* `--endpoint <ENDPOINT>` — Peer's `host:port` endpoint (omit for a peer that only dials out, e.g. one behind NAT — it must set an endpoint pointing back here)
+
+
+
+## `hivectl wg status`
+
+Show the live mesh interface state (`wg show wg-hive`). Requires the mesh to be enabled + up
+
+**Usage:** `hivectl wg status`
+
+
+
 ## `hivectl choom`
 
 Open an interactive Claude session inside an agent container.