From 5a87f217ef1089ebfb8d2fbeee43b95fdb82c12c Mon Sep 17 00:00:00 2001
From: Kaj Kowalski <info@kajkowalski.nl>
Date: Sun, 9 Nov 2025 23:22:11 +0100
Subject: [PATCH 1/3] docs(schema): clarify refs and examples

Clarifies variable ref syntax using scoped names (.VERSION, .BASE_VERSION)
Improves prompt docs with single/multi examples and associated commands
Fixes precondition example to check a directory instead of a file
Corrects loop matrix example to use ITEM-scoped fields

Aligns documentation with actual behavior to reduce confusion and copy-paste errors.
---
 website/src/docs/reference/schema.md | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/website/src/docs/reference/schema.md b/website/src/docs/reference/schema.md
index a6d81c3515..87d4002f63 100644
--- a/website/src/docs/reference/schema.md
+++ b/website/src/docs/reference/schema.md
@@ -99,7 +99,7 @@ vars:
 
   # Variable references
   BUILD_VERSION:
-    ref: VERSION
+    ref: .VERSION
 
   # Map variables
   CONFIG:
@@ -360,7 +360,7 @@ vars:
 vars:
   BASE_VERSION: 1.0.0
   FULL_VERSION:
-    ref: BASE_VERSION
+    ref: .BASE_VERSION
 ```
 
 ### Map Variables (`map`)
@@ -513,12 +513,19 @@ tasks:
 
 ```yaml
 tasks:
+  # Single prompt
   deploy:
     prompt: "Deploy to production?"
-    # or multiple prompts
+    cmds:
+      - ./deploy.sh
+
+  # Multiple prompts
+  deploy-multi:
     prompt:
       - "Are you sure?"
       - "This will affect live users!"
+    cmds:
+      - ./deploy.sh
 ```
 
 #### `aliases`
@@ -592,7 +599,7 @@ tasks:
   # Simple precondition (shorthand)
   build:
     preconditions:
-      - test -f ./src
+      - test -d ./src
     cmds:
       - go build ./...
 
@@ -773,7 +780,7 @@ tasks:
           matrix:
             OS: [linux, windows, darwin]
             ARCH: [amd64, arm64]
-        cmd: echo "Testing {{.OS}}/{{.ARCH}}"
+        cmd: echo "Testing {{.ITEM.OS}}/{{.ITEM.ARCH}}"
 ```
 
 #### Loop in Dependencies

From b80d2b169b5286091a658d092183ec7f1fb30443 Mon Sep 17 00:00:00 2001
From: Kaj Kowalski <info@kajkowalski.nl>
Date: Sun, 9 Nov 2025 23:34:14 +0100
Subject: [PATCH 2/3] docs(guide): correct YAML indentation and task name

Ensures examples reflect valid YAML/Taskfile structure to avoid confusion.
Replaces colon in task name with a hyphen to prevent parsing issues and failing checks.
---
 website/src/docs/guide.md | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/website/src/docs/guide.md b/website/src/docs/guide.md
index fbc9ca450f..3b6445a922 100644
--- a/website/src/docs/guide.md
+++ b/website/src/docs/guide.md
@@ -406,10 +406,11 @@ option takes the list of tasks to be excluded from this include.
 
 ```yaml [Taskfile.yml]
 version: '3'
-  includes:
-    included:
-      taskfile: ./Included.yml
-      excludes: [foo]
+
+includes:
+  included:
+    taskfile: ./Included.yml
+    excludes: [foo]
 ```
 
 ```yaml [Included.yml]
@@ -913,7 +914,7 @@ programmatic check fails:
 version: '3'
 
 tasks:
-  build:prod:
+  build-prod:
     desc: Build for production usage.
     cmds:
       - composer install

From c9a99a6e187286cca9b91d5ada451fa922ee40f4 Mon Sep 17 00:00:00 2001
From: Kaj Kowalski <info@kajkowalski.nl>
Date: Mon, 10 Nov 2025 01:06:57 +0100
Subject: [PATCH 3/3] docs(guide): escape colon in status command with {{:}}
 template

Fixes YAML parsing error where unescaped colons in status commands
are interpreted as YAML key-value separators. Reverts task name back
to build:prod: as the issue was with the status command, not the task name.
---
 website/src/docs/guide.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/website/src/docs/guide.md b/website/src/docs/guide.md
index 3b6445a922..1fcee419f3 100644
--- a/website/src/docs/guide.md
+++ b/website/src/docs/guide.md
@@ -914,7 +914,7 @@ programmatic check fails:
 version: '3'
 
 tasks:
-  build-prod:
+  build:prod:
     desc: Build for production usage.
     cmds:
       - composer install
@@ -927,7 +927,7 @@ tasks:
       - ./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
+      - grep -q '"dev"{{:}} false' ./vendor/composer/installed.json
 ```
 
 ### Using programmatic checks to cancel the execution of a task and its dependencies