📖 Scribe: Document meshguard connect command

[igorls]

💡 What:

The documentation in docs/reference/cli.md was missing several functional commands implemented in the src/main.zig codebase, particularly the meshguard connect command. This gap meant users were not aware of the direct peer connection and UDP hole-punching feature.

🔍 Source:

The implementation in src/main.zig defines meshguard connect, which accepts --generate, --join, and --in parameters to establish connections between peers bypassing seed nodes. The missing command and arguments were gathered from the usage text in cmdConnect.

📝 Fix:

Added the meshguard connect command to docs/reference/cli.md. Documented the purpose of the command (token exchange / UDP hole punching) and its parameters (--generate, --join, --in). Added a journal entry to .jules/scribe.md explaining the documentation drift caused by manual argument parsing instead of a generator framework.

---

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

[google-labs-jules]

👋 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

This PR adds documentation for the meshguard connect command to docs/reference/cli.md, which was previously missing from the CLI reference despite being fully implemented in src/main.zig. It also records the documentation gap in the project's scribe journal (.jules/scribe.md).

Changes:

• Adds the meshguard connect command section to the CLI reference, including its syntax, flags, and a brief description of its UDP hole-punching purpose
• Appends a journal entry to .jules/scribe.md noting the cause and prevention of the documentation drift

Reviewed changes

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

File	Description
docs/reference/cli.md	Adds the meshguard connect section documenting its flags and purpose
.jules/scribe.md	Records the documentation gap and proposes a prevention strategy

---

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

[Copilot]

The meshguard connect command involves a mandatory two-step interactive protocol between two peers that is not documented here. Users need to know:

1. The initiator runs --generate, then shares the printed mg:// token with the peer
2. The peer runs --join <token>, then pastes the response token back to the initiator
3. Both sides then punch simultaneously

This is consistent with how meshguard up documents its "Startup sequence" as a numbered list. Without this flow description, users may not understand that --generate is interactive (it reads from stdin) or that there is a required back-and-forth token exchange between the two parties.

Suggested change

	**Connection sequence**:
	1. Initiator runs `meshguard connect --generate [--in <minutes>]` and is printed an `mg://` token.
	2. Initiator securely shares this `mg://` token with the peer.
	3. Peer runs `meshguard connect --join <mg://token>`, which prints a response token.
	4. Peer sends the response token back to the initiator.
	5. Initiator pastes the response token into the waiting `--generate` process (stdin).
	6. At the agreed time (controlled by `--in`), both sides punch simultaneously to establish the direct connection.

[Copilot]

The journal entry date 2025-02-13 appears to be inaccurate. The current date is March 2026, and the previous scribe entry is dated 2026-02-24. This new entry is dated about a year earlier than that entry, placing it out of chronological order in the file. The date should reflect when this documentation gap was identified and fixed (approximately 2026-03-07 or similar).

Suggested change

	## 2025-02-13 - Missing CLI Command Documentation
	## 2026-03-07 - Missing CLI Command Documentation

[igorls]

Closing: superseded by docs audit fixes and direct commits to main. See PR #67 (merged) for codec bounds check, and direct commit for timing-safe fix in noise.zig.

[google-labs-jules]

Closing: superseded by docs audit fixes and direct commits to main. See PR #67 (merged) for codec bounds check, and direct commit for timing-safe fix in noise.zig.

Understood. Acknowledging that this work is superseded and stopping work on this task.

[igorls]

Closing: superseded by docs audit fixes and direct commits to main. Timing-safe fix applied directly, docs updated comprehensively.