seriatim/docs/operations.md

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:

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:

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:

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:

go run ./cmd/seriatim render \
  --input-file normalized.json \
  --output-file transcript.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
• Configuration reference: config.md
• Troubleshooting: troubleshooting.md
• Integration notes:
  • integrations/whisperx-json.md
  • integrations/output-schemas.md
• Synthetic examples: ../examples/README.md