Document shared debug input and reporting mode

binding.go

@@ -84,6 +84,12 @@ func RenameFlag[I any](flag Flag[I], name string) Flag[I] {
 // BoolFlag declares a boolean flag. A bare flag is supplied by the parser as
 // "true"; explicit values are converted with strconv.ParseBool. Set distinguishes
 // an omitted flag from an explicit false value.
+//
+// A BoolFlag named debug receives the shared reporting flag's input. Its
+// default and requiredness apply to application input, not reporting mode;
+// explicit false satisfies requiredness. Its optional short spelling and
+// completion metadata follow ordinary flag rules. The final input value can
+// differ from [Invocation.ReportingMode] when other mode flags are supplied.
 func BoolFlag[I any](meta FlagMeta, defaultValue bool, set func(*I, Supplied[bool])) Flag[I] {
 	binding := flagBinding[I]{identity: newBindingIdentity(), meta: meta, defaultText: fmt.Sprint(defaultValue), boolean: true}
 	if set == nil {