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

Assisted-by: GLM 5.3

examples/basic/main.go

@@ -3,8 +3,8 @@
 
 // Command basic demonstrates decoding and encoding a TOML document with
 // interpres. It exercises struct mapping, arrays of tables, Marshaler
-// customisation, the Decoder's strict mode, and the Encoder's policy
-// options, covering every feature a regular user would reach for.
+// customisation, and the Encoder's policy options, covering every feature a
+// regular user would reach for.
 package main
 
 import (
@@ -18,8 +18,7 @@ import (
 )
 
 // document is a small but realistic configuration: it has scalars, a
-// sub-table, an array of tables, and a date-time. We pick a 32-bit port so
-// the demonstration also covers overflow-safe integer conversion.
+// sub-table, an array of tables, and a date-time.
 const document = `
 title  = "interpres demo"
 launched = 2024-11-04T09:00:00Z
@@ -62,9 +61,11 @@ type User struct {
 	Admin bool   `toml:"admin"`
 }
 
-// Port is a typed alias that controls how its value appears in TOML. The
-// MarshalTOML hook returns a string, so a Port field is rendered as
-// "host:port" instead of the raw integer.
+// Port is a typed string alias that carries a Marshaler. The MarshalTOML
+// hook returns the string unchanged, so a Port field is rendered as the
+// string it holds, a string the encoding would print the same way without
+// the hook; the demonstration that a Marshaler reshapes a value is
+// Endpoint's below.
 type Port string
 
 func (p Port) MarshalTOML() (any, error) {