Complete documentation rebuild

docs/internal/README.md

@@ -0,0 +1,24 @@
+# Internal Documentation Index
+
+## Audience
+Developers and LLM coding agents changing Narratio internals.
+
+## Scope
+Implementation-accurate contracts for workspace/state, stages, and external adapter boundaries.
+
+## Component Docs
+- `workspace.md`: local state model, manifests, run-local layout, promotion, and cleanup invariants.
+- `stage-prepare.md`: input materialization and provenance capture.
+- `stage-transcribe.md`: WhisperX transcript generation.
+- `stage-merge.md`: Seriatim normalization + merge.
+- `stage-polish.md`: Audita transcript polishing.
+- `stage-normalize.md`: post-polish normalization.
+- `stage-trim.md`: bounds-driven transcript trimming.
+- `stage-analyze.md`: Scriptorium session recap generation.
+- `stage-archive.md`: archive upload and current-pointer publish contract.
+- `integration-audita.md`: Audita adapter invocation/validation contract.
+- `integration-seriatim.md`: Seriatim merge/normalize/trim adapter contract.
+- `integration-scriptorium.md`: Scriptorium run/render adapter contract.
+
+## Canonical Owner
+`docs/internal/` is the canonical home for implemented internals per `docs/documentation/policy.md`.

docs/internal/integration-audita.md

@@ -0,0 +1,66 @@
+# Integration: audita
+
+## Purpose
+Define Narratio's adapter contract for transcript polishing via Audita CLI subprocess execution.
+
+## Inputs and Outputs
+Inputs (`audita.PolishRequest`):
+- merged transcript path
+- glossary path
+- output processed transcript path
+- optional report path (required when report enabled)
+- work dir
+- generated config path
+- stdout/stderr log paths
+- optional module/model/base URL and concurrency knobs
+
+Outputs (`audita.PolishResult`):
+- processed transcript path
+- optional report path
+- generated config path
+- stdout/stderr log paths
+- exit code, duration, invoked binary
+- adapter metadata
+
+## Boundaries
+Owns:
+- Deterministic CLI argument construction for `audita process`
+- Environment bridging for API credentials
+- Invocation config emission
+- Output validation for processed transcript and report
+
+Does not own:
+- Upstream/downstream stage orchestration
+- Credential sourcing policy beyond required env-var presence check
+
+## Config Fields Used
+Via `pipeline.audita.*` mapped in app/stage wiring:
+- `binary`, `timeout`, `llm_api_key_env`, `modules`, `base_url`, `model`
+- `transcript_description`, `config_path`, `output_schema`, `work_dir_retention`
+- `total_llm_concurrency`, `proposal_llm_concurrency`, `validation_model`, `validation_llm_concurrency`, `report`
+
+## External Adapters Used
+- Shared subprocess helper (`internal/adapters/subprocess`) to run CLI and capture logs.
+
+## State and Manifest Behavior
+- No direct manifest writes.
+- Stage-level metadata records adapter provenance and credential-present signal.
+- Generated invocation YAML is written when `GeneratedConfigPath` is provided.
+
+## Skip and Resume Behavior
+- Adapter has no skip/resume logic. Stage/runner controls this.
+
+## Failure Behavior
+- Constructor validation fails on invalid binary/timeout/schema/concurrency/URL values.
+- Run fails on missing required paths, missing required credential env var, subprocess errors, invalid processed JSON shape, or invalid report JSON.
+- Failures preserve stdout/stderr paths in returned result metadata.
+
+## Tests to Inspect Before Changing
+- `internal/adapters/audita/subprocess_test.go`
+- `internal/adapters/audita/fake_test.go`
+- `internal/stage/polish_test.go`
+
+## Architectural Invariants
+- Processed output must be valid JSON with top-level `segments` array.
+- When report is enabled, report output must be valid JSON.
+- If `llm_api_key_env` is configured, credential must be present in environment.

docs/internal/integration-scriptorium.md

@@ -0,0 +1,64 @@
+# Integration: scriptorium
+
+## Purpose
+Define Narratio's adapter contract for Scriptorium artifact generation and render-debug subprocess invocations.
+
+## Inputs and Outputs
+Inputs:
+- `RunArtifactRequest`: binary, config path, prompt/profile IDs, input map, vars map, timeout, output path, logs/config paths, optional API env and working dir
+- `RenderArtifactRequest`: same core fields for render mode
+
+Outputs (`ArtifactResult`):
+- output path
+- stdout/stderr log paths
+- generated config path
+- exit code and duration
+- command mode (`run` or `render`)
+- prompt/profile provenance
+- validation failure signal
+- adapter metadata
+
+## Boundaries
+Owns:
+- Deterministic CLI arg construction for `scriptorium run` and `scriptorium render`
+- Common request validation
+- Invocation config emission
+- Output existence/non-empty checks
+- Validation-failure mapping for run exit code 2
+
+Does not own:
+- Artifact selection policy (`analyze` stage)
+- Bounds semantic validation (`trim` stage)
+
+## Config Fields Used
+Via `pipeline.scriptorium.*` and stage-level artifact config:
+- `binary`, `config_path`, `timeout`, `render_debug`
+- artifact-level `prompt_id`, `profile_id`, `timeout`, `inputs`, `vars`, `output_path`
+
+## External Adapters Used
+- Shared subprocess helper (`internal/adapters/subprocess`).
+
+## State and Manifest Behavior
+- No direct manifest writes.
+- Stage metadata records adapter outputs and command mode.
+- Generated invocation YAML is written when requested.
+
+## Skip and Resume Behavior
+- Adapter has no skip/resume logic. Stage/runner controls execution.
+
+## Failure Behavior
+- Request validation fails for missing binary/prompt/output, invalid timeout, invalid input/var names, or missing required API env var.
+- Subprocess errors bubble with command context.
+- `run` exit code 2 is treated as `ValidationFailed=true` and surfaced as error by calling stage.
+- Successful subprocess still fails if output file is missing/empty.
+
+## Tests to Inspect Before Changing
+- `internal/adapters/scriptorium/subprocess_test.go`
+- `internal/adapters/scriptorium/fake_test.go`
+- `internal/stage/analyze_test.go`
+- `internal/stage/trim_test.go`
+
+## Architectural Invariants
+- Both modes require explicit timeout > 0.
+- Input/var maps are sorted into deterministic CLI argument order.
+- Run-mode validation failures are represented explicitly, not silently skipped.

docs/internal/integration-seriatim.md

@@ -0,0 +1,60 @@
+# Integration: seriatim
+
+## Purpose
+Define Narratio's adapter contract for merge, normalize, and trim subprocess invocations of Seriatim.
+
+## Inputs and Outputs
+Inputs:
+- `MergeRequest`: raw/normalized transcript inputs, output path, optional report, speaker/autocorrect paths, logs/config
+- `NormalizeRequest`: input transcript, output path, schema, optional report, timeout/log/config
+- `TrimRequest`: input transcript, output path, keep selector, timeout/log/config
+
+Outputs:
+- `MergeResult`, `NormalizeResult`, `TrimResult` with output paths, logs/config paths, exit code, duration, binary provenance, and metadata.
+
+## Boundaries
+Owns:
+- Validated deterministic CLI invocation construction
+- Optional env tuning propagation for merge
+- Invocation config file emission
+- JSON output validation
+
+Does not own:
+- Transcript input selection/promotion logic (stage-owned)
+- Bounds computation (scriptorium/trim-stage-owned)
+
+## Config Fields Used
+Via `pipeline.seriatim.*` mapped in app/stage wiring:
+- `binary`, `timeout`, `output_schema`, `coalesce_gap`, `report`
+- `env.overlap_word_run_gap`
+- `env.overlap_word_run_reorder_window`
+- `env.backchannel_max_duration`
+- `env.filler_max_duration`
+
+## External Adapters Used
+- Shared subprocess helper (`internal/adapters/subprocess`).
+
+## State and Manifest Behavior
+- No direct manifest writes.
+- Stage metadata consumes adapter result fields and preserves generated config/log references.
+
+## Skip and Resume Behavior
+- Adapter has no skip/resume logic. Runner controls stage execution.
+
+## Failure Behavior
+- Constructor fails for invalid binary/timeout/output-schema/coalesce-gap.
+- Merge fails on missing output path/inputs/report path (if enabled), subprocess errors, invalid merged output JSON, invalid report JSON.
+- Normalize fails on missing input/output, invalid schema, subprocess errors, invalid normalized output JSON shape, invalid report JSON.
+- Trim fails on missing input/output/keep selector, subprocess errors, invalid trimmed output JSON shape.
+
+## Tests to Inspect Before Changing
+- `internal/adapters/seriatim/subprocess_test.go`
+- `internal/adapters/seriatim/fake_test.go`
+- `internal/stage/merge_test.go`
+- `internal/stage/normalize_test.go`
+- `internal/stage/trim_test.go`
+
+## Architectural Invariants
+- Supported output schemas are limited to `seriatim-minimal`, `seriatim-intermediate`, `seriatim-full`.
+- Normalize/trim outputs must include `segments` arrays.
+- Merge/normalize/trim all route through deterministic subprocess invocation.

docs/internal/stage-analyze.md

@@ -0,0 +1,69 @@
+# Stage: analyze
+
+## Purpose
+Generate the session recap artifact using configured Scriptorium artifact settings.
+
+## Inputs and Outputs
+Inputs:
+- transcript inputs as requested by selected artifact config (processed/normalized/trimmed/current recap, depending on `pipeline.scriptorium.artifacts.session_recap.inputs`)
+
+Outputs:
+- `artifacts/session_recap.md`
+
+## Boundaries
+Owns:
+- Selecting supported analyze artifact (`session_recap` only)
+- Resolving transcript/reference inputs and vars
+- Optional render-debug execution before run
+- Main Scriptorium run and output promotion
+
+Does not own:
+- Transcript processing pipeline stages
+- Archive publish/pointer behavior
+
+## Config Fields Used
+- `session.session_id`
+- `session.campaign`
+- `pipeline.workspace.root`
+- `pipeline.scriptorium.binary`
+- `pipeline.scriptorium.config_path`
+- `pipeline.scriptorium.timeout`
+- `pipeline.scriptorium.render_debug`
+- `pipeline.scriptorium.artifacts.session_recap.*`
+  - `enabled`
+  - `prompt_id`
+  - `profile_id`
+  - `timeout`
+  - `output_path`
+  - `render_debug`
+  - `inputs`
+  - `vars`
+
+## External Adapters Used
+- Scriptorium adapter:
+  - optional `RenderArtifact` (debug diagnostics)
+  - `RunArtifact` (actual recap generation)
+
+## State and Manifest Behavior
+- If `pipeline.scriptorium` is nil, stage returns success metadata with `skipped=true`.
+- If no enabled artifacts exist, stage returns success metadata with `skipped=true`.
+- If enabled artifacts exist but any artifact other than `session_recap` is enabled, stage fails.
+- Uses run-local output/log/config/reports paths when run layout is enabled.
+- Promotes canonical recap output and records adapter metadata.
+
+## Skip and Resume Behavior
+- Runner-level skip applies when already succeeded and not forced.
+- Forced reruns can stale downstream succeeded stages.
+- Stage-local "skipped" metadata is distinct from runner-level stage status skip.
+
+## Failure Behavior
+- Fails on missing required resolved inputs, invalid transcript inputs, render/run adapter failures, or validation-failed run results.
+
+## Tests to Inspect Before Changing
+- `internal/stage/analyze_test.go`
+- `internal/adapters/scriptorium/subprocess_test.go`
+
+## Architectural Invariants
+- Analyze implementation supports only `artifacts.session_recap` as executable artifact.
+- Optional inputs may be omitted; required inputs must resolve.
+- Successful output must exist and be non-empty before promotion.

docs/internal/stage-archive.md

@@ -0,0 +1,68 @@
+# Stage: archive
+
+## Purpose
+Publish run records and promoted session artifacts to object storage, then atomically advance the remote current pointer.
+
+## Inputs and Outputs
+Inputs:
+- session manifest and prerequisite stage records
+- run root contents under `runs/{run_id}/`
+- promotion sources from session root (`archive.promote_artifacts`)
+
+Outputs:
+- uploaded run files under `{session_prefix}/runs/{run_id}/...`
+- uploaded promoted artifacts under `{session_prefix}/...`
+- `{session_prefix}/current/manifest.json`
+- `{session_prefix}/current/run_id.txt` written last
+
+## Boundaries
+Owns:
+- Archive enable/disable gate behavior
+- Prerequisite stage success enforcement
+- Run file collection and upload (excluding `audio/`)
+- Promotion rule resolution and upload
+- Commit pointer publish order
+
+Does not own:
+- Stage execution before archive
+- Post-archive local cleanup policy execution (handled by app cleanup logic)
+
+## Config Fields Used
+- `pipeline.archive.enabled`
+- `pipeline.archive.upload_run`
+- `pipeline.archive.promote_artifacts`
+- `pipeline.storage.s3.bucket`
+- `pipeline.storage.s3.root_prefix`
+- `pipeline.workspace.root`
+- `session.campaign`
+- `session.session_id`
+
+## External Adapters Used
+- Object storage backend (`env.ObjectStore`) for upload/list primitives.
+
+## State and Manifest Behavior
+- Requires `prepare`, `transcribe`, `merge`, `polish`, `normalize`, `trim`, and `analyze` status `succeeded`.
+- Resolves bucket/prefix from manifest identity first, then config fallback.
+- Writes metadata including:
+  - upload counts/paths
+  - `current_manifest_key`
+  - `current_run_id_key`
+  - `current_pointer_written`
+- On skipped archive path, returns metadata with `skipped=true` and pointer not written.
+
+## Skip and Resume Behavior
+- Stage may self-skip (metadata skip) when archive disabled or run upload disabled.
+- Runner-level skip also applies for previously succeeded stage unless forced.
+
+## Failure Behavior
+- Fails on missing prerequisite success, missing object store when required, missing run root, missing required promotion source, upload failures, or pointer write failures.
+- Pointer semantics are fail-safe: `current/run_id.txt` is not written if prior required uploads fail.
+
+## Tests to Inspect Before Changing
+- `internal/stage/archive_test.go`
+- `internal/app/post_archive_cleanup_test.go`
+
+## Architectural Invariants
+- Run upload excludes `audio/` subtree.
+- `current/manifest.json` uploads before `current/run_id.txt`.
+- `current/run_id.txt` is the remote publish commit marker.

docs/internal/stage-merge.md

@@ -0,0 +1,63 @@
+# Stage: merge
+
+## Purpose
+Normalize per-speaker raw transcripts and merge them into one merged transcript via Seriatim.
+
+## Inputs and Outputs
+Inputs:
+- `transcripts/raw/*.json`
+- `inputs/speakers.yml`
+- `inputs/autocorrect.yml`
+
+Outputs:
+- `transcripts/merged.json`
+- optional `artifacts/seriatim.report.json` (when report enabled)
+
+## Boundaries
+Owns:
+- Raw transcript discovery/validation
+- Per-input normalize calls to Seriatim
+- Final merge call to Seriatim
+- Run-local log/config/report path wiring
+- Promotion of merged/report outputs to canonical paths
+
+Does not own:
+- Transcript polishing or downstream artifact generation
+
+## Config Fields Used
+- `session.session_id`
+- `session.campaign`
+- `pipeline.workspace.root`
+- `pipeline.seriatim.binary`
+- `pipeline.seriatim.timeout`
+- `pipeline.seriatim.output_schema`
+- `pipeline.seriatim.coalesce_gap`
+- `pipeline.seriatim.report`
+- `pipeline.seriatim.env.*`
+
+## External Adapters Used
+- Seriatim adapter:
+  - `Normalize` for each raw input
+  - `Run` for final merge
+
+## State and Manifest Behavior
+- Reads transcript inputs from transcribe stage outputs in manifest when present; falls back to canonical raw directory.
+- Writes run-local outputs/logs/config under `runs/{run_id}/merge/...` when enabled.
+- Promotes canonical merged transcript and optional report.
+- Records normalized-input provenance and adapter metadata in stage metadata.
+
+## Skip and Resume Behavior
+- Runner-level skip applies when already succeeded and not forced.
+- Forced rerun of this or upstream stages can stale downstream succeeded stages via runner invalidation.
+
+## Failure Behavior
+- Fails on missing/invalid raw transcripts, missing speakers/autocorrect files, normalize failure, merge failure, invalid merged output JSON, or invalid report JSON when enabled.
+
+## Tests to Inspect Before Changing
+- `internal/stage/merge_test.go`
+- `internal/adapters/seriatim/subprocess_test.go`
+
+## Architectural Invariants
+- Merge consumes normalized forms of each raw transcript.
+- Merged transcript must validate before promotion.
+- Report output is optional and gated by config.

docs/internal/stage-normalize.md

@@ -0,0 +1,56 @@
+# Stage: normalize
+
+## Purpose
+Normalize the processed transcript into a deterministic intermediate schema for trim and optionally emit a normalize report.
+
+## Inputs and Outputs
+Inputs:
+- `transcripts/processed.json`
+
+Outputs:
+- `transcripts/normalized.json` (or configured normalize output path)
+- optional `artifacts/seriatim.normalize.report.json`
+
+## Boundaries
+Owns:
+- Processed transcript discovery/validation
+- Normalize request construction and invocation
+- Optional normalize report wiring
+- Promotion of normalized transcript and optional report
+
+Does not own:
+- Bounds detection or segment trimming
+
+## Config Fields Used
+- `session.session_id`
+- `session.campaign`
+- `pipeline.workspace.root`
+- `pipeline.normalize.output_path`
+- `pipeline.normalize.output_schema`
+- `pipeline.normalize.report`
+- `pipeline.seriatim.binary`
+- `pipeline.seriatim.timeout`
+
+## External Adapters Used
+- Seriatim adapter (`Normalize`).
+
+## State and Manifest Behavior
+- Reads processed transcript from polish outputs in manifest when present; falls back to canonical path.
+- Uses run-local output/report/log/config paths when run layout is enabled.
+- Promotes canonical normalized transcript and optional normalize report.
+- Records adapter/result metadata including source path selection.
+
+## Skip and Resume Behavior
+- Runner-level skip applies when already succeeded and not forced.
+- Forced reruns can stale downstream succeeded stages.
+
+## Failure Behavior
+- Fails on missing/invalid processed transcript, adapter error, invalid normalized output, or invalid report output when report enabled.
+
+## Tests to Inspect Before Changing
+- `internal/stage/normalize_test.go`
+- `internal/adapters/seriatim/subprocess_test.go`
+
+## Architectural Invariants
+- Normalized output must validate as processed-transcript-compatible JSON (`segments` array required).
+- Default normalize config is applied when `pipeline.normalize` is unset.

docs/internal/stage-polish.md

@@ -0,0 +1,69 @@
+# Stage: polish
+
+## Purpose
+Polish merged transcript with Audita and produce a processed transcript for downstream normalization/analyze.
+
+## Inputs and Outputs
+Inputs:
+- `transcripts/merged.json`
+- `inputs/glossary.yml`
+
+Outputs:
+- `transcripts/processed.json`
+- optional `artifacts/audita.report.json` (when report enabled)
+
+## Boundaries
+Owns:
+- Merged transcript discovery/validation
+- Audita invocation request construction
+- Run-local logs/config/work-dir/report wiring
+- Promotion of processed transcript and optional report
+
+Does not own:
+- Upstream merge normalization
+- Downstream normalize/trim/analyze logic
+
+## Config Fields Used
+- `session.session_id`
+- `session.campaign`
+- `pipeline.workspace.root`
+- `pipeline.audita.binary`
+- `pipeline.audita.timeout`
+- `pipeline.audita.llm_api_key_env`
+- `pipeline.audita.modules`
+- `pipeline.audita.base_url`
+- `pipeline.audita.model`
+- `pipeline.audita.transcript_description`
+- `pipeline.audita.config_path`
+- `pipeline.audita.output_schema`
+- `pipeline.audita.work_dir_retention`
+- `pipeline.audita.total_llm_concurrency`
+- `pipeline.audita.proposal_llm_concurrency`
+- `pipeline.audita.validation_model`
+- `pipeline.audita.validation_llm_concurrency`
+- `pipeline.audita.report`
+
+## External Adapters Used
+- Audita adapter (`env.Audita.Run`).
+
+## State and Manifest Behavior
+- Reads merged transcript from merge manifest outputs when available; falls back to canonical merged path.
+- Uses run-local output/report/log/config/scratch paths when run layout is enabled.
+- Promotes canonical `transcripts/processed.json` and optional report.
+- Records adapter invocation metadata, credential presence signal, and output provenance in stage metadata.
+
+## Skip and Resume Behavior
+- Runner-level skip applies when already succeeded and not forced.
+- Forced rerun can stale downstream succeeded stages via runner invalidation.
+
+## Failure Behavior
+- Fails on missing/invalid merged transcript, missing glossary, adapter error, invalid processed output shape (`segments` array required), or invalid report JSON when enabled.
+
+## Tests to Inspect Before Changing
+- `internal/stage/polish_test.go`
+- `internal/adapters/audita/subprocess_test.go`
+
+## Architectural Invariants
+- Processed transcript must contain a top-level `segments` array.
+- Report behavior is strictly config-gated.
+- Stage output canonicalization always ends at `transcripts/processed.json`.

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.

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.

docs/internal/stage-trim.md

@@ -0,0 +1,75 @@
+# Stage: trim
+
+## Purpose
+Optionally trim the normalized transcript to session bounds; always produce a durable trimmed transcript.
+
+## Inputs and Outputs
+Inputs:
+- `transcripts/normalized.json`
+
+Outputs:
+- `transcripts/trimmed.json` (or configured trim output path)
+- when trim enabled: `artifacts/session_bounds.json`
+
+## Boundaries
+Owns:
+- Trim-enabled switch behavior
+- Bounds generation via Scriptorium artifact run
+- Bounds validation against normalized transcript
+- Keep-selector derivation and Seriatim trim invocation
+- Copy-through behavior when disabled or bounds indicate unchanged transcript
+
+Does not own:
+- Upstream normalization
+- Downstream artifact analysis
+
+## Config Fields Used
+- `session.session_id`
+- `session.campaign`
+- `pipeline.workspace.root`
+- `pipeline.trim.enabled`
+- `pipeline.trim.output_path`
+- `pipeline.trim.bounds.prompt_id`
+- `pipeline.trim.bounds.profile_id`
+- `pipeline.trim.bounds.timeout`
+- `pipeline.trim.bounds.output_path`
+- `pipeline.trim.bounds.transcript_input_name`
+- `pipeline.trim.bounds.render_debug`
+- `pipeline.trim.bounds.render_output_path`
+- `pipeline.seriatim.binary`
+- `pipeline.seriatim.timeout`
+- `pipeline.scriptorium.binary`
+- `pipeline.scriptorium.config_path`
+- `pipeline.scriptorium.timeout`
+
+## External Adapters Used
+- Scriptorium adapter:
+  - optional `RenderArtifact` for bounds debug render
+  - `RunArtifact` for bounds output
+- Seriatim adapter:
+  - `Trim` when bounds indicate trimming is required
+
+## State and Manifest Behavior
+- Reads normalized transcript from normalize manifest outputs when available; falls back to canonical path.
+- Uses run-local outputs/logs/reports/config/scratch paths when run layout is enabled.
+- Promotes canonical trimmed transcript; promotes session bounds when trim enabled.
+- Records bounds diagnostics, trim action, keep selector, and adapter metadata.
+
+## Skip and Resume Behavior
+- Runner-level skip applies when already succeeded and not forced.
+- Forced reruns can stale downstream succeeded stages.
+- When `trim.enabled=false`, stage still succeeds by copying normalized to trimmed output.
+
+## Failure Behavior
+- Fails on missing/invalid normalized transcript.
+- With trim enabled, fails on missing adapters/config, bounds generation/validation errors, invalid bounds JSON, invalid range/segment ids, trim adapter failures, or invalid trimmed output.
+
+## Tests to Inspect Before Changing
+- `internal/stage/trim_test.go`
+- `internal/adapters/scriptorium/subprocess_test.go`
+- `internal/adapters/seriatim/subprocess_test.go`
+
+## Architectural Invariants
+- Trim never falls back to processed transcript; normalized transcript is required input.
+- `session_bounds` output exists only for enabled trim path.
+- Render-debug artifacts are diagnostics and not declared stage outputs.

docs/internal/workspace.md

@@ -0,0 +1,68 @@
+# Workspace internals
+
+## Purpose
+Define the local durable and run-local workspace model used by stages, manifests, resume, and archive.
+
+## Inputs and Outputs
+Inputs:
+- `pipeline.workspace.root`
+- `session.campaign`
+- `session.session_id`
+- generated `run_id`
+
+Outputs:
+- Session manifest at `{workspace.root}/work/{campaign}/{session_id}/manifest.json`
+- Run manifest at `{workspace.root}/work/{campaign}/{session_id}/runs/{run_id}/manifest.json`
+- Canonical durable session directories and run-local stage trees
+
+## Boundaries
+Owns:
+- Session-level path layout (`inputs/`, `audio/`, `transcripts/`, `artifacts/`, `reports/`, `logs/`, `config/`, `current/`, `runs/`)
+- Run-local stage sandbox layout under `runs/{run_id}/{stage}/`
+- Session lock acquisition/release (`.lock`)
+
+Does not own:
+- Stage business logic
+- Remote archive semantics (documented in `stage-archive.md`)
+- CLI argument parsing
+
+## Config Fields Used
+- `pipeline.workspace.root`
+- `pipeline.workspace.cleanup_after_archive`
+- `pipeline.spool.root`
+- `pipeline.spool.delete_audio_after_archive`
+- `session.campaign`
+- `session.session_id`
+
+## External Adapters Used
+None directly in this subsystem. Stages may use object storage adapters and then write local outputs into this layout.
+
+## State and Manifest Behavior
+- Session state is persisted in the session manifest (`manifest.Manifest`).
+- Invocation history is persisted per run in run manifests under `runs/{run_id}/manifest.json`.
+- During each run, stage outputs are often written run-local first (`runs/{run_id}/{stage}/outputs/...`) and promoted to canonical session paths after stage success.
+- `manifest.Artifacts` entries record `ProducerRunID` for durable outputs.
+- For S3 audio sessions, `prepare` records spool/work paths and S3 provenance in `manifest.Inputs`.
+
+## Skip and Resume Behavior
+- Skip/resume decisions are made in `internal/app` (`run_control.go`, `resume.go`) using stage status in the session manifest.
+- `--force` reruns selected stages and marks downstream previously-succeeded stages as `stale`.
+- Workspace layout is idempotent (`EnsureLayoutFor`) and reused across runs.
+
+## Failure Behavior
+- Failures preserve manifests and run-local files for inspection.
+- Lock conflicts fail fast via `ErrLockConflict`.
+- Cleanup can fail post-archive; failure is recorded in archive stage metadata and returned by the run.
+
+## Tests to Inspect Before Changing
+- `internal/artifacts/local_test.go`
+- `internal/stage/run_local_test.go`
+- `internal/app/run_control_test.go`
+- `internal/app/resume_run_stage_test.go`
+- `internal/app/post_archive_cleanup_test.go`
+
+## Architectural Invariants
+- Session root is campaign-aware: `{workspace.root}/work/{campaign}/{session_id}`.
+- Run roots are always nested: `runs/{run_id}` under the session root.
+- Run-local output promotion must end in canonical session paths.
+- Cleanup only targets run-scoped directories and must never delete configured root directories.