docs: enhance security header documentation by removing content references and clarifying examples

Author: cak

docs/configuration.md

@@ -88,18 +88,28 @@ In this example, a custom HTTP header `X-Custom-Header` is added to the response
 
 ## Combining Presets with Customization
 
-You can use one of the built-in presets as a starting point and then further customize specific headers to meet your security needs.
+You can use one of the built-in presets as a starting point and then further customize specific headers to meet your security needs. Every `Secure` instance exposes its configuration as a list of header builders via `headers_list`, so you can replace, reorder, or extend that list to adjust individual headers even after instantiation.
 
 ### Example: Customizing a Preset
 
 ```python
-from secure import Secure, Preset
+from secure import Preset, Secure, StrictTransportSecurity
 
 secure_headers = Secure.from_preset(Preset.BASIC)
-secure_headers.hsts.max_age(63072000)  # Override the default max-age value
+
+secure_headers.headers_list = [
+    header
+    for header in secure_headers.headers_list
+    if header.header_name != "Strict-Transport-Security"
+]
+secure_headers.headers_list.append(
+    StrictTransportSecurity()
+    .max_age(63072000)
+    .include_subdomains()
+)
 ```
 
-This approach allows you to quickly set up basic security headers while customizing certain parameters to fit your application’s security posture.
+This replaces the preset’s `Strict-Transport-Security` builder with a custom one while keeping the remaining headers unchanged.
 
 ---
 

docs/headers/cache_control.md

@@ -2,13 +2,13 @@
 
 ## Purpose
 
-`Cache-Control` is a comma-separated list of **directives** that control caching behavior for both **requests** and **responses**. Used correctly, it helps prevent sensitive data from being cached and improves performance for cacheable assets. :contentReference[oaicite:1]{index=1}
+`Cache-Control` is a comma-separated list of **directives** that control caching behavior for both **requests** and **responses**. Used correctly, it helps prevent sensitive data from being cached and improves performance for cacheable assets.
 
 ## Default behavior
 
 If you create `CacheControl()` and do not add directives, it returns the library default value:
 
-- **Default header value:** `no-store, max-age=0` :contentReference[oaicite:2]{index=2}
+- **Default header value:** `no-store, max-age=0`
 
 This is a secure baseline intended to prevent storage of sensitive responses.
 

docs/headers/cross-origin-resource-policy.md

@@ -4,13 +4,13 @@
 
 The `Cross-Origin-Resource-Policy` (CORP) response header lets a **resource owner** declare what sites/origins are allowed to load that resource.
 
-This header is commonly used to reduce cross-origin data leaks by controlling who can load your resources (images, scripts, etc.) and by blocking certain cross-origin/cross-site `no-cors` requests when the policy is more restrictive. :contentReference[oaicite:1]{index=1}
+This header is commonly used to reduce cross-origin data leaks by controlling who can load your resources (images, scripts, etc.) and by blocking certain cross-origin/cross-site `no-cors` requests when the policy is more restrictive.
 
 ## Best Practices
 
-- **`same-origin`**: Strong default for sensitive resources; only allow loads from the same origin. :contentReference[oaicite:2]{index=2}
-- **`same-site`**: Useful when you need to share resources across subdomains on the same “site” but not with unrelated sites. :contentReference[oaicite:3]{index=3}
-- **`cross-origin`**: Most permissive; allow any origin to load the resource (use intentionally, not by accident). :contentReference[oaicite:4]{index=4}
+- **`same-origin`**: Strong default for sensitive resources; only allow loads from the same origin.
+- **`same-site`**: Useful when you need to share resources across subdomains on the same “site” but not with unrelated sites.
+- **`cross-origin`**: Most permissive; allow any origin to load the resource (use intentionally, not by accident).
 
 ## Configuration with `secure`
 

docs/headers/x-permitted-cross-domain-policies.md

@@ -2,19 +2,19 @@
 
 ## Purpose
 
-`X-Permitted-Cross-Domain-Policies` is a **response header** that sets a _meta-policy_ controlling whether site resources can be accessed cross-origin by documents running in legacy web clients (for example, Adobe Acrobat or Microsoft Silverlight). :contentReference[oaicite:0]{index=0}
+`X-Permitted-Cross-Domain-Policies` is a **response header** that sets a _meta-policy_ controlling whether site resources can be accessed cross-origin by documents running in legacy web clients (for example, Adobe Acrobat or Microsoft Silverlight).
 
-Usage is less common today because Flash/Silverlight have been deprecated, but many security testing tools still check for `X-Permitted-Cross-Domain-Policies: none` to reduce the risk of an overly-permissive cross-domain policy being present accidentally or maliciously. :contentReference[oaicite:1]{index=1}
+Usage is less common today because Flash/Silverlight have been deprecated, but many security testing tools still check for `X-Permitted-Cross-Domain-Policies: none` to reduce the risk of an overly-permissive cross-domain policy being present accidentally or maliciously.
 
-> This documentation format mirrors the style used in the existing header docs (e.g., Cache-Control). :contentReference[oaicite:2]{index=2}
+> This documentation format mirrors the style used in the existing header docs (e.g., Cache-Control).
 
 ## Default behavior
 
 If you create `XPermittedCrossDomainPolicies()` and do not set a policy, it returns the library default value:
 
-- **Default header value:** `none` :contentReference[oaicite:3]{index=3}
+- **Default header value:** `none`
 
-This is the least permissive option and is the most common secure setting when you do not need legacy cross-domain policy behavior. :contentReference[oaicite:4]{index=4}
+This is the least permissive option and is the most common secure setting when you do not need legacy cross-domain policy behavior.
 
 ## Using with `Secure`