📖 Scribe: Document missing org and upgrade CLI commands by igorls · Pull Request #74 · igorls/meshguard

igorls · 2026-03-10T11:30:32Z

💡 What

Four CLI commands were completely missing from the CLI reference documentation: org-keygen, org-sign, org-vouch, and upgrade.

🔍 Source

The ground truth implementation for these commands is located in src/main.zig within the main function's argument parsing logic and the usage string constant.

📝 Fix

Appended the documentation for the following commands to docs/reference/cli.md, complete with descriptions, argument definitions, and examples that match the behavior in src/main.zig:

meshguard org-keygen
meshguard org-sign
meshguard org-vouch
meshguard upgrade

PR created automatically by Jules for task 10492436269268949134 started by @igorls

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>

google-labs-jules · 2026-03-10T11:30:34Z

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

New to Jules? Learn more at jules.google/docs.

For security, I will only act on instructions from the user who triggered this task.

Copilot

Pull request overview

Adds missing CLI reference documentation for organization-related commands and the self-upgrade command, aligning docs/reference/cli.md with the command set implemented in src/main.zig, and records the documentation drift lesson in Jules’ scribe log.

Changes:

Documented meshguard org-keygen, org-sign, org-vouch, and upgrade in the CLI reference.
Added an internal scribe entry capturing the “manual CLI drift” gap and prevention guidance.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
docs/reference/cli.md	Appends new CLI reference sections for org/admin and upgrade commands.
.jules/scribe.md	Adds an internal retrospective entry about CLI documentation drift.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-10T11:33:32Z

docs/reference/cli.md

+**Output files** (in `$MESHGUARD_CONFIG_DIR`):
+
+- `org.key` — secret key (permissions `0600`)
+- `org.pub` — public key


The org keypair files are saved under $MESHGUARD_CONFIG_DIR/org/ (see Org.saveOrgKeyPair / loadOrgKeyPair), not directly in $MESHGUARD_CONFIG_DIR. Please update the output paths accordingly to avoid pointing users at the wrong location.

Suggested change

**Output files** (in `$MESHGUARD_CONFIG_DIR`):

- `org.key` — secret key (permissions `0600`)

- `org.pub` — public key

**Output files** (in `$MESHGUARD_CONFIG_DIR/org/`):

- `org/org.key` — secret key (permissions `0600`)

- `org/org.pub` — public key

Copilot · 2026-03-10T11:33:33Z

docs/reference/cli.md

+## `meshguard upgrade`
+
+Upgrade meshguard to the latest release from GitHub.
+
+```bash
+meshguard upgrade
+```


meshguard upgrade is implemented as a Linux/systemd-specific self-updater: it downloads the meshguard-linux-amd64 asset, uses systemctl to stop/start the service, and installs to /usr/local/bin/meshguard (often requiring sudo). The docs currently describe it generically; please document these OS/arch and privilege/tooling requirements so users on other platforms don’t assume it will work.

Copilot · 2026-03-10T11:33:33Z

.jules/scribe.md

+## 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.


This entry says to check “fn main() switch cases”, but src/main.zig dispatches commands via an if (std.mem.eql(...)) chain (no switch). Please reword this to match the actual structure so the prevention guidance is actionable.

Suggested change

**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.

**Prevention:** We need to habitually check the `if (std.mem.eql(...))` command-dispatch chain and the usage/help string block in src/main.zig whenever updating CLI docs to ensure no commands have been added without corresponding documentation updates.

Copilot · 2026-03-10T11:33:33Z

.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`.


There’s no blank line separating this new section from the previous one (the earlier entries are separated by a blank line). Consider adding an empty line before this heading for consistent Markdown formatting/readability.

Suggested change

**Prevention:** Add a CI check that grep's `docs/guide/configuration.md` for values that match constants exported in `src/config.zig`.

**Prevention:** Add a CI check that grep's `docs/guide/configuration.md` for values that match constants exported in `src/config.zig`.

docs: add missing org and upgrade commands to CLI reference

e8bfa1b

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>

Copilot AI review requested due to automatic review settings March 10, 2026 11:30

Copilot started reviewing on behalf of igorls March 10, 2026 11:30 View session

Copilot AI reviewed Mar 10, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

📖 Scribe: Document missing org and upgrade CLI commands#74

📖 Scribe: Document missing org and upgrade CLI commands#74
igorls wants to merge 1 commit intomainfrom
scribe-document-missing-cli-commands-10492436269268949134

igorls commented Mar 10, 2026

Uh oh!

google-labs-jules bot commented Mar 10, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 10, 2026

Uh oh!

Copilot AI Mar 10, 2026

Uh oh!

Copilot AI Mar 10, 2026

Uh oh!

Copilot AI Mar 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	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.
	Prevention: We need to habitually check the `if (std.mem.eql(...))` command-dispatch chain and the usage/help string block in src/main.zig whenever updating CLI docs to ensure no commands have been added without corresponding documentation updates.

	Prevention: Add a CI check that grep's `docs/guide/configuration.md` for values that match constants exported in `src/config.zig`.
	Prevention: Add a CI check that grep's `docs/guide/configuration.md` for values that match constants exported in `src/config.zig`.

Conversation

igorls commented Mar 10, 2026

💡 What

🔍 Source

📝 Fix

Uh oh!

google-labs-jules bot commented Mar 10, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants