docs: improve policy concepts section

site/content/en/latest/concepts/gateway_api_extensions/backend-traffic-policy.md

@@ -29,17 +29,58 @@ Think of it as a traffic controller between your gateway and backend services. I
 
 `BackendTrafficPolicy` is part of the Envoy Gateway API suite, which extends the Kubernetes Gateway API with additional capabilities. It's implemented as a Custom Resource Definition (CRD) that you can use to configure how Envoy Gateway manages traffic to your backend services.
 
-You can attach it to Gateway API resources in two ways:
+### Targets
 
-1. Using `targetRefs` to directly reference specific Gateway resources
-2. Using `targetSelectors` to match Gateway resources based on labels
+BackendTrafficPolicy can be attached to Gateway API resources using two targeting mechanisms:
 
-The policy applies to all resources that match either targeting method. When multiple policies target the same resource, the most specific configuration wins.
+1. **Direct Reference (`targetRefs`)**: Explicitly reference specific resources by name and kind.
+2. **Label Selection (`targetSelectors`)**: Match resources based on their labels (see [targetSelectors API reference](../../api/extension_types#targetselectors))
 
-For example, consider these two policies:
+```yaml
+# Direct reference targeting
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: BackendTrafficPolicy
+metadata:
+  name: direct-policy
+spec:
+  targetRefs:
+    - kind: HTTPRoute
+      name: my-route
+  circuitBreaker:
+    maxConnections: 50
+
+---
+# Label-based targeting
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: BackendTrafficPolicy
+metadata:
+  name: selector-policy
+spec:
+  targetSelectors:
+    - kind: HTTPRoute
+      matchLabels:
+        app: payment-service
+  rateLimit:
+    type: Local
+    local:
+      requests: 10
+      unit: Second
+```
+
+The policy applies to all resources that match either targeting method. You can target various Gateway API resource types including
+`Gateway`, `HTTPRoute`, `GRPCRoute`, `TCPRoute`, `UDPRoute`, `TLSRoute`.
+
+**Important**: A BackendTrafficPolicy can only target resources in the same namespace as the policy itself.
+
+### Precedence
+
+When multiple BackendTrafficPolicies apply to the same resource, Envoy Gateway resolves conflicts using a precedence hierarchy based on the target resource type, regardless of how the policy was attached:
+
+1. **Route-level policies** (HTTPRoute, GRPCRoute, etc.) - Highest precedence
+2. **Gateway-level policies** - Lower precedence
 
 ```yaml
-# Policy 1: Applies to all routes in the gateway
+# Gateway-level policy (lower precedence) - Applies to all routes in the gateway
 apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: BackendTrafficPolicy
 metadata:
@@ -52,7 +93,7 @@ spec:
     maxConnections: 100
 
 ---
-# Policy 2: Applies to a specific route
+# Route-level policy (higher precedence)
 apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: BackendTrafficPolicy
 metadata:
@@ -65,9 +106,47 @@ spec:
     maxConnections: 50
 ```
 
-In this example `my-route` and `my-gateway` would both affect the route. However, since Policy 2 targets the route directly while Policy 1 targets the gateway, Policy 2's configuration (`maxConnections: 50`) will take precedence for that specific route.
+In this example, the HTTPRoute `my-route` would use `maxConnections: 50` from the route-level policy, overriding the gateway-level setting of 100.
+
+#### Multiple Policies at the Same Level
+
+When multiple BackendTrafficPolicies target the same resource at the same hierarchy level (e.g., multiple policies targeting the same HTTPRoute), Envoy Gateway uses the following tie-breaking rules:
+
+1. **Creation Time Priority**: The oldest policy (earliest `creationTimestamp`) takes precedence
+2. **Name-based Sorting**: If policies have identical creation timestamps, they are sorted alphabetically by namespaced name, with the first policy taking precedence
+
+```yaml
+# Policy created first - takes precedence
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: BackendTrafficPolicy
+metadata:
+  name: alpha-policy
+  creationTimestamp: "2023-01-01T10:00:00Z"
+spec:
+  targetRefs:
+    - kind: HTTPRoute
+      name: my-route
+  circuitBreaker:
+    maxConnections: 30
+
+---
+# Policy created later - lower precedence
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: BackendTrafficPolicy
+metadata:
+  name: beta-policy
+  creationTimestamp: "2023-01-01T11:00:00Z"
+spec:
+  targetRefs:
+    - kind: HTTPRoute
+      name: my-route
+  circuitBreaker:
+    maxConnections: 40
+```
+
+In this example, `alpha-policy` would take precedence due to its earlier creation time, so the HTTPRoute would use `maxConnections: 30`.
 
-Lastly, it's important to note that even when you apply a policy to a Gateway, the policy's effects are tracked separately for each backend service referenced in your routes. For example, if you set up circuit breaking on a Gateway with multiple backend services, each backend service will have its own independent circuit breaker counter. This ensures that issues with one backend service don't affect the others.
+When the `mergeType` field is unset, no merging occurs and only the most specific configuration takes effect. However, policies can be configured to merge with parent policies using the `mergeType` field (see [Policy Merging](#policy-merging) section below).
 
 ## Policy Merging
 

site/content/en/latest/concepts/gateway_api_extensions/client-traffic-policy.md

@@ -36,14 +36,67 @@ Think of `ClientTrafficPolicy` as a set of rules for your Gateway's entry points
 
 `ClientTrafficPolicy` is part of the Envoy Gateway API suite, which extends the Kubernetes Gateway API with additional capabilities. It's implemented as a Custom Resource Definition (CRD) that you can use to configure how Envoy Gateway manages incoming client traffic.
 
-You can attach it to Gateway API resources in two ways:
+### Targets
 
-1. Using `targetRefs` to directly reference specific Gateway resources
-2. Using `targetSelectors` to match Gateway resources based on labels
+ClientTrafficPolicy can be attached to Gateway API resources using two targeting mechanisms:
 
-The policy applies to all Gateway resources that match either targeting method. When multiple policies target the same resource, the most specific configuration wins.
+1. **Direct Reference (`targetRefs`)**: Explicitly reference specific Gateway resources by name and kind.
+2. **Label Selection (`targetSelectors`)**: Match Gateway resources based on their labels (see [targetSelectors API reference](../../api/extension_types#targetselectors))
 
-For example, consider these policies targeting the same Gateway Listener:
+The policy applies to all Gateway resources that match either targeting method.
+
+**Important**: A ClientTrafficPolicy can only target Gateway resources in the same namespace as the policy itself.
+
+### Precedence
+
+When multiple ClientTrafficPolicies apply to the same resource, Envoy Gateway resolves conflicts using section-level specificity and creation-time priority:
+
+1. **Section-specific policies** (targeting specific listeners via `sectionName`) - Highest precedence
+2. **Gateway-wide policies** (targeting entire Gateway) - Lower precedence
+
+#### Multiple Policies at the Same Level
+
+When multiple ClientTrafficPolicies target the same resource at the same specificity level (e.g., multiple policies targeting the same Gateway listener section), Envoy Gateway uses the following tie-breaking rules:
+
+1. **Creation Time Priority**: The oldest policy (earliest `creationTimestamp`) takes precedence
+2. **Name-based Sorting**: If policies have identical creation timestamps, they are sorted alphabetically by namespaced name, with the first policy taking precedence
+
+```yaml
+# Policy created first - takes precedence
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: ClientTrafficPolicy
+metadata:
+  name: alpha-policy
+  creationTimestamp: "2023-01-01T10:00:00Z"
+spec:
+  targetRefs:
+    - kind: Gateway
+      name: my-gateway
+      sectionName: https-listener
+  timeout:
+    http:
+      idleTimeout: 30s
+
+---
+# Policy created later - lower precedence
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: ClientTrafficPolicy
+metadata:
+  name: beta-policy
+  creationTimestamp: "2023-01-01T11:00:00Z"
+spec:
+  targetRefs:
+    - kind: Gateway
+      name: my-gateway
+      sectionName: https-listener
+  timeout:
+    http:
+      idleTimeout: 40s
+```
+
+In this example, `alpha-policy` would take precedence due to its earlier creation time, so the listener would use `idleTimeout: 30s`.
+
+For example, consider these policies with different specificity levels targeting the same Gateway:
 
 ```yaml
 # Policy A: Targets a specific listener in the gateway

site/content/en/latest/concepts/gateway_api_extensions/security-policy.md

@@ -27,14 +27,146 @@ title: "SecurityPolicy"
 
 ## SecurityPolicy in Envoy Gateway
 
-`SecurityPolicy` is implemented as a Kubernetes Custom Resource Definition (CRD) and follows the policy attachment model. You can attach it to Gateway API resources in two ways:
+`SecurityPolicy` is implemented as a Kubernetes Custom Resource Definition (CRD) and follows the policy attachment model. 
 
-1. Using `targetRefs` to directly reference specific Gateway resources
-2. Using `targetSelectors` to match Gateway resources based on labels
+### Targets
 
-The policy applies to all resources that match either targeting method. When multiple policies target the same resource, the most specific configuration wins.
+SecurityPolicy can be attached to Gateway API resources using two targeting mechanisms:
 
-For example, consider these policies targeting the same Gateway Listener:
+1. **Direct Reference (`targetRefs`)**: Explicitly reference specific resources by name and kind.
+2. **Label Selection (`targetSelectors`)**: Match resources based on their labels (see [targetSelectors API reference](../../api/extension_types#targetselectors))
+
+The policy applies to all resources that match either targeting method. You can target various Gateway API resource types including `Gateway`, `HTTPRoute`, and `GRPCRoute`.
+
+**Important**: A SecurityPolicy can only target resources in the same namespace as the policy itself.
+
+### Precedence
+
+When multiple SecurityPolicies apply to the same resource, Envoy Gateway resolves conflicts using a precedence hierarchy based on the target resource type and section-level specificity:
+
+1. **Route rule-level policies** (HTTPRoute/GRPCRoute with `sectionName` targeting specific rules) - Highest precedence
+2. **Route-level policies** (HTTPRoute, GRPCRoute without `sectionName`) - High precedence  
+3. **Listener-level policies** (Gateway with `sectionName` targeting specific listeners) - Medium precedence
+4. **Gateway-level policies** (Gateway without `sectionName`) - Lowest precedence
+
+#### Multiple Policies at the Same Level
+
+When multiple SecurityPolicies target the same resource at the same hierarchy level (e.g., multiple policies targeting the same HTTPRoute), Envoy Gateway uses the following tie-breaking rules:
+
+1. **Creation Time Priority**: The oldest policy (earliest `creationTimestamp`) takes precedence
+2. **Name-based Sorting**: If policies have identical creation timestamps, they are sorted alphabetically by namespaced name, with the first policy taking precedence
+
+```yaml
+# Policy created first - takes precedence
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: SecurityPolicy
+metadata:
+  name: alpha-policy
+  creationTimestamp: "2023-01-01T10:00:00Z"
+spec:
+  targetRefs:
+    - kind: HTTPRoute
+      name: my-route
+  cors:
+    allowOrigins:
+      - exact: https://example.com
+
+---
+# Policy created later - lower precedence
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: SecurityPolicy
+metadata:
+  name: beta-policy
+  creationTimestamp: "2023-01-01T11:00:00Z"
+spec:
+  targetRefs:
+    - kind: HTTPRoute
+      name: my-route
+  cors:
+    allowOrigins:
+      - exact: https://different.com
+```
+
+In this example, `alpha-policy` would take precedence due to its earlier creation time, so the HTTPRoute would use the CORS setting from `alpha-policy`.
+
+```yaml
+# HTTPRoute with named rules
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: my-route
+spec:
+  rules:
+  - name: rule-1  # Named rule for sectionName targeting
+    matches:
+    - path:
+        value: "/api"
+    backendRefs:
+    - name: api-service
+      port: 80
+
+---
+# Route rule-level policy (highest precedence)
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: SecurityPolicy
+metadata:
+  name: rule-policy
+spec:
+  targetRef:
+    kind: HTTPRoute
+    name: my-route
+    sectionName: rule-1  # Targets specific named rule
+  cors:
+    allowOrigins:
+    - exact: https://rule.example.com
+
+---
+# Route-level policy (high precedence)
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: SecurityPolicy
+metadata:
+  name: route-policy
+spec:
+  targetRef:
+    kind: HTTPRoute
+    name: my-route  # No sectionName = entire route
+  cors:
+    allowOrigins:
+    - exact: https://route.example.com
+
+---
+# Listener-level policy (medium precedence)
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: SecurityPolicy
+metadata:
+  name: listener-policy
+spec:
+  targetRef:
+    kind: Gateway
+    name: my-gateway
+    sectionName: https-listener  # Targets specific listener
+  cors:
+    allowOrigins:
+    - exact: https://listener.example.com
+
+---
+# Gateway-level policy (lowest precedence)
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: SecurityPolicy
+metadata:
+  name: gateway-policy
+spec:
+  targetRef:
+    kind: Gateway
+    name: my-gateway  # No sectionName = entire gateway
+  cors:
+    allowOrigins:
+    - exact: https://gateway.example.com
+```
+
+In this example, the specific rule `rule-1` within HTTPRoute `my-route` would use the CORS settings from the route rule-level policy (`https://rule.example.com`), overriding the route-level, listener-level, and gateway-level settings.
+
+For section-specific targeting, consider these policies with different hierarchy levels targeting the same Gateway:
 
 ```yaml
 # Policy A: Applies to a specific listener