Most measurement --help examples do not run, and two recovery hints point at nonexistent commands/flags

[sneg55]

Most zoo kcl measurement --help examples do not run (missing required flags), and two recovery hints name nonexistent commands

Context: API Makeathon participant. Found while reviewing the kcl help text.

1. Documented examples omit required arguments

The measurement commands make --output-unit a non-Option field with no default_value, so clap requires it, but the help examples omit it. Copying any of these examples out of --help exits with clap usage error status 2 ("the following required arguments were not provided").

Affected example blocks (doc comments vs field declarations) in src/cmd_kcl.rs:

• volume (examples ~1137-1143 vs required --output-unit ~1160)
• bounding-box (~1173-1177)
• mass (~1334-1338 vs required --material-density, --material-density-unit, --output-unit)
• center-of-mass (~1427-1431)
• density (~1506-1510)
• surface-area (~1599-1603)

The same shape exists on the file side (file volume, file mass, etc.). Some stdin examples (cat my-file.kcl | zoo kcl volume) are doubly broken: the required positional input (or the - stdin marker) is missing too. zoo kcl analyze shows the intended pattern: it gives each unit flag a default_value, and its examples run as written.

2. Two recovery hints name nonexistent commands

• A snapshot session hint (around src/cmd_kcl.rs:328) recommends zoo session-start --listen-on ..., but the actual command is start-session (src/main.rs) with a positional address (src/cmd_start_session.rs).
• An invalid snapshot extension (around src/cmd_kcl.rs:781-787) reports "unknown source format" and recommends a nonexistent --src-format; the actual option is --output-format (src/cmd_kcl.rs:320-322).

Concrete failure

A user copies the example from zoo kcl volume --help and it fails during argument parsing. Combined with the missing possible-values list (see the value_enum issue), the follow-up error does not tell them what --output-unit accepts. The two recovery hints send users to commands and flags that do not exist.

Verify

Run any measurement example verbatim (e.g. zoo kcl volume some.kcl): clap errors before any network I/O. zoo start-session --help and zoo kcl snapshot --help show the actual forms.

Suggested fix

Give the measurement unit flags sensible default_values (as analyze does), or update the examples to include the required flags and positionals. Fix the two recovery hints to name start-session and --output-format.

Environment

Zoo CLI v0.2.184 (33534cd). Reviewed against the current main of KittyCAD/cli.