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)