Reconcile module docs and release materials

binding.go

@@ -6,8 +6,9 @@ import (
 )
 
 // ValueFlag declares a singleton flag with a typed parser, optional default,
-// and setter. Every supplied occurrence is parsed; the last parsed value is
-// applied with Set=true.
+// and setter. The default value is captured at construction. Every supplied
+// occurrence is parsed before input construction; the last parsed value is
+// applied with Set=true. A malformed earlier occurrence remains an error.
 func ValueFlag[I, V any](meta FlagMeta, defaultValue *V, parse func(string) (V, error), set func(*I, Supplied[V])) Flag[I] {
 	var fallback V
 	if defaultValue != nil {
@@ -36,7 +37,8 @@ func ValueFlag[I, V any](meta FlagMeta, defaultValue *V, parse func(string) (V,
 }
 
 // BoolFlag declares a boolean flag. A bare flag is supplied by the parser as
-// "true"; explicit values are converted with strconv.ParseBool.
+// "true"; explicit values are converted with strconv.ParseBool. Set distinguishes
+// an omitted flag from an explicit false value.
 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 {
@@ -60,8 +62,10 @@ func BoolFlag[I any](meta FlagMeta, defaultValue bool, set func(*I, Supplied[boo
 	return Flag[I]{binding: binding}
 }
 
-// RepeatFlag declares a repeatable flag. Supplied occurrences replace defaults
-// and are parsed in argv order, with each occurrence treated as one value.
+// RepeatFlag declares a repeatable flag. It captures a copy of defaults. Supplied
+// occurrences replace defaults and are parsed in argv order, with each
+// occurrence treated as one value. The core-owned result slice is copied when
+// applied to input.
 func RepeatFlag[I, V any](meta FlagMeta, defaults []V, parse func(string) (V, error), set func(*I, Supplied[[]V])) Flag[I] {
 	fallback := append([]V(nil), defaults...)
 	binding := flagBinding[I]{identity: newBindingIdentity(), meta: meta, defaultText: fmt.Sprint(fallback), repeated: true}
@@ -91,8 +95,9 @@ func RepeatFlag[I, V any](meta FlagMeta, defaults []V, parse func(string) (V, er
 	return Flag[I]{binding: binding}
 }
 
-// ValueArgument declares an optional or required singleton positional
-// argument.
+// ValueArgument declares an optional or required singleton positional argument.
+// Required cardinality is enforced for execution, while help can be rendered
+// without a supplied operand. Parsing completes before input construction.
 func ValueArgument[I, V any](meta ArgumentMeta, required bool, parse func(string) (V, error), set func(*I, Supplied[V])) Argument[I] {
 	min := 0
 	if required {
@@ -122,8 +127,9 @@ func ValueArgument[I, V any](meta ArgumentMeta, required bool, parse func(string
 	return Argument[I]{binding: binding}
 }
 
-// RepeatArgument declares a positional argument that accepts a bounded number
-// of values. A maximum of -1 means unbounded.
+// RepeatArgument declares a positional argument that accepts at least min and
+// at most max values. A maximum of -1 means unbounded. Parsing completes before
+// input construction, and the core-owned result slice is copied when applied.
 func RepeatArgument[I, V any](meta ArgumentMeta, min, max int, parse func(string) (V, error), set func(*I, Supplied[[]V])) Argument[I] {
 	binding := argumentBinding[I]{identity: newBindingIdentity(), meta: meta, min: min, max: max}
 	if parse == nil || set == nil {