docs: document env and client-default on global headers

fern/products/api-def/ferndef/api-yml/global-configuration.mdx

@@ -23,6 +23,22 @@ headers:
 
 When you define global headers in your `api.yml`, you must [include them in your endpoint examples](/api-definitions/ferndef/examples#examples-with-headers).
 
+The object form of a header accepts `env`, an environment variable the generated SDK reads, and `client-default`, the value the SDK sends when nothing else supplies one:
+
+<CodeBlock title="api.yml">
+```yaml
+name: api
+headers:
+  X-API-Version:
+    name: version
+    type: optional<string>
+    env: MY_API_VERSION
+    client-default: "2024-01-01"
+```
+</CodeBlock>
+
+Generated SDKs resolve the header value from an explicit argument passed to the client constructor or a single request, then `env`, then `client-default`. The same keys are available for headers declared in [`generators.yml`](/learn/sdks/reference/generators-yml#headers).
+
 ## Global path parameters
 
 You can specify path parameters that are meant to be included on every request:

fern/products/api-def/openapi/extensions/global-headers.mdx

@@ -50,16 +50,19 @@ Alternatively, you can add headers to the [`api` block in your `generators.yml`
 
 ```yaml title="generators.yml"
 api:
-  - openapi: ./path/to/openapi
-    headers:
-      custom_api_key:
-        name: api_key
-        type: string
-      userpool_id:
-        name: userpool_id
-        type: optional<string>
+  specs:
+    - openapi: ./path/to/openapi
+  headers:
+    custom_api_key:
+      name: api_key
+      type: string
+    userpool_id:
+      name: userpool_id
+      type: optional<string>
 ```
 
+A header declared in `generators.yml` also accepts `env` (an environment variable the SDK reads) and `client-default` (the value the SDK sends when nothing else supplies one). Generated SDKs resolve the value from an explicit argument first, then `env`, then `client-default`. For the full set of keys, see [`api.headers`](/learn/sdks/reference/generators-yml#headers).
+
 ## Generated SDK behavior
 
 Both configurations yield the following client code:

fern/products/sdks/deep-dives/configure-global-headers.mdx

@@ -34,4 +34,18 @@ x-fern-global-headers:
 
 You can also pin a [default value](/learn/api-definitions/openapi/extensions/default-values) on a global header so the SDK sends it automatically when the caller doesn't provide one.
 
+Headers declared in [`generators.yml`](/learn/sdks/reference/generators-yml#headers) or in a Fern Definition [`api.yml`](/learn/api-definitions/ferndef/api-yml/global-headers) additionally accept `env` and `client-default`:
+
+```yaml title="generators.yml"
+api:
+  headers:
+    X-API-Version:
+      name: version
+      type: optional<string>
+      env: MY_API_VERSION
+      client-default: "2024-01-01"
+```
+
+Every SDK language resolves the value in the same order: an option set on a single request, then the value passed to the client constructor, then the `MY_API_VERSION` environment variable, then `2024-01-01`. A value passed to the constructor persists across every request the client makes; per-request options override it only when the caller sets them.
+
 For full configuration details, see [Global headers in OpenAPI](/learn/api-definitions/openapi/extensions/global-headers).

fern/products/sdks/reference/generators-yml-reference.mdx

@@ -208,6 +208,14 @@ api:
 <ParamField path="headers" type="string or list of objects" toc={true}>
   Global headers to include with all API requests. This is an alternative to configuring [global headers in your OpenAPI spec](/learn/api-definitions/openapi/extensions/global-headers). You can specify headers as simple string values or as objects with additional configuration for code generation.
 
+  The object form supports these keys:
+
+  - `name`: the parameter name used in generated SDK code. Defaults to the header name.
+  - `type`: the header type for code generation, such as `string`, `optional<string>`, or `literal<"1234">`.
+  - `env`: the environment variable the generated SDK reads when the caller doesn't supply the header.
+  - `client-default`: the value the generated SDK sends when neither an explicit value nor `env` supplies one.
+  - `default`: a documentation-only value displayed in the API Reference. It has no effect on generated SDKs.
+
   <AccordionGroup>
   <Accordion title="Simple string values">
 
@@ -222,18 +230,19 @@ api:
 
   ```yaml title="generators.yml"
   api:
-    - openapi: ./path/to/openapi
-      headers: 
-        X-Version: 
-          # The variable name to use in generated SDK code. 
-          # If not specified, uses the header name.
-          name: version 
-          # The type of the header value for code generation 
-          # (e.g., "string", "literal<'value'>", "number").
-          type: literal<"1234">
+    specs:
+      - openapi: ./path/to/openapi
+    headers:
+      X-API-Version:
+        name: version
+        type: optional<string>
+        env: MY_API_VERSION
+        client-default: "2024-01-01"
   ```
   </Accordion>
   </AccordionGroup>
+
+  Generated SDKs resolve a [global header](/learn/sdks/deep-dives/global-headers) value in a fixed order: an option set on a single request, then the value passed to the client constructor, then the `env` environment variable, then `client-default`. The order is identical in TypeScript, Java, Python, Go, C#, Ruby, and PHP.
 </ParamField>
 
 <ParamField path="environments" type="object" toc={true}>