Fix NUL byte validation comment and error guidance

The doc comment incorrectly claimed truncation occurs in relay JSON
serialization. Rust strings and JSON can represent NUL — the real
boundary is the OS command line on Windows, where a NUL terminates the
native command line before buzz.exe starts, so Clap never sees the NUL.

The error message recommended --content - (stdin), but validation runs
after read_or_stdin, so stdin content hits the same check. The actionable
workaround is a PowerShell literal here-string (single-quoted) piped
through stdin, which avoids backtick expansion entirely.

Add a help-contract regression test that verifies the error mentions
stdin and does not recommend --content -. Add a PowerShell here-string
example to the CLI README.

Addresses themiguelamador's review feedback.

Co-authored-by: Brad Groux <brad@digitalmeld.com>
Signed-off-by: Brad Groux <brad@digitalmeld.com>

Author: 2 people

crates/buzz-cli/README.md

@@ -32,6 +32,11 @@ export BUZZ_RELAY_URL="https://relay.example.com"
 buzz messages send --channel <uuid> --content "Hello"
 buzz messages send --channel <uuid> --content "Reply" --reply-to <event-id> --broadcast
 buzz messages send --channel <uuid> --content - < message.md   # read body from stdin
+
+# On Windows, use a PowerShell literal here-string to avoid backtick expansion:
+#   buzz messages send --channel <uuid> --content - <<'EOF'
+#   Content with `backticks` and $variables — preserved literally.
+#   EOF
 buzz messages get --channel <uuid> --limit 20
 buzz messages thread --channel <uuid> --event <event-id>
 buzz messages thread --link 'buzz://message?channel=<uuid>&id=<event-id>&thread=<root-id>'

crates/buzz-cli/src/validate.rs

@@ -74,16 +74,22 @@ pub fn validate_content_size(content: &str) -> Result<(), CliError> {
 
 /// Reject content containing NUL bytes (0x00).
 ///
-/// On Windows, a NUL byte inside a `--content` argument (e.g. from PowerShell
-/// expandable here-string `` `0 ``) silently truncates the string at the
-/// C-string boundary when it crosses into the relay's JSON serialization,
-/// but the CLI still returns `accepted:true`. Rejecting it here turns silent
-/// data loss into a hard error (#5916).
+/// Rust strings and JSON can represent NUL, so this is not a Rust-level
+/// truncation. The real boundary is the OS command line: on Windows, a NUL
+/// byte in `--content` terminates the native command line before `buzz.exe`
+/// starts, so Clap receives only the prefix and the validator never sees the
+/// NUL. This validator is a defense for NULs that reach Buzz through other
+/// paths (stdin, file, or platforms where the NUL survives into the process).
+///
+/// The actionable workaround for the Windows `--content` case is to use a
+/// PowerShell literal here-string (single-quoted, so backtick escapes do not
+/// expand) and pipe it through stdin.
 pub fn validate_no_nul_bytes(content: &str) -> Result<(), CliError> {
     if content.bytes().any(|b| b == 0) {
         return Err(CliError::Usage(
-            "content contains a NUL byte (0x00), which would be silently truncated — \
-             remove the NUL byte or use stdin (`--content -`) to pass the full content"
+            "content contains a NUL byte (0x00), which can cause silent truncation — \
+             remove the NUL byte. On Windows, pass content via stdin using a \
+             PowerShell literal here-string (single-quoted) to avoid backtick expansion"
                 .to_string(),
         ));
     }
@@ -326,6 +332,19 @@ mod tests {
         assert!(matches!(err, CliError::Usage(_)));
     }
 
+    #[test]
+    fn validate_no_nul_bytes_error_mentions_stdin_workaround() {
+        // The error must steer the operator toward stdin as the workaround,
+        // not toward --content (which would hit the same validator).
+        let err = validate_no_nul_bytes("hello\0world").unwrap_err();
+        let msg = err.to_string();
+        assert!(msg.contains("stdin"), "error should mention stdin: {msg}");
+        assert!(
+            !msg.contains("--content -"),
+            "error should not recommend --content - (it hits the same validator): {msg}"
+        );
+    }
+
     // --- percent_encode ---
 
     #[test]