# Operations Guide

## Scope

This document covers runtime operation of the implemented CLI commands:

- `merge`
- `trim`
- `normalize`
- `render`

## 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.
- `render`: input must be an existing valid seriatim artifact JSON file.

## 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
```

### Render

1. Provide existing seriatim artifact with `--input-file`.
2. Provide `--output-file`.
3. Provide `--format markdown`.
4. Optionally provide `--title`, `--include-timestamps`, `--include-segment-ids`, and `--include-metadata`.

Example:

```sh
go run ./cmd/seriatim render \
  --input-file examples/render/input-intermediate.json \
  --output-file /tmp/seriatim-example-render.md \
  --format markdown
```

## Output and report artifacts

Primary outputs:

- `merge`, `trim`, `normalize`: `--output-file` writes JSON transcript artifact in the selected schema.
- `render`: `--output-file` writes presentation Markdown.

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.
- `render` has no report output in the current implementation.

## 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 notes:

- With identical inputs/config/version, `merge` behavior is deterministic and input files are sorted before processing.
- With identical input artifact and render flags, `render` output is deterministic.

## 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.
- Rendered Markdown is human-readable transcript content and should be handled as sensitive output when applicable.

## Related docs

- CLI reference: [cli.md](cli.md)
- Configuration reference: [config.md](config.md)
- Troubleshooting: [troubleshooting.md](troubleshooting.md)
- Integration notes:
  - [integrations/whisperx-json.md](integrations/whisperx-json.md)
  - [integrations/output-schemas.md](integrations/output-schemas.md)
- Synthetic examples: [../examples/README.md](../examples/README.md)