docs: add missing bug fixes to 0.2.4 changelog and troubleshooting

Add changelog entries for the ValueError wrapping fix (753eeef) and the
empty args cwd detection fix (b5bb046). Add a troubleshooting entry for
the new "invalid syntax" error message so users can find it.

Co-authored-by: Ralphify <noreply@ralphify.co>

Author: 2 people

docs/changelog.md

@@ -20,6 +20,8 @@ All notable changes to ralphify are documented here.
 - **Indented `---` in YAML block scalars mistaken for closing frontmatter delimiter** — the frontmatter parser used `line.strip()` to detect the closing `---`, which caused indented `---` inside YAML block scalars (e.g. `notes: |` with `  ---` content) to be treated as the end of the frontmatter. Now only `---` at column 0 is recognized as the closing delimiter.
 - **Indented opening `---` delimiter accepted inconsistently** — the opening frontmatter delimiter check used `strip()` which accepted leading whitespace (e.g. `  ---`), while the closing delimiter required column 0. Both delimiters now require `---` at column 0 per the YAML frontmatter spec.
 - **Arg values with spaces breaking command execution** — when `{{ args.name }}` placeholders were substituted into command `run` strings, values containing spaces (e.g. `"hello world"`) were split into separate tokens by `shlex.split`, causing the wrong command to execute. Arg values are now shell-quoted before substitution so they are always treated as single tokens.
+- **Helpful error when command has invalid syntax** — when a command's `run` string has malformed shell syntax (e.g. unmatched quotes), the error now identifies which command failed and points to the `commands` field. Previously this surfaced as a bare `ValueError` like "No closing quotation" with no context.
+- **Empty arg values breaking `./` working directory detection** — when an `{{ args.name }}` placeholder resolved to an empty string, the substitution could introduce leading whitespace that prevented the `./` prefix from being detected, causing the command to run from the project root instead of the ralph directory.
 
 ### Improved
 

docs/troubleshooting.md

@@ -162,6 +162,16 @@ commands:
 
 ## Command issues
 
+### "Command '...' has invalid syntax"
+
+A command's `run` string has malformed shell syntax — usually an unmatched quote. The error message tells you which command failed:
+
+```
+Command 'tests' has invalid syntax: 'uv run pytest -x "unclosed'. Check the 'commands' field in your RALPH.md frontmatter.
+```
+
+Fix the quoting in the `run` value. If your command needs complex quoting, point it at a script instead — see [Command with pipes or redirections not working](#command-with-pipes-or-redirections-not-working).
+
 ### "Command '...' binary not found"
 
 A command in your `commands` field references a binary that isn't installed or isn't on your PATH. The error message tells you which command failed: