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`