Update add headers action docs (v2)

snippets/shared/phases-explanation.mdx

@@ -0,0 +1 @@
+In Traffic Policy, a phase represents a distinct point in the lifecycle of a request as it moves through an ngrok endpoint. Phases allow you to inspect, process, and manage traffic at key moments.

traffic-policy/actions/add-headers.mdx

@@ -5,25 +5,29 @@ description: Add headers to an HTTP request or response before it is delivered u
 ---
 import { ConfigField } from "/snippets/ConfigTable.jsx";
 import ActionVariablesDescription from "/snippets/traffic-policy/common/action-variables-description.mdx";
+import PhasesExplanation from "/snippets/shared/phases-explanation.mdx";
 
 The Add Headers action enables you to add custom headers to an HTTP request or 
 response before delivery to the upstream service or client. This is useful 
 for attaching metadata like request identifiers, applying security controls, or 
 adjusting how applications process traffic.
 
-## Configuration Reference
+## Configuration reference
 
 The [Traffic Policy](/traffic-policy/) configuration reference for this action.
 
-### Supported Phases
+### Supported phases
 
-`on_http_request`, `on_http_response`
+<PhasesExplanation />
+
+- `on_http_request`: When called in this phase, the specified headers are added to incoming http requests before reaching the upstream service.
+- `on_http_response`: When called in this phase, the specified headers are added to the http response from the upstream service, before being delivered.
 
 ### Type
 
 `add-headers`
 
-### Configuration Fields
+### Configuration fields
 
 <ConfigField title="headers" type="object" cel={true}>
   Map of header key to header value to be added.
@@ -33,41 +37,157 @@ The [Traffic Policy](/traffic-policy/) configuration reference for this action.
 
 ## Behavior
 
-When configured in the `on_http_request` phase, this action will add the specified headers to incoming http requests before reaching the upstream server. When
-configured in the `on_http_response` phase, the specified headers are added to the http response from the upstream server.
+This Action's behavior varies based on which [request phase](#supported-phases) it's used in.
+
+### Addition only
+
+This action will only **add** headers to the request or response.
+If the header already exists, it will append another header with the same key (unless it's the `host` header. See [Special Cases](#special-cases)).
+
+#### Adding to existing headers
+
+For example, you could use this action to add the client's IP to `x-forwarded-for`, appending information about the client making the request, so the upstream server can see where the request originated, regardless of the proxies it passed through.
+
+<Note>
+This example uses a connection variable.
+See [the connection variable reference](https://ngrok.com/docs/traffic-policy/variables/connection#conn-client-ip) to learn more.
+</Note>
+
+<CodeGroup>
+```yaml policy.yml
+on_http_request:
+  - actions:
+    - type: "add-headers"
+      config:
+        headers:
+          x-forwarded-for: "${conn.client_ip}"
+```
+```json policy.json
+{
+  "on_http_request": [
+    {
+      "actions": [
+        {
+          "type": "add-headers",
+          "config": {
+            "headers": {
+              "x-forwarded-for": "${conn.client_ip}"
+            }
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+</CodeGroup>
+
+The server will see an `x-forwarded-for` header with the client's IP chain, which might look like this:
+
+```bash
+x-forwarded-for: 233.1.111.1, 11.5.5.5
+```
+
+#### Replacing headers
 
-### Addition Only
+To replace or remove headers, first use the [`remove-headers`](/traffic-policy/actions/remove-headers) action, then add the header with the desired value.
+The following snippet demonstrates a basic example.
 
-This action will only add headers to the request or response. If the header already exists
-it will append another header with the same key unless it is the `host` header,
-see [Special Cases](#special-cases).
+<CodeGroup>
+
+```yaml policy.yml
+on_http_request:
+- actions:
+  - type: remove-headers
+    config:
+      headers:
+      - x-example-header-1
+  - type: add-headers
+    config:
+      headers:
+        x-example-header-2: Example Value
+```
+
+```json policy.json
+{
+  "on_http_request": [
+    {
+      "actions": [
+        {
+          "type": "remove-headers",
+          "config": {
+            "headers": [
+              "x-example-header-1"
+            ]
+          }
+        },
+        {
+          "type": "add-headers",
+          "config": {
+            "headers": {
+              "x-example-header-2": "Example Value"
+						}
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+</CodeGroup>
 
-To replace or remove headers use the [`remove-headers`](/traffic-policy/actions/remove-headers) action then
-add the header with the desired value.
+<Tip>
+See [our Adding and Removing Headers examples](/traffic-policy/examples/add-and-remove-headers) for use cases.
+</Tip>
 
-### Case Sensitivity
+### Case sensitivity
 
-Header keys added through this action are normalized to lowercase per the [HTTP/2 specification](https://datatracker.ietf.org/doc/html/rfc7540#section-8.1.2).
+Header keys are case-insensitive.
+All header keys added with `add-headers` are normalized to lowercase, per the [HTTP/2 specification](https://datatracker.ietf.org/doc/html/rfc7540#section-8.1.2).
+
+For example, the following snippets, despite specifying a capitalized `Authorization` header, would yield a lower-case `authorization` header.
+
+<CodeGroup>
+```yaml policy.yml
+- type: add-headers
+  config:
+    headers:
+      Authorization: ax10malv
+```
+```json policy.json
+{
+	"type": "add-headers",
+	"config": {
+		"headers": {
+			"Authorization": "ax10malv"
+		}
+	}
+}
+```
+</CodeGroup>
 
 ### Ordering
 
-Since actions are run in the order they are specified, to modify headers that have been added by other actions you must place this action
-after them in your traffic policy document.
+Actions are run in the same order that they're defined in your traffic policy.
+If you want an `add-headers` action to modify headers created or modified in other actions, it must be defined after them in your traffic policy document.
+
+### Special cases
 
-### Special Cases
+These are the special cases in which this action will behave differently from how this reference document has specified.
 
-- Adding the `host` header override the existing value instead of appending another header.
+- Adding the `host` header overrides the existing value instead of appending another header.
 - You may not add or remove the `user-agent` header.
 - You may not use this action to add the `ngrok-skip-browser-warning` header to skip the ngrok browser warning on free accounts. For more information, check out the [free plan limits guide](/pricing-limits/free-plan-limits#removing-the-interstitial-page).
 
 ## Examples
 
-### Adding Client IP Headers to all HTTP requests
+### Adding Client IP headers to all HTTP requests
 
 The following [Traffic Policy](/traffic-policy/)
 configuration will add the client IP address to all HTTP requests.
 
-#### Example Traffic Policy Document
+#### Example traffic policy document
 
 <CodeGroup>
 ```yaml policy.yml
@@ -104,7 +224,7 @@ https://httpbin.org and we are adding the following header to all requests:
 - `x-client-ip` with the value `${conn.client_ip}` to demonstrate the use of
   CEL interpolation to include the client IP address.
 
-#### Example Request
+#### Example request
 
 ```bash
 $ curl -i https://httpbin.ngrok.app/get
@@ -126,7 +246,7 @@ content-type: application/json
 The following [Traffic Policy](/traffic-policy/)
 configuration will add headers to the response from the upstream service when the method is `GET` and the URL starts with `/status/200`.
 
-#### Example Traffic Policy Document
+#### Example traffic policy document
 
 <CodeGroup>
 ```yaml policy.yml highlight={3}
@@ -172,7 +292,7 @@ https://httpbin.org and we will be adding two headers:
   to demonstrate the use of CEL interpolation to include the request connection
   start time.
 
-### Example Request
+### Example request
 
 ```bash
 $ curl -i https://httpbin.ngrok.app/status/200
@@ -184,7 +304,7 @@ x-custom-header: my-custom-value
 x-string-interpolation-example: started at 2024-07-13T00:10:16Z
 ```
 
-## Action Result Variables
+## Action result variables
 
 <ActionVariablesDescription />
 

traffic-policy/concepts/phases.mdx

@@ -1,8 +1,11 @@
 ---
 title: Phases
+description: Learn about the different phases in the lifecycle of a request to your ngrok endpoints, and what actions you can take during them. 
 ---
 
-In Traffic Policy, a phase represents a distinct point in the lifecycle of a request as it moves through an ngrok endpoint. Phases allow you to inspect, process, and manage traffic at key moments.
+import PhasesExplanation from "/snippets/shared/phases-explanation.mdx";
+
+<PhasesExplanation />
 
 ## Traffic Policy Phases