From 242e9197e5f6264ec3501c3c9c393573e439e9a6 Mon Sep 17 00:00:00 2001
From: Yaroslav Gurov <ygurov@proton.me>
Date: Mon, 12 Jan 2026 22:09:48 +0000
Subject: [PATCH] readme: reformat tags formatting guide

---
 README.md | 163 ++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 134 insertions(+), 29 deletions(-)

diff --git a/README.md b/README.md
index 79cbb7e..d28cfd7 100644
--- a/README.md
+++ b/README.md
@@ -129,7 +129,7 @@ Value as a tag-sequence, as described in Tag format paragraph
 - **Example** `FormatIn = <b 0x4567><dz be 4><r 12><d><t>`
 
 ### Format of output
-- A format of packet which AWG device would generate on the output side instead of the original WG packet. The whole packet would be generated as a single piece and would be sent to the system as-is
+A format of packet which AWG device would generate on the output side instead of the original WG packet. The whole packet would be generated as a single piece and would be sent to the system as-is
 - **Format** `FormatOut = [fmt]`
 - `[fmt]` is a tag-sequence specified in Tags format section
 - **Example** `FormatOut = <b 0x1234><dz be 4><d>`
@@ -137,43 +137,148 @@ Value as a tag-sequence, as described in Tag format paragraph
 ## Tags format
 
 ### Static bytes tag
-- Adds specified bytes as is to the packet
-- **Format** `<b 0x[seq]>
-- **Param** `[seq]` is a hex-encoded sequence of bytes (2 hex numbers per byte). *always even-sized*
-- **Example** `<b 0xd34db3ef>`
+
+**Description**
+- Static bytes, sends and receives specified bytes as-is with predictable size
+- Immutable, does not change after configuration
+
+**Format**
+```
+<b 0x[seq]>
+```
+
+**Params**
+- `[seq]` - *always even-sized* hex-encoded sequence of bytes (2 hex numbers per byte)
+
+**Sample usage**
+```
+<b 0xd34db3ef>
+<b 0x1234><dz be 2><d>
+```
 
 ### Random bytes tag
-- Adds the specified amount of randomly-generated bytes to the packet
-- **Format** `<r [size]>`
-- `[size]` is the amount of bytes
-- **Example** `<r 21>`
+
+**Description**
+- Randomly-generated bytes of specified size
+- Uses cryptographically secure generator
+
+**Format**
+```
+<r [size]>
+```
+
+**Params**
+- `[size]` - amount of random bytes
+
+**Sample usage**
+```
+<r 21>
+<r 21><dz be 2><r 1><d>
+```
 
 ### Random digits tag
-- Adds the specified amount of randomly-generated digits from `[0-9]` set to the packet
-- **Format** `<rd [size]>`
-- `[size]` is the amount of digits
-- **Example** `<rd 1>`
+
+**Description**
+- Randomly-generated digits from `[0-9]` set
+- Uses cryptographically secure generator
+
+**Format**
+```
+<rd [size]>
+```
+
+**Params**
+- `[size]` - amount of digits
+
+**Sample usage**
+```
+<rd 21>
+<b 0x6e756d3a><rd 21><b 0x0d0a><dz hex 0x0d><b 0x0a><rd 1><d>
+```
 
 ### Random characters tag
-- Adds the specified amount of randomly-generated digits from `[a-zA-Z]` to the packet
-- **Format** `<rc [size]>`
-- `[size]` is the amount of chars
-- **Example** `<rc 2>`
+
+**Description**
+- Randomly-generated digits from `[a-zA-Z]` set
+- Uses cryptographically secure generator
+
+**Format**
+```
+<rc [size]>
+```
+
+**Params**
+- `[size]` - amount of chars
+
+**Example**
+```
+<rc 21>
+<b 0x6e616d653a><rc 21><b 0x0d0a><dz ascii 0x0d><b 0x0a><rc 1><d>
+```
 
 ### Timestamp tag
-- Adds current UNIX time (4 bytes) to the packet
-- **Format** `<t>`
+
+**Description**
+- Current UNIX time, int32
+- Provided in big-endian
+
+**Format**
+```
+<t>
+```
+
+**Sample usage**
+```
+<t>
+<b 0x1234><t><dz be 2><d>
+```
 
 ### Data tag
-- Adds original wireguard data to the packet
-- **Format** `<d>`
+
+**Description**
+- The original WireGuard packet
+- Has `H1-H4` and `S1-S4` params applied
+
+**Format**
+```
+<d>
+```
+
+**Sample usage**
+```
+<d>
+<dz hex 0x0d><b 0x0a><d>
+```
 
 ### Data size tag
-- Adds a size of the current original wireguard data to the packet
-- **Variant 1** `<dz [fmt] [size]>` 
-- `[fmt]` could be `be` or `le` meaning `big-endian` and `little-endian` accordingly
-- `[size]` is the amount of bytes a value take
-- **Example** `<dz be 4>` would put `int32` value in `big-endian` format
-- **Variant 2** `<dz [fmt] [end]>`
-- `[fmt]` could be `ascii` or `hex`. `ascii` converts `int(10)`-> `"10"`, and `hex` converts `int(10)` -> `"A"`. size of this field is dynamic. has no leading zeroes
-- `[end]` is the static symbol which is following the size. sender would also apply it to the packet
+
+**Description**
+- Size of the remaining pard of original WireGuard packet
+- `hex` and `ascii` formats are dynamic-sized and no leading zeroes
+- sender appends `[end]` to the end in case of `ascii` or `hex`
+
+**Format**
+```
+<dz [fmt] [size|end]>
+```
+
+**Params**
+- `[fmt]` - format of the field
+    - `be`    - fixed-size big-endian
+    - `le`    - fixed-size little-endian
+    - `ascii` - decimal ascii representation
+    - `hex`   - hexadecimal ASCII representation
+- `[size]` - amount of bytes of the field
+    - only for `be` and `le`
+- `[end]` - the symbol following the data size
+    - only for `ascii` and `hex`
+
+**Sample usage**
+```
+<dz ascii 0x0d>     e.g. `10 -> "10\r"`
+<dz hex 0x0a>       e.g. `10 -> "A\n"`
+<dz be 4>           e.g. `10 -> 0x00 0x00 0x00 0x0A`
+<dz le 2>           e.g. `10 -> 0x0A 0x00`
+
+<dz 0x0d><b 0x0a><d><b 0x0d0a>
+```