Add integration docs and synthetic command examples

docs/integrations/output-schemas.md

@@ -0,0 +1,68 @@
+# Output Schemas
+
+## Scope
+
+seriatim emits one of three public JSON output contracts:
+
+- `seriatim-minimal`
+- `seriatim-intermediate`
+- `seriatim-full`
+
+These are used by `merge`, `trim`, and `normalize`.
+
+## Schema roles
+
+`seriatim-minimal`:
+
+- compact metadata plus ordered transcript segments
+- no source/provenance fields
+- no overlap groups
+
+`seriatim-intermediate`:
+
+- compact metadata plus ordered segments
+- includes optional segment `categories`
+- no source/provenance fields
+- no overlap groups
+
+`seriatim-full`:
+
+- full metadata (`input_reader`, module lists, input files, output modules)
+- source/provenance fields on segments
+- overlap-group data
+- version metadata populated from build info (`internal/buildinfo`)
+
+## Semantic invariants
+
+All schema outputs enforce:
+
+- segment IDs are sequential starting at `1`
+- segment timing uses `end >= start`
+
+Full schema also enforces overlap-group timing (`end >= start`).
+
+## Validation APIs
+
+Go package: `gitea.maximumdirect.net/eric/seriatim/schema`
+
+Key validators:
+
+- `schema.ValidateMinimalTranscript`
+- `schema.ValidateIntermediateTranscript`
+- `schema.ValidateTranscript`
+- `schema.ValidateMinimalJSON`
+- `schema.ValidateIntermediateJSON`
+- `schema.ValidateJSON`
+
+## Machine-readable schema files
+
+- [../../schema/minimal-output.schema.json](../../schema/minimal-output.schema.json)
+- [../../schema/intermediate-output.schema.json](../../schema/intermediate-output.schema.json)
+- [../../schema/full-output.schema.json](../../schema/full-output.schema.json)
+
+## Related docs and examples
+
+- CLI reference: [../cli.md](../cli.md)
+- Artifact internals: [../internal/artifacts.md](../internal/artifacts.md)
+- Trim example input artifact:
+  - [../../examples/trim/input-full.json](../../examples/trim/input-full.json)

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)