docs: add documentation for new template variable features

- Document _1, _2, etc. positional args as template variables
- Document _args for numbered list of all positional args
- Document --_varname CLI flags without frontmatter declaration
- Add Auto-Injected Template Variables table to README
- Update CLAUDE.md with new system keys
- Add example files: positional-vars, args-list, optional-flags

Author: johnlindquist

CLAUDE.md

@@ -93,12 +93,16 @@ Commands are resolved in priority order:
 **System keys** (consumed by md, not passed to command):
 - `_varname`: Template variables (e.g., `_name: "default"` → `{{ _name }}` in body → `--_name` CLI flag)
 - `_stdin`: Auto-injected template variable containing piped input
+- `_1`, `_2`, etc.: Auto-injected positional CLI args (e.g., `md task.md "foo"` → `{{ _1 }}` = "foo")
+- `_args`: Auto-injected numbered list of all positional args
 - `env` (object form): Sets process.env before execution
 - `$1`, `$2`, etc.: Map positional args to flags
 - `_interactive`: Enable interactive mode (overrides print-mode defaults)
 - `_subcommand`: Prepend subcommand(s) to CLI args (e.g., `_subcommand: exec`)
 - `_cwd`: Override working directory for inline commands (`` !`cmd` ``)
 
+**Note:** `--_varname` CLI flags work without frontmatter declaration. If a `_` prefixed variable is used in the body but not provided, you'll be prompted for it.
+
 **All other keys** are passed directly as CLI flags:
 
 ```yaml

README.md

@@ -161,6 +161,54 @@ mdflow create.claude.md --_feature_name "Payments" --_target_dir "src/billing"
 
 The `--_feature_name` and `--_target_dir` flags are consumed by mdflow for template substitution—they won't be passed to the command.
 
+**No frontmatter declaration required:** You can pass `--_varname` flags without declaring them in frontmatter. If the variable is used in the body but not provided, you'll be prompted for it:
+
+```yaml
+---
+print: true
+---
+{% if _verbose == "yes" %}Detailed analysis:{% endif %}
+Review this code: {{ _target }}
+```
+
+```bash
+mdflow review.claude.md --_verbose yes --_target "./src"
+```
+
+### Positional Arguments as Template Variables
+
+CLI positional arguments are available as `{{ _1 }}`, `{{ _2 }}`, etc.:
+
+```yaml
+---
+print: true
+---
+Translate "{{ _1 }}" to {{ _2 }}.
+```
+
+```bash
+mdflow translate.claude.md "hello world" "French"
+# → Translate "hello world" to French.
+```
+
+Use `{{ _args }}` to get all positional args as a numbered list:
+
+```yaml
+---
+print: true
+---
+Process these items:
+{{ _args }}
+```
+
+```bash
+mdflow process.claude.md "apple" "banana" "cherry"
+# → Process these items:
+# → 1. apple
+# → 2. banana
+# → 3. cherry
+```
+
 ### `_stdin` - Piped Input
 
 When you pipe content to mdflow, it's available as the `_stdin` template variable:
@@ -192,6 +240,14 @@ cat README.md | mdflow summarize.claude.md
 | `_subcommand` | string/string[] | Prepend subcommand(s) to CLI args |
 | `_cwd` | string | Override working directory for inline commands |
 
+### Auto-Injected Template Variables
+
+| Variable | Description |
+|----------|-------------|
+| `{{ _stdin }}` | Content piped to mdflow |
+| `{{ _1 }}`, `{{ _2 }}`... | Positional CLI arguments |
+| `{{ _args }}` | All positional args as numbered list (1. arg1, 2. arg2, ...) |
+
 ### All Other Keys → CLI Flags
 
 Every other frontmatter key is passed directly to the command:

examples/args-list.claude.md

@@ -0,0 +1,7 @@
+---
+# Example: Using _args to get all positional args as a numbered list
+# Usage: md args-list.claude.md "apple" "banana" "cherry"
+print: true
+---
+Process these items:
+{{ _args }}

examples/optional-flags.claude.md

@@ -0,0 +1,13 @@
+---
+# Example: Using --_varname flags without frontmatter declaration
+# Usage: md optional-flags.claude.md --_mode detailed
+# Or just: md optional-flags.claude.md (will prompt for _mode)
+print: true
+---
+{% if _mode == "detailed" %}
+Provide a detailed, comprehensive analysis.
+{% else %}
+Provide a brief summary.
+{% endif %}
+
+Analyze this codebase.

examples/positional-vars.claude.md

@@ -0,0 +1,6 @@
+---
+# Example: Using positional CLI args as template variables
+# Usage: md positional-vars.claude.md "hello" "French"
+print: true
+---
+Translate "{{ _1 }}" to {{ _2 }}.