Added the standard documentation policy and a roadmap for adding documentation

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2026 eric. 
+Copyright (c) 2026 Eric Rakestraw. 
 
 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
 

README.md

@@ -1,8 +1,8 @@
 # seriatim
 
-`seriatim` merges per-speaker WhisperX-style JSON transcripts into a single JSON transcript that preserves speaker identity and chronological order. It also trims existing seriatim output artifacts by segment ID.
+`seriatim` merges per-speaker WhisperX-style JSON transcripts into a single JSON transcript that preserves speaker identity and chronological order. It also trims existing seriatim output artifacts by segment ID and normalizes external transcript-like JSON into standard seriatim output schemas.
 
-The current implementation supports the `merge` and `trim` commands. `merge` reads one or more input JSON files, optionally maps each input file to a canonical speaker using `speakers.yml`, sorts all segments by timestamp, detects and resolves overlaps when word-level timing is available, assigns consecutive numeric `id` values, and writes a merged JSON artifact. `trim` reads an existing seriatim output artifact and projects it to a retained segment subset.
+The current implementation supports the `merge`, `trim`, and `normalize` commands. `merge` reads one or more input JSON files, optionally maps each input file to a canonical speaker using `speakers.yml`, sorts all segments by timestamp, detects and resolves overlaps when word-level timing is available, assigns consecutive numeric `id` values, and writes a merged JSON artifact. `trim` reads an existing seriatim output artifact and projects it to a retained segment subset. `normalize` reads transcript-like JSON input, validates required segment fields, sorts deterministically, assigns fresh IDs, and emits a selected seriatim output schema.
 
 ## Usage
 
@@ -34,11 +34,30 @@ go run ./cmd/seriatim trim \
   --keep "1-10, 15, 20-25"
 ```
 
+Normalize external transcript-style JSON:
+
+```sh
+go run ./cmd/seriatim normalize \
+  --input-file transcript.json \
+  --output-file normalized.json
+```
+
+Normalize an Audita-style bare segment array to full schema with report output:
+
+```sh
+go run ./cmd/seriatim normalize \
+  --input-file audita-segments.json \
+  --output-file normalized-full.json \
+  --output-schema seriatim-full \
+  --report-file normalize-report.json
+```
+
 ## CLI
 
 ```text
 seriatim merge [flags]
 seriatim trim [flags]
+seriatim normalize [flags]
 ```
 
 Global flags:
@@ -108,6 +127,43 @@ Global flags:
 - The report includes a `trim-audit` event containing trim operation metadata, including selected IDs, retained/removed counts, removed IDs, and old-to-new segment ID mapping.
 - Old-to-new ID mapping is emitted as a deterministic ordered array of `{old_id, new_id}` pairs.
 
+`normalize` flags:
+
+| Flag | Required | Default | Description |
+| --- | --- | --- | --- |
+| `--input-file` | Yes | none | Input transcript JSON file. |
+| `--output-file` | Yes | none | Normalized transcript JSON output path. |
+| `--output-schema` | No | `seriatim-intermediate` (resolved via `SERIATIM_OUTPUT_SCHEMA` when set) | Output JSON schema: `seriatim-minimal`, `seriatim-intermediate`, or `seriatim-full`. |
+| `--output-modules` | No | `json` | Comma-separated output modules. Current normalize support is `json` only. |
+| `--report-file` | No | none | Optional report JSON output path. |
+
+`normalize` input shapes:
+
+- Top-level object with a `segments` array.
+- Bare top-level array of segment objects (for example, Audita-style output).
+
+`normalize` behavior:
+
+- Repairs missing timing fields deterministically:
+  if one of `start`/`end` is present, sets both to that value;
+  if both are missing, uses midpoint of previous `end` and next `start`,
+  with edge fallback to available neighbor and `0.0` for single-segment inputs.
+- If `end < start`, swaps them.
+- Fills missing/empty `speaker` with `Unknown_Speaker`.
+- Drops segments with missing, empty, or whitespace-only `text`.
+- Validates repaired timing with `start >= 0`.
+- Accepts existing input `id` values as provenance only.
+- Reassigns output segment IDs sequentially from `1` to `N`.
+- Sorts deterministically by `(start, end, original_input_index, speaker)`.
+- Uses original input order only as a tie-breaker.
+- Does not run merge postprocessors such as overlap detection, overlap resolution, coalescing, or autocorrect.
+- Useful for converting external transcript outputs into standard seriatim artifacts.
+
+`normalize` report output:
+
+- When `--report-file` is provided, normalize emits deterministic report events with input shape detection, segment counts, schema/module selections, sorting/ID diagnostics, and output write/validation summaries.
+- A machine-readable `normalize-audit` event is included for downstream tooling.
+
 Environment variables:
 
 | Environment Variable | Default | Description |

architecture.md

@@ -3,7 +3,8 @@
 `seriatim` is a deterministic transcript utility for:
 
 - merging multiple per-speaker transcript inputs into a single chronologically ordered diarized transcript, and
-- projecting existing seriatim transcript artifacts through deterministic segment-ID trimming.
+- projecting existing seriatim transcript artifacts through deterministic segment-ID trimming, and
+- canonicalizing external transcript-style JSON inputs into standard seriatim output schemas.
 
 The initial use case is merging independently transcribed speaker audio tracks from the same recorded session, such as a weekly tabletop RPG session. The architecture should also support meetings, podcasts, interviews, and other multi-speaker events.
 
@@ -60,7 +61,7 @@ configuration check
 
 Each stage has an explicit data contract. Input and output stages perform I/O. Processing stages should be deterministic transformations over in-memory models and should record report events for validation findings, corrections, and transformations.
 
-`merge` runs this pipeline. `trim` is intentionally separate from this pipeline and operates at the artifact layer.
+`merge` runs this pipeline. `trim` and `normalize` are intentionally separate from this pipeline and operate at the artifact layer.
 
 ## Stage Contracts
 
@@ -214,6 +215,24 @@ Design constraints:
 
 `trim` must not rerun merge postprocessors such as `resolve-overlaps`, `coalesce`, or `autocorrect`.
 
+### 8. Artifact Canonicalization Stage (`normalize` command)
+
+`normalize` is an artifact-level command that reads transcript-like JSON and emits a standard seriatim output artifact in a selected schema.
+
+Design constraints:
+
+- `normalize` runs outside the merge pipeline and does not invoke merge preprocessing or postprocessing modules.
+- `normalize` accepts two input shapes: object-with-`segments` and bare segment arrays.
+- `normalize` applies deterministic repair rules for missing/irregular `start`, `end`, and `speaker`, and drops segments with missing/empty `text`.
+- `normalize` sorts segments deterministically by chronological keys and stable input-index tie-breakers.
+- `normalize` assigns fresh sequential output IDs (`1..N`) after sorting.
+- `normalize` validates final output against the selected schema before writing.
+- `normalize` writes optional deterministic report diagnostics when `--report-file` is requested.
+
+`normalize` is intended for canonicalizing external transcript outputs (including Audita-style bare arrays) into seriatim contracts, not for running merge-time language or overlap transformations.
+
+`normalize` must not run merge postprocessors such as overlap detection, overlap resolution, coalescing, or autocorrect.
+
 ## Module Classification
 
 Modules should be classified by their contract and allowed effects.
@@ -442,6 +461,13 @@ Trim-specific determinism requirements:
 - Old-to-new ID mapping in trim reports is emitted in deterministic order.
 - Full-schema overlap recomputation is deterministic for the same input artifact and selector.
 
+Normalize-specific determinism requirements:
+
+- Input-shape detection is deterministic.
+- Segment ordering is deterministic for identical input data.
+- Output IDs are always reassigned sequentially after deterministic sorting.
+- Normalize diagnostic reports are deterministic for identical inputs and configuration.
+
 ## Go Package Layout
 
 ```text
@@ -450,6 +476,7 @@ internal/config/         CLI/env/config loading and validation
 internal/pipeline/       Pipeline orchestration and module registry
 internal/builtin/        Built-in pipeline modules
 internal/artifact/       Conversion from internal model to public output schema
+internal/normalize/      Normalize input parsing, validation, deterministic sorting, schema conversion, and diagnostics
 internal/trim/           Artifact parsing, trim selection, schema conversion, overlap recomputation for full schema
 internal/buildinfo/      Build-time version metadata
 internal/speaker/        Speaker map parsing and lookup
@@ -468,6 +495,12 @@ For trim:
 - CLI command code handles only flag parsing, file I/O, and report emission.
 - Transform logic is deterministic and pure except for command-layer I/O.
 
+For normalize:
+
+- `internal/normalize` contains parsing/validation and deterministic schema conversion logic.
+- CLI command code handles flag parsing and delegates execution.
+- Normalize remains artifact-level and does not compose merge pipeline modules.
+
 ## Default Modules
 
 The default pipeline is equivalent to explicit module lists.

docs/policy/architecture.md

@@ -0,0 +1,219 @@
+# Architecture Policy
+
+## Purpose
+
+This document defines seriatim's development architecture and invariants for
+maintainers and automated coding agents. It describes how the implemented
+system is intended to be built and changed. It is not a user manual, CLI
+reference, config reference, or roadmap.
+
+Keep this document aligned with [documentation policy](documentation.md). It
+must describe current behavior only; planned or speculative work belongs under
+`docs/roadmap/`.
+
+## Project Shape
+
+seriatim is a Go CLI for transcript artifact processing. The implemented
+commands are `merge`, `trim`, and `normalize`.
+
+`merge` reads one or more JSON transcript files, optionally maps input files to
+canonical speakers, runs a registry-selected preprocessing chain, merges
+canonical segments into deterministic chronological order, runs a
+registry-selected postprocessing chain, validates the selected output schema,
+and writes JSON output plus an optional JSON report.
+
+`trim` and `normalize` are artifact-level commands outside the merge pipeline.
+`trim` reads an existing seriatim output artifact and projects it by segment ID.
+`normalize` reads transcript-like JSON and emits one of seriatim's supported
+output schemas. Neither command runs merge preprocessing or postprocessing
+modules.
+
+The supported public output schemas are `seriatim-minimal`,
+`seriatim-intermediate`, and `seriatim-full`. For current command and flag
+details, use [the README](../../README.md) until dedicated `docs/cli.md` and
+`docs/config.md` files exist.
+
+## Core Design Principles
+
+- Keep a hexagonal architecture boundary. Domain models, stage contracts, and
+  deterministic transformations must stay separate from CLI parsing,
+  filesystem access, config loading, reporting, and other external adapters.
+- Keep stages and modules composable. Built-in modules are selected by
+  canonical registry names and implement explicit interfaces for their pipeline
+  role.
+- Preserve deterministic behavior. Given the same inputs, configuration, and
+  version, output ordering, segment IDs, schema validation, and report event
+  ordering should remain stable.
+- Current command execution is sequential. There is no scheduler, worker pool,
+  or concurrent module execution in the implemented pipeline. Any concurrency
+  added later must be bounded, observable, and must not make output handling
+  nondeterministic.
+- Prefer the Go standard library. Third-party dependencies should remain narrow
+  and justified, such as Cobra for CLI structure, YAML parsing, and JSON Schema
+  validation.
+- Document current behavior. Architecture, user, and internal docs must not
+  describe planned features as implemented behavior.
+
+## Architectural Boundaries
+
+Core transcript data belongs in `internal/model` and public artifact contracts
+belong in `schema`. Conversion from internal merged data to public JSON shapes
+belongs at the artifact boundary, not inside CLI code or transformation
+packages.
+
+Pipeline orchestration belongs in `internal/pipeline`. It resolves registered
+modules, validates preprocessing state transitions, executes stages in order,
+collects report events, converts the final transcript, and writes optional
+reports. Built-in adapters and modules are registered from `internal/builtin`.
+
+CLI code in `internal/cli` should parse flags, build validated config values,
+and delegate. `merge` delegates to `pipeline.Run`; `trim` and `normalize`
+perform artifact-level orchestration and delegate deterministic parsing,
+validation, and transformation work to their internal packages.
+
+Config loading and validation belongs in `internal/config`. Filesystem reads and
+writes are adapter concerns and should not spread into pure transformation
+helpers. Existing built-in modules that load configured YAML files must keep
+that I/O narrow and explicit.
+
+Reports belong in `internal/report`. Modules and commands should emit concise
+events for validation findings, corrections, and transformations without
+turning report messages into a duplicate output artifact.
+
+Tests and samples are supporting evidence for behavior. Tests should verify
+stable contracts and edge cases; samples should remain valid examples, not
+hidden architecture dependencies.
+
+## Modules or Stages
+
+The merge pipeline has these implemented stages:
+
+- `InputReader`: reads configured external input into raw transcripts.
+- `Preprocessor`: transforms `PreprocessState` from raw to canonical state.
+- `Merger`: combines canonical transcripts into one merged transcript.
+- `Postprocessor`: transforms or annotates the merged transcript.
+- `OutputWriter`: writes the selected output artifact.
+
+Modules must keep narrow responsibilities, declare their stage through the
+interface they implement, and use explicit config values. Preprocessors must
+declare `Requires()` and `Produces()` states; the runner rejects invalid
+raw/canonical ordering before processing completes.
+
+Modules run in the configured order. Order-affecting modules must run before
+`assign-ids`, and `validate-output` must see final IDs that match the selected
+schema. Accepted and rejected transformations should be deterministic and, when
+observable, recorded through report events.
+
+Transformation helpers should avoid hidden global state. Shared caches, such as
+compiled JSON schemas, must be protected and must not affect output ordering.
+
+## State, Inputs, and Outputs
+
+seriatim is file-based. It reads JSON inputs and optional YAML rule files, then
+writes JSON transcript artifacts and optional JSON reports.
+
+The implemented application has no durable database, daemon state, resume
+state, remote storage, or background job state. Runtime state is held in memory
+for the current command invocation and serialized only through requested output
+and report files.
+
+Input file paths are normalized and validated during config construction.
+`merge` sorts input file paths before processing, then uses stable segment sort
+keys. `trim` preserves transcript order while renumbering retained IDs.
+`normalize` sorts by implemented deterministic keys and assigns fresh IDs.
+
+## Configuration and CLI Boundaries
+
+The CLI surface is an adapter over validated config structs. Cobra command code
+should stay thin: parse flags, account for flag/default precedence, call config
+constructors, and delegate.
+
+Config constructors validate required paths, output parent directories, module
+lists, selected schemas, mutually exclusive trim selector options, and supported
+environment-derived settings. Module name validation is split between config
+where command-specific names are fixed and the pipeline registry where module
+composition is resolved.
+
+Do not duplicate full CLI or config reference material here. Use
+[the README](../../README.md) for the current user-facing reference until the
+canonical `docs/cli.md` and `docs/config.md` files exist.
+
+## Errors, Logging, and Diagnostics
+
+Commands return errors instead of printing inside deep logic. The root command
+silences Cobra usage/error output, and `cmd/seriatim/main.go` prints one error
+to stderr and exits with status `1`.
+
+Validation failures should fail fast with contextual errors. Correctable
+conditions should be deterministic and, where reports are requested, reflected
+as report events. Optional reports contain metadata and ordered events; they are
+not required for command success unless the report file itself cannot be
+written.
+
+The implemented code does not use a logging subsystem. Diagnostics are returned
+as errors or written to optional report JSON. Normalize report events avoid
+embedding transcript text; keep that privacy-oriented behavior when changing
+normalize diagnostics.
+
+## Testing Expectations
+
+`go test ./...` is the repository-wide check. There is currently no Makefile,
+taskfile, linter config, or dedicated documentation check.
+
+When changing config or CLI behavior, inspect `internal/config` and
+`internal/cli` tests. When changing pipeline composition or stage contracts,
+inspect `internal/pipeline` and `internal/builtin` tests. When changing
+correction or annotation modules, inspect the package tests for overlap,
+coalesce, danglers, backchannel, filler, and autocorrect behavior.
+
+When changing artifact-level commands, inspect `internal/trim`,
+`internal/normalize`, and their CLI tests. When changing public output shape or
+schema validation, inspect `schema` and `internal/artifact` tests. Report and
+diagnostic changes should be covered through the command or package tests that
+emit the affected events.
+
+## Dependency Policy
+
+Prefer the Go standard library for parsing, data transformation, concurrency
+primitives, filesystem work, and testing wherever it is reasonable.
+
+Third-party dependencies must be narrow, justified, and preferably de facto
+standard for their purpose. Existing examples include Cobra for CLI structure,
+`gopkg.in/yaml.v3` for YAML files, and `jsonschema/v6` for validating embedded
+public JSON schemas. Avoid broad framework dependencies for behavior that is
+already simple and local.
+
+## Documentation Expectations
+
+Architecture docs must stay aligned with [documentation policy](documentation.md).
+Current-behavior docs must not become aspirational. If code and docs disagree,
+fix the inaccurate current-behavior doc or put planned work under
+`docs/roadmap/`.
+
+Prefer links to canonical docs instead of repeating full CLI, config, schema, or
+operations reference material. Keep examples real, tested where practical, and
+free of secrets or private transcript data.
+
+## Architectural Invariants
+
+- Keep core/domain logic separate from CLI, config, filesystem, reporting, and
+  other adapter concerns.
+- Keep modules narrowly scoped, explicitly configured, and composable by
+  registry name.
+- Preserve deterministic ordering, final segment ID assignment, and schema
+  validation before output acceptance.
+- Keep `trim` and `normalize` artifact-level; do not run merge modules from
+  those commands.
+- Keep public output schemas validated through `schema`.
+- Keep optional reports ordered, concise, and diagnostic.
+- Avoid broad dependencies without a concrete maintainability benefit.
+- Do not document unimplemented behavior outside `docs/roadmap/`.
+
+## Non-Goals
+
+The implemented application does not perform transcription, audio diarization,
+speaker inference from audio or text, summarization, daemon operation, remote
+storage, dynamic external plugin loading, or concurrent pipeline execution.
+
+The architecture policy is not a package-by-package reference, CLI manual,
+config reference, schema reference, or roadmap.

docs/policy/documentation.md

@@ -0,0 +1,356 @@
+# Go Project Documentation Policy
+
+## Purpose
+
+Project documentation must help four audiences:
+
+1. users who need to run the application;
+2. administrators/operators who need to configure and operate it;
+3. developers who need to understand and change it safely;
+4. LLM coding agents that need clear scope, boundaries, and invariants.
+
+Docs should be accurate, concise, task-oriented, and organized by audience. Prefer links to canonical docs over repetition.
+
+## Core Rules
+
+### 1. Keep docs concise
+
+Each document should cover a defined scope and only the essentials for that scope.
+
+Avoid:
+- long background explanations;
+- repeated reference material;
+- implementation detail in user-facing docs;
+- aspirational language outside roadmap docs;
+- verbose examples where one minimal example is clearer.
+
+### 2. Document only implemented behavior outside roadmap files
+
+Unimplemented, planned, aspirational, experimental, or future work may be described only under:
+
+- `docs/roadmap/`
+
+No other documentation file, including `README.md`, should describe code, features, modules, stages, commands, config fields, or behaviors that do not currently exist.
+
+If a feature is partial, non-roadmap docs may describe only the implemented portion and its current boundary.
+
+### 3. Use canonical homes
+
+Each type of information should have one canonical location.
+
+Canonical homes:
+
+- project purpose and quickstart: `README.md`
+- development principles: `docs/policy/architecture.md`
+- configuration reference: `docs/config.md`
+- CLI reference: `docs/cli.md`
+- operations and recovery: `docs/operations.md`
+- troubleshooting: `docs/troubleshooting.md`
+- implemented internals: `docs/internal/`
+- future work: `docs/roadmap/`
+- contributor workflow: `docs/policy/development.md`
+- copyable examples: `examples/`
+
+Other files should summarize briefly and link to the canonical source.
+
+### 4. Keep examples real
+
+Examples should be valid, maintained, and free of secrets.
+
+Where practical:
+- example configs should load successfully;
+- example commands should match real CLI syntax;
+- important examples should be covered by tests.
+
+## Documentation Profiles
+
+All projects require:
+
+- `README.md`
+- `docs/policy/architecture.md`
+
+Additional docs depend on the project.
+
+### Small library
+
+Recommended:
+- `docs/policy/development.md`, if contributor conventions are non-obvious
+
+### Simple CLI
+
+Required:
+- `docs/cli.md`
+
+Recommended:
+- `docs/policy/development.md`
+
+### Config-driven CLI
+
+Required:
+- `docs/cli.md`
+- `docs/config.md`
+
+Recommended:
+- `examples/`
+- `docs/policy/development.md`
+
+### Stateful or operator-facing application
+
+Required:
+- `docs/cli.md`, if CLI-based
+- `docs/config.md`, if config-driven
+- `docs/operations.md`
+
+Recommended:
+- `docs/troubleshooting.md`
+- `examples/`
+- `docs/policy/development.md`
+
+### Modular, staged, service-oriented, or orchestration application
+
+Required:
+- `docs/cli.md`, if CLI-based
+- `docs/config.md`, if config-driven
+- `docs/operations.md`
+- `docs/internal/`
+- `docs/policy/development.md`
+
+Recommended:
+- `docs/troubleshooting.md`
+- validated examples under `examples/`
+
+## Required Documents
+
+### README.md
+
+**Audience:** users, administrators, operators
+
+The README is the outward-facing project orientation page.
+
+It should include, in order:
+
+1. concise description;
+2. elevator pitch;
+3. shortest useful command or usage example;
+4. links to targeted docs.
+
+The README should be short. It is not a manual.
+
+The “shortest useful command” means the simplest command that performs the project’s core use case. (It does not mean `app --help`.)
+
+### docs/policy/architecture.md
+
+**Audience:** developers, LLM coding agents
+
+`docs/policy/architecture.md` is required for every project.
+
+It is an inward-facing development policy document. It should describe how the project is intended to be built and changed.
+
+It should include:
+
+- project shape;
+- core design principles;
+- package and boundary philosophy;
+- state/persistence philosophy, if applicable;
+- external integration philosophy, if applicable;
+- error-handling and logging principles;
+- testing expectations;
+- documentation expectations;
+- architectural invariants;
+- explicit non-goals, if useful.
+
+For small projects, this file may be brief. It may simply state that the project is intentionally narrow, monolithic, and dependency-light.
+
+### docs/policy/development.md
+
+**Audience:** developers, LLM coding agents
+
+Required for projects maintained by humans and LLM coding agents.
+
+It should include:
+
+- repository layout;
+- build/test commands;
+- coding conventions;
+- dependency policy;
+- how to add config fields;
+- how to add CLI flags;
+- how to add stages/modules/adapters, if applicable;
+- how to update examples;
+- documentation update expectations.
+
+### docs/config.md
+
+**Audience:** administrators, operators, advanced users
+
+Required for applications with configuration files.
+
+It should include, in order:
+
+1. config file locations and discovery precedence;
+2. minimal working config;
+3. production-oriented config;
+4. full configuration reference;
+5. secrets handling, if applicable;
+6. links to maintained examples.
+
+The full configuration reference should be canonical.
+
+### docs/cli.md
+
+**Audience:** users, administrators, operators
+
+Required for CLI applications.
+
+It should include, in order:
+
+1. shortest useful command;
+2. command overview;
+3. complete flag reference;
+4. common workflows;
+5. diagnostic or recovery commands, if applicable.
+
+Explain when commands are useful, not just their syntax.
+
+### docs/operations.md
+
+**Audience:** administrators, operators
+
+Required for applications that maintain state, support resume behavior, run multiple stages, write durable artifacts, use remote storage, or require recovery procedures.
+
+It should cover:
+
+- normal workflow;
+- filesystem layout;
+- remote storage layout, if applicable;
+- logs and manifests;
+- resume/retry behavior;
+- cleanup behavior;
+- archive/backup behavior;
+- safe recovery procedures;
+- operational caveats.
+
+### docs/troubleshooting.md
+
+**Audience:** administrators, operators
+
+Recommended once recurring failure modes exist.
+
+Each entry should include:
+
+- symptom;
+- likely cause;
+- diagnostic command or inspection step;
+- safe fix;
+- relevant links.
+
+### docs/internal/
+
+**Audience:** developers, LLM coding agents
+
+Required for modular, staged, service-oriented, or orchestration projects.
+
+This directory describes implemented internal components. It is not the roadmap.
+
+Use one file per major component where useful.
+
+Each component doc should include:
+
+1. purpose;
+2. inputs and outputs;
+3. boundaries;
+4. config fields used;
+5. external adapters used;
+6. state or manifest behavior, if applicable;
+7. skip/resume behavior, if applicable;
+8. failure behavior;
+9. tests to inspect before changing;
+10. architectural invariants.
+
+### docs/roadmap/
+
+**Audience:** maintainers, developers, LLM coding agents
+
+This is the only place for planned, future, aspirational, experimental, or unimplemented work.
+
+Roadmap docs should clearly distinguish:
+
+- proposed work;
+- accepted plans;
+- deferred ideas;
+- rejected ideas;
+- implementation prompts or task breakdowns, if useful.
+
+Roadmap docs should not be confused with current behavior.
+
+### docs/integrations/
+
+**Audience:** developers, LLM coding agents
+
+Required for projects that depend on external CLIs, APIs, services, protocols, or file formats where the integration contract is important to maintain.
+
+This directory contains concise, versioned reference notes for external integration contracts. It should document only the parts of the external system that this project actually uses.
+
+Use one file per integration where useful.
+
+## Examples Directory
+
+Projects with non-trivial configuration or workflows should include `examples/`.
+
+Useful examples include:
+
+- minimal working config;
+- production-oriented config;
+- full annotated config;
+- local development config;
+- remote/object-storage config;
+- minimal session/input file.
+
+Examples should be valid, maintained, tested when practical, and linked from relevant docs.
+
+## Security and Privacy
+
+Docs and examples must not include:
+
+- real API keys;
+- tokens;
+- passwords;
+- private keys;
+- private environment dumps;
+- sensitive user data;
+- raw private transcripts;
+- private infrastructure details unless intentionally public.
+
+Document secret-handling mechanisms, not actual secret values.
+
+## Maintenance Rules
+
+When docs change, verify the affected behavior.
+
+Where practical:
+
+- load example config files in tests;
+- test CLI examples or command parser behavior;
+- validate documented flags against real flags;
+- remove stale references;
+- update links after renames;
+- keep roadmap content out of non-roadmap docs.
+
+If documentation and code disagree, fix the documentation and/or open a roadmap item; do not leave aspirational behavior in current-behavior docs.
+
+Documentation is complete only when it matches the current code.
+
+## Documentation Change Checklist
+
+Before merging documentation changes, verify:
+
+- README is concise and orientation-focused.
+- `docs/policy/architecture.md` describes development principles.
+- Future work appears only under `docs/roadmap/`.
+- User-facing docs avoid unnecessary internals.
+- Developer-facing docs preserve boundaries and invariants.
+- Config examples match the schema.
+- CLI examples match real commands and flags.
+- Defaults appear in the canonical config reference.
+- No secrets or private data are included.
+- Links are accurate.

docs/roadmap/documentation.md

@@ -0,0 +1,579 @@
+# Documentation Roadmap
+
+## Purpose
+
+This roadmap defines the work required to bring seriatim's documentation into
+compliance with `docs/policy/documentation.md` and the current implementation.
+It is grounded in the repository as it exists now: the Go CLI, config loading,
+pipeline modules, artifact commands, schemas, reports, samples, and tests.
+
+Outside `docs/roadmap/`, documentation must describe only implemented
+behavior. Planned, future, deprecated, experimental, or unimplemented work must
+remain in roadmap documents until the code exists.
+
+## Repository Documentation Inventory
+
+- `README.md` - keep and rewrite. It currently mixes project orientation,
+  quickstart, full CLI reference, config/env reference, file formats, module
+  internals, limitations, and release build notes. Policy says README should be
+  concise and link to canonical docs.
+- `docs/policy/documentation.md` - keep and lightly update only if the policy
+  itself changes. It is the controlling documentation layout and maintenance
+  policy.
+- `docs/policy/architecture.md` - keep and lightly update as implementation
+  changes. It is the canonical development architecture policy.
+- Root `architecture.md` - delete after salvage, or move only truly roadmap
+  material into `docs/roadmap/`. It is in the wrong canonical home and contains
+  future-oriented and aspirational claims.
+- `docs/roadmap/documentation.md` - create new. This file is the planning
+  artifact for the documentation migration.
+- `samples/` - split or move after audit. It contains sample raw transcripts,
+  merged artifacts, reports, `speakers.yml`, and `autocorrect.yml`, but
+  copyable examples belong under `examples/`. The raw sample data is large and
+  should be reviewed for privacy and maintainability before linking from docs.
+- `schema/*.schema.json` - keep. These are public output contracts and should
+  be linked from documentation instead of duplicated in full.
+- Missing canonical docs - create `docs/cli.md`, `docs/config.md`,
+  `docs/operations.md`, `docs/policy/development.md`, `docs/internal/`, and
+  likely `docs/troubleshooting.md`, `docs/integrations/`, and `examples/`.
+
+## Policy Compliance Assessment
+
+Required documents missing for seriatim's current shape as a modular, staged,
+CLI/config-driven project:
+
+- `docs/cli.md`
+- `docs/config.md`
+- `docs/operations.md`
+- `docs/internal/`
+- `docs/policy/development.md`
+
+Recommended documents and directories missing:
+
+- `docs/troubleshooting.md`
+- maintained copyable examples under `examples/`
+- concise integration notes under `docs/integrations/`
+
+Existing compliance issues:
+
+- `README.md` is too broad for its canonical scope. It should keep project
+  purpose, quickstart, and links, then delegate CLI, config, operations,
+  internals, and schema details.
+- Root `architecture.md` is stale and in the wrong home. It includes future
+  input methods and formats, future output formats, dynamic plugin speculation,
+  an LLM non-goal, interface sketches that diverge from code, and other
+  development-policy content now covered by `docs/policy/architecture.md`.
+- Non-roadmap docs should not carry forward claims about future defaults,
+  future formats, unimplemented plugin systems, or unimplemented alternate
+  input/output methods.
+- Historical or deprecated wording, such as the old speaker map format, should
+  move out of the README unless it is still needed in troubleshooting or a
+  narrow migration note.
+- There is no `examples/` directory. `samples/` exists but is not the canonical
+  examples home and should not be treated as copyable public examples without a
+  privacy and size audit.
+- Links need verification after migration: README should link to all new
+  canonical docs, docs should link to schema files and maintained examples, and
+  no doc should link to the deleted root `architecture.md`.
+
+## Target Documentation Set
+
+### `README.md`
+
+- Audience: users, administrators, and operators.
+- Purpose: project orientation and shortest useful quickstart.
+- Canonical scope: concise project purpose, elevator pitch, one minimal command,
+  and links to targeted docs.
+- Recommended outline: project description; shortest merge command; command
+  summary; links to CLI, config, operations, architecture, development, schemas,
+  examples, and troubleshooting.
+- Source of truth: current `README.md`, `internal/cli`, `internal/config`,
+  `cmd/seriatim/main.go`, and CLI tests.
+- Acceptance criteria: no full flag tables, no full config reference, no module
+  manual, no future-feature claims, and all links resolve.
+
+### `docs/cli.md`
+
+- Audience: users, administrators, and operators.
+- Purpose: canonical CLI reference and workflows.
+- Canonical scope: shortest useful command, command overview, complete flag
+  reference, common workflows, diagnostics and report flags.
+- Recommended outline: shortest useful command; global flags; `merge`; `trim`;
+  `normalize`; common workflows; exit/error behavior; links to config,
+  operations, examples, and schemas.
+- Source of truth: `internal/cli/root.go`, `internal/cli/merge.go`,
+  `internal/cli/trim.go`, `internal/cli/normalize.go`, `internal/config`, and
+  `internal/cli/*_test.go`.
+- Acceptance criteria: every documented flag, default, and required/mutually
+  exclusive rule matches code; package internals are linked rather than
+  explained in depth.
+
+### `docs/config.md`
+
+- Audience: administrators, operators, and advanced users.
+- Purpose: canonical runtime configuration reference.
+- Canonical scope: environment variables, default module lists, output schema
+  selection, `speakers.yml`, `autocorrect.yml`, path validation, and precedence.
+- Recommended outline: config surfaces; output schema precedence; merge module
+  defaults; environment variables; speaker map YAML; autocorrect YAML; path and
+  validation rules; links to examples.
+- Source of truth: `internal/config/config.go`, `internal/speaker/map.go`,
+  `internal/autocorrect/autocorrect.go`, `internal/config/config_test.go`,
+  `internal/speaker/map_test.go`, and `internal/autocorrect/autocorrect_test.go`.
+- Acceptance criteria: all config fields and `SERIATIM_*` env vars match code;
+  unsupported config files or unimplemented formats are not described.
+
+### `docs/operations.md`
+
+- Audience: administrators and operators.
+- Purpose: operational behavior for running commands safely.
+- Canonical scope: file workflow, filesystem layout expectations, output and
+  report files, retry behavior, cleanup, validation failures, and operational
+  caveats.
+- Recommended outline: normal workflow; input/output/report files; no durable
+  state; failure and retry behavior; reports and diagnostics; cleanup; privacy
+  considerations for transcript artifacts.
+- Source of truth: `cmd/seriatim/main.go`, `internal/cli`, `internal/config`,
+  `internal/report`, `internal/builtin/output.go`, `internal/normalize`, and
+  trim/merge/normalize CLI tests.
+- Acceptance criteria: clearly states there is no daemon, database, resume
+  state, remote storage, or background job state; does not invent recovery
+  workflows.
+
+### `docs/policy/development.md`
+
+- Audience: developers and coding agents.
+- Purpose: contributor workflow and change guidance.
+- Canonical scope: repository layout, build/test commands, coding conventions,
+  dependency policy, adding flags/config fields/modules/docs/examples.
+- Recommended outline: repo layout; local checks; coding conventions; adding
+  CLI flags; adding config/env vars; adding modules/stages; schema changes;
+  examples and documentation updates.
+- Source of truth: `docs/policy/documentation.md`,
+  `docs/policy/architecture.md`, `go.mod`, package layout, and test layout.
+- Acceptance criteria: includes `go test ./...`; states there is no current
+  Makefile, taskfile, linter config, or automated doc checker; aligns with the
+  architecture policy.
+
+### `docs/internal/pipeline.md`
+
+- Audience: developers and coding agents.
+- Purpose: implemented merge pipeline internals.
+- Canonical scope: registry, stage interfaces, preprocessing state transitions,
+  module order, report event accumulation, final output/report writing.
+- Recommended outline: purpose; inputs and outputs; stage contracts; registry
+  resolution; execution order; config fields used; adapters; failure behavior;
+  tests; invariants.
+- Source of truth: `internal/pipeline`, `internal/builtin`, `internal/model`,
+  `internal/report`, `internal/pipeline/runner_test.go`,
+  `internal/builtin/*_test.go`, and `internal/cli/merge_test.go`.
+- Acceptance criteria: describes only implemented sequential execution; does
+  not document concurrency, plugins, or future formats.
+
+### `docs/internal/artifacts.md`
+
+- Audience: developers and coding agents.
+- Purpose: public artifact conversion and validation internals.
+- Canonical scope: schema structs, embedded JSON Schemas, conversion from merged
+  model, trim/normalize artifact handling, and output validation.
+- Recommended outline: artifact contracts; schema selection; conversion;
+  validation; trim projection; normalize canonicalization; tests; invariants.
+- Source of truth: `schema`, `internal/artifact`, `internal/trim`,
+  `internal/normalize`, and related tests.
+- Acceptance criteria: links to `schema/*.schema.json`; does not duplicate full
+  schemas or describe unavailable output formats.
+
+### `docs/internal/modules.md`
+
+- Audience: developers and coding agents.
+- Purpose: implemented built-in module behavior and boundaries.
+- Canonical scope: `json-files`, preprocessing modules, chronological merge,
+  postprocessing modules, and JSON output writer.
+- Recommended outline: module list; inputs/outputs; config fields used; allowed
+  side effects; ordering constraints; failure behavior; tests; invariants.
+- Source of truth: `internal/builtin`, `internal/overlap`, `internal/coalesce`,
+  `internal/danglers`, `internal/backchannel`, `internal/filler`,
+  `internal/autocorrect`, and package tests.
+- Acceptance criteria: avoids full CLI/config duplication; identifies
+  order-sensitive transforms that must run before `assign-ids`.
+
+### `docs/troubleshooting.md`
+
+- Audience: users, administrators, and operators.
+- Purpose: common failure symptoms and safe fixes.
+- Canonical scope: implemented validation and runtime failures observed in
+  error paths and tests.
+- Recommended outline: invalid JSON/input shape; missing required flags; invalid
+  output parent directory; invalid speaker/autocorrect YAML; unknown module;
+  invalid output schema; invalid trim selector; schema validation failure;
+  report write failure.
+- Source of truth: `internal/config`, `internal/cli/*_test.go`,
+  `internal/trim/*_test.go`, `internal/normalize/*_test.go`,
+  `internal/speaker/*_test.go`, and `internal/autocorrect/*_test.go`.
+- Acceptance criteria: each entry has symptom, likely cause, inspection step,
+  safe fix, and link; no speculative failure modes.
+
+### `docs/integrations/whisperx-json.md`
+
+- Audience: developers and coding agents.
+- Purpose: external input JSON contract used by `merge`.
+- Canonical scope: the supported WhisperX-like subset only.
+- Recommended outline: top-level shape; required segment fields; optional word
+  timing fields; validation/failure behavior; how word timing affects overlap
+  resolution; links to CLI and examples.
+- Source of truth: `internal/builtin/input.go`, merge CLI tests, and README
+  input-format material.
+- Acceptance criteria: does not attempt to document full WhisperX behavior or
+  unsupported input formats.
+
+### `docs/integrations/output-schemas.md`
+
+- Audience: developers, coding agents, and artifact consumers.
+- Purpose: orientation to public JSON output contracts.
+- Canonical scope: minimal/intermediate/full schema roles and links to schema
+  files.
+- Recommended outline: schema selection; minimal; intermediate; full; semantic
+  invariants; validation APIs; links to `schema/*.schema.json`.
+- Source of truth: `schema/output.go`, `schema/*.schema.json`,
+  `schema/output_test.go`, and `internal/artifact`.
+- Acceptance criteria: links to machine-readable schemas instead of copying
+  them in full.
+
+### `examples/`
+
+- Audience: users, administrators, operators, developers, and coding agents.
+- Purpose: maintained copyable examples.
+- Canonical scope: small synthetic inputs and config files for implemented
+  commands only.
+- Source of truth: examples created during the documentation migration and
+  validated through actual command invocations.
+- Acceptance criteria: examples are valid, free of secrets/private transcript
+  data, and linked from README, CLI, config, and operations docs.
+
+## File-by-File Rewrite Guidance
+
+### README
+
+Cover what seriatim is, the shortest useful `merge` command, a brief command
+summary, and links to canonical docs. Avoid full flag tables, config/env
+reference, module internals, schema examples, troubleshooting details, future
+formats, or release-history narrative. Inspect `internal/cli`, `internal/config`,
+and CLI tests before updating commands.
+
+### CLI Reference
+
+Document actual `merge`, `trim`, and `normalize` flags from `internal/cli`.
+Include required flags, defaults, mutually exclusive selector rules, schema
+selection, report flags, and common workflows. Link to `docs/config.md` for
+environment variables and YAML formats. Avoid internal package explanations.
+Inspect `internal/cli/*_test.go` for edge cases and examples.
+
+### Config Reference
+
+Document all implemented config surfaces: flags that become config values,
+`SERIATIM_OUTPUT_SCHEMA`, `SERIATIM_OVERLAP_WORD_RUN_GAP`,
+`SERIATIM_OVERLAP_WORD_RUN_REORDER_WINDOW`,
+`SERIATIM_BACKCHANNEL_MAX_DURATION`, `SERIATIM_FILLER_MAX_DURATION`, module
+lists, output schemas, `speakers.yml`, and `autocorrect.yml`. Avoid command
+tutorials and unimplemented config files. Inspect `internal/config`,
+`internal/speaker`, `internal/autocorrect`, and tests.
+
+### Operations
+
+Document filesystem-only command execution, output/report artifacts, validation
+failures, retry behavior, and cleanup. Explicitly say there is no daemon,
+database, remote storage, resume state, or background job state. Avoid
+unimplemented recovery procedures.
+
+### Development Policy
+
+Document repository layout, `go test ./...`, package conventions,
+standard-library-first dependency guidance, how to add flags/config/modules,
+and documentation update expectations. State that no Makefile, taskfile,
+linter config, or automated documentation checker currently exists.
+
+### Internal Docs
+
+Keep internal docs behavior-level and concise. Describe implemented inputs,
+outputs, boundaries, config fields used, adapters, failure behavior, tests, and
+invariants. Avoid future plugins, future input/output formats, concurrency, or
+duplicating CLI/config reference material.
+
+### Root `architecture.md`
+
+Do not carry forward future input methods, future formats, future output
+formats, LLM text, dynamic plugin speculation, or interface sketches that
+diverge from code. Salvage only current-behavior details that are not already
+covered in `docs/policy/architecture.md` and move any legitimate future ideas
+under `docs/roadmap/`.
+
+## Examples Plan
+
+Create small synthetic examples under `examples/` rather than relying on the
+current large `samples/raw` data.
+
+- `examples/minimal-merge/`
+  - Purpose: shortest complete merge workflow with two small raw JSON files and
+    optional `speakers.yml`.
+  - Expected validity check: run `go run ./cmd/seriatim merge` with the example
+    files and validate JSON output is produced.
+  - Docs to link: README, `docs/cli.md`, `docs/config.md`,
+    `docs/operations.md`.
+- `examples/normalize/`
+  - Purpose: normalize object-with-`segments` and bare segment array inputs.
+  - Expected validity check: run `go run ./cmd/seriatim normalize` for both
+    shapes.
+  - Docs to link: `docs/cli.md`, `docs/operations.md`, and any Audita/bare
+    array integration note if created.
+- `examples/trim/`
+  - Purpose: trim a small existing seriatim artifact by `--keep` and/or
+    `--remove`.
+  - Expected validity check: run `go run ./cmd/seriatim trim` and validate
+    sequential retained IDs.
+  - Docs to link: `docs/cli.md`, `docs/operations.md`.
+- `examples/speakers.yml` and `examples/autocorrect.yml`
+  - Purpose: copyable YAML rule examples if linked from `docs/config.md`.
+  - Expected validity check: load through merge command or package tests.
+  - Docs to link: `docs/config.md`, `docs/cli.md`.
+
+Do not invent examples for unimplemented input methods, output formats,
+services, or plugin systems. Do not reuse `samples/raw` as public examples
+without privacy and size review.
+
+## Internal Documentation Plan
+
+### Pipeline
+
+- Path: `docs/internal/pipeline.md`
+- Purpose: document implemented merge pipeline orchestration.
+- Inputs and outputs: `config.Config`, raw transcripts, canonical transcripts,
+  merged transcript, selected public artifact, optional report.
+- Boundaries: registry and runner orchestration; no CLI flag parsing; no schema
+  details beyond output selection.
+- Config fields used: input reader, module lists, output modules, output schema,
+  input/output/report files, timing thresholds passed through modules.
+- Adapters used: input reader, output writer, report writer.
+- Failure behavior: unknown modules, invalid preprocessing state, stage errors,
+  output/report write failures.
+- Tests to inspect: `internal/pipeline/runner_test.go`,
+  `internal/builtin/*_test.go`, `internal/cli/merge_test.go`.
+- Architectural invariants: deterministic sequential stage order, explicit
+  raw-to-canonical preprocessing state, output validation before acceptance.
+
+### Artifacts and Schemas
+
+- Path: `docs/internal/artifacts.md`
+- Purpose: document public artifact conversion and validation internals.
+- Inputs and outputs: merged model, schema structs, serialized JSON artifacts,
+  parsed trim/normalize artifacts.
+- Boundaries: conversion and validation only; CLI docs own user-facing flags.
+- Config fields used: output schema, output modules, input files for metadata.
+- Adapters used: embedded JSON Schema files and JSON encoders/decoders.
+- Failure behavior: schema validation errors, unsupported artifact/schema
+  conversion, invalid IDs/timing.
+- Tests to inspect: `schema/output_test.go`,
+  `internal/artifact/transcript_test.go`, `internal/trim/*_test.go`,
+  `internal/normalize/*_test.go`.
+- Architectural invariants: sequential IDs, selected schema validation, no
+  internal-only fields in public schemas.
+
+### Built-In Modules
+
+- Path: `docs/internal/modules.md`
+- Purpose: document implemented module responsibilities and ordering
+  constraints.
+- Inputs and outputs: raw transcripts, preprocess state, merged transcript,
+  report events, selected JSON output.
+- Boundaries: module behavior only; no full CLI/config reference.
+- Config fields used: speaker file, autocorrect file, coalesce gap, overlap word
+  gap, word run reorder window, backchannel/filler max durations.
+- Adapters used: JSON input/output, speaker YAML, autocorrect YAML, report
+  events.
+- Failure behavior: input validation errors, invalid YAML, unknown module names,
+  invalid output schema before write.
+- Tests to inspect: `internal/builtin`, `internal/overlap`,
+  `internal/coalesce`, `internal/danglers`, `internal/backchannel`,
+  `internal/filler`, `internal/autocorrect`, and CLI merge tests.
+- Architectural invariants: order-sensitive transforms run before `assign-ids`;
+  modules stay narrow and explicitly configured.
+
+### Trim
+
+- Path: include in `docs/internal/artifacts.md` or create
+  `docs/internal/trim.md` if artifacts doc grows too large.
+- Purpose: document artifact-level segment projection.
+- Inputs and outputs: existing seriatim artifact, selector, selected output
+  schema, optional report.
+- Boundaries: no merge postprocessors; no raw WhisperX input.
+- Config fields used: input/output/report files, keep/remove selector,
+  optional output schema, allow-empty.
+- Adapters used: file I/O in CLI, artifact parsing/validation, report writer.
+- Failure behavior: malformed selector, invalid artifact, missing selected IDs,
+  non-sequential input IDs, empty output unless allowed, unsupported schema
+  up-conversion.
+- Tests to inspect: `internal/trim/*_test.go`, `internal/cli/trim_test.go`.
+- Architectural invariants: preserve transcript order, renumber retained IDs,
+  recompute full-schema overlap groups, never run merge modules.
+
+### Normalize
+
+- Path: include in `docs/internal/artifacts.md` or create
+  `docs/internal/normalize.md` if artifacts doc grows too large.
+- Purpose: document artifact-level transcript canonicalization.
+- Inputs and outputs: transcript-like JSON object or bare array, selected
+  seriatim output schema, optional report.
+- Boundaries: no merge preprocessing or postprocessing modules.
+- Config fields used: input/output/report files, output schema, output modules.
+- Adapters used: file I/O, JSON parsing, schema validation, report writer.
+- Failure behavior: invalid JSON, unsupported top-level shape, invalid timing
+  after repair, unsupported output module/schema, report write failure.
+- Tests to inspect: `internal/normalize/*_test.go`,
+  `internal/cli/normalize_test.go`.
+- Architectural invariants: deterministic repair/sort/ID assignment, no
+  transcript text in normalize report events, no merge modules.
+
+## Integration Documentation Plan
+
+- `docs/integrations/whisperx-json.md`
+  - External system or contract: WhisperX-like JSON transcript subset.
+  - Current usage: `merge` reads a top-level `segments` array with required
+    segment timing/text and optional word timing.
+  - Version or compatibility notes: no explicit WhisperX version is encoded in
+    the repository; document only the accepted subset.
+  - Document: supported fields, validation, word timing behavior, errors.
+  - Do not document: full WhisperX schema, audio diarization, non-JSON formats.
+- `docs/integrations/output-schemas.md`
+  - External system or contract: seriatim public JSON output contracts.
+  - Current usage: `merge`, `trim`, and `normalize` emit
+    `seriatim-minimal`, `seriatim-intermediate`, or `seriatim-full`.
+  - Version or compatibility notes: schemas are embedded from `schema/`; release
+    version metadata is injected through build info.
+  - Document: schema roles, semantic invariants, validation APIs, links to
+    schema files.
+  - Do not document: unimplemented output formats or full schema copies.
+- YAML rule files
+  - Prefer documenting speaker and autocorrect YAML contracts in
+    `docs/config.md`. Create `docs/integrations/yaml-rule-files.md` only if the
+    config reference becomes too large.
+- Audita-style bare arrays
+  - Cover under `docs/cli.md` normalize behavior unless maintainers need a
+    separate integration note. Do not generalize beyond implemented bare segment
+    arrays.
+- No external CLI/API/service docs are needed now. The repository implements no
+  external CLI, network API, daemon, remote storage, or service integration.
+
+## Recommended Implementation Sequence
+
+### Stage 1: Write Documentation Roadmap
+
+- Goal: create this roadmap.
+- Files: `docs/roadmap/documentation.md`.
+- Repository areas to inspect: documentation policy, architecture policy,
+  README, root `architecture.md`, CLI/config/pipeline/schema/report/tests.
+- Acceptance criteria: roadmap exists, no other files changed by this stage,
+  and the roadmap is action-oriented.
+- Suggested validation commands: `go test ./...`; `git status --short`.
+- Prompt size: one implementation prompt.
+
+### Stage 2: User-Facing Canonical Docs and Slim README
+
+- Goal: move user reference material out of README into canonical docs.
+- Files: update `README.md`; create `docs/cli.md` and `docs/config.md`.
+- Repository areas to inspect: `internal/cli`, `internal/config`,
+  `internal/speaker`, `internal/autocorrect`, CLI/config tests.
+- Acceptance criteria: README is concise; CLI/config docs match flags, defaults,
+  env vars, YAML formats, and validation; no roadmap-only content appears.
+- Suggested validation commands: `go test ./...`;
+  `go run ./cmd/seriatim --help`;
+  `go run ./cmd/seriatim merge --help`;
+  `go run ./cmd/seriatim trim --help`;
+  `go run ./cmd/seriatim normalize --help`;
+  stale-term grep from the validation plan.
+- Prompt size: one prompt if concise; split if README rewrite or config
+  reference grows too large.
+
+### Stage 3: Operations and Troubleshooting
+
+- Goal: document runtime operation, reports, failure behavior, and common fixes.
+- Files: create `docs/operations.md` and `docs/troubleshooting.md`.
+- Repository areas to inspect: `cmd/seriatim/main.go`, `internal/cli`,
+  `internal/config`, `internal/report`, output writer, normalize/trim/merge
+  tests.
+- Acceptance criteria: docs describe filesystem-only operation and current
+  failure modes; no daemon, resume, remote storage, or recovery behavior is
+  invented.
+- Suggested validation commands: `go test ./...`; manual link review.
+- Prompt size: one prompt.
+
+### Stage 4: Developer and Internal Docs
+
+- Goal: create developer workflow and implemented internal component docs.
+- Files: create `docs/policy/development.md`,
+  `docs/internal/pipeline.md`, `docs/internal/artifacts.md`, and
+  `docs/internal/modules.md`.
+- Repository areas to inspect: architecture policy, pipeline, modules, schema,
+  artifact conversion, trim/normalize packages, tests.
+- Acceptance criteria: docs preserve boundaries, avoid CLI/config duplication,
+  and identify tests/invariants for future changes.
+- Suggested validation commands: `go test ./...`; grep for unimplemented
+  future-format/plugin/concurrency claims outside roadmap.
+- Prompt size: split into development policy and internal docs if needed.
+
+### Stage 5: Integrations and Examples
+
+- Goal: add concise integration notes and maintained synthetic examples.
+- Files: create `docs/integrations/whisperx-json.md`,
+  `docs/integrations/output-schemas.md`, and `examples/*`; decide whether
+  `samples/` should remain separate.
+- Repository areas to inspect: `internal/builtin/input.go`, `schema`,
+  `internal/artifact`, CLI tests, existing `samples/`.
+- Acceptance criteria: examples are small, synthetic, valid, and linked from
+  relevant docs; integration docs document only implemented contracts.
+- Suggested validation commands: `go test ./...`; run documented example
+  `go run` commands; validate example YAML through command paths.
+- Prompt size: split if examples need tests or sample cleanup decisions.
+
+### Stage 6: Stale Documentation Cleanup
+
+- Goal: remove wrong-home and stale documentation after canonical replacements
+  exist.
+- Files: delete or relocate root `architecture.md`; remove stale material from
+  README; update links across docs.
+- Repository areas to inspect: all docs, README, roadmap, root files.
+- Acceptance criteria: no links to deleted root `architecture.md`; no
+  unimplemented behavior outside `docs/roadmap/`; canonical homes are respected.
+- Suggested validation commands: `go test ./...`; stale-term grep; manual link
+  check; `git status --short`.
+- Prompt size: one prompt.
+
+## Validation Plan
+
+Use these checks during or after documentation migration:
+
+- Run `go test ./...`.
+- Run `go run ./cmd/seriatim --help`.
+- Run `go run ./cmd/seriatim merge --help`.
+- Run `go run ./cmd/seriatim trim --help`.
+- Run `go run ./cmd/seriatim normalize --help`.
+- Once examples exist, run each documented example command and verify output is
+  produced in a temporary path.
+- Load example YAML through the merge command or package tests.
+- Validate example JSON through existing CLI/schema paths where practical.
+- Grep outside `docs/roadmap/` for stale or roadmap-only terms:
+  `Future input`, `Future output`, `LLM`, `plugin`, `SRT`, `VTT`, `.tar.gz`,
+  `URI`, `old format`, `not implemented yet`, and
+  `runtime default may change`.
+- Manually check links unless a link checker is added. No automated
+  documentation checker currently exists.
+- Verify docs and examples contain no secrets, private transcript data, API
+  keys, tokens, passwords, or private infrastructure details.
+
+## Open Questions
+
+- Should `samples/` be removed, kept as non-doc sample data, or replaced by
+  small synthetic `examples/`? Recommendation: create small synthetic examples
+  first, then audit `samples/` for privacy, size, and ongoing maintenance before
+  deleting or linking it.
+- Should Audita-style bare-array normalization have a separate integration doc?
+  Recommendation: cover it in `docs/cli.md` normalize behavior unless a
+  stronger external-contract requirement emerges.

internal/cli/normalize.go

@@ -0,0 +1,39 @@
+package cli
+
+import (
+	"github.com/spf13/cobra"
+
+	"gitea.maximumdirect.net/eric/seriatim/internal/config"
+	"gitea.maximumdirect.net/eric/seriatim/internal/normalize"
+)
+
+func newNormalizeCommand() *cobra.Command {
+	var opts config.NormalizeOptions
+
+	cmd := &cobra.Command{
+		Use:   "normalize",
+		Short: "Normalize a transcript artifact into a standard seriatim output shape",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			normalizeOpts := opts
+			if !cmd.Flags().Changed("output-schema") {
+				normalizeOpts.OutputSchema = ""
+			}
+
+			cfg, err := config.NewNormalizeConfig(normalizeOpts)
+			if err != nil {
+				return err
+			}
+
+			return normalize.Run(cmd.Context(), cfg)
+		},
+	}
+
+	flags := cmd.Flags()
+	flags.StringVar(&opts.InputFile, "input-file", "", "input transcript JSON file")
+	flags.StringVar(&opts.OutputFile, "output-file", "", "output transcript JSON file")
+	flags.StringVar(&opts.ReportFile, "report-file", "", "optional report JSON file")
+	flags.StringVar(&opts.OutputSchema, "output-schema", config.DefaultOutputSchema, "output JSON schema: seriatim-minimal, seriatim-intermediate, or seriatim-full")
+	flags.StringVar(&opts.OutputModules, "output-modules", config.DefaultOutputModules, "comma-separated output modules")
+
+	return cmd
+}

internal/cli/normalize_test.go

@@ -0,0 +1,522 @@
+package cli
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/seriatim/internal/config"
+	"gitea.maximumdirect.net/eric/seriatim/internal/report"
+	"gitea.maximumdirect.net/eric/seriatim/schema"
+)
+
+func TestNormalizeCommandIsRecognized(t *testing.T) {
+	cmd := NewRootCommand()
+	cmd.SetArgs([]string{"normalize", "--help"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("normalize command should be recognized: %v", err)
+	}
+}
+
+func TestNormalizeMissingInputFileFails(t *testing.T) {
+	dir := t.TempDir()
+	output := filepath.Join(dir, "normalized.json")
+
+	err := executeNormalize(
+		"--output-file", output,
+	)
+	if err == nil {
+		t.Fatal("expected missing input-file error")
+	}
+	if !strings.Contains(err.Error(), "--input-file is required") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestNormalizeMissingOutputFileFails(t *testing.T) {
+	dir := t.TempDir()
+	input := writeJSONFile(t, dir, "input.json", `{"segments":[]}`)
+
+	err := executeNormalize(
+		"--input-file", input,
+	)
+	if err == nil {
+		t.Fatal("expected missing output-file error")
+	}
+	if !strings.Contains(err.Error(), "--output-file is required") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestNormalizeInvalidOutputSchemaFails(t *testing.T) {
+	dir := t.TempDir()
+	input := writeJSONFile(t, dir, "input.json", `{"segments":[]}`)
+	output := filepath.Join(dir, "normalized.json")
+
+	err := executeNormalize(
+		"--input-file", input,
+		"--output-file", output,
+		"--output-schema", "compact",
+	)
+	if err == nil {
+		t.Fatal("expected invalid output schema error")
+	}
+	if !strings.Contains(err.Error(), "--output-schema must be one of") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestNormalizeInvalidOutputModuleFails(t *testing.T) {
+	dir := t.TempDir()
+	input := writeJSONFile(t, dir, "input.json", `{"segments":[]}`)
+	output := filepath.Join(dir, "normalized.json")
+
+	err := executeNormalize(
+		"--input-file", input,
+		"--output-file", output,
+		"--output-modules", "yaml",
+	)
+	if err == nil {
+		t.Fatal("expected invalid output module error")
+	}
+	if !strings.Contains(err.Error(), "unknown output module") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestNormalizeDefaultOutputSchemaIsIntermediate(t *testing.T) {
+	dir := t.TempDir()
+	input := writeJSONFile(t, dir, "input.json", `{
+		"segments": [
+			{"id": 99, "start": 5, "end": 6, "speaker": "Bob", "text": "second", "categories": ["filler"]},
+			{"id": 10, "start": 1, "end": 2, "speaker": "Alice", "text": "first", "categories": ["backchannel"]}
+		]
+	}`)
+	output := filepath.Join(dir, "normalized.json")
+
+	err := executeNormalize(
+		"--input-file", input,
+		"--output-file", output,
+	)
+	if err != nil {
+		t.Fatalf("normalize failed: %v", err)
+	}
+
+	var transcript schema.IntermediateTranscript
+	readJSON(t, output, &transcript)
+	if transcript.Metadata.OutputSchema != config.OutputSchemaIntermediate {
+		t.Fatalf("output schema = %q, want %q", transcript.Metadata.OutputSchema, config.OutputSchemaIntermediate)
+	}
+	if len(transcript.Segments) != 2 {
+		t.Fatalf("segment count = %d, want 2", len(transcript.Segments))
+	}
+	if transcript.Segments[0].ID != 1 || transcript.Segments[1].ID != 2 {
+		t.Fatalf("segment IDs = %d,%d, want 1,2", transcript.Segments[0].ID, transcript.Segments[1].ID)
+	}
+	if transcript.Segments[0].Text != "first" || transcript.Segments[1].Text != "second" {
+		t.Fatalf("unexpected sort order: %#v", transcript.Segments)
+	}
+	if len(transcript.Segments[0].Categories) != 1 || transcript.Segments[0].Categories[0] != "backchannel" {
+		t.Fatalf("expected categories preserved on first segment, got %#v", transcript.Segments[0].Categories)
+	}
+}
+
+func TestNormalizeBareArrayInputToIntermediateOutput(t *testing.T) {
+	dir := t.TempDir()
+	input := writeJSONFile(t, dir, "input.json", `[
+		{"start": 2, "end": 3, "speaker": "Bob", "text": "second"},
+		{"start": 1, "end": 2, "speaker": "Alice", "text": "first"}
+	]`)
+	output := filepath.Join(dir, "normalized.json")
+
+	err := executeNormalize(
+		"--input-file", input,
+		"--output-file", output,
+		"--output-schema", config.OutputSchemaIntermediate,
+	)
+	if err != nil {
+		t.Fatalf("normalize failed: %v", err)
+	}
+
+	var transcript schema.IntermediateTranscript
+	readJSON(t, output, &transcript)
+	if len(transcript.Segments) != 2 {
+		t.Fatalf("segment count = %d, want 2", len(transcript.Segments))
+	}
+	if transcript.Segments[0].Speaker != "Alice" || transcript.Segments[1].Speaker != "Bob" {
+		t.Fatalf("unexpected sorted speakers: %#v", transcript.Segments)
+	}
+}
+
+func TestNormalizeInputIndexTieBreakerIsDeterministic(t *testing.T) {
+	dir := t.TempDir()
+	input := writeJSONFile(t, dir, "input.json", `[
+		{"start": 1, "end": 2, "speaker": "Zulu", "text": "first in"},
+		{"start": 1, "end": 2, "speaker": "Alpha", "text": "second in"}
+	]`)
+	output := filepath.Join(dir, "normalized.json")
+
+	err := executeNormalize(
+		"--input-file", input,
+		"--output-file", output,
+	)
+	if err != nil {
+		t.Fatalf("normalize failed: %v", err)
+	}
+
+	var transcript schema.IntermediateTranscript
+	readJSON(t, output, &transcript)
+	if transcript.Segments[0].Speaker != "Zulu" || transcript.Segments[1].Speaker != "Alpha" {
+		t.Fatalf("tie-break order mismatch: %#v", transcript.Segments)
+	}
+}
+
+func TestNormalizeMinimalSchemaOmitsCategories(t *testing.T) {
+	dir := t.TempDir()
+	input := writeJSONFile(t, dir, "input.json", `{
+		"segments": [
+			{"start": 1, "end": 2, "speaker": "Alice", "text": "first", "categories": ["filler"]}
+		]
+	}`)
+	output := filepath.Join(dir, "normalized.json")
+
+	err := executeNormalize(
+		"--input-file", input,
+		"--output-file", output,
+		"--output-schema", config.OutputSchemaMinimal,
+	)
+	if err != nil {
+		t.Fatalf("normalize failed: %v", err)
+	}
+
+	var transcript schema.MinimalTranscript
+	readJSON(t, output, &transcript)
+	if transcript.Metadata.OutputSchema != config.OutputSchemaMinimal {
+		t.Fatalf("output schema = %q, want %q", transcript.Metadata.OutputSchema, config.OutputSchemaMinimal)
+	}
+	if len(transcript.Segments) != 1 || transcript.Segments[0].ID != 1 {
+		t.Fatalf("unexpected minimal output: %#v", transcript.Segments)
+	}
+	bytes, readErr := os.ReadFile(output)
+	if readErr != nil {
+		t.Fatalf("read output: %v", readErr)
+	}
+	if strings.Contains(string(bytes), "categories") {
+		t.Fatalf("minimal output unexpectedly contains categories:\n%s", string(bytes))
+	}
+}
+
+func TestNormalizeFullSchemaOutputValidatesAndHasProvenanceFallback(t *testing.T) {
+	dir := t.TempDir()
+	input := writeJSONFile(t, dir, "input.json", `[
+		{"start": 1, "end": 2, "speaker": "Alice", "text": "first"},
+		{"start": 3, "end": 4, "speaker": "Bob", "text": "second", "source":"custom.json", "source_segment_index": 7}
+	]`)
+	output := filepath.Join(dir, "normalized.json")
+
+	err := executeNormalize(
+		"--input-file", input,
+		"--output-file", output,
+		"--output-schema", config.OutputSchemaFull,
+	)
+	if err != nil {
+		t.Fatalf("normalize failed: %v", err)
+	}
+
+	var transcript schema.Transcript
+	readJSON(t, output, &transcript)
+	if err := schema.ValidateTranscript(transcript); err != nil {
+		t.Fatalf("full output should validate: %v", err)
+	}
+	if len(transcript.Segments) != 2 {
+		t.Fatalf("segment count = %d, want 2", len(transcript.Segments))
+	}
+	if transcript.Segments[0].Source != filepath.Base(input) {
+		t.Fatalf("source fallback = %q, want %q", transcript.Segments[0].Source, filepath.Base(input))
+	}
+	if transcript.Segments[0].SourceSegmentIndex == nil || *transcript.Segments[0].SourceSegmentIndex != 0 {
+		t.Fatalf("source_segment_index fallback = %v, want 0", transcript.Segments[0].SourceSegmentIndex)
+	}
+	if transcript.Segments[1].Source != "custom.json" {
+		t.Fatalf("explicit source preserved = %q, want custom.json", transcript.Segments[1].Source)
+	}
+	if transcript.Segments[1].SourceSegmentIndex == nil || *transcript.Segments[1].SourceSegmentIndex != 7 {
+		t.Fatalf("explicit source_segment_index preserved = %v, want 7", transcript.Segments[1].SourceSegmentIndex)
+	}
+	if transcript.OverlapGroups == nil || len(transcript.OverlapGroups) != 0 {
+		t.Fatalf("overlap_groups = %#v, want empty array", transcript.OverlapGroups)
+	}
+}
+
+func TestNormalizeEmptySegmentsArrayProducesValidOutput(t *testing.T) {
+	dir := t.TempDir()
+	input := writeJSONFile(t, dir, "input.json", `{"segments":[]}`)
+	output := filepath.Join(dir, "normalized.json")
+
+	err := executeNormalize(
+		"--input-file", input,
+		"--output-file", output,
+	)
+	if err != nil {
+		t.Fatalf("normalize failed: %v", err)
+	}
+
+	var transcript schema.IntermediateTranscript
+	readJSON(t, output, &transcript)
+	if len(transcript.Segments) != 0 {
+		t.Fatalf("segment count = %d, want 0", len(transcript.Segments))
+	}
+	if err := schema.ValidateIntermediateTranscript(transcript); err != nil {
+		t.Fatalf("intermediate output should validate: %v", err)
+	}
+}
+
+func TestNormalizeRepairsAndDropsDefectiveSegments(t *testing.T) {
+	dir := t.TempDir()
+	input := writeJSONFile(t, dir, "input.json", `[
+		{"start": 5, "speaker": "", "text": "keep-a"},
+		{"end": 3, "speaker": "  ", "text": "keep-b"},
+		{"speaker": "A"},
+		{"speaker": "A", "text": "   "},
+		{"start": 9, "end": 4, "speaker": "B", "text": "keep-c"}
+	]`)
+	output := filepath.Join(dir, "normalized.json")
+	reportPath := filepath.Join(dir, "report.json")
+
+	err := executeNormalize(
+		"--input-file", input,
+		"--output-file", output,
+		"--report-file", reportPath,
+		"--output-schema", config.OutputSchemaIntermediate,
+	)
+	if err != nil {
+		t.Fatalf("normalize failed: %v", err)
+	}
+
+	var transcript schema.IntermediateTranscript
+	readJSON(t, output, &transcript)
+	if len(transcript.Segments) != 3 {
+		t.Fatalf("segment count = %d, want 3", len(transcript.Segments))
+	}
+	if transcript.Segments[0].Start != 3 || transcript.Segments[0].End != 3 {
+		t.Fatalf("segment[0] timing = %v..%v, want 3..3", transcript.Segments[0].Start, transcript.Segments[0].End)
+	}
+	if transcript.Segments[1].Start != 4 || transcript.Segments[1].End != 9 {
+		t.Fatalf("segment[1] timing = %v..%v, want 4..9", transcript.Segments[1].Start, transcript.Segments[1].End)
+	}
+	if transcript.Segments[2].Start != 5 || transcript.Segments[2].End != 5 {
+		t.Fatalf("segment[2] timing = %v..%v, want 5..5", transcript.Segments[2].Start, transcript.Segments[2].End)
+	}
+	if transcript.Segments[0].Speaker != "Unknown_Speaker" || transcript.Segments[2].Speaker != "Unknown_Speaker" {
+		t.Fatalf("expected Unknown_Speaker placeholders, got %#v", transcript.Segments)
+	}
+
+	var rpt report.Report
+	readJSON(t, reportPath, &rpt)
+	audit := extractNormalizeAudit(t, rpt)
+	if audit.InputSegmentCount != 5 || audit.OutputSegmentCount != 3 {
+		t.Fatalf("audit counts = in:%d out:%d, want in:5 out:3", audit.InputSegmentCount, audit.OutputSegmentCount)
+	}
+	if audit.TimingFieldsRepaired != 2 {
+		t.Fatalf("timing fields repaired = %d, want 2", audit.TimingFieldsRepaired)
+	}
+	if audit.TimingOrderSwapped != 1 {
+		t.Fatalf("timing order swapped = %d, want 1", audit.TimingOrderSwapped)
+	}
+	if audit.SpeakerFilled != 2 {
+		t.Fatalf("speaker filled = %d, want 2", audit.SpeakerFilled)
+	}
+	if audit.SegmentsDroppedText != 2 {
+		t.Fatalf("segments dropped text = %d, want 2", audit.SegmentsDroppedText)
+	}
+}
+
+func TestNormalizeSelectedOutputSchemaIsHonored(t *testing.T) {
+	dir := t.TempDir()
+	input := writeJSONFile(t, dir, "input.json", `{"segments":[{"start":1,"end":2,"speaker":"A","text":"one"}]}`)
+	output := filepath.Join(dir, "normalized.json")
+
+	err := executeNormalize(
+		"--input-file", input,
+		"--output-file", output,
+		"--output-schema", config.OutputSchemaMinimal,
+	)
+	if err != nil {
+		t.Fatalf("normalize failed: %v", err)
+	}
+
+	var transcript schema.MinimalTranscript
+	readJSON(t, output, &transcript)
+	if transcript.Metadata.OutputSchema != config.OutputSchemaMinimal {
+		t.Fatalf("output schema = %q, want %q", transcript.Metadata.OutputSchema, config.OutputSchemaMinimal)
+	}
+}
+
+func TestNormalizeReportFileWrittenAndContainsObjectInputShape(t *testing.T) {
+	dir := t.TempDir()
+	input := writeJSONFile(t, dir, "input.json", `{"segments":[{"start":1,"end":2,"speaker":"A","text":"one"}]}`)
+	output := filepath.Join(dir, "normalized.json")
+	reportPath := filepath.Join(dir, "report.json")
+
+	err := executeNormalize(
+		"--input-file", input,
+		"--output-file", output,
+		"--report-file", reportPath,
+	)
+	if err != nil {
+		t.Fatalf("normalize failed: %v", err)
+	}
+
+	var rpt report.Report
+	readJSON(t, reportPath, &rpt)
+	audit := extractNormalizeAudit(t, rpt)
+	if audit.InputShape != "object_with_segments" {
+		t.Fatalf("input shape = %q, want object_with_segments", audit.InputShape)
+	}
+	if audit.InputSegmentCount != 1 {
+		t.Fatalf("input segment count = %d, want 1", audit.InputSegmentCount)
+	}
+	if audit.OutputSchema != config.OutputSchemaIntermediate {
+		t.Fatalf("output schema = %q, want %q", audit.OutputSchema, config.OutputSchemaIntermediate)
+	}
+	if len(audit.OutputModules) != 1 || audit.OutputModules[0] != "json" {
+		t.Fatalf("output modules = %v, want [json]", audit.OutputModules)
+	}
+}
+
+func TestNormalizeReportIncludesBareArrayShape(t *testing.T) {
+	dir := t.TempDir()
+	input := writeJSONFile(t, dir, "input.json", `[{"start":1,"end":2,"speaker":"A","text":"one"}]`)
+	output := filepath.Join(dir, "normalized.json")
+	reportPath := filepath.Join(dir, "report.json")
+
+	err := executeNormalize(
+		"--input-file", input,
+		"--output-file", output,
+		"--report-file", reportPath,
+	)
+	if err != nil {
+		t.Fatalf("normalize failed: %v", err)
+	}
+
+	var rpt report.Report
+	readJSON(t, reportPath, &rpt)
+	audit := extractNormalizeAudit(t, rpt)
+	if audit.InputShape != "bare_segments_array" {
+		t.Fatalf("input shape = %q, want bare_segments_array", audit.InputShape)
+	}
+}
+
+func TestNormalizeReportDoesNotIncludeTranscriptText(t *testing.T) {
+	dir := t.TempDir()
+	const segmentText = "normalize-report-secret-text"
+	input := writeJSONFile(t, dir, "input.json", `[{"start":1,"end":2,"speaker":"A","text":"`+segmentText+`"}]`)
+	output := filepath.Join(dir, "normalized.json")
+	reportPath := filepath.Join(dir, "report.json")
+
+	err := executeNormalize(
+		"--input-file", input,
+		"--output-file", output,
+		"--report-file", reportPath,
+	)
+	if err != nil {
+		t.Fatalf("normalize failed: %v", err)
+	}
+
+	var rpt report.Report
+	readJSON(t, reportPath, &rpt)
+	for _, event := range rpt.Events {
+		if strings.Contains(event.Message, segmentText) {
+			t.Fatalf("report unexpectedly contained transcript text in event %#v", event)
+		}
+	}
+}
+
+func TestNormalizeReportEmptyInputEmitsWarning(t *testing.T) {
+	dir := t.TempDir()
+	input := writeJSONFile(t, dir, "input.json", `{"segments":[]}`)
+	output := filepath.Join(dir, "normalized.json")
+	reportPath := filepath.Join(dir, "report.json")
+
+	err := executeNormalize(
+		"--input-file", input,
+		"--output-file", output,
+		"--report-file", reportPath,
+	)
+	if err != nil {
+		t.Fatalf("normalize failed: %v", err)
+	}
+
+	var rpt report.Report
+	readJSON(t, reportPath, &rpt)
+	found := false
+	for _, event := range rpt.Events {
+		if event.Stage == "normalize" && event.Module == "normalize" && event.Severity == report.SeverityWarning &&
+			strings.Contains(event.Message, "zero segments") {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Fatalf("expected empty transcript warning event, got %#v", rpt.Events)
+	}
+}
+
+func TestNormalizeReportWriteFailureReturnsClearError(t *testing.T) {
+	dir := t.TempDir()
+	input := writeJSONFile(t, dir, "input.json", `{"segments":[{"start":1,"end":2,"speaker":"A","text":"one"}]}`)
+	output := filepath.Join(dir, "normalized.json")
+
+	err := executeNormalize(
+		"--input-file", input,
+		"--output-file", output,
+		"--report-file", dir,
+	)
+	if err == nil {
+		t.Fatal("expected report write failure")
+	}
+	if !strings.Contains(err.Error(), "write --report-file") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func executeNormalize(args ...string) error {
+	cmd := NewRootCommand()
+	cmd.SetArgs(append([]string{"normalize"}, args...))
+	return cmd.Execute()
+}
+
+type normalizeAudit struct {
+	Command                string   `json:"command"`
+	InputFile              string   `json:"input_file"`
+	OutputFile             string   `json:"output_file"`
+	InputShape             string   `json:"input_shape"`
+	InputSegmentCount      int      `json:"input_segment_count"`
+	OutputSegmentCount     int      `json:"output_segment_count"`
+	OutputSchema           string   `json:"output_schema"`
+	OutputModules          []string `json:"output_modules"`
+	IDsReassigned          bool     `json:"ids_reassigned"`
+	SortingChangedInput    bool     `json:"sorting_changed_input_order"`
+	SegmentsWithCategories int      `json:"segments_with_categories"`
+	TimingFieldsRepaired   int      `json:"timing_fields_repaired"`
+	TimingOrderSwapped     int      `json:"timing_order_swapped"`
+	SpeakerFilled          int      `json:"speaker_filled"`
+	SegmentsDroppedText    int      `json:"segments_dropped_text"`
+}
+
+func extractNormalizeAudit(t *testing.T, rpt report.Report) normalizeAudit {
+	t.Helper()
+	for _, event := range rpt.Events {
+		if event.Stage == "normalize" && event.Module == "normalize-audit" {
+			var audit normalizeAudit
+			if err := json.Unmarshal([]byte(event.Message), &audit); err != nil {
+				t.Fatalf("decode normalize audit: %v", err)
+			}
+			return audit
+		}
+	}
+	t.Fatalf("missing normalize-audit event: %#v", rpt.Events)
+	return normalizeAudit{}
+}

internal/cli/root.go

@@ -10,13 +10,14 @@ import (
 func NewRootCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:           "seriatim",
-		Short:         "Merge per-speaker transcripts into a chronological transcript",
+		Short:         "Merge, trim, and normalize transcript artifacts",
 		Version:       buildinfo.Version,
 		SilenceErrors: true,
 		SilenceUsage:  true,
 	}
 
 	cmd.AddCommand(newMergeCommand())
+	cmd.AddCommand(newNormalizeCommand())
 	cmd.AddCommand(newTrimCommand())
 	return cmd
 }

internal/config/config.go

@@ -58,6 +58,15 @@ type TrimOptions struct {
 	AllowEmpty   bool
 }
 
+// NormalizeOptions captures raw CLI option values before validation.
+type NormalizeOptions struct {
+	InputFile     string
+	OutputFile    string
+	ReportFile    string
+	OutputSchema  string
+	OutputModules string
+}
+
 // Config is the validated runtime configuration for a merge invocation.
 type Config struct {
 	InputFiles             []string
@@ -88,6 +97,15 @@ type TrimConfig struct {
 	AllowEmpty   bool
 }
 
+// NormalizeConfig is the validated runtime configuration for a normalize invocation.
+type NormalizeConfig struct {
+	InputFile     string
+	OutputFile    string
+	ReportFile    string
+	OutputSchema  string
+	OutputModules []string
+}
+
 // NewMergeConfig validates raw merge options and returns normalized config.
 func NewMergeConfig(opts MergeOptions) (Config, error) {
 	cfg := Config{
@@ -247,6 +265,54 @@ func NewTrimConfig(opts TrimOptions) (TrimConfig, error) {
 	}, nil
 }
 
+// NewNormalizeConfig validates raw normalize options and returns normalized config.
+func NewNormalizeConfig(opts NormalizeOptions) (NormalizeConfig, error) {
+	inputFile := filepath.Clean(strings.TrimSpace(opts.InputFile))
+	if strings.TrimSpace(opts.InputFile) == "" {
+		return NormalizeConfig{}, errors.New("--input-file is required")
+	}
+	if err := requireFile(inputFile, "--input-file"); err != nil {
+		return NormalizeConfig{}, err
+	}
+
+	outputFile, err := normalizeOutputPath(opts.OutputFile, "--output-file")
+	if err != nil {
+		return NormalizeConfig{}, err
+	}
+
+	reportFile := ""
+	if strings.TrimSpace(opts.ReportFile) != "" {
+		reportFile, err = normalizeOutputPath(opts.ReportFile, "--report-file")
+		if err != nil {
+			return NormalizeConfig{}, err
+		}
+	}
+
+	outputSchema, err := resolveOutputSchema(opts.OutputSchema)
+	if err != nil {
+		return NormalizeConfig{}, err
+	}
+
+	outputModules, err := parseModuleList(opts.OutputModules)
+	if err != nil {
+		return NormalizeConfig{}, fmt.Errorf("--output-modules: %w", err)
+	}
+	if len(outputModules) == 0 {
+		return NormalizeConfig{}, errors.New("--output-modules must include at least one module")
+	}
+	if err := validateNormalizeOutputModules(outputModules); err != nil {
+		return NormalizeConfig{}, err
+	}
+
+	return NormalizeConfig{
+		InputFile:     inputFile,
+		OutputFile:    outputFile,
+		ReportFile:    reportFile,
+		OutputSchema:  outputSchema,
+		OutputModules: outputModules,
+	}, nil
+}
+
 func parseModuleList(value string) ([]string, error) {
 	value = strings.TrimSpace(value)
 	if value == "" {
@@ -400,3 +466,12 @@ func contains(values []string, target string) bool {
 	}
 	return false
 }
+
+func validateNormalizeOutputModules(modules []string) error {
+	for _, module := range modules {
+		if module != "json" {
+			return fmt.Errorf("unknown output module %q", module)
+		}
+	}
+	return nil
+}

internal/config/config_test.go

@@ -711,6 +711,107 @@ func TestNewTrimConfigRejectsInvalidOutputSchemaOverride(t *testing.T) {
 	}
 }
 
+func TestNewNormalizeConfigRequiresInputFile(t *testing.T) {
+	dir := t.TempDir()
+	output := filepath.Join(dir, "normalized.json")
+
+	_, err := NewNormalizeConfig(NormalizeOptions{
+		OutputFile:    output,
+		OutputModules: DefaultOutputModules,
+	})
+	if err == nil {
+		t.Fatal("expected input-file required error")
+	}
+	if !strings.Contains(err.Error(), "--input-file is required") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestNewNormalizeConfigRequiresOutputFile(t *testing.T) {
+	dir := t.TempDir()
+	input := writeTempFile(t, dir, "input.json")
+
+	_, err := NewNormalizeConfig(NormalizeOptions{
+		InputFile:     input,
+		OutputModules: DefaultOutputModules,
+	})
+	if err == nil {
+		t.Fatal("expected output-file required error")
+	}
+	if !strings.Contains(err.Error(), "--output-file is required") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestNewNormalizeConfigResolvesOutputSchemaDefaultAndEnv(t *testing.T) {
+	dir := t.TempDir()
+	input := writeTempFile(t, dir, "input.json")
+	output := filepath.Join(dir, "normalized.json")
+
+	t.Setenv(OutputSchemaEnv, "")
+	cfg, err := NewNormalizeConfig(NormalizeOptions{
+		InputFile:     input,
+		OutputFile:    output,
+		OutputModules: DefaultOutputModules,
+	})
+	if err != nil {
+		t.Fatalf("config failed: %v", err)
+	}
+	if cfg.OutputSchema != DefaultOutputSchema {
+		t.Fatalf("output schema = %q, want %q", cfg.OutputSchema, DefaultOutputSchema)
+	}
+
+	t.Setenv(OutputSchemaEnv, OutputSchemaMinimal)
+	cfg, err = NewNormalizeConfig(NormalizeOptions{
+		InputFile:     input,
+		OutputFile:    output,
+		OutputModules: DefaultOutputModules,
+	})
+	if err != nil {
+		t.Fatalf("config failed: %v", err)
+	}
+	if cfg.OutputSchema != OutputSchemaMinimal {
+		t.Fatalf("output schema = %q, want %q", cfg.OutputSchema, OutputSchemaMinimal)
+	}
+}
+
+func TestNewNormalizeConfigRejectsInvalidOutputSchema(t *testing.T) {
+	dir := t.TempDir()
+	input := writeTempFile(t, dir, "input.json")
+	output := filepath.Join(dir, "normalized.json")
+
+	_, err := NewNormalizeConfig(NormalizeOptions{
+		InputFile:     input,
+		OutputFile:    output,
+		OutputSchema:  "compact",
+		OutputModules: DefaultOutputModules,
+	})
+	if err == nil {
+		t.Fatal("expected output schema error")
+	}
+	if !strings.Contains(err.Error(), "--output-schema must be one of") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestNewNormalizeConfigRejectsUnknownOutputModule(t *testing.T) {
+	dir := t.TempDir()
+	input := writeTempFile(t, dir, "input.json")
+	output := filepath.Join(dir, "normalized.json")
+
+	_, err := NewNormalizeConfig(NormalizeOptions{
+		InputFile:     input,
+		OutputFile:    output,
+		OutputModules: "json,yaml",
+	})
+	if err == nil {
+		t.Fatal("expected output module error")
+	}
+	if !strings.Contains(err.Error(), "unknown output module") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
 func assertPositiveFloatEnvValidation(t *testing.T, envName string) {
 	t.Helper()
 

internal/normalize/build.go

@@ -0,0 +1,220 @@
+package normalize
+
+import (
+	"fmt"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/seriatim/internal/artifact"
+	"gitea.maximumdirect.net/eric/seriatim/internal/buildinfo"
+	"gitea.maximumdirect.net/eric/seriatim/internal/config"
+	"gitea.maximumdirect.net/eric/seriatim/schema"
+)
+
+// BuildResult contains normalize output plus deterministic transformation diagnostics.
+type BuildResult struct {
+	Output                 any
+	OutputSegmentCount     int
+	SortingChanged         bool
+	IDsReassigned          bool
+	SegmentsWithCategories int
+}
+
+// Build converts parsed normalize input into a selected seriatim output schema.
+func Build(parsed ParsedTranscript, cfg config.NormalizeConfig) (BuildResult, error) {
+	ordered := sortedSegments(parsed.Segments)
+	sortingChanged := didSortingChangeOrder(ordered)
+	idsReassigned := didReassignIDs(ordered)
+	segmentsWithCategories := countSegmentsWithCategories(ordered)
+
+	switch cfg.OutputSchema {
+	case config.OutputSchemaMinimal:
+		output := buildMinimal(ordered)
+		if err := schema.ValidateMinimalTranscript(output); err != nil {
+			return BuildResult{}, fmt.Errorf("validate normalize output: %w", err)
+		}
+		return BuildResult{
+			Output:                 output,
+			OutputSegmentCount:     len(ordered),
+			SortingChanged:         sortingChanged,
+			IDsReassigned:          idsReassigned,
+			SegmentsWithCategories: segmentsWithCategories,
+		}, nil
+	case config.OutputSchemaIntermediate:
+		output := buildIntermediate(ordered)
+		if err := schema.ValidateIntermediateTranscript(output); err != nil {
+			return BuildResult{}, fmt.Errorf("validate normalize output: %w", err)
+		}
+		return BuildResult{
+			Output:                 output,
+			OutputSegmentCount:     len(ordered),
+			SortingChanged:         sortingChanged,
+			IDsReassigned:          idsReassigned,
+			SegmentsWithCategories: segmentsWithCategories,
+		}, nil
+	case config.OutputSchemaFull:
+		output := buildFull(ordered, cfg)
+		if err := schema.ValidateTranscript(output); err != nil {
+			return BuildResult{}, fmt.Errorf("validate normalize output: %w", err)
+		}
+		return BuildResult{
+			Output:                 output,
+			OutputSegmentCount:     len(ordered),
+			SortingChanged:         sortingChanged,
+			IDsReassigned:          idsReassigned,
+			SegmentsWithCategories: segmentsWithCategories,
+		}, nil
+	default:
+		return BuildResult{}, fmt.Errorf("unsupported output schema %q", cfg.OutputSchema)
+	}
+}
+
+func sortedSegments(input []InputSegment) []InputSegment {
+	ordered := make([]InputSegment, len(input))
+	copy(ordered, input)
+	sort.SliceStable(ordered, func(i, j int) bool {
+		left := ordered[i]
+		right := ordered[j]
+		if left.Start != right.Start {
+			return left.Start < right.Start
+		}
+		if left.End != right.End {
+			return left.End < right.End
+		}
+		if left.InputIndex != right.InputIndex {
+			return left.InputIndex < right.InputIndex
+		}
+		return left.Speaker < right.Speaker
+	})
+	return ordered
+}
+
+func buildMinimal(segments []InputSegment) schema.MinimalTranscript {
+	outputSegments := make([]schema.MinimalSegment, len(segments))
+	for index, segment := range segments {
+		outputSegments[index] = schema.MinimalSegment{
+			ID:      index + 1,
+			Start:   segment.Start,
+			End:     segment.End,
+			Speaker: segment.Speaker,
+			Text:    segment.Text,
+		}
+	}
+
+	return schema.MinimalTranscript{
+		Metadata: schema.MinimalMetadata{
+			Application:  artifact.ApplicationName,
+			Version:      buildinfo.Version,
+			OutputSchema: config.OutputSchemaMinimal,
+		},
+		Segments: outputSegments,
+	}
+}
+
+func buildIntermediate(segments []InputSegment) schema.IntermediateTranscript {
+	outputSegments := make([]schema.IntermediateSegment, len(segments))
+	for index, segment := range segments {
+		outputSegments[index] = schema.IntermediateSegment{
+			ID:         index + 1,
+			Start:      segment.Start,
+			End:        segment.End,
+			Speaker:    segment.Speaker,
+			Text:       segment.Text,
+			Categories: append([]string(nil), segment.Categories...),
+		}
+	}
+
+	return schema.IntermediateTranscript{
+		Metadata: schema.IntermediateMetadata{
+			Application:  artifact.ApplicationName,
+			Version:      buildinfo.Version,
+			OutputSchema: config.OutputSchemaIntermediate,
+		},
+		Segments: outputSegments,
+	}
+}
+
+func buildFull(segments []InputSegment, cfg config.NormalizeConfig) schema.Transcript {
+	defaultSource := filepath.Base(cfg.InputFile)
+	outputSegments := make([]schema.Segment, len(segments))
+	for index, segment := range segments {
+		source := strings.TrimSpace(segment.Source)
+		if source == "" {
+			source = defaultSource
+		}
+
+		sourceSegmentIndex := copyIntPtr(segment.SourceSegmentIndex)
+		if sourceSegmentIndex == nil {
+			fallback := segment.InputIndex
+			sourceSegmentIndex = &fallback
+		}
+
+		outputSegments[index] = schema.Segment{
+			ID:                 index + 1,
+			Source:             source,
+			SourceSegmentIndex: sourceSegmentIndex,
+			SourceRef:          segment.SourceRef,
+			DerivedFrom:        append([]string(nil), segment.DerivedFrom...),
+			Speaker:            segment.Speaker,
+			Start:              segment.Start,
+			End:                segment.End,
+			Text:               segment.Text,
+			Categories:         append([]string(nil), segment.Categories...),
+		}
+	}
+
+	return schema.Transcript{
+		Metadata: schema.Metadata{
+			Application:           artifact.ApplicationName,
+			Version:               buildinfo.Version,
+			InputReader:           "normalize-input",
+			InputFiles:            []string{cfg.InputFile},
+			PreprocessingModules:  []string{},
+			PostprocessingModules: []string{},
+			OutputModules:         append([]string(nil), cfg.OutputModules...),
+		},
+		Segments:      outputSegments,
+		OverlapGroups: []schema.OverlapGroup{},
+	}
+}
+
+func copyIntPtr(value *int) *int {
+	if value == nil {
+		return nil
+	}
+	copied := *value
+	return &copied
+}
+
+func didSortingChangeOrder(segments []InputSegment) bool {
+	for index, segment := range segments {
+		if segment.InputIndex != index {
+			return true
+		}
+	}
+	return false
+}
+
+func didReassignIDs(segments []InputSegment) bool {
+	if len(segments) == 0 {
+		return false
+	}
+	for index, segment := range segments {
+		newID := index + 1
+		if segment.OriginalID == nil || *segment.OriginalID != newID {
+			return true
+		}
+	}
+	return false
+}
+
+func countSegmentsWithCategories(segments []InputSegment) int {
+	count := 0
+	for _, segment := range segments {
+		if len(segment.Categories) > 0 {
+			count++
+		}
+	}
+	return count
+}

internal/normalize/normalize.go

@@ -0,0 +1,135 @@
+package normalize
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/seriatim/internal/artifact"
+	"gitea.maximumdirect.net/eric/seriatim/internal/buildinfo"
+	"gitea.maximumdirect.net/eric/seriatim/internal/config"
+	"gitea.maximumdirect.net/eric/seriatim/internal/report"
+)
+
+type normalizeAudit struct {
+	Command                string   `json:"command"`
+	InputFile              string   `json:"input_file"`
+	OutputFile             string   `json:"output_file"`
+	InputShape             string   `json:"input_shape"`
+	InputSegmentCount      int      `json:"input_segment_count"`
+	OutputSegmentCount     int      `json:"output_segment_count"`
+	OutputSchema           string   `json:"output_schema"`
+	OutputModules          []string `json:"output_modules"`
+	IDsReassigned          bool     `json:"ids_reassigned"`
+	SortingChangedInput    bool     `json:"sorting_changed_input_order"`
+	SegmentsWithCategories int      `json:"segments_with_categories"`
+	TimingFieldsRepaired   int      `json:"timing_fields_repaired"`
+	TimingOrderSwapped     int      `json:"timing_order_swapped"`
+	SpeakerFilled          int      `json:"speaker_filled"`
+	SegmentsDroppedText    int      `json:"segments_dropped_text"`
+}
+
+// Run executes artifact-level normalization.
+func Run(ctx context.Context, cfg config.NormalizeConfig) error {
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+
+	parsed, err := ParseFile(cfg.InputFile)
+	if err != nil {
+		return err
+	}
+
+	built, err := Build(parsed, cfg)
+	if err != nil {
+		return err
+	}
+
+	if err := writeOutputJSON(cfg.OutputFile, built.Output); err != nil {
+		return err
+	}
+
+	if cfg.ReportFile != "" {
+		audit := normalizeAudit{
+			Command:                "normalize",
+			InputFile:              cfg.InputFile,
+			OutputFile:             cfg.OutputFile,
+			InputShape:             string(parsed.Shape),
+			InputSegmentCount:      parsed.InputSegmentCount,
+			OutputSegmentCount:     built.OutputSegmentCount,
+			OutputSchema:           cfg.OutputSchema,
+			OutputModules:          append([]string(nil), cfg.OutputModules...),
+			IDsReassigned:          built.IDsReassigned,
+			SortingChangedInput:    built.SortingChanged,
+			SegmentsWithCategories: built.SegmentsWithCategories,
+			TimingFieldsRepaired:   parsed.Stats.TimingFieldsRepaired,
+			TimingOrderSwapped:     parsed.Stats.TimingOrderSwapped,
+			SpeakerFilled:          parsed.Stats.SpeakerFilled,
+			SegmentsDroppedText:    parsed.Stats.SegmentsDroppedText,
+		}
+		auditJSON, err := json.Marshal(audit)
+		if err != nil {
+			return fmt.Errorf("marshal normalize audit: %w", err)
+		}
+
+		events := []report.Event{
+			report.Info("normalize", "normalize", "started normalize command"),
+			report.Info("normalize", "normalize", fmt.Sprintf("input file: %s", cfg.InputFile)),
+			report.Info("normalize", "normalize", fmt.Sprintf("detected input shape: %s", parsed.Shape)),
+			report.Info("normalize", "normalize", fmt.Sprintf("input segment count: %d", parsed.InputSegmentCount)),
+			report.Info("normalize", "normalize", fmt.Sprintf("selected output schema: %s", cfg.OutputSchema)),
+			report.Info("normalize", "normalize", fmt.Sprintf("selected output modules: %s", strings.Join(cfg.OutputModules, ","))),
+			report.Info("normalize", "normalize", fmt.Sprintf("output file: %s", cfg.OutputFile)),
+			report.Info("normalize", "normalize", fmt.Sprintf("ids reassigned: %t", built.IDsReassigned)),
+			report.Info("normalize", "normalize", fmt.Sprintf("sorting changed input order: %t", built.SortingChanged)),
+			report.Info("normalize", "normalize", fmt.Sprintf("segments with categories: %d", built.SegmentsWithCategories)),
+			report.Info("normalize", "normalize", fmt.Sprintf("timing fields repaired: %d", parsed.Stats.TimingFieldsRepaired)),
+			report.Info("normalize", "normalize", fmt.Sprintf("timing order swapped: %d", parsed.Stats.TimingOrderSwapped)),
+			report.Info("normalize", "normalize", fmt.Sprintf("speaker placeholders added: %d", parsed.Stats.SpeakerFilled)),
+			report.Info("normalize", "normalize", fmt.Sprintf("segments dropped for empty text: %d", parsed.Stats.SegmentsDroppedText)),
+			report.Info("normalize", "normalize-audit", string(auditJSON)),
+		}
+		if parsed.InputSegmentCount == 0 {
+			events = append(events, report.Warning("normalize", "normalize", "input transcript contains zero segments"))
+		}
+		events = append(events,
+			report.Info("normalize", "validate-output", fmt.Sprintf("validated %d output segment(s)", built.OutputSegmentCount)),
+			report.Info("output", "json", "wrote transcript JSON"),
+		)
+
+		rpt := report.Report{
+			Metadata: report.Metadata{
+				Application:           artifact.ApplicationName,
+				Version:               buildinfo.Version,
+				InputReader:           "normalize-input",
+				InputFiles:            []string{cfg.InputFile},
+				PreprocessingModules:  []string{},
+				PostprocessingModules: []string{},
+				OutputModules:         append([]string(nil), cfg.OutputModules...),
+			},
+			Events: events,
+		}
+		if err := report.WriteJSON(cfg.ReportFile, rpt); err != nil {
+			return fmt.Errorf("write --report-file %q: %w", cfg.ReportFile, err)
+		}
+	}
+
+	return nil
+}
+
+func writeOutputJSON(path string, value any) error {
+	file, err := os.Create(path)
+	if err != nil {
+		return err
+	}
+	defer file.Close()
+
+	encoder := json.NewEncoder(file)
+	encoder.SetIndent("", "  ")
+	if err := encoder.Encode(value); err != nil {
+		return fmt.Errorf("encode normalize output JSON: %w", err)
+	}
+	return nil
+}

internal/normalize/parse.go

@@ -0,0 +1,307 @@
+package normalize
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+)
+
+// InputShape identifies which top-level input shape was parsed.
+type InputShape string
+
+const (
+	ShapeObjectWithSegments InputShape = "object_with_segments"
+	ShapeBareSegmentsArray  InputShape = "bare_segments_array"
+)
+
+// ParsedTranscript is the validated normalize input model.
+type ParsedTranscript struct {
+	Shape             InputShape
+	InputSegmentCount int
+	Stats             NormalizeStats
+	Segments          []InputSegment
+}
+
+// InputSegment is a validated segment from normalize input.
+type InputSegment struct {
+	InputIndex         int
+	OriginalID         *int
+	StartPresent       bool
+	EndPresent         bool
+	SpeakerPresent     bool
+	TextPresent        bool
+	Start              float64
+	End                float64
+	Speaker            string
+	Text               string
+	Categories         []string
+	Source             string
+	SourceSegmentIndex *int
+	SourceRef          string
+	DerivedFrom        []string
+	OverlapGroupID     *int
+}
+
+// NormalizeStats captures deterministic repair/drop outcomes from normalize input processing.
+type NormalizeStats struct {
+	TimingFieldsRepaired int
+	TimingOrderSwapped   int
+	SpeakerFilled        int
+	SegmentsDroppedText  int
+}
+
+type inputSegmentPayload struct {
+	ID                 *int     `json:"id"`
+	Start              *float64 `json:"start"`
+	End                *float64 `json:"end"`
+	Speaker            *string  `json:"speaker"`
+	Text               *string  `json:"text"`
+	Categories         []string `json:"categories"`
+	Source             string   `json:"source"`
+	SourceSegmentIndex *int     `json:"source_segment_index"`
+	SourceRef          string   `json:"source_ref"`
+	DerivedFrom        []string `json:"derived_from"`
+	OverlapGroupID     *int     `json:"overlap_group_id"`
+}
+
+// ParseFile parses normalize input JSON from file path.
+func ParseFile(path string) (ParsedTranscript, error) {
+	file, err := os.Open(path)
+	if err != nil {
+		return ParsedTranscript{}, err
+	}
+	defer file.Close()
+
+	return ParseReader(file)
+}
+
+// ParseReader parses normalize input JSON from a reader.
+func ParseReader(reader io.Reader) (ParsedTranscript, error) {
+	var raw json.RawMessage
+	decoder := json.NewDecoder(reader)
+	decoder.UseNumber()
+	if err := decoder.Decode(&raw); err != nil {
+		return ParsedTranscript{}, fmt.Errorf("decode normalize input JSON: %w", err)
+	}
+	if err := ensureSingleValue(decoder); err != nil {
+		return ParsedTranscript{}, err
+	}
+
+	trimmed := bytes.TrimSpace(raw)
+	if len(trimmed) == 0 {
+		return ParsedTranscript{}, fmt.Errorf("normalize input is empty")
+	}
+
+	switch trimmed[0] {
+	case '{':
+		return parseObjectShape(trimmed)
+	case '[':
+		segments, stats, inputCount, err := parseSegmentsArray(trimmed)
+		if err != nil {
+			return ParsedTranscript{}, err
+		}
+		return ParsedTranscript{
+			Shape:             ShapeBareSegmentsArray,
+			InputSegmentCount: inputCount,
+			Stats:             stats,
+			Segments:          segments,
+		}, nil
+	default:
+		return ParsedTranscript{}, fmt.Errorf("normalize input must be a top-level object with \"segments\" or a top-level segment array")
+	}
+}
+
+func ensureSingleValue(decoder *json.Decoder) error {
+	var extra json.RawMessage
+	err := decoder.Decode(&extra)
+	if err == io.EOF {
+		return nil
+	}
+	if err == nil {
+		return fmt.Errorf("normalize input must contain exactly one top-level JSON value")
+	}
+	return fmt.Errorf("decode normalize input JSON: %w", err)
+}
+
+func parseObjectShape(raw []byte) (ParsedTranscript, error) {
+	var object map[string]json.RawMessage
+	if err := json.Unmarshal(raw, &object); err != nil {
+		return ParsedTranscript{}, fmt.Errorf("decode normalize object input: %w", err)
+	}
+
+	segmentsRaw, exists := object["segments"]
+	if !exists {
+		return ParsedTranscript{}, fmt.Errorf("normalize object input must contain a \"segments\" field")
+	}
+
+	segments, stats, inputCount, err := parseSegmentsArray(segmentsRaw)
+	if err != nil {
+		return ParsedTranscript{}, err
+	}
+
+	return ParsedTranscript{
+		Shape:             ShapeObjectWithSegments,
+		InputSegmentCount: inputCount,
+		Stats:             stats,
+		Segments:          segments,
+	}, nil
+}
+
+func parseSegmentsArray(raw []byte) ([]InputSegment, NormalizeStats, int, error) {
+	var segmentValues []json.RawMessage
+	if err := json.Unmarshal(raw, &segmentValues); err != nil {
+		return nil, NormalizeStats{}, 0, fmt.Errorf("normalize input \"segments\" must be an array")
+	}
+
+	segments := make([]InputSegment, len(segmentValues))
+	for index, segmentRaw := range segmentValues {
+		segment, err := decodeSegment(index, segmentRaw)
+		if err != nil {
+			return nil, NormalizeStats{}, 0, err
+		}
+		segments[index] = segment
+	}
+	normalized, stats, err := normalizeSegments(segments)
+	return normalized, stats, len(segmentValues), err
+}
+
+func decodeSegment(index int, raw []byte) (InputSegment, error) {
+	var payload inputSegmentPayload
+	if err := json.Unmarshal(raw, &payload); err != nil {
+		return InputSegment{}, fmt.Errorf("segment %d: invalid segment object: %w", index, err)
+	}
+
+	var start float64
+	if payload.Start != nil {
+		start = *payload.Start
+	}
+	var end float64
+	if payload.End != nil {
+		end = *payload.End
+	}
+
+	speaker := ""
+	if payload.Speaker != nil {
+		speaker = strings.TrimSpace(*payload.Speaker)
+	}
+
+	text := ""
+	if payload.Text != nil {
+		text = *payload.Text
+	}
+
+	return InputSegment{
+		InputIndex:         index,
+		OriginalID:         payload.ID,
+		StartPresent:       payload.Start != nil,
+		EndPresent:         payload.End != nil,
+		SpeakerPresent:     payload.Speaker != nil,
+		TextPresent:        payload.Text != nil,
+		Start:              start,
+		End:                end,
+		Speaker:            speaker,
+		Text:               text,
+		Categories:         append([]string(nil), payload.Categories...),
+		Source:             payload.Source,
+		SourceSegmentIndex: payload.SourceSegmentIndex,
+		SourceRef:          payload.SourceRef,
+		DerivedFrom:        append([]string(nil), payload.DerivedFrom...),
+		OverlapGroupID:     payload.OverlapGroupID,
+	}, nil
+}
+
+func normalizeSegments(segments []InputSegment) ([]InputSegment, NormalizeStats, error) {
+	stats := NormalizeStats{}
+	filtered := make([]InputSegment, 0, len(segments))
+	for _, segment := range segments {
+		if strings.TrimSpace(segment.Text) == "" {
+			stats.SegmentsDroppedText++
+			continue
+		}
+		filtered = append(filtered, segment)
+	}
+
+	if len(filtered) == 0 {
+		return filtered, stats, nil
+	}
+
+	hasStart := make([]bool, len(filtered))
+	hasEnd := make([]bool, len(filtered))
+	for index, segment := range filtered {
+		hasStart[index] = segment.StartPresent
+		hasEnd[index] = segment.EndPresent
+	}
+	for index := range filtered {
+		if !hasStart[index] && !hasEnd[index] {
+			midpoint := inferTimestampFromNeighbors(filtered, hasStart, hasEnd, index)
+			filtered[index].Start = midpoint
+			filtered[index].End = midpoint
+			stats.TimingFieldsRepaired += 2
+			hasStart[index] = true
+			hasEnd[index] = true
+			continue
+		}
+		if hasStart[index] && !hasEnd[index] {
+			filtered[index].End = filtered[index].Start
+			stats.TimingFieldsRepaired++
+			hasEnd[index] = true
+		}
+		if !hasStart[index] && hasEnd[index] {
+			filtered[index].Start = filtered[index].End
+			stats.TimingFieldsRepaired++
+			hasStart[index] = true
+		}
+	}
+
+	for index := range filtered {
+		if filtered[index].Start < 0 {
+			return nil, NormalizeStats{}, fmt.Errorf("segment %d has start %v; start must be >= 0", filtered[index].InputIndex, filtered[index].Start)
+		}
+		if filtered[index].End < filtered[index].Start {
+			filtered[index].Start, filtered[index].End = filtered[index].End, filtered[index].Start
+			stats.TimingOrderSwapped++
+		}
+		if strings.TrimSpace(filtered[index].Speaker) == "" {
+			filtered[index].Speaker = "Unknown_Speaker"
+			stats.SpeakerFilled++
+		}
+	}
+
+	return filtered, stats, nil
+}
+
+func inferTimestampFromNeighbors(segments []InputSegment, hasStart []bool, hasEnd []bool, index int) float64 {
+	prevEnd, hasPrev := nearestPreviousEnd(segments, hasEnd, index)
+	nextStart, hasNext := nearestNextStart(segments, hasStart, index)
+	if hasPrev && hasNext {
+		return (prevEnd + nextStart) / 2
+	}
+	if hasPrev {
+		return prevEnd
+	}
+	if hasNext {
+		return nextStart
+	}
+	return 0
+}
+
+func nearestPreviousEnd(segments []InputSegment, hasEnd []bool, index int) (float64, bool) {
+	for i := index - 1; i >= 0; i-- {
+		if hasEnd[i] {
+			return segments[i].End, true
+		}
+	}
+	return 0, false
+}
+
+func nearestNextStart(segments []InputSegment, hasStart []bool, index int) (float64, bool) {
+	for i := index + 1; i < len(segments); i++ {
+		if hasStart[i] {
+			return segments[i].Start, true
+		}
+	}
+	return 0, false
+}

internal/normalize/parse_test.go

@@ -0,0 +1,279 @@
+package normalize
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestParseReaderObjectWithSegmentsParses(t *testing.T) {
+	input := `{
+		"segments": [
+			{"start": 1.0, "end": 2.0, "speaker": " Alice ", "text": "hello", "id": 100}
+		]
+	}`
+
+	parsed, err := ParseReader(strings.NewReader(input))
+	if err != nil {
+		t.Fatalf("parse failed: %v", err)
+	}
+	if parsed.Shape != ShapeObjectWithSegments {
+		t.Fatalf("shape = %q, want %q", parsed.Shape, ShapeObjectWithSegments)
+	}
+	if len(parsed.Segments) != 1 {
+		t.Fatalf("segment count = %d, want 1", len(parsed.Segments))
+	}
+	segment := parsed.Segments[0]
+	if segment.Speaker != "Alice" {
+		t.Fatalf("speaker = %q, want %q", segment.Speaker, "Alice")
+	}
+	if segment.OriginalID == nil || *segment.OriginalID != 100 {
+		t.Fatalf("original id = %v, want 100", segment.OriginalID)
+	}
+}
+
+func TestParseReaderBareSegmentArrayParses(t *testing.T) {
+	input := `[
+		{"start": 1.0, "end": 2.0, "speaker": "Alice", "text": "hello"},
+		{"start": 3.0, "end": 4.0, "speaker": "Bob", "text": "world"}
+	]`
+
+	parsed, err := ParseReader(strings.NewReader(input))
+	if err != nil {
+		t.Fatalf("parse failed: %v", err)
+	}
+	if parsed.Shape != ShapeBareSegmentsArray {
+		t.Fatalf("shape = %q, want %q", parsed.Shape, ShapeBareSegmentsArray)
+	}
+	if len(parsed.Segments) != 2 {
+		t.Fatalf("segment count = %d, want 2", len(parsed.Segments))
+	}
+}
+
+func TestParseReaderInvalidJSONFails(t *testing.T) {
+	_, err := ParseReader(strings.NewReader(`{"segments":`))
+	if err == nil {
+		t.Fatal("expected parse error")
+	}
+	if !strings.Contains(err.Error(), "decode normalize input JSON") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestParseReaderObjectMissingSegmentsFails(t *testing.T) {
+	_, err := ParseReader(strings.NewReader(`{"items":[]}`))
+	if err == nil {
+		t.Fatal("expected missing segments error")
+	}
+	if !strings.Contains(err.Error(), "must contain a \"segments\" field") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestParseReaderSegmentsNotArrayFails(t *testing.T) {
+	_, err := ParseReader(strings.NewReader(`{"segments": {}}`))
+	if err == nil {
+		t.Fatal("expected segments not array error")
+	}
+	if !strings.Contains(err.Error(), "\"segments\" must be an array") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestParseReaderTopLevelScalarShapesFail(t *testing.T) {
+	tests := []string{`"text"`, `42`, `null`, `true`}
+	for _, input := range tests {
+		_, err := ParseReader(strings.NewReader(input))
+		if err == nil {
+			t.Fatalf("expected top-level shape error for %s", input)
+		}
+		if !strings.Contains(err.Error(), "top-level object") {
+			t.Fatalf("unexpected error for %s: %v", input, err)
+		}
+	}
+}
+
+func TestParseReaderMissingStartUsesEndValue(t *testing.T) {
+	parsed, err := ParseReader(strings.NewReader(`[{"end":2,"speaker":"A","text":"t"}]`))
+	if err != nil {
+		t.Fatalf("parse failed: %v", err)
+	}
+	if len(parsed.Segments) != 1 {
+		t.Fatalf("segment count = %d, want 1", len(parsed.Segments))
+	}
+	if parsed.Segments[0].Start != 2 || parsed.Segments[0].End != 2 {
+		t.Fatalf("segment timing = %v..%v, want 2..2", parsed.Segments[0].Start, parsed.Segments[0].End)
+	}
+}
+
+func TestParseReaderMissingEndUsesStartValue(t *testing.T) {
+	parsed, err := ParseReader(strings.NewReader(`[{"start":1,"speaker":"A","text":"t"}]`))
+	if err != nil {
+		t.Fatalf("parse failed: %v", err)
+	}
+	if len(parsed.Segments) != 1 {
+		t.Fatalf("segment count = %d, want 1", len(parsed.Segments))
+	}
+	if parsed.Segments[0].Start != 1 || parsed.Segments[0].End != 1 {
+		t.Fatalf("segment timing = %v..%v, want 1..1", parsed.Segments[0].Start, parsed.Segments[0].End)
+	}
+}
+
+func TestParseReaderMissingSpeakerUsesUnknownPlaceholder(t *testing.T) {
+	parsed, err := ParseReader(strings.NewReader(`[{"start":1,"end":2,"text":"t"}]`))
+	if err != nil {
+		t.Fatalf("parse failed: %v", err)
+	}
+	if parsed.Segments[0].Speaker != "Unknown_Speaker" {
+		t.Fatalf("speaker = %q, want Unknown_Speaker", parsed.Segments[0].Speaker)
+	}
+}
+
+func TestParseReaderEmptySpeakerUsesUnknownPlaceholder(t *testing.T) {
+	parsed, err := ParseReader(strings.NewReader(`[{"start":1,"end":2,"speaker":"   ","text":"t"}]`))
+	if err != nil {
+		t.Fatalf("parse failed: %v", err)
+	}
+	if parsed.Segments[0].Speaker != "Unknown_Speaker" {
+		t.Fatalf("speaker = %q, want Unknown_Speaker", parsed.Segments[0].Speaker)
+	}
+}
+
+func TestParseReaderMissingTextDropsSegment(t *testing.T) {
+	parsed, err := ParseReader(strings.NewReader(`[{"start":1,"end":2,"speaker":"A"}]`))
+	if err != nil {
+		t.Fatalf("parse failed: %v", err)
+	}
+	if len(parsed.Segments) != 0 {
+		t.Fatalf("segment count = %d, want 0", len(parsed.Segments))
+	}
+}
+
+func TestParseReaderEndBeforeStartSwapsValues(t *testing.T) {
+	parsed, err := ParseReader(strings.NewReader(`[{"start":3,"end":2,"speaker":"A","text":"t"}]`))
+	if err != nil {
+		t.Fatalf("parse failed: %v", err)
+	}
+	if parsed.Segments[0].Start != 2 || parsed.Segments[0].End != 3 {
+		t.Fatalf("segment timing = %v..%v, want 2..3", parsed.Segments[0].Start, parsed.Segments[0].End)
+	}
+}
+
+func TestParseReaderNegativeStartFails(t *testing.T) {
+	_, err := ParseReader(strings.NewReader(`[{"start":-1,"end":2,"speaker":"A","text":"t"}]`))
+	assertContains(t, err, "start must be >= 0")
+}
+
+func TestParseReaderEmptySegmentsArrayAccepted(t *testing.T) {
+	parsed, err := ParseReader(strings.NewReader(`{"segments":[]}`))
+	if err != nil {
+		t.Fatalf("parse failed: %v", err)
+	}
+	if len(parsed.Segments) != 0 {
+		t.Fatalf("segment count = %d, want 0", len(parsed.Segments))
+	}
+}
+
+func TestParseReaderCategoriesPreservedWhenValid(t *testing.T) {
+	parsed, err := ParseReader(strings.NewReader(`[{"start":1,"end":2,"speaker":"A","text":"t","categories":["filler","backchannel"]}]`))
+	if err != nil {
+		t.Fatalf("parse failed: %v", err)
+	}
+	if len(parsed.Segments) != 1 {
+		t.Fatalf("segment count = %d, want 1", len(parsed.Segments))
+	}
+	if len(parsed.Segments[0].Categories) != 2 {
+		t.Fatalf("categories length = %d, want 2", len(parsed.Segments[0].Categories))
+	}
+	if parsed.Segments[0].Categories[0] != "filler" || parsed.Segments[0].Categories[1] != "backchannel" {
+		t.Fatalf("categories = %v", parsed.Segments[0].Categories)
+	}
+}
+
+func TestParseReaderMissingBothTimesMiddleUsesNeighborMidpoint(t *testing.T) {
+	parsed, err := ParseReader(strings.NewReader(`[
+		{"start":1,"end":2,"speaker":"A","text":"left"},
+		{"speaker":"B","text":"middle"},
+		{"start":6,"end":7,"speaker":"C","text":"right"}
+	]`))
+	if err != nil {
+		t.Fatalf("parse failed: %v", err)
+	}
+	if parsed.Segments[1].Start != 4 || parsed.Segments[1].End != 4 {
+		t.Fatalf("middle timing = %v..%v, want 4..4", parsed.Segments[1].Start, parsed.Segments[1].End)
+	}
+}
+
+func TestParseReaderMissingBothTimesEdgeFallbacks(t *testing.T) {
+	parsedFirst, err := ParseReader(strings.NewReader(`[
+		{"speaker":"A","text":"first"},
+		{"start":5,"end":6,"speaker":"B","text":"second"}
+	]`))
+	if err != nil {
+		t.Fatalf("parse first failed: %v", err)
+	}
+	if parsedFirst.Segments[0].Start != 5 || parsedFirst.Segments[0].End != 5 {
+		t.Fatalf("first timing = %v..%v, want 5..5", parsedFirst.Segments[0].Start, parsedFirst.Segments[0].End)
+	}
+
+	parsedLast, err := ParseReader(strings.NewReader(`[
+		{"start":1,"end":2,"speaker":"A","text":"first"},
+		{"speaker":"B","text":"last"}
+	]`))
+	if err != nil {
+		t.Fatalf("parse last failed: %v", err)
+	}
+	if parsedLast.Segments[1].Start != 2 || parsedLast.Segments[1].End != 2 {
+		t.Fatalf("last timing = %v..%v, want 2..2", parsedLast.Segments[1].Start, parsedLast.Segments[1].End)
+	}
+}
+
+func TestParseReaderMissingBothTimesSingleSegmentUsesZero(t *testing.T) {
+	parsed, err := ParseReader(strings.NewReader(`[{"speaker":"A","text":"only"}]`))
+	if err != nil {
+		t.Fatalf("parse failed: %v", err)
+	}
+	if parsed.Segments[0].Start != 0 || parsed.Segments[0].End != 0 {
+		t.Fatalf("timing = %v..%v, want 0..0", parsed.Segments[0].Start, parsed.Segments[0].End)
+	}
+}
+
+func TestParseReaderEmptyOrWhitespaceTextDropped(t *testing.T) {
+	parsed, err := ParseReader(strings.NewReader(`[
+		{"start":1,"end":2,"speaker":"A","text":"ok"},
+		{"start":2,"end":3,"speaker":"A","text":""},
+		{"start":3,"end":4,"speaker":"A","text":"   "}
+	]`))
+	if err != nil {
+		t.Fatalf("parse failed: %v", err)
+	}
+	if len(parsed.Segments) != 1 {
+		t.Fatalf("segment count = %d, want 1", len(parsed.Segments))
+	}
+}
+
+func TestParseReaderOriginalInputIndexPreserved(t *testing.T) {
+	input := `[
+		{"start":1,"end":2,"speaker":"A","text":"one"},
+		{"start":2,"end":3,"speaker":"B","text":"two"},
+		{"start":3,"end":4,"speaker":"C","text":"three"}
+	]`
+	parsed, err := ParseReader(strings.NewReader(input))
+	if err != nil {
+		t.Fatalf("parse failed: %v", err)
+	}
+	for index, segment := range parsed.Segments {
+		if segment.InputIndex != index {
+			t.Fatalf("segment %d input index = %d, want %d", index, segment.InputIndex, index)
+		}
+	}
+}
+
+func assertContains(t *testing.T, err error, fragment string) {
+	t.Helper()
+	if err == nil {
+		t.Fatalf("expected error containing %q", fragment)
+	}
+	if !strings.Contains(err.Error(), fragment) {
+		t.Fatalf("error = %q, want substring %q", err.Error(), fragment)
+	}
+}