Update readme with map format for env config

Author: petetomasik

README.md

@@ -260,10 +260,89 @@ steps:
                 build:
                   message: "Deploying foo service"
                   env:
-                    - HELLO=123
-                    - AWS_REGION
+                    HELLO: 123
+                    AWS_REGION: ~  # Null literal reads from $AWS_REGION
 ```
 
+### Environment Variables
+
+Environment variables can be specified in two formats. Both formats are fully supported.
+
+#### Map Format (Recommended)
+
+The map format provides clean, readable syntax:
+
+```yaml
+steps:
+  - label: "Triggering pipelines"
+    plugins:
+      - monorepo-diff#v1.8.0:
+          env:
+            NODE_ENV: production
+            API_URL: https://api.example.com
+            PORT: 8080
+            DEBUG: false
+            AWS_REGION: ~         # Null literal reads from $AWS_REGION
+            EMPTY_STRING: ""      # Empty string sets to literal ""
+          watch:
+            - path: "services/"
+              config:
+                command: "npm test"
+                env:
+                  TEST_ENV: integration
+                  MAX_WORKERS: 4
+```
+
+Map format features:
+- Clean YAML syntax using key-value pairs
+- Supports non-string values (numbers, booleans) which are converted to strings automatically
+- Null values read from OS environment: use `KEY: ~` (recommended YAML null literal)
+- The explicit `~` ensures nothing is accidentally added during pipeline processing
+- Note: Unlike array format, you cannot use just `KEY` alone - you must use a null value
+- Empty string (`""`) is treated as a literal empty string value
+- Whitespace in values is preserved
+- Recommended for new configurations
+
+#### Array Format (Fully Supported)
+
+The array format uses key=value syntax:
+
+```yaml
+steps:
+  - label: "Triggering pipelines"
+    plugins:
+      - monorepo-diff#v1.8.0:
+          env:
+            - NODE_ENV=production
+            - API_URL=https://api.example.com
+            - AWS_REGION          # Key-only reads from $AWS_REGION
+          watch:
+            - path: "services/"
+              config:
+                command: "npm test"
+                env:
+                  - TEST_ENV=integration
+```
+
+Array format features:
+- Key-only entries (e.g., `AWS_REGION`) read from OS environment variables
+- Supports values with equals signs: `BUILD_ARGS=--arg1=val1`
+- Whitespace trimmed from keys and values automatically
+- Fully supported alongside map format
+
+#### Format Comparison
+
+| Feature | Map Format | Array Format |
+|---------|-----------|--------------|
+| Syntax | `KEY: value` | `KEY=value` |
+| OS env reading | Null literal (`KEY: ~`) | Key-only entries (`KEY`) |
+| Empty string | `KEY: ""` sets to `""` | `KEY=` sets to `""` |
+| Type support | Numbers, booleans | Strings only |
+| Whitespace | Preserved in values | Trimmed |
+| Readability | High | Medium |
+
+**Note:** The format is determined by YAML structure - you cannot mix array and map syntax at the same level. However, you can use different formats at different levels (e.g., map format at plugin level, array format at step level).
+
 ### `log_level` (optional)
 
 Add `log_level` property to set the log level. Supported log levels are `debug` and `info`. Defaults to `info`.
@@ -413,7 +492,7 @@ steps:
           diff: "git diff --name-only $(head -n 1 last_successful_build)"
           interpolation: false
           env:
-            - env1=env-1 # this will be appended to all env configuration
+            env1: env-1  # this will be appended to all env configuration
           hooks:
             - command: "echo $(git rev-parse HEAD) > last_successful_build"
           watch:
@@ -444,7 +523,7 @@ steps:
                 artifacts:
                   - "logs/*"
                 env:
-                  - FOO=bar
+                  FOO: bar
 
           wait: true
 ```