From 2475552bf28006bd9aee6d94f55e50a150096691 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Mon, 9 Mar 2026 11:30:20 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=96=20Scribe:=20Document=20missing=20C?=
 =?UTF-8?q?LI=20commands=20in=20reference?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Updated `docs/reference/cli.md` to properly document several commands and flags that are implemented in `src/main.zig` but were missing from the reference documentation.

What:
- Added `--org` flag under the `meshguard trust` section.
- Added documentation for `connect`, `org-keygen`, `org-sign`, `org-vouch`, and `upgrade` commands.
- Appended learning to `.jules/scribe.md` to track CLI argument drift.

Source: `src/main.zig`
Fix: Added markdown sections in `docs/reference/cli.md` for missing features.

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

diff --git a/.jules/scribe.md b/.jules/scribe.md
index 48b090c..2a1de2a 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`.
+
+## 2026-03-05 - Missing CLI Commands in Reference Documentation
+**Gap:** Several implemented CLI commands (`connect`, `org-keygen`, `org-sign`, `org-vouch`, `upgrade`) and flags (`--org` for `trust`) were present in `src/main.zig` but missing from `docs/reference/cli.md`.
+**Learning:** `src/main.zig` uses hardcoded argument parsing without a central CLI generator, making it easy to add new commands without updating documentation.
+**Prevention:** Add a CI check that verifies every command listed in the `usage` string in `src/main.zig` is documented in `docs/reference/cli.md`.
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index 750324c..5935630 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -36,13 +36,14 @@ meshguard export > my-node.pub
 Add a peer's public key to your authorized keys.
 
 ```bash
-meshguard trust <key-or-path> [--name <name>]
+meshguard trust <key-or-path> [--name <name>] [--org]
 ```
 
 | Argument        | Description                                            |
 | --------------- | ------------------------------------------------------ |
 | `<key-or-path>` | Base64 public key string _or_ path to a `.pub` file    |
 | `--name`        | Human-readable name (default: auto-generated from key) |
+| `--org`         | Trust an organization's public key                     |
 
 **Validation**:
 
@@ -117,6 +118,77 @@ meshguard status
 
 ---
 
+## `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 token to share with the peer         |
+| `--join`     | Join a connection using the peer's token        |
+| `--in`       | Punch delay in minutes (default: 1 minute)      |
+
+---
+
+## `meshguard org-keygen`
+
+Generate a new organization keypair.
+
+```bash
+meshguard org-keygen
+```
+
+**Output files** (in `$MESHGUARD_CONFIG_DIR/org/`):
+- `org.key` — secret key
+- `org.pub` — public key
+
+---
+
+## `meshguard org-sign`
+
+Sign a node's public key with the organization's private key, producing a NodeCertificate.
+
+```bash
+meshguard org-sign <node.pub> [--name <label>] [--expires <unix-timestamp>]
+```
+
+| Argument     | Description                                     |
+| ------------ | ----------------------------------------------- |
+| `<node.pub>` | Node's public key file                          |
+| `--name`     | Node name label                                 |
+| `--expires`  | Expiration as a Unix timestamp (default: never) |
+
+---
+
+## `meshguard org-vouch`
+
+Vouch for an external node (auto-propagates to org members).
+
+```bash
+meshguard org-vouch <node.pub>
+```
+
+| Argument     | Description                                     |
+| ------------ | ----------------------------------------------- |
+| `<node.pub>` | Node's public key file                          |
+
+---
+
+## `meshguard upgrade`
+
+Upgrade meshguard to the latest release from GitHub.
+
+```bash
+meshguard upgrade
+```
+
+---
+
 ## `meshguard version`
 
 Print the version.