references/shell-quoting.md

# Shell expansion, quoting and argument contracts

- Distinguish lexer/parser syntax from runtime expansion: parameter expansion, command substitution, arithmetic, field splitting, globbing and quote removal.
- `"$var"` represents a single argument, except intentionally split formats. `"$@"` preserves positional argument boundaries. In Bash use `"${array[@]}"` for arrays.
- `printf '%s\n' "$value"` is clearer than `echo "$value"` where `-n`, backslashes or portability matter.
- Quote embedded substitutions independently: `"$(command "$path")"`; do not assume surrounding double quotes reach inside nested shell commands.
- File names can contain spaces, tabs, newlines and leading dashes. Use `find ... -exec ... {} +` or NUL-delimited pipelines where supported.
- POSIX utilities are not guaranteed to accept `--`. Use a safe path prefix or platform-specific documented convention.
- `set -e` exceptions require explicit checks for material operations. POSIX `sh` cannot assume Bash arrays, process substitution, `[[ ... ]]`, or portable `pipefail`.
- Avoid building shell commands by interpolating untrusted strings into `eval`, `sh -c` or SSH strings. Prefer arguments or controlled, separate scripts.

Primary: POSIX shell command language https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html and ShellCheck SC2086 https://www.shellcheck.net/wiki/SC2086