Finish render rollout with markdown publish defaults, analyze guidance, and docs updates

docs/cli.md

@@ -93,6 +93,7 @@ Valid stage names:
 - `polish`
 - `normalize`
 - `trim`
+- `render`
 - `analyze`
 - `publish`
 - `notify`

docs/config.md

@@ -98,6 +98,12 @@ publish:
     - source: narratio.transcript.final_trimmed
       dest: transcripts/final.trimmed.json
       required: true
+    - source: narratio.transcript.final_markdown
+      dest: transcripts/final.md
+      required: true
+    - source: narratio.transcript.final_trimmed_markdown
+      dest: transcripts/final.trimmed.md
+      required: true
     - source: narratio.artifact.session_recap
       dest: artifacts/session_recap.md
       required: true
@@ -138,7 +144,7 @@ Rules:
 | `pipeline.cache.s3_audio` | bool | No | `true` |
 | `pipeline.publish.enabled` | bool | No | `true` |
 | `pipeline.publish.upload_run` | bool | No | `true` |
-| `pipeline.publish.outputs[]` | list | No | defaults to final trimmed transcript output |
+| `pipeline.publish.outputs[]` | list | No | defaults to final trimmed JSON plus final and final-trimmed Markdown outputs |
 | `pipeline.publish.outputs[].source` | string | Yes (per rule) | must reference built-in or configured artifact source |
 | `pipeline.publish.outputs[].dest` | string | Conditional | derived if omitted and source supports derivation |
 | `pipeline.publish.outputs[].required` | bool | No | `true` |
@@ -188,6 +194,12 @@ Rules:
 | `pipeline.trim.bounds.render_debug` | bool | No | `false` |
 | `pipeline.trim.bounds.render_output_path` | string | Conditional | required when `render_debug` is true |
 | `pipeline.trim.seriatim.report` | bool | No | `false` |
+| `pipeline.render.enabled` | bool | No | `true` |
+| `pipeline.render.format` | string | No | `markdown` (only supported value) |
+| `pipeline.render.title` | string | No | empty (falls back to `session.title` when set) |
+| `pipeline.render.include_timestamps` | bool | No | `true` |
+| `pipeline.render.include_segment_ids` | bool | No | `false` |
+| `pipeline.render.include_metadata` | bool | No | `false` |
 | `pipeline.scriptorium.binary` | string | No | `scriptorium` |
 | `pipeline.scriptorium.config_path` | string | No | empty |
 | `pipeline.scriptorium.timeout` | duration | No | `10m` |

docs/integrations/seriatim.md

@@ -1,7 +1,7 @@
 # Integration: Seriatim
 
 ## Purpose
-Define the Seriatim adapter contract used by `merge`, `normalize`, and `trim`.
+Define the Seriatim adapter contract used by `merge`, `normalize`, `trim`, and `render`.
 
 ## Adapter Boundary
 Interface:
@@ -10,6 +10,7 @@ Interface:
   - `Run(ctx, MergeRequest)`
   - `Normalize(ctx, NormalizeRequest)`
   - `Trim(ctx, TrimRequest)`
+  - `Render(ctx, RenderRequest)`
 
 Primary implementation:
 - `internal/adapters/seriatim/SubprocessRunner`
@@ -18,11 +19,13 @@ Execution modes:
 - `seriatim merge`
 - `seriatim normalize`
 - `seriatim trim`
+- `seriatim render`
 
 ## Request/Result Contracts
 - `MergeRequest`/`MergeResult`: multi-input merge to base transcript, optional report.
 - `NormalizeRequest`/`NormalizeResult`: transcript normalization with explicit schema.
 - `TrimRequest`/`TrimResult`: transcript trimming with required keep selector.
+- `RenderRequest`/`RenderResult`: transcript-to-markdown rendering with explicit format and render booleans.
 
 Results include output/log/config paths, timing, exit code, and metadata.
 
@@ -36,9 +39,11 @@ Runner construction validates:
 Invocation fails on:
 - missing required request paths/inputs;
 - invalid normalize schema override;
+- unsupported render format;
 - subprocess failure;
-- invalid JSON outputs;
-- missing `segments` array for normalize/trim transcript outputs.
+- invalid JSON outputs for merge/normalize/trim;
+- missing `segments` array for normalize/trim transcript outputs;
+- empty render output files.
 
 When report paths are provided/enabled, report files must parse as JSON.
 
@@ -49,7 +54,7 @@ When report paths are provided/enabled, report files must parse as JSON.
 - adapter does not write manifests or choose stage inputs.
 
 ## Config Mapping
-Config fields consumed through runner/stage wiring are under `pipeline.seriatim.*`.
+Config fields consumed through runner/stage wiring are under `pipeline.seriatim.*` and `pipeline.render.*`.
 
 Maintained examples with Seriatim config:
 - `examples/pipeline.full.annotated.yml`

docs/internal/README.md

@@ -20,9 +20,10 @@ Canonical stage order from `internal/stage.All()`:
 4. `polish`
 5. `normalize`
 6. `trim`
-7. `analyze`
-8. `publish`
-9. `notify` (placeholder)
+7. `render`
+8. `analyze`
+9. `publish`
+10. `notify` (placeholder)
 
 `notify` is currently a placeholder stage with optional notifier call behavior; it has no persisted pipeline outputs.
 
@@ -39,5 +40,6 @@ Canonical stage order from `internal/stage.All()`:
 - `stage-polish.md`
 - `stage-normalize.md`
 - `stage-trim.md`
+- `stage-render.md`
 - `stage-analyze.md`
 - `stage-publish.md`

docs/internal/artifacts.md

@@ -9,6 +9,8 @@ Define canonical artifact IDs, runtime catalog behavior, source resolution rules
 - `narratio.transcript.polished` -> `transcripts/polished.json` (`polish`)
 - `narratio.transcript.final` -> `transcripts/final.json` (`normalize`)
 - `narratio.transcript.final_trimmed` -> `transcripts/final.trimmed.json` (`trim`)
+- `narratio.transcript.final_markdown` -> `transcripts/final.md` (`render`)
+- `narratio.transcript.final_trimmed_markdown` -> `transcripts/final.trimmed.md` (`render`)
 - `narratio.bounds.session` -> `artifacts/session_bounds.json` (`trim`)
 
 ## Configured and Previous-Session Sources
@@ -53,7 +55,8 @@ Previous-session sources (`narratio.previous_session.artifact.*`):
 
 Validation by content type:
 
-- transcript built-ins: JSON with top-level `segments` array;
+- transcript JSON built-ins: JSON with top-level `segments` array;
+- transcript Markdown built-ins: non-empty text file;
 - bounds built-in: valid JSON;
 - configured/previous-session artifact files: non-empty text file.
 

docs/internal/stage-analyze.md

@@ -30,6 +30,7 @@ Supported source families:
 ## Failure Semantics
 - required missing configured/previous-session inputs fail.
 - missing required previous-session source includes prepare rerun guidance.
+- missing required `narratio.transcript.final_markdown` or `narratio.transcript.final_trimmed_markdown` inputs includes render rerun guidance.
 - dependency cycles or unavailable required dependencies fail.
 - adapter validation failures fail stage.
 

docs/internal/stage-publish.md

@@ -4,7 +4,7 @@
 Upload run/session outputs to object storage and atomically advance remote current state.
 
 ## Inputs
-- successful prerequisite stages: `prepare`, `transcribe`, `merge`, `polish`, `normalize`, `trim`, `analyze`
+- successful prerequisite stages: `prepare`, `transcribe`, `merge`, `polish`, `normalize`, `trim`, `render`, `analyze`
 - run root `runs/{run_id}/**`
 - publish output rules (`pipeline.publish.outputs`)
 - effective publish locks (static + remote merged lock set)

docs/internal/stage-render.md

@@ -0,0 +1,29 @@
+# Stage: render
+
+## Purpose
+Render Markdown transcript artifacts from normalized JSON transcripts via Seriatim.
+
+## Inputs
+- `narratio.transcript.final` (`transcripts/final.json`)
+- `narratio.transcript.final_trimmed` (`transcripts/final.trimmed.json`)
+
+## Outputs
+- `narratio.transcript.final_markdown` -> `transcripts/final.md`
+- `narratio.transcript.final_trimmed_markdown` -> `transcripts/final.trimmed.md`
+
+## Key Behavior
+- uses `pipeline.render` settings (enabled/format/title/booleans).
+- resolves inputs manifest-first, then canonical fallback.
+- writes run-local outputs first, then materializes canonical session outputs.
+- records input provenance, output paths, adapter metadata, logs, and generated config refs.
+- skips with stage metadata when `pipeline.render.enabled=false`.
+
+## Failure Semantics
+- missing normalized input fails with normalize rerun guidance.
+- missing trimmed input fails with trim rerun guidance.
+- adapter/subprocess failure fails stage.
+- empty render output files fail validation.
+
+## Invariants
+- only `format: markdown` is supported.
+- render stage owns production of built-in Markdown transcript sources.

docs/operations.md

@@ -73,9 +73,10 @@ Canonical stage order:
 4. `polish`
 5. `normalize`
 6. `trim`
-7. `analyze`
-8. `publish`
-9. `notify`
+7. `render`
+8. `analyze`
+9. `publish`
+10. `notify`
 
 Execution rules:
 
@@ -245,5 +246,6 @@ Rules:
 
 - Local and S3 audio modes are mutually exclusive.
 - Publish requires prerequisite stages through analyze to be succeeded.
+- Markdown publish defaults require render outputs (`transcripts/final.md` and `transcripts/final.trimmed.md`).
 - Restore requires configured object storage and committed remote current state.
 - Storage-backed commands load filesystem secrets before object-store initialization.