docs(sdk/provisioner): document new behaviours

Author: jmsnll

sdk/provisioner.go

@@ -102,6 +102,10 @@ func (out *ProvisionOutput) AddEnvVar(name string, value string) {
 	out.Environment[name] = value
 }
 
+// AddArgsAtIndex inserts additional arguments into the command line at the specified index.
+// - If position is -1 or greater than the current length, the arguments are appended.
+// - If position is 0 or negative, the arguments are prepended.
+// - Otherwise, the arguments are inserted at the specified index, shifting existing elements forward.
 func (out *ProvisionOutput) AddArgsAtIndex(position int, args ...string) {
 	if position == -1 || position >= len(out.CommandLine) {
 		out.CommandLine = append(out.CommandLine, args...)
@@ -116,12 +120,14 @@ func (out *ProvisionOutput) AddArgsAtIndex(position int, args ...string) {
 	out.CommandLine = append(out.CommandLine[:position], append(args, out.CommandLine[position:]...)...)
 }
 
-// PrependArgs can be used to add additional arguments to the command line of the provision output.
+// PrependArgs inserts additional arguments at the beginning of the command line, after the first argument.
+// This ensures that the first argument (typically the executable name) remains unchanged.
 func (out *ProvisionOutput) PrependArgs(args ...string) {
 	out.AddArgsAtIndex(1, args...)
 }
 
-// AppendArgs can be used to add additional arguments to the command line of the provision output.
+// AppendArgs appends additional arguments to the end of the command line.
+// This ensures that new arguments are always added last, preserving existing order.
 func (out *ProvisionOutput) AppendArgs(args ...string) {
 	out.AddArgsAtIndex(-1, args...)
 }