fix(cmd): long-form flags, honest counts and safer inference

Assisted-by: GLM 5.3

man/interpres-decode.1

@@ -1,4 +1,4 @@
-.TH INTERPRES-DECODE 1 "2026-09-21" "interpres 2.0.0" "User Commands"
+.TH INTERPRES-DECODE 1 "2026-09-22" "interpres 2.0.0" "User Commands"
 .SH NAME
 interpres-decode \- TOML validator and toml-test harness adapter
 .SH SYNOPSIS
@@ -6,38 +6,38 @@ interpres-decode \- TOML validator and toml-test harness adapter
 [\fIFLAGS\fR]
 .br
 .B interpres-decode
-.B \-encode
+.B \-\-encode
 .br
 .B interpres-decode
-.B \-validate
+.B \-\-validate
 [\fIFILE\fR...]
 .br
 .B interpres-decode
-.B \-validate
+.B \-\-validate
 [\fIDIRECTORY\fR...]
 .br
 .B interpres-decode
-.B \-json
+.B \-\-json
 .br
 .B interpres-decode
-.B \-struct
+.B \-\-struct
 .br
 .B interpres-decode
-.B \-schema
+.B \-\-schema
 \fITYPE\fR
 \fIFILE.go\fR
 .br
 .B interpres-decode
-.B \-version
+.B \-\-version
 .SH DESCRIPTION
 .B interpres-decode
 is the toml-test harness adapter in both directions and a TOML validator.
 Without a mode flag it reads one TOML document from standard input and writes
 the toml-test tagged-JSON representation to standard output.
-.B \-encode
+.B \-\-encode
 reads a tagged-JSON description from standard input and writes the TOML
 document it describes.
-.B \-validate
+.B \-\-validate
 parses each named file, or standard input when none are named, and prints one
 line per invalid document to standard error; a named directory is walked for
 .B .toml
@@ -45,48 +45,49 @@ files, every one validated, and the walk closes with a summary on standard
 error naming the counts. The name
 .B \-
 means standard input.
-.B \-json
-prints plain indented JSON instead of the tagged form.
-.B \-struct
+.B \-\-json
+prints plain indented JSON instead of the tagged form; it shapes the decoding
+output only, so it is rejected together with the mode flags.
+.B \-\-struct
 prints a Go struct definition inferred from the document on standard input.
-.B \-schema
+.B \-\-schema
 writes a TOML template for the struct type
 \fITYPE\fR
 declared in the Go source file
 \fIFILE.go\fR,
 taking the key names, comments and defaults from the fields' tags.
-.B \-version
+.B \-\-version
 prints the binary's version and exits.
 .PP
 The mode flags
-.BR \-validate ,
-.BR \-encode ,
-.B \-struct
+.BR \-\-validate ,
+.BR \-\-encode ,
+.B \-\-struct
 and
-.B \-schema
+.B \-\-schema
 cannot be combined.
 .SH OPTIONS
 .TP
-.B \-validate
+.B \-\-validate
 Validate the documents instead of emitting tagged JSON.
 .TP
-.B \-encode
+.B \-\-encode
 Read tagged JSON from standard input and write TOML instead.
 .TP
-.B \-json
+.B \-\-json
 With the default mode, print plain indented JSON instead of tagged JSON.
 .TP
-.B \-struct
+.B \-\-struct
 Infer a Go struct definition from the document on standard input and print it.
 .TP
-.BI \-schema " TYPE"
+.BI \-\-schema " TYPE"
 Write a TOML template for the struct type \fITYPE\fR; the Go source file
 follows as the first argument.
 .TP
-.B \-version
+.B \-\-version
 Print the version and exit.
 .TP
-.B \-h
+.B \-\-help
 Print the usage.
 .SH EXIT STATUS
 .TP
@@ -95,11 +96,12 @@ The document parsed and the output was written; in validate mode, every
 document parsed.
 .TP
 .B 1
-Adapter: a parse error. Validate: at least one document is invalid.
+Adapter: a parse error. Validate: at least one document is invalid. Struct:
+the document on standard input failed to parse.
 .TP
 .B 2
-A usage error, a read failure, malformed tagged JSON, or a value with no TOML
-representation.
+A usage error, a read or write failure, malformed tagged JSON, or a value
+with no TOML representation.
 .SH EXAMPLES
 Decode a document into tagged JSON:
 .PP
@@ -113,7 +115,7 @@ Validate a directory of configuration, with the summary:
 .PP
 .nf
 .RS
-interpres-decode -validate configs/
+interpres-decode \-\-validate configs/
 .RE
 .fi
 .PP
@@ -121,7 +123,7 @@ Infer a Go type from a document:
 .PP
 .nf
 .RS
-interpres-decode -struct < config.toml > config.go
+interpres-decode \-\-struct < config.toml > config.go
 .RE
 .fi
 .PP
@@ -129,7 +131,7 @@ Write the template back from the type:
 .PP
 .nf
 .RS
-interpres-decode -schema Config config.go
+interpres-decode \-\-schema Config config.go
 .RE
 .fi
 .SH SEE ALSO