docs: fix YAML syntax errors in schema and guide documentation

[kjanat]

Summary

Fixes 7 YAML syntax errors in documentation that would fail when users copy examples directly.

Changes

Schema Reference (reference/schema.md) - 5 fixes [1-5]

1. Variable refs: ref: VERSION → ref: .VERSION (missing dot prefix) [1] [2]
2. Prompt examples: duplicate prompt: keys → separate tasks [3]
3. Preconditions: test -f ./src → test -d ./src (checking directory) [4]
4. Matrix loops: {{.OS}} → {{.ITEM.OS}} (access via ITEM scope) [5]

Guide (guide.md) - 2 fixes [6-7]

1. Includes indentation: fixed includes: key indented under version: [6]
2. Status command: escaped colon with {{:}} to prevent YAML parser treating ": " as key-value separator [7]

Testing

227 YAML blocks validated across all documentation files using systematic Task CLI validation.

Impact

• Copy-paste examples now work without syntax errors
• Documentation reflects correct Taskfile syntax
• Best practices for variable refs, YAML escaping, and matrix loops

[kjanat]

I thought I spotted a bug, cause of an issue with reproducing a documentation example.

Example

version: '3'

tasks:
  build:prod:
    desc: Build for production usage.
    cmds:
      - composer install
    # Run this task if source files changes.
    sources:
      - composer.json
      - composer.lock
    generates:
      - ./vendor/composer/installed.json
      - ./vendor/autoload.php
    # But also run the task if the last build was not a production build.
    status:
      - grep -q '"dev": false' ./vendor/composer/installed.json

Task fails with a YAML parsing error:

err:  cannot unmarshal !!map into string
file: /path/to/Taskfile.yml:5:5
  3 | tasks:
  4 |   build:prod:
> 5 |     desc: Build for production usage.
    |     ^
  6 |     cmds:
  7 |       - composer install

Turns out it was just an escaping issue...

version: '3'

tasks:
  default:
    desc: Lists all tasks
    cmd: '{{.TASK_EXE}} --taskfile {{.TASKFILE}} --list-all'

  command-broken: # Like the docs example
    desc: This command is broken...
    summary: "err:  cannot unmarshal !!str `- grep ...` into []string"
    status:
      # Even the syntax highlighting picks it up...
      - grep -q '"dev": false' ./anyfile.txt
    cmd: echo "Hi!"

  # All of these variations work!
  command-works:
    status:
      - grep -q '"dev"{{:}} false' ./anyfile.txt
      - "grep -q '\"dev\": false' ./anyfile.txt"
      - grep -q '"dev"{{:}} false' ./anyfile.txt"
      - |
        grep -q '"dev": false' ./anyfile.txt
      - >
        grep -q '"dev": false' ./anyfile.txt
    cmd: echo "Hi!"

  command-also-works:
    status: ["grep -q '\"dev\": false' ./anyfile.txt"]
    cmd: echo "Hi!"

Additional Context

This "issue" was discovered while systematically testing all 227 YAML code blocks in the Task documentation. The example in guide.md contained this unescaped colon pattern and failed validation.

Related Issues

• Issue Colon in cmds fails yaml parsing #20
• Issue Make using both sources and status work #411

[vmaerten]

Thanks a lot!