Document new duplicate key behavior

Companion to tenzir/tenzir#5445

Author: IyeOnline

src/partials/operators/ParsingOptions.mdx

@@ -1,5 +1,25 @@
 import Base from "../ParsingOptionsBase.mdx";
 
+### Duplicate Keys
+
+If the parser encounters a duplicate key in an event, it will transparently
+upgrade the field to be a list of values instead. If the values are of different
+type, conversions to a common type will be attempted, such as to a common number
+type. Ultimately values will be stringified if they do not share a common type.
+
+For a simple example, consider this JSON file:
+```json title="Example JSON with duplicate key" {2}
+{ "key": 7 }
+{ "key": 0.0, "key": 1 }
+{ "key": 42 }
+```
+The event with a duplicate key has the respective value upgraded to a list:
+```tql {2}
+{ key: 7 }
+{ key: [0.0, 1.0] }
+{ key: 42 }
+```
+
 ### `merge = bool (optional)`
 
 Merges all incoming events into a single schema\* that converges over time. This
@@ -8,4 +28,6 @@ to huge schemas filled with nulls and imprecise results. Use with caution.
 
 \*: In selector mode, only events with the same selector are merged.
 
+In merging mode, a repeated key will always overwrite the previous value.
+
 <Base />