docs(provider/env): clarify merge_strategy does not include host environment

docs/resources/env.md

@@ -32,6 +32,23 @@ resource "coder_env" "internal_api_url" {
   name     = "INTERNAL_API_URL"
   value    = "https://api.internal.company.com/v1"
 }
+
+# Append to PATH without losing the directories already set by the
+# workspace's image. Only one coder_env resource needs to reference
+# $PATH; the others can append plain values.
+resource "coder_env" "path_cuda" {
+  agent_id       = coder_agent.dev.id
+  name           = "PATH"
+  value          = "$PATH:/usr/local/cuda/bin"
+  merge_strategy = "append"
+}
+
+resource "coder_env" "path_go" {
+  agent_id       = coder_agent.dev.id
+  name           = "PATH"
+  value          = "/usr/local/go/bin"
+  merge_strategy = "append"
+}
 ```
 
 <!-- schema generated by tfplugindocs -->
@@ -44,7 +61,14 @@ resource "coder_env" "internal_api_url" {
 
 ### Optional
 
-- `merge_strategy` (String) Controls how this environment variable is merged when multiple coder_env resources define the same name. `replace` (default): last value wins. `append`: appends to existing value with a colon `:` separator. `prepend`: prepends to existing value with a colon `:` separator. `error`: fail the build if another coder_env defines the same name. When multiple resources append or prepend to the same name, they are applied in alphabetical order by Terraform resource address.
+- `merge_strategy` (String) Controls how this environment variable is merged when multiple coder_env resources define the same name.
+When multiple resources append or prepend to the same name, they are applied in alphabetical order by Terraform resource address.
+This only merges values across `coder_env` resources; it does not consider any value already present in the workspace's environment, such as a base image's `PATH`.
+To extend such a value, reference it directly (e.g., `value = "$PATH:/usr/local/bin"`), so the agent expands it against the real environment at startup. Valid values are as follows:
+  - `replace` (default): last value wins.
+  - `append`: appends to existing value with a colon `:` separator.
+  - `prepend`: prepends to existing value with a colon `:` separator.
+  - `error`: fail the build if another coder_env defines the same name.
 - `value` (String) The value of the environment variable.
 
 ### Read-Only

examples/resources/coder_env/resource.tf

@@ -16,4 +16,21 @@ resource "coder_env" "internal_api_url" {
   agent_id = coder_agent.dev.id
   name     = "INTERNAL_API_URL"
   value    = "https://api.internal.company.com/v1"
-}
+}
+
+# Append to PATH without losing the directories already set by the
+# workspace's image. Only one coder_env resource needs to reference
+# $PATH; the others can append plain values.
+resource "coder_env" "path_cuda" {
+  agent_id       = coder_agent.dev.id
+  name           = "PATH"
+  value          = "$PATH:/usr/local/cuda/bin"
+  merge_strategy = "append"
+}
+
+resource "coder_env" "path_go" {
+  agent_id       = coder_agent.dev.id
+  name           = "PATH"
+  value          = "/usr/local/go/bin"
+  merge_strategy = "append"
+}

provider/env.go

@@ -47,7 +47,7 @@ func envResource() *schema.Resource {
 			},
 			"merge_strategy": {
 				Type:        schema.TypeString,
-				Description: "Controls how this environment variable is merged when multiple coder_env resources define the same name. `replace` (default): last value wins. `append`: appends to existing value with a colon `:` separator. `prepend`: prepends to existing value with a colon `:` separator. `error`: fail the build if another coder_env defines the same name. When multiple resources append or prepend to the same name, they are applied in alphabetical order by Terraform resource address.",
+				Description: "Controls how this environment variable is merged when multiple coder_env resources define the same name.\nWhen multiple resources append or prepend to the same name, they are applied in alphabetical order by Terraform resource address.\nThis only merges values across `coder_env` resources; it does not consider any value already present in the workspace's environment, such as a base image's `PATH`.\nTo extend such a value, reference it directly (e.g., `value = \"$PATH:/usr/local/bin\"`), so the agent expands it against the real environment at startup. Valid values are as follows:\n  - `replace` (default): last value wins.\n  - `append`: appends to existing value with a colon `:` separator.\n  - `prepend`: prepends to existing value with a colon `:` separator.\n  - `error`: fail the build if another coder_env defines the same name.",
 				ForceNew:    true,
 				Optional:    true,
 				Default:     "replace",