From 96715640b5b70bd4dc5a817dd91d1c761693cd3a Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Sun, 8 Mar 2026 11:16:18 +0000
Subject: [PATCH] docs: Add missing `meshguard connect` command to CLI
 reference

This commit adds the `meshguard connect` command and its flags
(`--generate`, `--join`, `--in`) to the `docs/reference/cli.md` file. This
command was implemented in `src/main.zig` but was missing from the documentation.

Co-authored-by: igorls <4753812+igorls@users.noreply.github.com>
---
 .jules/scribe.md      |  5 +++++
 docs/reference/cli.md | 17 +++++++++++++++++
 2 files changed, 22 insertions(+)

diff --git a/.jules/scribe.md b/.jules/scribe.md
index 48b090c..29dee29 100644
--- a/.jules/scribe.md
+++ b/.jules/scribe.md
@@ -12,3 +12,8 @@
 **Gap:** The documentation stated the SWIM protocol period was 1000ms (1s), but the implementation uses 5000ms (5s) in both `src/config.zig` and `src/discovery/swim.zig`.
 **Learning:** The documentation likely reflected an early design decision or standard SWIM defaults, but the implementation settled on a more conservative 5s interval for WAN stability, and docs were not updated.
 **Prevention:** Add a CI check that grep's `docs/guide/configuration.md` for values that match constants exported in `src/config.zig`.
+
+## 2024-05-24 - Missing CLI Command Documentation
+**Gap:** The `meshguard connect` command was implemented in `src/main.zig` but missing from the CLI reference in `docs/reference/cli.md`.
+**Learning:** The CLI reference document is highly prone to drift because command parsing and help messages are implemented manually in `src/main.zig` rather than using a generator framework.
+**Prevention:** Ensure that whenever a new command is added to the `usage` string in `main.zig`, a corresponding section is added to `docs/reference/cli.md`.
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index 750324c..51e4277 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -107,6 +107,23 @@ Uses `RTM_DELLINK` via RTNETLINK to remove the interface.
 
 ---
 
+## `meshguard connect`
+
+Direct peer connection via token exchange (bypassing seed nodes) and performs a coordinated UDP hole punch.
+
+```bash
+meshguard connect --generate [--in <minutes>]
+meshguard connect --join <mg://token>
+```
+
+| Flag         | Description                                     |
+| ------------ | ----------------------------------------------- |
+| `--generate` | Generate a connection token as the initiator    |
+| `--join`     | Join a connection using the peer's token        |
+| `--in`       | Delay before punching in minutes (default: 1)   |
+
+---
+
 ## `meshguard status`
 
 Display the current mesh state.