From e8bfa1b94f956a5d69cdc86ba63bc6f033e7e581 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Tue, 10 Mar 2026 11:30:29 +0000
Subject: [PATCH] docs: add missing org and upgrade commands to CLI reference

Document org-keygen, org-sign, org-vouch, and upgrade commands in
docs/reference/cli.md to match the implementation in src/main.zig.

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

diff --git a/.jules/scribe.md b/.jules/scribe.md
index 48b090c..1aa57a8 100644
--- a/.jules/scribe.md
+++ b/.jules/scribe.md
@@ -12,3 +12,7 @@
 **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-10 - Manual CLI Drift
+**Gap:** The org-keygen, org-sign, org-vouch, and upgrade commands were completely missing from docs/reference/cli.md despite existing in src/main.zig.
+**Learning:** Because CLI argument parsing and help messages in src/main.zig are implemented manually rather than using a generator framework, the CLI reference documentation (docs/reference/cli.md) is highly prone to drift if not updated concurrently.
+**Prevention:** We need to habitually check the fn main() switch cases or the usage string block in src/main.zig whenever updating CLI docs to ensure no commands have been added without corresponding documentation updates.
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index 6ccded7..dd678d1 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -243,3 +243,58 @@ meshguard connect --join mg://...
 | Variable               | Description                                                |
 | ---------------------- | ---------------------------------------------------------- |
 | `MESHGUARD_CONFIG_DIR` | Override config directory (default: `~/.config/meshguard`) |
+
+---
+
+## `meshguard org-keygen`
+
+Generate a new Ed25519 organization keypair.
+
+```bash
+meshguard org-keygen
+```
+
+**Output files** (in `$MESHGUARD_CONFIG_DIR`):
+
+- `org.key` — secret key (permissions `0600`)
+- `org.pub` — public key
+
+---
+
+## `meshguard org-sign`
+
+Sign a node's public key with the organization key.
+
+```bash
+meshguard org-sign <node-key-or-path> [--name <label>] [--expires <unix-timestamp>]
+```
+
+| Argument | Description |
+| -------- | ----------- |
+| `<node-key-or-path>` | Base64 public key string _or_ path to a `.pub` file |
+| `--name` | Human-readable name for the node |
+| `--expires` | Unix timestamp when the signature expires (default: 0, never expires) |
+
+---
+
+## `meshguard org-vouch`
+
+Vouch for an external node. This action auto-propagates to organization members.
+
+```bash
+meshguard org-vouch <node-key-or-path>
+```
+
+| Argument | Description |
+| -------- | ----------- |
+| `<node-key-or-path>` | Base64 public key string _or_ path to a `.pub` file |
+
+---
+
+## `meshguard upgrade`
+
+Upgrade meshguard to the latest release from GitHub.
+
+```bash
+meshguard upgrade
+```