Add operations and troubleshooting documentation

docs/operations.md

@@ -0,0 +1,132 @@
+# Operations Guide
+
+## Scope
+
+This document covers runtime operation of the implemented CLI commands:
+
+- `merge`
+- `trim`
+- `normalize`
+
+## Runtime model
+
+seriatim is a single-process, filesystem-only CLI.
+
+- Each invocation reads input files, processes in memory, and writes output files.
+- There is no daemon, queue, database, resume checkpoint, remote storage, or background worker.
+- On error, the command exits non-zero; there is no built-in retry/resume flow.
+
+## Filesystem expectations
+
+All commands require accessible local files and existing parent directories for outputs.
+
+- Input paths must exist and must be files.
+- Output/report parent directories must already exist.
+- Output and report files are created with `os.Create`, so existing files at those paths are overwritten.
+
+Command-specific expectations:
+
+- `merge`: requires at least one `--input-file`; optional `--speakers` and `--autocorrect` paths must exist when provided.
+- `trim`: input must be an existing valid seriatim artifact JSON file.
+- `normalize`: input must be a JSON object with `segments` or a top-level segment array.
+
+## Normal workflow
+
+### Merge
+
+1. Provide one or more `--input-file` values.
+2. Optionally provide `--speakers`, `--autocorrect`, and `--report-file`.
+3. Provide `--output-file`.
+4. Run command.
+
+Example:
+
+```sh
+go run ./cmd/seriatim merge \
+  --input-file speaker-a.json \
+  --input-file speaker-b.json \
+  --output-file merged.json \
+  --report-file merge-report.json
+```
+
+### Trim
+
+1. Provide existing artifact with `--input-file`.
+2. Select segments with exactly one of `--keep` or `--remove`.
+3. Provide `--output-file`.
+4. Optionally provide `--output-schema`, `--allow-empty`, and `--report-file`.
+
+Example:
+
+```sh
+go run ./cmd/seriatim trim \
+  --input-file merged.json \
+  --output-file trimmed.json \
+  --keep "1-20,25"
+```
+
+### Normalize
+
+1. Provide `--input-file` containing supported JSON shape.
+2. Provide `--output-file`.
+3. Optionally provide `--output-schema`, `--output-modules`, and `--report-file`.
+
+Example:
+
+```sh
+go run ./cmd/seriatim normalize \
+  --input-file external.json \
+  --output-file normalized.json \
+  --report-file normalize-report.json
+```
+
+## Output and report artifacts
+
+Primary output:
+
+- `--output-file` writes JSON transcript artifact in selected schema.
+
+Optional report output:
+
+- `--report-file` writes deterministic JSON report events.
+- `merge` report metadata records reader/modules and event sequence.
+- `trim` report includes a `trim-audit` event with mode/selector/counts and old-to-new ID mapping.
+- `normalize` report includes a `normalize-audit` event with input shape, repair stats, and output selection details.
+
+## Failure and retry behavior
+
+Failure behavior:
+
+- Errors are printed once to stderr by the root command and exit status is `1`.
+- There is no partial-state recovery mechanism.
+
+Retry guidance:
+
+1. Fix the reported input/config/path issue.
+2. Re-run the same command.
+3. If a prior run created a partial or unwanted output/report file, remove it and rerun.
+
+Operational note:
+
+- With identical inputs/config/version, merge behavior is deterministic and input files are sorted before processing.
+
+## Cleanup
+
+seriatim does not manage retention.
+
+- Remove unneeded output/report artifacts manually.
+- No cache, state directory, or lock files are maintained by the application.
+
+## Privacy considerations
+
+Transcript artifacts and reports are local files and may contain sensitive conversational data.
+
+- Store outputs in controlled directories with appropriate OS permissions.
+- Share report files carefully; they include file paths and processing diagnostics.
+- Normalize report events intentionally avoid embedding transcript text, but output artifacts contain transcript content.
+
+## Related docs
+
+- CLI reference: [cli.md](cli.md)
+- Configuration reference: [config.md](config.md)
+- Troubleshooting: [troubleshooting.md](troubleshooting.md)