Document transcript trim workflow

README.md

@@ -9,15 +9,13 @@ Implemented now:
 - strict config loading/validation (`pipeline.yml` and `session.yml`)
 - local workspace/session layout, locking, and manifest persistence
 - resumable stage control (`run`, `plan`, `resume`, `run-stage`, `status`)
-- real `prepare`, `transcribe`, `merge`, and `polish` stages
+- real `prepare`, `transcribe`, `merge`, `polish`, `trim`, and `analyze` stages
 - real WhisperX, Seriatim, and Audita adapters
 - real Scriptorium subprocess adapter
-- real `analyze` stage for `session_recap`
 - optional Scriptorium render diagnostics (`render_debug`)
 
 Not implemented yet:
 
-- real `trim` behavior
 - real `archive` behavior
 - real `notify` behavior
 - additional analyze artifacts beyond `session_recap`
@@ -32,7 +30,24 @@ Narratio expects two YAML files:
 
 YAML decoding is strict (`KnownFields(true)`), so unknown fields fail fast.
 
-## Trim Configuration (Scaffold)
+## Canonical Stage Order
+
+1. `prepare`
+2. `transcribe`
+3. `merge`
+4. `polish`
+5. `trim`
+6. `analyze`
+7. `archive`
+8. `notify`
+
+## Transcript Tiers
+
+- `transcripts/merged.json`: canonical deterministic merged transcript from Seriatim merge
+- `transcripts/processed.json`: full polished transcript from Audita polish
+- `transcripts/trimmed.json`: gameplay-only polished transcript from trim stage
+
+## Trim Configuration
 
 `pipeline.trim` is optional. If omitted, no trim config is loaded. If `trim.enabled` is omitted, it defaults to `false`.
 
@@ -48,7 +63,7 @@ When `trim.enabled: true`:
 
 Trim paths are treated as session-workdir-relative when not absolute.
 
-Example trim scaffold config:
+Example trim config:
 
 ```yaml
 trim:
@@ -66,6 +81,30 @@ trim:
     report: false
 ```
 
+Trim behavior summary:
+
+- trim discovers and validates `transcripts/processed.json`
+- trim uses Scriptorium bounds (`dnd_session.bounds` by example config) to produce `artifacts/session_bounds.json`
+- bounds IDs are validated against the same processed transcript ID space that Seriatim trim will consume
+- trim converts bounds to Seriatim keep selector (for example `10-868`) and runs Seriatim trim
+- if trim is disabled, Narratio copies processed transcript to trimmed transcript and records `trim_action=copy_disabled`
+
+Trim outputs and diagnostics:
+
+- `artifacts/session_bounds.json`
+- `transcripts/trimmed.json`
+- `logs/scriptorium.bounds.stdout.log`
+- `logs/scriptorium.bounds.stderr.log`
+- `config/scriptorium.bounds.generated.yml`
+- `logs/seriatim.trim.stdout.log`
+- `logs/seriatim.trim.stderr.log`
+- `config/seriatim.trim.generated.yml`
+- optional bounds render-debug outputs:
+  - `artifacts/session_bounds.render.json`
+  - `logs/scriptorium.bounds.render.stdout.log`
+  - `logs/scriptorium.bounds.render.stderr.log`
+  - `config/scriptorium.bounds.render.generated.yml`
+
 ## Scriptorium Configuration
 
 `pipeline.scriptorium` is optional. When present, Narratio validates and uses it for analyze-stage artifact generation.
@@ -133,8 +172,10 @@ For the initial implementation, only `session_recap` generation is supported.
 
 Analyze-stage session recap behavior:
 
-- defaults to trimmed transcript input (`transcripts/trimmed.json`) when configured with `source: trimmed_transcript`
-- still supports full polished transcript input (`transcripts/processed.json`) when configured with `source: processed_transcript`
+- session recap should use gameplay-only transcript input (`source: trimmed_transcript`)
+- Narratio resolves `trimmed_transcript` from trim manifest output (`transcript_trimmed`) or fallback `transcripts/trimmed.json`
+- missing trimmed transcript fails clearly and advises running trim stage first
+- full polished transcript input (`source: processed_transcript`) remains supported for future table/meta-analysis artifacts
 - optionally includes `previous_recap` when configured and resolvable
 - omits optional previous recap when unavailable
 - fails if required inputs are missing
@@ -182,6 +223,18 @@ Run analyze only:
 go run ./cmd/narratio run-stage --config examples/pipeline.minimal.yml --session examples/session.minimal.yml analyze
 ```
 
+## Operational Note
+
+Checksum-based stale detection is not implemented yet.
+
+If prepared inputs or prompt/runtime config change, rerun the appropriate upstream stages before relying on downstream artifacts.
+
+Examples:
+
+- glossary/autocorrect/speaker-context changes: rerun at least `merge`, `polish`, `trim`, and `analyze`
+- trim bounds prompt/profile/config changes: rerun at least `trim` and `analyze`
+- session recap prompt/profile/input-source changes: rerun `analyze`
+
 ## Roadmap
 
 Near-term roadmap: