From 665be5d98af3cb3f4dd3d22de5fafc64f60a54a0 Mon Sep 17 00:00:00 2001
From: Aykhan Shahsuvarov <aykhan.shahs@gmail.com>
Date: Sun, 15 Feb 2026 03:05:03 +0400
Subject: [PATCH] update docs

---
 docs/configuration.md | 45 +++++++++++++++++++++++++++++++------------
 docs/examples.md      | 24 +++++++++++++++++------
 2 files changed, 51 insertions(+), 18 deletions(-)

diff --git a/docs/configuration.md b/docs/configuration.md
index 489998b..ad1f6ac 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -227,26 +227,33 @@ SARIN_BODY='{"product": "car"}'
 
 ## Params
 
-URL query parameters. If multiple values are provided for a key, Sarin cycles through them in order, starting from a random index for each request. Supports [templating](templating.md).
+URL query parameters. Supports [templating](templating.md).
+
+When the same key appears as **separate entries** (in CLI or config file), all values are sent in every request. When multiple values are specified as an **array on a single key** (config file only), Sarin cycles through them.
 
 **YAML example:**
 
 ```yaml
 params:
   key1: value1
-  key2: [value2, value3]
+  key2: [value2, value3]  # cycles between value2 and value3
 
 # OR
 
 params:
   - key1: value1
-  - key2: [value2, value3]
+  - key2: [value2, value3]  # cycles between value2 and value3
+
+# To send both values in every request, use separate entries:
+params:
+  - key2: value2
+  - key2: value3  # both sent in every request
 ```
 
 **CLI example:**
 
 ```sh
--param "key1=value1" -param "key2=value2" -param "key2=value3"
+-param "key1=value1" -param "key2=value2" -param "key2=value3"  # sends both value2 and value3
 ```
 
 **ENV example:**
@@ -257,26 +264,33 @@ SARIN_PARAM="key1=value1"
 
 ## Headers
 
-HTTP headers. If multiple values are provided for a key, Sarin cycles through them in order, starting from a random index for each request. Supports [templating](templating.md).
+HTTP headers. Supports [templating](templating.md).
+
+When the same key appears as **separate entries** (in CLI or config file), all values are sent in every request. When multiple values are specified as an **array on a single key** (config file only), Sarin cycles through them.
 
 **YAML example:**
 
 ```yaml
 headers:
   key1: value1
-  key2: [value2, value3]
+  key2: [value2, value3]  # cycles between value2 and value3
 
 # OR
 
 headers:
   - key1: value1
-  - key2: [value2, value3]
+  - key2: [value2, value3]  # cycles between value2 and value3
+
+# To send both values in every request, use separate entries:
+headers:
+  - key2: value2
+  - key2: value3  # both sent in every request
 ```
 
 **CLI example:**
 
 ```sh
--header "key1: value1" -header "key2: value2" -header "key2: value3"
+-header "key1: value1" -header "key2: value2" -header "key2: value3"  # sends both value2 and value3
 ```
 
 **ENV example:**
@@ -287,26 +301,33 @@ SARIN_HEADER="key1: value1"
 
 ## Cookies
 
-HTTP cookies. If multiple values are provided for a key, Sarin cycles through them in order, starting from a random index for each request. Supports [templating](templating.md).
+HTTP cookies. Supports [templating](templating.md).
+
+When the same key appears as **separate entries** (in CLI or config file), all values are sent in every request. When multiple values are specified as an **array on a single key** (config file only), Sarin cycles through them.
 
 **YAML example:**
 
 ```yaml
 cookies:
   key1: value1
-  key2: [value2, value3]
+  key2: [value2, value3]  # cycles between value2 and value3
 
 # OR
 
 cookies:
   - key1: value1
-  - key2: [value2, value3]
+  - key2: [value2, value3]  # cycles between value2 and value3
+
+# To send both values in every request, use separate entries:
+cookies:
+  - key2: value2
+  - key2: value3  # both sent in every request
 ```
 
 **CLI example:**
 
 ```sh
--cookie "key1=value1" -cookie "key2=value2" -cookie "key2=value3"
+-cookie "key1=value1" -cookie "key2=value2" -cookie "key2=value3"  # sends both value2 and value3
 ```
 
 **ENV example:**
diff --git a/docs/examples.md b/docs/examples.md
index 71e7707..561cbb3 100644
--- a/docs/examples.md
+++ b/docs/examples.md
@@ -134,20 +134,34 @@ headers:
 
 </details>
 
-**Random headers from multiple values:**
+**Multiple values for the same header (all sent in every request):**
 
-> **Note:** When multiple values are provided for the same header, Sarin starts at a random index and cycles through all values in order. Once the cycle completes, it picks a new random starting point. This ensures all values are used while maintaining some randomness.
+> **Note:** When the same key appears as separate entries (in CLI or config file), all values are sent in every request.
 
 ```sh
 sarin -U http://example.com -r 1000 -c 10 \
   -H "X-Region: us-east" \
-  -H "X-Region: us-west" \
-  -H "X-Region: eu-central"
+  -H "X-Region: us-west"
 ```
 
 <details>
 <summary>YAML equivalent</summary>
 
+```yaml
+url: http://example.com
+requests: 1000
+concurrency: 10
+headers:
+    - X-Region: us-east
+    - X-Region: us-west
+```
+
+</details>
+
+**Cycling headers from multiple values (config file only):**
+
+> **Note:** When multiple values are specified as an array on a single key, Sarin starts at a random index and cycles through all values in order. Once the cycle completes, it picks a new random starting point.
+
 ```yaml
 url: http://example.com
 requests: 1000
@@ -159,8 +173,6 @@ headers:
         - eu-central
 ```
 
-</details>
-
 **Query parameters:**
 
 ```sh