Add integration docs and synthetic command examples

docs/cli.md

@@ -136,28 +136,28 @@ Merge with a speaker map and report output:
 
 ```sh
 go run ./cmd/seriatim merge \
-  --input-file speaker-a.json \
-  --input-file speaker-b.json \
-  --speakers speakers.yml \
-  --output-file merged.json \
-  --report-file merge-report.json
+  --input-file examples/minimal-merge/input-alice.json \
+  --input-file examples/minimal-merge/input-bob.json \
+  --speakers examples/minimal-merge/speakers.yml \
+  --output-file /tmp/seriatim-example-merge.json \
+  --report-file /tmp/seriatim-example-merge-report.json
 ```
 
 Trim to a segment subset:
 
 ```sh
 go run ./cmd/seriatim trim \
-  --input-file merged.json \
-  --output-file trimmed.json \
-  --keep "1-20,25"
+  --input-file examples/trim/input-full.json \
+  --output-file /tmp/seriatim-example-trim.json \
+  --keep "1-2"
 ```
 
 Normalize an external transcript JSON file:
 
 ```sh
 go run ./cmd/seriatim normalize \
-  --input-file external.json \
-  --output-file normalized.json
+  --input-file examples/normalize/object-with-segments.json \
+  --output-file /tmp/seriatim-example-normalize-object.json
 ```
 
 ## Exit and errors
@@ -171,6 +171,10 @@ go run ./cmd/seriatim normalize \
 - Configuration reference: [config.md](config.md)
 - Operations guide: [operations.md](operations.md)
 - Troubleshooting: [troubleshooting.md](troubleshooting.md)
+- Integration notes:
+  - [integrations/whisperx-json.md](integrations/whisperx-json.md)
+  - [integrations/output-schemas.md](integrations/output-schemas.md)
+- Synthetic examples: [../examples/README.md](../examples/README.md)
 - Public output schemas:
   - [../schema/minimal-output.schema.json](../schema/minimal-output.schema.json)
   - [../schema/intermediate-output.schema.json](../schema/intermediate-output.schema.json)

docs/config.md

@@ -157,6 +157,10 @@ All commands:
 - CLI reference: [cli.md](cli.md)
 - Operations guide: [operations.md](operations.md)
 - Troubleshooting: [troubleshooting.md](troubleshooting.md)
+- YAML example files:
+  - [../examples/speakers.yml](../examples/speakers.yml)
+  - [../examples/autocorrect.yml](../examples/autocorrect.yml)
+- Synthetic examples: [../examples/README.md](../examples/README.md)
 - Public output schemas:
   - [../schema/minimal-output.schema.json](../schema/minimal-output.schema.json)
   - [../schema/intermediate-output.schema.json](../schema/intermediate-output.schema.json)

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)

docs/operations.md

@@ -130,3 +130,7 @@ Transcript artifacts and reports are local files and may contain sensitive conve
 - CLI reference: [cli.md](cli.md)
 - Configuration reference: [config.md](config.md)
 - Troubleshooting: [troubleshooting.md](troubleshooting.md)
+- Integration notes:
+  - [integrations/whisperx-json.md](integrations/whisperx-json.md)
+  - [integrations/output-schemas.md](integrations/output-schemas.md)
+- Synthetic examples: [../examples/README.md](../examples/README.md)