docs: add bash array pattern for variadic args (#480)

## Summary

Documents how to properly convert variadic args (`var=#true`) to bash
arrays using the pattern:

```bash
eval "arr=($usage_var)"
```

This handles arguments with spaces correctly.

## Example

```bash
# Given: usage_files="arg1 'arg with space' arg3"

# Convert to bash array:
eval "files=($usage_files)"

# Now use as array:
for f in "${files[@]}"; do
  echo "Processing: $f"
done
```

This addresses the common issue where users struggle to handle variadic
args with spaces in bash scripts.

Related: #189

🤖 Generated with [Claude Code](https://claude.ai/code)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Documentation-only change; no runtime behavior is modified. Low risk
aside from potentially encouraging unsafe `eval` usage if misapplied.
> 
> **Overview**
> Adds a new **“Using Variadic Args in Bash”** section to
`docs/spec/reference/arg.md` describing how `var=#true` values are
exposed via `usage_<name>` and providing a Bash snippet (`eval
"files=($usage_files)"`) to safely iterate/pass variadic args that may
contain spaces.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
d23303c. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Opus 4.5 <[email protected]>

Author: jdx

docs/spec/reference/arg.md

@@ -13,7 +13,32 @@ arg "<file>" var=#true # multiple args can be passed (e.g. mycli file1 file2 fil
 arg "<file>..."        # shorthand for var=#true (trailing ellipsis)
 arg "<file>" var=#true var_min=3 # at least 3 args must be passed
 arg "<file>" var=#true var_max=3 # up to 3 args can be passed
+```
+
+## Using Variadic Args in Bash
+
+When using variadic arguments (`var=#true`), the values are passed as a shell-escaped
+string via the `usage_<name>` environment variable. To properly handle arguments
+containing spaces as a bash array, wrap the variable in parentheses:
+
+```bash
+# Given: usage_files="arg1 'arg with space' arg3"
+
+# Convert to bash array:
+eval "files=($usage_files)"
+
+# Now use as array:
+for f in "${files[@]}"; do
+  echo "Processing: $f"
+done
+
+# Or pass to commands:
+touch "${files[@]}"
+```
+
+This pattern ensures arguments with spaces are handled correctly as separate elements.
 
+```kdl
 arg "<shell>" {
   choices "bash" "zsh" "fish" # <shell> must be one of the choices
 }