docs: clarify dotenv file precedence when multiple files are specified (#2628)

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

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`