feat: support global and node-level env variables (#108)

## Summary

- Adds three-layer `env` inheritance (project → node → variant) to
`veld.json`, matching the existing layering pattern used by
`url_template`, `features`, and `client_log_levels`
- For each key, the most specific layer wins; keys from parent layers
that are not overridden are preserved
- Adds `resolve_env()` in config.rs, updates all three `build_env` call
sites in the orchestrator, extends the JSON schema with a shared
`EnvMap` definition, and documents the feature

## Test plan

- [x] 5 new unit tests for `resolve_env()` covering: no layers,
project-only, node overrides project, variant overrides all,
variant-only
- [x] All 68 existing veld-core tests pass
- [ ] Manual: create a veld.json with project-level `env`, verify vars
are inherited by all variants
- [ ] Manual: add node-level `env` override, verify node-level wins for
that key while project keys are preserved
- [ ] Manual: add variant-level `env` override, verify variant wins

Closes #107

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: peter-adam-dy

README.md

@@ -198,7 +198,27 @@ Control which Veld capabilities are injected into `start_server` nodes' HTML res
 }
 ```
 
-Available features: `feedback_overlay` (toolbar/comments UI), `client_logs` (browser log collector). All default to `true`.
+Available features: `feedback_overlay` (toolbar/comments UI), `client_logs` (browser log collector), `inject` (auto-inject bootstrap scripts). All default to `true`.
+
+### Environment variables
+
+Declare `env` at the project, node, or variant level. Variables cascade: variant > node > project (per-key merge, most specific wins). Values support `${...}` variable substitution.
+
+```json
+{
+  "env": { "FEATURE_FLAG": "1" },
+  "nodes": {
+    "api": {
+      "env": { "LOG_LEVEL": "debug" },
+      "variants": {
+        "local": {
+          "env": { "PORT": "${veld.port}" }
+        }
+      }
+    }
+  }
+}
+```
 
 ### Variable interpolation
 

crates/veld-core/src/config.rs

@@ -64,6 +64,11 @@ pub struct VeldConfig {
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub features: Option<FeaturesConfig>,
 
+    /// Global environment variables inherited by all node variants.
+    /// Overridable at node and variant level.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub env: Option<HashMap<String, String>>,
+
     /// The dependency graph nodes.
     pub nodes: HashMap<String, NodeConfig>,
 }
@@ -98,6 +103,11 @@ pub struct NodeConfig {
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub features: Option<FeaturesConfig>,
 
+    /// Extra environment variables inherited by all variants of this node.
+    /// Overrides project-level env. Overridable at variant level.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub env: Option<HashMap<String, String>>,
+
     /// Working directory for all variants of this node. Relative paths are resolved from the project root (the directory containing veld.json).
     /// Overridable at variant level. Supports variable substitution.
     #[serde(default, skip_serializing_if = "Option::is_none")]
@@ -303,6 +313,29 @@ pub fn resolve_features(
     }
 }
 
+/// Merge environment variable maps using the most specific override:
+/// variant > node > project. For each key, the most specific layer wins.
+pub fn resolve_env(
+    project: Option<&HashMap<String, String>>,
+    node: Option<&HashMap<String, String>>,
+    variant: Option<&HashMap<String, String>>,
+) -> Option<HashMap<String, String>> {
+    let layers: &[Option<&HashMap<String, String>>] = &[project, node, variant];
+    let has_any = layers.iter().any(|l| l.is_some());
+    if !has_any {
+        return None;
+    }
+
+    let mut merged = HashMap::new();
+    // Apply from least specific to most specific so later layers override.
+    for map in layers.iter().flatten() {
+        for (k, v) in *map {
+            merged.insert(k.clone(), v.clone());
+        }
+    }
+    Some(merged)
+}
+
 // ---------------------------------------------------------------------------
 // StepType enum
 // ---------------------------------------------------------------------------
@@ -650,6 +683,64 @@ mod tests {
         assert_eq!(result, PathBuf::from("/opt/services/api"));
     }
 
+    // -- Env resolution tests --------------------------------------------------
+
+    #[test]
+    fn test_resolve_env_none() {
+        assert_eq!(resolve_env(None, None, None), None);
+    }
+
+    #[test]
+    fn test_resolve_env_project_only() {
+        let project = HashMap::from([("A".into(), "1".into())]);
+        let result = resolve_env(Some(&project), None, None).unwrap();
+        assert_eq!(result.get("A").unwrap(), "1");
+    }
+
+    #[test]
+    fn test_resolve_env_node_overrides_project() {
+        let project = HashMap::from([("A".into(), "1".into()), ("B".into(), "2".into())]);
+        let node = HashMap::from([("A".into(), "override".into())]);
+        let result = resolve_env(Some(&project), Some(&node), None).unwrap();
+        assert_eq!(result.get("A").unwrap(), "override");
+        assert_eq!(result.get("B").unwrap(), "2");
+    }
+
+    #[test]
+    fn test_resolve_env_variant_overrides_all() {
+        let project = HashMap::from([("A".into(), "1".into())]);
+        let node = HashMap::from([("A".into(), "2".into()), ("B".into(), "3".into())]);
+        let variant = HashMap::from([("A".into(), "final".into()), ("C".into(), "4".into())]);
+        let result = resolve_env(Some(&project), Some(&node), Some(&variant)).unwrap();
+        assert_eq!(result.get("A").unwrap(), "final");
+        assert_eq!(result.get("B").unwrap(), "3");
+        assert_eq!(result.get("C").unwrap(), "4");
+    }
+
+    #[test]
+    fn test_resolve_env_empty_map_with_values() {
+        let empty = HashMap::new();
+        let variant = HashMap::from([("X".into(), "1".into())]);
+        let result = resolve_env(Some(&empty), None, Some(&variant)).unwrap();
+        assert_eq!(result.len(), 1);
+        assert_eq!(result.get("X").unwrap(), "1");
+    }
+
+    #[test]
+    fn test_resolve_env_all_empty_maps() {
+        let empty = HashMap::new();
+        let result = resolve_env(Some(&empty), Some(&empty), Some(&empty)).unwrap();
+        assert!(result.is_empty());
+    }
+
+    #[test]
+    fn test_resolve_env_variant_only() {
+        let variant = HashMap::from([("X".into(), "val".into())]);
+        let result = resolve_env(None, None, Some(&variant)).unwrap();
+        assert_eq!(result.len(), 1);
+        assert_eq!(result.get("X").unwrap(), "val");
+    }
+
     #[test]
     fn test_resolve_cwd_variant_none_falls_through_to_node() {
         let root = PathBuf::from("/projects/myapp");

crates/veld-core/src/graph.rs

@@ -309,14 +309,27 @@ fn validate_variable_references(
             .push(&sel.variant);
     }
 
-    // For each node, scan its env and command strings for unqualified refs.
+    // Scan project-level env for unqualified refs.
+    if let Some(env_map) = &config.env {
+        for v in env_map.values() {
+            check_string_for_ambiguous_refs(v, &active_variants)?;
+        }
+    }
+
+    // For each node, scan its env, variant env, and command strings for unqualified refs.
     for sel in all_nodes {
-        let variant_cfg = &config.nodes[&sel.node].variants[&sel.variant];
+        let node_cfg = &config.nodes[&sel.node];
+        let variant_cfg = &node_cfg.variants[&sel.variant];
 
         let mut strings_to_check: Vec<&str> = Vec::new();
         if let Some(cmd) = &variant_cfg.command {
             strings_to_check.push(cmd);
         }
+        if let Some(env_map) = &node_cfg.env {
+            for v in env_map.values() {
+                strings_to_check.push(v);
+            }
+        }
         if let Some(env_map) = &variant_cfg.env {
             for v in env_map.values() {
                 strings_to_check.push(v);

crates/veld-core/src/orchestrator.rs

@@ -829,8 +829,14 @@ impl Orchestrator {
             }
         };
 
-        // Build env from the variant config.
-        let env = match build_env(variant_cfg.env.as_ref(), &ctx) {
+        // Build env (variant > node > project).
+        let node_cfg_opt = self.config.nodes.get(&node_state.node_name);
+        let merged_env = config::resolve_env(
+            self.config.env.as_ref(),
+            node_cfg_opt.and_then(|n| n.env.as_ref()),
+            variant_cfg.env.as_ref(),
+        );
+        let env = match build_env(merged_env.as_ref(), &ctx) {
             Ok(env) => env,
             Err(e) => {
                 tracing::warn!(
@@ -843,7 +849,6 @@ impl Orchestrator {
         };
 
         // Resolve working directory (variant > node > project root).
-        let node_cfg_opt = self.config.nodes.get(&node_state.node_name);
         let working_dir = resolve_working_dir(
             variant_cfg.cwd.as_deref(),
             node_cfg_opt.and_then(|n| n.cwd.as_deref()),
@@ -1221,8 +1226,13 @@ async fn execute_start_server_isolated(
     )
     .await;
 
-    // Build env.
-    let mut env = build_env(variant_cfg.env.as_ref(), var_ctx)?;
+    // Build env (variant > node > project).
+    let merged_env = config::resolve_env(
+        ctx.config.env.as_ref(),
+        node_cfg.env.as_ref(),
+        variant_cfg.env.as_ref(),
+    );
+    let mut env = build_env(merged_env.as_ref(), var_ctx)?;
     env.insert("VELD_PORT".to_owned(), port.to_string());
     env.insert("VELD_URL".to_owned(), https_url.clone());
 
@@ -1489,7 +1499,13 @@ async fn execute_command_isolated(
     };
     let resolved_cmd = crate::variables::interpolate(&raw_cmd, var_ctx)?;
 
-    let env = build_env(variant_cfg.env.as_ref(), var_ctx)?;
+    // Build env (variant > node > project).
+    let merged_env = config::resolve_env(
+        ctx.config.env.as_ref(),
+        node_cfg.env.as_ref(),
+        variant_cfg.env.as_ref(),
+    );
+    let env = build_env(merged_env.as_ref(), var_ctx)?;
 
     // Verify step (idempotency).
     if let Some(ref verify_cmd) = variant_cfg.verify {

docs/configuration.md

@@ -40,6 +40,7 @@ All relative paths in the configuration resolve relative to the directory contai
 | `presets`           | object | No       | Named shortcuts for node:variant selections       |
 | `client_log_levels` | array  | No       | Browser log levels to capture (see [Client-Side Log Levels]) |
 | `features`          | object | No       | Feature toggles (see [Features](#features))       |
+| `env`               | object | No       | Global environment variables inherited by all nodes |
 | `nodes`             | object | Yes      | The dependency graph nodes                        |
 
 [Client-Side Log Levels]: #client-side-log-levels
@@ -118,6 +119,7 @@ Controls which Veld capabilities are injected into `start_server` nodes' HTML re
 |---------------------|---------|---------|-------------|
 | `feedback_overlay`  | boolean | `true`  | Inject the feedback overlay toolbar (FAB, screenshot, comments) |
 | `client_logs`       | boolean | `true`  | Inject the client-side log collector |
+| `inject`            | boolean | `true`  | Auto-inject bootstrap scripts into HTML responses. When `false`, `/__veld__/*` routes are still available for manual `<script>` tags. |
 
 ```json
 {
@@ -139,6 +141,35 @@ Controls which Veld capabilities are injected into `start_server` nodes' HTML re
 
 In this example, the project disables the feedback overlay by default, and the `api` node also disables client logs. But the `api:local` variant re-enables the feedback overlay.
 
+### `env`
+
+Global environment variables inherited by all node variants. Values support Veld variable substitution. The same override hierarchy applies: variant > node > project. For each key, the most specific layer wins; keys from parent layers that are not overridden are preserved.
+
+```json
+{
+  "env": {
+    "FEATURE_FLAG_X": "1",
+    "SHARED_CONFIG": "value"
+  },
+  "nodes": {
+    "api": {
+      "env": {
+        "SHARED_CONFIG": "api-override"
+      },
+      "variants": {
+        "local": {
+          "env": {
+            "PORT": "${veld.port}"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+In this example, `api:local` inherits `FEATURE_FLAG_X=1` from the project, gets `SHARED_CONFIG=api-override` from the node (overriding the project value), and adds `PORT` at the variant level.
+
 ---
 
 ## Nodes
@@ -391,7 +422,9 @@ Extra environment variables injected into the process. Values support Veld varia
 }
 ```
 
-**Precedence:** The `env` block takes strict precedence over the inherited shell environment. Shell variables not overridden by `env` are passed through unchanged.
+**Layering:** Environment variables cascade from project to node to variant. For each key, the most specific layer wins. Keys from parent layers that are not overridden are preserved. See the project-level [`env`](#env) section for a full example.
+
+**Precedence:** The merged `env` block takes strict precedence over the inherited shell environment. Shell variables not overridden by `env` are passed through unchanged.
 
 ### `outputs`
 

schema/v1/veld.schema.json

@@ -50,6 +50,10 @@
       "$ref": "#/$defs/FeaturesConfig",
       "description": "Feature toggles (project-level defaults). Overridable at node and variant level."
     },
+    "env": {
+      "$ref": "#/$defs/EnvMap",
+      "description": "Global environment variables inherited by all node variants. Overridable at node and variant level."
+    },
     "nodes": {
       "type": "object",
       "description": "The dependency graph nodes. Each key is a node name, and the value defines its variants.",
@@ -87,6 +91,10 @@
           "$ref": "#/$defs/FeaturesConfig",
           "description": "Feature toggles override for all variants of this node."
         },
+        "env": {
+          "$ref": "#/$defs/EnvMap",
+          "description": "Extra environment variables inherited by all variants of this node. Overrides project-level env. Overridable at variant level."
+        },
         "cwd": {
           "type": "string",
           "description": "Working directory for all variants of this node. Relative paths are resolved from the project root. Overridable at variant level. Supports Veld variable substitution."
@@ -132,11 +140,8 @@
           }
         },
         "env": {
-          "type": "object",
-          "description": "Extra environment variables injected into the process.",
-          "additionalProperties": {
-            "type": "string"
-          }
+          "$ref": "#/$defs/EnvMap",
+          "description": "Extra environment variables injected into the process. Overrides node-level and project-level env."
         },
         "outputs": {
           "description": "Output declarations. For command steps: an array of output names captured from $VELD_OUTPUT_FILE (preferred) or VELD_OUTPUT stdout lines (legacy). For start_server steps: an object mapping output names to template strings.",
@@ -250,6 +255,13 @@
       "default": ["log", "warn", "error"],
       "uniqueItems": true
     },
+    "EnvMap": {
+      "type": "object",
+      "description": "A map of environment variable names to values. Values support Veld variable substitution (e.g. ${veld.port}, ${nodes.backend.url}).",
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
     "HealthCheck": {
       "type": "object",
       "description": "Health check configuration for a start_server variant.",

skills/veld/reference/config.md

@@ -118,9 +118,10 @@ Named shortcuts for common selections:
 
 | Field | Level | Description |
 |-------|-------|-------------|
+| `env` | project, node, variant | Environment variables. Cascades: variant > node > project (per-key merge). Supports `${...}` substitution. |
 | `cwd` | node, variant | Working directory. Relative paths resolve from project root. Variant overrides node. Supports `${...}` substitution. |
 | `hidden` | node | Hide from `veld nodes` output |
 | `client_log_levels` | project, node, variant | Browser log levels: `["log", "warn", "error", "info", "debug"]`. Exceptions always captured. |
-| `features` | project, node, variant | `{"feedback_overlay": bool, "client_logs": bool}`. All default `true`. |
+| `features` | project, node, variant | `{"feedback_overlay": bool, "client_logs": bool, "inject": bool}`. All default `true`. |
 | `on_stop` | variant | Teardown command that runs on `veld stop`. |
 | `sensitive_outputs` | variant | Output keys to mask in logs and encrypt at rest. |