# Repository instructions

## Automatic commits are mandatory

- Automatically commit each completed, validated change before finishing a
  task. Do not wait for the user to ask for a commit or request confirmation.
- Keep commits focused. Include the implementation, regression tests, and
  relevant documentation together; commit independent changes separately.
- Inspect staged and unstaged changes before committing. Stage only files that
  belong to the task. Do not commit user recordings, generated transcripts,
  credentials, or unrelated changes.
- Use Conventional Commit subjects and explain the change and validation in
  the commit body, including a `Test Plan:` section.
- Run the relevant checks, including `python3 -B -m unittest -v`,
  `bash -n transcribe` for shell changes, and `git diff --cached --check`.
  Report any validation that could not be completed; never claim a mocked
  provider test proves live API behavior.
- After committing, inspect the commit and working tree, and report the commit
  hash with any remaining work. Do not push unless requested.

## Project layout

- `transcribe`: CLI options, audio preparation, and transcription requests.
- `chunks.py`: upload boundaries and ordered overlap stitching.
- `subtitles.py`: timestamp validation and SRT cue formatting.
- `transcript.py`: readable text paragraphs and speaker markers.
- `test_*.py` and `tests/fake_provider.py`: local regression tests without real
  credentials or provider requests.

Keep the CLI and its three Python helpers together. Preserve transcript order
and emit stdout only after all chunks and output conversion succeed. Provider
speaker IDs are request-local; reuse transcript IDs across requests only with
supporting overlap evidence. Keep chunk details out of the final transcript.
Progress, processing details, and errors belong on stderr.