Complete documentation rebuild

docs/internal/stage-transcribe.md

@@ -0,0 +1,58 @@
+# Stage: transcribe
+
+## Purpose
+Generate per-speaker raw transcripts from prepared audio using WhisperX.
+
+## Inputs and Outputs
+Inputs:
+- `audio/*.flac` prepared by `prepare`
+
+Outputs:
+- `transcripts/raw/<speaker>.json` for each input audio file
+
+## Boundaries
+Owns:
+- Discovering prepared audio inputs
+- Deriving speaker ids from audio basenames
+- Parallel WhisperX invocation with bounded concurrency
+- Validating produced JSON and promoting run-local outputs
+
+Does not own:
+- Transcript merge/polish/normalize/trim/analyze
+
+## Config Fields Used
+- `session.session_id`
+- `session.campaign`
+- `pipeline.workspace.root`
+- `pipeline.whisperx.transcribe_url`
+- `pipeline.whisperx.language`
+- `pipeline.whisperx.timeout`
+- `pipeline.whisperx.retries`
+- `pipeline.whisperx.retry_delay`
+- `pipeline.whisperx.concurrency`
+
+## External Adapters Used
+- WhisperX adapter (`env.WhisperX.Transcribe`).
+
+## State and Manifest Behavior
+- Uses run-local output paths under `runs/{run_id}/transcribe/outputs/...` when run layout is enabled.
+- Validates each generated transcript JSON before promotion.
+- Promotes canonical outputs to `transcripts/raw/*.json`.
+- Records per-file metadata (attempts/status/duration/output path) in stage metadata.
+
+## Skip and Resume Behavior
+- Runner-level skip applies for previously succeeded stage unless forced.
+- On forced upstream reruns, downstream succeeded stages can be marked `stale` by runner logic.
+
+## Failure Behavior
+- Fails if no prepared audio exists, duplicate speaker basenames are detected, adapter output path mismatches expected path, any output JSON is invalid, or one worker fails.
+- Cancels in-flight workers after first terminal error.
+
+## Tests to Inspect Before Changing
+- `internal/stage/transcribe_test.go`
+- `internal/app/whisperx_wiring_test.go`
+
+## Architectural Invariants
+- Speaker identity is derived from `.flac` basename and must be unique.
+- Every successful speaker output must be valid JSON before promotion.
+- Canonical raw transcript set is the only supported merge input surface.