Complete documentation rebuild

docs/internal/stage-prepare.md

@@ -0,0 +1,74 @@
+# Stage: prepare
+
+## Purpose
+Materialize all required session inputs into canonical local workspace paths and record input provenance in the session manifest.
+
+## Inputs and Outputs
+Inputs:
+- `session.yml` (resolved session config)
+- `pipeline.resolved.yml` (materialized from resolved pipeline config)
+- `speakers.yml`
+- `autocorrect.yml`
+- `glossary.yml`
+- audio source:
+  - local (`session.inputs.audio_dir` or `session.inputs.audio_files`), or
+  - S3 (`session.inputs.audio_s3.prefix`)
+
+Outputs:
+- `inputs/session.yml`
+- `inputs/pipeline.resolved.yml`
+- `inputs/speakers.yml`
+- `inputs/autocorrect.yml`
+- `inputs/glossary.yml`
+- `audio/*.flac` in session workdir
+- `manifest.Inputs` records with checksums and source metadata
+
+## Boundaries
+Owns:
+- Input path resolution and validation
+- Local copy/materialization of configs and audio files
+- S3 audio download to run-scoped spool, then copy into work audio dir
+
+Does not own:
+- Transcript generation/processing
+- Archive publish behavior
+
+## Config Fields Used
+- `session.session_id`
+- `session.campaign`
+- `session.inputs.speakers_file`
+- `session.inputs.autocorrect_file`
+- `session.inputs.glossary_file`
+- `session.inputs.audio_dir`
+- `session.inputs.audio_files`
+- `session.inputs.audio_s3.prefix`
+- `pipeline.workspace.root`
+- `pipeline.spool.root`
+- `pipeline.storage.s3.bucket`
+- `pipeline.storage.s3.root_prefix`
+
+## External Adapters Used
+- Object storage backend (`env.ObjectStore`) for S3 audio list/download when `audio_s3` is configured.
+
+## State and Manifest Behavior
+- Ensures workspace layout exists.
+- Writes resolved config and input files to canonical `inputs/` paths.
+- Records all prepared inputs into `manifest.Inputs` (sorted deterministically by kind/path).
+- For S3 audio, records `S3Bucket`, `S3Key`, `S3Size`, `S3ETag`, and `SpoolPath` in each audio input record.
+
+## Skip and Resume Behavior
+- Runner-level skip applies when stage already `succeeded` and `--force` is not set.
+- Stage itself is deterministic/idempotent for unchanged inputs (`copyFileIfChanged`, `writeBytesIfChanged`).
+
+## Failure Behavior
+- Fails on missing required files, invalid audio source combinations, no discoverable `.flac` files, duplicate audio basenames, missing object store for S3 mode, or S3 list/download failures.
+
+## Tests to Inspect Before Changing
+- `internal/stage/prepare_test.go`
+- `internal/app/session_cli_test.go`
+- `internal/config/load_validate_test.go`
+
+## Architectural Invariants
+- `audio_dir`/`audio_files` and `audio_s3` are mutually exclusive.
+- Audio files must be `.flac`.
+- Canonical `inputs/*` and `audio/*` paths are the durable source for downstream stages.