From 3d4d189bcd90779149a4e596a2f6b3fb3980a44a Mon Sep 17 00:00:00 2001
From: Bouke Versteegh <info@boukeversteegh.nl>
Date: Wed, 14 Jan 2026 19:37:41 +0100
Subject: [PATCH] docs: clarify dotenv file precedence when multiple files are
 specified (#2628)

---
 website/src/docs/guide.md            | 13 +++++++++++++
 website/src/docs/reference/schema.md |  8 +++++---
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/website/src/docs/guide.md b/website/src/docs/guide.md
index ef59375c..790bb2a4 100644
--- a/website/src/docs/guide.md
+++ b/website/src/docs/guide.md
@@ -174,6 +174,19 @@ tasks:
       - echo "Using $KEYNAME and endpoint $ENDPOINT"
 ```
 
+When the same variable is defined in multiple dotenv files, the **first file in
+the list takes precedence**. This allows you to set up override patterns by
+placing higher-priority files first:
+
+```yaml
+version: '3'
+
+dotenv:
+  - .env.local # Highest priority - local developer overrides
+  - .env.{{.ENV}} # Environment-specific settings
+  - .env # Base defaults (lowest priority)
+```
+
 Dotenv files can also be specified at the task level:
 
 ```yaml
diff --git a/website/src/docs/reference/schema.md b/website/src/docs/reference/schema.md
index f28b2998..d9e7cfb3 100644
--- a/website/src/docs/reference/schema.md
+++ b/website/src/docs/reference/schema.md
@@ -155,12 +155,14 @@ silent: true
 ### `dotenv`
 
 - **Type**: `[]string`
-- **Description**: Load environment variables from .env files
+- **Description**: Load environment variables from .env files. When the same
+  variable is defined in multiple files, the first file in the list takes
+  precedence.
 
 ```yaml
 dotenv:
-  - .env
-  - .env.local
+  - .env.local # Highest priority
+  - .env # Lowest priority
 ```
 
 ### `run`