Rewrite integration documentation and verify maintained examples

docs/integrations/seriatim.md

@@ -1,60 +1,56 @@
-# Integration: seriatim
+# Integration: Seriatim
 
 ## Purpose
-Define Narratio's adapter contract for merge, normalize, and trim subprocess invocations of Seriatim.
+Define the Seriatim adapter contract used by `merge`, `normalize`, and `trim`.
 
-## Inputs and Outputs
-Inputs:
-- `MergeRequest`: raw/per-speaker normalized transcript inputs, base output path, optional report, speaker/autocorrect paths, logs/config
-- `NormalizeRequest`: input transcript, output path, schema, optional report, timeout/log/config
-- `TrimRequest`: input transcript, output path, keep selector, timeout/log/config
+## Adapter Boundary
+Interface:
+- `seriatim.Runner`
+- methods:
+  - `Run(ctx, MergeRequest)`
+  - `Normalize(ctx, NormalizeRequest)`
+  - `Trim(ctx, TrimRequest)`
 
-Outputs:
-- `MergeResult`, `NormalizeResult`, `TrimResult` with output paths, logs/config paths, exit code, duration, binary provenance, and metadata.
+Primary implementation:
+- `internal/adapters/seriatim/SubprocessRunner`
 
-## Boundaries
-Owns:
-- Validated deterministic CLI invocation construction
-- Optional env tuning propagation for merge
-- Invocation config file emission
-- JSON output validation
+Execution modes:
+- `seriatim merge`
+- `seriatim normalize`
+- `seriatim trim`
 
-Does not own:
-- Transcript input selection/materialization logic (stage-owned)
-- Bounds computation (scriptorium/trim-stage-owned)
+## Request/Result Contracts
+- `MergeRequest`/`MergeResult`: multi-input merge to base transcript, optional report.
+- `NormalizeRequest`/`NormalizeResult`: transcript normalization with explicit schema.
+- `TrimRequest`/`TrimResult`: transcript trimming with required keep selector.
 
-## Config Fields Used
-Via `pipeline.seriatim.*` mapped in app/stage wiring:
-- `binary`, `timeout`, `output_schema`, `coalesce_gap`, `report`
-- `env.overlap_word_run_gap`
-- `env.overlap_word_run_reorder_window`
-- `env.backchannel_max_duration`
-- `env.filler_max_duration`
+Results include output/log/config paths, timing, exit code, and metadata.
 
-## External Adapters Used
-- Shared subprocess helper (`internal/adapters/subprocess`).
+## Validation and Failure Semantics
+Runner construction validates:
+- binary presence;
+- timeout > 0;
+- supported output schema (`seriatim-minimal|seriatim-intermediate|seriatim-full`);
+- non-negative coalesce gap.
 
-## State and Manifest Behavior
-- No direct manifest writes.
-- Stage metadata consumes adapter result fields and preserves generated config/log references.
+Invocation fails on:
+- missing required request paths/inputs;
+- invalid normalize schema override;
+- subprocess failure;
+- invalid JSON outputs;
+- missing `segments` array for normalize/trim transcript outputs.
 
-## Skip and Resume Behavior
-- Adapter has no skip/resume logic. Runner controls stage execution.
+When report paths are provided/enabled, report files must parse as JSON.
 
-## Failure Behavior
-- Constructor fails for invalid binary/timeout/output-schema/coalesce-gap.
-- Merge fails on missing output path/inputs/report path (if enabled), subprocess errors, invalid merged output JSON, invalid report JSON.
-- Normalize fails on missing input/output, invalid schema, subprocess errors, invalid final output JSON shape, invalid report JSON.
-- Trim fails on missing input/output/keep selector, subprocess errors, invalid final-trimmed output JSON shape.
+## Deterministic Behavior
+- argument ordering is deterministic per command construction.
+- merge env overrides are explicit (`SERIATIM_*`) and only emitted when configured.
+- generated invocation YAML (`seriatim.generated.v1`) is emitted when requested.
+- adapter does not write manifests or choose stage inputs.
 
-## Tests to Inspect Before Changing
-- `internal/adapters/seriatim/subprocess_test.go`
-- `internal/adapters/seriatim/fake_test.go`
-- `internal/stage/merge_test.go`
-- `internal/stage/normalize_test.go`
-- `internal/stage/trim_test.go`
+## Config Mapping
+Config fields consumed through runner/stage wiring are under `pipeline.seriatim.*`.
 
-## Architectural Invariants
-- Supported output schemas are limited to `seriatim-minimal`, `seriatim-intermediate`, `seriatim-full`.
-- Final and final-trimmed outputs must include `segments` arrays.
-- Merge/normalize/trim all route through deterministic subprocess invocation.
+Maintained examples with Seriatim config:
+- `examples/pipeline.full.annotated.yml`
+- `examples/pipeline.production.yml`