Add integration docs and synthetic command examples

docs/integrations/whisperx-json.md

@@ -0,0 +1,85 @@
+# WhisperX-Like JSON Input
+
+## Scope
+
+This document covers the implemented JSON subset consumed by `seriatim merge`.
+It does not describe full WhisperX output.
+No explicit WhisperX version is encoded in the repository.
+
+## Supported top-level shape
+
+Merge expects a JSON object with top-level `segments` array:
+
+```json
+{
+  "segments": [
+    {
+      "start": 0.0,
+      "end": 1.2,
+      "text": "hello"
+    }
+  ]
+}
+```
+
+## Supported segment fields
+
+Required per segment:
+
+- `start` (number, `>= 0`)
+- `end` (number, `>= start`)
+- `text` (string)
+
+Optional per segment:
+
+- `words` (array)
+
+## Supported word fields
+
+Required when a word object is present:
+
+- `word` (string)
+
+Optional word timing fields:
+
+- `start` (number)
+- `end` (number)
+
+Timing rules:
+
+- if both `start` and `end` are present, they must be numeric and `end >= start`
+- if either timing field is missing, the word is accepted but not used as a
+  timing anchor for overlap resolution
+
+Additional optional word fields:
+
+- `score` (number)
+- `speaker` (string)
+
+## Validation and failure behavior
+
+Merge fails for:
+
+- malformed JSON
+- missing top-level `segments`
+- non-array `segments`
+- missing required segment fields
+- wrong field types
+- negative segment/word start times
+- segment/word end before start
+
+Word timing missing from a word does not fail merge; it emits a warning event
+in the optional report.
+
+## Overlap-resolution impact
+
+- overlap resolution uses timed words when available
+- untimed words are kept in replacement text but do not provide timing anchors
+
+## Related docs and examples
+
+- CLI reference: [../cli.md](../cli.md)
+- Configuration reference: [../config.md](../config.md)
+- Minimal merge example inputs:
+  - [../../examples/minimal-merge/input-alice.json](../../examples/minimal-merge/input-alice.json)
+  - [../../examples/minimal-merge/input-bob.json](../../examples/minimal-merge/input-bob.json)