Final documentation cleanup for v1.0.0 release

README.md

@@ -1,22 +1,22 @@
 # narratio
 
-Narratio is a Go orchestration application that turns D&D session audio into polished transcripts and generated session artifacts.
+Narratio is a stage-driven Go orchestrator for turning D&D session audio into polished transcripts and generated artifacts.
 
-It coordinates transcription, merge/polish/normalize/trim processing, artifact generation, archive publishing, and resumable run state in one operator workflow.
+It runs a deterministic workflow across `prepare`, `transcribe`, `merge`, `polish`, `normalize`, `trim`, `analyze`, and `publish`, with manifest-driven continuation and restore support.
 
 ```bash
-narratio run --session-id 2026-04-04
+narratio run 2026-04-04
 ```
 
-This command requires discoverable `pipeline.yml` and `session.yml` files (or explicit `--config` and `--session` flags).
+This requires resolvable `pipeline.yml`, `campaign.yml`, and concrete `session.yml` (or explicit config flags).
 
 ## Documentation
 
-- [Configuration](docs/config.md)
 - [CLI Reference](docs/cli.md)
-- [Operations and Recovery](docs/operations.md)
+- [Configuration](docs/config.md)
+- [Operations](docs/operations.md)
 - [Troubleshooting](docs/troubleshooting.md)
-- [Development Guide](docs/development.md)
-- [Architecture Principles](docs/architecture.md)
 - [Internal Component Contracts](docs/internal/README.md)
-- [Config Examples](examples/)
+- [Development Guide](docs/policy/development.md)
+- [Architecture Principles](docs/policy/architecture.md)
+- [Maintained Examples](examples/)

docs/cli.md

@@ -1,88 +1,89 @@
-# CLI
+# CLI Reference
 
 ## Shortest Useful Command
 
 ```bash
-narratio run --session-id 2026-04-04
+narratio run 2026-04-04
 ```
 
-This command uses default system discovery for `pipeline.yml`, `campaign.yml`, and local `session.yml`. If local session discovery misses and S3 storage is configured, `--session-id` can load remote `session.yml` from the canonical session prefix.
-
-Default discovery checks system config locations only. Pass `--config`, `--campaign`, and `--session` to use files from the current working directory.
+This runs the canonical full pipeline for session `2026-04-04`.
 
 ## Command Overview
 
-Implemented commands:
+Top-level commands:
 
-- `run`: execute pipeline stages and persist manifest state.
-- `plan`: validate config, prepare workspace layout, and print stage run/skip decisions.
-- `resume`: continue from first non-succeeded stage unless forced.
-- `status`: read an existing manifest or inspect local/remote state for a session.
-- `run-stage`: execute exactly one stage.
-- `analyze`: force-rerun the analyze stage.
-- `restore`: restore durable local session state from the committed remote archive state.
-- `session validate`: run read-only preflight checks for a session.
-- `session init`: create local or remote `session.yml`.
-- `artifacts list`: list effective artifact source IDs.
-- `locks`: list, add, and remove archive promotion locks.
-- `clean`: remove local workspace/spool state for one session or all local sessions.
+- `run <session_id>`: run full stage order.
+- `run-stage <stage> <session_id>`: run one stage.
+- `analyze <session_id>`: force-run analyze.
+- `publish <session_id>`: force-run publish.
+- `clean <session_id>` or `clean --all`: remove local work/spool state.
+- `session <subcommand>`: session helper commands.
 
-Unknown commands print usage and exit non-zero.
+Session subcommands:
 
-For config semantics, see [docs/config.md](./config.md). For operator lifecycle and recovery, see [docs/operations.md](./operations.md).
+- `session init <session_id>`
+- `session plan <session_id>`
+- `session validate <session_id>`
+- `session status <session_id>`
+- `session restore <session_id>`
+- `session artifacts <session_id>`
+- `session locks <session_id>`
+- `session locks add <session_id> <source>`
+- `session locks remove <session_id> <source>`
 
-## Complete Flag Reference
+## Common Config Flags
+
+Most session-aware commands accept:
+
+- `--config <pipeline.yml>`
+- `--campaign <id>`
+- `--campaign-file <campaign.yml>`
+- `--session <session.yml>`
+- `--session-id <session_id>`
+- `--previous-session-id <session_id>`
+
+Rules:
+
+- `--campaign` and `--campaign-file` are mutually exclusive.
+- `--session` is not used by `session init`.
+- if both positional `<session_id>` and `--session-id` are provided, values must match.
+- `clean --all` cannot be combined with campaign/session selectors.
+
+## Session ID Input Rules
+
+Session-aware commands accept one of these forms:
+
+- positional session ID: `... <session_id>`
+- compatibility flag: `... --session-id <session_id>`
+
+When both are present, command parsing requires an exact match.
+
+Commands with additional positionals keep their command-specific order:
+
+- `run-stage <stage> <session_id>` or `run-stage <stage> --session-id <session_id>`
+- `session locks add <session_id> <source>` or `session locks add --session-id <session_id> <source>`
+- `session locks remove <session_id> <source>` or `session locks remove --session-id <session_id> <source>`
+
+## Command Reference
 
 ### `run`
 
-- `--config <path>`: optional explicit `pipeline.yml` path.
-- `--campaign <path>`: optional explicit `campaign.yml` path.
-- `--session <path>`: optional explicit `session.yml` path.
-- `--session-id <value>`: session template variable value.
-- `--previous-session-id <value>`: previous-session template variable value.
-- `--force`: force stage execution.
-- `--artifacts <names>`: analyze artifact keys to execute (repeatable or comma-separated).
+```bash
+narratio run <session_id> [--force] [--artifacts <name[,name...]>] [...common config flags]
+```
 
-### `plan`
+Behavior:
 
-- `--config <path>`
-- `--campaign <path>`
-- `--session <path>`
-- `--session-id <value>`
-- `--previous-session-id <value>`
-- `--force`
-
-### `resume`
-
-- `--config <path>`
-- `--campaign <path>`
-- `--session <path>`
-- `--session-id <value>`
-- `--previous-session-id <value>`
-- `--force`
-- `--artifacts <names>`: analyze artifact keys to execute (repeatable or comma-separated).
+- evaluates full stage order;
+- skips already-succeeded stages unless `--force` is set;
+- continues interrupted or partially completed sessions by running non-succeeded stages;
+- writes session and run manifests.
 
 ### `run-stage`
 
-- `--config <path>`
-- `--campaign <path>`
-- `--session <path>`
-- `--session-id <value>`
-- `--previous-session-id <value>`
-- `--force`
-- `--artifacts <names>`: analyze artifact keys to execute (repeatable or comma-separated).
-- positional `<stage>`: required stage name.
-
-### `analyze`
-
-- `--config <path>`
-- `--campaign <path>`
-- `--session <path>`
-- `--session-id <value>`
-- `--previous-session-id <value>`
-- `--artifacts <names>`: analyze artifact keys to execute (repeatable or comma-separated).
-
-`analyze` is force-by-design and does not accept `--force`.
+```bash
+narratio run-stage <stage> <session_id> [--force] [--artifacts <name[,name...]>] [...common config flags]
+```
 
 Valid stage names:
 
@@ -93,439 +94,187 @@ Valid stage names:
 - `normalize`
 - `trim`
 - `analyze`
-- `archive`
+- `publish`
 - `notify`
 
-### `restore`
+Rules:
 
-- `--config <path>`
-- `--campaign <path>`
-- `--session <path>`
-- `--session-id <value>`
-- `--previous-session-id <value>`
-- `--dry-run`: plan restore actions without writing local files.
-- `--force`: overwrite local conflicting files with remote archive files.
-- `--include-audio`: include durable archived `audio/**` files in restore scope.
-
-### `clean`
-
-- `--session-id <value>`: required for session cleanup unless `--all` is set.
-- `--config <path>`
-- `--campaign <path>`
-- `--session <path>`
-- `--previous-session-id <value>`
-- `--all`: clean all local session work/spool state using pipeline config only.
-- `--dry-run`: print cleanup targets without deleting.
-- `--clear-cache`: also remove matching S3 audio cache entries.
-
-### `status`
-
-- `--manifest <path>`: inspect one manifest file.
-- `--config <path>`
-- `--campaign <path>`
-- `--session <path>`
-- `--session-id <value>`
-- `--previous-session-id <value>`
-
-### `session validate`
-
-- `--config <path>`
-- `--campaign <path>`
-- `--session <path>`
-- `--session-id <value>`
-- `--previous-session-id <value>`
-
-### `session init`
-
-- `--config <path>`: required.
-- `--campaign <path>`: required.
-- `--session-id <value>`: required.
-- `--output <path>`: local `session.yml` target; mutually exclusive with `--remote`.
-- `--remote`: write remote `session.yml` to the canonical session prefix; mutually exclusive with `--output`.
-- `--previous-session-id <value>`
-- `--date <value>`
-- `--title <value>`
-- `--audio-s3-prefix <prefix>`: defaults to `audio/` when neither audio flag is provided.
-- `--audio-dir <path>`: local audio directory; mutually exclusive with `--audio-s3-prefix`.
-- `--force`: overwrite existing local or remote target.
-
-### `artifacts list`
-
-- `--config <path>`
-- `--campaign <path>`
-- `--session <path>`
-- `--session-id <value>`
-- `--previous-session-id <value>`
-- `--remote`: check remote availability for configured archive promotion destinations.
-
-### `locks`
-
-- `--session-id <value>`: required for list, add, and remove.
-- `--config <path>`: optional explicit `pipeline.yml` path.
-- `--campaign <path>`: optional explicit `campaign.yml` path.
-- `--session <path>`: optional explicit `session.yml` path.
-- `--previous-session-id <value>`: optional session template value.
-- `add <source>`: add a remote lock for one artifact or transcript source.
-- `add --reason <text>`: record an optional remote lock reason.
-- `add --force`: update the reason for an existing remote lock.
-- `remove <source>`: remove one remote lock.
-
-## Command Reference
-
-### `run`
-
-Purpose:
-- Execute configured stages in canonical order.
-
-Syntax:
-
-```bash
-narratio run [--config <pipeline.yml>] [--campaign <campaign.yml>] [--session <session.yml>] [--session-id <id>] [--previous-session-id <id>] [--force] [--artifacts <name[,name...]>]
-```
-
-Success output:
-- `narratio run: session <session_id>; executed=<n> skipped=<n>; manifest=<path>`
-
-Common failure cases:
-- missing system default config/campaign/session paths when flags omitted.
-- missing local session plus missing/unavailable remote `session.yml`.
-- invalid template/rendered session mismatch.
-- unknown/invalid `--artifacts` value.
-- `--artifacts` with unknown configured artifact key.
-
-### `plan`
-
-Purpose:
-- Validate config, load secrets (if configured), prepare workdir, and print stage run/skip decisions.
-
-Syntax:
-
-```bash
-narratio plan [--config <pipeline.yml>] [--campaign <campaign.yml>] [--session <session.yml>] [--session-id <id>] [--previous-session-id <id>] [--force]
-```
-
-Success output includes:
-- `narratio plan: workdir prepared at <path>`
-- one line per stage (`<stage>: run|skip`)
-- `totals: run=<n> skip=<n>`
-
-Common failure cases:
-- same config/campaign/session discovery and validation failures as `run`.
-- remote session fallback failures when local session discovery misses.
-- secrets directory read failures when `pipeline.secrets.env_dir` is configured.
-
-### `resume`
-
-Purpose:
-- Continue from session-manifest stage status.
-
-Syntax:
-
-```bash
-narratio resume [--config <pipeline.yml>] [--campaign <campaign.yml>] [--session <session.yml>] [--session-id <id>] [--previous-session-id <id>] [--force] [--artifacts <name[,name...]>]
-```
-
-Success output:
-- `narratio resume: session <session_id> has no remaining stages`
-- or `narratio resume: session <session_id>; executed=<n> skipped=<n>; manifest=<path>`
-
-Common failure cases:
-- same discovery/template/validation failures as `run`.
-- manifest load errors when existing manifest is unreadable.
-- invalid or unknown artifact selections.
-
-### `status`
-
-Purpose:
-- Inspect one manifest file, or inspect configured local/remote state for a session.
-
-Syntax:
-
-```bash
-narratio status --manifest <manifest.json>
-narratio status [--config <pipeline.yml>] [--campaign <campaign.yml>] [--session <session.yml>] [--session-id <id>] [--previous-session-id <id>]
-```
-
-Manifest output includes:
-- `session_id: <id>`
-- `updated_at: <timestamp>`
-- `stages:` entries (`- <stage>: <status>`)
-
-Session output includes:
-- session ID, campaign, workspace, session config source.
-- local manifest state when present.
-- remote current archive state when storage is configured.
-- catalog-based remote output availability for expected transcript and artifact sources.
-- effective archive locks and conservative next actions.
-
-Common failure cases:
-- missing `--manifest` when no config/session flags are provided.
-- unreadable or invalid manifest path.
-- invalid config or remote session fallback failure in session mode.
-
-### `session validate`
-
-Purpose:
-- Run read-only preflight checks for a session.
-
-Syntax:
-
-```bash
-narratio session validate [--config <pipeline.yml>] [--campaign <campaign.yml>] [--session <session.yml>] [--session-id <id>] [--previous-session-id <id>]
-```
-
-Checks include:
-- effective config and session source.
-- stable input files.
-- local or remote audio availability.
-- previous-session requirements.
-- archive promotions and effective locks.
-
-Warnings do not fail the command. Any `ERROR` finding exits non-zero.
-
-### `session init`
-
-Purpose:
-- Create a strict-decoded session skeleton locally or in object storage.
-
-Syntax:
-
-```bash
-narratio session init --config <pipeline.yml> --campaign <campaign.yml> --session-id <id> --output ./session.yml
-narratio session init --config <pipeline.yml> --campaign <campaign.yml> --session-id <id> --remote
-```
-
-Behavior:
-- exactly one of `--output` or `--remote` is required.
-- remote writes target `{root_prefix}/campaigns/{campaign}/sessions/{session_id}/session.yml`.
-- existing local or remote targets fail unless `--force` is passed.
-- remote writes use existence checks, not compare-and-swap.
-
-### `artifacts list`
-
-Purpose:
-- List built-in, configured, previous-session, promoted, and locked artifact sources.
-
-Syntax:
-
-```bash
-narratio artifacts list [--config <pipeline.yml>] [--campaign <campaign.yml>] [--session <session.yml>] [--session-id <id>] [--previous-session-id <id>] [--remote]
-```
-
-`--remote` checks promoted top-level object availability through the storage adapter. Remote markers appear only in the `Promoted` section, which reports each configured archive promotion destination and includes `dest=<path>` when that destination differs from the source's canonical path.
-
-### `locks`
-
-Purpose:
-- Inspect and mutate source-based archive promotion locks for one session.
-
-Syntax:
-
-```bash
-narratio locks --session-id <id>
-narratio locks add --session-id <id> [--reason <text>] [--force] <source>
-narratio locks remove --session-id <id> <source>
-```
-
-Behavior:
-- `--session-id` is required for list, add, and remove.
-- optional `--config`, `--campaign`, and `--session` override default config discovery.
-- list mode prints effective locks from static `pipeline.archive.locks` and remote `{session_prefix}/locks.yml`.
-- `locks add` writes only the remote lock store and fails if the source is already locked by pipeline config.
-- `locks remove` removes only remote locks and cannot remove static pipeline locks.
-- `locks add --force` is required to update an existing remote lock reason.
-
-Examples:
-
-```bash
-narratio locks --session-id 2026-04-04
-narratio locks add --session-id 2026-04-04 --reason "manual transcript review" narratio.transcript.trimmed
-narratio locks remove --session-id 2026-04-04 narratio.transcript.trimmed
-```
-
-### `run-stage`
-
-Purpose:
-- Execute exactly one stage.
-
-Syntax:
-
-```bash
-narratio run-stage [--config <pipeline.yml>] [--campaign <campaign.yml>] [--session <session.yml>] [--session-id <id>] [--previous-session-id <id>] [--force] [--artifacts <name[,name...]>] <stage>
-```
-
-Success output:
-- `narratio run-stage: stage=<name> executed=<n> skipped=<n> force=<true|false>; manifest=<path>`
-
-`--artifacts` behavior:
-- accepted only when `<stage>` is `analyze`.
-- names are normalized (trimmed, deduplicated, sorted).
-- unknown configured artifact keys fail.
-
-Common failure cases:
-- missing stage positional arg.
-- unknown stage name.
-- using `--artifacts` with any non-`analyze` stage.
+- `--artifacts` is accepted only for `analyze` and `publish` stage targets.
 
 ### `analyze`
 
-Purpose:
-- Force-rerun the analyze stage.
-- Provide a shorter equivalent for `narratio run-stage --force analyze`.
-
-Syntax:
-
 ```bash
-narratio analyze [--config <pipeline.yml>] [--campaign <campaign.yml>] [--session <session.yml>] [--session-id <id>] [--previous-session-id <id>] [--artifacts <name[,name...]>]
+narratio analyze <session_id> [--artifacts <name[,name...]>] [...common config flags]
 ```
 
-Success output:
-- `narratio analyze: executed=<n> skipped=<n> force=true; manifest=<path>`
-
-Common failure cases:
-- positional arguments.
-- `--force`, because force is implicit.
-- unknown configured artifact keys.
-
-### `restore`
-
-Purpose:
-- Restore durable session state (`manifest.json`, `transcripts/**`, `artifacts/**`, `previous/**`, and optional `audio/**`) from the committed remote archive current state.
-
-Syntax:
+Equivalent to:
 
 ```bash
-narratio restore [--config <pipeline.yml>] [--campaign <campaign.yml>] [--session <session.yml>] [--session-id <id>] [--previous-session-id <id>] [--dry-run] [--force] [--include-audio]
+narratio run-stage analyze <session_id> --force [...common config flags]
 ```
 
-Success output (dry-run):
-- `Restore plan for <campaign>/<session_id>`
-- `Remote run: <run_id>`
-- `Would download: <n>`
-- `Would skip unchanged: <n>`
-- `Conflicts: <n>`
+### `publish`
 
-Success output (non-dry-run):
-- `Restored session archive for <campaign>/<session_id>`
-- `Remote run: <run_id>`
-- `Downloaded: <n>`
-- `Skipped unchanged: <n>`
-- `Conflicts: <n>`
+```bash
+narratio publish <session_id> [--artifacts <name[,name...]>] [...common config flags]
+```
 
-Common failure cases:
-- storage backend is not configured.
-- remote `current/run_id.txt` missing/empty.
-- remote `current/manifest.json` missing or invalid.
-- remote manifest session/campaign mismatch.
-- local conflicts without `--force`.
-- session lock conflict.
+Equivalent to:
 
-When `--include-audio` is set, S3 audio files are restored through the shared audio cache. Cache hits avoid re-downloading large audio objects.
+```bash
+narratio run-stage publish <session_id> --force [...common config flags]
+```
 
 ### `clean`
 
-Purpose:
-- Remove local Narratio work/spool state for testing, reruns, or recovery from corrupted local files.
-- Preserve durable S3 audio cache state unless `--clear-cache` is passed.
-
-Syntax:
-
 ```bash
-narratio clean --session-id <id> [--config <pipeline.yml>] [--campaign <campaign.yml>] [--session <session.yml>] [--previous-session-id <id>] [--dry-run] [--clear-cache]
-narratio clean --all [--config <pipeline.yml>] [--dry-run] [--clear-cache]
+narratio clean <session_id> [--dry-run] [--clear-cache] [...common config flags]
+narratio clean --all [--dry-run] [--clear-cache] [--config <pipeline.yml>]
 ```
 
-Session cleanup deletes:
-- `{workspace.root}/work/{campaign}/{session_id}`
-- `{spool.root}/{campaign}/{session_id}`
+Behavior:
 
-All-session cleanup deletes:
-- `{workspace.root}/work`
-- the contents of `{spool.root}`, while preserving the spool root directory itself.
+- session mode removes:
+  - `{workspace.root}/work/{campaign}/{session_id}`
+  - `{spool.root}/{campaign}/{session_id}`
+- `--all` removes:
+  - `{workspace.root}/work/*`
+  - direct children under `{spool.root}`
+- cache remains unless `--clear-cache` is provided.
 
-Cache behavior:
-- cache is preserved by default.
-- `--clear-cache` in session mode removes cached S3 audio files for the resolved session.
-- `--all --clear-cache` removes the configured Narratio S3 audio cache namespace for the configured bucket/root prefix.
-- `--clear-cache` does not delete arbitrary files under `pipeline.cache.root`.
+### `session plan`
 
-Common failure cases:
-- missing `--session-id` when `--all` is not set.
-- combining `--all` with `--campaign`, `--session`, `--session-id`, or `--previous-session-id`.
-- unsafe cleanup target, such as a symlink, a non-directory session target, a configured root directory, or a path outside the configured root.
+```bash
+narratio session plan <session_id> [--force] [...common config flags]
+```
+
+Validates config, prepares local workdir layout, and prints run/skip decisions for each stage.
+
+### `session validate`
+
+```bash
+narratio session validate <session_id> [...common config flags]
+```
+
+Read-only preflight checks for config validity, required inputs, audio mode, previous-session requirements, publish outputs, and effective locks.
+
+### `session status`
+
+```bash
+narratio session status <session_id> [...common config flags]
+```
+
+Prints local manifest state and, when storage is available, remote current-state and published-output status.
+
+### `session init`
+
+```bash
+narratio session init <session_id> --output ./session.yml [options]
+narratio session init <session_id> --remote [options]
+```
+
+Required target selection:
+
+- exactly one of:
+  - `--output <path>`
+  - `--remote`
+
+Options:
+
+- `--config <pipeline.yml>`
+- `--campaign <id>` or `--campaign-file <campaign.yml>`
+- `--previous-session-id <id>`
+- `--date <YYYY-MM-DD>`
+- `--title <text>`
+- `--audio-dir <path>`
+- `--audio-s3-prefix <prefix>`
+- `--force`
+
+Rules:
+
+- `--audio-dir` and `--audio-s3-prefix` are mutually exclusive.
+- if campaign `session_template_file` is configured, `session init` renders it.
+- generated session YAML must be concrete (no unresolved `{{ ... }}` placeholders).
+
+### `session restore`
+
+```bash
+narratio session restore <session_id> [--dry-run] [--force] [--include-audio] [...common config flags]
+```
+
+Behavior:
+
+- discovers committed remote current state;
+- plans local restores;
+- writes `reports/restore-latest.json` on execution;
+- blocks conflicting overwrites unless `--force` is set.
+
+Default restore scope:
+
+- `manifest.json`
+- `transcripts/**`
+- `artifacts/**`
+- `previous/**` when required by configured previous-session inputs
+
+`audio/**` is included only with `--include-audio`.
+
+### `session artifacts`
+
+```bash
+narratio session artifacts <session_id> [--remote] [...common config flags]
+```
+
+Lists effective built-in and configured artifact sources, publish rules, lock state, and optional remote published-state availability.
+
+### `session locks`
+
+```bash
+narratio session locks <session_id> [...common config flags]
+narratio session locks add <session_id> <source> [--reason <text>] [--force] [...common config flags]
+narratio session locks remove <session_id> <source> [...common config flags]
+```
+
+Behavior:
+
+- list mode merges static `pipeline.publish.locks` with remote `{session_prefix}/locks.yml`;
+- add/remove mutate only remote locks;
+- static locks from pipeline config cannot be removed by CLI commands.
+
+## `--artifacts` Selection Rules
+
+- accepted on `run`, `run-stage`, `analyze`, and `publish`;
+- names must exist in `pipeline.scriptorium.artifacts`;
+- empty entries are invalid;
+- repeated names are deduplicated.
+
+Effects:
+
+- filters analyze execution to selected configured artifacts;
+- filters publish rules that source `narratio.artifact.<name>`;
+- does not filter built-in transcript/bounds publish sources.
 
 ## Common Workflows
 
-Default-discovery run:
+Run full pipeline:
 
 ```bash
-narratio run --session-id 2026-04-04
+narratio run 2026-04-04
 ```
 
-Run only selected analyze artifacts:
+Dry-run restore plan:
 
 ```bash
-narratio run --session-id 2026-04-04 --artifacts session_recap,player_handout
+narratio session restore 2026-04-04 --dry-run
 ```
 
-Resume with selected analyze artifacts:
+Generate a concrete session file from template/default structure:
 
 ```bash
-narratio resume --session-id 2026-04-04 --artifacts player_handout
+narratio session init 2026-04-04 --output ./session.yml --date 2026-04-04 --title "Session 12"
 ```
 
-Force-rerun analyze with selected artifacts:
+Force publish only:
 
 ```bash
-narratio analyze --session-id 2026-04-04 --artifacts player_handout
+narratio publish 2026-04-04
 ```
-
-Preview restore actions without writes:
-
-```bash
-narratio restore --session-id 2026-04-04 --dry-run
-```
-
-Restore and then force analyze:
-
-```bash
-narratio restore --session-id 2026-04-04
-narratio analyze --session-id 2026-04-04
-```
-
-Rehydrate canonical previous-session inputs after artifact-input changes:
-
-```bash
-narratio run-stage --session-id 2026-04-04 --force prepare
-```
-
-Reset local state before testing restore:
-
-```bash
-narratio clean --session-id 2026-04-04 --dry-run
-narratio clean --session-id 2026-04-04
-narratio restore --session-id 2026-04-04 --include-audio
-```
-
-Clean all local sessions while keeping cached S3 audio:
-
-```bash
-narratio clean --all
-```
-
-## Diagnostic / Recovery Commands
-
-Inspect stage status:
-
-```bash
-narratio status --manifest <manifest.json>
-```
-
-Get manifest path from previous output:
-- `run`, `resume`, `run-stage`, and `analyze` print `manifest=<path>` on success.
-
-## `--artifacts` and `--force`
-
-- `--artifacts` filters which configured artifacts are executable when analyze runs.
-- `--artifacts` does not imply `--force`.
-- if analyze is already `succeeded` and `--force` is not set, runner-level skip still applies.

docs/config.md

@@ -1,263 +1,131 @@
-# Configuration
+# Configuration Reference
 
-## 1. Overview
+## Purpose
 
-Narratio loads three YAML files:
+Narratio resolves three YAML documents:
 
-- `pipeline.yml`: pipeline-level runtime configuration.
-- `campaign.yml`: stable campaign identity and campaign-level input defaults.
-- `session.yml`: per-session metadata and input selection, loaded locally or from the configured S3 backend.
+- `pipeline.yml`: pipeline/runtime settings
+- `campaign.yml`: campaign identity and stable input defaults
+- `session.yml`: session identity, metadata, and audio source selection
 
-These commands load and validate all three files before running:
-
-- `narratio run`
-- `narratio plan`
-- `narratio resume`
-- `narratio run-stage`
-- `narratio restore`
-
-Behavior:
-
-- strict YAML decode is enabled (`KnownFields(true)`): unknown fields fail.
-- session templates render before session YAML decode.
-- remote `session.yml` uses the same strict decode and template behavior as local `session.yml`.
-- defaults are applied for optional pipeline fields.
-- campaign-level stable input paths fill missing session input paths.
-- session-level stable input paths override campaign-level input paths.
-- validation enforces required fields, value formats, and cross-field constraints.
-
-## 2. Config file discovery
-
-These commands use the same config discovery behavior:
-
-- `narratio run`
-- `narratio plan`
-- `narratio resume`
-- `narratio run-stage`
-- `narratio restore`
-
-Pipeline config lookup:
-
-- if `--config <path>` is provided, that path is used.
-- if omitted, Narratio searches in order:
-  1. `/usr/local/etc/narratio/pipeline.yml`
-  2. `/etc/narratio/pipeline.yml`
-- first existing file wins.
-
-Campaign config lookup:
-
-- if `--campaign <path>` is provided, that path is used.
-- if omitted, Narratio searches in order:
-  1. `/usr/local/etc/narratio/campaign.yml`
-  2. `/etc/narratio/campaign.yml`
-- first existing file wins.
-
-Session config lookup:
-
-- if `--session <path>` is provided, that path is used.
-- if `--session` is omitted, Narratio searches locally in order:
-  1. `/usr/local/etc/narratio/session.yml`
-  2. `/etc/narratio/session.yml`
-- first existing local file wins.
-- if no local session file is found, `--session-id <value>` is present, storage is configured, and campaign identity is resolved, Narratio loads remote `session.yml` from:
-  - `{root_prefix}/campaigns/{campaign}/sessions/{session_id}/session.yml`
-- local discovery always runs before remote fallback.
-- local files in the current working directory are used only when passed explicitly, for example `--config ./pipeline.yml --campaign ./campaign.yml --session ./session.yml`.
-
-## 3. Session templating
-
-Template behavior for local and remote `session.yml`:
-
-- supported placeholders:
-  - `{{session_id}}`
-  - `{{ session_id }}`
-  - `{{previous_session_id}}`
-  - `{{ previous_session_id }}`
-- `--session-id <value>` supplies the placeholder value.
-- `--previous-session-id <value>` supplies the previous-session placeholder value.
-- unresolved placeholders fail load.
-- if rendered `session_id` mismatches `--session-id`, load fails.
-- if rendered `previous_session_id` mismatches `--previous-session-id`, load fails.
-
-## 4. Minimal config set
+## Discovery and Selection
 
 ### `pipeline.yml`
 
-```yaml
-whisperx:
-  transcribe_url: "https://transcription.example.com/transcribe"
-```
+When `--config` is omitted, search order is:
 
-Why this is sufficient:
-
-- `whisperx.transcribe_url` is required.
-- `workspace.root` defaults to `/var/lib/narratio`.
-- optional sections (`seriatim`, `audita`, `archive`, `scriptorium`, `trim`, `normalize`, etc.) receive defaults or stay inactive.
+1. `/usr/local/etc/narratio/pipeline.yml`
+2. `/etc/narratio/pipeline.yml`
 
 ### `campaign.yml`
 
+Selection rules:
+
+- if `--campaign-file` is set, use that path;
+- else if `--campaign <id>` is set, use `{pipeline.campaigns.root}/{id}/campaign.yml`;
+- else use `{pipeline.campaigns.root}/{pipeline.campaigns.default_campaign_id}/campaign.yml`.
+
+### `session.yml`
+
+When `--session` is omitted, local search order is:
+
+1. `/usr/local/etc/narratio/session.yml`
+2. `/etc/narratio/session.yml`
+
+If local session discovery fails and a `session_id` is known, Narratio attempts remote session loading from:
+
+- `{root_prefix}/campaigns/{campaign}/sessions/{session_id}/session.yml`
+
+using configured object storage.
+
+## Validation and Merge Rules
+
+- YAML decode is strict (`KnownFields(true)`): unknown fields fail load.
+- Session files must be concrete; unresolved `{{ ... }}` placeholders fail load.
+- Pipeline defaults are applied before validation.
+- Campaign and session identities must agree.
+- Stable files (`speakers_file`, `autocorrect_file`, `glossary_file`) resolve from session overrides when provided, otherwise from campaign defaults.
+- Exactly one audio mode must be configured in session input:
+  - local (`audio_dir` or `audio_files`), or
+  - S3 (`audio_s3.prefix`).
+
+## Minimal Working Configuration
+
+`pipeline.yml`
+
 ```yaml
-campaign: sample-campaign
+campaigns:
+  root: /usr/local/share/narratio/campaigns
+  default_campaign_id: sample-campaign
+whisperx:
+  transcribe_url: https://transcription.example.com/transcribe
+```
+
+`campaign.yml`
+
+```yaml
+campaign_id: sample-campaign
 inputs:
   speakers_file: ./speakers.yml
   autocorrect_file: ./autocorrect.yml
   glossary_file: ./glossary.yml
 ```
 
-Why this is sufficient:
-
-- `campaign` supplies the stable campaign identity.
-- stable input files are required and resolve relative to `campaign.yml` when copied during `prepare`.
-
-### `session.yml`
+`session.yml` (local audio)
 
 ```yaml
-session_id: "{{ session_id }}"
+session_id: 2026-05-03
 inputs:
   audio_dir: ./audio
 ```
 
-Why this is sufficient:
+## Secrets Handling
 
-- `session_id` is required and can be rendered from `--session-id`.
-- `campaign` can be omitted because it is supplied by `campaign.yml`.
-- stable input paths can be omitted because `campaign.yml` supplies defaults.
-- local `audio_dir` resolves relative to `session.yml`.
+- Do not place raw secrets in YAML.
+- Use env var names in config (for example `pipeline.audita.llm_api_key_env`).
+- Optionally load env files from `pipeline.secrets.env_dir`.
+- Commands that need storage/auth load filesystem secrets before constructing adapters.
 
-Minimal local-file usage:
+## Publish Configuration Summary
 
-```bash
-narratio run --config /path/to/pipeline.yml --campaign ./campaign.yml --session ./session.yml --session-id 2026-05-03
-```
-
-Previous-session-enabled variant:
+Publish rules live under `pipeline.publish`.
 
 ```yaml
-session_id: "{{ session_id }}"
-previous_session_id: "{{ previous_session_id }}"
-inputs:
-  audio_dir: ./audio
-```
-
-```bash
-narratio run --config /path/to/pipeline.yml --campaign ./campaign.yml --session ./session.yml --session-id 2026-05-03 --previous-session-id 2026-04-26
-```
-
-## 5. Production-oriented config set
-
-### `pipeline.yml`
-
-```yaml
-workspace:
-  root: /var/lib/narratio/workspace
-  cleanup_after_archive: true
-
-storage:
-  backend: s3
-  s3:
-    bucket: my-dnd-archive
-    root_prefix: dnd
-    region: us-east-1
-    access_key_id_env: OBJECT_STORAGE_KEY_ID
-    secret_access_key_env: OBJECT_STORAGE_KEY
-
-spool:
-  root: /var/spool/narratio
-  delete_audio_after_archive: true
-
-cache:
-  root: /var/cache/narratio
-  s3_audio: true
-
-archive:
+publish:
   enabled: true
   upload_run: true
-  promote_artifacts:
-    - source: narratio.transcript.trimmed
-      dest: transcripts/trimmed.json
+  outputs:
+    - source: narratio.transcript.final_trimmed
+      dest: transcripts/final.trimmed.json
       required: true
     - source: narratio.artifact.session_recap
       dest: artifacts/session_recap.md
       required: true
   locks:
     - source: narratio.artifact.session_recap
-      reason: Final recap was manually edited.
-
-whisperx:
-  transcribe_url: "https://transcription.example.com/transcribe"
-
-scriptorium:
-  artifacts:
-    session_recap:
-      enabled: true
-      prompt_id: dnd.session_recap
-      output_path: artifacts/session_recap.md
-      inputs:
-        transcript:
-          source: narratio.transcript.trimmed
-          required: true
-        previous_recap:
-          source: narratio.previous_session.artifact.session_recap
-          required: false
+      reason: manual post-publish edits
 ```
 
-### `campaign.yml`
+Rules:
 
-```yaml
-campaign: forsaken
-inputs:
-  speakers_file: /srv/narratio/campaigns/forsaken/speakers.yml
-  autocorrect_file: /srv/narratio/campaigns/forsaken/autocorrect.yml
-  glossary_file: /srv/narratio/campaigns/forsaken/glossary.yml
-```
+- `outputs[].source` is required.
+- `outputs[].dest` may be omitted when derivable from source.
+- `outputs[].required` defaults to `true`.
+- static locks (`pipeline.publish.locks`) merge with remote locks (`{session_prefix}/locks.yml`), with static locks taking precedence on duplicates.
 
-### Local `session.yml`
+## Full Schema
 
-```yaml
-session_id: "{{ session_id }}"
-previous_session_id: "{{ previous_session_id }}"
-date: 2026-05-03
-title: The Black Cabin
-inputs:
-  audio_s3:
-    prefix: audio/
-```
+### Pipeline
 
-### S3-first session config
-
-For S3-first operation, upload the same `session.yml` content to:
-
-```text
-{root_prefix}/campaigns/{campaign}/sessions/{session_id}/session.yml
-```
-
-Then run with explicit or discovered pipeline/campaign config and no `--session`:
-
-```bash
-narratio run --config /usr/local/etc/narratio/pipeline.yml --campaign /usr/local/etc/narratio/campaign.yml --session-id 2026-05-03 --previous-session-id 2026-04-26
-```
-
-Operational notes:
-
-- archive promotion is explicit and source-based via `archive.promote_artifacts`.
-- `source` is required; `dest` is optional and derived when omitted.
-- `archive.locks` skips top-level promotion overwrites for static locked sources while preserving run-local uploads.
-- operator-created mutable locks are stored at `{root_prefix}/campaigns/{campaign}/sessions/{session_id}/locks.yml` and are merged with static locks.
-- Narratio does not auto-promote all generated analyze artifacts.
-- `restore` reads the same config/campaign/session inputs and restore scope is bounded by committed archive current state.
-- `clean` removes workspace/spool state by default and preserves `pipeline.cache.root` unless `--clear-cache` is passed.
-
-## 6. Full pipeline reference
-
-| Path | Type | Required | Default |
+| Field | Type | Required | Default / Rule |
 | --- | --- | --- | --- |
 | `pipeline.workspace.root` | string | No | `/var/lib/narratio` |
-| `pipeline.workspace.cleanup_after_archive` | bool | No | `false` |
-| `pipeline.secrets.env_dir` | string | Conditional | none |
+| `pipeline.workspace.cleanup_after_publish` | bool | No | `false` |
+| `pipeline.campaigns.root` | string | No | `/usr/local/share/narratio/campaigns` |
+| `pipeline.campaigns.default_campaign_id` | string | No | empty |
+| `pipeline.secrets.env_dir` | string | No | empty |
 | `pipeline.storage.backend` | string | No | empty |
-| `pipeline.storage.bucket` | string | No | empty |
-| `pipeline.storage.prefix` | string | No | empty |
-| `pipeline.storage.s3.bucket` | string | Conditional | empty |
+| `pipeline.storage.s3.bucket` | string | Conditional | required for S3 session-audio and for publish upload when backend is `s3` |
 | `pipeline.storage.s3.root_prefix` | string | No | `dnd` |
 | `pipeline.storage.s3.region` | string | No | empty |
 | `pipeline.storage.s3.endpoint` | string | No | empty |
@@ -265,26 +133,26 @@ Operational notes:
 | `pipeline.storage.s3.access_key_id_env` | string | No | `OBJECT_STORAGE_KEY_ID` |
 | `pipeline.storage.s3.secret_access_key_env` | string | No | `OBJECT_STORAGE_KEY` |
 | `pipeline.spool.root` | string | No | `/var/spool/narratio` |
-| `pipeline.spool.delete_audio_after_archive` | bool | No | `false` |
+| `pipeline.spool.delete_audio_after_publish` | bool | No | `false` |
 | `pipeline.cache.root` | string | No | `/var/cache/narratio` |
 | `pipeline.cache.s3_audio` | bool | No | `true` |
-| `pipeline.archive.enabled` | bool | No | `true` |
-| `pipeline.archive.upload_run` | bool | No | `true` |
-| `pipeline.archive.promote_artifacts[]` | list | No | trimmed transcript rule |
-| `pipeline.archive.promote_artifacts[].source` | string | Yes (per rule) | none |
-| `pipeline.archive.promote_artifacts[].dest` | string | No | derived from source |
-| `pipeline.archive.promote_artifacts[].required` | bool | No | `true` |
-| `pipeline.archive.locks[]` | list | No | empty |
-| `pipeline.archive.locks[].source` | string | Yes (per lock) | none |
-| `pipeline.archive.locks[].reason` | string | No | empty |
-| `pipeline.whisperx.transcribe_url` | string | Yes | none |
+| `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[].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` |
+| `pipeline.publish.locks[]` | list | No | empty |
+| `pipeline.publish.locks[].source` | string | Yes (per lock) | must reference supported publish source |
+| `pipeline.publish.locks[].reason` | string | No | empty |
+| `pipeline.whisperx.transcribe_url` | string | Yes | valid URL |
 | `pipeline.whisperx.language` | string | No | `en` |
-| `pipeline.whisperx.timeout` | duration string | No | `30m` |
+| `pipeline.whisperx.timeout` | duration | No | `30m` |
 | `pipeline.whisperx.retries` | int | No | `3` |
-| `pipeline.whisperx.retry_delay` | duration string | No | `2s` |
+| `pipeline.whisperx.retry_delay` | duration | No | `2s` |
 | `pipeline.whisperx.concurrency` | int | No | `2` |
 | `pipeline.seriatim.binary` | string | No | `seriatim` |
-| `pipeline.seriatim.timeout` | duration string | No | `10m` |
+| `pipeline.seriatim.timeout` | duration | No | `10m` |
 | `pipeline.seriatim.output_schema` | string | No | `seriatim-intermediate` |
 | `pipeline.seriatim.coalesce_gap` | float | No | `3.0` |
 | `pipeline.seriatim.report` | bool | No | `true` |
@@ -293,7 +161,7 @@ Operational notes:
 | `pipeline.seriatim.env.backchannel_max_duration` | float | No | unset |
 | `pipeline.seriatim.env.filler_max_duration` | float | No | unset |
 | `pipeline.audita.binary` | string | No | `audita` |
-| `pipeline.audita.timeout` | duration string | No | `3h` |
+| `pipeline.audita.timeout` | duration | No | `3h` |
 | `pipeline.audita.llm_api_key_env` | string | No | empty |
 | `pipeline.audita.modules[]` | list[string] | No | empty |
 | `pipeline.audita.base_url` | string | No | empty |
@@ -307,181 +175,89 @@ Operational notes:
 | `pipeline.audita.output_schema` | string | No | empty |
 | `pipeline.audita.work_dir_retention` | string | No | empty |
 | `pipeline.audita.report` | bool | No | `true` |
-| `pipeline.normalize.output_path` | string | No | `transcripts/normalized.json` |
+| `pipeline.normalize.output_path` | string | No | `transcripts/final.json` |
 | `pipeline.normalize.output_schema` | string | No | `seriatim-intermediate` |
 | `pipeline.normalize.report` | bool | No | `true` |
 | `pipeline.trim.enabled` | bool | No | `false` |
-| `pipeline.trim.output_path` | string | Conditional | none |
-| `pipeline.trim.bounds.prompt_id` | string | Conditional | none |
+| `pipeline.trim.output_path` | string | Conditional | required when trim enabled |
+| `pipeline.trim.bounds.prompt_id` | string | Conditional | required when trim enabled |
 | `pipeline.trim.bounds.profile_id` | string | No | empty |
-| `pipeline.trim.bounds.transcript_input_name` | string | Conditional | none |
-| `pipeline.trim.bounds.output_path` | string | Conditional | none |
-| `pipeline.trim.bounds.timeout` | duration string | No | `10m` |
+| `pipeline.trim.bounds.transcript_input_name` | string | Conditional | required when trim enabled |
+| `pipeline.trim.bounds.output_path` | string | Conditional | required when trim enabled |
+| `pipeline.trim.bounds.timeout` | duration | No | `10m` |
 | `pipeline.trim.bounds.render_debug` | bool | No | `false` |
-| `pipeline.trim.bounds.render_output_path` | string | Conditional | none |
+| `pipeline.trim.bounds.render_output_path` | string | Conditional | required when `render_debug` is true |
 | `pipeline.trim.seriatim.report` | bool | No | `false` |
 | `pipeline.scriptorium.binary` | string | No | `scriptorium` |
 | `pipeline.scriptorium.config_path` | string | No | empty |
-| `pipeline.scriptorium.timeout` | duration string | No | `10m` |
+| `pipeline.scriptorium.timeout` | duration | No | `10m` |
 | `pipeline.scriptorium.render_debug` | bool | No | `false` |
 | `pipeline.scriptorium.artifacts` | map | No | empty |
-| `pipeline.scriptorium.artifacts.<name>.enabled` | bool | No | `false` |
-| `pipeline.scriptorium.artifacts.<name>.depends_on[]` | list[string] | No | empty |
-| `pipeline.scriptorium.artifacts.<name>.render_debug` | bool | No | unset |
-| `pipeline.scriptorium.artifacts.<name>.prompt_id` | string | Conditional | none |
-| `pipeline.scriptorium.artifacts.<name>.profile_id` | string | No | empty |
-| `pipeline.scriptorium.artifacts.<name>.output_path` | string | Conditional | none |
-| `pipeline.scriptorium.artifacts.<name>.timeout` | duration string | No | empty |
-| `pipeline.scriptorium.artifacts.<name>.inputs.<key>.source` | string | Conditional | none |
-| `pipeline.scriptorium.artifacts.<name>.inputs.<key>.artifact` | string | No | empty |
-| `pipeline.scriptorium.artifacts.<name>.inputs.<key>.path` | string | No | empty |
-| `pipeline.scriptorium.artifacts.<name>.inputs.<key>.required` | bool | No | `false` |
-| `pipeline.scriptorium.artifacts.<name>.vars.<key>` | map value | No | empty |
-| `pipeline.analyzer.binary_path` | string | No | empty |
-| `pipeline.analyzer.timeout` | duration string | No | empty |
-| `pipeline.analyzer.artifacts.output_dir` | string | No | empty |
-| `pipeline.analyzer.artifacts.types[]` | list[string] | No | empty |
 | `pipeline.notification.backend` | string | No | empty |
 | `pipeline.notification.recipient` | string | No | empty |
-| `pipeline.notification.timeout` | duration string | No | empty |
+| `pipeline.notification.timeout` | duration | No | `30s` |
 
-Scriptorium artifact-key and dependency rules:
+### Scriptorium Artifact Entries
 
-- artifact keys must match `^[a-z][a-z0-9_]*$`.
-- enabled artifacts require `prompt_id` and `output_path`.
-- `output_path` must be relative, traversal-safe, and under `artifacts/`.
-- configured artifact input sources use `narratio.artifact.<name>`.
-- if input source references `narratio.artifact.<name>`, artifact `<name>` must exist and must be listed in `depends_on`.
-- every `depends_on` entry must be a configured artifact key.
-- self-dependency is rejected.
-- enabled dependency cycles are rejected.
-- any artifact referenced by `depends_on` or `narratio.artifact.<name>` source must define `output_path` (even if not enabled).
+For each `pipeline.scriptorium.artifacts.<name>`:
 
-Allowed `pipeline.scriptorium.artifacts.<name>.inputs.<key>.source` values:
-
-- `narratio.previous_session.artifact.<configured_artifact_key>`
-- `narratio.transcript.merged`
-- `narratio.transcript.polished`
-- `narratio.transcript.full`
-- `narratio.transcript.trimmed`
-- `narratio.bounds.session`
-- `narratio.artifact.<configured_artifact_key>`
-- `previous_session_artifact` (legacy path-based source; uses `inputs.<key>.path`)
-
-`pipeline.archive.promote_artifacts[].source` values:
-
-- `narratio.transcript.merged`
-- `narratio.transcript.polished`
-- `narratio.transcript.full`
-- `narratio.transcript.trimmed`
-- `narratio.bounds.session`
-- `narratio.artifact.<configured_artifact_key>`
-
-`pipeline.archive.locks[].source` accepts the same source values as `pipeline.archive.promote_artifacts[].source`.
-
-Archive promotion destination rules:
-
-- `dest` must be a clean relative path (not absolute, no traversal).
-- duplicate `dest` values are rejected.
-- if `dest` is omitted:
-  - built-in sources derive their canonical destination path;
-  - configured sources derive from `pipeline.scriptorium.artifacts.<name>.output_path`;
-  - derivation failure is a config validation error.
-
-Archive lock rules:
-
-- locks are source-based and do not accept `dest`.
-- duplicate lock sources are rejected.
-- static `pipeline.archive.locks` win over remote mutable locks for the same source.
-- locked promotions are recorded as intentional skips in archive metadata.
-- locked required promotions do not fail archive by default.
-- ordinary `--force` reruns do not override locks.
-
-Remote mutable lock store:
-
-- path: `{root_prefix}/campaigns/{campaign}/sessions/{session_id}/locks.yml`.
-- strict YAML shape: top-level `locks`, each with `source` and optional `reason`.
-- `narratio locks add` and `narratio locks remove` mutate only the remote lock store.
-- writes use existence checks plus `--force` for updates; they are not compare-and-swap atomic.
-
-Restore-related implications:
-
-- restore remote identity requires archive S3 identity to resolve (`pipeline.storage.s3.bucket` and session prefix derivation inputs).
-- restore scope considers committed current state and durable paths (`manifest.json`, `transcripts/**`, `artifacts/**`, `previous/**`, optional `audio/**`).
-- S3 audio downloads use `pipeline.spool.root` for active downloads and `pipeline.cache.root` for reusable cached audio when `pipeline.cache.s3_audio` is true.
-- `pipeline.cache.root` is durable local cache state. It is not workspace state and is preserved by default by `narratio clean`.
-
-## 7. Full campaign reference
-
-| Path | Type | Required | Default |
+| Field | Type | Required | Rule |
 | --- | --- | --- | --- |
-| `campaign.campaign` | string | Yes | none |
-| `campaign.inputs.speakers_file` | string | Yes | none |
-| `campaign.inputs.autocorrect_file` | string | Yes | none |
-| `campaign.inputs.glossary_file` | string | Yes | none |
+| `enabled` | bool | No | `false` if omitted |
+| `depends_on[]` | list[string] | No | must reference configured artifact keys; no self-reference; enabled graph must be acyclic |
+| `render_debug` | bool | No | per-artifact override |
+| `prompt_id` | string | Conditional | required when artifact is enabled |
+| `profile_id` | string | No | empty |
+| `output_path` | string | Conditional | required when enabled; also required when referenced by publish/output/input rules |
+| `timeout` | duration | No | artifact override |
+| `inputs` | map | No | input key names must be non-empty |
+| `vars` | map | No | values must be string or bool |
 
-Campaign input paths may be absolute or relative. Relative paths resolve from the directory containing `campaign.yml`.
+For each artifact input `pipeline.scriptorium.artifacts.<name>.inputs.<input_name>`:
 
-## 8. Full session reference
-
-| Path | Type | Required | Default |
+| Field | Type | Required | Rule |
 | --- | --- | --- | --- |
-| `session.session_id` | string | Yes | none |
-| `session.previous_session_id` | string | No | empty |
-| `session.campaign` | string | No | `campaign.campaign` |
-| `session.date` | string | No | empty |
-| `session.title` | string | No | empty |
-| `session.inputs.audio_dir` | string | Conditional | empty |
-| `session.inputs.audio_files[]` | list[string] | Conditional | empty |
-| `session.inputs.audio_s3.prefix` | string | Conditional | none |
-| `session.inputs.speakers_file` | string | No | `campaign.inputs.speakers_file` |
-| `session.inputs.autocorrect_file` | string | No | `campaign.inputs.autocorrect_file` |
-| `session.inputs.glossary_file` | string | No | `campaign.inputs.glossary_file` |
+| `source` | string | Yes | built-in runtime source, `narratio.artifact.<name>`, or `narratio.previous_session.artifact.<name>` |
+| `artifact` | string | No | optional passthrough adapter field |
+| `path` | string | No | optional passthrough adapter field |
+| `required` | bool | No | optional input requirement |
 
-Session input paths may be absolute or relative. Relative audio paths and session-level stable input overrides resolve from the directory containing `session.yml`. If both `campaign.yml` and `session.yml` specify campaign identity, the values must match.
+### Campaign
 
-Audio-source rule:
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `campaign_id` | string | Yes | canonical campaign identity |
+| `session_template_file` | string | No | used by `session init` when set |
+| `inputs.speakers_file` | string | Yes | stable input default |
+| `inputs.autocorrect_file` | string | Yes | stable input default |
+| `inputs.glossary_file` | string | Yes | stable input default |
 
-- configure exactly one mode:
-  - `audio_dir`, or
-  - `audio_files` (at least one), or
-  - `audio_s3.prefix`
-- `audio_s3` cannot be combined with local audio fields.
+### Session
 
-Previous-session rule:
+| Field | Type | Required in session file | Notes |
+| --- | --- | --- | --- |
+| `session_id` | string | Yes | must match CLI session target when provided |
+| `previous_session_id` | string | No | must not equal `session_id` |
+| `campaign` | string | No | filled from `campaign_id` during resolve if omitted |
+| `date` | string | No | metadata |
+| `title` | string | No | metadata |
+| `inputs.speakers_file` | string | No | overrides campaign stable input |
+| `inputs.autocorrect_file` | string | No | overrides campaign stable input |
+| `inputs.glossary_file` | string | No | overrides campaign stable input |
+| `inputs.audio_dir` | string | Conditional | local audio mode |
+| `inputs.audio_files[]` | list[string] | Conditional | local audio mode |
+| `inputs.audio_s3.prefix` | string | Conditional | S3 audio mode |
 
-- if `session.previous_session_id` is set, it must not equal `session.session_id`.
-- canonical previous-session sources (`narratio.previous_session.artifact.<name>`) are hydrated during `prepare` from archive current state when required by enabled configured artifacts.
+Audio rules:
 
-## 9. Secrets
+- configure local mode (`audio_dir` or `audio_files`) or S3 mode (`audio_s3.prefix`), not both.
 
-Narratio supports filesystem-based secret injection via `pipeline.secrets.env_dir`.
-
-Behavior:
-
-- `env_dir` may be absolute or relative.
-- relative `env_dir` resolves from current working directory.
-- files with valid env-var names (`[A-Za-z_][A-Za-z0-9_]*`) are loaded.
-- values are loaded from file contents with trailing newline trimming.
-- existing process env vars are preserved.
-- invalid names and subdirectories are skipped.
-- missing/unreadable `env_dir` fails command execution.
-
-Guidance:
-
-- do not put secret values directly in YAML.
-- configure env var names in config and provide values via env/secrets files.
-
-## 10. Examples
-
-Maintained examples:
+## Maintained Examples
 
 - `examples/pipeline.minimal.yml`
 - `examples/pipeline.production.yml`
 - `examples/pipeline.full.annotated.yml`
-- `examples/campaign.yml`
-- `examples/session.template.yml`
+- `examples/campaigns/sample-campaign/campaign.yml`
 - `examples/session.local-audio.yml`
 - `examples/session.s3-audio.yml`
-
-These examples are validated by `internal/config` tests.
+- `examples/session.template.yml`

docs/integrations/README.md

@@ -1,15 +1,19 @@
-# Integration Documentation Index
+# Integrations Index
 
 ## Audience
-Developers and LLM coding agents changing Narratio's external integration contracts.
+Developers and coding agents changing Narratio's external integration boundaries.
 
 ## Scope
-Implemented-only reference notes for the external systems Narratio currently integrates with.
+`docs/integrations/` is the implementation-level reference for downstream tool adapter contracts.
 
-## Integration Docs
-- `audita.md`: Audita adapter invocation and validation contract.
-- `seriatim.md`: Seriatim normalize/merge/trim adapter contract.
-- `scriptorium.md`: Scriptorium run/render adapter contract.
+These docs cover what Narratio expects from external tools and what each adapter guarantees back to stage code.
 
-## Canonical Owner
-`docs/integrations/` is the canonical home for external integration reference notes per `docs/documentation/policy.md`.
+## Integration Contracts
+- `audita.md`: transcript polishing adapter (`audita process`).
+- `seriatim.md`: merge/normalize/trim adapter (`seriatim`).
+- `scriptorium.md`: artifact run/render adapter (`scriptorium run|render`).
+
+## Related Canonical Docs
+- `docs/config.md`: operator-facing configuration reference.
+- `docs/internal/adapters.md`: shared adapter boundary and runner wiring.
+- `docs/internal/stage-*.md`: stage-specific integration usage.

docs/integrations/audita.md

@@ -1,66 +1,60 @@
-# Integration: audita
+# Integration: Audita
 
 ## Purpose
-Define Narratio's adapter contract for transcript polishing via Audita CLI subprocess execution.
+Define the Audita adapter contract used by the `polish` stage.
 
-## 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
+## Adapter Boundary
+Interface:
+- `audita.Runner`
+- method: `Run(ctx, PolishRequest) (PolishResult, error)`
 
-Outputs (`audita.PolishResult`):
-- processed transcript path
-- optional report path
-- generated config path
-- stdout/stderr log paths
-- exit code, duration, invoked binary
-- adapter metadata
+Primary implementation:
+- `internal/adapters/audita/SubprocessRunner`
 
-## Boundaries
-Owns:
-- Deterministic CLI argument construction for `audita process`
-- Environment bridging for API credentials
-- Invocation config emission
-- Output validation for processed transcript and report
+Execution mode:
+- subprocess invocation of `audita process`
 
-Does not own:
-- Upstream/downstream stage orchestration
-- Credential sourcing policy beyond required env-var presence check
+## Request Contract
+`PolishRequest` carries:
+- required transcript/glossary/output/work-dir paths;
+- optional report path (required when report mode is enabled);
+- generated config and stdout/stderr log paths;
+- optional module/model/base-url/config/output-schema/concurrency settings.
 
-## 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`
+## Result Contract
+`PolishResult` returns:
+- processed transcript path;
+- optional report path;
+- work dir and generated-config/log paths;
+- exit code, duration, binary provenance;
+- adapter metadata map.
 
-## External Adapters Used
-- Shared subprocess helper (`internal/adapters/subprocess`) to run CLI and capture logs.
+## Validation and Failure Semantics
+Construction fails for invalid static config values, including:
+- empty binary;
+- non-positive timeout;
+- invalid base URL;
+- invalid output schema;
+- invalid work-dir retention value;
+- invalid concurrency values.
 
-## 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.
+Run fails for:
+- missing required request paths;
+- missing required credential env var when configured (`llm_api_key_env`);
+- subprocess execution failure;
+- invalid processed transcript JSON (`segments` array required);
+- invalid report JSON when reporting is enabled.
 
-## Skip and Resume Behavior
-- Adapter has no skip/resume logic. Stage/runner controls this.
+Failure results still include output/log/config/exit metadata for diagnostics.
 
-## 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.
+## Deterministic Behavior
+- CLI args are built from runner config + request in a fixed order.
+- Generated invocation YAML (`audita.generated.v1`) is emitted when requested.
+- Manifest writes are stage-owned; adapter itself is stateless.
 
-## Tests to Inspect Before Changing
-- `internal/adapters/audita/subprocess_test.go`
-- `internal/adapters/audita/fake_test.go`
-- `internal/stage/polish_test.go`
+## Config Mapping
+Config fields consumed through runner/stage wiring are under `pipeline.audita.*`.
 
-## 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.
+Maintained example with Audita config:
+- `examples/pipeline.full.annotated.yml`
+- `examples/pipeline.production.yml`

docs/integrations/scriptorium.md

@@ -1,64 +1,66 @@
-# Integration: scriptorium
+# Integration: Scriptorium
 
 ## Purpose
-Define Narratio's adapter contract for Scriptorium artifact generation and render-debug subprocess invocations.
+Define the Scriptorium adapter contract used by `analyze` and trim-bounds generation in `trim`.
 
-## 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
+## Adapter Boundary
+Interface:
+- `scriptorium.Runner`
+- methods:
+  - `RunArtifact(ctx, RunArtifactRequest)`
+  - `RenderArtifact(ctx, RenderArtifactRequest)`
 
-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
+Primary implementation:
+- `internal/adapters/scriptorium/SubprocessRunner`
 
-## 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
+Execution modes:
+- `scriptorium run`
+- `scriptorium render`
 
-Does not own:
-- Artifact selection policy (`analyze` stage)
-- Bounds semantic validation (`trim` stage)
+## Request Contract
+Both request types carry:
+- binary/config/prompt/profile IDs;
+- input map and vars map;
+- output path;
+- timeout;
+- generated config + stdout/stderr log paths;
+- optional API-key env var name;
+- optional working directory.
 
-## 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`
+## Result Contract
+`ArtifactResult` returns:
+- output/log/generated-config paths;
+- exit code and duration;
+- command mode (`run` or `render`);
+- prompt/profile provenance;
+- `ValidationFailed` marker;
+- metadata map.
 
-## External Adapters Used
-- Shared subprocess helper (`internal/adapters/subprocess`).
+## Validation and Failure Semantics
+Request validation fails for:
+- missing binary, prompt id, or output path;
+- non-positive timeout;
+- empty input/var names;
+- empty input path values;
+- missing required credential env var when `APIKeyEnv` is set.
 
-## State and Manifest Behavior
-- No direct manifest writes.
-- Stage metadata records adapter outputs and command mode.
-- Generated invocation YAML is written when requested.
+Run behavior:
+- subprocess errors propagate with context;
+- `run` exit code `2` is mapped to `ValidationFailed=true`;
+- successful subprocess still fails if output file is missing or empty.
 
-## Skip and Resume Behavior
-- Adapter has no skip/resume logic. Stage/runner controls execution.
+Render behavior:
+- subprocess errors propagate;
+- output file must exist and be non-empty.
 
-## 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.
+## Deterministic Behavior
+- input and var maps are sorted into deterministic `--input` and `--var` CLI args.
+- generated invocation YAML (`scriptorium.generated.v1`) is emitted when requested.
+- adapter is stateless and does not own artifact-selection policy.
 
-## 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`
+## Config Mapping
+Config fields consumed through runner/stage wiring are under `pipeline.scriptorium.*` plus per-artifact settings under `pipeline.scriptorium.artifacts.*`.
 
-## 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.
+Maintained examples with Scriptorium config:
+- `examples/pipeline.full.annotated.yml`
+- `examples/pipeline.production.yml`

docs/integrations/seriatim.md

@@ -1,60 +1,56 @@
-# Integration: seriatim
+# Integration: Seriatim
 
 ## Purpose
-Define Narratio's adapter contract for merge, normalize, and trim subprocess invocations of Seriatim.
+Define the Seriatim adapter contract used by `merge`, `normalize`, and `trim`.
 
-## 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
+## Adapter Boundary
+Interface:
+- `seriatim.Runner`
+- methods:
+  - `Run(ctx, MergeRequest)`
+  - `Normalize(ctx, NormalizeRequest)`
+  - `Trim(ctx, TrimRequest)`
 
-Outputs:
-- `MergeResult`, `NormalizeResult`, `TrimResult` with output paths, logs/config paths, exit code, duration, binary provenance, and metadata.
+Primary implementation:
+- `internal/adapters/seriatim/SubprocessRunner`
 
-## Boundaries
-Owns:
-- Validated deterministic CLI invocation construction
-- Optional env tuning propagation for merge
-- Invocation config file emission
-- JSON output validation
+Execution modes:
+- `seriatim merge`
+- `seriatim normalize`
+- `seriatim trim`
 
-Does not own:
-- Transcript input selection/promotion logic (stage-owned)
-- Bounds computation (scriptorium/trim-stage-owned)
+## 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.
 
-## 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`
+Results include output/log/config paths, timing, exit code, and metadata.
 
-## External Adapters Used
-- Shared subprocess helper (`internal/adapters/subprocess`).
+## Validation and Failure Semantics
+Runner construction validates:
+- binary presence;
+- timeout > 0;
+- supported output schema (`seriatim-minimal|seriatim-intermediate|seriatim-full`);
+- non-negative coalesce gap.
 
-## State and Manifest Behavior
-- No direct manifest writes.
-- Stage metadata consumes adapter result fields and preserves generated config/log references.
+Invocation fails on:
+- missing required request paths/inputs;
+- invalid normalize schema override;
+- subprocess failure;
+- invalid JSON outputs;
+- missing `segments` array for normalize/trim transcript outputs.
 
-## Skip and Resume Behavior
-- Adapter has no skip/resume logic. Runner controls stage execution.
+When report paths are provided/enabled, report files must parse as JSON.
 
-## 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.
+## Deterministic Behavior
+- argument ordering is deterministic per command construction.
+- merge env overrides are explicit (`SERIATIM_*`) and only emitted when configured.
+- generated invocation YAML (`seriatim.generated.v1`) is emitted when requested.
+- adapter does not write manifests or choose stage inputs.
 
-## 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`
+## Config Mapping
+Config fields consumed through runner/stage wiring are under `pipeline.seriatim.*`.
 
-## 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.
+Maintained examples with Seriatim config:
+- `examples/pipeline.full.annotated.yml`
+- `examples/pipeline.production.yml`

docs/internal/README.md

@@ -1,29 +1,43 @@
 # Internal Documentation Index
 
 ## Audience
-Developers and LLM coding agents changing Narratio internals.
+Developers and coding agents changing Narratio internals.
 
 ## Scope
-Implementation-accurate contracts for workspace/state, manifests, stages, artifact resolution, adapter boundaries, and restore command behavior.
+`docs/internal/` documents implemented internal contracts: stage boundaries, manifest/state behavior, artifact resolution, restore behavior, storage boundaries, and workspace invariants.
 
-## Component Docs
-- `adapters.md`: external adapter map, runtime wiring, and boundary ownership.
-- `storage.md`: remote storage backend contracts and object-store invariants.
-- `manifest.md`: session/run manifest schemas, lifecycle transitions, and persistence semantics.
-- `artifacts.md`: built-in artifact registry, runtime artifact catalog, and source-resolution behavior.
-- `workspace.md`: local state model, manifests, run-local layout, promotion, and cleanup invariants.
-- `command-restore.md`: restore command discovery/planning/execution/reporting contract.
-- `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`: dependency-ordered Scriptorium artifact generation for selected configured artifacts.
-- `stage-archive.md`: archive upload and current-pointer publish contract.
+User and operator behavior belongs in:
+- `docs/cli.md`
+- `docs/config.md`
+- `docs/operations.md`
+- `docs/troubleshooting.md`
 
-## External Integration Notes
-- `../integrations/README.md`: canonical location for external integration contracts (`audita.md`, `seriatim.md`, `scriptorium.md`).
+## Pipeline Stage Set
+Canonical stage order from `internal/stage.All()`:
+1. `prepare`
+2. `transcribe`
+3. `merge`
+4. `polish`
+5. `normalize`
+6. `trim`
+7. `analyze`
+8. `publish`
+9. `notify` (placeholder)
 
-## Canonical Owner
-`docs/internal/` is the canonical home for implemented internals per `docs/documentation/policy.md`.
+`notify` is currently a placeholder stage with optional notifier call behavior; it has no persisted pipeline outputs.
+
+## Internal Component Docs
+- `adapters.md`: external adapter boundaries and default runtime wiring.
+- `artifacts.md`: canonical source IDs, runtime catalog behavior, and resolution rules.
+- `manifest.md`: session and run manifest contracts.
+- `storage.md`: object-store interface and S3 implementation behavior.
+- `workspace.md`: local session layout, run-local layout, and cleanup guardrails.
+- `command-restore.md`: restore discovery, planning, execution, and reporting.
+- `stage-prepare.md`
+- `stage-transcribe.md`
+- `stage-merge.md`
+- `stage-polish.md`
+- `stage-normalize.md`
+- `stage-trim.md`
+- `stage-analyze.md`
+- `stage-publish.md`

docs/internal/adapters.md

@@ -1,80 +1,49 @@
 # Internal: Adapters
 
 ## Purpose
-Describe the external adapter boundaries used by Narratio stages and app orchestration, including default runtime wiring.
+Define external integration boundaries and default adapter wiring used by app/stage orchestration.
 
-## Inputs and outputs
-Inputs:
-- Stage requests passed through adapter interfaces (for example transcription, merge/normalize/trim, polish, artifact generation, object-store operations, notifications).
-- Resolved config values used to construct default adapters.
+## Adapter Boundaries
+Narratio stage logic depends on adapter interfaces, not transport-specific details.
 
-Outputs:
-- Adapter-specific result structs (paths, metadata, status/attempt info, duration/exit details).
-- Adapter errors returned to stage/app orchestration.
-
-## Boundaries
-Owns:
-- Transport/process/SDK details at system boundaries (`HTTP`, subprocess CLI invocation, AWS SDK calls).
-- Request/response contracts in `internal/adapters/*` packages.
-
-Does not own:
-- Stage sequencing, skip/force/resume decisions.
-- Manifest transition logic.
-- Canonical workspace path policy.
-
-## Config fields used
-Default wiring and adapter calls consume:
-- `pipeline.whisperx.*`
-- `pipeline.seriatim.*`
-- `pipeline.audita.*`
-- `pipeline.scriptorium.*`
-- `pipeline.storage.*` and `pipeline.archive.*` (object-store construction/gating)
-- `pipeline.notification.*` (sender boundary exists; placeholder behavior today)
-
-## External adapters used
-Runtime env boundary fields (`internal/stage.Env`):
+Primary adapters:
 - `whisperx.Client`
 - `seriatim.Runner`
 - `audita.Runner`
 - `scriptorium.Runner`
 - `storage.ObjectStore`
 - `notify.Sender`
-- `analyzer.Runner`
 
-Current execution usage:
-- Actively used by implemented stages: `WhisperX`, `Seriatim`, `Audita`, `Scriptorium`, `ObjectStore`, `Notifier`.
-- Present but not used by implemented stage set: `Analyzer`, legacy `storage.Backend`.
+## Ownership
+Adapters own:
+- HTTP/subprocess/SDK argument and transport details.
+- Backend-specific request/response mapping.
 
-Default construction in app runner:
-- Auto-constructed when not injected: WhisperX HTTP client, Seriatim subprocess runner, Audita subprocess runner, Scriptorium subprocess runner, object store (only when needed), and `notify.NoopSender`.
-- Object-store construction goes through app command orchestration so configured filesystem secrets are loaded before the storage adapter is initialized.
-- Callers can inject test/fake implementations through `app.RunOptions.Env`.
+Adapters do not own:
+- stage ordering/skip/force logic;
+- manifest transitions;
+- canonical path policy.
 
-## State and manifest behavior
-- Adapters do not directly mutate session/run manifests.
-- Stages and runner own manifest writes and stage status transitions.
-- Adapter outputs are persisted indirectly through stage result mapping (outputs/logs/generated configs/metadata).
+## Default Wiring
+`internal/app/runner.go` initializes default adapters when not injected:
+- WhisperX HTTP client from pipeline config.
+- Seriatim subprocess runner.
+- Audita subprocess runner.
+- Scriptorium subprocess runner.
+- Noop notifier (`notify.NoopSender`).
+- Object store only when required by selected stages/config.
 
-## Skip and resume behavior
-- No adapter-level skip/resume semantics.
-- Skip/resume/force behavior is decided by app runner using manifest stage state.
+Object-store construction goes through `newCommandObjectStore`, which loads configured filesystem secrets before adapter initialization.
 
-## Failure behavior
-- Adapter constructors validate config-derived values and fail early on invalid required inputs.
-- Adapter run-time failures are returned to stage code with boundary context and are recorded as stage failures by runner logic.
-- Subprocess adapters preserve stdout/stderr and generated-config paths to aid diagnosis.
+## Failure Semantics
+- Constructor errors fail stage execution setup early.
+- Runtime adapter errors propagate to stage code and then manifest failure handling.
+- Subprocess adapters persist stage logs/generated configs through stage-managed paths.
 
-## Tests to inspect before changing
+## Test Surfaces
 - `internal/adapters/whisperx/http_test.go`
 - `internal/adapters/seriatim/subprocess_test.go`
 - `internal/adapters/audita/subprocess_test.go`
 - `internal/adapters/scriptorium/subprocess_test.go`
 - `internal/adapters/storage/*_test.go`
-- `internal/adapters/notify/fake_test.go`
-- `internal/adapters/analyzer/fake_test.go`
 - `internal/app/runner_test.go`
-
-## Architectural invariants
-- Stage code depends on adapter interfaces, not transport-specific implementation types.
-- External SDK-specific types remain inside adapter implementations.
-- Default app wiring must remain deterministic and overrideable via injected env dependencies.

docs/internal/artifacts.md

@@ -1,106 +1,112 @@
 # Internal: Artifacts
 
 ## Purpose
-Define Narratio artifact identity, catalog, and source-resolution behavior for:
-- built-in session artifacts;
-- configured analyze artifacts;
-- canonical previous-session artifact sources.
+Define canonical artifact IDs, runtime catalog behavior, source resolution rules, and shared current-state mechanics used by app and previous-cache code.
 
-## Inputs and outputs
-Inputs:
-- configured input sources (`pipeline.scriptorium.artifacts.*.inputs.*.source`);
-- session paths and manifest inputs/outputs;
-- runtime catalog state.
+## Built-in Source IDs
 
-Outputs:
-- resolved artifact path + provenance (`ResolvedSessionArtifact`);
-- runtime catalog entries for built-ins and configured artifacts;
-- requirement sets for canonical previous-session inputs.
-- canonical S3 session, run, current, session config, session locks, audio, and promoted artifact keys.
+- `narratio.transcript.base` -> `transcripts/base.json` (`merge`)
+- `narratio.transcript.polished` -> `transcripts/polished.json` (`polish`)
+- `narratio.transcript.final` -> `transcripts/final.json` (`normalize`)
+- `narratio.transcript.final_trimmed` -> `transcripts/final.trimmed.json` (`trim`)
+- `narratio.bounds.session` -> `artifacts/session_bounds.json` (`trim`)
 
-## Boundaries
-Owns:
-- built-in source registry and validation;
-- configured artifact catalog identity (`narratio.artifact.<name>`);
-- canonical previous-session source parsing and resolution;
-- previous-session requirement collection (`CollectPreviousArtifactRequirements`).
+## Configured and Previous-Session Sources
 
-Does not own:
-- prepare-stage remote hydration;
-- stage success/skip transitions;
-- archive upload orchestration.
+- configured source ID format: `narratio.artifact.<artifact_key>`
+- previous-session source ID format: `narratio.previous_session.artifact.<artifact_key>`
 
-## Built-in IDs
-| Artifact ID | Canonical file | Producer stage | Output kind |
-| --- | --- | --- | --- |
-| `narratio.transcript.merged` | `transcripts/merged.json` | `merge` | `transcript_merged` |
-| `narratio.transcript.polished` | `transcripts/processed.json` | `polish` | `transcript_processed` |
-| `narratio.transcript.full` | `transcripts/normalized.json` | `normalize` | `transcript_normalized` |
-| `narratio.transcript.trimmed` | `transcripts/trimmed.json` | `trim` | `transcript_trimmed` |
-| `narratio.bounds.session` | `artifacts/session_bounds.json` | `trim` | `session_bounds` |
+Both formats are validated by strict source-policy rules.
 
-## Source families
-- built-in: `narratio.transcript.*`, `narratio.bounds.session`
-- configured artifact: `narratio.artifact.<artifact_key>`
-- canonical previous-session artifact: `narratio.previous_session.artifact.<artifact_key>`
+## Runtime Catalog
 
-## S3 key helpers
-- session prefix: `{root_prefix}/campaigns/{campaign}/sessions/{session_id}/`
-- session config: `{session_prefix}/session.yml`
-- session lock store: `{session_prefix}/locks.yml`
-- run prefix: `{session_prefix}/runs/{run_id}/`
-- audio prefix: `{session_prefix}/{session.inputs.audio_s3.prefix}`
-- current manifest: `{session_prefix}/current/manifest.json`
-- current run pointer: `{session_prefix}/current/run_id.txt`
+`ArtifactCatalog` tracks:
 
-## Runtime catalog model
-Catalog entries track:
-- `planned`: source is registered for this run;
-- `executable`: configured artifact is selected for analyze execution;
-- `available`: usable local file exists (generated this run or reused from disk).
+- `planned`: source registered for run context;
+- `executable`: selected and enabled for analyze execution;
+- `available`: local file exists and validates;
+- `provenance`: availability source.
+
+Current provenance values:
 
-Configured artifact provenance values include:
 - `generated.current_analyze_run`
 - `filesystem.disabled_artifact_output`
-
-Previous-session canonical provenance values include:
 - `manifest.inputs.previous_cache`
 - `current_session.previous_cache`
 
-## Resolution behavior
-- Built-ins resolve via manifest producer outputs first, then canonical fallback paths.
-- Configured `narratio.artifact.<name>` sources resolve through catalog availability.
-- Canonical previous-session sources resolve to current-session `previous/` cache candidates derived from configured artifact canonical output paths.
-- Archive-relative configured artifact paths under `artifacts/` are cached without a redundant nested `artifacts/` segment.
-- Previous-session canonical resolution prefers manifest-recorded input paths when present, then filesystem fallback under `previous/artifacts/**`.
+## Resolution Rules
 
-## Previous-session requirement scanning
-`CollectPreviousArtifactRequirements`:
-- scans enabled configured artifacts only;
-- includes canonical previous-session sources only;
-- deduplicates by artifact key;
-- merges required/optional references (`required` wins);
-- records deterministic sorted source locations for diagnostics.
+Built-ins:
+
+1. manifest producer outputs (when present)
+2. canonical session-path fallback
+
+Configured sources (`narratio.artifact.*`):
+
+- resolve only through runtime catalog availability.
+
+Previous-session sources (`narratio.previous_session.artifact.*`):
+
+- resolve only from local `previous/` cache state;
+- prefer manifest-backed previous-input paths;
+- fallback to existing previous-cache filesystem paths.
+
+Validation by content type:
 
-## Validation behavior
 - transcript built-ins: JSON with top-level `segments` array;
 - bounds built-in: valid JSON;
-- configured and previous-session artifact files: non-empty text content.
+- configured/previous-session artifact files: non-empty text file.
 
-## Failure behavior
-- unsupported source or malformed canonical previous source: validation/resolution error;
-- known source unavailable: `ErrSessionArtifactNotFound`;
-- configured/previous canonical source without catalog: error;
-- resolved invalid file content: validation error.
+## Previous Requirement Collection
 
-## Tests to inspect before changing
-- `internal/artifacts/artifact_resolver_test.go`
-- `internal/artifacts/catalog_test.go`
-- `internal/artifacts/previous_requirements_test.go`
-- `internal/stage/prepare_previous_test.go`
-- `internal/stage/analyze_test.go`
+`CollectPreviousArtifactRequirements`:
 
-## Architectural invariants
-- Built-in source IDs are static.
-- Configured and previous-session source IDs are artifact-key based and validation-gated.
-- Resolution behavior remains deterministic and manifest-aware.
+- scans enabled configured artifacts only;
+- extracts only canonical previous-session sources;
+- deduplicates by artifact key;
+- merges required and optional references (required wins);
+- returns deterministic ordering and source locations.
+
+## Current-State Helpers
+
+Artifacts package owns shared remote current-state loading mechanics used by restore, status/validate checks, and previous-cache planning.
+
+Core helpers:
+
+- `LoadCurrentRunPointer`
+- `LoadCurrentManifest`
+- `LoadCurrentState`
+- `ValidateCurrentStateIdentity`
+
+Typed missing-state errors:
+
+- `CurrentRunPointerMissingError` (`ErrCurrentRunPointerMissing`)
+- `CurrentManifestMissingError` (`ErrCurrentManifestMissing`)
+
+Identity validation supports caller-provided expectations:
+
+- expected campaign;
+- expected session ID;
+- expected run ID, or pointer/manifest run-ID consistency check.
+
+Caller policy is intentionally outside artifacts helpers:
+
+- some callers fail on missing current state;
+- some callers downgrade missing state to status/findings;
+- some callers skip optional behavior when state is missing.
+
+## Key Path Helpers
+
+`internal/artifacts/paths.go` and S3-key helpers define canonical helpers for:
+
+- session/work/run paths;
+- previous-cache paths;
+- spool/cache paths;
+- S3 session/run/current-state key layout.
+
+## Invariants
+
+- source ID formats are stable contracts;
+- artifact resolution is deterministic and manifest-aware;
+- previous-session source resolution in `analyze` is local-only;
+- remote current-state key construction remains centralized in artifacts helpers.

docs/internal/command-restore.md

@@ -1,105 +1,84 @@
 # Internal: Command Restore
 
 ## Purpose
-Define the implemented `narratio restore` contract: committed remote-state discovery, deterministic plan classification, safe file install semantics, and restore reporting.
+Define the implemented `narratio session restore` command contract:
 
-## Inputs and outputs
-Inputs:
-- CLI flags: `--config`, `--session`, `--session-id`, `--previous-session-id`, `--dry-run`, `--force`, `--include-audio`.
-- Resolved/validated `pipeline.yml` and `session.yml`.
-- Configured remote object store.
-- Remote committed current-state markers (`current/run_id.txt`, `current/manifest.json`).
+- committed remote current-state discovery;
+- deterministic restore planning;
+- safe local install semantics;
+- durable restore reporting.
 
-Outputs:
-- Dry-run summary to stdout (plan + counts).
-- Non-dry-run completion summary to stdout.
-- Local durable session files restored under canonical session root.
-- Non-dry-run restore report at `reports/restore-latest.json`.
+## Discovery Contract
 
-## Boundaries
-Owns:
-- Restore command flag parsing and command wiring.
-- Remote current-state discovery and identity validation.
-- Restore plan construction and conflict classification.
-- Restore execution for planned downloads.
-- Restore report model and persistence.
+Restore resolves remote committed state from the session publish current pointers:
 
-Does not own:
-- Stage execution orchestration (`run`, `resume`, `run-stage`).
-- Archive publish behavior (owned by archive stage).
-- Storage transport implementation details (owned by storage adapters).
+- `current/run_id.txt` (required, non-empty);
+- `current/manifest.json` (required, decodable).
 
-## Config fields used
-- Config/session discovery and templating fields consumed by all commands.
-- `pipeline.workspace.root` (local restore target root).
-- `pipeline.storage.*` (remote backend + archive identity derivation).
-- `pipeline.storage.s3.*` identity components used by archive prefix helpers.
-- `pipeline.spool.root` for active audio downloads.
-- `pipeline.cache.root` and `pipeline.cache.s3_audio` for reusable S3 audio cache.
-- `session.session_id`
-- `session.campaign`
+Current-state discovery uses shared artifacts-level mechanics and validates identity against the resolved request config:
 
-## External adapters used
-- `storage.ObjectStore` for `Exists`, `List`, `Download`.
-- `artifacts.Store` (`LocalStore`) for layout and session lock management.
-- `manifest.LocalStore` for manifest decode/validation and identity checks.
+- campaign must match;
+- session ID must match.
 
-## State and manifest behavior
-- Restore is not a pipeline run and does not create a run manifest.
-- Restore uses committed remote current state only:
-  - `current/run_id.txt` must exist and be non-empty.
-  - `current/manifest.json` must decode and match requested session/campaign.
-- Non-dry-run writes restore files to canonical session paths.
-- With `--include-audio`, restore uses the shared S3 audio cache for `audio/**` objects. Cache hits avoid object downloads; cache misses download through spool, install the work file, and populate cache.
-- Manifest install behavior:
-  - validated before replacement.
-  - installed last among download actions.
-  - existing local manifest is preserved if restored manifest validation/install fails.
-- Non-dry-run report persists summary/action status metadata in `reports/restore-latest.json`.
+Restore treats any missing or invalid remote current state as a command error.
 
-Restore path scope:
-- includes:
-  - `manifest.json`
-  - `transcripts/**`
-  - `artifacts/**`
-  - `previous/**`
-  - `audio/**` only when `--include-audio` is set
-- excludes:
-  - `runs/**`
-  - `logs/**`
-  - `reports/**`
-  - `config/**`
-  - `inputs/**`
-  - remote `current/**` pointer files as local restore targets
+## Planning Contract
 
-## Skip and resume behavior
-- Restore does not participate in stage skip/resume decisions.
-- Restore provides durable local state so subsequent stage commands can resume or rerun based on restored manifest state.
-- Audio cache is outside the workspace and is reused across restore and prepare invocations.
-- Dry-run is read-only and returns plan output only.
+Restore planner action kinds:
 
-## Failure behavior
-- Fails when storage backend is unavailable or archive identity cannot be resolved.
-- Fails when remote current pointer/manifest is missing or invalid.
-- Fails when remote manifest identity mismatches requested campaign/session.
-- Fails on local conflicts unless `--force` is set.
-- Fails fast on session lock acquisition conflict for non-dry-run execution.
-- On execution failure, previously installed files remain; no rollback is performed.
+- `download`;
+- `skip_same`;
+- `conflict`.
 
-## Tests to inspect before changing
-- `internal/app/restore_test.go`
-- `internal/app/restore_discovery_test.go`
-- `internal/app/restore_plan_test.go`
-- `internal/app/restore_execution_test.go`
-- `internal/app/restore_workflow_test.go`
-- `internal/artifacts/archive_identity_test.go`
+Planner behavior:
 
-## Architectural invariants
-- Restore relies on centralized archive identity/key helpers (`internal/artifacts`) rather than ad hoc key building.
-- `current/run_id.txt` is the remote commit marker; restore must not infer committed state from incidental files.
-- Local path mapping is traversal-safe and constrained to session root.
-- Restore scope is deterministic and path-classified:
-  - include `manifest.json`, `transcripts/**`, `artifacts/**`, `previous/**`
-  - include `audio/**` only with `--include-audio`
-  - exclude `runs/**`, `logs/**`, `reports/**`, `config/**`, `inputs/**`
-- Command remains standalone; no implicit `run --restore` behavior.
+- remote list scope is the resolved session prefix;
+- remote-to-local mapping is traversal-safe;
+- actions are sorted deterministically by local relative path.
+
+Restore scope from current remote state:
+
+- include `manifest.json`;
+- include `transcripts/**`;
+- include `artifacts/**`;
+- include `audio/**` only with `--include-audio`.
+
+Explicit exclusions from current remote state mapping:
+
+- `current/**`;
+- `runs/**`;
+- `logs/**`;
+- `reports/**`;
+- `config/**`;
+- `inputs/**`;
+- `previous/**`.
+
+Previous-cache files are planned separately through `previouscache.BuildPlan` when configured previous-session requirements exist.
+
+## Execution Contract
+
+Execution order and safety:
+
+- non-manifest downloads happen before manifest install;
+- `manifest.json` installs last;
+- downloads use sibling temp files plus atomic rename;
+- manifest replacement is validated before rename;
+- failed installs do not roll back files already written in the same execution.
+
+Audio restore path:
+
+- uses `audio.MaterializeS3Audio`;
+- integrates spool and S3 audio cache paths;
+- supports cache-hit reuse without object redownload.
+
+## Reporting Contract
+
+- `--dry-run`: prints summary only; no local writes.
+- non-dry-run: writes `reports/restore-latest.json`.
+- report includes plan counts, per-action status, and execution failures.
+
+## Invariants
+
+- restore uses committed remote current state as authority;
+- `current/run_id.txt` is the remote publish commit marker;
+- restore does not execute pipeline stages.

docs/internal/manifest.md

@@ -1,81 +1,57 @@
 # Internal: Manifest
 
 ## Purpose
-Describe Narratio's durable execution state model for session-level and run-level manifests, including lifecycle transitions and persistence behavior.
+Define durable session state (`manifest.json`) and invocation state (`runs/{run_id}/manifest.json`) contracts.
 
-## Inputs and outputs
-Inputs:
-- Session identity and run identity from app orchestration.
-- Stage transition events and stage result payloads.
+## Session Manifest
+Path:
+- `{workspace.root}/work/{campaign}/{session_id}/manifest.json`
 
-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`.
+Primary model (`manifest.Manifest`):
+- identity (`session_id`, `campaign`, `run_id`)
+- local path metadata (`local_workdir`, `local_spool_dir`)
+- remote identity metadata (`s3_bucket`, `s3_session_prefix`, `s3_run_prefix`)
+- `inputs` records
+- durable `artifacts` records
+- per-stage `stages` map
 
-## Boundaries
-Owns:
-- Manifest schemas (`Manifest`, `RunManifest`, stage records, error records, input/artifact records).
-- Stage status/action transition methods.
-- Persistent store contract (`manifest.Store`) and local JSON store implementation.
+Stage status enum:
+- `pending`
+- `running`
+- `succeeded`
+- `failed`
+- `skipped`
+- `stale`
+- `interrupted`
 
-Does not own:
-- Stage implementation details.
-- Path construction policy outside manifest file persistence calls.
-- CLI command behavior.
+## Run Manifest
+Path:
+- `{workspace.root}/work/{campaign}/{session_id}/runs/{run_id}/manifest.json`
 
-## Config fields used
-Manifest package itself does not read config directly.
+Run model (`manifest.RunManifest`):
+- invocation identity and `force` flag
+- requested stages
+- per-stage action (`run` or `skip`)
+- per-stage status
+- overall run status (`running`, `succeeded`, `failed`)
 
-Manifest identity fields are populated by app/stage orchestration from:
-- `session.session_id`
-- `session.campaign`
-- `pipeline.workspace.root`
-- `pipeline.storage.s3.*` (when archive/S3 identity is set)
+## Persistence Semantics
+`manifest.LocalStore`:
+- validates loaded documents;
+- normalizes missing maps/stage records;
+- writes atomically via temp file + rename;
+- updates `updated_at` on save.
 
-## External adapters used
-- No external service adapters.
-- Uses local filesystem for persistence via `manifest.LocalStore`.
+## Execution Semantics
+Runner updates both manifests per stage transition:
+- mark running
+- mark succeeded/failed/skipped
+- persist logs/generated config refs and metadata
 
-## State and manifest behavior
-Session manifest model:
-- Tracks durable per-session stage state and provenance (`pending`, `running`, `succeeded`, `failed`, `skipped`, `stale`, `interrupted`).
-- Stores resolved inputs, durable artifacts, stage logs/config refs, and stage metadata.
+Session manifest is the authoritative stage-progress ledger across invocations.
+Run manifest is invocation-scoped audit state.
 
-Run manifest model:
-- Tracks one invocation (`run_id`) with requested stages and force mode.
-- Tracks per-stage action (`run` or `skip`) and per-stage status.
-- Tracks overall run status (`running`, `succeeded`, `failed`).
-
-Persistence behavior:
-- Load validates required identity/timestamp fields and normalizes maps/records.
-- Save updates `updated_at` and writes JSON atomically (temp file + rename).
-- Session and run manifests are saved incrementally before/after stage transitions.
-
-Relationship during execution:
-- Runner updates both manifests for every stage transition.
-- Session manifest is the durable pipeline-progress ledger.
-- Run manifest is invocation history and audit record.
-- Analyze stage outputs are persisted as `kind=scriptorium_artifact` with `source_id=narratio.artifact.<name>` for configured artifact identity.
-
-## Skip and resume behavior
-- Resume and skip decisions are based on session-manifest stage statuses.
-- `--force` reruns selected stages and marks downstream succeeded stages as `stale` in session manifest.
-- Run manifest records whether each stage was executed or skipped in that invocation.
-
-## Failure behavior
-- Stage failure marks both manifests failed for that stage and records error messages/timestamps.
-- Save failures are returned immediately and fail the command.
-- Invalid/malformed manifest files fail load with explicit validation/decode errors.
-
-## Tests to inspect before changing
-- `internal/manifest/manifest_test.go`
-- `internal/manifest/run_manifest_test.go`
-- `internal/manifest/store_test.go`
-- `internal/app/runner_test.go`
-- `internal/app/run_control_test.go`
-- `internal/app/resume_run_stage_test.go`
-
-## Architectural invariants
-- Session manifest is authoritative for stage progression across invocations.
-- Run manifest is invocation-scoped and never replaces session manifest as progress authority.
-- Manifest writes are atomic and deterministic (JSON + newline, temp rename pattern).
+## Invariants
+- stage resume/skip decisions are session-manifest driven.
+- force reruns stale downstream succeeded stages.
+- run manifest does not replace session manifest as progress authority.

docs/internal/stage-analyze.md

@@ -1,81 +1,38 @@
 # Stage: analyze
 
 ## Purpose
-Execute selected configured Scriptorium artifacts in deterministic dependency order and promote successful outputs to canonical session artifact paths.
+Execute selected configured Scriptorium artifacts in dependency order and materialize outputs.
 
-## Inputs and outputs
-Inputs:
-- configured artifact definitions from `pipeline.scriptorium.artifacts`;
-- selected artifact filter (`--artifacts`) when provided;
-- resolved artifact sources from resolver/catalog.
+## Inputs
+- configured artifacts from `pipeline.scriptorium.artifacts`
+- optional selected artifact filter (`--artifacts`)
+- built-in/configured/previous-session source references in artifact inputs
 
-Source types used by analyze:
-- built-ins: `narratio.transcript.*`, `narratio.bounds.session`;
-- configured artifacts: `narratio.artifact.<artifact_key>`;
-- canonical previous-session artifacts: `narratio.previous_session.artifact.<artifact_key>`;
-- legacy path-based previous-session source: `previous_session_artifact` (uses `inputs.*.path`).
+Supported source families:
+- built-ins: `narratio.transcript.*`, `narratio.bounds.session`
+- configured artifacts: `narratio.artifact.<key>`
+- previous-session cache: `narratio.previous_session.artifact.<key>`
 
-Outputs:
-- promoted configured artifact files at each configured `output_path`;
-- stage metadata (`generated_artifacts`, `reused_artifacts`, selected/order info).
+## Outputs
+- one materialized output per executed configured artifact (`output_path`)
+- stage metadata describing selected/generated/reused artifacts
 
-## Boundaries
-Owns:
-- runtime artifact catalog construction;
-- selected-artifact planning and dependency ordering;
-- per-input resolution and required/optional handling;
-- Scriptorium render/run invocation;
-- run-local output generation and canonical promotion.
+## Key Behavior
+- skips with metadata when Scriptorium config is missing or no executable artifacts remain.
+- builds runtime artifact catalog (built-ins + configured artifacts).
+- marks non-executable configured artifacts as reusable when output files already exist.
+- validates selected artifact dependency order (cycle-safe topo ordering).
+- resolves required/optional inputs per artifact source definition.
+- resolves previous-session sources from local `previous/` cache only.
+- runs optional render-debug, then artifact execution.
+- validates non-empty output files and materializes canonical outputs.
 
-Does not own:
-- prepare-time previous-session hydration;
-- object-store access for previous-session sources;
-- archive promotion policy.
+## Failure Semantics
+- required missing configured/previous-session inputs fail.
+- missing required previous-session source includes prepare rerun guidance.
+- dependency cycles or unavailable required dependencies fail.
+- adapter validation failures fail stage.
 
-## 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.<name>.*`
-
-## External adapters used
-- Scriptorium adapter:
-  - optional `RenderArtifact` when render-debug is enabled;
-  - `RunArtifact` for artifact generation.
-
-## State and manifest behavior
-- If Scriptorium config is absent, or no artifacts are executable after filtering, analyze returns success metadata with `skipped=true`.
-- Builds runtime catalog with built-ins and configured `narratio.artifact.<name>` entries.
-- Non-executable configured artifacts may still be marked available from existing canonical output files.
-- Resolves canonical previous-session sources from local prepared `previous/` cache:
-  - prefers manifest-backed previous input paths when present;
-  - may fall back to current-session `previous/` filesystem paths.
-- Analyze does not call object storage for canonical previous-session source resolution.
-- Required canonical previous-session input missing:
-  - fails with guidance to run `narratio run-stage --force prepare`.
-- Optional missing sources are omitted from adapter input paths.
-
-## Skip and resume behavior
-- Runner-level skip applies when analyze is already `succeeded` and `--force` is not set.
-- Analyze is stage-scoped for resume; no per-artifact manifest resume state.
-- `--artifacts` filters executable artifacts but does not imply force rerun.
-
-## Failure behavior
-- Fails on dependency-order violations, missing required inputs, resolver validation failures, adapter errors, and missing/empty generated outputs.
-- Required unavailable configured artifact source (`narratio.artifact.<name>`) fails before invocation.
-- Required canonical previous-session source fails with prepare-rerun guidance.
-
-## Tests to inspect before changing
-- `internal/stage/analyze_test.go`
-- `internal/artifacts/catalog_test.go`
-- `internal/artifacts/artifact_resolver_test.go`
-- `internal/app/restore_workflow_test.go`
-
-## Architectural invariants
-- Canonical previous-session behavior is local-cache only during analyze.
-- Generated outputs are validated and promoted before stage success is recorded.
-- Resolver/catalog decisions stay deterministic and validation-gated.
+## Invariants
+- `analyze` performs no remote storage calls for previous-session source resolution.
+- output provenance and metadata are deterministic per execution.

docs/internal/stage-archive.md

@@ -1,84 +0,0 @@
-# Stage: archive
-
-## Purpose
-Publish durable run/session state to object storage, then atomically advance remote current state.
-
-## Inputs and Outputs
-Inputs:
-- session manifest and prerequisite stage records
-- run root contents under `runs/{run_id}/`
-- promotion rules with artifact `source` IDs and archive `dest` paths (`archive.promote_artifacts`)
-- effective source-based promotion locks from static config and remote session lock store
-- session-level `previous/**` cache files when present
-
-Outputs:
-- uploaded run files under `{session_prefix}/runs/{run_id}/...`
-- uploaded promoted artifacts under `{session_prefix}/...`
-- uploaded session previous-cache files under `{session_prefix}/previous/...` when present
-- `{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
-- Promotion lock enforcement
-- Session previous-cache file collection/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.archive.locks`
-- `{session_prefix}/locks.yml` loaded by app orchestration before archive execution
-- `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.
-- Uploads session `previous/**` files as durable session state when the local `previous/` directory exists.
-- Skips top-level promotion uploads for effective locked sources; run-local uploads still publish.
-- Effective locks are the union of `pipeline.archive.locks` and remote `{session_prefix}/locks.yml`; static pipeline locks win on duplicate sources.
-- Writes metadata including:
-  - upload counts/paths
-  - `previous_files_uploaded` and `previous_uploaded_paths`
-  - `locked_promotion_count` and `locked_promotions`
-  - `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 unlocked required promotion source, upload failures, or pointer write failures.
-- Locked required promotions are intentional skips and do not fail archive.
-- 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.
-- Session `previous/**` is archiveable durable input/provenance state, not run-local output.
-- Ordinary `--force` does not override archive locks.
-- Malformed or unreadable remote lock store fails archive-capable execution before promotion.
-- `current/manifest.json` uploads before `current/run_id.txt`.
-- `current/run_id.txt` is the remote publish commit marker.

docs/internal/stage-merge.md

@@ -1,63 +1,25 @@
 # Stage: merge
 
 ## Purpose
-Normalize per-speaker raw transcripts and merge them into one merged transcript via Seriatim.
+Normalize raw transcript inputs and merge into base transcript via Seriatim.
 
-## Inputs and Outputs
-Inputs:
+## Inputs
 - `transcripts/raw/*.json`
 - `inputs/speakers.yml`
 - `inputs/autocorrect.yml`
 
-Outputs:
-- `transcripts/merged.json`
-- optional `artifacts/seriatim.report.json` (when report enabled)
+## Outputs
+- `transcripts/base.json`
+- optional `artifacts/seriatim.report.json`
 
-## 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
+## Key Behavior
+- discovers and validates raw transcript inputs.
+- normalizes each raw transcript (`seriatim.Normalize`) into run-local scratch output.
+- merges normalized inputs (`seriatim.Run`) into base transcript.
+- validates merged transcript and optional report JSON.
+- materializes canonical outputs and records stage logs/generated configs.
 
-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.
+## Invariants
+- merge always consumes normalized forms of raw inputs.
+- base transcript must validate before stage success.
+- report output is config-gated.

docs/internal/stage-normalize.md

@@ -1,56 +1,22 @@
 # Stage: normalize
 
 ## Purpose
-Normalize the processed transcript into a deterministic intermediate schema for trim and optionally emit a normalize report.
+Normalize polished transcript into final transcript using Seriatim.
 
-## Inputs and Outputs
-Inputs:
-- `transcripts/processed.json`
+## Inputs
+- `transcripts/polished.json`
 
-Outputs:
-- `transcripts/normalized.json` (or configured normalize output path)
+## Outputs
+- `transcripts/final.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
+## Key Behavior
+- resolves polished transcript from manifest outputs/canonical fallback.
+- applies `pipeline.normalize` config or default normalize config.
+- runs Seriatim normalize with configured timeout/binary.
+- validates normalized transcript and optional report.
+- materializes canonical outputs and records logs/generated configs.
 
-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.
+## Invariants
+- final transcript must validate as processed transcript JSON (`segments` array).
+- normalize defaults are applied when `pipeline.normalize` is unset.

docs/internal/stage-polish.md

@@ -1,69 +1,23 @@
 # Stage: polish
 
 ## Purpose
-Polish merged transcript with Audita and produce a processed transcript for downstream normalization/analyze.
+Run Audita polishing on base transcript and produce polished transcript.
 
-## Inputs and Outputs
-Inputs:
-- `transcripts/merged.json`
+## Inputs
+- `transcripts/base.json`
 - `inputs/glossary.yml`
 
-Outputs:
-- `transcripts/processed.json`
-- optional `artifacts/audita.report.json` (when report enabled)
+## Outputs
+- `transcripts/polished.json`
+- optional `artifacts/audita.report.json`
 
-## 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
+## Key Behavior
+- resolves base transcript from merge outputs/canonical fallback.
+- invokes Audita with configured model/module/runtime options.
+- validates processed transcript structure (`segments` array required).
+- validates optional report JSON.
+- materializes canonical outputs; records logs/generated config and adapter metadata.
 
-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`.
+## Invariants
+- polished transcript schema validation is mandatory.
+- report output is config-gated.

docs/internal/stage-prepare.md

@@ -1,124 +1,42 @@
 # Stage: prepare
 
 ## Purpose
-Materialize canonical current-session input state and provenance before downstream stages run.
+Materialize canonical current-session inputs before processing stages.
 
-Prepare owns:
-- local input file materialization (`inputs/**`);
-- audio input materialization (`audio/**`);
-- previous-session cache hydration (`previous/**`) for canonical previous-session artifact sources.
-
-## Inputs and outputs
-Inputs:
-- resolved config/campaign/session (`pipeline.yml`, `campaign.yml`, `session.yml`);
-- remote session provenance when `session.yml` was loaded from S3;
-- campaign or session input files (`speakers`, `autocorrect`, `glossary`);
+## Inputs
+- resolved `campaign.yml`, `session.yml`, and pipeline config
+- stable input files (`speakers`, `autocorrect`, `glossary`)
 - audio source:
-  - local: `session.inputs.audio_dir` or `session.inputs.audio_files`;
-  - S3: `session.inputs.audio_s3.prefix`;
-- configured enabled Scriptorium artifact inputs (for previous-session requirement scanning);
-- remote previous-session current archive state when previous hydration is required.
+  - local `audio_dir`/`audio_files`, or
+  - S3 `audio_s3.prefix`
+- enabled configured artifact input requirements for previous-session sources
 
-Outputs:
-- `inputs/campaign.yml`;
-- `inputs/session.yml`;
-- `inputs/pipeline.resolved.yml`;
-- `inputs/speakers.yml`;
-- `inputs/autocorrect.yml`;
-- `inputs/glossary.yml`;
-- `audio/*.flac` in canonical session `audio/`;
-- optional `previous/manifest.json`;
-- optional `previous/artifacts/**`;
-- deterministic `manifest.Inputs` records with checksums and provenance metadata.
+## Outputs
+- `inputs/campaign.yml`
+- `inputs/session.yml`
+- `inputs/pipeline.resolved.yml`
+- `inputs/speakers.yml`
+- `inputs/autocorrect.yml`
+- `inputs/glossary.yml`
+- `audio/*.flac`
+- optional `previous/manifest.json`
+- optional `previous/artifacts/**`
+- deterministic `manifest.inputs` entries (checksums + provenance)
 
-## Boundaries
-Owns:
-- input path resolution and materialization;
-- S3 audio list/download/copy flow;
-- previous-session artifact requirement collection from enabled configured artifacts;
-- previous cache lifecycle when requirements exist (clear and rehydrate managed `previous/` state).
-
-Does not own:
-- transcript or artifact generation;
-- analyze-stage source resolution;
-- archive commit behavior.
-
-## Config fields used
-- `session.session_id`
-- `session.previous_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.cache.root`
-- `pipeline.cache.s3_audio`
-- `pipeline.storage.s3.bucket`
-- `pipeline.storage.s3.root_prefix`
-- `pipeline.scriptorium.artifacts.<name>.enabled`
-- `pipeline.scriptorium.artifacts.<name>.inputs.<key>.source`
-- `pipeline.scriptorium.artifacts.<name>.inputs.<key>.required`
-- `campaign.campaign`
-- `campaign.inputs.speakers_file`
-- `campaign.inputs.autocorrect_file`
-- `campaign.inputs.glossary_file`
-
-## External adapters used
-- `storage.ObjectStore` for:
-  - S3 audio listing/downloads;
-  - previous-session current pointer/manifest/artifact object checks and downloads.
-
-## State and manifest behavior
-- Ensures workspace layout exists.
-- Materializes canonical input files and audio files.
-- For S3 audio, uses run-scoped spool for active downloads and durable cache for reusable audio files; cache hits copy directly to work audio without downloading the object again.
-- Records `inputs/session.yml` provenance as local `session_config` or remote `session_config.s3`.
-- Resolves campaign-provided stable input paths relative to `campaign.yml`.
-- Resolves session-provided stable input overrides relative to `session.yml`.
-- Scans enabled configured artifact inputs for canonical sources:
-  - `narratio.previous_session.artifact.<artifact_key>`
-- If one or more canonical previous-session requirements exist:
+## Key Behavior
+- validates required config/store state.
+- enforces local audio vs S3 audio mutual exclusivity.
+- materializes S3 audio through spool/cache-aware logic.
+- scans enabled configured artifact inputs for `narratio.previous_session.artifact.*` requirements.
+- when previous requirements exist:
   - clears managed `previous/` state;
-  - hydrates required/optional previous artifacts from the configured previous session’s committed archive current state;
-  - writes `previous/manifest.json` and hydrated `previous/artifacts/**`;
-  - stores archive-relative artifact paths such as `artifacts/session_recap.md` as `previous/artifacts/session_recap.md`, not `previous/artifacts/artifacts/session_recap.md`;
-  - records hydrated previous inputs in `manifest.Inputs` with source `previous_session_archive.current`.
-- If no canonical previous-session requirements exist, prepare does not manage `previous/`.
-- `manifest.Inputs` is sorted deterministically by `(kind, path)`.
-- S3 audio `manifest.Inputs` retain S3 provenance and include `cache_path`; `spool_path` is present only when the current prepare invocation downloaded the file.
+  - builds previous-cache remote plan;
+  - downloads previous manifest/artifacts;
+  - records previous inputs in `manifest.inputs`.
 
-## Required and optional previous-session behavior
-- `previous_session_id` unset:
-  - if any referenced previous artifact is required: fail;
-  - if all referenced previous artifacts are optional: continue and omit them.
-- Previous session archive current pointer or manifest missing:
-  - if any referenced previous artifact is required: fail;
-  - if all referenced previous artifacts are optional: continue and omit missing ones.
-- Missing required previous artifact object: fail.
-- Missing optional previous artifact object: omit.
-- Downloaded previous artifacts must validate as non-empty files.
+Required previous-session inputs fail when unavailable; optional missing inputs are skipped.
 
-## Skip and resume behavior
-- Runner-level skip remains authoritative:
-  - if `prepare` already succeeded and run is not forced, `prepare` does not run and no hydration/download occurs.
-- If `prepare` runs (including with `--force`), it owns managed `previous/` state for canonical previous-session inputs.
-
-## Failure behavior
-- Fails on missing required input files, invalid audio-source combinations, empty/duplicate audio inputs, missing object store for S3 modes, and remote access/download/validation errors.
-- For required canonical previous-session inputs, analyze-time missing-input guidance is to rerun:
-  - `narratio run-stage --force prepare`
-
-## Tests to inspect before changing
-- `internal/stage/prepare_test.go`
-- `internal/stage/prepare_previous_test.go`
-- `internal/artifacts/previous_requirements_test.go`
-- `internal/app/runner_test.go`
-
-## Architectural invariants
-- `audio_dir`/`audio_files` and `audio_s3` are mutually exclusive.
-- Storage keys are computed by callers using archive/path helpers; storage adapter receives explicit keys.
-- `prepare` is the only stage that hydrates canonical previous-session cache state.
+## Invariants
+- only `prepare` hydrates canonical `previous/` cache state.
+- managed previous artifacts are stored under `previous/artifacts/**` without duplicate `artifacts/artifacts/` nesting.
+- `manifest.inputs` ordering is deterministic (`kind`, `path`).

docs/internal/stage-publish.md

@@ -0,0 +1,44 @@
+# Stage: publish
+
+## Purpose
+Upload run/session outputs to object storage and atomically advance remote current state.
+
+## Inputs
+- successful prerequisite stages: `prepare`, `transcribe`, `merge`, `polish`, `normalize`, `trim`, `analyze`
+- run root `runs/{run_id}/**`
+- publish output rules (`pipeline.publish.outputs`)
+- effective publish locks (static + remote merged lock set)
+- local `previous/**` files when present
+
+## Outputs
+- uploaded run files under remote `runs/{run_id}/...` (excluding `audio/**`)
+- uploaded selected publish outputs under session prefix
+- uploaded `previous/**` files under session prefix when present
+- uploaded `current/manifest.json`
+- uploaded `current/run_id.txt` written last
+
+## Key Behavior
+- stage can self-skip when publish disabled or run upload disabled.
+- validates prerequisite stage success and object-store availability.
+- collects deterministic run file list plus run `manifest.json`.
+- resolves publish output sources through runtime artifact catalog and manifest-aware resolution.
+- selected artifact filter applies to configured artifact sources only.
+- locked outputs are skipped intentionally (including required ones).
+- optional missing outputs are skipped; required missing unlocked outputs fail.
+- writes remote current manifest before current run pointer.
+
+## Metadata Signals
+Includes counts/lists for:
+- run uploads
+- published output uploads
+- previous uploads
+- skipped optional outputs
+- skipped unselected outputs
+- locked outputs
+- current-state key paths
+- `current_pointer_written`
+
+## Invariants
+- `current/run_id.txt` is the remote commit marker and is written last.
+- run upload excludes `audio/**`.
+- publish locks are not overridden by `--force`.

docs/internal/stage-transcribe.md

@@ -1,58 +1,22 @@
 # Stage: transcribe
 
 ## Purpose
-Generate per-speaker raw transcripts from prepared audio using WhisperX.
+Generate raw per-speaker transcripts from prepared audio using WhisperX.
 
-## Inputs and Outputs
-Inputs:
-- `audio/*.flac` prepared by `prepare`
+## Inputs
+- `audio/*.flac` from `prepare`
 
-Outputs:
-- `transcripts/raw/<speaker>.json` for each input audio file
+## Outputs
+- `transcripts/raw/<speaker>.json`
 
-## 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
+## Key Behavior
+- discovers prepared audio from manifest inputs or canonical audio directory.
+- derives speaker ID from `.flac` basename.
+- runs WhisperX with configured concurrency/retry settings.
+- validates each output as JSON.
+- writes run-local outputs then materializes canonical transcript 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.
+## Invariants
+- speaker basenames must be unique.
+- output path returned by adapter must match requested output path.
+- each successful output is validated before stage success.

docs/internal/stage-trim.md

@@ -1,75 +1,28 @@
 # Stage: trim
 
 ## Purpose
-Optionally trim the normalized transcript to session bounds; always produce a durable trimmed transcript.
+Produce a final-trimmed transcript; optionally generate bounds-driven trim.
 
-## Inputs and Outputs
-Inputs:
-- `transcripts/normalized.json`
+## Inputs
+- `transcripts/final.json`
 
-Outputs:
-- `transcripts/trimmed.json` (or configured trim output path)
+## Outputs
+- `transcripts/final.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
+## Key Behavior
+When `trim.enabled=false`:
+- copies normalized transcript to trimmed output.
 
-Does not own:
-- Upstream normalization
-- Downstream artifact analysis
+When `trim.enabled=true`:
+- runs Scriptorium bounds artifact generation;
+- optionally runs render-debug output generation;
+- validates bounds payload against transcript;
+- derives keep selector;
+- either copies unchanged transcript or runs Seriatim trim;
+- validates trimmed transcript and materializes bounds output.
 
-## 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.
+## Invariants
+- normalized transcript is required input.
+- bounds output exists only in enabled trim path.
+- render-debug output is diagnostic and not a declared stage output.

docs/internal/storage.md

@@ -1,75 +1,34 @@
 # Internal: Storage
 
 ## Purpose
-Document Narratio's remote storage backend contracts and implementations under `internal/adapters/storage`.
+Document remote object-store contracts and S3 implementation behavior.
 
-## Inputs and outputs
-Inputs:
-- Resolved storage config (`pipeline.storage.*`).
-- Already-loaded environment variables for configured S3 credentials.
-- Bucket-relative object keys and local file paths from app/stage orchestration.
+## Primary Contract
+`storage.ObjectStore` interface:
+- `List(ctx, prefix)`
+- `Download(ctx, key, localPath)`
+- `Upload(ctx, localPath, key, opts)`
+- `Exists(ctx, key)`
 
-Outputs:
-- Listed/downloaded/uploaded object metadata (`ObjectInfo`).
-- Existence checks and storage-layer errors.
+Key invariant:
+- callers pass full bucket-relative keys;
+- storage implementations do not infer campaign/session/run prefixes.
 
-## Boundaries
-Owns:
-- Remote object-store interface and implementation details.
-- S3 client wiring and API calls.
-- Object key normalization and upload/download/list primitives.
+## Configuration
+`NewObjectStoreFromConfig` currently supports S3-backed stores from `pipeline.storage.*` config.
 
-Does not own:
-- Session/run prefix semantics.
-- Archive commit order semantics.
-- Manifest updates.
-- Filesystem secret loading from `pipeline.secrets.env_dir`.
+S3 constructor behavior:
+- requires configured bucket;
+- uses region/endpoint/path-style options when set;
+- resolves credentials from configured env var names (with defaults).
 
-## Config fields used
-- `pipeline.storage.backend`
-- `pipeline.storage.s3.bucket`
-- `pipeline.storage.s3.region`
-- `pipeline.storage.s3.endpoint`
-- `pipeline.storage.s3.force_path_style`
-- `pipeline.storage.s3.access_key_id_env`
-- `pipeline.storage.s3.secret_access_key_env`
+## S3 Backend Behavior
+- normalizes object keys.
+- `List` paginates and returns normalized `ObjectInfo`.
+- `Download` writes local files with parent directory creation.
+- `Upload` streams local file and returns remote metadata.
+- `Exists` maps not-found responses to `false`.
 
-## External adapters used
-Storage package contracts:
-- `ObjectStore` (active remote object-store boundary): `List`, `Download`, `Upload`, `Exists`.
-- `Backend` (archive request boundary): currently implemented with `NoopBackend` only.
-
-Implementations:
-- `S3Backend`: AWS SDK-backed `ObjectStore` implementation.
-- `FakeBackend`: deterministic test `ObjectStore` and archive backend.
-- `NoopBackend`: deterministic no-op archive backend for compatibility wiring.
-
-## State and manifest behavior
-- Storage implementations are stateless with respect to manifest/session lifecycle.
-- Caller supplies fully-qualified bucket-relative keys.
-- Storage layer does not infer campaign/session/run/root-prefix semantics.
-- Caller controls publish ordering; storage layer executes individual operations in the order invoked.
-
-## Skip and resume behavior
-- No storage-level skip/resume behavior.
-- Skip/resume decisions are made by stage/app logic before storage calls occur.
-
-## Failure behavior
-- `NewObjectStoreFromConfig` fails when no remote backend is configured or required S3 config is missing.
-- `S3Backend` constructor fails when required bucket is missing or AWS client setup fails.
-- App command orchestration loads configured filesystem secrets before calling the object-store factory.
-- CRUD operations return contextual errors (including not-found behavior via `Exists`).
-- Key normalization is applied before operations (`\\` to `/`, leading slash trimmed).
-- Remote session loading uses `List` to find the exact `session.yml` key and `Download` to materialize it to a local temp file.
-
-## Tests to inspect before changing
-- `internal/adapters/storage/factory_test.go`
-- `internal/adapters/storage/s3_backend_test.go`
-- `internal/adapters/storage/fake_test.go`
-- `internal/adapters/storage/keys_test.go`
-- `internal/adapters/storage/archive.go` + consumers in stage tests (`prepare`, `archive`)
-
-## Architectural invariants
-- Callers pass full bucket-relative keys.
-- Storage backends must not prepend or infer narratio prefixes.
-- Remote transport details remain isolated to storage adapter implementations.
+## Invariants
+- storage layer is stateless regarding manifest/stage progression.
+- publish ordering semantics are owned by stage/app code, not storage adapters.

docs/internal/workspace.md

@@ -1,77 +1,57 @@
-# Workspace internals
+# Internal: Workspace
 
 ## Purpose
-Define the local durable and run-local workspace model used by stages, manifests, resume, and archive.
+Define local session layout, run-local stage layout, and cleanup guardrails.
 
-## Inputs and Outputs
-Inputs:
-- `pipeline.workspace.root`
-- `session.campaign`
-- `session.session_id`
-- generated `run_id`
+## Canonical Session Layout
+Session root:
+- `{workspace.root}/work/{campaign}/{session_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
+Core directories/files:
+- `inputs/`
+- `audio/`
+- `transcripts/`
+- `artifacts/`
+- `reports/`
+- `logs/`
+- `config/`
+- `current/`
+- `runs/`
+- `previous/`
+- `manifest.json`
+- `.lock`
 
-## Boundaries
-Owns:
-- Session-level path layout (`inputs/`, `audio/`, `transcripts/`, `artifacts/`, `reports/`, `logs/`, `config/`, `current/`, `runs/`, `previous/`)
-  - `previous/manifest.json` and `previous/artifacts/**` are reserved for prepared previous-session state
-- Run-local stage sandbox layout under `runs/{run_id}/{stage}/`
-- Session lock acquisition/release (`.lock`)
+`previous/` reserved files:
+- `previous/manifest.json`
+- `previous/artifacts/**`
 
-Does not own:
-- Stage business logic
-- Remote archive semantics (documented in `stage-archive.md`)
-- CLI argument parsing
+## Run-Local Stage Layout
+When run context is available, stages use:
+- `runs/{run_id}/{stage}/outputs/`
+- `runs/{run_id}/{stage}/logs/`
+- `runs/{run_id}/{stage}/reports/`
+- `runs/{run_id}/{stage}/config/`
+- `runs/{run_id}/{stage}/scratch/`
 
-## Config Fields Used
-- `pipeline.workspace.root`
-- `pipeline.workspace.cleanup_after_archive`
-- `pipeline.spool.root`
-- `pipeline.spool.delete_audio_after_archive`
-- `pipeline.cache.root`
-- `pipeline.cache.s3_audio`
-- `session.campaign`
-- `session.session_id`
+Run-local outputs are materialized back into canonical session paths before stage success.
+`previous/**` writes are never redirected to run-local output paths.
 
-## External Adapters Used
-None directly in this subsystem. Stages may use object storage adapters and then write local outputs into this layout.
+## Locking
+`artifacts.LocalStore` enforces single-writer session lock via `.lock` file (`ErrLockConflict` on contention).
 
-## 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 work/cache paths, S3 provenance, and spool path when the invocation downloaded the object.
-- Durable cache state under `pipeline.cache.root` is not workspace state and is preserved by default by `narratio clean`.
-- `narratio clean --session-id <id>` removes the session work root and session spool root.
-- `narratio clean --all` removes all local session work under `workspace.root/work` and spool children under `spool.root`.
-- `narratio clean --clear-cache` is the explicit opt-in for deleting matching S3 audio cache entries.
+## Cleanup Semantics
+Automatic post-publish cleanup:
+- only runs when publish actually executed and succeeded;
+- requires `uploaded=true` and `current_pointer_written=true` metadata;
+- respects `pipeline.spool.delete_audio_after_publish` and `pipeline.workspace.cleanup_after_publish`;
+- refuses unsafe deletes (root delete, out-of-root delete, symlink paths).
 
-## 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.
+Manual clean command:
+- `clean <session_id>` removes session work and spool subtree.
+- `clean --all` removes all workspace work and spool children.
+- durable cache is preserved unless `--clear-cache` is requested.
 
-## 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.
-- `previous/**` is session-durable state and must not be treated as run-local output scratch state.
-- Automatic post-archive cleanup only targets run-scoped directories and must never delete configured root directories.
-- Manual `clean` may delete session-scoped directories or the `workspace.root/work` directory, but it must preserve configured root directories and reject unsafe targets.
+## Invariants
+- campaign-aware session root is mandatory.
+- manifest-driven stage state is durable across runs.
+- cleanup guardrails prevent destructive root/out-of-scope deletion.

docs/operations.md

@@ -1,279 +1,249 @@
-# Operations
+# Operations Guide
 
-This guide describes the implemented operator lifecycle for Narratio.
+Operator workflow for running, recovering, and publishing Narratio sessions.
 
-For field-level configuration, see [docs/config.md](./config.md). For full command/flag reference, see [docs/cli.md](./cli.md).
+For command syntax, see [docs/cli.md](./cli.md). For field-level config, see [docs/config.md](./config.md).
 
-## Normal workflow (S3-first path)
+## Campaign and Session Selection
 
-1. Create or upload `session.yml`, or pass a local `session.yml` explicitly.
-2. Upload session `.flac` files to object storage under the configured session audio prefix.
-3. Run Narratio:
+Campaign selection priority:
+
+- `--campaign-file`
+- `--campaign`
+- `pipeline.campaigns.default_campaign_id`
+
+Session source priority:
+
+- `--session`
+- local default search paths
+- remote session object (S3) when local session file is not found and storage is configured
+
+## Session Initialization
+
+Use `session init` to generate a concrete session file for local or remote use.
+
+Local file:
 
 ```bash
-narratio run --session-id 2026-04-04
+narratio session init 2026-04-04 --output ./session.yml --date 2026-04-04 --title "Session 12"
 ```
 
-4. Read success output:
-- `narratio run: session <session_id>; executed=<n> skipped=<n>; manifest=<path>`
-- use `manifest=<path>` with `status` for inspection.
-
-Notes:
-- default config/campaign/session discovery checks system config locations unless `--config`, `--campaign`, and `--session` are passed.
-- when local `session.yml` discovery misses, `--session-id` loads remote `session.yml` from `{root_prefix}/campaigns/{campaign}/sessions/{session_id}/session.yml`.
-- S3 audio mode requires `session.inputs.audio_s3.prefix` and valid object-store access.
-
-Initialize a remote session skeleton:
+Remote session object:
 
 ```bash
-narratio session init --config /etc/narratio/pipeline.yml --campaign /etc/narratio/campaign.yml --session-id 2026-04-04 --remote
+narratio session init 2026-04-04 --remote --force
 ```
 
-Remote init writes `{root_prefix}/campaigns/{campaign}/sessions/{session_id}/session.yml`. It fails if the object already exists unless `--force` is passed.
+If `campaign.yml` sets `session_template_file`, `session init` renders it. Template variables must resolve to concrete values.
 
-Validate before running:
+## Standard Session Workflow
+
+1. Select pipeline/campaign/session config.
+2. Validate session readiness:
 
 ```bash
-narratio session validate --session-id 2026-04-04
+narratio session validate 2026-04-04
 ```
 
-## Restore workflow
-
-Use restore when local durable session state is missing or stale and archive current state is authoritative.
-
-Dry-run (no local writes):
+3. (Optional) inspect stage decisions:
 
 ```bash
-narratio restore --session-id 2026-04-04 --dry-run
+narratio session plan 2026-04-04
 ```
 
-Execution:
+4. Run the pipeline:
 
 ```bash
-narratio restore --session-id 2026-04-04
+narratio run 2026-04-04
 ```
 
-Post-restore analyze rerun pattern:
+5. Check state:
 
 ```bash
-narratio analyze --session-id 2026-04-04
+narratio session status 2026-04-04
 ```
 
-Restore source-of-truth:
-- remote commit marker: `current/run_id.txt`
-- remote current manifest: `current/manifest.json`
+## Stage Execution and Continuation Behavior
 
-Restore default scope:
-- includes `manifest.json`, `transcripts/**`, `artifacts/**`, `previous/**`
-- includes `audio/**` only with `--include-audio`
-- excludes `runs/**`, `logs/**`, `reports/**`, `config/**`, `inputs/**`, and `current/**` (except remote `current/manifest.json` as source)
+Canonical stage order:
 
-Reset local state before restore testing:
+1. `prepare`
+2. `transcribe`
+3. `merge`
+4. `polish`
+5. `normalize`
+6. `trim`
+7. `analyze`
+8. `publish`
+9. `notify`
+
+Execution rules:
+
+- succeeded stages are skipped unless `--force` is set;
+- `run` continues interrupted or partially completed sessions by running non-succeeded stages;
+- force rerunning a succeeded upstream stage marks succeeded downstream stages as `stale`.
+
+Single-stage execution:
 
 ```bash
-narratio clean --session-id 2026-04-04 --dry-run
-narratio clean --session-id 2026-04-04
-narratio restore --session-id 2026-04-04 --include-audio
+narratio run-stage normalize 2026-04-04 --force
 ```
 
-`clean` removes the local session work directory and session spool directory. It preserves the durable S3 audio cache by default, so repeated restore or forced prepare tests do not re-download large audio files.
+## Artifact Selection
 
-## Local filesystem layout and state artifacts
+`--artifacts` can be used on `run`, `run-stage`, `analyze`, and `publish`.
+
+Selection behavior:
+
+- validates names against `pipeline.scriptorium.artifacts`;
+- filters analyze execution to selected configured artifacts;
+- filters publish rules for `narratio.artifact.<name>` sources only;
+- does not suppress built-in transcript or bounds publish sources.
+
+## Publish Workflow
+
+Run publish only:
+
+```bash
+narratio publish 2026-04-04
+```
+
+Equivalent:
+
+```bash
+narratio run-stage publish 2026-04-04 --force
+```
+
+Publish commit model:
+
+- uploads run files under `{session_prefix}/runs/{run_id}/`;
+- uploads configured published outputs;
+- uploads `previous/**` cache files when present;
+- writes `current/manifest.json`;
+- writes `current/run_id.txt` last.
+
+`current/run_id.txt` is the remote current-state commit marker.
+
+## Publish Locks
+
+Lock sources:
+
+- static locks in `pipeline.publish.locks`
+- mutable remote locks in `{session_prefix}/locks.yml`
+
+Effective lock rules:
+
+- static and remote locks are merged;
+- static locks win on source collisions;
+- locked outputs are intentional skips;
+- lock add/remove commands mutate only remote lock state.
+
+Examples:
+
+```bash
+narratio session locks 2026-04-04
+narratio session locks add 2026-04-04 narratio.artifact.session_recap --reason "manual edits" --force
+narratio session locks remove 2026-04-04 narratio.artifact.session_recap
+```
+
+## Restore Workflow
+
+Use restore when local durable session state is missing or stale and remote committed current state is authoritative.
+
+Dry run:
+
+```bash
+narratio session restore 2026-04-04 --dry-run
+```
+
+Apply:
+
+```bash
+narratio session restore 2026-04-04
+```
+
+Default restore scope:
+
+- `manifest.json`
+- `transcripts/**`
+- `artifacts/**`
+- `previous/**` when needed by configured previous-session artifact inputs
+
+Optional:
+
+- `--include-audio` to include `audio/**`
+- `--force` to overwrite local conflicts
+
+Restore writes an execution report at `reports/restore-latest.json`.
+
+## Local State Layout
 
 Session root:
-- `{workspace.root}/work/{campaign}/{session_id}/`
 
-Primary state:
-- `manifest.json`: session-level stage state.
-- `runs/{run_id}/manifest.json`: invocation-level state.
-- `.lock`: session lock while a modifying command is active.
-- `inputs/campaign.yml`, `inputs/session.yml`, and `inputs/pipeline.resolved.yml`: materialized config inputs for the run.
+- `{workspace.root}/work/{campaign}/{session_id}`
 
-Canonical session directories:
-- `inputs/`
-- `audio/`
-- `transcripts/`
-- `artifacts/`
-- `previous/`
-- `reports/`
-- `logs/`
-- `config/`
-- `current/`
-- `runs/`
+Durable session paths:
 
-Run-local stage directories:
-- `runs/{run_id}/{stage}/` with stage-local `outputs/`, `logs/`, `reports/`, `config/`, `scratch/`.
+- `manifest.json`
+- `inputs/**`
+- `audio/**`
+- `transcripts/**`
+- `artifacts/**`
+- `previous/**`
+- `reports/**`
+- `logs/**`
+- `config/**`
+- `runs/**`
 
-Behavior:
-- directory creation is idempotent.
-- stage outputs are generally generated run-local first, then promoted to canonical paths on success.
-- restore installs downloaded files to canonical session paths and does not recreate historical run sandboxes.
+Run-local layout:
 
-## Analyze artifact execution lifecycle
+- `runs/{run_id}/{stage}/outputs`
+- `runs/{run_id}/{stage}/logs`
+- `runs/{run_id}/{stage}/reports`
+- `runs/{run_id}/{stage}/config`
+- `runs/{run_id}/{stage}/scratch`
 
-Analyze executes configured artifacts from `pipeline.scriptorium.artifacts`.
+Spool layout (runtime/transient):
 
-Execution model:
-- executable set = enabled artifacts, filtered by `--artifacts` when provided.
-- artifact-to-artifact dependencies are declared via `depends_on`.
-- selected artifacts run in deterministic dependency order.
-- after each successful artifact run, output is promoted to configured canonical `output_path`.
+- `{spool.root}/{campaign}/{session_id}/{run_id}/...`
+- restore audio spool under `{spool.root}/{campaign}/{session_id}/restore/audio`
 
-Configured artifact source reuse:
-- a non-executable configured artifact can satisfy inputs if its configured output file already exists and is valid.
-- reused configured artifact provenance is `filesystem.disabled_artifact_output`.
+Cache layout (durable S3 audio cache):
 
-`--artifacts` behavior:
-- accepted on `run`, `resume`, `run-stage analyze`, and `analyze`.
-- filters analyze execution only.
-- does not imply force on `run`, `resume`, or `run-stage`; `narratio analyze` is force-by-design.
+- `{cache.root}/s3/{bucket}/...`
 
-Canonical previous-session input behavior:
-- canonical sources use `narratio.previous_session.artifact.<artifact_key>`.
-- these inputs are hydrated by `prepare`, not `analyze`.
-- if analyze fails due to missing canonical previous cache, rerun:
-  - `narratio run-stage --session-id <id> --force prepare`
+## Cleanup
 
-## Remote archive layout and publish contract
-
-When archive is enabled and run upload is enabled, archive publishes under:
-
-- session prefix: `{root_prefix}/campaigns/{campaign}/sessions/{session_id}/`
-- run prefix: `{session_prefix}/runs/{run_id}/`
-
-Archive uploads:
-- run record files from run root (excluding `audio/`).
-- promoted files from explicit `archive.promote_artifacts` rules.
-- mutable session locks from helper commands live at `{session_prefix}/locks.yml`.
-
-Publish order:
-1. upload `current/manifest.json`
-2. upload `current/run_id.txt` last
-
-`current/run_id.txt` is the remote commit marker.
-
-Archive promotion is explicit and source-based:
-- Narratio does not auto-promote all generated analyze artifacts.
-- each rule resolves `source` through the artifact resolver/catalog model, then uploads to `dest`.
-- missing required promotion sources fail archive stage.
-- missing optional promotion sources are skipped.
-- invalid resolved artifacts fail archive stage.
-- `archive.locks` skips top-level promotion overwrites for locked sources while run-local uploads still publish.
-- remote locks from `{session_prefix}/locks.yml` are merged with static `archive.locks`; static locks win on duplicate sources.
-- locked required promotions are treated as intentional successful skips and are recorded in archive metadata.
-
-Lock helper behavior:
-- `narratio locks --session-id <id>` lists effective static and remote locks.
-- `narratio locks add --session-id <id> --reason <text> <source>` writes a remote lock.
-- `narratio locks add --session-id <id> --force --reason <text> <source>` updates an existing remote lock reason.
-- `narratio locks remove --session-id <id> <source>` removes only a remote lock.
-- `locks remove` cannot remove static pipeline locks.
-- remote lock writes check whether the lock store exists, but are not compare-and-swap atomic.
-
-## Resume, retry, restore, and safe rerun behavior
-
-Default skip:
-- `run` and `run-stage` skip already-succeeded stages unless `--force` is set.
-
-Resume:
-- `resume` starts at first non-succeeded stage.
-- `resume --force` runs full stage order.
-
-Restore conflict policy:
-- restore classifies local differences as conflicts.
-- without `--force`, restore fails when conflicts exist.
-- with `--force`, conflicting local files are overwritten by remote archive files.
-
-Forced reruns:
-- force-rerunning an upstream succeeded stage marks downstream succeeded stages as `stale`.
-- ordinary `--force` does not override archive locks.
-
-Safe rerun pattern:
-1. rerun the changed stage with `--force`.
-2. run `resume` to rebuild downstream stages.
-
-## Cleanup behavior
-
-Automatic post-archive cleanup is considered only when archive stage executed and succeeded.
-
-Automatic cleanup toggles:
-- `pipeline.spool.delete_audio_after_archive=true` deletes run-scoped spool audio.
-- `pipeline.workspace.cleanup_after_archive=true` deletes run-scoped local run directory.
-
-Manual cleanup:
-- `narratio clean --session-id <id>` deletes `{workspace.root}/work/{campaign}/{session_id}` and `{spool.root}/{campaign}/{session_id}`.
-- `narratio clean --all` deletes all local session work under `{workspace.root}/work` and all spool children under `{spool.root}`.
-- `--dry-run` prints targets without deleting.
-- `--clear-cache` also removes matching S3 audio cache files. Without it, cache is preserved.
-
-The S3 audio cache under `pipeline.cache.root` is durable input cache state, not workspace or spool state. Automatic cleanup and default manual cleanup do not delete it.
-
-Cleanup eligibility gates:
-- archive enabled
-- archive run upload enabled
-- run record upload completed
-- current pointer write completed (`current/run_id.txt` written)
-
-No cleanup for failed/incomplete/unarchived/archive-skipped runs.
-
-## Failure and recovery playbooks
-
-After run failure, Narratio keeps:
-- session manifest
-- run manifest
-- run-local artifacts/logs/config/reports
-
-Failed or incomplete runs remain local-only.
-
-After restore failure:
-- already-installed restore files remain in place.
-- restore does not roll back prior successful installs.
-- existing local manifest is preserved if restored manifest validation/install fails.
-
-Recommended recovery:
-
-1. inspect state:
+Session-scoped cleanup:
 
 ```bash
-narratio status --session-id 2026-04-04
+narratio clean 2026-04-04
 ```
 
-This reports local manifest state, committed remote current state, expected remote transcript/artifact availability, and archive locks.
-
-2. for one manifest file, run:
+Global cleanup:
 
 ```bash
-narratio status --manifest <manifest-path>
+narratio clean --all
 ```
 
-3. for restore-specific checks, run:
+Dry-run and cache variants:
 
 ```bash
-narratio restore --session-id 2026-04-04 --dry-run
+narratio clean 2026-04-04 --dry-run --clear-cache
+narratio clean --all --dry-run --clear-cache
 ```
 
-4. fix root cause (config/input/credentials/storage/service availability).
-5. continue with `resume`, or targeted `run-stage --force` followed by `resume`.
+Rules:
 
-## Restore report
+- `clean` deletes work/spool session state;
+- cache is preserved unless `--clear-cache` is set;
+- automatic post-publish cleanup is gated by successful publish commit plus:
+  - `pipeline.spool.delete_audio_after_publish=true`
+  - `pipeline.workspace.cleanup_after_publish=true`
 
-Non-dry-run restore writes a durable report at:
-- `reports/restore-latest.json`
+## Operational Caveats
 
-Report content includes:
-- identity (`campaign`, `session_id`, `run_id`)
-- mode flags (`dry_run`, `force`, `include_audio`)
-- plan counts and execution counts
-- per-action status
-
-Dry-run does not write restore report files.
-
-## Operational caveats
-
-- `status` with no config/session flags still requires explicit `--manifest`.
-- `status --session-id <id>` uses normal config/session loading, including remote session fallback.
-- `status --session-id <id>` includes the same promoted remote output availability view as `artifacts list --remote` when storage is configured.
-- local and S3 audio input modes are mutually exclusive.
-- archive publish requires upstream stages through `analyze` to be `succeeded`.
-- required promotion rules can fail when selected analyze artifacts did not generate a required file path.
-- restore requires configured remote object storage and committed remote current state.
+- Local and S3 audio modes are mutually exclusive.
+- Publish requires prerequisite stages through analyze to be succeeded.
+- Restore requires configured object storage and committed remote current state.
+- Storage-backed commands load filesystem secrets before object-store initialization.

docs/policy/architecture.md

@@ -19,7 +19,7 @@ It coordinates specialized downstream systems rather than reimplementing their d
 - Audita handles transcript correction and polishing.
 - Scriptorium handles prompt execution and generated artifacts.
 
-Narratio owns orchestration, configuration loading, session/run state, local and remote path modeling, manifest persistence, stage sequencing, resume behavior, and archive semantics.
+Narratio owns orchestration, configuration loading, session/run state, local and remote path modeling, manifest persistence, stage sequencing, resume behavior, and publish semantics.
 
 Narratio should remain explicit and comprehensible. It is not intended to become a generic workflow engine.
 
@@ -80,7 +80,7 @@ It should record:
 - input and output refs;
 - logs and generated config refs;
 - checksums or provenance where useful;
-- non-secret adapter and archive metadata.
+- non-secret adapter and publish metadata.
 
 Resume behavior should be manifest-driven. Filesystem state may be inspected and validated, but it should not replace manifest stage state as the source of run progress.
 
@@ -117,19 +117,19 @@ Narratio should not become a secondary configuration system for downstream tools
 
 Local and remote paths are part of Narratio’s application contract.
 
-Code should use centralized path helpers for workspace, spool, session, run, artifact, log, config, and archive paths. Stages should avoid reconstructing canonical paths through scattered string concatenation.
+Code should use centralized path helpers for workspace, spool, session, run, artifact, log, config, and publish/current paths. Stages should avoid reconstructing canonical paths through scattered string concatenation.
 
 Storage backends should receive explicit bucket-relative keys. Storage implementations should not infer campaign, session, run, or root-prefix semantics.
 
-## Archive Invariants
+## Publish Invariants
 
-Archive behavior must preserve a clear commit boundary.
+Publish behavior must preserve a clear commit boundary.
 
-A remote run is current only after the archive stage has successfully uploaded the run record, required promoted outputs, `current/manifest.json`, and finally `current/run_id.txt`.
+A remote run is current only after the publish stage has successfully uploaded the run record, required published outputs, `current/manifest.json`, and finally `current/run_id.txt`.
 
 `current/run_id.txt` is the final remote commit marker and must be written last.
 
-Failed, incomplete, skipped, or uncommitted archive attempts must not be presented as current remote state. Local cleanup is permitted only after successful archive commit and only when explicitly configured.
+Failed, incomplete, skipped, or uncommitted publish attempts must not be presented as current remote state. Local cleanup is permitted only after successful publish commit and only when explicitly configured.
 
 ## Security and Privacy
 
@@ -139,7 +139,7 @@ Rules:
 
 - Do not store raw secrets in pipeline or session YAML.
 - Use environment variable names or secret-file references for secret handling.
-- Do not write raw secret values to manifests, logs, generated configs, or archive metadata.
+- Do not write raw secret values to manifests, logs, generated configs, or publish metadata.
 - Treat transcripts, generated artifacts, prompts, reports, and logs as potentially sensitive.
 - Avoid logging transcript or prompt content unless there is a deliberate diagnostic reason.
 
@@ -177,7 +177,7 @@ Tests should cover:
 - stage success, failure, skip, and resume behavior;
 - adapter command construction;
 - fake storage behavior;
-- archive commit ordering;
+- publish commit ordering;
 - example config validity where practical.
 
 Live S3, WhisperX, LLM, or subprocess integration tests should be explicit integration tests, not required for ordinary unit test runs.

docs/policy/development.md

@@ -6,7 +6,7 @@ Canonical contributor workflow and engineering conventions for implemented Narra
 ## Repository layout
 
 - `cmd/narratio/`: CLI entrypoint.
-- `internal/app/`: command handlers, plan/run/resume orchestration, cleanup gates, secrets loading.
+- `internal/app/`: command handlers, run/stage orchestration, cleanup gates, secrets loading.
 - `internal/config/`: strict YAML loading, defaults, and validation.
 - `internal/stage/`: stage implementations and stage registry/order.
 - `internal/adapters/`: external boundary adapters (WhisperX, Seriatim, Audita, Scriptorium, storage, notify).
@@ -75,7 +75,7 @@ Remote-storage commands must obtain object storage through the app-level command
 
 1. Implement stage behavior in `internal/stage` with clear input/output boundaries.
 2. Keep external transport/subprocess details in `internal/adapters`.
-3. Preserve manifest and promotion semantics expected by runner and archive logic.
+3. Preserve manifest and publish-output semantics expected by runner and publish logic.
 4. Add/update stage and adapter tests.
 5. Update internal component contracts in `docs/internal/`.
 

docs/roadmap/operations.md

@@ -1,52 +0,0 @@
-# Roadmap: Operator Helper Commands
-
-## Status
-
-Implemented.
-
-The operator helper command set is no longer conceptual. Current behavior is documented in:
-
-- `docs/cli.md`
-- `docs/operations.md`
-- `docs/config.md`
-- `docs/internal/artifacts.md`
-- `docs/internal/stage-archive.md`
-
-## Implemented Commands
-
-- `narratio session validate`
-- `narratio status --manifest <path>`
-- `narratio status --session-id <id>`
-- `narratio session init --output <path>`
-- `narratio session init --remote`
-- `narratio artifacts list`
-- `narratio artifacts list --remote`
-- `narratio locks`
-- `narratio locks add <source>`
-- `narratio locks remove <source>`
-
-## Implemented Decisions
-
-- Helper output is text-only. No JSON schema exists yet.
-- `status` remains a top-level command.
-- `session validate`, `session init`, and `artifacts list` are nested helper commands.
-- `locks` is the single top-level command for listing, adding, and removing archive promotion locks.
-- Remote session initialization requires explicit `--remote`.
-- Local session initialization requires `--output`.
-- Remote artifact availability is opt-in with `artifacts list --remote`.
-- Mutable locks are source-based and stored at `{session_prefix}/locks.yml`.
-- The remote lock store uses strict YAML with top-level `locks`.
-- Static `pipeline.archive.locks` and remote locks are merged; static locks win on duplicate sources.
-- `locks remove` removes only remote locks.
-- Ordinary execution `--force` does not override locks.
-- Remote lock writes use existence checks and `--force` for updates; there is no compare-and-swap protection.
-
-## Remaining Future Enhancements
-
-These are intentionally not implemented:
-
-- `--json` output for helper commands.
-- Optimistic concurrency or ETag compare-and-swap for remote lock mutations.
-- Rich remote artifact availability across historical run-local objects.
-- Session-lock acquisition for remote mutation helpers.
-- Broader campaign helper commands such as `campaign validate` or `campaign publish`.

docs/troubleshooting.md

@@ -1,380 +1,273 @@
 # Troubleshooting
 
-## Purpose
-Canonical operator troubleshooting guide for recurring implemented Narratio failures.
+Operational diagnosis guide for common Narratio failures.
 
-## Config file discovery failure
+## Config file not found
 
 Symptom:
-- `run`, `plan`, `resume`, `run-stage`, or `restore` fails with config/session not found.
 
-Likely Cause:
-- `pipeline.yml`, `campaign.yml`, or `session.yml` is missing from system discovery paths.
-- a local working-directory config file was not passed explicitly.
+- command fails to resolve `pipeline.yml`, `campaign.yml`, or `session.yml`.
+
+Likely causes:
+
+- missing files in default search paths;
+- wrong campaign selection;
+- omitted explicit flags.
 
 Diagnostics:
 
 ```bash
-ls -l /usr/local/etc/narratio/pipeline.yml /etc/narratio/pipeline.yml
-ls -l /usr/local/etc/narratio/campaign.yml /etc/narratio/campaign.yml
-ls -l /usr/local/etc/narratio/session.yml /etc/narratio/session.yml
+narratio session plan 2026-04-04
 ```
 
-Safe Fix:
-- pass explicit `--config`, `--campaign`, and `--session`.
-- or place files in documented discovery paths.
+Safe fix:
 
-Links:
-- [docs/config.md](./config.md)
-- [docs/cli.md](./cli.md)
+- pass explicit `--config`, `--campaign` or `--campaign-file`, and `--session`.
 
-## Session template rendering failure
+## Session template placeholders rejected
 
 Symptom:
-- load fails with unresolved placeholder or `session_id` mismatch.
 
-Likely Cause:
-- templated `session.yml` used without `--session-id`.
-- rendered `session_id` differs from passed `--session-id`.
+- load error says session file must be concrete or contains `{{ ... }}` placeholders.
+
+Likely cause:
+
+- using template content as runtime session config.
 
 Diagnostics:
 
 ```bash
-narratio plan --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session ./session.yml --session-id 2026-04-04
+narratio session validate 2026-04-04 --session /path/session.yml
 ```
 
-Safe Fix:
-- pass `--session-id` when template placeholders are present.
-- ensure rendered `session_id` matches intended run session id.
+Safe fix:
 
-Links:
-- [docs/config.md](./config.md)
+- generate concrete session YAML with `narratio session init`.
 
-## Strict YAML decode or validation failure
+## Strict decode or schema validation failure
 
 Symptom:
-- config load fails with unknown field or validation error.
 
-Likely Cause:
-- typo/stale field name.
-- missing required fields or invalid constraints.
+- unknown field / invalid value error during config load.
+
+Likely cause:
+
+- stale field name, typo, invalid enum, or invalid duration/path format.
 
 Diagnostics:
 
 ```bash
-narratio plan --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml --session-id 2026-04-04
+narratio session plan 2026-04-04 --config /path/pipeline.yml --campaign-file /path/campaign.yml --session /path/session.yml
 ```
 
-Safe Fix:
-- align fields/values to canonical config reference and examples.
+Safe fix:
 
-Links:
-- [docs/config.md](./config.md)
-- [examples/](../examples/)
+- align config with [docs/config.md](./config.md) and maintained files under `examples/`.
 
-## `--artifacts` selection failure
+## Audio mode conflict
 
 Symptom:
-- `run`/`resume`/`run-stage` fails with invalid or unknown artifact selection.
 
-Likely Cause:
-- `--artifacts` contains blank names or unknown artifact keys.
-- `pipeline.scriptorium.artifacts` missing while using `--artifacts`.
+- validation fails on session audio configuration.
+
+Likely cause:
+
+- configured both local and S3 session audio inputs.
+
+Safe fix:
+
+- use local mode (`audio_dir` or `audio_files`) or S3 mode (`audio_s3.prefix`), not both.
+
+## `--artifacts` selection error
+
+Symptom:
+
+- unknown artifact key or invalid `--artifacts` usage.
+
+Likely causes:
+
+- key not defined in `pipeline.scriptorium.artifacts`;
+- empty list entry (for example trailing comma);
+- `run-stage` used with non-`analyze`/`publish` target.
+
+Safe fix:
+
+- provide only configured keys and use `--artifacts` with supported commands/stages.
+
+## Previous-session artifact input missing
+
+Symptom:
+
+- prepare/analyze fails due to missing required previous-session artifact cache input.
+
+Likely causes:
+
+- missing `session.previous_session_id`;
+- previous artifact not restored/published for source session.
 
 Diagnostics:
 
 ```bash
-narratio run --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml --session-id 2026-04-04 --artifacts player_handout
+narratio session validate 2026-04-04
+narratio session status 2026-04-04
 ```
 
-Safe Fix:
-- use configured artifact keys only.
-- ensure `pipeline.scriptorium.artifacts` is defined.
-
-Links:
-- [docs/cli.md](./cli.md)
-- [docs/config.md](./config.md)
-
-## `run-stage --artifacts` on non-analyze stage
-
-Symptom:
-- `run-stage` fails with `--artifacts is only supported for stage "analyze"`.
-
-Likely Cause:
-- `--artifacts` was used with a non-`analyze` stage.
-
-Diagnostics:
+Safe fix:
 
 ```bash
-narratio run-stage --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml --session-id 2026-04-04 --artifacts session_recap polish
+narratio session restore 2026-04-04
 ```
 
-Safe Fix:
-- use `--artifacts` only with `run-stage ... analyze`.
-
-Links:
-- [docs/cli.md](./cli.md)
-
-## Configured artifact dependency/input validation failure
-
-Symptom:
-- config validation fails for `depends_on`, `narratio.artifact.<name>` source, or artifact output path.
-
-Likely Cause:
-- `narratio.artifact.<name>` source missing matching `depends_on` key.
-- dependency references unknown artifact key.
-- dependency self-reference or enabled dependency cycle.
-- artifact output path missing/invalid/outside `artifacts/` root.
-
-Diagnostics:
+or rerun prepare after correcting session config:
 
 ```bash
-narratio plan --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml --session-id 2026-04-04
+narratio run-stage prepare 2026-04-04 --force
 ```
 
-Safe Fix:
-- ensure artifact-to-artifact inputs have explicit `depends_on` entries using artifact keys.
-- ensure referenced artifacts exist and define valid `output_path` values.
-- keep output paths relative and under `artifacts/`.
-
-Links:
-- [docs/config.md](./config.md)
-- [docs/internal/stage-analyze.md](./internal/stage-analyze.md)
-
-## Required configured artifact input unavailable at analyze time
-
-Symptom:
-- analyze fails because configured input source is unavailable.
-
-Likely Cause:
-- required upstream configured artifact was not selected/executed this run.
-- non-executable dependency output file is missing or invalid on disk.
-
-Diagnostics:
-
-```bash
-narratio status --manifest /path/to/manifest.json
-narratio run-stage --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml --session-id 2026-04-04 --artifacts player_handout analyze
-```
-
-Safe Fix:
-- run analyze with needed artifacts selected.
-- or ensure dependency output file exists at configured path and is valid.
-
-Links:
-- [docs/operations.md](./operations.md)
-- [docs/config.md](./config.md)
-
-## Manifest/status path failure
-
-Symptom:
-- `status` fails because manifest path is missing, unreadable, or invalid.
-
-Likely Cause:
-- wrong manifest path.
-- manifest removed after cleanup.
-- `--manifest` omitted.
-
-Diagnostics:
-
-```bash
-narratio status --manifest /path/to/manifest.json
-ls -l /path/to/manifest.json
-```
-
-Safe Fix:
-- use manifest path printed by `run`, `resume`, or `run-stage`.
-
-Links:
-- [docs/cli.md](./cli.md)
-- [docs/operations.md](./operations.md)
-
 ## Session lock conflict (`.lock`)
 
 Symptom:
-- `run`, `resume`, `run-stage`, or `restore` fails with lock conflict for session workdir.
 
-Likely Cause:
-- another Narratio process is running same session.
-- stale lock from interrupted prior run.
+- command fails acquiring session lock.
+
+Likely causes:
+
+- another process is running for the same session;
+- stale lock left by interrupted process.
 
 Diagnostics:
 
 ```bash
 ls -l {workspace.root}/work/{campaign}/{session_id}/.lock
-cat {workspace.root}/work/{campaign}/{session_id}/.lock
 ps aux | grep narratio
 ```
 
-Safe Fix:
-- wait for active process to finish.
-- if no process is active, remove only stale session `.lock` file.
+Safe fix:
 
-Links:
-- [docs/operations.md](./operations.md)
-- [docs/internal/workspace.md](./internal/workspace.md)
-
-## Restore remote current pointer or manifest missing
-
-Symptom:
-- `restore` fails with remote current pointer or current manifest errors.
-
-Likely Cause:
-- `current/run_id.txt` was never published.
-- `current/manifest.json` is missing for the session prefix.
-- archive commit did not complete.
-
-Diagnostics:
-
-```bash
-narratio restore --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml --session-id 2026-04-04 --dry-run
-```
-
-Safe Fix:
-- verify archive stage succeeded for the target session.
-- rerun/archive from a healthy source workspace so current pointers are published.
-
-Links:
-- [docs/operations.md](./operations.md)
-- [docs/internal/stage-archive.md](./internal/stage-archive.md)
-
-## Restore manifest identity mismatch
-
-Symptom:
-- `restore` fails because remote manifest session or campaign does not match requested values.
-
-Likely Cause:
-- wrong `--session-id` or wrong session config selected.
-- archive prefix points to a different campaign/session.
-
-Diagnostics:
-
-```bash
-narratio restore --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml --session-id 2026-04-04 --dry-run
-```
-
-Safe Fix:
-- use the correct session config and `--session-id`.
-- verify campaign/session identity in local config before restore.
-
-Links:
-- [docs/config.md](./config.md)
-- [docs/operations.md](./operations.md)
+- wait for active process completion;
+- remove stale lock only after confirming no live process owns it.
 
 ## Restore conflict without `--force`
 
 Symptom:
-- `restore` fails with `restore conflict` and conflict counts.
 
-Likely Cause:
-- local durable file differs from remote file for one or more planned restore paths.
+- restore fails with conflict count.
+
+Likely cause:
+
+- local durable files differ from remote restore sources.
 
 Diagnostics:
 
 ```bash
-narratio restore --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml --session-id 2026-04-04 --dry-run
+narratio session restore 2026-04-04 --dry-run
 ```
 
-Safe Fix:
-- review planned conflicts.
-- rerun with `--force` only when remote state should overwrite local state.
+Safe fix:
 
-Links:
-- [docs/cli.md](./cli.md)
-- [docs/operations.md](./operations.md)
+- review conflicts;
+- rerun with `--force` only when remote state should overwrite local.
 
-## Restore report expectations
+## Restore current-state discovery failure
 
 Symptom:
-- operator expects restore report file but does not find one.
 
-Likely Cause:
-- restore was executed in `--dry-run` mode.
-- restore failed before report persistence path (for example lock acquisition failure).
+- restore cannot find current pointer or current manifest.
+
+Likely causes:
+
+- no committed publish current state;
+- storage credentials or connectivity failure.
 
 Diagnostics:
 
 ```bash
-ls -l {workspace.root}/work/{campaign}/{session_id}/reports/restore-latest.json
+narratio session status 2026-04-04
+narratio session restore 2026-04-04 --dry-run
 ```
 
-Safe Fix:
-- run non-dry-run restore for durable report output.
-- resolve lock or early preflight failures and retry.
+Safe fix:
 
-Links:
-- [docs/operations.md](./operations.md)
+- resolve storage/auth issue;
+- republish from healthy local state if current pointer is missing.
 
-## Secrets env-dir or credential-env failure
+## Publish output failure
 
 Symptom:
-- startup fails loading secrets directory, or stage fails due to missing credential env vars.
 
-Likely Cause:
-- invalid `pipeline.secrets.env_dir` path/permissions.
-- required credential env var unset/empty.
+- publish fails on missing required source, upload error, or commit write.
+
+Likely causes:
+
+- required source file not produced;
+- lock/state expectations mismatch;
+- remote storage failure.
+
+Diagnostics:
+
+```bash
+narratio session artifacts 2026-04-04 --remote
+narratio session status 2026-04-04
+narratio run-stage publish 2026-04-04 --force
+```
+
+Safe fix:
+
+- regenerate missing sources by rerunning prerequisite stages;
+- correct publish source/destination rules;
+- retry after storage failure is resolved.
+
+## Secrets or storage credential failure
+
+Symptom:
+
+- object-store command fails at initialization/auth.
+
+Likely causes:
+
+- invalid `pipeline.secrets.env_dir`;
+- missing credential environment variables;
+- invalid S3 endpoint/bucket settings.
 
 Diagnostics:
 
 ```bash
 ls -la /path/to/secrets_dir
-env | grep -E 'AUDITA|OBJECT_STORAGE|AWS|SCRIPTORIUM'
+env | grep -E 'OBJECT_STORAGE|AWS|AUDITA|SCRIPTORIUM'
 ```
 
-Safe Fix:
-- fix secrets directory and credential env vars.
+Safe fix:
+
+- correct secret-file path and permissions;
+- provide required env vars;
 - keep secret values out of YAML.
 
-Links:
-- [docs/config.md](./config.md)
-
-## S3-audio prepare failure
+## S3 audio prepare failure
 
 Symptom:
-- `prepare` fails in S3 mode (listing/downloading/no audio/backend error).
 
-Likely Cause:
-- wrong `session.inputs.audio_s3.prefix`.
-- no `.flac` files at resolved prefix.
-- invalid/missing object-store credentials or backend config.
-- mixed local+S3 audio input config.
+- prepare fails listing/downloading session S3 audio.
+
+Likely causes:
+
+- incorrect `session.inputs.audio_s3.prefix`;
+- no matching `.flac` objects;
+- storage connectivity or permissions failure.
 
 Diagnostics:
 
 ```bash
-narratio run-stage --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml --session-id 2026-04-04 prepare
+narratio run-stage prepare 2026-04-04 --force
 ```
 
-Safe Fix:
-- configure exactly one audio source mode.
-- verify `.flac` files and storage access.
+Safe fix:
 
-Links:
+- verify prefix contents and storage access;
+- keep session audio mode consistent.
+
+## References
+
+- [docs/cli.md](./cli.md)
 - [docs/config.md](./config.md)
 - [docs/operations.md](./operations.md)
-
-## Archive promotion/current-pointer failure
-
-Symptom:
-- archive fails on required promotion source missing or pointer write failure.
-
-Likely Cause:
-- required promoted file absent (including analyze outputs not generated for this run).
-- storage upload failed before `current/run_id.txt` commit marker write.
-
-Diagnostics:
-
-```bash
-narratio status --manifest /path/to/manifest.json
-narratio run-stage --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml --session-id 2026-04-04 archive
-```
-
-Safe Fix:
-- rerun or resume upstream stages to generate required files.
-- adjust promotion `source`/`dest` rules to match artifacts that must exist.
-- retry after storage issue is resolved.
-
-Links:
-- [docs/operations.md](./operations.md)
-- [docs/config.md](./config.md)
-- [docs/internal/stage-archive.md](./internal/stage-archive.md)
+- [docs/internal/stage-publish.md](./internal/stage-publish.md)

examples/campaigns/sample-campaign/autocorrect.yml

@@ -0,0 +1 @@
+[]

examples/campaigns/sample-campaign/campaign.yml

@@ -1,4 +1,5 @@
-campaign: sample-campaign
+campaign_id: sample-campaign
+session_template_file: ./session.template.yml
 inputs:
   speakers_file: ./speakers.yml
   autocorrect_file: ./autocorrect.yml

examples/campaigns/sample-campaign/glossary.yml

@@ -0,0 +1 @@
+[]

examples/campaigns/sample-campaign/session.template.yml

@@ -0,0 +1,3 @@
+session_id: "{{ session_id }}"
+inputs:
+  audio_dir: ./audio

examples/campaigns/sample-campaign/speakers.yml

@@ -0,0 +1,5 @@
+match:
+  - speaker: "Eric Rakestraw"
+    match:
+      - "Eric_Rakestraw"
+      - "Eric"

examples/pipeline.full.annotated.yml

@@ -4,21 +4,18 @@
 workspace:
   # Optional: defaults to /var/lib/narratio.
   root: /var/lib/narratio/workspace
-  # Optional: remove run-scoped workdir after successful archive commit.
-  cleanup_after_archive: false
+  # Optional: remove run-scoped workdir after successful publish commit.
+  cleanup_after_publish: false
 
 # Optional: local secret file loader (directory of ENV_VAR_NAME files).
 # secrets:
 #   env_dir: ./secrets
 
 storage:
-  # Optional storage backend selector; use "s3" for archive + S3 audio workflows.
+  # Optional storage backend selector; use "s3" for publish + S3 audio workflows.
   backend: s3
-  # Compatibility fields retained in schema.
-  bucket: ""
-  prefix: ""
   s3:
-    # Required when using S3 audio or S3 archive uploads.
+    # Required when using S3 audio or S3 publish uploads.
     bucket: my-dnd-archive
     # Optional; defaults to "dnd".
     root_prefix: dnd
@@ -30,20 +27,26 @@ storage:
     access_key_id_env: OBJECT_STORAGE_KEY_ID
     secret_access_key_env: OBJECT_STORAGE_KEY
 
+campaigns:
+  # Optional; defaults to /usr/local/share/narratio/campaigns.
+  root: /usr/local/share/narratio/campaigns
+  # Optional command default when --campaign is omitted.
+  default_campaign_id: sample-campaign
+
 spool:
   # Optional; defaults to /var/spool/narratio.
   root: /var/spool/narratio
-  # Optional cleanup of run-scoped spool audio after successful archive commit.
-  delete_audio_after_archive: false
+  # Optional cleanup of run-scoped spool audio after successful publish commit.
+  delete_audio_after_publish: false
 
-archive:
+publish:
   # Optional booleans; defaults are true.
   enabled: true
   upload_run: true
-  # Optional promotion rules; sources use Narratio artifact source IDs.
-  promote_artifacts:
-    - source: narratio.transcript.trimmed
-      dest: transcripts/trimmed.json
+  # Optional publish output rules; sources use Narratio artifact source IDs.
+  outputs:
+    - source: narratio.transcript.final_trimmed
+      dest: transcripts/final.trimmed.json
       required: true
     - source: narratio.artifact.session_recap
       dest: artifacts/session_recap.md
@@ -96,14 +99,14 @@ audita:
 
 normalize:
   # Optional; defaults shown explicitly.
-  output_path: transcripts/normalized.json
+  output_path: transcripts/final.json
   output_schema: seriatim-intermediate
   report: true
 
 trim:
   # Keep disabled unless bounds prompt integration is configured.
   enabled: false
-  output_path: transcripts/trimmed.json
+  output_path: transcripts/final.trimmed.json
   bounds:
     prompt_id: dnd.session_bounds
     profile_id: local-fast
@@ -130,7 +133,7 @@ scriptorium:
       timeout: 10m
       inputs:
         transcript:
-          source: narratio.transcript.trimmed
+          source: narratio.transcript.final_trimmed
           required: true
         previous_recap:
           source: narratio.previous_session.artifact.session_recap
@@ -158,21 +161,13 @@ scriptorium:
           source: narratio.artifact.session_recap
           required: true
         transcript:
-          source: narratio.transcript.trimmed
+          source: narratio.transcript.final_trimmed
           required: true
       vars:
         session_id: true
         campaign_name: true
         output_kind: player_handout
 
-analyzer:
-  # Optional adapter settings.
-  binary_path: ""
-  timeout: 2m
-  artifacts:
-    output_dir: ""
-    types: []
-
 notification:
   # Optional notification settings.
   backend: ""

examples/pipeline.minimal.yml

@@ -1,2 +1,6 @@
+campaigns:
+  root: /usr/local/share/narratio/campaigns
+  default_campaign_id: sample-campaign
+
 whisperx:
   transcribe_url: "https://transcription.example.com/transcribe"

examples/pipeline.production.yml

@@ -1,6 +1,6 @@
 workspace:
   root: /var/lib/narratio/workspace
-  cleanup_after_archive: true
+  cleanup_after_publish: true
 
 storage:
   backend: s3
@@ -11,16 +11,20 @@ storage:
     access_key_id_env: OBJECT_STORAGE_KEY_ID
     secret_access_key_env: OBJECT_STORAGE_KEY
 
+campaigns:
+  root: /usr/local/share/narratio/campaigns
+  default_campaign_id: sample-campaign
+
 spool:
   root: /var/spool/narratio
-  delete_audio_after_archive: true
+  delete_audio_after_publish: true
 
-archive:
+publish:
   enabled: true
   upload_run: true
-  promote_artifacts:
-    - source: narratio.transcript.trimmed
-      dest: transcripts/trimmed.json
+  outputs:
+    - source: narratio.transcript.final_trimmed
+      dest: transcripts/final.trimmed.json
       required: true
     - source: narratio.artifact.session_recap
       dest: artifacts/session_recap.md
@@ -57,7 +61,7 @@ audita:
   report: true
 
 normalize:
-  output_path: transcripts/normalized.json
+  output_path: transcripts/final.json
   output_schema: seriatim-intermediate
   report: true
 
@@ -78,7 +82,7 @@ scriptorium:
       timeout: 10m
       inputs:
         transcript:
-          source: narratio.transcript.trimmed
+          source: narratio.transcript.final_trimmed
           required: true
         previous_recap:
           source: narratio.previous_session.artifact.session_recap
@@ -102,14 +106,11 @@ scriptorium:
           source: narratio.artifact.session_recap
           required: true
         transcript:
-          source: narratio.transcript.trimmed
+          source: narratio.transcript.final_trimmed
           required: true
       vars:
         session_id: true
         output_kind: player_handout
 
-analyzer:
-  timeout: 2m
-
 notification:
   timeout: 30s

internal/adapters/analyzer/fake.go

@@ -1,40 +0,0 @@
-package analyzer
-
-import "context"
-
-// NoopRunner is a deterministic no-op analyzer adapter.
-type NoopRunner struct{}
-
-// Run returns the requested output path with placeholder metadata.
-func (n *NoopRunner) Run(ctx context.Context, req AnalyzeRequest) (AnalyzeResult, error) {
-	if err := ctx.Err(); err != nil {
-		return AnalyzeResult{}, err
-	}
-	return AnalyzeResult{ArtifactPath: req.OutputPath, Metadata: map[string]any{"placeholder": true}}, nil
-}
-
-// FakeRunner captures analyze requests and returns deterministic responses.
-type FakeRunner struct {
-	Requests []AnalyzeRequest
-	Err      error
-	Result   AnalyzeResult
-}
-
-// Run records request and returns configured response.
-func (f *FakeRunner) Run(ctx context.Context, req AnalyzeRequest) (AnalyzeResult, error) {
-	if err := ctx.Err(); err != nil {
-		return AnalyzeResult{}, err
-	}
-	f.Requests = append(f.Requests, req)
-	if f.Err != nil {
-		return AnalyzeResult{}, f.Err
-	}
-	res := f.Result
-	if res.ArtifactPath == "" {
-		res.ArtifactPath = req.OutputPath
-	}
-	if res.Metadata == nil {
-		res.Metadata = map[string]any{"fake": true}
-	}
-	return res, nil
-}

internal/adapters/analyzer/fake_test.go

@@ -1,31 +0,0 @@
-package analyzer
-
-import (
-	"context"
-	"errors"
-	"testing"
-)
-
-func TestFakeRunnerCapturesRequestAndReturnsPath(t *testing.T) {
-	fake := &FakeRunner{}
-	req := AnalyzeRequest{ArtifactType: "session-log", OutputPath: "artifacts/session-log.md"}
-
-	res, err := fake.Run(context.Background(), req)
-	if err != nil {
-		t.Fatalf("Run() error = %v", err)
-	}
-	if len(fake.Requests) != 1 || fake.Requests[0].ArtifactType != "session-log" {
-		t.Fatalf("requests = %#v, want captured request", fake.Requests)
-	}
-	if res.ArtifactPath != req.OutputPath {
-		t.Fatalf("artifact path = %q, want %q", res.ArtifactPath, req.OutputPath)
-	}
-}
-
-func TestFakeRunnerError(t *testing.T) {
-	fake := &FakeRunner{Err: errors.New("boom")}
-	_, err := fake.Run(context.Background(), AnalyzeRequest{})
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-}

internal/adapters/analyzer/runner.go

@@ -1,28 +0,0 @@
-// Package analyzer declares the adapter contract for artifact analysis generation.
-package analyzer
-
-import "context"
-
-// TODO: implement analyzer integration once the analyzer contract is finalized.
-
-// Runner is the adapter boundary for analyzer invocations.
-type Runner interface {
-	Run(ctx context.Context, req AnalyzeRequest) (AnalyzeResult, error)
-}
-
-// AnalyzeRequest describes one analyzer artifact generation request.
-type AnalyzeRequest struct {
-	ArtifactType            string
-	ProcessedTranscriptPath string
-	ContextReferences       []string
-	OutputPath              string
-	GeneratedConfigPath     string
-	StdoutLogPath           string
-	StderrLogPath           string
-}
-
-// AnalyzeResult describes analyzer output.
-type AnalyzeResult struct {
-	ArtifactPath string
-	Metadata     map[string]any
-}

internal/adapters/audita/fake_test.go

@@ -14,7 +14,7 @@ func TestFakeRunnerCapturesRequestAndReturnsPath(t *testing.T) {
 	dir := t.TempDir()
 	req := PolishRequest{
 		GeneratedConfigPath: filepath.Join(dir, "config", "audita.yml"),
-		OutputProcessedPath: filepath.Join(dir, "transcripts", "processed.json"),
+		OutputProcessedPath: filepath.Join(dir, "transcripts", "polished.json"),
 		StdoutLogPath:       filepath.Join(dir, "logs", "audita.stdout.log"),
 		StderrLogPath:       filepath.Join(dir, "logs", "audita.stderr.log"),
 	}

internal/adapters/audita/subprocess_test.go

@@ -52,9 +52,9 @@ func TestSubprocessRunnerSuccessArgsEnvAndValidation(t *testing.T) {
 	dir := t.TempDir()
 	req := PolishRequest{
 		GeneratedConfigPath:  filepath.Join(dir, "audita.generated.yml"),
-		MergedTranscriptPath: filepath.Join(dir, "merged.json"),
+		MergedTranscriptPath: filepath.Join(dir, "base.json"),
 		GlossaryPath:         filepath.Join(dir, "glossary.yml"),
-		OutputProcessedPath:  filepath.Join(dir, "processed.json"),
+		OutputProcessedPath:  filepath.Join(dir, "polished.json"),
 		ReportPath:           filepath.Join(dir, "audita.report.json"),
 		WorkDir:              filepath.Join(dir, "artifacts", "audita-work"),
 		StdoutLogPath:        filepath.Join(dir, "audita.stdout.log"),
@@ -571,7 +571,7 @@ func mustAuditaRunner(t *testing.T, cfg SubprocessRunnerConfig) *SubprocessRunne
 func auditaReqForTest(t *testing.T, withReport bool) PolishRequest {
 	t.Helper()
 	dir := t.TempDir()
-	merged := filepath.Join(dir, "merged.json")
+	merged := filepath.Join(dir, "base.json")
 	glossary := filepath.Join(dir, "glossary.yml")
 	writeAuditaTestFile(t, merged, `{"segments":[]}`)
 	writeAuditaTestFile(t, glossary, "terms: []\n")
@@ -579,7 +579,7 @@ func auditaReqForTest(t *testing.T, withReport bool) PolishRequest {
 		GeneratedConfigPath:  filepath.Join(dir, "audita.generated.yml"),
 		MergedTranscriptPath: merged,
 		GlossaryPath:         glossary,
-		OutputProcessedPath:  filepath.Join(dir, "processed.json"),
+		OutputProcessedPath:  filepath.Join(dir, "polished.json"),
 		WorkDir:              filepath.Join(dir, "artifacts", "audita-work"),
 		StdoutLogPath:        filepath.Join(dir, "audita.stdout.log"),
 		StderrLogPath:        filepath.Join(dir, "audita.stderr.log"),

internal/adapters/scriptorium/subprocess_test.go

@@ -31,7 +31,7 @@ func TestSubprocessRunnerRunSuccessBuildsDeterministicArgsAndCapturesLogs(t *tes
 		ConfigPath:          "/etc/scriptorium/config.yml",
 		PromptID:            "dnd.session_recap",
 		ProfileID:           "local-quality",
-		InputPaths:          map[string]string{"transcript": filepath.Join(dir, "processed.json"), "other": filepath.Join(dir, "other.md")},
+		InputPaths:          map[string]string{"transcript": filepath.Join(dir, "polished.json"), "other": filepath.Join(dir, "other.md")},
 		Vars:                map[string]string{"session_id": "2026-05-03", "campaign_name": "Icewind Dale"},
 		OutputPath:          filepath.Join(dir, "artifacts", "session_recap.md"),
 		StdoutLogPath:       filepath.Join(dir, "logs", "scriptorium.run.stdout.log"),
@@ -180,7 +180,7 @@ func TestSubprocessRunnerRenderSuccess(t *testing.T) {
 	req := RenderArtifactRequest{
 		Binary:              wrapper,
 		PromptID:            "dnd.session_recap",
-		InputPaths:          map[string]string{"transcript": filepath.Join(dir, "processed.json")},
+		InputPaths:          map[string]string{"transcript": filepath.Join(dir, "polished.json")},
 		OutputPath:          filepath.Join(dir, "artifacts", "session_recap.render.json"),
 		StdoutLogPath:       filepath.Join(dir, "logs", "scriptorium.render.stdout.log"),
 		StderrLogPath:       filepath.Join(dir, "logs", "scriptorium.render.stderr.log"),
@@ -285,7 +285,7 @@ type scriptoriumHelperRecord struct {
 func runReqForTest(t *testing.T, binary string) RunArtifactRequest {
 	t.Helper()
 	dir := t.TempDir()
-	transcriptPath := filepath.Join(dir, "processed.json")
+	transcriptPath := filepath.Join(dir, "polished.json")
 	writeScriptoriumFile(t, transcriptPath, `{"segments":[]}`)
 	return RunArtifactRequest{
 		Binary:              binary,

internal/adapters/seriatim/fake_test.go

@@ -14,7 +14,7 @@ func TestFakeRunnerCapturesRequestAndReturnsPath(t *testing.T) {
 	dir := t.TempDir()
 	req := MergeRequest{
 		GeneratedConfigPath:        filepath.Join(dir, "config", "seriatim.yml"),
-		OutputMergedTranscriptPath: filepath.Join(dir, "transcripts", "merged.json"),
+		OutputMergedTranscriptPath: filepath.Join(dir, "transcripts", "base.json"),
 		StdoutLogPath:              filepath.Join(dir, "logs", "seriatim.stdout.log"),
 		StderrLogPath:              filepath.Join(dir, "logs", "seriatim.stderr.log"),
 	}
@@ -57,8 +57,8 @@ func TestFakeRunnerTrimCapturesRequestAndReturnsPath(t *testing.T) {
 	dir := t.TempDir()
 	req := TrimRequest{
 		GeneratedConfigPath: filepath.Join(dir, "config", "seriatim.trim.yml"),
-		InputTranscriptPath: filepath.Join(dir, "transcripts", "processed.json"),
-		OutputTrimmedPath:   filepath.Join(dir, "transcripts", "trimmed.json"),
+		InputTranscriptPath: filepath.Join(dir, "transcripts", "polished.json"),
+		OutputTrimmedPath:   filepath.Join(dir, "transcripts", "final.trimmed.json"),
 		KeepSelector:        "1-10",
 		StdoutLogPath:       filepath.Join(dir, "logs", "seriatim.trim.stdout.log"),
 		StderrLogPath:       filepath.Join(dir, "logs", "seriatim.trim.stderr.log"),
@@ -105,8 +105,8 @@ func TestFakeRunnerNormalizeCapturesRequestAndReturnsPath(t *testing.T) {
 	dir := t.TempDir()
 	req := NormalizeRequest{
 		GeneratedConfigPath:  filepath.Join(dir, "config", "seriatim.normalize.yml"),
-		InputTranscriptPath:  filepath.Join(dir, "transcripts", "processed.json"),
-		OutputNormalizedPath: filepath.Join(dir, "transcripts", "normalized.json"),
+		InputTranscriptPath:  filepath.Join(dir, "transcripts", "polished.json"),
+		OutputNormalizedPath: filepath.Join(dir, "transcripts", "final.json"),
 		OutputSchema:         "seriatim-intermediate",
 		ReportPath:           filepath.Join(dir, "artifacts", "seriatim.normalize.report.json"),
 		StdoutLogPath:        filepath.Join(dir, "logs", "seriatim.normalize.stdout.log"),

internal/adapters/seriatim/subprocess_test.go

@@ -50,7 +50,7 @@ func TestSubprocessRunnerSuccessWithReportArgsAndEnv(t *testing.T) {
 	req := MergeRequest{
 		GeneratedConfigPath:        filepath.Join(dir, "seriatim.generated.yml"),
 		InputTranscriptPaths:       []string{filepath.Join(dir, "a.json"), filepath.Join(dir, "b.json")},
-		OutputMergedTranscriptPath: filepath.Join(dir, "merged.json"),
+		OutputMergedTranscriptPath: filepath.Join(dir, "base.json"),
 		ReportPath:                 filepath.Join(dir, "seriatim.report.json"),
 		SpeakersPath:               filepath.Join(dir, "speakers.yml"),
 		AutocorrectPath:            filepath.Join(dir, "autocorrect.yml"),
@@ -732,7 +732,7 @@ func mergeReqForTest(t *testing.T, withReport bool) MergeRequest {
 	req := MergeRequest{
 		GeneratedConfigPath:        filepath.Join(dir, "seriatim.generated.yml"),
 		InputTranscriptPaths:       []string{in1, in2},
-		OutputMergedTranscriptPath: filepath.Join(dir, "merged.json"),
+		OutputMergedTranscriptPath: filepath.Join(dir, "base.json"),
 		StdoutLogPath:              filepath.Join(dir, "seriatim.stdout.log"),
 		StderrLogPath:              filepath.Join(dir, "seriatim.stderr.log"),
 	}
@@ -745,11 +745,11 @@ func mergeReqForTest(t *testing.T, withReport bool) MergeRequest {
 func trimReqForTest(t *testing.T) TrimRequest {
 	t.Helper()
 	dir := t.TempDir()
-	input := filepath.Join(dir, "processed.json")
+	input := filepath.Join(dir, "polished.json")
 	writeSeriatimFile(t, input, `{"schema":"seriatim.intermediate.v1","segments":[]}`)
 	return TrimRequest{
 		InputTranscriptPath: input,
-		OutputTrimmedPath:   filepath.Join(dir, "trimmed.json"),
+		OutputTrimmedPath:   filepath.Join(dir, "final.trimmed.json"),
 		KeepSelector:        "5-12",
 		GeneratedConfigPath: filepath.Join(dir, "seriatim.trim.generated.yml"),
 		StdoutLogPath:       filepath.Join(dir, "seriatim.trim.stdout.log"),
@@ -760,12 +760,12 @@ func trimReqForTest(t *testing.T) TrimRequest {
 func normalizeReqForTest(t *testing.T, withReport bool) NormalizeRequest {
 	t.Helper()
 	dir := t.TempDir()
-	input := filepath.Join(dir, "processed.json")
+	input := filepath.Join(dir, "polished.json")
 	writeSeriatimFile(t, input, `{"schema":"audita.processed.v1","segments":[]}`)
 
 	req := NormalizeRequest{
 		InputTranscriptPath:  input,
-		OutputNormalizedPath: filepath.Join(dir, "normalized.json"),
+		OutputNormalizedPath: filepath.Join(dir, "final.json"),
 		OutputSchema:         "seriatim-intermediate",
 		GeneratedConfigPath:  filepath.Join(dir, "seriatim.normalize.generated.yml"),
 		StdoutLogPath:        filepath.Join(dir, "seriatim.normalize.stdout.log"),

internal/adapters/storage/archive.go

@@ -1,31 +0,0 @@
-// Package storage declares archive/storage backend adapter boundaries.
-package storage
-
-import "context"
-
-// TODO: implement remote storage/archive backends (S3/SFTP/etc.).
-
-// Backend is the adapter boundary for archive/storage operations.
-type Backend interface {
-	Archive(ctx context.Context, req ArchiveRequest) (ArchiveResult, error)
-}
-
-// ArchiveItem describes one item to archive.
-type ArchiveItem struct {
-	Kind      string
-	LocalPath string
-	RemoteKey string
-}
-
-// ArchiveRequest describes one archive operation.
-type ArchiveRequest struct {
-	SessionID    string
-	ManifestPath string
-	Items        []ArchiveItem
-}
-
-// ArchiveResult describes archive operation output.
-type ArchiveResult struct {
-	Archived []ArchiveItem
-	Metadata map[string]any
-}

internal/adapters/storage/fake.go

@@ -10,23 +10,8 @@ import (
 	"time"
 )
 
-// NoopBackend is a deterministic no-op archive/storage adapter.
-type NoopBackend struct{}
-
-// Archive returns the requested items as archived with placeholder metadata.
-func (n *NoopBackend) Archive(ctx context.Context, req ArchiveRequest) (ArchiveResult, error) {
-	if err := ctx.Err(); err != nil {
-		return ArchiveResult{}, err
-	}
-	return ArchiveResult{Archived: append([]ArchiveItem(nil), req.Items...), Metadata: map[string]any{"placeholder": true}}, nil
-}
-
-// FakeBackend captures archive requests and returns deterministic responses.
+// FakeBackend provides a deterministic in-memory object store for tests.
 type FakeBackend struct {
-	Requests []ArchiveRequest
-	Err      error
-	Result   ArchiveResult
-
 	Objects   map[string]FakeObject
 	Uploads   []FakeUploadCall
 	Downloads []FakeDownloadCall
@@ -50,25 +35,6 @@ type FakeDownloadCall struct {
 	LocalPath string
 }
 
-// Archive records request and returns configured response.
-func (f *FakeBackend) Archive(ctx context.Context, req ArchiveRequest) (ArchiveResult, error) {
-	if err := ctx.Err(); err != nil {
-		return ArchiveResult{}, err
-	}
-	f.Requests = append(f.Requests, req)
-	if f.Err != nil {
-		return ArchiveResult{}, f.Err
-	}
-	res := f.Result
-	if res.Archived == nil {
-		res.Archived = append([]ArchiveItem(nil), req.Items...)
-	}
-	if res.Metadata == nil {
-		res.Metadata = map[string]any{"fake": true}
-	}
-	return res, nil
-}
-
 // FakeObject is a deterministic fake object-store record.
 type FakeObject struct {
 	Key          string

internal/adapters/storage/fake_test.go

@@ -9,30 +9,6 @@ import (
 	"testing"
 )
 
-func TestFakeBackendCapturesRequestAndReturnsItems(t *testing.T) {
-	fake := &FakeBackend{}
-	req := ArchiveRequest{SessionID: "s1", Items: []ArchiveItem{{Kind: "artifact", LocalPath: "artifacts/log.md"}}}
-
-	res, err := fake.Archive(context.Background(), req)
-	if err != nil {
-		t.Fatalf("Archive() error = %v", err)
-	}
-	if len(fake.Requests) != 1 || fake.Requests[0].SessionID != "s1" {
-		t.Fatalf("requests = %#v, want captured request", fake.Requests)
-	}
-	if len(res.Archived) != 1 {
-		t.Fatalf("archived len = %d, want 1", len(res.Archived))
-	}
-}
-
-func TestFakeBackendError(t *testing.T) {
-	fake := &FakeBackend{Err: errors.New("boom")}
-	_, err := fake.Archive(context.Background(), ArchiveRequest{})
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-}
-
 func TestFakeBackendListPrefixFiltering(t *testing.T) {
 	fake := &FakeBackend{}
 	fake.SeedObject(FakeObject{Key: "dnd/campaigns/forsaken/audio/a.flac", Data: []byte("a")})

internal/adapters/storage/object_store.go

@@ -5,7 +5,7 @@ import (
 	"time"
 )
 
-// ObjectStore is a remote object storage boundary used by future prepare/archive work.
+// ObjectStore is a remote object storage boundary used by prepare, restore, and publish work.
 //
 // Key invariant:
 // callers pass full bucket-relative object keys. Backend implementations do not

internal/adapters/storage/temp_download.go

@@ -0,0 +1,36 @@
+package storage
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// DownloadObjectToTemp downloads an object into a temporary file and returns
+// the cleaned local path.
+func DownloadObjectToTemp(ctx context.Context, store ObjectStore, key, pattern string) (string, error) {
+	if store == nil {
+		return "", fmt.Errorf("object store is required")
+	}
+	if strings.TrimSpace(pattern) == "" {
+		return "", fmt.Errorf("temp file pattern is required")
+	}
+
+	tmp, err := os.CreateTemp("", pattern)
+	if err != nil {
+		return "", fmt.Errorf("create temp file: %w", err)
+	}
+	path := tmp.Name()
+	if err := tmp.Close(); err != nil {
+		_ = os.Remove(path)
+		return "", fmt.Errorf("close temp file: %w", err)
+	}
+
+	if err := store.Download(ctx, key, path); err != nil {
+		_ = os.Remove(path)
+		return "", err
+	}
+	return filepath.Clean(path), nil
+}

internal/adapters/storage/temp_download_test.go

@@ -0,0 +1,69 @@
+package storage
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestDownloadObjectToTempSuccess(t *testing.T) {
+	store := &FakeBackend{}
+	store.SeedObject(FakeObject{Key: "sessions/a/current/run_id.txt", Data: []byte("run-123\n")})
+
+	path, err := DownloadObjectToTemp(context.Background(), store, "sessions/a/current/run_id.txt", "narratio-test-*.txt")
+	if err != nil {
+		t.Fatalf("DownloadObjectToTemp() error = %v", err)
+	}
+	t.Cleanup(func() { _ = os.Remove(path) })
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("ReadFile() error = %v", err)
+	}
+	if string(data) != "run-123\n" {
+		t.Fatalf("downloaded data = %q, want %q", string(data), "run-123\n")
+	}
+}
+
+func TestDownloadObjectToTempFailedDownloadRemovesTempFile(t *testing.T) {
+	sentinel := errors.New("download failed")
+	store := &FakeBackend{DownloadErr: sentinel}
+	pattern := "narratio-test-fail-*.txt"
+	before, err := filepath.Glob(filepath.Join(os.TempDir(), "narratio-test-fail-*.txt"))
+	if err != nil {
+		t.Fatalf("Glob(before) error = %v", err)
+	}
+
+	path, err := DownloadObjectToTemp(context.Background(), store, "sessions/a/current/run_id.txt", pattern)
+	if !errors.Is(err, sentinel) {
+		t.Fatalf("DownloadObjectToTemp() error = %v, want %v", err, sentinel)
+	}
+	if strings.TrimSpace(path) != "" {
+		t.Fatalf("DownloadObjectToTemp() path = %q, want empty on failure", path)
+	}
+	after, err := filepath.Glob(filepath.Join(os.TempDir(), "narratio-test-fail-*.txt"))
+	if err != nil {
+		t.Fatalf("Glob(after) error = %v", err)
+	}
+	if len(after) != len(before) {
+		t.Fatalf("temp file count changed after failed download: before=%d after=%d", len(before), len(after))
+	}
+}
+
+func TestDownloadObjectToTempCallerContextWrappingPreservesCause(t *testing.T) {
+	sentinel := errors.New("object missing")
+	store := &FakeBackend{DownloadErr: sentinel}
+
+	_, err := DownloadObjectToTemp(context.Background(), store, "sessions/a/current/run_id.txt", "narratio-test-*.txt")
+	if err == nil {
+		t.Fatal("DownloadObjectToTemp() error = nil, want error")
+	}
+	err = fmt.Errorf("download run pointer failed: %w", err)
+	if !errors.Is(err, sentinel) {
+		t.Fatalf("wrapped error does not preserve sentinel cause: %v", err)
+	}
+}

internal/adapters/whisperx/http_test.go

@@ -145,7 +145,7 @@ func TestHTTPClientDoesNotRetryOnNonRetryableStatus(t *testing.T) {
 	}
 }
 
-func TestHTTPClientInvalidJSONFailsAndDoesNotPromote(t *testing.T) {
+func TestHTTPClientInvalidJSONFailsAndDoesNotInstallOutput(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		_, _ = w.Write([]byte(`not-json`))
 	}))

internal/app/analyze_artifacts.go

@@ -46,7 +46,7 @@ func (f *artifactSelectionFlag) Normalize() ([]string, error) {
 	return out, nil
 }
 
-func validateSelectedAnalyzeArtifacts(cfg *config.Config, selected []string) error {
+func validateSelectedArtifacts(cfg *config.Config, selected []string) error {
 	if len(selected) == 0 {
 		return nil
 	}

internal/app/analyze_artifacts_commands_test.go

@@ -14,25 +14,67 @@ import (
 	"gitea.maximumdirect.net/eric/narratio/internal/stage"
 )
 
-func TestExecuteRunStageArtifactsNonAnalyzeFails(t *testing.T) {
+func TestExecuteRunStageArtifactsUnsupportedStageFails(t *testing.T) {
 	workspaceRoot := t.TempDir()
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFilesWithScriptoriumArtifacts(t, workspaceRoot)
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
 	code := Execute(
-		[]string{"run-stage", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "--artifacts", "session_recap", "polish"},
+		[]string{"run-stage", "polish", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--artifacts", "session_recap"},
 		&stdout,
 		&stderr,
 	)
 	if code == 0 {
 		t.Fatal("exit code = 0, want non-zero")
 	}
-	if !strings.Contains(stderr.String(), `run-stage: --artifacts is only supported for stage "analyze"`) {
+	if !strings.Contains(stderr.String(), `run-stage: --artifacts is only supported for stages "analyze" and "publish"`) {
 		t.Fatalf("stderr = %q, want stage-gating error", stderr.String())
 	}
 }
 
+func TestExecuteRunStagePublishPropagatesSelectedArtifacts(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, campaignPath, sessionPath := writeValidConfigFilesWithScriptoriumArtifacts(t, workspaceRoot)
+
+	var capturedStages []string
+	var capturedArtifacts []string
+	origExecuteStagesFn := executeStagesFn
+	t.Cleanup(func() {
+		executeStagesFn = origExecuteStagesFn
+	})
+	executeStagesFn = func(_ context.Context, _ *config.Config, stages []stage.Stage, opts RunOptions) (*RunSummary, error) {
+		for _, s := range stages {
+			capturedStages = append(capturedStages, s.Name())
+		}
+		capturedArtifacts = append([]string(nil), opts.SelectedArtifacts...)
+		return &RunSummary{ManifestPath: filepath.Join(workspaceRoot, "manifest.json"), Executed: []string{"publish"}}, nil
+	}
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	code := Execute(
+		[]string{
+			"run-stage", "publish", "2026-05-03",
+			"--config", pipelinePath,
+			"--campaign-file", campaignPath,
+			"--session", sessionPath,
+			"--artifacts", "session_recap",
+		},
+		&stdout,
+		&stderr,
+	)
+	if code != 0 {
+		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
+	}
+	if len(capturedStages) != 1 || capturedStages[0] != "publish" {
+		t.Fatalf("captured stages = %#v, want [publish]", capturedStages)
+	}
+	if strings.Join(capturedArtifacts, ",") != "session_recap" {
+		t.Fatalf("captured artifacts = %#v, want [session_recap]", capturedArtifacts)
+	}
+}
+
 func TestExecuteUnknownArtifactsFailValidation(t *testing.T) {
 	workspaceRoot := t.TempDir()
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFilesWithScriptoriumArtifacts(t, workspaceRoot)
@@ -40,7 +82,7 @@ func TestExecuteUnknownArtifactsFailValidation(t *testing.T) {
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
 	code := Execute(
-		[]string{"run", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "--artifacts", "unknown_artifact"},
+		[]string{"run", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--artifacts", "unknown_artifact"},
 		&stdout,
 		&stderr,
 	)
@@ -67,7 +109,7 @@ func TestRunStageArtifactsDoesNotImplyForce(t *testing.T) {
 	var out bytes.Buffer
 	err := RunStage(
 		context.Background(),
-		[]string{"--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "--artifacts", "session_recap,session_recap", "analyze"},
+		[]string{"analyze", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--artifacts", "session_recap,session_recap"},
 		&out,
 	)
 	if err != nil {
@@ -78,14 +120,14 @@ func TestRunStageArtifactsDoesNotImplyForce(t *testing.T) {
 	}
 }
 
-func TestResumeArtifactsWithSucceededAnalyzeSkipsUnlessForced(t *testing.T) {
+func TestRunArtifactsWithSucceededAnalyzeSkipsUnlessForced(t *testing.T) {
 	workspaceRoot := t.TempDir()
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFilesWithScriptoriumArtifacts(t, workspaceRoot)
 	manifestPath := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03", "manifest.json")
 
 	store := &manifest.LocalStore{}
 	seed := manifest.New("2026-05-03", time.Date(2026, 5, 3, 10, 0, 0, 0, time.UTC))
-	for _, stageName := range []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim", "analyze", "archive", "notify"} {
+	for _, stageName := range []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim", "analyze", "publish", "notify"} {
 		seed.MarkStageSucceeded(stageName, time.Date(2026, 5, 3, 10, 1, 0, 0, time.UTC), nil)
 	}
 	if err := store.Save(context.Background(), manifestPath, seed); err != nil {
@@ -93,16 +135,16 @@ func TestResumeArtifactsWithSucceededAnalyzeSkipsUnlessForced(t *testing.T) {
 	}
 
 	var out bytes.Buffer
-	err := Resume(
+	err := Run(
 		context.Background(),
-		[]string{"--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "--artifacts", "session_recap"},
+		[]string{"2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--artifacts", "session_recap"},
 		&out,
 	)
 	if err != nil {
-		t.Fatalf("Resume() error = %v", err)
+		t.Fatalf("Run() error = %v", err)
 	}
-	if !strings.Contains(out.String(), "has no remaining stages") {
-		t.Fatalf("output = %q, want no remaining stages", out.String())
+	if !strings.Contains(out.String(), "executed=0 skipped=9") {
+		t.Fatalf("output = %q, want all stages skipped", out.String())
 	}
 }
 
@@ -130,7 +172,7 @@ func TestExecuteAnalyzeForceRunsAnalyze(t *testing.T) {
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
 	code := Execute(
-		[]string{"analyze", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath},
+		[]string{"analyze", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath},
 		&stdout,
 		&stderr,
 	)
@@ -167,8 +209,9 @@ func TestExecuteAnalyzePropagatesSelectedArtifacts(t *testing.T) {
 	code := Execute(
 		[]string{
 			"analyze",
+			"2026-05-03",
 			"--config", pipelinePath,
-			"--campaign", campaignPath,
+			"--campaign-file", campaignPath,
 			"--session", sessionPath,
 			"--artifacts", "player_handout,session_recap",
 		},
@@ -190,7 +233,7 @@ func TestExecuteAnalyzeUnknownArtifactFailsValidation(t *testing.T) {
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
 	code := Execute(
-		[]string{"analyze", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "--artifacts", "unknown_artifact"},
+		[]string{"analyze", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--artifacts", "unknown_artifact"},
 		&stdout,
 		&stderr,
 	)
@@ -208,7 +251,7 @@ func TestExecuteAnalyzeRejectsPositionalArgsAndForceFlag(t *testing.T) {
 		args []string
 		want string
 	}{
-		{name: "positional", args: []string{"analyze", "extra"}, want: "analyze: unexpected positional arguments"},
+		{name: "extra positional", args: []string{"analyze", "2026-05-03", "extra"}, want: "analyze: unexpected positional arguments"},
 		{name: "force flag", args: []string{"analyze", "--force"}, want: "analyze: invalid flags: flag provided but not defined: -force"},
 	}
 	for _, tc := range cases {
@@ -229,7 +272,7 @@ func TestExecuteAnalyzeRejectsPositionalArgsAndForceFlag(t *testing.T) {
 func TestExecuteAnalyzeMissingConfigUsesRunStageLoadingPath(t *testing.T) {
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"analyze"}, &stdout, &stderr)
+	code := Execute([]string{"analyze", "2026-05-03"}, &stdout, &stderr)
 	if code == 0 {
 		t.Fatal("exit code = 0, want non-zero")
 	}
@@ -238,7 +281,109 @@ func TestExecuteAnalyzeMissingConfigUsesRunStageLoadingPath(t *testing.T) {
 	}
 }
 
-func TestExecuteUsageIncludesAnalyze(t *testing.T) {
+func TestExecutePublishForceRunsPublish(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, campaignPath, sessionPath := writeValidConfigFilesWithScriptoriumArtifacts(t, workspaceRoot)
+
+	var capturedStages []string
+	var capturedForce bool
+	var capturedArtifacts []string
+	origExecuteStagesFn := executeStagesFn
+	t.Cleanup(func() {
+		executeStagesFn = origExecuteStagesFn
+	})
+	executeStagesFn = func(_ context.Context, _ *config.Config, stages []stage.Stage, opts RunOptions) (*RunSummary, error) {
+		for _, s := range stages {
+			capturedStages = append(capturedStages, s.Name())
+		}
+		capturedForce = opts.Force
+		capturedArtifacts = append([]string(nil), opts.SelectedArtifacts...)
+		return &RunSummary{
+			ManifestPath: filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03", "manifest.json"),
+			Executed:     []string{"publish"},
+		}, nil
+	}
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	code := Execute(
+		[]string{"publish", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--artifacts", "session_recap"},
+		&stdout,
+		&stderr,
+	)
+	if code != 0 {
+		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
+	}
+	if len(capturedStages) != 1 || capturedStages[0] != "publish" {
+		t.Fatalf("captured stages = %#v, want [publish]", capturedStages)
+	}
+	if !capturedForce {
+		t.Fatal("captured force = false, want true")
+	}
+	if strings.Join(capturedArtifacts, ",") != "session_recap" {
+		t.Fatalf("captured artifacts = %#v, want [session_recap]", capturedArtifacts)
+	}
+	if !strings.Contains(stdout.String(), "narratio publish: executed=1 skipped=0 force=true; manifest=") {
+		t.Fatalf("stdout = %q, want publish summary", stdout.String())
+	}
+}
+
+func TestExecutePublishRejectsUnsupportedArgsAndFlags(t *testing.T) {
+	cases := []struct {
+		name string
+		args []string
+		want string
+	}{
+		{name: "extra positional", args: []string{"publish", "2026-05-03", "extra"}, want: "publish: unexpected positional arguments"},
+		{name: "force flag", args: []string{"publish", "--force"}, want: "publish: invalid flags: flag provided but not defined: -force"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			var stdout bytes.Buffer
+			var stderr bytes.Buffer
+			code := Execute(tc.args, &stdout, &stderr)
+			if code == 0 {
+				t.Fatal("exit code = 0, want non-zero")
+			}
+			if !strings.Contains(stderr.String(), tc.want) {
+				t.Fatalf("stderr = %q, want %q", stderr.String(), tc.want)
+			}
+		})
+	}
+}
+
+func TestExecutePublishUnknownArtifactFailsValidation(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, campaignPath, sessionPath := writeValidConfigFilesWithScriptoriumArtifacts(t, workspaceRoot)
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	code := Execute(
+		[]string{"publish", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--artifacts", "unknown_artifact"},
+		&stdout,
+		&stderr,
+	)
+	if code == 0 {
+		t.Fatal("exit code = 0, want non-zero")
+	}
+	if !strings.Contains(stderr.String(), `publish: --artifacts includes unknown artifact "unknown_artifact"`) {
+		t.Fatalf("stderr = %q, want unknown-artifact validation error", stderr.String())
+	}
+}
+
+func TestExecutePublishMissingConfigUsesRunStageLoadingPath(t *testing.T) {
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	code := Execute([]string{"publish", "2026-05-03"}, &stdout, &stderr)
+	if code == 0 {
+		t.Fatal("exit code = 0, want non-zero")
+	}
+	if !strings.Contains(stderr.String(), "publish: no pipeline config path provided and no default pipeline config found; searched:") {
+		t.Fatalf("stderr = %q, want pipeline discovery error", stderr.String())
+	}
+}
+
+func TestExecuteUsageIncludesAnalyzeAndPublish(t *testing.T) {
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
 	code := Execute(nil, &stdout, &stderr)
@@ -248,6 +393,9 @@ func TestExecuteUsageIncludesAnalyze(t *testing.T) {
 	if !strings.Contains(stderr.String(), "analyze") {
 		t.Fatalf("stderr = %q, want usage to include analyze", stderr.String())
 	}
+	if !strings.Contains(stderr.String(), "publish") {
+		t.Fatalf("stderr = %q, want usage to include publish", stderr.String())
+	}
 }
 
 func writeValidConfigFilesWithScriptoriumArtifacts(t *testing.T, workspaceRoot string) (string, string, string) {

internal/app/analyze_artifacts_test.go

@@ -64,7 +64,7 @@ func TestArtifactSelectionFlagNormalize(t *testing.T) {
 	}
 }
 
-func TestValidateSelectedAnalyzeArtifacts(t *testing.T) {
+func TestValidateSelectedArtifacts(t *testing.T) {
 	tests := []struct {
 		name     string
 		cfg      *config.Config
@@ -114,7 +114,7 @@ func TestValidateSelectedAnalyzeArtifacts(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			err := validateSelectedAnalyzeArtifacts(tt.cfg, tt.selected)
+			err := validateSelectedArtifacts(tt.cfg, tt.selected)
 			if tt.wantErr != "" {
 				if err == nil {
 					t.Fatalf("error = nil, want %q", tt.wantErr)

internal/app/campaign_config_path.go

@@ -1,49 +1,44 @@
 package app
 
 import (
-	"errors"
 	"fmt"
-	"os"
 	"path/filepath"
 	"strings"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
 )
 
-func resolveCampaignConfigPath(flagValue string) (string, error) {
-	return resolveCampaignConfigPathWithCandidates(flagValue, config.DefaultCampaignConfigSearchPaths)
+func resolveCampaignConfigPath(pipelineCfg *config.PipelineConfig, campaignIDFlag, campaignFileFlag string) (string, error) {
+	campaignID := strings.TrimSpace(campaignIDFlag)
+	campaignFile := strings.TrimSpace(campaignFileFlag)
+	if campaignID != "" && campaignFile != "" {
+		return "", fmt.Errorf("--campaign and --campaign-file are mutually exclusive")
+	}
+	if campaignFile != "" {
+		return filepath.Clean(campaignFile), nil
+	}
+	if campaignID == "" && pipelineCfg != nil {
+		campaignID = strings.TrimSpace(pipelineCfg.Campaigns.DefaultCampaignID)
+	}
+	if campaignID == "" {
+		return "", fmt.Errorf("no campaign selected; pass --campaign <id> or set pipeline.campaigns.default_campaign_id")
+	}
+	if err := validateCampaignIDToken(campaignID); err != nil {
+		return "", err
+	}
+	if pipelineCfg == nil || strings.TrimSpace(pipelineCfg.Campaigns.Root) == "" {
+		return "", fmt.Errorf("pipeline.campaigns.root is required to select campaign %q", campaignID)
+	}
+	return filepath.Clean(filepath.Join(pipelineCfg.Campaigns.Root, campaignID, "campaign.yml")), nil
 }
 
-func resolveCampaignConfigPathWithCandidates(flagValue string, candidates []string) (string, error) {
-	if explicit := strings.TrimSpace(flagValue); explicit != "" {
-		return explicit, nil
+func validateCampaignIDToken(campaignID string) error {
+	if filepath.IsAbs(campaignID) ||
+		strings.Contains(campaignID, "/") ||
+		strings.Contains(campaignID, `\`) ||
+		campaignID == "." ||
+		campaignID == ".." {
+		return fmt.Errorf("campaign id %q must be a single path segment", campaignID)
 	}
-
-	ordered := make([]string, 0, len(candidates))
-	for _, raw := range candidates {
-		path := strings.TrimSpace(raw)
-		if path == "" {
-			continue
-		}
-		ordered = append(ordered, path)
-		info, err := os.Stat(path)
-		if err == nil {
-			if info.IsDir() {
-				continue
-			}
-			return filepath.Clean(path), nil
-		}
-		if errors.Is(err, os.ErrNotExist) {
-			continue
-		}
-		return "", fmt.Errorf("check default campaign config %q: %w", path, err)
-	}
-
-	if len(ordered) == 0 {
-		return "", fmt.Errorf("no campaign config path provided and no default locations configured")
-	}
-	return "", fmt.Errorf(
-		"no campaign config path provided and no default campaign config found; searched: %s; pass --campaign to use an explicit path",
-		strings.Join(ordered, ", "),
-	)
+	return nil
 }

internal/app/campaign_config_path_test.go

@@ -1,49 +1,84 @@
 package app
 
 import (
-	"os"
 	"path/filepath"
 	"strings"
 	"testing"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
 )
 
-func TestResolveCampaignConfigPathExplicitWins(t *testing.T) {
+func TestResolveCampaignConfigPathCampaignFileWins(t *testing.T) {
 	explicit := filepath.Join(t.TempDir(), "custom-campaign.yml")
-	got, err := resolveCampaignConfigPathWithCandidates(explicit, []string{filepath.Join(t.TempDir(), "campaign.yml")})
+	got, err := resolveCampaignConfigPath(&config.PipelineConfig{}, "", explicit)
 	if err != nil {
-		t.Fatalf("resolveCampaignConfigPathWithCandidates() error = %v", err)
+		t.Fatalf("resolveCampaignConfigPath() error = %v", err)
 	}
 	if got != explicit {
 		t.Fatalf("path = %q, want explicit path %q", got, explicit)
 	}
 }
 
-func TestResolveCampaignConfigPathUsesFirstExistingDefault(t *testing.T) {
+func TestResolveCampaignConfigPathUsesSelectedCampaignID(t *testing.T) {
 	dir := t.TempDir()
-	missing := filepath.Join(dir, "missing.yml")
-	found := filepath.Join(dir, "campaign.yml")
-	if err := os.WriteFile(found, []byte("campaign: sample-campaign\n"), 0o644); err != nil {
-		t.Fatalf("write campaign.yml: %v", err)
-	}
+	pipelineCfg := &config.PipelineConfig{}
+	pipelineCfg.Campaigns.Root = dir
 
-	got, err := resolveCampaignConfigPathWithCandidates("", []string{missing, found})
+	got, err := resolveCampaignConfigPath(pipelineCfg, "icewind", "")
 	if err != nil {
-		t.Fatalf("resolveCampaignConfigPathWithCandidates() error = %v", err)
+		t.Fatalf("resolveCampaignConfigPath() error = %v", err)
 	}
-	if got != filepath.Clean(found) {
-		t.Fatalf("path = %q, want %q", got, filepath.Clean(found))
+	want := filepath.Join(dir, "icewind", "campaign.yml")
+	if got != filepath.Clean(want) {
+		t.Fatalf("path = %q, want %q", got, filepath.Clean(want))
 	}
 }
 
-func TestResolveCampaignConfigPathErrorIncludesSearchedPaths(t *testing.T) {
-	_, err := resolveCampaignConfigPathWithCandidates("", []string{"/usr/local/etc/narratio/campaign.yml", "/etc/narratio/campaign.yml"})
+func TestResolveCampaignConfigPathUsesDefaultCampaignID(t *testing.T) {
+	dir := t.TempDir()
+	pipelineCfg := &config.PipelineConfig{}
+	pipelineCfg.Campaigns.Root = dir
+	pipelineCfg.Campaigns.DefaultCampaignID = "dilfs"
+
+	got, err := resolveCampaignConfigPath(pipelineCfg, "", "")
+	if err != nil {
+		t.Fatalf("resolveCampaignConfigPath() error = %v", err)
+	}
+	want := filepath.Join(dir, "dilfs", "campaign.yml")
+	if got != filepath.Clean(want) {
+		t.Fatalf("path = %q, want %q", got, filepath.Clean(want))
+	}
+}
+
+func TestResolveCampaignConfigPathRejectsCampaignIDAndFile(t *testing.T) {
+	_, err := resolveCampaignConfigPath(&config.PipelineConfig{}, "dilfs", filepath.Join(t.TempDir(), "campaign.yml"))
 	if err == nil {
 		t.Fatal("expected error, got nil")
 	}
-	if !strings.Contains(err.Error(), "searched") {
-		t.Fatalf("error = %q, want searched paths", err.Error())
-	}
-	if !strings.Contains(err.Error(), "pass --campaign") {
-		t.Fatalf("error = %q, want explicit-campaign guidance", err.Error())
+	if !strings.Contains(err.Error(), "mutually exclusive") {
+		t.Fatalf("error = %q, want mutual exclusion", err.Error())
+	}
+}
+
+func TestResolveCampaignConfigPathRequiresCampaignSelection(t *testing.T) {
+	_, err := resolveCampaignConfigPath(&config.PipelineConfig{}, "", "")
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	if !strings.Contains(err.Error(), "no campaign selected") {
+		t.Fatalf("error = %q, want missing selection guidance", err.Error())
+	}
+}
+
+func TestResolveCampaignConfigPathRejectsPathLikeCampaignID(t *testing.T) {
+	pipelineCfg := &config.PipelineConfig{}
+	pipelineCfg.Campaigns.Root = t.TempDir()
+
+	_, err := resolveCampaignConfigPath(pipelineCfg, "../icewind", "")
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	if !strings.Contains(err.Error(), "single path segment") {
+		t.Fatalf("error = %q, want path segment guidance", err.Error())
 	}
 }

internal/app/clean.go

@@ -26,11 +26,8 @@ func Clean(ctx context.Context, args []string, out io.Writer) error {
 	fs.BoolVar(&all, "all", false, "clean all local session work/spool state")
 	fs.BoolVar(&dryRun, "dry-run", false, "print cleanup targets without deleting")
 	fs.BoolVar(&clearCache, "clear-cache", false, "also clear durable S3 audio cache entries")
-	if err := fs.Parse(args); err != nil {
-		return fmt.Errorf("clean: invalid flags: %w", err)
-	}
-	if fs.NArg() != 0 {
-		return fmt.Errorf("clean: unexpected positional arguments")
+	if err := parseSessionAwareFlags("clean", fs, args, &flags.sessionID); err != nil {
+		return err
 	}
 	if all {
 		return cleanAllLocal(flags, dryRun, clearCache, out)
@@ -40,9 +37,9 @@ func Clean(ctx context.Context, args []string, out io.Writer) error {
 
 func cleanSession(ctx context.Context, flags commonConfigFlags, dryRun, clearCache bool, out io.Writer) error {
 	if strings.TrimSpace(flags.sessionID) == "" {
-		return fmt.Errorf("clean: --session-id is required unless --all is set")
+		return fmt.Errorf("clean: session_id is required unless --all is set")
 	}
-	cfg, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.sessionPath, flags.sessionOptions())
+	cfg, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.campaignFilePath, flags.sessionPath, flags.sessionOptions())
 	if err != nil {
 		return fmt.Errorf("clean: %w", err)
 	}
@@ -82,10 +79,11 @@ func cleanSession(ctx context.Context, flags commonConfigFlags, dryRun, clearCac
 
 func cleanAllLocal(flags commonConfigFlags, dryRun, clearCache bool, out io.Writer) error {
 	if strings.TrimSpace(flags.campaignPath) != "" ||
+		strings.TrimSpace(flags.campaignFilePath) != "" ||
 		strings.TrimSpace(flags.sessionPath) != "" ||
 		strings.TrimSpace(flags.sessionID) != "" ||
 		strings.TrimSpace(flags.previousSessionID) != "" {
-		return fmt.Errorf("clean: --all cannot be combined with --campaign, --session, --session-id, or --previous-session-id")
+		return fmt.Errorf("clean: --all cannot be combined with --campaign, --campaign-file, --session, a session_id, or --previous-session-id")
 	}
 	resolvedPipelinePath, err := resolvePipelineConfigPath(flags.pipelinePath)
 	if err != nil {
@@ -171,26 +169,12 @@ func reportCleanRootChildren(out io.Writer, root, policy string, dryRun bool) er
 }
 
 func cleanableRootChildren(root, policy string) (string, []string, error) {
-	cleanRoot := strings.TrimSpace(root)
-	if cleanRoot == "" {
-		return "", nil, fmt.Errorf("cleanup policy %s: root path is required", policy)
-	}
-	rootAbs, err := filepath.Abs(cleanRoot)
+	rootAbs, exists, err := validateCleanRoot(root, policy)
 	if err != nil {
-		return "", nil, fmt.Errorf("cleanup policy %s: resolve root %q: %w", policy, cleanRoot, err)
+		return "", nil, err
 	}
-	info, err := os.Lstat(rootAbs)
-	if err != nil {
-		if os.IsNotExist(err) {
-			return rootAbs, nil, nil
-		}
-		return "", nil, fmt.Errorf("cleanup policy %s: stat root %q: %w", policy, rootAbs, err)
-	}
-	if info.Mode()&os.ModeSymlink != 0 {
-		return "", nil, fmt.Errorf("cleanup policy %s: refusing to clean symlink root %q", policy, rootAbs)
-	}
-	if !info.IsDir() {
-		return "", nil, fmt.Errorf("cleanup policy %s: root %q is not a directory", policy, rootAbs)
+	if !exists {
+		return rootAbs, nil, nil
 	}
 	entries, err := os.ReadDir(rootAbs)
 	if err != nil {
@@ -289,46 +273,7 @@ func reportCleanScopedFile(out io.Writer, root, target, policy string, dryRun bo
 }
 
 func validateScopedFile(root, target, policy string) (scopedDir, error) {
-	cleanRoot := strings.TrimSpace(root)
-	cleanTarget := strings.TrimSpace(target)
-	if cleanRoot == "" {
-		return scopedDir{}, fmt.Errorf("cleanup policy %s: root path is required", policy)
-	}
-	if cleanTarget == "" {
-		return scopedDir{}, fmt.Errorf("cleanup policy %s: target path is required", policy)
-	}
-	rootAbs, err := filepath.Abs(cleanRoot)
-	if err != nil {
-		return scopedDir{}, fmt.Errorf("cleanup policy %s: resolve root %q: %w", policy, cleanRoot, err)
-	}
-	targetAbs, err := filepath.Abs(cleanTarget)
-	if err != nil {
-		return scopedDir{}, fmt.Errorf("cleanup policy %s: resolve target %q: %w", policy, cleanTarget, err)
-	}
-	rel, err := filepath.Rel(rootAbs, targetAbs)
-	if err != nil {
-		return scopedDir{}, fmt.Errorf("cleanup policy %s: relative path from %q to %q: %w", policy, rootAbs, targetAbs, err)
-	}
-	if rel == "." {
-		return scopedDir{}, fmt.Errorf("cleanup policy %s: refusing to delete root directory %q", policy, rootAbs)
-	}
-	if rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
-		return scopedDir{}, fmt.Errorf("cleanup policy %s: refusing to delete path outside root: root=%q target=%q", policy, rootAbs, targetAbs)
-	}
-	info, err := os.Lstat(targetAbs)
-	if err != nil {
-		if os.IsNotExist(err) {
-			return scopedDir{RootAbs: rootAbs, TargetAbs: targetAbs, Exists: false}, nil
-		}
-		return scopedDir{}, fmt.Errorf("cleanup policy %s: stat target %q: %w", policy, targetAbs, err)
-	}
-	if info.Mode()&os.ModeSymlink != 0 {
-		return scopedDir{}, fmt.Errorf("cleanup policy %s: refusing to delete symlink path %q", policy, targetAbs)
-	}
-	if info.IsDir() {
-		return scopedDir{}, fmt.Errorf("cleanup policy %s: target %q is a directory", policy, targetAbs)
-	}
-	return scopedDir{RootAbs: rootAbs, TargetAbs: targetAbs, Exists: true}, nil
+	return validateScopedTarget(root, target, policy, false)
 }
 
 func cleanIsFlac(path string) bool {

internal/app/clean_test.go

@@ -26,7 +26,7 @@ func TestExecuteCleanSessionDeletesWorkAndSpoolButPreservesCache(t *testing.T) {
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"clean", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "--session-id", "2026-05-03"}, &stdout, &stderr)
+	code := Execute([]string{"clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
 	}
@@ -48,7 +48,7 @@ func TestExecuteCleanSessionDryRunDeletesNothing(t *testing.T) {
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"clean", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "--session-id", "2026-05-03", "--dry-run"}, &stdout, &stderr)
+	code := Execute([]string{"clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--dry-run"}, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
 	}
@@ -65,7 +65,7 @@ func TestExecuteCleanMissingSessionPathsSucceeds(t *testing.T) {
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"clean", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "--session-id", "2026-05-03"}, &stdout, &stderr)
+	code := Execute([]string{"clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
 	}
@@ -105,7 +105,7 @@ inputs:
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"clean", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "--session-id", "2026-05-03", "--clear-cache"}, &stdout, &stderr)
+	code := Execute([]string{"clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--clear-cache"}, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
 	}
@@ -122,7 +122,7 @@ func TestExecuteCleanLocalAudioClearCacheIsNoop(t *testing.T) {
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"clean", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "--session-id", "2026-05-03", "--clear-cache"}, &stdout, &stderr)
+	code := Execute([]string{"clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--clear-cache"}, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
 	}
@@ -184,7 +184,7 @@ func TestExecuteCleanAllRejectsSessionScopedFlags(t *testing.T) {
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"clean", "--config", pipelinePath, "--campaign", campaignPath, "--all"}, &stdout, &stderr)
+	code := Execute([]string{"clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--all"}, &stdout, &stderr)
 	if code == 0 {
 		t.Fatal("exit code = 0, want non-zero")
 	}
@@ -200,7 +200,7 @@ func TestCleanRequiresSessionID(t *testing.T) {
 	if code == 0 {
 		t.Fatal("exit code = 0, want non-zero")
 	}
-	if !strings.Contains(stderr.String(), "--session-id is required unless --all is set") {
+	if !strings.Contains(stderr.String(), "session_id is required unless --all is set") {
 		t.Fatalf("stderr = %q, want missing session-id", stderr.String())
 	}
 }

internal/app/cleanup_targets.go

@@ -0,0 +1,82 @@
+package app
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+func validateScopedTarget(root, target, policy string, requireDir bool) (scopedDir, error) {
+	cleanRoot := strings.TrimSpace(root)
+	cleanTarget := strings.TrimSpace(target)
+	if cleanRoot == "" {
+		return scopedDir{}, fmt.Errorf("cleanup policy %s: root path is required", policy)
+	}
+	if cleanTarget == "" {
+		return scopedDir{}, fmt.Errorf("cleanup policy %s: target path is required", policy)
+	}
+
+	rootAbs, err := filepath.Abs(cleanRoot)
+	if err != nil {
+		return scopedDir{}, fmt.Errorf("cleanup policy %s: resolve root %q: %w", policy, cleanRoot, err)
+	}
+	targetAbs, err := filepath.Abs(cleanTarget)
+	if err != nil {
+		return scopedDir{}, fmt.Errorf("cleanup policy %s: resolve target %q: %w", policy, cleanTarget, err)
+	}
+
+	rel, err := filepath.Rel(rootAbs, targetAbs)
+	if err != nil {
+		return scopedDir{}, fmt.Errorf("cleanup policy %s: relative path from %q to %q: %w", policy, rootAbs, targetAbs, err)
+	}
+	if rel == "." {
+		return scopedDir{}, fmt.Errorf("cleanup policy %s: refusing to delete root directory %q", policy, rootAbs)
+	}
+	if rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
+		return scopedDir{}, fmt.Errorf("cleanup policy %s: refusing to delete path outside root: root=%q target=%q", policy, rootAbs, targetAbs)
+	}
+
+	info, err := os.Lstat(targetAbs)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return scopedDir{RootAbs: rootAbs, TargetAbs: targetAbs, Exists: false}, nil
+		}
+		return scopedDir{}, fmt.Errorf("cleanup policy %s: stat target %q: %w", policy, targetAbs, err)
+	}
+	if info.Mode()&os.ModeSymlink != 0 {
+		return scopedDir{}, fmt.Errorf("cleanup policy %s: refusing to delete symlink path %q", policy, targetAbs)
+	}
+	if requireDir && !info.IsDir() {
+		return scopedDir{}, fmt.Errorf("cleanup policy %s: target %q is not a directory", policy, targetAbs)
+	}
+	if !requireDir && info.IsDir() {
+		return scopedDir{}, fmt.Errorf("cleanup policy %s: target %q is a directory", policy, targetAbs)
+	}
+	return scopedDir{RootAbs: rootAbs, TargetAbs: targetAbs, Exists: true}, nil
+}
+
+func validateCleanRoot(root, policy string) (string, bool, error) {
+	cleanRoot := strings.TrimSpace(root)
+	if cleanRoot == "" {
+		return "", false, fmt.Errorf("cleanup policy %s: root path is required", policy)
+	}
+	rootAbs, err := filepath.Abs(cleanRoot)
+	if err != nil {
+		return "", false, fmt.Errorf("cleanup policy %s: resolve root %q: %w", policy, cleanRoot, err)
+	}
+	info, err := os.Lstat(rootAbs)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return rootAbs, false, nil
+		}
+		return "", false, fmt.Errorf("cleanup policy %s: stat root %q: %w", policy, rootAbs, err)
+	}
+	if info.Mode()&os.ModeSymlink != 0 {
+		return "", false, fmt.Errorf("cleanup policy %s: refusing to clean symlink root %q", policy, rootAbs)
+	}
+	if !info.IsDir() {
+		return "", false, fmt.Errorf("cleanup policy %s: root %q is not a directory", policy, rootAbs)
+	}
+	return rootAbs, true, nil
+}

internal/app/cleanup_targets_test.go

@@ -0,0 +1,103 @@
+package app
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestCleanValidateScopedDirAndFile(t *testing.T) {
+	root := t.TempDir()
+	dirTarget := filepath.Join(root, "runs", "run-1")
+	fileTarget := filepath.Join(root, "cache", "a.flac")
+	if err := os.MkdirAll(dirTarget, 0o755); err != nil {
+		t.Fatalf("MkdirAll(dirTarget) error = %v", err)
+	}
+	if err := os.MkdirAll(filepath.Dir(fileTarget), 0o755); err != nil {
+		t.Fatalf("MkdirAll(file parent) error = %v", err)
+	}
+	if err := os.WriteFile(fileTarget, []byte("audio"), 0o644); err != nil {
+		t.Fatalf("WriteFile(fileTarget) error = %v", err)
+	}
+
+	if _, err := validateScopedDir(root, dirTarget, "test.dir"); err != nil {
+		t.Fatalf("validateScopedDir() error = %v", err)
+	}
+	if _, err := validateScopedFile(root, fileTarget, "test.file"); err != nil {
+		t.Fatalf("validateScopedFile() error = %v", err)
+	}
+}
+
+func TestCleanValidateScopedTargetSafetyRules(t *testing.T) {
+	root := t.TempDir()
+	outside := t.TempDir()
+	target := filepath.Join(root, "runs", "run-1")
+	if err := os.MkdirAll(target, 0o755); err != nil {
+		t.Fatalf("MkdirAll(target) error = %v", err)
+	}
+	fileTarget := filepath.Join(root, "cache", "a.flac")
+	if err := os.MkdirAll(filepath.Dir(fileTarget), 0o755); err != nil {
+		t.Fatalf("MkdirAll(file parent) error = %v", err)
+	}
+	if err := os.WriteFile(fileTarget, []byte("audio"), 0o644); err != nil {
+		t.Fatalf("WriteFile(fileTarget) error = %v", err)
+	}
+	symlinkTarget := filepath.Join(root, "symlink")
+	if err := os.Symlink(target, symlinkTarget); err != nil {
+		t.Fatalf("Symlink() error = %v", err)
+	}
+
+	if _, err := validateScopedDir(root, root, "test.root"); err == nil || !strings.Contains(err.Error(), "refusing to delete root directory") {
+		t.Fatalf("validateScopedDir(root) error = %v, want root deletion rejection", err)
+	}
+	if _, err := validateScopedDir(root, filepath.Join(outside, "x"), "test.outside"); err == nil || !strings.Contains(err.Error(), "outside root") {
+		t.Fatalf("validateScopedDir(outside) error = %v, want outside-root rejection", err)
+	}
+	if _, err := validateScopedDir(root, fileTarget, "test.file-as-dir"); err == nil || !strings.Contains(err.Error(), "is not a directory") {
+		t.Fatalf("validateScopedDir(file) error = %v, want not-a-directory rejection", err)
+	}
+	if _, err := validateScopedFile(root, target, "test.dir-as-file"); err == nil || !strings.Contains(err.Error(), "is a directory") {
+		t.Fatalf("validateScopedFile(dir) error = %v, want is-a-directory rejection", err)
+	}
+	if _, err := validateScopedDir(root, symlinkTarget, "test.symlink"); err == nil || !strings.Contains(err.Error(), "refusing to delete symlink path") {
+		t.Fatalf("validateScopedDir(symlink) error = %v, want symlink rejection", err)
+	}
+}
+
+func TestCleanableRootChildrenRejectsSymlinkChild(t *testing.T) {
+	root := t.TempDir()
+	realChild := filepath.Join(root, "runs")
+	if err := os.MkdirAll(realChild, 0o755); err != nil {
+		t.Fatalf("MkdirAll(realChild) error = %v", err)
+	}
+	if err := os.Symlink(realChild, filepath.Join(root, "link")); err != nil {
+		t.Fatalf("Symlink() error = %v", err)
+	}
+
+	_, _, err := cleanableRootChildren(root, "test.root.children")
+	if err == nil || !strings.Contains(err.Error(), "refusing to delete symlink path") {
+		t.Fatalf("cleanableRootChildren() error = %v, want symlink rejection", err)
+	}
+}
+
+func TestCleanValidateScopedTargetMissing(t *testing.T) {
+	root := t.TempDir()
+	missingDir := filepath.Join(root, "runs", "missing")
+	got, err := validateScopedDir(root, missingDir, "test.missing")
+	if err != nil {
+		t.Fatalf("validateScopedDir(missing) error = %v", err)
+	}
+	if got.Exists {
+		t.Fatalf("validateScopedDir(missing).Exists = true, want false")
+	}
+
+	missingFile := filepath.Join(root, "cache", "missing.flac")
+	got, err = validateScopedFile(root, missingFile, "test.missing.file")
+	if err != nil {
+		t.Fatalf("validateScopedFile(missing) error = %v", err)
+	}
+	if got.Exists {
+		t.Fatalf("validateScopedFile(missing).Exists = true, want false")
+	}
+}

internal/app/commands.go

@@ -7,7 +7,7 @@ import (
 	"strings"
 )
 
-var supportedCommands = []string{"run", "plan", "status", "resume", "run-stage", "analyze", "restore", "session", "artifacts", "locks", "clean"}
+var supportedCommands = []string{"run", "run-stage", "analyze", "publish", "clean", "session"}
 
 // Execute dispatches CLI commands and returns a process exit code.
 func Execute(args []string, stdout, stderr io.Writer) int {
@@ -24,24 +24,14 @@ func Execute(args []string, stdout, stderr io.Writer) int {
 	switch cmd {
 	case "run":
 		err = Run(ctx, cmdArgs, stdout)
-	case "plan":
-		err = Plan(ctx, cmdArgs, stdout)
-	case "status":
-		err = Status(ctx, cmdArgs, stdout)
-	case "resume":
-		err = Resume(ctx, cmdArgs, stdout)
 	case "run-stage":
 		err = RunStage(ctx, cmdArgs, stdout)
 	case "analyze":
 		err = Analyze(ctx, cmdArgs, stdout)
-	case "restore":
-		err = Restore(ctx, cmdArgs, stdout)
+	case "publish":
+		err = Publish(ctx, cmdArgs, stdout)
 	case "session":
 		err = Session(ctx, cmdArgs, stdout)
-	case "artifacts":
-		err = Artifacts(ctx, cmdArgs, stdout)
-	case "locks":
-		err = Locks(ctx, cmdArgs, stdout)
 	case "clean":
 		err = Clean(ctx, cmdArgs, stdout)
 	default:

internal/app/commands_test.go

@@ -25,18 +25,16 @@ func TestExecuteValidCommands(t *testing.T) {
 	defer srv.Close()
 
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot, srv.URL)
-	manifestPath := writeManifestPathForExecute(t)
 
 	cases := []struct {
 		name    string
 		args    []string
 		wantOut string
 	}{
-		{name: "run", args: []string{"run", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath}, wantOut: "narratio run: session 2026-05-03; executed=9 skipped=0; manifest="},
-		{name: "plan", args: []string{"plan", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath}, wantOut: "prepare: skip\ntranscribe: skip\nmerge: skip\npolish: skip\nnormalize: skip\ntrim: skip\nanalyze: skip\narchive: skip\nnotify: skip"},
-		{name: "status", args: []string{"status", "--manifest", manifestPath}, wantOut: "session_id: 2026-05-03"},
-		{name: "resume", args: []string{"resume", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath}, wantOut: "narratio resume: session 2026-05-03 has no remaining stages"},
-		{name: "run-stage", args: []string{"run-stage", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "polish"}, wantOut: "narratio run-stage: stage=polish executed=0 skipped=1 force=false; manifest="},
+		{name: "run", args: []string{"run", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, wantOut: "narratio run: session 2026-05-03; executed=9 skipped=0; manifest="},
+		{name: "session plan", args: []string{"session", "plan", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, wantOut: "prepare: skip\ntranscribe: skip\nmerge: skip\npolish: skip\nnormalize: skip\ntrim: skip\nanalyze: skip\npublish: skip\nnotify: skip"},
+		{name: "session status", args: []string{"session", "status", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, wantOut: "Session: 2026-05-03"},
+		{name: "run-stage", args: []string{"run-stage", "polish", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, wantOut: "narratio run-stage: stage=polish executed=0 skipped=1 force=false; manifest="},
 	}
 
 	for _, tc := range cases {
@@ -64,13 +62,13 @@ func TestExecuteMissingRequiredFlags(t *testing.T) {
 		args []string
 		want string
 	}{
-		{name: "run missing flags", args: []string{"run"}, want: "run: no pipeline config path provided and no default pipeline config found; searched:"},
-		{name: "plan missing flags", args: []string{"plan"}, want: "plan: no pipeline config path provided and no default pipeline config found; searched:"},
-		{name: "status missing flags", args: []string{"status"}, want: "status: --manifest is required"},
-		{name: "resume missing flags", args: []string{"resume"}, want: "resume: no pipeline config path provided and no default pipeline config found; searched:"},
-		{name: "run-stage missing name", args: []string{"run-stage", "--config", "a", "--session", "b"}, want: "run-stage: expected exactly one stage name"},
-		{name: "run-stage missing config flags", args: []string{"run-stage", "polish"}, want: "run-stage: no pipeline config path provided and no default pipeline config found; searched:"},
-		{name: "run missing config uses defaults", args: []string{"run", "--session", "session.yml"}, want: "run: no pipeline config path provided and no default pipeline config found; searched:"},
+		{name: "run missing session", args: []string{"run"}, want: "run: session_id is required"},
+		{name: "plan old top-level removed", args: []string{"plan"}, want: `unknown command: "plan"`},
+		{name: "status old top-level removed", args: []string{"status"}, want: `unknown command: "status"`},
+		{name: "resume removed", args: []string{"resume"}, want: `unknown command: "resume"`},
+		{name: "run-stage missing name", args: []string{"run-stage", "--config", "a", "--session", "b"}, want: "run-stage: expected stage name and session_id"},
+		{name: "run-stage missing session", args: []string{"run-stage", "polish"}, want: "run-stage: expected stage name and session_id"},
+		{name: "run missing config uses defaults", args: []string{"run", "2026-05-03", "--session", "session.yml"}, want: "run: no pipeline config path provided and no default pipeline config found; searched:"},
 	}
 
 	for _, tc := range cases {
@@ -99,7 +97,7 @@ func TestExecuteRunStageUnknownFails(t *testing.T) {
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
 
-	code := Execute([]string{"run-stage", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "unknown"}, &stdout, &stderr)
+	code := Execute([]string{"run-stage", "unknown", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
 	if code == 0 {
 		t.Fatal("exit code = 0, want non-zero")
 	}
@@ -108,16 +106,32 @@ func TestExecuteRunStageUnknownFails(t *testing.T) {
 	}
 }
 
-func TestExecuteRunStageNormalizeIsAccepted(t *testing.T) {
+func TestExecuteRunStageArchiveAliasFails(t *testing.T) {
 	workspaceRoot := t.TempDir()
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot, "https://example.com/transcribe")
-	workRoot := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03")
-	mustWriteTestFile(t, filepath.Join(workRoot, "transcripts", "processed.json"), `{"segments":[{"id":1}]}`)
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
 
-	code := Execute([]string{"run-stage", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "normalize"}, &stdout, &stderr)
+	code := Execute([]string{"run-stage", "archive", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
+	if code == 0 {
+		t.Fatal("exit code = 0, want non-zero")
+	}
+	if !strings.Contains(stderr.String(), `unknown stage "archive"`) {
+		t.Fatalf("stderr = %q, want unknown stage alias error", stderr.String())
+	}
+}
+
+func TestExecuteRunStageNormalizeIsAccepted(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot, "https://example.com/transcribe")
+	workRoot := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03")
+	mustWriteTestFile(t, filepath.Join(workRoot, "transcripts", "polished.json"), `{"segments":[{"id":1}]}`)
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+
+	code := Execute([]string{"run-stage", "normalize", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
 	}
@@ -141,14 +155,14 @@ func TestExecuteRunStageTranscribeUsesConfiguredWhisperXServer(t *testing.T) {
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
 
-	code := Execute([]string{"run-stage", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "prepare"}, &stdout, &stderr)
+	code := Execute([]string{"run-stage", "prepare", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("prepare exit code = %d, want 0; stderr=%q", code, stderr.String())
 	}
 	stdout.Reset()
 	stderr.Reset()
 
-	code = Execute([]string{"run-stage", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "--force", "transcribe"}, &stdout, &stderr)
+	code = Execute([]string{"run-stage", "transcribe", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--force"}, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("transcribe exit code = %d, want 0; stderr=%q", code, stderr.String())
 	}
@@ -203,8 +217,6 @@ seriatim:
 audita:
   binary: ` + auditaBinary + `
   llm_api_key_env: OPENROUTER_API_KEY
-analyzer:
-  timeout: 20m
 notification:
   timeout: 10s
 `
@@ -235,12 +247,12 @@ inputs:
 	})
 
 	workRoot := filepath.Join(workspaceRoot, "work", "sample-campaign", sessionID)
-	mustWriteTestFile(t, filepath.Join(workRoot, "transcripts", "merged.json"), `{"schema":"seriatim-intermediate","segments":[]}`)
+	mustWriteTestFile(t, filepath.Join(workRoot, "transcripts", "base.json"), `{"schema":"seriatim-intermediate","segments":[]}`)
 	mustWriteTestFile(t, filepath.Join(workRoot, "inputs", "glossary.yml"), "[]\n")
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"run-stage", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "--force", "polish"}, &stdout, &stderr)
+	code := Execute([]string{"run-stage", "polish", sessionID, "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--force"}, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
 	}
@@ -268,8 +280,6 @@ seriatim:
   binary: seriatim
 audita:
   binary: audita
-analyzer:
-  timeout: 20m
 notification:
   timeout: 10s
 `
@@ -290,7 +300,7 @@ inputs:
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"run", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath}, &stdout, &stderr)
+	code := Execute([]string{"run", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
 	if code == 0 {
 		t.Fatal("exit code = 0, want non-zero")
 	}
@@ -309,17 +319,15 @@ func TestExecuteUsesDefaultPipelineConfigPathWhenConfigFlagOmitted(t *testing.T)
 
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot, srv.URL)
 	originalDefaults := append([]string(nil), config.DefaultPipelineConfigSearchPaths...)
-	originalCampaignDefaults := append([]string(nil), config.DefaultCampaignConfigSearchPaths...)
 	config.DefaultPipelineConfigSearchPaths = []string{pipelinePath}
-	config.DefaultCampaignConfigSearchPaths = []string{campaignPath}
 	defer func() {
 		config.DefaultPipelineConfigSearchPaths = originalDefaults
-		config.DefaultCampaignConfigSearchPaths = originalCampaignDefaults
 	}()
+	_ = campaignPath
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"run", "--session", sessionPath}, &stdout, &stderr)
+	code := Execute([]string{"run", "2026-05-03", "--session", sessionPath}, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
 	}
@@ -328,30 +336,83 @@ func TestExecuteUsesDefaultPipelineConfigPathWhenConfigFlagOmitted(t *testing.T)
 	}
 }
 
-func TestExecuteMissingCampaignConfigReportsSearchedPaths(t *testing.T) {
+func TestExecuteMissingCampaignConfigReportsRegistryPath(t *testing.T) {
 	workspaceRoot := t.TempDir()
-	pipelinePath, _, sessionPath := writeValidConfigFiles(t, workspaceRoot)
-	missingCampaignPath := filepath.Join(t.TempDir(), "campaign.yml")
-	originalCampaignDefaults := append([]string(nil), config.DefaultCampaignConfigSearchPaths...)
-	config.DefaultCampaignConfigSearchPaths = []string{missingCampaignPath}
-	defer func() {
-		config.DefaultCampaignConfigSearchPaths = originalCampaignDefaults
-	}()
+	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
+	if err := os.Remove(campaignPath); err != nil {
+		t.Fatalf("remove campaign config: %v", err)
+	}
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"run", "--config", pipelinePath, "--session", sessionPath}, &stdout, &stderr)
+	code := Execute([]string{"run", "2026-05-03", "--config", pipelinePath, "--session", sessionPath}, &stdout, &stderr)
 	if code == 0 {
 		t.Fatal("exit code = 0, want non-zero")
 	}
 	if stdout.Len() != 0 {
 		t.Fatalf("stdout = %q, want empty", stdout.String())
 	}
-	if !strings.Contains(stderr.String(), "no campaign config path provided and no default campaign config found; searched:") {
+	if !strings.Contains(stderr.String(), "load campaign config") {
 		t.Fatalf("stderr = %q, want campaign discovery failure", stderr.String())
 	}
-	if !strings.Contains(stderr.String(), "pass --campaign") {
-		t.Fatalf("stderr = %q, want explicit campaign guidance", stderr.String())
+	if !strings.Contains(stderr.String(), filepath.ToSlash(filepath.Join("campaigns", "sample-campaign", "campaign.yml"))) {
+		t.Fatalf("stderr = %q, want campaign registry path", stderr.String())
+	}
+}
+
+func TestExecuteUsesPipelineDefaultCampaignID(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, _, sessionPath := writeValidConfigFiles(t, workspaceRoot)
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	code := Execute([]string{"session", "status", "2026-05-03", "--config", pipelinePath, "--session", sessionPath}, &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
+	}
+	if !strings.Contains(stdout.String(), "Campaign: sample-campaign") {
+		t.Fatalf("stdout = %q, want default campaign", stdout.String())
+	}
+}
+
+func TestExecuteCampaignIDSelectsRegistryCampaign(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
+	campaignRoot := filepath.Dir(filepath.Dir(campaignPath))
+	otherDir := filepath.Join(campaignRoot, "icewind")
+	mustWriteTestFile(t, filepath.Join(otherDir, "campaign.yml"), `campaign_id: icewind
+inputs:
+  speakers_file: ./speakers.yml
+  autocorrect_file: ./autocorrect.yml
+  glossary_file: ./glossary.yml
+`)
+	mustWriteTestFile(t, filepath.Join(otherDir, "speakers.yml"), "match:\n  - speaker: Alice\n    match: [\"alice\"]\n")
+	mustWriteTestFile(t, filepath.Join(otherDir, "autocorrect.yml"), "[]\n")
+	mustWriteTestFile(t, filepath.Join(otherDir, "glossary.yml"), "[]\n")
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	code := Execute([]string{"session", "status", "2026-05-03", "--config", pipelinePath, "--campaign", "icewind", "--session", sessionPath}, &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
+	}
+	if !strings.Contains(stdout.String(), "Campaign: icewind") {
+		t.Fatalf("stdout = %q, want selected campaign", stdout.String())
+	}
+}
+
+func TestExecuteRejectsCampaignIDAndCampaignFile(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	code := Execute([]string{"session", "status", "2026-05-03", "--config", pipelinePath, "--campaign", "sample-campaign", "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
+	if code == 0 {
+		t.Fatal("exit code = 0, want non-zero")
+	}
+	if !strings.Contains(stderr.String(), "mutually exclusive") {
+		t.Fatalf("stderr = %q, want mutually exclusive error", stderr.String())
 	}
 }
 
@@ -396,7 +457,9 @@ func writeValidConfigFiles(t *testing.T, workspaceRoot string, transcribeURL ...
 
 	dir := t.TempDir()
 	pipelinePath := filepath.Join(dir, "pipeline.yml")
-	campaignPath := filepath.Join(dir, "campaign.yml")
+	campaignRoot := filepath.Join(dir, "campaigns")
+	campaignDir := filepath.Join(campaignRoot, "sample-campaign")
+	campaignPath := filepath.Join(campaignDir, "campaign.yml")
 	sessionPath := filepath.Join(dir, "session.yml")
 	url := "https://example.com/transcribe"
 	if len(transcribeURL) > 0 && strings.TrimSpace(transcribeURL[0]) != "" {
@@ -410,6 +473,9 @@ func writeValidConfigFiles(t *testing.T, workspaceRoot string, transcribeURL ...
 
 	pipelineYAML := `workspace:
   root: ` + workspaceRoot + `
+campaigns:
+  root: ` + campaignRoot + `
+  default_campaign_id: sample-campaign
 cache:
   root: ` + filepath.Join(workspaceRoot, "cache") + `
 spool:
@@ -418,7 +484,7 @@ storage:
   backend: s3
   s3:
     bucket: test-bucket
-archive:
+publish:
   enabled: true
   upload_run: false
 whisperx:
@@ -435,10 +501,6 @@ seriatim:
   report: true
 audita:
   binary: ` + auditaBinary + `
-analyzer:
-  timeout: 20m
-  artifacts:
-    output_dir: artifacts
 notification:
   timeout: 10s
 `
@@ -447,7 +509,7 @@ notification:
 inputs:
   audio_dir: ./audio
 `
-	campaignYAML := `campaign: sample-campaign
+	campaignYAML := `campaign_id: sample-campaign
 inputs:
   speakers_file: ./speakers.yml
   autocorrect_file: ./autocorrect.yml
@@ -457,6 +519,9 @@ inputs:
 	if err := os.WriteFile(pipelinePath, []byte(pipelineYAML), 0o644); err != nil {
 		t.Fatalf("write pipeline config: %v", err)
 	}
+	if err := os.MkdirAll(campaignDir, 0o755); err != nil {
+		t.Fatalf("create campaign dir: %v", err)
+	}
 	if err := os.WriteFile(campaignPath, []byte(campaignYAML), 0o644); err != nil {
 		t.Fatalf("write campaign config: %v", err)
 	}
@@ -464,9 +529,9 @@ inputs:
 		t.Fatalf("write session config: %v", err)
 	}
 
-	mustWriteTestFile(t, filepath.Join(dir, "speakers.yml"), "match:\n  - speaker: Alice\n    match: [\"alice\"]\n")
-	mustWriteTestFile(t, filepath.Join(dir, "autocorrect.yml"), "[]\n")
-	mustWriteTestFile(t, filepath.Join(dir, "glossary.yml"), "[]\n")
+	mustWriteTestFile(t, filepath.Join(campaignDir, "speakers.yml"), "match:\n  - speaker: Alice\n    match: [\"alice\"]\n")
+	mustWriteTestFile(t, filepath.Join(campaignDir, "autocorrect.yml"), "[]\n")
+	mustWriteTestFile(t, filepath.Join(campaignDir, "glossary.yml"), "[]\n")
 	mustWriteTestFile(t, filepath.Join(dir, "audio", "alice.flac"), "audio-bytes")
 
 	return pipelinePath, campaignPath, sessionPath
@@ -475,7 +540,7 @@ inputs:
 func writeAppTestCampaignConfig(t *testing.T, dir string) string {
 	t.Helper()
 	campaignPath := filepath.Join(dir, "campaign.yml")
-	campaignYAML := `campaign: sample-campaign
+	campaignYAML := `campaign_id: sample-campaign
 inputs:
   speakers_file: ./speakers.yml
   autocorrect_file: ./autocorrect.yml

internal/app/config_loader.go

@@ -4,7 +4,6 @@ import (
 	"context"
 	"fmt"
 	"os"
-	"path/filepath"
 	"strings"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
@@ -12,18 +11,21 @@ import (
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
 )
 
-func loadCommandConfig(ctx context.Context, pipelineFlag, campaignFlag, sessionFlag string, sessionOpts config.SessionLoadOptions) (*config.Config, error) {
-	resolvedPipelinePath, err := resolvePipelineConfigPath(pipelineFlag)
-	if err != nil {
-		return nil, err
-	}
-	resolvedCampaignPath, err := resolveCampaignConfigPath(campaignFlag)
+type pipelineCampaignConfig struct {
+	PipelinePath string
+	CampaignPath string
+	Pipeline     *config.PipelineConfig
+	Campaign     *config.CampaignConfig
+}
+
+func loadCommandConfig(ctx context.Context, pipelineFlag, campaignFlag, campaignFileFlag, sessionFlag string, sessionOpts config.SessionLoadOptions) (*config.Config, error) {
+	base, err := loadPipelineCampaignConfig(pipelineFlag, campaignFlag, campaignFileFlag)
 	if err != nil {
 		return nil, err
 	}
 
 	if explicitSession := strings.TrimSpace(sessionFlag); explicitSession != "" {
-		return config.LoadWithSessionOptions(resolvedPipelinePath, resolvedCampaignPath, explicitSession, sessionOpts)
+		return config.LoadWithSessionOptions(base.PipelinePath, base.CampaignPath, explicitSession, sessionOpts)
 	}
 
 	discoveredSession, err := discoverSessionConfigPathWithCandidates(config.DefaultSessionConfigSearchPaths)
@@ -31,30 +33,21 @@ func loadCommandConfig(ctx context.Context, pipelineFlag, campaignFlag, sessionF
 		return nil, err
 	}
 	if discoveredSession.Path != "" {
-		return config.LoadWithSessionOptions(resolvedPipelinePath, resolvedCampaignPath, discoveredSession.Path, sessionOpts)
-	}
-
-	pipelineCfg, err := config.LoadPipeline(resolvedPipelinePath)
-	if err != nil {
-		return nil, err
-	}
-	campaignCfg, err := config.LoadCampaign(resolvedCampaignPath)
-	if err != nil {
-		return nil, err
+		return config.LoadWithSessionOptions(base.PipelinePath, base.CampaignPath, discoveredSession.Path, sessionOpts)
 	}
 
 	sessionID := strings.TrimSpace(sessionOpts.SessionID)
 	if sessionID == "" {
-		return nil, missingSessionConfigError(discoveredSession.Searched, "remote session loading requires --session-id")
+		return nil, missingSessionConfigError(discoveredSession.Searched, "remote session loading requires a session_id")
 	}
 
-	sessionPrefix := artifacts.S3SessionPrefix(pipelineCfg.Storage.S3.RootPrefix, campaignCfg.Campaign, sessionID)
+	sessionPrefix := artifacts.S3SessionPrefix(base.Pipeline.Storage.S3.RootPrefix, config.CampaignID(base.Campaign), sessionID)
 	remoteKey := artifacts.S3SessionConfigKey(sessionPrefix)
 	partialCfg := &config.Config{
-		Pipeline:     pipelineCfg,
-		Campaign:     campaignCfg,
-		PipelinePath: resolvedPipelinePath,
-		CampaignPath: resolvedCampaignPath,
+		Pipeline:     base.Pipeline,
+		Campaign:     base.Campaign,
+		PipelinePath: base.PipelinePath,
+		CampaignPath: base.CampaignPath,
 	}
 	store, err := newCommandObjectStore(ctx, partialCfg, nil)
 	if err != nil {
@@ -65,7 +58,7 @@ func loadCommandConfig(ctx context.Context, pipelineFlag, campaignFlag, sessionF
 	if err != nil {
 		return nil, missingSessionConfigError(discoveredSession.Searched, err.Error())
 	}
-	sessionTempPath, err := downloadRemoteSessionConfig(ctx, store, remoteKey)
+	sessionTempPath, err := storage.DownloadObjectToTemp(ctx, store, remoteKey, "narratio-session-*.yml")
 	if err != nil {
 		return nil, missingSessionConfigError(discoveredSession.Searched, fmt.Sprintf("remote session %q download failed: %v", remoteKey, err))
 	}
@@ -73,22 +66,22 @@ func loadCommandConfig(ctx context.Context, pipelineFlag, campaignFlag, sessionF
 	if err != nil {
 		return nil, fmt.Errorf("read downloaded remote session %q: %w", sessionTempPath, err)
 	}
-	sessionCfg, err := config.LoadSessionBytesWithOptions("s3://"+s3BucketName(pipelineCfg)+"/"+remoteKey, sessionBytes, sessionOpts)
+	sessionCfg, err := config.LoadSessionBytesWithOptions("s3://"+s3BucketName(base.Pipeline)+"/"+remoteKey, sessionBytes, sessionOpts)
 	if err != nil {
 		return nil, err
 	}
 
 	return config.Resolve(
-		resolvedPipelinePath,
-		pipelineCfg,
-		resolvedCampaignPath,
-		campaignCfg,
+		base.PipelinePath,
+		base.Pipeline,
+		base.CampaignPath,
+		base.Campaign,
 		sessionTempPath,
 		sessionCfg,
 		config.SessionSource{
 			Source:    "session_config.s3",
 			LocalPath: sessionTempPath,
-			S3Bucket:  s3BucketName(pipelineCfg),
+			S3Bucket:  s3BucketName(base.Pipeline),
 			S3Key:     remoteKey,
 			S3Size:    sessionInfo.Size,
 			S3ETag:    sessionInfo.ETag,
@@ -97,6 +90,36 @@ func loadCommandConfig(ctx context.Context, pipelineFlag, campaignFlag, sessionF
 	)
 }
 
+func loadPipelineCampaignConfig(pipelineFlag, campaignFlag, campaignFileFlag string) (*pipelineCampaignConfig, error) {
+	resolvedPipelinePath, err := resolvePipelineConfigPath(pipelineFlag)
+	if err != nil {
+		return nil, err
+	}
+	pipelineCfg, err := config.LoadPipeline(resolvedPipelinePath)
+	if err != nil {
+		return nil, err
+	}
+	resolvedCampaignPath, err := resolveCampaignConfigPath(pipelineCfg, campaignFlag, campaignFileFlag)
+	if err != nil {
+		return nil, err
+	}
+	campaignCfg, err := config.LoadCampaign(resolvedCampaignPath)
+	if err != nil {
+		return nil, err
+	}
+	if selectedID := strings.TrimSpace(campaignFlag); selectedID != "" && strings.TrimSpace(campaignFileFlag) == "" {
+		if got := config.CampaignID(campaignCfg); got != selectedID {
+			return nil, fmt.Errorf("campaign config %q invalid: campaign_id %q does not match selected campaign %q", resolvedCampaignPath, got, selectedID)
+		}
+	}
+	return &pipelineCampaignConfig{
+		PipelinePath: resolvedPipelinePath,
+		CampaignPath: resolvedCampaignPath,
+		Pipeline:     pipelineCfg,
+		Campaign:     campaignCfg,
+	}, nil
+}
+
 func findRemoteSessionConfig(ctx context.Context, store storage.ObjectStore, sessionPrefix, remoteKey string) (storage.ObjectInfo, error) {
 	objects, err := store.List(ctx, sessionPrefix)
 	if err != nil {
@@ -110,21 +133,6 @@ func findRemoteSessionConfig(ctx context.Context, store storage.ObjectStore, ses
 	return storage.ObjectInfo{}, fmt.Errorf("remote session %q not found", remoteKey)
 }
 
-func downloadRemoteSessionConfig(ctx context.Context, store storage.ObjectStore, remoteKey string) (string, error) {
-	f, err := os.CreateTemp("", "narratio-session-*.yml")
-	if err != nil {
-		return "", fmt.Errorf("create temp file: %w", err)
-	}
-	path := f.Name()
-	if err := f.Close(); err != nil {
-		return "", fmt.Errorf("close temp file %q: %w", path, err)
-	}
-	if err := store.Download(ctx, remoteKey, path); err != nil {
-		return "", err
-	}
-	return filepath.Clean(path), nil
-}
-
 func s3BucketName(cfg *config.PipelineConfig) string {
 	if cfg == nil || cfg.Storage.S3 == nil {
 		return ""

internal/app/operator_artifact_rendering.go

@@ -0,0 +1,136 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
+	"gitea.maximumdirect.net/eric/narratio/internal/artifactpolicy"
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+)
+
+func buildHelperArtifactCatalog(cfg *config.Config) (*artifacts.ArtifactCatalog, error) {
+	catalog := artifacts.NewArtifactCatalog()
+	if err := catalog.RegisterBuiltIns(); err != nil {
+		return nil, err
+	}
+	configured := map[string]artifacts.ConfiguredArtifactDefinition{}
+	if cfg.Pipeline.Scriptorium != nil {
+		for key, item := range cfg.Pipeline.Scriptorium.Artifacts {
+			configured[key] = artifacts.ConfiguredArtifactDefinition{Enabled: item.Enabled, OutputPath: item.OutputPath}
+		}
+	}
+	if err := catalog.RegisterConfiguredArtifacts(configured, nil); err != nil {
+		return nil, err
+	}
+	return catalog, nil
+}
+
+func writeArtifactList(out io.Writer, cfg *config.Config, catalog *artifacts.ArtifactCatalog, locks *effectiveLocks, publishedRemoteState map[string]string) {
+	lockSet := lockSourceSet(locks.All)
+	fmt.Fprintln(out, "Built-in:")
+	for _, id := range []string{
+		artifacts.ArtifactTranscriptBase,
+		artifacts.ArtifactTranscriptPolished,
+		artifacts.ArtifactTranscriptFinal,
+		artifacts.ArtifactTranscriptFinalTrimmed,
+		artifacts.ArtifactBoundsSession,
+	} {
+		writeArtifactLine(out, id, lockSet)
+	}
+	fmt.Fprintln(out, "Configured:")
+	for _, entry := range catalog.ListConfigured() {
+		writeArtifactLine(out, entry.SourceID, lockSet)
+	}
+	fmt.Fprintln(out, "Previous-session:")
+	for _, req := range artifacts.CollectPreviousArtifactRequirements(configuredScriptoriumArtifacts(cfg)) {
+		fmt.Fprintf(out, "- %s required=%t\n", artifactpolicy.PreviousSessionSourceID(req.Name), req.Required)
+	}
+	fmt.Fprintln(out, "Published:")
+	for _, rule := range cfg.Pipeline.Publish.Outputs {
+		writePublishedOutputLine(out, rule, catalog, lockSet, publishedRemoteState)
+	}
+}
+
+func writeArtifactLine(out io.Writer, source string, lockSet map[string]config.PublishLockRule) {
+	parts := []string{source}
+	if _, ok := lockSet[source]; ok {
+		parts = append(parts, "locked")
+	}
+	fmt.Fprintf(out, "- %s\n", strings.Join(parts, " "))
+}
+
+func writePublishedOutputLine(out io.Writer, rule config.PublishOutputRule, catalog *artifacts.ArtifactCatalog, lockSet map[string]config.PublishLockRule, remoteState map[string]string) {
+	source := strings.TrimSpace(rule.Source)
+	parts := []string{source}
+	if _, ok := lockSet[source]; ok {
+		parts = append(parts, "locked")
+	}
+	dest, showDest, err := helperPublishedOutputDest(rule, catalog)
+	if err != nil {
+		parts = append(parts, "remote=error")
+		fmt.Fprintf(out, "- %s\n", strings.Join(parts, " "))
+		return
+	}
+	if showDest {
+		parts = append(parts, "dest="+dest)
+	}
+	if state := remoteState[publishedOutputRemoteStateKey(source, dest)]; state != "" {
+		parts = append(parts, state)
+	}
+	fmt.Fprintf(out, "- %s\n", strings.Join(parts, " "))
+}
+
+func remotePublishedOutputAvailability(ctx context.Context, cfg *config.Config, store storage.ObjectStore, catalog *artifacts.ArtifactCatalog) map[string]string {
+	out := map[string]string{}
+	sessionPrefix := artifacts.S3SessionPrefix(cfg.Pipeline.Storage.S3.RootPrefix, cfg.Session.Campaign, cfg.Session.SessionID)
+	for _, rule := range cfg.Pipeline.Publish.Outputs {
+		source := strings.TrimSpace(rule.Source)
+		dest, _, err := helperPublishedOutputDest(rule, catalog)
+		if err != nil {
+			out[publishedOutputRemoteStateKey(source, "")] = "remote=error"
+			continue
+		}
+		key := artifacts.S3PublishedOutputKey(sessionPrefix, dest)
+		if exists, err := store.Exists(ctx, key); err == nil && exists {
+			out[publishedOutputRemoteStateKey(source, dest)] = "remote=published"
+		} else if err != nil {
+			out[publishedOutputRemoteStateKey(source, dest)] = "remote=error"
+		} else {
+			out[publishedOutputRemoteStateKey(source, dest)] = "remote=missing"
+		}
+	}
+	return out
+}
+
+func helperPublishedOutputDest(rule config.PublishOutputRule, catalog *artifacts.ArtifactCatalog) (string, bool, error) {
+	source := strings.TrimSpace(rule.Source)
+	normalized, err := artifactpolicy.ResolvePublishedDestination(source, rule.Dest, helperConfiguredOutputPathMap(catalog))
+	if err != nil {
+		return "", false, err
+	}
+	entry, ok := catalog.Lookup(source)
+	showDest := !ok || strings.TrimSpace(entry.CanonicalRelPath) != normalized
+	return normalized, showDest, nil
+}
+
+func helperConfiguredOutputPathMap(catalog *artifacts.ArtifactCatalog) map[string]string {
+	out := map[string]string{}
+	if catalog == nil {
+		return out
+	}
+	for _, entry := range catalog.ListConfigured() {
+		if strings.TrimSpace(entry.ConfiguredKey) == "" {
+			continue
+		}
+		out[entry.ConfiguredKey] = strings.TrimSpace(entry.CanonicalRelPath)
+	}
+	return out
+}
+
+func publishedOutputRemoteStateKey(source, dest string) string {
+	return strings.TrimSpace(source) + "\x00" + strings.TrimSpace(dest)
+}

internal/app/operator_artifacts_list.go

@@ -0,0 +1,39 @@
+package app
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"io"
+	"strings"
+)
+
+// ArtifactsList lists effective artifact sources.
+func ArtifactsList(ctx context.Context, args []string, out io.Writer) error {
+	fs := flag.NewFlagSet("artifacts list", flag.ContinueOnError)
+	fs.SetOutput(io.Discard)
+	var flags commonConfigFlags
+	var remote bool
+	addCommonConfigFlags(fs, &flags)
+	fs.BoolVar(&remote, "remote", false, "inspect remote publish availability")
+	if err := parseSessionAwareFlags("artifacts list", fs, args, &flags.sessionID); err != nil {
+		return err
+	}
+	if strings.TrimSpace(flags.sessionID) == "" {
+		return fmt.Errorf("artifacts list: session_id is required")
+	}
+	cfg, store, locks, _, err := loadHelperContext(ctx, flags, remote)
+	if err != nil {
+		return fmt.Errorf("artifacts list: %w", err)
+	}
+	catalog, err := buildHelperArtifactCatalog(cfg)
+	if err != nil {
+		return fmt.Errorf("artifacts list: %w", err)
+	}
+	publishedRemoteState := map[string]string{}
+	if remote && store != nil {
+		publishedRemoteState = remotePublishedOutputAvailability(ctx, cfg, store, catalog)
+	}
+	writeArtifactList(out, cfg, catalog, locks, publishedRemoteState)
+	return nil
+}

internal/app/operator_findings.go

@@ -0,0 +1,140 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
+)
+
+type finding struct {
+	Severity string
+	Category string
+	Message  string
+}
+
+type findingError struct {
+	count int
+}
+
+func (e findingError) Error() string {
+	return fmt.Sprintf("%d validation error(s)", e.count)
+}
+
+func renderFindings(out io.Writer, campaign, sessionID string, findings []finding) error {
+	if campaign != "" || sessionID != "" {
+		fmt.Fprintf(out, "Campaign: %s\n", campaign)
+		fmt.Fprintf(out, "Session: %s\n\n", sessionID)
+	}
+	errorsCount := 0
+	for _, f := range findings {
+		if f.Severity == "ERROR" {
+			errorsCount++
+		}
+		fmt.Fprintf(out, "%-5s %-10s %s\n", f.Severity, f.Category, f.Message)
+	}
+	if errorsCount > 0 {
+		return findingError{count: errorsCount}
+	}
+	return nil
+}
+
+func okFinding(category, msg string) finding    { return finding{"OK", category, msg} }
+func infoFinding(category, msg string) finding  { return finding{"INFO", category, msg} }
+func warnFinding(category, msg string) finding  { return finding{"WARN", category, msg} }
+func errorFinding(category, msg string) finding { return finding{"ERROR", category, msg} }
+
+func sessionSourceSummary(cfg *config.Config) string {
+	source := cfg.SessionSource.Source
+	if source == "" {
+		source = "session_config"
+	}
+	if cfg.SessionSource.S3Key != "" {
+		return source + " " + cfg.SessionSource.S3Key
+	}
+	return source + " " + cfg.SessionPath
+}
+
+func validateStableInputFindings(cfg *config.Config) []finding {
+	checks := inspectStableInputs(cfg)
+	out := make([]finding, 0, len(checks))
+	for _, check := range checks {
+		if check.Err != nil {
+			msg := check.Name + ": " + check.Err.Error()
+			if strings.TrimSpace(check.Path) != "" {
+				msg = fmt.Sprintf("%s missing: %v", check.Name, check.Err)
+			}
+			out = append(out, errorFinding("inputs", msg))
+			continue
+		}
+		out = append(out, okFinding("inputs", check.Name+": "+check.Path))
+	}
+	return out
+}
+
+func resolveHelperConfigRelativePath(input config.ResolvedInputFile) (string, error) {
+	if strings.TrimSpace(input.ConfigPath) == "" {
+		return "", fmt.Errorf("source config path is required")
+	}
+	path := strings.TrimSpace(input.Path)
+	if path == "" {
+		return "", fmt.Errorf("path is required")
+	}
+	if filepath.IsAbs(path) {
+		return filepath.Clean(path), nil
+	}
+	return filepath.Clean(filepath.Join(filepath.Dir(input.ConfigPath), path)), nil
+}
+
+func validateLocalAudioFindings(cfg *config.Config) []finding {
+	check := inspectLocalAudioPresence(cfg)
+	if !check.Checked {
+		return nil
+	}
+	if check.Err != nil {
+		return []finding{errorFinding("audio", check.Err.Error())}
+	}
+	return []finding{okFinding("audio", fmt.Sprintf("%d local audio file(s)", len(check.Paths)))}
+}
+
+func validateRemoteAudioFinding(ctx context.Context, cfg *config.Config, store storage.ObjectStore) finding {
+	check := inspectRemoteAudioPresence(ctx, cfg, store)
+	if check.Err != nil {
+		return errorFinding("audio", check.Err.Error())
+	}
+	return okFinding("audio", fmt.Sprintf("%d remote .flac object(s)", len(check.Keys)))
+}
+
+func loadLocalManifest(ctx context.Context, path string) (*manifest.Manifest, error) {
+	if _, err := os.Stat(path); err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	store := &manifest.LocalStore{}
+	return store.Load(ctx, path)
+}
+
+func writeStageStatuses(out io.Writer, m *manifest.Manifest) {
+	if m == nil || len(m.Stages) == 0 {
+		fmt.Fprintln(out, "stages: no stages recorded")
+		return
+	}
+	fmt.Fprintln(out, "stages:")
+	names := make([]string, 0, len(m.Stages))
+	for name := range m.Stages {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	for _, name := range names {
+		fmt.Fprintf(out, "- %s: %s\n", name, m.Stages[name].Status)
+	}
+}

internal/app/operator_helpers.go

@@ -5,47 +5,30 @@ import (
 	"flag"
 	"fmt"
 	"io"
-	"os"
-	"path/filepath"
-	"regexp"
-	"sort"
 	"strings"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
 	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
 	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
-	"gopkg.in/yaml.v3"
 )
 
 type commonConfigFlags struct {
 	pipelinePath      string
 	campaignPath      string
+	campaignFilePath  string
 	sessionPath       string
 	sessionID         string
 	previousSessionID string
 }
 
-type finding struct {
-	Severity string
-	Category string
-	Message  string
-}
-
-type findingError struct {
-	count int
-}
-
-func (e findingError) Error() string {
-	return fmt.Sprintf("%d validation error(s)", e.count)
-}
-
 func addCommonConfigFlags(fs *flag.FlagSet, flags *commonConfigFlags) {
 	fs.StringVar(&flags.pipelinePath, "config", "", "path to pipeline.yml (optional; defaults searched)")
-	fs.StringVar(&flags.campaignPath, "campaign", "", "path to campaign.yml (optional; defaults searched)")
+	fs.StringVar(&flags.campaignPath, "campaign", "", "campaign ID")
+	fs.StringVar(&flags.campaignFilePath, "campaign-file", "", "path to campaign.yml")
 	fs.StringVar(&flags.sessionPath, "session", "", "path to session.yml")
-	fs.StringVar(&flags.sessionID, "session-id", "", "session identifier for session.yml templates")
-	fs.StringVar(&flags.previousSessionID, "previous-session-id", "", "previous session identifier for session.yml templates")
+	fs.StringVar(&flags.sessionID, "session-id", "", "session identifier")
+	fs.StringVar(&flags.previousSessionID, "previous-session-id", "", "expected previous session identifier")
 }
 
 func (f commonConfigFlags) sessionOptions() config.SessionLoadOptions {
@@ -58,18 +41,42 @@ func (f commonConfigFlags) sessionOptions() config.SessionLoadOptions {
 // Session dispatches session helper subcommands.
 func Session(ctx context.Context, args []string, out io.Writer) error {
 	if len(args) == 0 {
-		return fmt.Errorf("session: expected subcommand: validate|init")
+		return fmt.Errorf("session: expected subcommand: init|validate|status|plan|restore|artifacts|locks")
 	}
 	switch args[0] {
-	case "validate":
-		return SessionValidate(ctx, args[1:], out)
 	case "init":
 		return SessionInit(ctx, args[1:], out)
+	case "validate":
+		return SessionValidate(ctx, args[1:], out)
+	case "status":
+		return Status(ctx, args[1:], out)
+	case "plan":
+		return Plan(ctx, args[1:], out)
+	case "restore":
+		return Restore(ctx, args[1:], out)
+	case "artifacts":
+		return ArtifactsList(ctx, args[1:], out)
+	case "locks":
+		return SessionLocks(ctx, args[1:], out)
 	default:
 		return fmt.Errorf("session: unknown subcommand %q", args[0])
 	}
 }
 
+// SessionLocks dispatches session-oriented publish lock list and mutation
+// helpers while preserving the existing lock implementations.
+func SessionLocks(ctx context.Context, args []string, out io.Writer) error {
+	if len(args) > 0 && !isCLIFlagToken(args[0]) {
+		switch args[0] {
+		case "add":
+			return LocksAdd(ctx, args[1:], out)
+		case "remove":
+			return LocksRemove(ctx, args[1:], out)
+		}
+	}
+	return LocksList(ctx, args, out)
+}
+
 // Artifacts dispatches artifact helper subcommands.
 func Artifacts(ctx context.Context, args []string, out io.Writer) error {
 	if len(args) == 0 {
@@ -83,444 +90,8 @@ func Artifacts(ctx context.Context, args []string, out io.Writer) error {
 	}
 }
 
-// SessionValidate performs a read-only session preflight.
-func SessionValidate(ctx context.Context, args []string, out io.Writer) error {
-	fs := flag.NewFlagSet("session validate", flag.ContinueOnError)
-	fs.SetOutput(io.Discard)
-	var flags commonConfigFlags
-	addCommonConfigFlags(fs, &flags)
-	if err := fs.Parse(args); err != nil {
-		return fmt.Errorf("session validate: invalid flags: %w", err)
-	}
-	if fs.NArg() != 0 {
-		return fmt.Errorf("session validate: unexpected positional arguments")
-	}
-
-	findings := []finding{}
-	cfg, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.sessionPath, flags.sessionOptions())
-	if err != nil {
-		findings = append(findings, errorFinding("config", err.Error()))
-		return renderFindings(out, "", "", findings)
-	}
-	if err := config.Validate(cfg); err != nil {
-		findings = append(findings, errorFinding("config", err.Error()))
-	} else {
-		findings = append(findings, okFinding("config", "resolved pipeline, campaign, and session config"))
-	}
-	findings = append(findings, okFinding("session", fmt.Sprintf("session source: %s", sessionSourceSummary(cfg))))
-
-	paths := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root).SessionPathsFor(cfg.Session.Campaign, cfg.Session.SessionID)
-	findings = append(findings, validateStableInputFindings(cfg)...)
-	findings = append(findings, validateLocalAudioFindings(cfg)...)
-
-	store, storeErr := objectStoreIfConfigured(ctx, cfg)
-	if storeErr != nil {
-		findings = append(findings, errorFinding("storage", storeErr.Error()))
-	}
-	if cfg.Session.Inputs.AudioS3 != nil {
-		if storeErr != nil {
-			findings = append(findings, errorFinding("audio", "remote audio cannot be checked because storage is unavailable"))
-		} else {
-			findings = append(findings, validateRemoteAudioFinding(ctx, cfg, store))
-		}
-	}
-
-	requirements := artifacts.CollectPreviousArtifactRequirements(configuredScriptoriumArtifacts(cfg))
-	if len(requirements) == 0 {
-		findings = append(findings, okFinding("previous", "no previous-session artifacts required"))
-	} else if strings.TrimSpace(cfg.Session.PreviousSessionID) == "" {
-		findings = append(findings, errorFinding("previous", "previous_session_id is required by configured previous-session artifacts"))
-	} else if storeErr != nil {
-		findings = append(findings, errorFinding("previous", "previous-session artifacts cannot be checked because storage is unavailable"))
-	} else {
-		findings = append(findings, validatePreviousArtifactFindings(ctx, cfg, store, requirements)...)
-	}
-
-	locks, lockErr := loadEffectiveLocks(ctx, cfg, store)
-	if lockErr != nil {
-		findings = append(findings, errorFinding("locks", lockErr.Error()))
-	} else if len(locks.All) == 0 {
-		findings = append(findings, okFinding("locks", "no effective archive locks"))
-	} else {
-		for _, lock := range locks.All {
-			findings = append(findings, warnFinding("locks", fmt.Sprintf("%s locked: %s", lock.Source, strings.TrimSpace(lock.Reason))))
-		}
-	}
-	if paths.ManifestPath != "" {
-		findings = append(findings, infoFinding("workspace", "manifest path: "+paths.ManifestPath))
-	}
-	return renderFindings(out, cfg.Session.Campaign, cfg.Session.SessionID, findings)
-}
-
-// Status reports either a requested manifest or effective local/remote session state.
-func Status(ctx context.Context, args []string, out io.Writer) error {
-	fs := flag.NewFlagSet("status", flag.ContinueOnError)
-	fs.SetOutput(io.Discard)
-	var manifestPath string
-	var flags commonConfigFlags
-	fs.StringVar(&manifestPath, "manifest", "", "path to manifest.json")
-	addCommonConfigFlags(fs, &flags)
-	if err := fs.Parse(args); err != nil {
-		return fmt.Errorf("status: invalid flags: %w", err)
-	}
-	if fs.NArg() != 0 {
-		return fmt.Errorf("status: unexpected positional arguments")
-	}
-	if strings.TrimSpace(manifestPath) != "" {
-		return statusManifest(ctx, manifestPath, out)
-	}
-	if flags.pipelinePath == "" && flags.campaignPath == "" && flags.sessionPath == "" && flags.sessionID == "" && flags.previousSessionID == "" {
-		return fmt.Errorf("status: --manifest is required")
-	}
-	cfg, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.sessionPath, flags.sessionOptions())
-	if err != nil {
-		return fmt.Errorf("status: %w", err)
-	}
-	if err := config.Validate(cfg); err != nil {
-		return fmt.Errorf("status: %w", err)
-	}
-	paths := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root).SessionPathsFor(cfg.Session.Campaign, cfg.Session.SessionID)
-	fmt.Fprintf(out, "Session: %s\n", cfg.Session.SessionID)
-	fmt.Fprintf(out, "Campaign: %s\n", cfg.Session.Campaign)
-	fmt.Fprintf(out, "Workspace: %s\n", paths.Root)
-	fmt.Fprintf(out, "Session config: %s\n", sessionSourceSummary(cfg))
-
-	if m, err := loadLocalManifest(ctx, paths.ManifestPath); err != nil {
-		fmt.Fprintf(out, "Local manifest: error: %v\n", err)
-	} else if m == nil {
-		fmt.Fprintln(out, "Local manifest: missing")
-	} else {
-		fmt.Fprintf(out, "Local manifest: %s\n", paths.ManifestPath)
-		writeStageStatuses(out, m)
-	}
-
-	store, storeErr := objectStoreIfConfigured(ctx, cfg)
-	if storeErr != nil {
-		fmt.Fprintf(out, "Remote archive: unavailable: %v\n", storeErr)
-	} else if store != nil {
-		current, err := discoverRemoteCurrentStateFn(ctx, cfg, store)
-		if err != nil {
-			fmt.Fprintf(out, "Remote archive: missing or unavailable: %v\n", err)
-		} else {
-			fmt.Fprintf(out, "Remote archive: current run %s\n", current.RunID)
-			fmt.Fprintf(out, "Remote manifest: %s\n", current.CurrentManifestKey)
-		}
-	}
-
-	locks, err := loadEffectiveLocks(ctx, cfg, store)
-	if catalog, catalogErr := buildHelperArtifactCatalog(cfg); catalogErr != nil {
-		fmt.Fprintf(out, "Remote outputs: error: %v\n", catalogErr)
-	} else if storeErr == nil {
-		catalogLocks := locks
-		if err != nil {
-			catalogLocks = &effectiveLocks{
-				Static: staticArchiveLocks(cfg),
-				All:    staticArchiveLocks(cfg),
-			}
-		}
-		promotedRemoteState := map[string]string{}
-		if store != nil {
-			promotedRemoteState = remotePromotionAvailability(ctx, cfg, store, catalog)
-		}
-		fmt.Fprintln(out, "Remote outputs:")
-		writeArtifactList(out, cfg, catalog, catalogLocks, promotedRemoteState)
-	}
-	if err != nil {
-		fmt.Fprintf(out, "Archive locks: error: %v\n", err)
-	} else {
-		writeLocks(out, cfg, locks)
-	}
-	fmt.Fprintln(out, "Next actions:")
-	fmt.Fprintf(out, "- narratio session validate --session-id %s\n", cfg.Session.SessionID)
-	fmt.Fprintf(out, "- narratio restore --session-id %s --dry-run\n", cfg.Session.SessionID)
-	return nil
-}
-
-func statusManifest(ctx context.Context, manifestPath string, out io.Writer) error {
-	store := &manifest.LocalStore{}
-	m, err := store.Load(ctx, manifestPath)
-	if err != nil {
-		return fmt.Errorf("status: %w", err)
-	}
-	if _, err := fmt.Fprintf(out, "session_id: %s\n", m.SessionID); err != nil {
-		return err
-	}
-	if _, err := fmt.Fprintf(out, "updated_at: %s\n", m.UpdatedAt.UTC().Format("2006-01-02T15:04:05Z07:00")); err != nil {
-		return err
-	}
-	writeStageStatuses(out, m)
-	return nil
-}
-
-// SessionInit creates a local or remote session.yml skeleton.
-func SessionInit(ctx context.Context, args []string, out io.Writer) error {
-	fs := flag.NewFlagSet("session init", flag.ContinueOnError)
-	fs.SetOutput(io.Discard)
-	var pipelinePath, campaignPath, sessionID, previousSessionID, date, title, output, audioS3Prefix, audioDir string
-	var remote, force bool
-	fs.StringVar(&pipelinePath, "config", "", "path to pipeline.yml")
-	fs.StringVar(&campaignPath, "campaign", "", "path to campaign.yml")
-	fs.StringVar(&sessionID, "session-id", "", "session identifier")
-	fs.StringVar(&previousSessionID, "previous-session-id", "", "previous session identifier")
-	fs.StringVar(&date, "date", "", "session date")
-	fs.StringVar(&title, "title", "", "session title")
-	fs.StringVar(&output, "output", "", "local output session.yml path")
-	fs.StringVar(&audioS3Prefix, "audio-s3-prefix", "", "session audio S3 prefix")
-	fs.StringVar(&audioDir, "audio-dir", "", "local audio directory")
-	fs.BoolVar(&remote, "remote", false, "write session.yml to S3 session prefix")
-	fs.BoolVar(&force, "force", false, "overwrite existing target")
-	if err := fs.Parse(args); err != nil {
-		return fmt.Errorf("session init: invalid flags: %w", err)
-	}
-	if fs.NArg() != 0 {
-		return fmt.Errorf("session init: unexpected positional arguments")
-	}
-	if strings.TrimSpace(pipelinePath) == "" || strings.TrimSpace(campaignPath) == "" || strings.TrimSpace(sessionID) == "" {
-		return fmt.Errorf("session init: --config, --campaign, and --session-id are required")
-	}
-	if (strings.TrimSpace(output) == "") == !remote {
-		return fmt.Errorf("session init: specify exactly one target: --output <path> or --remote")
-	}
-	if strings.TrimSpace(audioDir) != "" && strings.TrimSpace(audioS3Prefix) != "" {
-		return fmt.Errorf("session init: --audio-dir and --audio-s3-prefix are mutually exclusive")
-	}
-
-	resolvedPipeline, err := resolvePipelineConfigPath(pipelinePath)
-	if err != nil {
-		return fmt.Errorf("session init: %w", err)
-	}
-	resolvedCampaign, err := resolveCampaignConfigPath(campaignPath)
-	if err != nil {
-		return fmt.Errorf("session init: %w", err)
-	}
-	pipelineCfg, err := config.LoadPipeline(resolvedPipeline)
-	if err != nil {
-		return fmt.Errorf("session init: %w", err)
-	}
-	campaignCfg, err := config.LoadCampaign(resolvedCampaign)
-	if err != nil {
-		return fmt.Errorf("session init: %w", err)
-	}
-
-	data, err := buildSessionYAML(campaignCfg.Campaign, sessionID, previousSessionID, date, title, audioS3Prefix, audioDir)
-	if err != nil {
-		return fmt.Errorf("session init: %w", err)
-	}
-	label := strings.TrimSpace(output)
-	if label == "" {
-		label = "remote session.yml"
-	}
-	sessionCfg, err := config.LoadSessionBytesWithOptions(label, data, config.SessionLoadOptions{
-		SessionID:         sessionID,
-		PreviousSessionID: previousSessionID,
-	})
-	if err != nil {
-		return fmt.Errorf("session init: %w", err)
-	}
-	cfg, err := config.Resolve(resolvedPipeline, pipelineCfg, resolvedCampaign, campaignCfg, label, sessionCfg, config.SessionSource{Source: "session_config", LocalPath: label})
-	if err != nil {
-		return fmt.Errorf("session init: %w", err)
-	}
-	if err := config.Validate(cfg); err != nil {
-		return fmt.Errorf("session init: %w", err)
-	}
-
-	if !remote {
-		if err := writeLocalFile(output, data, force); err != nil {
-			return fmt.Errorf("session init: %w", err)
-		}
-		_, err := fmt.Fprintf(out, "narratio session init: wrote %s\n", filepath.Clean(output))
-		return err
-	}
-
-	store, err := newCommandObjectStore(ctx, cfg, nil)
-	if err != nil {
-		return fmt.Errorf("session init: %w", err)
-	}
-	sessionPrefix := artifacts.S3SessionPrefix(pipelineCfg.Storage.S3.RootPrefix, campaignCfg.Campaign, sessionID)
-	key := artifacts.S3SessionConfigKey(sessionPrefix)
-	exists, err := store.Exists(ctx, key)
-	if err != nil {
-		return fmt.Errorf("session init: check remote session %q: %w", key, err)
-	}
-	if exists && !force {
-		return fmt.Errorf("session init: remote session %q already exists; pass --force to overwrite", key)
-	}
-	tmp, err := os.CreateTemp("", "narratio-session-init-*.yml")
-	if err != nil {
-		return fmt.Errorf("session init: create temp file: %w", err)
-	}
-	tmpPath := tmp.Name()
-	defer func() { _ = os.Remove(tmpPath) }()
-	if _, err := tmp.Write(data); err != nil {
-		_ = tmp.Close()
-		return fmt.Errorf("session init: write temp file: %w", err)
-	}
-	if err := tmp.Close(); err != nil {
-		return fmt.Errorf("session init: close temp file: %w", err)
-	}
-	if _, err := store.Upload(ctx, tmpPath, key, storage.UploadOptions{ContentType: "application/x-yaml; charset=utf-8"}); err != nil {
-		return fmt.Errorf("session init: upload remote session %q: %w", key, err)
-	}
-	_, err = fmt.Fprintf(out, "narratio session init: wrote s3://%s/%s\n", s3BucketName(pipelineCfg), key)
-	return err
-}
-
-// ArtifactsList lists effective artifact sources.
-func ArtifactsList(ctx context.Context, args []string, out io.Writer) error {
-	fs := flag.NewFlagSet("artifacts list", flag.ContinueOnError)
-	fs.SetOutput(io.Discard)
-	var flags commonConfigFlags
-	var remote bool
-	addCommonConfigFlags(fs, &flags)
-	fs.BoolVar(&remote, "remote", false, "inspect remote archive availability")
-	if err := fs.Parse(args); err != nil {
-		return fmt.Errorf("artifacts list: invalid flags: %w", err)
-	}
-	if fs.NArg() != 0 {
-		return fmt.Errorf("artifacts list: unexpected positional arguments")
-	}
-	cfg, store, locks, _, err := loadHelperContext(ctx, flags, remote)
-	if err != nil {
-		return fmt.Errorf("artifacts list: %w", err)
-	}
-	catalog, err := buildHelperArtifactCatalog(cfg)
-	if err != nil {
-		return fmt.Errorf("artifacts list: %w", err)
-	}
-	promotedRemoteState := map[string]string{}
-	if remote && store != nil {
-		promotedRemoteState = remotePromotionAvailability(ctx, cfg, store, catalog)
-	}
-	writeArtifactList(out, cfg, catalog, locks, promotedRemoteState)
-	return nil
-}
-
-// Locks dispatches archive lock list and mutation helpers.
-func Locks(ctx context.Context, args []string, out io.Writer) error {
-	if len(args) > 0 && !strings.HasPrefix(args[0], "-") {
-		switch args[0] {
-		case "add":
-			return LocksAdd(ctx, args[1:], out)
-		case "remove":
-			return LocksRemove(ctx, args[1:], out)
-		default:
-			return fmt.Errorf("locks: unknown subcommand %q", args[0])
-		}
-	}
-	return LocksList(ctx, args, out)
-}
-
-// LocksList lists effective archive locks.
-func LocksList(ctx context.Context, args []string, out io.Writer) error {
-	fs := flag.NewFlagSet("locks", flag.ContinueOnError)
-	fs.SetOutput(io.Discard)
-	var flags commonConfigFlags
-	addCommonConfigFlags(fs, &flags)
-	if err := fs.Parse(args); err != nil {
-		return fmt.Errorf("locks: invalid flags: %w", err)
-	}
-	if fs.NArg() != 0 {
-		return fmt.Errorf("locks: unexpected positional arguments")
-	}
-	if strings.TrimSpace(flags.sessionID) == "" {
-		return fmt.Errorf("locks: --session-id is required")
-	}
-	cfg, _, locks, _, err := loadHelperContext(ctx, flags, true)
-	if err != nil {
-		return fmt.Errorf("locks: %w", err)
-	}
-	writeLocks(out, cfg, locks)
-	return nil
-}
-
-// LocksAdd adds or updates one remote lock.
-func LocksAdd(ctx context.Context, args []string, out io.Writer) error {
-	fs := flag.NewFlagSet("locks add", flag.ContinueOnError)
-	fs.SetOutput(io.Discard)
-	var flags commonConfigFlags
-	var reason string
-	var force bool
-	addCommonConfigFlags(fs, &flags)
-	fs.StringVar(&reason, "reason", "", "lock reason")
-	fs.BoolVar(&force, "force", false, "update existing remote lock")
-	if err := fs.Parse(args); err != nil {
-		return fmt.Errorf("locks add: invalid flags: %w", err)
-	}
-	if fs.NArg() != 1 {
-		return fmt.Errorf("locks add: expected exactly one source id")
-	}
-	if strings.TrimSpace(flags.sessionID) == "" {
-		return fmt.Errorf("locks add: --session-id is required")
-	}
-	source := strings.TrimSpace(fs.Arg(0))
-	cfg, store, locks, _, err := loadHelperContext(ctx, flags, true)
-	if err != nil {
-		return fmt.Errorf("locks add: %w", err)
-	}
-	if _, err := config.ValidateArchiveLockRules([]config.ArchiveLockRule{{Source: source}}, cfg.Pipeline.Scriptorium, "locks add"); err != nil {
-		return fmt.Errorf("locks add: %w", err)
-	}
-	if _, ok := lockSourceSet(locks.Static)[source]; ok {
-		return fmt.Errorf("locks add: source %q is locked by pipeline config and cannot be modified remotely", source)
-	}
-	remoteSet := lockSourceSet(locks.Remote)
-	if _, exists := remoteSet[source]; exists && !force {
-		return fmt.Errorf("locks add: remote lock for %q already exists; pass --force to update", source)
-	}
-	remoteSet[source] = config.ArchiveLockRule{Source: source, Reason: strings.TrimSpace(reason)}
-	remoteLocks := lockMapValues(remoteSet)
-	if _, err := config.ValidateArchiveLockRules(remoteLocks, cfg.Pipeline.Scriptorium, "locks"); err != nil {
-		return fmt.Errorf("locks add: %w", err)
-	}
-	if err := uploadRemoteLockStore(ctx, store, locks.Key, &config.ArchiveLockStore{Locks: remoteLocks}); err != nil {
-		return fmt.Errorf("locks add: %w", err)
-	}
-	_, err = fmt.Fprintf(out, "narratio locks add: locked %s\n", source)
-	return err
-}
-
-// LocksRemove removes one remote lock.
-func LocksRemove(ctx context.Context, args []string, out io.Writer) error {
-	fs := flag.NewFlagSet("locks remove", flag.ContinueOnError)
-	fs.SetOutput(io.Discard)
-	var flags commonConfigFlags
-	addCommonConfigFlags(fs, &flags)
-	if err := fs.Parse(args); err != nil {
-		return fmt.Errorf("locks remove: invalid flags: %w", err)
-	}
-	if fs.NArg() != 1 {
-		return fmt.Errorf("locks remove: expected exactly one source id")
-	}
-	if strings.TrimSpace(flags.sessionID) == "" {
-		return fmt.Errorf("locks remove: --session-id is required")
-	}
-	source := strings.TrimSpace(fs.Arg(0))
-	cfg, store, locks, _, err := loadHelperContext(ctx, flags, true)
-	if err != nil {
-		return fmt.Errorf("locks remove: %w", err)
-	}
-	if _, err := config.ValidateArchiveLockRules([]config.ArchiveLockRule{{Source: source}}, cfg.Pipeline.Scriptorium, "locks remove"); err != nil {
-		return fmt.Errorf("locks remove: %w", err)
-	}
-	remoteSet := lockSourceSet(locks.Remote)
-	if _, ok := remoteSet[source]; !ok {
-		if _, static := lockSourceSet(locks.Static)[source]; static {
-			return fmt.Errorf("locks remove: source %q is locked by pipeline config and cannot be unlocked remotely", source)
-		}
-		return fmt.Errorf("locks remove: remote lock for %q does not exist", source)
-	}
-	delete(remoteSet, source)
-	remoteLocks := lockMapValues(remoteSet)
-	if err := uploadRemoteLockStore(ctx, store, locks.Key, &config.ArchiveLockStore{Locks: remoteLocks}); err != nil {
-		return fmt.Errorf("locks remove: %w", err)
-	}
-	_, err = fmt.Fprintf(out, "narratio locks remove: unlocked %s\n", source)
-	return err
-}
-
 func loadHelperContext(ctx context.Context, flags commonConfigFlags, needStore bool) (*config.Config, storage.ObjectStore, *effectiveLocks, *manifest.Manifest, error) {
-	cfg, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.sessionPath, flags.sessionOptions())
+	cfg, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.campaignFilePath, flags.sessionPath, flags.sessionOptions())
 	if err != nil {
 		return nil, nil, nil, nil, err
 	}
@@ -558,401 +129,3 @@ func objectStoreIfConfigured(ctx context.Context, cfg *config.Config) (storage.O
 	}
 	return store, nil
 }
-
-func buildSessionYAML(campaign, sessionID, previousSessionID, date, title, audioS3Prefix, audioDir string) ([]byte, error) {
-	if strings.TrimSpace(date) == "" && regexp.MustCompile(`^\d{4}-\d{2}-\d{2}$`).MatchString(strings.TrimSpace(sessionID)) {
-		date = strings.TrimSpace(sessionID)
-	}
-	type audioS3 struct {
-		Prefix string `yaml:"prefix"`
-	}
-	type inputs struct {
-		AudioDir string   `yaml:"audio_dir,omitempty"`
-		AudioS3  *audioS3 `yaml:"audio_s3,omitempty"`
-	}
-	type sessionYAML struct {
-		Campaign          string `yaml:"campaign"`
-		SessionID         string `yaml:"session_id"`
-		PreviousSessionID string `yaml:"previous_session_id,omitempty"`
-		Date              string `yaml:"date,omitempty"`
-		Title             string `yaml:"title,omitempty"`
-		Inputs            inputs `yaml:"inputs"`
-	}
-	in := inputs{AudioDir: strings.TrimSpace(audioDir)}
-	if in.AudioDir == "" {
-		prefix := strings.TrimSpace(audioS3Prefix)
-		if prefix == "" {
-			prefix = "audio/"
-		}
-		in.AudioS3 = &audioS3{Prefix: prefix}
-	}
-	data, err := yaml.Marshal(sessionYAML{
-		Campaign:          strings.TrimSpace(campaign),
-		SessionID:         strings.TrimSpace(sessionID),
-		PreviousSessionID: strings.TrimSpace(previousSessionID),
-		Date:              strings.TrimSpace(date),
-		Title:             strings.TrimSpace(title),
-		Inputs:            in,
-	})
-	if err != nil {
-		return nil, err
-	}
-	return data, nil
-}
-
-func renderFindings(out io.Writer, campaign, sessionID string, findings []finding) error {
-	if campaign != "" || sessionID != "" {
-		fmt.Fprintf(out, "Campaign: %s\n", campaign)
-		fmt.Fprintf(out, "Session: %s\n\n", sessionID)
-	}
-	errorsCount := 0
-	for _, f := range findings {
-		if f.Severity == "ERROR" {
-			errorsCount++
-		}
-		fmt.Fprintf(out, "%-5s %-10s %s\n", f.Severity, f.Category, f.Message)
-	}
-	if errorsCount > 0 {
-		return findingError{count: errorsCount}
-	}
-	return nil
-}
-
-func okFinding(category, msg string) finding    { return finding{"OK", category, msg} }
-func infoFinding(category, msg string) finding  { return finding{"INFO", category, msg} }
-func warnFinding(category, msg string) finding  { return finding{"WARN", category, msg} }
-func errorFinding(category, msg string) finding { return finding{"ERROR", category, msg} }
-
-func sessionSourceSummary(cfg *config.Config) string {
-	source := cfg.SessionSource.Source
-	if source == "" {
-		source = "session_config"
-	}
-	if cfg.SessionSource.S3Key != "" {
-		return source + " " + cfg.SessionSource.S3Key
-	}
-	return source + " " + cfg.SessionPath
-}
-
-func validateStableInputFindings(cfg *config.Config) []finding {
-	items := []struct {
-		name string
-		in   config.ResolvedInputFile
-	}{
-		{"speakers", cfg.StableInputs.SpeakersFile},
-		{"autocorrect", cfg.StableInputs.AutocorrectFile},
-		{"glossary", cfg.StableInputs.GlossaryFile},
-	}
-	out := make([]finding, 0, len(items))
-	for _, item := range items {
-		path, err := resolveHelperConfigRelativePath(item.in)
-		if err != nil {
-			out = append(out, errorFinding("inputs", item.name+": "+err.Error()))
-			continue
-		}
-		if _, err := os.Stat(path); err != nil {
-			out = append(out, errorFinding("inputs", fmt.Sprintf("%s missing: %v", item.name, err)))
-		} else {
-			out = append(out, okFinding("inputs", item.name+": "+path))
-		}
-	}
-	return out
-}
-
-func resolveHelperConfigRelativePath(input config.ResolvedInputFile) (string, error) {
-	if strings.TrimSpace(input.ConfigPath) == "" {
-		return "", fmt.Errorf("source config path is required")
-	}
-	path := strings.TrimSpace(input.Path)
-	if path == "" {
-		return "", fmt.Errorf("path is required")
-	}
-	if filepath.IsAbs(path) {
-		return filepath.Clean(path), nil
-	}
-	return filepath.Clean(filepath.Join(filepath.Dir(input.ConfigPath), path)), nil
-}
-
-func validateLocalAudioFindings(cfg *config.Config) []finding {
-	if cfg.Session.Inputs.AudioS3 != nil {
-		return nil
-	}
-	audioDir := strings.TrimSpace(cfg.Session.Inputs.AudioDir)
-	if audioDir == "" && len(cfg.Session.Inputs.AudioFiles) == 0 {
-		return []finding{errorFinding("audio", "audio_dir, audio_files, or audio_s3 is required")}
-	}
-	base := filepath.Dir(cfg.SessionPath)
-	paths := []string{}
-	if audioDir != "" {
-		dir := audioDir
-		if !filepath.IsAbs(dir) {
-			dir = filepath.Join(base, dir)
-		}
-		matches, err := filepath.Glob(filepath.Join(dir, "*.flac"))
-		if err != nil || len(matches) == 0 {
-			return []finding{errorFinding("audio", "no .flac files found in "+dir)}
-		}
-		paths = append(paths, matches...)
-	}
-	for _, file := range cfg.Session.Inputs.AudioFiles {
-		p := file
-		if !filepath.IsAbs(p) {
-			p = filepath.Join(base, p)
-		}
-		paths = append(paths, p)
-	}
-	for _, p := range paths {
-		if _, err := os.Stat(p); err != nil {
-			return []finding{errorFinding("audio", fmt.Sprintf("audio file missing: %v", err))}
-		}
-	}
-	return []finding{okFinding("audio", fmt.Sprintf("%d local audio file(s)", len(paths)))}
-}
-
-func validateRemoteAudioFinding(ctx context.Context, cfg *config.Config, store storage.ObjectStore) finding {
-	sessionPrefix := artifacts.S3SessionPrefix(cfg.Pipeline.Storage.S3.RootPrefix, cfg.Session.Campaign, cfg.Session.SessionID)
-	audioPrefix := artifacts.S3AudioPrefix(sessionPrefix, cfg.Session.Inputs.AudioS3.Prefix)
-	objects, err := store.List(ctx, audioPrefix)
-	if err != nil {
-		return errorFinding("audio", err.Error())
-	}
-	count := 0
-	for _, obj := range objects {
-		if strings.HasSuffix(strings.ToLower(obj.Key), ".flac") {
-			count++
-		}
-	}
-	if count == 0 {
-		return errorFinding("audio", "no remote .flac objects found under "+audioPrefix)
-	}
-	return okFinding("audio", fmt.Sprintf("%d remote .flac object(s)", count))
-}
-
-func validatePreviousArtifactFindings(ctx context.Context, cfg *config.Config, store storage.ObjectStore, requirements []artifacts.PreviousArtifactRequirement) []finding {
-	out := []finding{}
-	prefix := artifacts.S3SessionPrefix(cfg.Pipeline.Storage.S3.RootPrefix, cfg.Session.Campaign, cfg.Session.PreviousSessionID)
-	manifestKey, runIDKey := artifacts.ResolveArchiveCurrentStateKeys(prefix)
-	for _, key := range []string{runIDKey, manifestKey} {
-		exists, err := store.Exists(ctx, key)
-		if err != nil {
-			out = append(out, errorFinding("previous", fmt.Sprintf("check %s: %v", key, err)))
-			return out
-		}
-		if !exists {
-			out = append(out, errorFinding("previous", "missing "+key))
-			return out
-		}
-	}
-	for _, req := range requirements {
-		out = append(out, okFinding("previous", fmt.Sprintf("%s required=%t", req.Name, req.Required)))
-	}
-	return out
-}
-
-func loadLocalManifest(ctx context.Context, path string) (*manifest.Manifest, error) {
-	if _, err := os.Stat(path); err != nil {
-		if os.IsNotExist(err) {
-			return nil, nil
-		}
-		return nil, err
-	}
-	store := &manifest.LocalStore{}
-	return store.Load(ctx, path)
-}
-
-func writeStageStatuses(out io.Writer, m *manifest.Manifest) {
-	if m == nil || len(m.Stages) == 0 {
-		fmt.Fprintln(out, "stages: no stages recorded")
-		return
-	}
-	fmt.Fprintln(out, "stages:")
-	names := make([]string, 0, len(m.Stages))
-	for name := range m.Stages {
-		names = append(names, name)
-	}
-	sort.Strings(names)
-	for _, name := range names {
-		fmt.Fprintf(out, "- %s: %s\n", name, m.Stages[name].Status)
-	}
-}
-
-func buildHelperArtifactCatalog(cfg *config.Config) (*artifacts.ArtifactCatalog, error) {
-	catalog := artifacts.NewArtifactCatalog()
-	if err := catalog.RegisterBuiltIns(); err != nil {
-		return nil, err
-	}
-	configured := map[string]artifacts.ConfiguredArtifactDefinition{}
-	if cfg.Pipeline.Scriptorium != nil {
-		for key, item := range cfg.Pipeline.Scriptorium.Artifacts {
-			configured[key] = artifacts.ConfiguredArtifactDefinition{Enabled: item.Enabled, OutputPath: item.OutputPath}
-		}
-	}
-	if err := catalog.RegisterConfiguredArtifacts(configured, nil); err != nil {
-		return nil, err
-	}
-	return catalog, nil
-}
-
-func writeArtifactList(out io.Writer, cfg *config.Config, catalog *artifacts.ArtifactCatalog, locks *effectiveLocks, promotedRemoteState map[string]string) {
-	lockSet := lockSourceSet(locks.All)
-	fmt.Fprintln(out, "Built-in:")
-	for _, id := range []string{
-		artifacts.ArtifactTranscriptMerged,
-		artifacts.ArtifactTranscriptPolished,
-		artifacts.ArtifactTranscriptFull,
-		artifacts.ArtifactTranscriptTrimmed,
-		artifacts.ArtifactBoundsSession,
-	} {
-		writeArtifactLine(out, id, lockSet)
-	}
-	fmt.Fprintln(out, "Configured:")
-	for _, entry := range catalog.ListConfigured() {
-		writeArtifactLine(out, entry.SourceID, lockSet)
-	}
-	fmt.Fprintln(out, "Previous-session:")
-	for _, req := range artifacts.CollectPreviousArtifactRequirements(configuredScriptoriumArtifacts(cfg)) {
-		fmt.Fprintf(out, "- narratio.previous_session.artifact.%s required=%t\n", req.Name, req.Required)
-	}
-	fmt.Fprintln(out, "Promoted:")
-	for _, rule := range cfg.Pipeline.Archive.PromoteArtifacts {
-		writePromotedArtifactLine(out, rule, catalog, lockSet, promotedRemoteState)
-	}
-}
-
-func writeArtifactLine(out io.Writer, source string, lockSet map[string]config.ArchiveLockRule) {
-	parts := []string{source}
-	if _, ok := lockSet[source]; ok {
-		parts = append(parts, "locked")
-	}
-	fmt.Fprintf(out, "- %s\n", strings.Join(parts, " "))
-}
-
-func writePromotedArtifactLine(out io.Writer, rule config.ArchivePromotionRule, catalog *artifacts.ArtifactCatalog, lockSet map[string]config.ArchiveLockRule, remoteState map[string]string) {
-	source := strings.TrimSpace(rule.Source)
-	parts := []string{source}
-	if _, ok := lockSet[source]; ok {
-		parts = append(parts, "locked")
-	}
-	dest, showDest, err := helperPromotionDest(rule, catalog)
-	if err != nil {
-		parts = append(parts, "remote=error")
-		fmt.Fprintf(out, "- %s\n", strings.Join(parts, " "))
-		return
-	}
-	if showDest {
-		parts = append(parts, "dest="+dest)
-	}
-	if state := remoteState[promotionRemoteStateKey(source, dest)]; state != "" {
-		parts = append(parts, state)
-	}
-	fmt.Fprintf(out, "- %s\n", strings.Join(parts, " "))
-}
-
-func remotePromotionAvailability(ctx context.Context, cfg *config.Config, store storage.ObjectStore, catalog *artifacts.ArtifactCatalog) map[string]string {
-	out := map[string]string{}
-	sessionPrefix := artifacts.S3SessionPrefix(cfg.Pipeline.Storage.S3.RootPrefix, cfg.Session.Campaign, cfg.Session.SessionID)
-	for _, rule := range cfg.Pipeline.Archive.PromoteArtifacts {
-		source := strings.TrimSpace(rule.Source)
-		dest, _, err := helperPromotionDest(rule, catalog)
-		if err != nil {
-			out[promotionRemoteStateKey(source, "")] = "remote=error"
-			continue
-		}
-		key := artifacts.S3PromotedArtifactKey(sessionPrefix, dest)
-		if exists, err := store.Exists(ctx, key); err == nil && exists {
-			out[promotionRemoteStateKey(source, dest)] = "remote=promoted"
-		} else if err != nil {
-			out[promotionRemoteStateKey(source, dest)] = "remote=error"
-		} else {
-			out[promotionRemoteStateKey(source, dest)] = "remote=missing"
-		}
-	}
-	return out
-}
-
-func helperPromotionDest(rule config.ArchivePromotionRule, catalog *artifacts.ArtifactCatalog) (string, bool, error) {
-	source := strings.TrimSpace(rule.Source)
-	dest := strings.TrimSpace(rule.Dest)
-	if dest == "" {
-		entry, ok := catalog.Lookup(source)
-		if !ok {
-			return "", false, fmt.Errorf("destination omitted and source is unknown")
-		}
-		dest = strings.TrimSpace(entry.CanonicalRelPath)
-		if dest == "" {
-			return "", false, fmt.Errorf("destination omitted and no canonical destination is available")
-		}
-	}
-	normalized, err := normalizeHelperArchiveRelativePath(dest)
-	if err != nil {
-		return "", false, err
-	}
-	entry, ok := catalog.Lookup(source)
-	showDest := !ok || strings.TrimSpace(entry.CanonicalRelPath) != normalized
-	return normalized, showDest, nil
-}
-
-func normalizeHelperArchiveRelativePath(rel string) (string, error) {
-	trimmed := strings.TrimSpace(rel)
-	if trimmed == "" {
-		return "", fmt.Errorf("relative path is required")
-	}
-	cleaned := filepath.ToSlash(filepath.Clean(filepath.FromSlash(trimmed)))
-	if cleaned == "." || cleaned == "" {
-		return "", fmt.Errorf("relative path is required")
-	}
-	if filepath.IsAbs(trimmed) || strings.HasPrefix(cleaned, "/") || cleaned == ".." || strings.HasPrefix(cleaned, "../") {
-		return "", fmt.Errorf("path must be a clean relative path")
-	}
-	return cleaned, nil
-}
-
-func promotionRemoteStateKey(source, dest string) string {
-	return strings.TrimSpace(source) + "\x00" + strings.TrimSpace(dest)
-}
-
-func writeLocks(out io.Writer, cfg *config.Config, locks *effectiveLocks) {
-	if locks == nil || len(locks.All) == 0 {
-		fmt.Fprintln(out, "Archive locks: none")
-		return
-	}
-	fmt.Fprintln(out, "Archive locks:")
-	promoted := map[string]config.ArchivePromotionRule{}
-	if cfg != nil && cfg.Pipeline != nil && cfg.Pipeline.Archive != nil {
-		for _, rule := range cfg.Pipeline.Archive.PromoteArtifacts {
-			promoted[strings.TrimSpace(rule.Source)] = rule
-		}
-	}
-	staticSet := lockSourceSet(locks.Static)
-	for _, lock := range locks.All {
-		origin := "remote"
-		if _, ok := staticSet[lock.Source]; ok {
-			origin = "pipeline"
-		}
-		promo := "not-promoted"
-		if _, ok := promoted[lock.Source]; ok {
-			promo = "promoted"
-		}
-		reason := strings.TrimSpace(lock.Reason)
-		if reason == "" {
-			reason = "(no reason)"
-		}
-		fmt.Fprintf(out, "- %s origin=%s %s reason=%s\n", lock.Source, origin, promo, reason)
-	}
-}
-
-func lockMapValues(in map[string]config.ArchiveLockRule) []config.ArchiveLockRule {
-	keys := make([]string, 0, len(in))
-	for key := range in {
-		keys = append(keys, key)
-	}
-	sort.Strings(keys)
-	out := make([]config.ArchiveLockRule, 0, len(keys))
-	for _, key := range keys {
-		item := in[key]
-		item.Source = key
-		item.Reason = strings.TrimSpace(item.Reason)
-		out = append(out, item)
-	}
-	return out
-}

internal/app/operator_inspection.go

@@ -0,0 +1,274 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+)
+
+type stableInputCheck struct {
+	Name string
+	Path string
+	Err  error
+}
+
+type localAudioCheck struct {
+	Checked bool
+	Paths   []string
+	Err     error
+}
+
+type remoteAudioCheck struct {
+	Checked bool
+	Prefix  string
+	Keys    []string
+	Err     error
+}
+
+type previousArtifactReadiness struct {
+	Requirements []artifacts.PreviousArtifactRequirement
+	MissingID    bool
+	Err          error
+}
+
+type remoteCurrentStateCheck struct {
+	State *RemoteCurrentState
+	Err   error
+}
+
+type effectiveLocksCheck struct {
+	Locks *effectiveLocks
+	Err   error
+}
+
+func inspectStableInputs(cfg *config.Config) []stableInputCheck {
+	items := []struct {
+		name string
+		in   config.ResolvedInputFile
+	}{
+		{name: "speakers", in: cfg.StableInputs.SpeakersFile},
+		{name: "autocorrect", in: cfg.StableInputs.AutocorrectFile},
+		{name: "glossary", in: cfg.StableInputs.GlossaryFile},
+	}
+	out := make([]stableInputCheck, 0, len(items))
+	for _, item := range items {
+		path, err := resolveHelperConfigRelativePath(item.in)
+		if err != nil {
+			out = append(out, stableInputCheck{Name: item.name, Err: err})
+			continue
+		}
+		if _, err := os.Stat(path); err != nil {
+			out = append(out, stableInputCheck{Name: item.name, Path: path, Err: err})
+			continue
+		}
+		out = append(out, stableInputCheck{Name: item.name, Path: path})
+	}
+	return out
+}
+
+func inspectLocalAudioPresence(cfg *config.Config) localAudioCheck {
+	if cfg.Session.Inputs.AudioS3 != nil {
+		return localAudioCheck{}
+	}
+
+	sessionDir := filepath.Dir(cfg.SessionPath)
+	resolved, err := resolveLocalInspectionAudioPaths(sessionDir, cfg.Session.Inputs)
+	if err != nil {
+		return localAudioCheck{Checked: true, Err: err}
+	}
+	return localAudioCheck{
+		Checked: true,
+		Paths:   resolved,
+	}
+}
+
+func inspectRemoteAudioPresence(ctx context.Context, cfg *config.Config, store storage.ObjectStore) remoteAudioCheck {
+	if cfg.Session.Inputs.AudioS3 == nil {
+		return remoteAudioCheck{}
+	}
+	if store == nil {
+		return remoteAudioCheck{Checked: true, Err: fmt.Errorf("storage backend is required for remote audio checks")}
+	}
+
+	sessionPrefix := artifacts.S3SessionPrefix(cfg.Pipeline.Storage.S3.RootPrefix, cfg.Session.Campaign, cfg.Session.SessionID)
+	audioPrefix := artifacts.S3AudioPrefix(sessionPrefix, cfg.Session.Inputs.AudioS3.Prefix)
+	objects, err := store.List(ctx, audioPrefix)
+	if err != nil {
+		return remoteAudioCheck{Checked: true, Prefix: audioPrefix, Err: err}
+	}
+
+	keys := make([]string, 0, len(objects))
+	seenBase := map[string]string{}
+	for _, obj := range objects {
+		key := strings.TrimSpace(obj.Key)
+		if key == "" || strings.HasSuffix(key, "/") || !isInspectionFlacPath(key) {
+			continue
+		}
+		base := path.Base(key)
+		if prev, exists := seenBase[base]; exists && prev != key {
+			return remoteAudioCheck{
+				Checked: true,
+				Prefix:  audioPrefix,
+				Err:     fmt.Errorf("duplicate s3 audio basename %q from %q and %q", base, prev, key),
+			}
+		}
+		seenBase[base] = key
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	if len(keys) == 0 {
+		return remoteAudioCheck{
+			Checked: true,
+			Prefix:  audioPrefix,
+			Err:     fmt.Errorf("no .flac files found under s3 audio prefix %q", audioPrefix),
+		}
+	}
+	return remoteAudioCheck{
+		Checked: true,
+		Prefix:  audioPrefix,
+		Keys:    keys,
+	}
+}
+
+func inspectPreviousArtifactReadiness(
+	ctx context.Context,
+	cfg *config.Config,
+	store storage.ObjectStore,
+	requirements []artifacts.PreviousArtifactRequirement,
+) previousArtifactReadiness {
+	out := previousArtifactReadiness{
+		Requirements: append([]artifacts.PreviousArtifactRequirement(nil), requirements...),
+	}
+	if len(requirements) == 0 {
+		return out
+	}
+	if strings.TrimSpace(cfg.Session.PreviousSessionID) == "" {
+		out.MissingID = true
+		return out
+	}
+	if store == nil {
+		out.Err = fmt.Errorf("previous-session artifacts cannot be checked because storage is unavailable")
+		return out
+	}
+
+	prefix := artifacts.S3SessionPrefix(cfg.Pipeline.Storage.S3.RootPrefix, cfg.Session.Campaign, cfg.Session.PreviousSessionID)
+	if _, err := artifacts.LoadCurrentState(ctx, store, prefix, artifacts.CurrentStateValidation{
+		ExpectedSessionID: strings.TrimSpace(cfg.Session.PreviousSessionID),
+		ExpectedCampaign:  strings.TrimSpace(cfg.Session.Campaign),
+		ValidateRunID:     true,
+	}); err != nil {
+		out.Err = fmt.Errorf("remote %v", err)
+	}
+	return out
+}
+
+func inspectRemoteCurrentState(ctx context.Context, cfg *config.Config, store storage.ObjectStore) remoteCurrentStateCheck {
+	if store == nil {
+		return remoteCurrentStateCheck{}
+	}
+	current, err := discoverRemoteCurrentStateFn(ctx, cfg, store)
+	if err != nil {
+		return remoteCurrentStateCheck{Err: err}
+	}
+	return remoteCurrentStateCheck{State: current}
+}
+
+func inspectEffectiveLocks(ctx context.Context, cfg *config.Config, store storage.ObjectStore) effectiveLocksCheck {
+	locks, err := loadEffectiveLocks(ctx, cfg, store)
+	if err != nil {
+		return effectiveLocksCheck{Err: err}
+	}
+	return effectiveLocksCheck{Locks: locks}
+}
+
+func resolveLocalInspectionAudioPaths(sessionDir string, inputs config.SessionInputsConfig) ([]string, error) {
+	if len(inputs.AudioFiles) > 0 {
+		out := make([]string, 0, len(inputs.AudioFiles))
+		seenBase := map[string]string{}
+		for _, item := range inputs.AudioFiles {
+			resolved, err := resolveInspectionPath(sessionDir, item)
+			if err != nil {
+				return nil, err
+			}
+			if !isInspectionFlacPath(resolved) {
+				return nil, fmt.Errorf("audio file %q must have .flac extension", resolved)
+			}
+			if err := requireInspectionFile(resolved, "audio file"); err != nil {
+				return nil, err
+			}
+			base := filepath.Base(resolved)
+			if prev, exists := seenBase[base]; exists && prev != resolved {
+				return nil, fmt.Errorf("duplicate audio basename %q from %q and %q", base, prev, resolved)
+			}
+			seenBase[base] = resolved
+			out = append(out, resolved)
+		}
+		sort.Strings(out)
+		return out, nil
+	}
+
+	audioDir, err := resolveInspectionPath(sessionDir, inputs.AudioDir)
+	if err != nil {
+		return nil, err
+	}
+	entries, err := os.ReadDir(audioDir)
+	if err != nil {
+		return nil, fmt.Errorf("read audio directory %q: %w", audioDir, err)
+	}
+	out := make([]string, 0, len(entries))
+	for _, entry := range entries {
+		if entry.IsDir() {
+			continue
+		}
+		full := filepath.Join(audioDir, entry.Name())
+		if !isInspectionFlacPath(full) {
+			continue
+		}
+		if err := requireInspectionFile(full, "audio file"); err != nil {
+			return nil, err
+		}
+		out = append(out, full)
+	}
+	if len(out) == 0 {
+		return nil, fmt.Errorf("no .flac files found in audio directory %q", audioDir)
+	}
+	sort.Strings(out)
+	return out, nil
+}
+
+func resolveInspectionPath(baseDir, inputPath string) (string, error) {
+	pathValue := strings.TrimSpace(inputPath)
+	if pathValue == "" {
+		return "", fmt.Errorf("path is required")
+	}
+	if filepath.IsAbs(pathValue) {
+		return filepath.Clean(pathValue), nil
+	}
+	return filepath.Clean(filepath.Join(baseDir, pathValue)), nil
+}
+
+func requireInspectionFile(path, label string) error {
+	info, err := os.Stat(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return fmt.Errorf("%s %q does not exist", label, path)
+		}
+		return fmt.Errorf("stat %s %q: %w", label, path, err)
+	}
+	if info.IsDir() {
+		return fmt.Errorf("%s %q is a directory", label, path)
+	}
+	return nil
+}
+
+func isInspectionFlacPath(path string) bool {
+	return strings.EqualFold(filepath.Ext(strings.TrimSpace(path)), ".flac")
+}

internal/app/operator_locks.go

@@ -0,0 +1,172 @@
+package app
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"io"
+	"sort"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+)
+
+// Locks dispatches publish lock list and mutation helpers.
+func Locks(ctx context.Context, args []string, out io.Writer) error {
+	if len(args) > 0 && !strings.HasPrefix(args[0], "-") {
+		switch args[0] {
+		case "add":
+			return LocksAdd(ctx, args[1:], out)
+		case "remove":
+			return LocksRemove(ctx, args[1:], out)
+		default:
+			return fmt.Errorf("locks: unknown subcommand %q", args[0])
+		}
+	}
+	return LocksList(ctx, args, out)
+}
+
+// LocksList lists effective publish locks.
+func LocksList(ctx context.Context, args []string, out io.Writer) error {
+	fs := flag.NewFlagSet("locks", flag.ContinueOnError)
+	fs.SetOutput(io.Discard)
+	var flags commonConfigFlags
+	addCommonConfigFlags(fs, &flags)
+	if err := parseSessionAwareFlags("locks", fs, args, &flags.sessionID); err != nil {
+		return err
+	}
+	if strings.TrimSpace(flags.sessionID) == "" {
+		return fmt.Errorf("locks: session_id is required")
+	}
+	cfg, _, locks, _, err := loadHelperContext(ctx, flags, true)
+	if err != nil {
+		return fmt.Errorf("locks: %w", err)
+	}
+	writeLocks(out, cfg, locks)
+	return nil
+}
+
+// LocksAdd adds or updates one remote lock.
+func LocksAdd(ctx context.Context, args []string, out io.Writer) error {
+	fs := flag.NewFlagSet("locks add", flag.ContinueOnError)
+	fs.SetOutput(io.Discard)
+	var flags commonConfigFlags
+	var reason string
+	var force bool
+	addCommonConfigFlags(fs, &flags)
+	fs.StringVar(&reason, "reason", "", "lock reason")
+	fs.BoolVar(&force, "force", false, "update existing remote lock")
+	source, err := parseSessionIDAndOnePositionalArg("locks add", "source id", fs, args, &flags.sessionID)
+	if err != nil {
+		return err
+	}
+	if strings.TrimSpace(flags.sessionID) == "" {
+		return fmt.Errorf("locks add: session_id is required")
+	}
+	cfg, store, locks, _, err := loadHelperContext(ctx, flags, true)
+	if err != nil {
+		return fmt.Errorf("locks add: %w", err)
+	}
+	if _, err := config.ValidatePublishLockRules([]config.PublishLockRule{{Source: source}}, cfg.Pipeline.Scriptorium, "locks add"); err != nil {
+		return fmt.Errorf("locks add: %w", err)
+	}
+	if _, ok := lockSourceSet(locks.Static)[source]; ok {
+		return fmt.Errorf("locks add: source %q is locked by pipeline config and cannot be modified remotely", source)
+	}
+	remoteSet := lockSourceSet(locks.Remote)
+	if _, exists := remoteSet[source]; exists && !force {
+		return fmt.Errorf("locks add: remote lock for %q already exists; pass --force to update", source)
+	}
+	remoteSet[source] = config.PublishLockRule{Source: source, Reason: strings.TrimSpace(reason)}
+	remoteLocks := lockMapValues(remoteSet)
+	if _, err := config.ValidatePublishLockRules(remoteLocks, cfg.Pipeline.Scriptorium, "locks"); err != nil {
+		return fmt.Errorf("locks add: %w", err)
+	}
+	if err := uploadRemoteLockStore(ctx, store, locks.Key, &config.PublishLockStore{Locks: remoteLocks}); err != nil {
+		return fmt.Errorf("locks add: %w", err)
+	}
+	_, err = fmt.Fprintf(out, "narratio session locks add: locked %s\n", source)
+	return err
+}
+
+// LocksRemove removes one remote lock.
+func LocksRemove(ctx context.Context, args []string, out io.Writer) error {
+	fs := flag.NewFlagSet("locks remove", flag.ContinueOnError)
+	fs.SetOutput(io.Discard)
+	var flags commonConfigFlags
+	addCommonConfigFlags(fs, &flags)
+	source, err := parseSessionIDAndOnePositionalArg("locks remove", "source id", fs, args, &flags.sessionID)
+	if err != nil {
+		return err
+	}
+	if strings.TrimSpace(flags.sessionID) == "" {
+		return fmt.Errorf("locks remove: session_id is required")
+	}
+	cfg, store, locks, _, err := loadHelperContext(ctx, flags, true)
+	if err != nil {
+		return fmt.Errorf("locks remove: %w", err)
+	}
+	if _, err := config.ValidatePublishLockRules([]config.PublishLockRule{{Source: source}}, cfg.Pipeline.Scriptorium, "locks remove"); err != nil {
+		return fmt.Errorf("locks remove: %w", err)
+	}
+	remoteSet := lockSourceSet(locks.Remote)
+	if _, ok := remoteSet[source]; !ok {
+		if _, static := lockSourceSet(locks.Static)[source]; static {
+			return fmt.Errorf("locks remove: source %q is locked by pipeline config and cannot be unlocked remotely", source)
+		}
+		return fmt.Errorf("locks remove: remote lock for %q does not exist", source)
+	}
+	delete(remoteSet, source)
+	remoteLocks := lockMapValues(remoteSet)
+	if err := uploadRemoteLockStore(ctx, store, locks.Key, &config.PublishLockStore{Locks: remoteLocks}); err != nil {
+		return fmt.Errorf("locks remove: %w", err)
+	}
+	_, err = fmt.Fprintf(out, "narratio session locks remove: unlocked %s\n", source)
+	return err
+}
+
+func writeLocks(out io.Writer, cfg *config.Config, locks *effectiveLocks) {
+	if locks == nil || len(locks.All) == 0 {
+		fmt.Fprintln(out, "Publish locks: none")
+		return
+	}
+	fmt.Fprintln(out, "Publish locks:")
+	published := map[string]config.PublishOutputRule{}
+	if cfg != nil && cfg.Pipeline != nil && cfg.Pipeline.Publish != nil {
+		for _, rule := range cfg.Pipeline.Publish.Outputs {
+			published[strings.TrimSpace(rule.Source)] = rule
+		}
+	}
+	staticSet := lockSourceSet(locks.Static)
+	for _, lock := range locks.All {
+		origin := "remote"
+		if _, ok := staticSet[lock.Source]; ok {
+			origin = "pipeline"
+		}
+		promo := "not-published"
+		if _, ok := published[lock.Source]; ok {
+			promo = "published"
+		}
+		reason := strings.TrimSpace(lock.Reason)
+		if reason == "" {
+			reason = "(no reason)"
+		}
+		fmt.Fprintf(out, "- %s origin=%s %s reason=%s\n", lock.Source, origin, promo, reason)
+	}
+}
+
+func lockMapValues(in map[string]config.PublishLockRule) []config.PublishLockRule {
+	keys := make([]string, 0, len(in))
+	for key := range in {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	out := make([]config.PublishLockRule, 0, len(keys))
+	for _, key := range keys {
+		item := in[key]
+		item.Source = key
+		item.Reason = strings.TrimSpace(item.Reason)
+		out = append(out, item)
+	}
+	return out
+}

internal/app/operator_session_init.go

@@ -0,0 +1,268 @@
+package app
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gopkg.in/yaml.v3"
+)
+
+// SessionInit creates a local or remote session.yml skeleton.
+func SessionInit(ctx context.Context, args []string, out io.Writer) error {
+	fs := flag.NewFlagSet("session init", flag.ContinueOnError)
+	fs.SetOutput(io.Discard)
+	var pipelinePath, campaignPath, campaignFilePath, sessionID, previousSessionID, date, title, output, audioS3Prefix, audioDir string
+	var remote, force bool
+	fs.StringVar(&pipelinePath, "config", "", "path to pipeline.yml (optional; defaults searched)")
+	fs.StringVar(&campaignPath, "campaign", "", "campaign ID")
+	fs.StringVar(&campaignFilePath, "campaign-file", "", "path to campaign.yml")
+	fs.StringVar(&sessionID, "session-id", "", "session identifier")
+	fs.StringVar(&previousSessionID, "previous-session-id", "", "previous session identifier")
+	fs.StringVar(&date, "date", "", "session date")
+	fs.StringVar(&title, "title", "", "session title")
+	fs.StringVar(&output, "output", "", "local output session.yml path")
+	fs.StringVar(&audioS3Prefix, "audio-s3-prefix", "", "session audio S3 prefix")
+	fs.StringVar(&audioDir, "audio-dir", "", "local audio directory")
+	fs.BoolVar(&remote, "remote", false, "write session.yml to S3 session prefix")
+	fs.BoolVar(&force, "force", false, "overwrite existing target")
+	if err := parseSessionAwareFlags("session init", fs, args, &sessionID); err != nil {
+		return err
+	}
+	if strings.TrimSpace(sessionID) == "" {
+		return fmt.Errorf("session init: session_id is required")
+	}
+	if (strings.TrimSpace(output) == "") == !remote {
+		return fmt.Errorf("session init: specify exactly one target: --output <path> or --remote")
+	}
+	if strings.TrimSpace(audioDir) != "" && strings.TrimSpace(audioS3Prefix) != "" {
+		return fmt.Errorf("session init: --audio-dir and --audio-s3-prefix are mutually exclusive")
+	}
+
+	base, err := loadPipelineCampaignConfig(pipelinePath, campaignPath, campaignFilePath)
+	if err != nil {
+		return fmt.Errorf("session init: %w", err)
+	}
+
+	input := sessionInitInput{
+		Campaign:          config.CampaignID(base.Campaign),
+		CampaignPath:      base.CampaignPath,
+		TemplateFile:      base.Campaign.SessionTemplateFile,
+		SessionID:         sessionID,
+		PreviousSessionID: previousSessionID,
+		Date:              date,
+		Title:             title,
+		AudioS3Prefix:     audioS3Prefix,
+		AudioDir:          audioDir,
+	}
+	data, err := buildSessionInitYAML(input)
+	if err != nil {
+		return fmt.Errorf("session init: %w", err)
+	}
+	label := strings.TrimSpace(output)
+	if label == "" {
+		label = "remote session.yml"
+	}
+	sessionCfg, err := config.LoadSessionBytesWithOptions(label, data, config.SessionLoadOptions{
+		SessionID:         sessionID,
+		PreviousSessionID: previousSessionID,
+	})
+	if err != nil {
+		return fmt.Errorf("session init: %w", err)
+	}
+	cfg, err := config.Resolve(base.PipelinePath, base.Pipeline, base.CampaignPath, base.Campaign, label, sessionCfg, config.SessionSource{Source: "session_config", LocalPath: label})
+	if err != nil {
+		return fmt.Errorf("session init: %w", err)
+	}
+	if err := config.Validate(cfg); err != nil {
+		return fmt.Errorf("session init: %w", err)
+	}
+
+	if !remote {
+		if err := writeLocalFile(output, data, force); err != nil {
+			return fmt.Errorf("session init: %w", err)
+		}
+		_, err := fmt.Fprintf(out, "narratio session init: wrote %s\n", filepath.Clean(output))
+		return err
+	}
+
+	store, err := newCommandObjectStore(ctx, cfg, nil)
+	if err != nil {
+		return fmt.Errorf("session init: %w", err)
+	}
+	sessionPrefix := artifacts.S3SessionPrefix(base.Pipeline.Storage.S3.RootPrefix, config.CampaignID(base.Campaign), sessionID)
+	key := artifacts.S3SessionConfigKey(sessionPrefix)
+	exists, err := store.Exists(ctx, key)
+	if err != nil {
+		return fmt.Errorf("session init: check remote session %q: %w", key, err)
+	}
+	if exists && !force {
+		return fmt.Errorf("session init: remote session %q already exists; pass --force to overwrite", key)
+	}
+	tmp, err := os.CreateTemp("", "narratio-session-init-*.yml")
+	if err != nil {
+		return fmt.Errorf("session init: create temp file: %w", err)
+	}
+	tmpPath := tmp.Name()
+	defer func() { _ = os.Remove(tmpPath) }()
+	if _, err := tmp.Write(data); err != nil {
+		_ = tmp.Close()
+		return fmt.Errorf("session init: write temp file: %w", err)
+	}
+	if err := tmp.Close(); err != nil {
+		return fmt.Errorf("session init: close temp file: %w", err)
+	}
+	if _, err := store.Upload(ctx, tmpPath, key, storage.UploadOptions{ContentType: "application/x-yaml; charset=utf-8"}); err != nil {
+		return fmt.Errorf("session init: upload remote session %q: %w", key, err)
+	}
+	_, err = fmt.Fprintf(out, "narratio session init: wrote s3://%s/%s\n", s3BucketName(base.Pipeline), key)
+	return err
+}
+
+func buildSessionYAML(campaign, sessionID, previousSessionID, date, title, audioS3Prefix, audioDir string) ([]byte, error) {
+	if strings.TrimSpace(date) == "" && regexp.MustCompile(`^\d{4}-\d{2}-\d{2}$`).MatchString(strings.TrimSpace(sessionID)) {
+		date = strings.TrimSpace(sessionID)
+	}
+	type audioS3 struct {
+		Prefix string `yaml:"prefix"`
+	}
+	type inputs struct {
+		AudioDir string   `yaml:"audio_dir,omitempty"`
+		AudioS3  *audioS3 `yaml:"audio_s3,omitempty"`
+	}
+	type sessionYAML struct {
+		Campaign          string `yaml:"campaign"`
+		SessionID         string `yaml:"session_id"`
+		PreviousSessionID string `yaml:"previous_session_id,omitempty"`
+		Date              string `yaml:"date,omitempty"`
+		Title             string `yaml:"title,omitempty"`
+		Inputs            inputs `yaml:"inputs"`
+	}
+	in := inputs{AudioDir: strings.TrimSpace(audioDir)}
+	if in.AudioDir == "" {
+		prefix := strings.TrimSpace(audioS3Prefix)
+		if prefix == "" {
+			prefix = "audio/"
+		}
+		in.AudioS3 = &audioS3{Prefix: prefix}
+	}
+	data, err := yaml.Marshal(sessionYAML{
+		Campaign:          strings.TrimSpace(campaign),
+		SessionID:         strings.TrimSpace(sessionID),
+		PreviousSessionID: strings.TrimSpace(previousSessionID),
+		Date:              strings.TrimSpace(date),
+		Title:             strings.TrimSpace(title),
+		Inputs:            in,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return data, nil
+}
+
+type sessionInitInput struct {
+	Campaign          string
+	CampaignPath      string
+	TemplateFile      string
+	SessionID         string
+	PreviousSessionID string
+	Date              string
+	Title             string
+	AudioS3Prefix     string
+	AudioDir          string
+}
+
+func buildSessionInitYAML(in sessionInitInput) ([]byte, error) {
+	if strings.TrimSpace(in.TemplateFile) == "" {
+		return buildSessionYAML(in.Campaign, in.SessionID, in.PreviousSessionID, in.Date, in.Title, in.AudioS3Prefix, in.AudioDir)
+	}
+	templatePath := resolveSessionInitTemplatePath(in.CampaignPath, in.TemplateFile)
+	templateBytes, err := os.ReadFile(templatePath)
+	if err != nil {
+		return nil, fmt.Errorf("read session template %q: %w", templatePath, err)
+	}
+	rendered, err := renderSessionInitTemplate(string(templateBytes), in)
+	if err != nil {
+		return nil, fmt.Errorf("render session template %q: %w", templatePath, err)
+	}
+	return []byte(rendered), nil
+}
+
+func resolveSessionInitTemplatePath(campaignPath, templateFile string) string {
+	templateFile = strings.TrimSpace(templateFile)
+	if filepath.IsAbs(templateFile) {
+		return filepath.Clean(templateFile)
+	}
+	return filepath.Clean(filepath.Join(filepath.Dir(campaignPath), templateFile))
+}
+
+var sessionInitTemplatePattern = regexp.MustCompile(`\{\{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}`)
+
+func renderSessionInitTemplate(content string, in sessionInitInput) (string, error) {
+	values := map[string]string{
+		"session_id":          strings.TrimSpace(in.SessionID),
+		"previous_session_id": strings.TrimSpace(in.PreviousSessionID),
+		"date":                strings.TrimSpace(in.Date),
+		"title":               strings.TrimSpace(in.Title),
+		"audio_s3_prefix":     strings.TrimSpace(in.AudioS3Prefix),
+		"audio_dir":           strings.TrimSpace(in.AudioDir),
+	}
+	used := map[string]struct{}{}
+	unknown := map[string]struct{}{}
+	missing := map[string]struct{}{}
+	rendered := sessionInitTemplatePattern.ReplaceAllStringFunc(content, func(match string) string {
+		parts := sessionInitTemplatePattern.FindStringSubmatch(match)
+		if len(parts) < 2 {
+			return match
+		}
+		name := parts[1]
+		value, ok := values[name]
+		if !ok {
+			unknown[name] = struct{}{}
+			return match
+		}
+		used[name] = struct{}{}
+		if value == "" {
+			missing[name] = struct{}{}
+			return match
+		}
+		return value
+	})
+	if len(unknown) > 0 {
+		return "", fmt.Errorf("unsupported template variable(s): %s", sortedStringSet(unknown))
+	}
+	if len(missing) > 0 {
+		return "", fmt.Errorf("missing required template variable value(s): %s", sortedStringSet(missing))
+	}
+	unused := map[string]struct{}{}
+	for _, name := range []string{"previous_session_id", "date", "title", "audio_s3_prefix", "audio_dir"} {
+		if values[name] == "" {
+			continue
+		}
+		if _, ok := used[name]; !ok {
+			unused[name] = struct{}{}
+		}
+	}
+	if len(unused) > 0 {
+		return "", fmt.Errorf("unused template variable value(s): %s", sortedStringSet(unused))
+	}
+	return rendered, nil
+}
+
+func sortedStringSet(set map[string]struct{}) string {
+	items := make([]string, 0, len(set))
+	for item := range set {
+		items = append(items, item)
+	}
+	sort.Strings(items)
+	return strings.Join(items, ", ")
+}

internal/app/operator_session_validate.go

@@ -0,0 +1,84 @@
+package app
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"io"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+)
+
+// SessionValidate performs a read-only session preflight.
+func SessionValidate(ctx context.Context, args []string, out io.Writer) error {
+	fs := flag.NewFlagSet("session validate", flag.ContinueOnError)
+	fs.SetOutput(io.Discard)
+	var flags commonConfigFlags
+	addCommonConfigFlags(fs, &flags)
+	if err := parseSessionAwareFlags("session validate", fs, args, &flags.sessionID); err != nil {
+		return err
+	}
+	if strings.TrimSpace(flags.sessionID) == "" {
+		return fmt.Errorf("session validate: session_id is required")
+	}
+
+	findings := []finding{}
+	cfg, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.campaignFilePath, flags.sessionPath, flags.sessionOptions())
+	if err != nil {
+		findings = append(findings, errorFinding("config", err.Error()))
+		return renderFindings(out, "", "", findings)
+	}
+	if err := config.Validate(cfg); err != nil {
+		findings = append(findings, errorFinding("config", err.Error()))
+	} else {
+		findings = append(findings, okFinding("config", "resolved pipeline, campaign, and session config"))
+	}
+	findings = append(findings, okFinding("session", fmt.Sprintf("session source: %s", sessionSourceSummary(cfg))))
+
+	paths := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root).SessionPathsFor(cfg.Session.Campaign, cfg.Session.SessionID)
+	findings = append(findings, validateStableInputFindings(cfg)...)
+	findings = append(findings, validateLocalAudioFindings(cfg)...)
+
+	store, storeErr := objectStoreIfConfigured(ctx, cfg)
+	if storeErr != nil {
+		findings = append(findings, errorFinding("storage", storeErr.Error()))
+	}
+	if cfg.Session.Inputs.AudioS3 != nil {
+		if storeErr != nil {
+			findings = append(findings, errorFinding("audio", "remote audio cannot be checked because storage is unavailable"))
+		} else {
+			findings = append(findings, validateRemoteAudioFinding(ctx, cfg, store))
+		}
+	}
+
+	requirements := artifacts.CollectPreviousArtifactRequirements(configuredScriptoriumArtifacts(cfg))
+	previous := inspectPreviousArtifactReadiness(ctx, cfg, store, requirements)
+	if len(previous.Requirements) == 0 {
+		findings = append(findings, okFinding("previous", "no previous-session artifacts required"))
+	} else if previous.MissingID {
+		findings = append(findings, errorFinding("previous", "previous_session_id is required by configured previous-session artifacts"))
+	} else if previous.Err != nil {
+		findings = append(findings, errorFinding("previous", previous.Err.Error()))
+	} else {
+		for _, req := range previous.Requirements {
+			findings = append(findings, okFinding("previous", fmt.Sprintf("%s required=%t", req.Name, req.Required)))
+		}
+	}
+
+	locks := inspectEffectiveLocks(ctx, cfg, store)
+	if locks.Err != nil {
+		findings = append(findings, errorFinding("locks", locks.Err.Error()))
+	} else if len(locks.Locks.All) == 0 {
+		findings = append(findings, okFinding("locks", "no effective publish locks"))
+	} else {
+		for _, lock := range locks.Locks.All {
+			findings = append(findings, warnFinding("locks", fmt.Sprintf("%s locked: %s", lock.Source, strings.TrimSpace(lock.Reason))))
+		}
+	}
+	if paths.ManifestPath != "" {
+		findings = append(findings, infoFinding("workspace", "manifest path: "+paths.ManifestPath))
+	}
+	return renderFindings(out, cfg.Session.Campaign, cfg.Session.SessionID, findings)
+}

internal/app/operator_status.go

@@ -0,0 +1,166 @@
+package app
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"io"
+	"sort"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+)
+
+// Status reports effective local/remote session state.
+func Status(ctx context.Context, args []string, out io.Writer) error {
+	fs := flag.NewFlagSet("status", flag.ContinueOnError)
+	fs.SetOutput(io.Discard)
+	var flags commonConfigFlags
+	addCommonConfigFlags(fs, &flags)
+	if err := parseSessionAwareFlags("status", fs, args, &flags.sessionID); err != nil {
+		return err
+	}
+	if strings.TrimSpace(flags.sessionID) == "" {
+		return fmt.Errorf("status: session_id is required")
+	}
+	cfg, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.campaignFilePath, flags.sessionPath, flags.sessionOptions())
+	if err != nil {
+		return fmt.Errorf("status: %w", err)
+	}
+	if err := config.Validate(cfg); err != nil {
+		return fmt.Errorf("status: %w", err)
+	}
+	paths := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root).SessionPathsFor(cfg.Session.Campaign, cfg.Session.SessionID)
+	fmt.Fprintf(out, "Session: %s\n", cfg.Session.SessionID)
+	fmt.Fprintf(out, "Campaign: %s\n", cfg.Session.Campaign)
+	fmt.Fprintf(out, "Workspace: %s\n", paths.Root)
+	fmt.Fprintf(out, "Session config: %s\n", sessionSourceSummary(cfg))
+	writeStatusStableInputs(out, inspectStableInputs(cfg))
+	writeStatusLocalAudio(out, inspectLocalAudioPresence(cfg))
+
+	if m, err := loadLocalManifest(ctx, paths.ManifestPath); err != nil {
+		fmt.Fprintf(out, "Local manifest: error: %v\n", err)
+	} else if m == nil {
+		fmt.Fprintln(out, "Local manifest: missing")
+	} else {
+		fmt.Fprintf(out, "Local manifest: %s\n", paths.ManifestPath)
+		writeStageStatuses(out, m)
+	}
+
+	store, storeErr := objectStoreIfConfigured(ctx, cfg)
+	if storeErr != nil {
+		fmt.Fprintf(out, "Remote publish: unavailable: %v\n", storeErr)
+	} else if store != nil {
+		current := inspectRemoteCurrentState(ctx, cfg, store)
+		if current.Err != nil {
+			fmt.Fprintf(out, "Remote publish: missing or unavailable: %v\n", current.Err)
+		} else {
+			fmt.Fprintf(out, "Remote publish: current run %s\n", current.State.RunID)
+			fmt.Fprintf(out, "Remote manifest: %s\n", current.State.CurrentManifestKey)
+		}
+	}
+	writeStatusRemoteAudio(ctx, out, cfg, store, storeErr)
+	writeStatusPreviousArtifacts(out, inspectPreviousArtifactReadiness(
+		ctx,
+		cfg,
+		store,
+		artifacts.CollectPreviousArtifactRequirements(configuredScriptoriumArtifacts(cfg)),
+	))
+
+	lockChecks := inspectEffectiveLocks(ctx, cfg, store)
+	locks := lockChecks.Locks
+	lockErr := lockChecks.Err
+	if catalog, catalogErr := buildHelperArtifactCatalog(cfg); catalogErr != nil {
+		fmt.Fprintf(out, "Remote outputs: error: %v\n", catalogErr)
+	} else if storeErr == nil {
+		catalogLocks := locks
+		if lockErr != nil {
+			catalogLocks = &effectiveLocks{
+				Static: staticPublishLocks(cfg),
+				All:    staticPublishLocks(cfg),
+			}
+		}
+		publishedRemoteState := map[string]string{}
+		if store != nil {
+			publishedRemoteState = remotePublishedOutputAvailability(ctx, cfg, store, catalog)
+		}
+		fmt.Fprintln(out, "Remote outputs:")
+		writeArtifactList(out, cfg, catalog, catalogLocks, publishedRemoteState)
+	}
+	if lockErr != nil {
+		fmt.Fprintf(out, "Publish locks: error: %v\n", lockErr)
+	} else {
+		writeLocks(out, cfg, locks)
+	}
+	fmt.Fprintln(out, "Next actions:")
+	fmt.Fprintf(out, "- narratio session validate %s\n", cfg.Session.SessionID)
+	fmt.Fprintf(out, "- narratio session restore %s --dry-run\n", cfg.Session.SessionID)
+	return nil
+}
+
+func writeStatusStableInputs(out io.Writer, checks []stableInputCheck) {
+	if len(checks) == 0 {
+		return
+	}
+	for _, check := range checks {
+		if check.Err != nil {
+			if strings.TrimSpace(check.Path) != "" {
+				fmt.Fprintf(out, "Stable input %s: unavailable: %v\n", check.Name, check.Err)
+			} else {
+				fmt.Fprintf(out, "Stable input %s: unavailable: %s\n", check.Name, check.Err.Error())
+			}
+			continue
+		}
+		fmt.Fprintf(out, "Stable input %s: %s\n", check.Name, check.Path)
+	}
+}
+
+func writeStatusLocalAudio(out io.Writer, check localAudioCheck) {
+	if !check.Checked {
+		return
+	}
+	if check.Err != nil {
+		fmt.Fprintf(out, "Local audio: unavailable: %v\n", check.Err)
+		return
+	}
+	fmt.Fprintf(out, "Local audio: %d file(s)\n", len(check.Paths))
+}
+
+func writeStatusRemoteAudio(ctx context.Context, out io.Writer, cfg *config.Config, store storage.ObjectStore, storeErr error) {
+	if cfg.Session.Inputs.AudioS3 == nil {
+		return
+	}
+	if storeErr != nil {
+		fmt.Fprintf(out, "Remote audio: unavailable: %v\n", storeErr)
+		return
+	}
+	check := inspectRemoteAudioPresence(ctx, cfg, store)
+	if check.Err != nil {
+		fmt.Fprintf(out, "Remote audio: unavailable: %v\n", check.Err)
+		return
+	}
+	fmt.Fprintf(out, "Remote audio: %d .flac object(s)\n", len(check.Keys))
+}
+
+func writeStatusPreviousArtifacts(out io.Writer, readiness previousArtifactReadiness) {
+	if len(readiness.Requirements) == 0 {
+		fmt.Fprintln(out, "Previous-session artifacts: not required")
+		return
+	}
+	if readiness.MissingID {
+		fmt.Fprintln(out, "Previous-session artifacts: unavailable: previous_session_id is required by configured previous-session artifacts")
+		return
+	}
+	if readiness.Err != nil {
+		fmt.Fprintf(out, "Previous-session artifacts: unavailable: %v\n", readiness.Err)
+		return
+	}
+	names := make([]string, 0, len(readiness.Requirements))
+	for _, req := range readiness.Requirements {
+		names = append(names, fmt.Sprintf("%s(required=%t)", req.Name, req.Required))
+	}
+	sort.Strings(names)
+	fmt.Fprintf(out, "Previous-session artifacts: ready: %s\n", strings.Join(names, ", "))
+}

internal/app/plan.go

@@ -19,29 +19,18 @@ func Plan(ctx context.Context, args []string, out io.Writer) error {
 	fs := flag.NewFlagSet("plan", flag.ContinueOnError)
 	fs.SetOutput(io.Discard)
 
-	var pipelinePath string
-	var campaignPath string
-	var sessionPath string
-	var sessionID string
-	var previousSessionID string
+	var flags commonConfigFlags
 	var force bool
-	fs.StringVar(&pipelinePath, "config", "", "path to pipeline.yml (optional; defaults searched)")
-	fs.StringVar(&campaignPath, "campaign", "", "path to campaign.yml (optional; defaults searched)")
-	fs.StringVar(&sessionPath, "session", "", "path to session.yml")
-	fs.StringVar(&sessionID, "session-id", "", "session identifier for session.yml templates")
-	fs.StringVar(&previousSessionID, "previous-session-id", "", "previous session identifier for session.yml templates")
+	addCommonConfigFlags(fs, &flags)
 	fs.BoolVar(&force, "force", false, "force stage execution (reserved for future behavior)")
 
-	if err := fs.Parse(args); err != nil {
-		return fmt.Errorf("plan: invalid flags: %w", err)
+	if err := parseSessionAwareFlags("plan", fs, args, &flags.sessionID); err != nil {
+		return err
 	}
-	if fs.NArg() != 0 {
-		return fmt.Errorf("plan: unexpected positional arguments")
+	if flags.sessionID == "" {
+		return fmt.Errorf("plan: session_id is required")
 	}
-	cfg, err := loadCommandConfig(ctx, pipelinePath, campaignPath, sessionPath, config.SessionLoadOptions{
-		SessionID:         sessionID,
-		PreviousSessionID: previousSessionID,
-	})
+	cfg, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.campaignFilePath, flags.sessionPath, flags.sessionOptions())
 	if err != nil {
 		return fmt.Errorf("plan: %w", err)
 	}
@@ -68,7 +57,7 @@ func Plan(ctx context.Context, args []string, out io.Writer) error {
 
 	runCount := 0
 	skipCount := 0
-	if _, err := fmt.Fprintf(out, "narratio plan: workdir prepared at %s\n", paths.Root); err != nil {
+	if _, err := fmt.Fprintf(out, "narratio session plan: workdir prepared at %s\n", paths.Root); err != nil {
 		return err
 	}
 	for _, d := range decisions {

internal/app/plan_test.go

@@ -18,16 +18,16 @@ func TestPlanCreatesAndReusesWorkdir(t *testing.T) {
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
 
 	var out bytes.Buffer
-	args := []string{"--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath}
+	args := []string{"2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}
 
 	if err := Plan(context.Background(), args, &out); err != nil {
 		t.Fatalf("first Plan() error = %v", err)
 	}
 	got := out.String()
-	if !strings.Contains(got, "narratio plan: workdir prepared at") {
+	if !strings.Contains(got, "narratio session plan: workdir prepared at") {
 		t.Fatalf("first output = %q, want workdir prepared", got)
 	}
-	for _, name := range []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim", "analyze", "archive", "notify"} {
+	for _, name := range []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim", "analyze", "publish", "notify"} {
 		if !strings.Contains(got, name+": run") {
 			t.Fatalf("first output = %q, missing stage %q", got, name)
 		}
@@ -55,7 +55,7 @@ func TestPlanCreatesAndReusesWorkdir(t *testing.T) {
 	if err := Plan(context.Background(), args, &out); err != nil {
 		t.Fatalf("second Plan() error = %v", err)
 	}
-	if !strings.Contains(out.String(), "narratio plan: workdir prepared at") {
+	if !strings.Contains(out.String(), "narratio session plan: workdir prepared at") {
 		t.Fatalf("second output = %q, want workdir prepared", out.String())
 	}
 }
@@ -74,7 +74,7 @@ func TestPlanShowsRunAndSkipFromManifest(t *testing.T) {
 	}
 
 	var out bytes.Buffer
-	if err := Plan(context.Background(), []string{"--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath}, &out); err != nil {
+	if err := Plan(context.Background(), []string{"2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &out); err != nil {
 		t.Fatalf("Plan() error = %v", err)
 	}
 	got := out.String()
@@ -108,8 +108,6 @@ seriatim:
   binary: seriatim
 audita:
   binary: audita
-analyzer:
-  timeout: 20m
 notification:
   timeout: 10s
 `
@@ -129,7 +127,7 @@ inputs:
 	}
 
 	var out bytes.Buffer
-	err := Plan(context.Background(), []string{"--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath}, &out)
+	err := Plan(context.Background(), []string{"2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &out)
 	if err == nil {
 		t.Fatal("expected error, got nil")
 	}

internal/app/planner_test.go

@@ -4,7 +4,7 @@ import "testing"
 
 func TestBuildFullPlanOrder(t *testing.T) {
 	got := BuildFullPlan()
-	want := []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim", "analyze", "archive", "notify"}
+	want := []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim", "analyze", "publish", "notify"}
 	if len(got) != len(want) {
 		t.Fatalf("len(plan) = %d, want %d", len(got), len(want))
 	}

internal/app/post_publish_cleanup.go

@@ -12,18 +12,18 @@ import (
 	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
 )
 
-func runPostArchiveCleanup(ctx context.Context, env *Env, manifestPath string, m *manifest.Manifest, executed []string) error {
+func runPostPublishCleanup(ctx context.Context, env *Env, manifestPath string, m *manifest.Manifest, executed []string) error {
 	if env == nil || env.Config == nil || env.Config.Pipeline == nil || m == nil {
 		return nil
 	}
 
-	spoolRequested := env.Config.Pipeline.Spool.DeleteAudioAfterArchive
-	workRequested := env.Config.Pipeline.Workspace.CleanupAfterArchive
+	spoolRequested := env.Config.Pipeline.Spool.DeleteAudioAfterPublish
+	workRequested := env.Config.Pipeline.Workspace.CleanupAfterPublish
 	if !spoolRequested && !workRequested {
 		return nil
 	}
 
-	sr := archiveStageRecordForCleanup(m, executed)
+	sr := publishStageRecordForCleanup(m, executed)
 	if sr == nil {
 		return nil
 	}
@@ -33,7 +33,7 @@ func runPostArchiveCleanup(ctx context.Context, env *Env, manifestPath string, m
 	sr.Metadata["spool_cleanup_requested"] = spoolRequested
 	sr.Metadata["workdir_cleanup_requested"] = workRequested
 
-	eligible, reason := archiveCleanupEligible(env.Config, sr)
+	eligible, reason := publishCleanupEligible(env.Config, sr)
 	if !eligible {
 		sr.Metadata["cleanup_skipped"] = true
 		sr.Metadata["cleanup_skipped_reason"] = reason
@@ -63,9 +63,9 @@ func runPostArchiveCleanup(ctx context.Context, env *Env, manifestPath string, m
 	}
 
 	if spoolRequested {
-		if err := removeRunScopedDir(strings.TrimSpace(env.Config.Pipeline.Spool.Root), spoolDir, "pipeline.spool.delete_audio_after_archive"); err != nil {
+		if err := removeRunScopedDir(strings.TrimSpace(env.Config.Pipeline.Spool.Root), spoolDir, "pipeline.spool.delete_audio_after_publish"); err != nil {
 			sr.Metadata["cleanup_failed"] = true
-			sr.Metadata["cleanup_failed_policy"] = "pipeline.spool.delete_audio_after_archive"
+			sr.Metadata["cleanup_failed_policy"] = "pipeline.spool.delete_audio_after_publish"
 			sr.Metadata["cleanup_failed_path"] = spoolDir
 			_ = env.ManifestStore.Save(ctx, manifestPath, m)
 			return err
@@ -82,9 +82,9 @@ func runPostArchiveCleanup(ctx context.Context, env *Env, manifestPath string, m
 		return nil
 	}
 
-	if err := removeRunScopedDir(strings.TrimSpace(env.Config.Pipeline.Workspace.Root), workDir, "pipeline.workspace.cleanup_after_archive"); err != nil {
+	if err := removeRunScopedDir(strings.TrimSpace(env.Config.Pipeline.Workspace.Root), workDir, "pipeline.workspace.cleanup_after_publish"); err != nil {
 		sr.Metadata["cleanup_failed"] = true
-		sr.Metadata["cleanup_failed_policy"] = "pipeline.workspace.cleanup_after_archive"
+		sr.Metadata["cleanup_failed_policy"] = "pipeline.workspace.cleanup_after_publish"
 		sr.Metadata["cleanup_failed_path"] = workDir
 		_ = env.ManifestStore.Save(ctx, manifestPath, m)
 		return err
@@ -96,59 +96,59 @@ func runPostArchiveCleanup(ctx context.Context, env *Env, manifestPath string, m
 	return nil
 }
 
-func archiveStageRecordForCleanup(m *manifest.Manifest, executed []string) *manifest.StageRecord {
+func publishStageRecordForCleanup(m *manifest.Manifest, executed []string) *manifest.StageRecord {
 	if m == nil {
 		return nil
 	}
-	archiveRan := false
+	publishRan := false
 	for _, name := range executed {
-		if name == "archive" {
-			archiveRan = true
+		if name == "publish" {
+			publishRan = true
 			break
 		}
 	}
-	if !archiveRan {
+	if !publishRan {
 		return nil
 	}
-	sr := m.Stages["archive"]
+	sr := m.Stages["publish"]
 	if sr == nil || sr.Status != manifest.StatusSucceeded {
 		return nil
 	}
 	return sr
 }
 
-func archiveCleanupEligible(cfg *config.Config, sr *manifest.StageRecord) (bool, string) {
-	if cfg == nil || cfg.Pipeline == nil || cfg.Pipeline.Archive == nil {
-		return false, "archive configuration is missing"
+func publishCleanupEligible(cfg *config.Config, sr *manifest.StageRecord) (bool, string) {
+	if cfg == nil || cfg.Pipeline == nil || cfg.Pipeline.Publish == nil {
+		return false, "publish configuration is missing"
 	}
 	enabled := true
-	if cfg.Pipeline.Archive.Enabled != nil {
-		enabled = *cfg.Pipeline.Archive.Enabled
+	if cfg.Pipeline.Publish.Enabled != nil {
+		enabled = *cfg.Pipeline.Publish.Enabled
 	}
 	if !enabled {
-		return false, "archive.enabled is false"
+		return false, "publish.enabled is false"
 	}
 	uploadRun := true
-	if cfg.Pipeline.Archive.UploadRun != nil {
-		uploadRun = *cfg.Pipeline.Archive.UploadRun
+	if cfg.Pipeline.Publish.UploadRun != nil {
+		uploadRun = *cfg.Pipeline.Publish.UploadRun
 	}
 	if !uploadRun {
-		return false, "archive.upload_run is false"
+		return false, "publish.upload_run is false"
 	}
 	if sr == nil || sr.Metadata == nil {
-		return false, "archive metadata is missing"
+		return false, "publish metadata is missing"
 	}
 	if skipped, _ := sr.Metadata["skipped"].(bool); skipped {
-		return false, "archive stage was skipped"
+		return false, "publish stage was skipped"
 	}
 	if uploaded, _ := sr.Metadata["uploaded"].(bool); !uploaded {
-		return false, "archive did not upload run record"
+		return false, "publish did not upload run record"
 	}
 	if pointer, _ := sr.Metadata["current_pointer_written"].(bool); !pointer {
-		return false, "archive did not write current pointer"
+		return false, "publish did not write current pointer"
 	}
 	if strings.TrimSpace(asString(sr.Metadata["current_run_id_key"])) == "" {
-		return false, "archive current run pointer key is missing"
+		return false, "publish current run pointer key is missing"
 	}
 	return true, ""
 }
@@ -174,49 +174,7 @@ func removeRunScopedDir(root, target, policy string) error {
 }
 
 func validateScopedDir(root, target, policy string) (scopedDir, error) {
-	cleanRoot := strings.TrimSpace(root)
-	cleanTarget := strings.TrimSpace(target)
-	if cleanRoot == "" {
-		return scopedDir{}, fmt.Errorf("cleanup policy %s: root path is required", policy)
-	}
-	if cleanTarget == "" {
-		return scopedDir{}, fmt.Errorf("cleanup policy %s: target path is required", policy)
-	}
-
-	rootAbs, err := filepath.Abs(cleanRoot)
-	if err != nil {
-		return scopedDir{}, fmt.Errorf("cleanup policy %s: resolve root %q: %w", policy, cleanRoot, err)
-	}
-	targetAbs, err := filepath.Abs(cleanTarget)
-	if err != nil {
-		return scopedDir{}, fmt.Errorf("cleanup policy %s: resolve target %q: %w", policy, cleanTarget, err)
-	}
-
-	rel, err := filepath.Rel(rootAbs, targetAbs)
-	if err != nil {
-		return scopedDir{}, fmt.Errorf("cleanup policy %s: relative path from %q to %q: %w", policy, rootAbs, targetAbs, err)
-	}
-	if rel == "." {
-		return scopedDir{}, fmt.Errorf("cleanup policy %s: refusing to delete root directory %q", policy, rootAbs)
-	}
-	if rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
-		return scopedDir{}, fmt.Errorf("cleanup policy %s: refusing to delete path outside root: root=%q target=%q", policy, rootAbs, targetAbs)
-	}
-
-	info, err := os.Lstat(targetAbs)
-	if err != nil {
-		if os.IsNotExist(err) {
-			return scopedDir{RootAbs: rootAbs, TargetAbs: targetAbs, Exists: false}, nil
-		}
-		return scopedDir{}, fmt.Errorf("cleanup policy %s: stat target %q: %w", policy, targetAbs, err)
-	}
-	if info.Mode()&os.ModeSymlink != 0 {
-		return scopedDir{}, fmt.Errorf("cleanup policy %s: refusing to delete symlink path %q", policy, targetAbs)
-	}
-	if !info.IsDir() {
-		return scopedDir{}, fmt.Errorf("cleanup policy %s: target %q is not a directory", policy, targetAbs)
-	}
-	return scopedDir{RootAbs: rootAbs, TargetAbs: targetAbs, Exists: true}, nil
+	return validateScopedTarget(root, target, policy, true)
 }
 
 func asString(v any) string {

internal/app/post_publish_cleanup_test.go

@@ -16,15 +16,15 @@ import (
 	"gitea.maximumdirect.net/eric/narratio/internal/stage"
 )
 
-type archiveSuccessStage struct {
+type publishSuccessStage struct {
 	metadata map[string]any
 }
 
-func (archiveSuccessStage) Name() string           { return "archive" }
-func (archiveSuccessStage) Declares() stage.IODecl { return stage.IODecl{} }
-func (s archiveSuccessStage) Run(_ context.Context, _ *stage.Env, _ *manifest.Manifest) (*stage.StageResult, error) {
+func (publishSuccessStage) Name() string           { return "publish" }
+func (publishSuccessStage) Declares() stage.IODecl { return stage.IODecl{} }
+func (s publishSuccessStage) Run(_ context.Context, _ *stage.Env, _ *manifest.Manifest) (*stage.StageResult, error) {
 	md := map[string]any{
-		"stage":                   "archive",
+		"stage":                   "publish",
 		"uploaded":                true,
 		"current_pointer_written": true,
 		"current_run_id_key":      "dnd/campaigns/sample-campaign/sessions/2026-05-03/current/run_id.txt",
@@ -43,12 +43,12 @@ func (notifyFailStage) Run(_ context.Context, _ *stage.Env, _ *manifest.Manifest
 	return nil, errors.New("notify failed")
 }
 
-func TestPostArchiveCleanupDisabledKeepsLocalDirs(t *testing.T) {
+func TestPostPublishCleanupDisabledKeepsLocalDirs(t *testing.T) {
 	cfg, seed := cleanupFixtureConfig(t)
-	cfg.Pipeline.Spool.DeleteAudioAfterArchive = false
-	cfg.Pipeline.Workspace.CleanupAfterArchive = false
+	cfg.Pipeline.Spool.DeleteAudioAfterPublish = false
+	cfg.Pipeline.Workspace.CleanupAfterPublish = false
 
-	if _, err := executeStages(context.Background(), cfg, []stage.Stage{archiveSuccessStage{}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
 		t.Fatalf("executeStages() error = %v", err)
 	}
 
@@ -57,12 +57,12 @@ func TestPostArchiveCleanupDisabledKeepsLocalDirs(t *testing.T) {
 	assertExists(t, seed.localSourceAudio)
 }
 
-func TestPostArchiveCleanupSpoolOnly(t *testing.T) {
+func TestPostPublishCleanupSpoolOnly(t *testing.T) {
 	cfg, seed := cleanupFixtureConfig(t)
-	cfg.Pipeline.Spool.DeleteAudioAfterArchive = true
-	cfg.Pipeline.Workspace.CleanupAfterArchive = false
+	cfg.Pipeline.Spool.DeleteAudioAfterPublish = true
+	cfg.Pipeline.Workspace.CleanupAfterPublish = false
 
-	if _, err := executeStages(context.Background(), cfg, []stage.Stage{archiveSuccessStage{}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
 		t.Fatalf("executeStages() error = %v", err)
 	}
 
@@ -71,12 +71,12 @@ func TestPostArchiveCleanupSpoolOnly(t *testing.T) {
 	assertExists(t, seed.localSourceAudio)
 }
 
-func TestPostArchiveCleanupWorkdirOnly(t *testing.T) {
+func TestPostPublishCleanupWorkdirOnly(t *testing.T) {
 	cfg, seed := cleanupFixtureConfig(t)
-	cfg.Pipeline.Spool.DeleteAudioAfterArchive = false
-	cfg.Pipeline.Workspace.CleanupAfterArchive = true
+	cfg.Pipeline.Spool.DeleteAudioAfterPublish = false
+	cfg.Pipeline.Workspace.CleanupAfterPublish = true
 
-	if _, err := executeStages(context.Background(), cfg, []stage.Stage{archiveSuccessStage{}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
 		t.Fatalf("executeStages() error = %v", err)
 	}
 
@@ -87,12 +87,12 @@ func TestPostArchiveCleanupWorkdirOnly(t *testing.T) {
 	assertExists(t, seed.spoolAudioDir)
 }
 
-func TestPostArchiveCleanupBothPolicies(t *testing.T) {
+func TestPostPublishCleanupBothPolicies(t *testing.T) {
 	cfg, seed := cleanupFixtureConfig(t)
-	cfg.Pipeline.Spool.DeleteAudioAfterArchive = true
-	cfg.Pipeline.Workspace.CleanupAfterArchive = true
+	cfg.Pipeline.Spool.DeleteAudioAfterPublish = true
+	cfg.Pipeline.Workspace.CleanupAfterPublish = true
 
-	if _, err := executeStages(context.Background(), cfg, []stage.Stage{archiveSuccessStage{}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
 		t.Fatalf("executeStages() error = %v", err)
 	}
 
@@ -102,26 +102,26 @@ func TestPostArchiveCleanupBothPolicies(t *testing.T) {
 	assertExists(t, seed.previousCachePath)
 }
 
-func TestPostArchiveCleanupNotRunWhenArchiveFails(t *testing.T) {
+func TestPostPublishCleanupNotRunWhenPublishFails(t *testing.T) {
 	cfg, seed := cleanupFixtureConfig(t)
-	cfg.Pipeline.Spool.DeleteAudioAfterArchive = true
-	cfg.Pipeline.Workspace.CleanupAfterArchive = true
+	cfg.Pipeline.Spool.DeleteAudioAfterPublish = true
+	cfg.Pipeline.Workspace.CleanupAfterPublish = true
 
-	_, err := executeStages(context.Background(), cfg, []stage.Stage{failingStage{name: "archive", err: errors.New("archive failed")}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}})
-	if err == nil || !strings.Contains(err.Error(), "stage \"archive\" failed") {
-		t.Fatalf("executeStages() error = %v, want archive failure", err)
+	_, err := executeStages(context.Background(), cfg, []stage.Stage{failingStage{name: "publish", err: errors.New("publish failed")}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}})
+	if err == nil || !strings.Contains(err.Error(), "stage \"publish\" failed") {
+		t.Fatalf("executeStages() error = %v, want publish failure", err)
 	}
 
 	assertExists(t, seed.spoolAudioDir)
 	assertExists(t, seed.runWorkDir)
 }
 
-func TestPostArchiveCleanupNotRunWhenArchiveSkipped(t *testing.T) {
+func TestPostPublishCleanupNotRunWhenPublishSkipped(t *testing.T) {
 	cfg, seed := cleanupFixtureConfig(t)
-	cfg.Pipeline.Spool.DeleteAudioAfterArchive = true
-	cfg.Pipeline.Workspace.CleanupAfterArchive = true
+	cfg.Pipeline.Spool.DeleteAudioAfterPublish = true
+	cfg.Pipeline.Workspace.CleanupAfterPublish = true
 
-	if _, err := executeStages(context.Background(), cfg, []stage.Stage{archiveSuccessStage{metadata: map[string]any{"skipped": true}}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{metadata: map[string]any{"skipped": true}}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
 		t.Fatalf("executeStages() error = %v", err)
 	}
 
@@ -129,12 +129,12 @@ func TestPostArchiveCleanupNotRunWhenArchiveSkipped(t *testing.T) {
 	assertExists(t, seed.runWorkDir)
 }
 
-func TestPostArchiveCleanupNotRunWhenCurrentPointerMissing(t *testing.T) {
+func TestPostPublishCleanupNotRunWhenCurrentPointerMissing(t *testing.T) {
 	cfg, seed := cleanupFixtureConfig(t)
-	cfg.Pipeline.Spool.DeleteAudioAfterArchive = true
-	cfg.Pipeline.Workspace.CleanupAfterArchive = true
+	cfg.Pipeline.Spool.DeleteAudioAfterPublish = true
+	cfg.Pipeline.Workspace.CleanupAfterPublish = true
 
-	if _, err := executeStages(context.Background(), cfg, []stage.Stage{archiveSuccessStage{metadata: map[string]any{"current_pointer_written": false}}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{metadata: map[string]any{"current_pointer_written": false}}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
 		t.Fatalf("executeStages() error = %v", err)
 	}
 
@@ -142,13 +142,13 @@ func TestPostArchiveCleanupNotRunWhenCurrentPointerMissing(t *testing.T) {
 	assertExists(t, seed.runWorkDir)
 }
 
-func TestPostArchiveCleanupNotRunWhenArchiveUploadDisabled(t *testing.T) {
+func TestPostPublishCleanupNotRunWhenPublishUploadDisabled(t *testing.T) {
 	cfg, seed := cleanupFixtureConfig(t)
-	cfg.Pipeline.Spool.DeleteAudioAfterArchive = true
-	cfg.Pipeline.Workspace.CleanupAfterArchive = true
-	cfg.Pipeline.Archive.UploadRun = boolPtr(false)
+	cfg.Pipeline.Spool.DeleteAudioAfterPublish = true
+	cfg.Pipeline.Workspace.CleanupAfterPublish = true
+	cfg.Pipeline.Publish.UploadRun = boolPtr(false)
 
-	if _, err := executeStages(context.Background(), cfg, []stage.Stage{archiveSuccessStage{}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
 		t.Fatalf("executeStages() error = %v", err)
 	}
 
@@ -156,12 +156,12 @@ func TestPostArchiveCleanupNotRunWhenArchiveUploadDisabled(t *testing.T) {
 	assertExists(t, seed.runWorkDir)
 }
 
-func TestPostArchiveCleanupWaitsUntilAllStagesSucceed(t *testing.T) {
+func TestPostPublishCleanupWaitsUntilAllStagesSucceed(t *testing.T) {
 	cfg, seed := cleanupFixtureConfig(t)
-	cfg.Pipeline.Spool.DeleteAudioAfterArchive = true
-	cfg.Pipeline.Workspace.CleanupAfterArchive = true
+	cfg.Pipeline.Spool.DeleteAudioAfterPublish = true
+	cfg.Pipeline.Workspace.CleanupAfterPublish = true
 
-	_, err := executeStages(context.Background(), cfg, []stage.Stage{archiveSuccessStage{}, notifyFailStage{}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}})
+	_, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{}, notifyFailStage{}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}})
 	if err == nil || !strings.Contains(err.Error(), "stage \"notify\" failed") {
 		t.Fatalf("executeStages() error = %v, want notify failure", err)
 	}
@@ -170,10 +170,10 @@ func TestPostArchiveCleanupWaitsUntilAllStagesSucceed(t *testing.T) {
 	assertExists(t, seed.runWorkDir)
 }
 
-func TestPostArchiveCleanupFailsOnUnsafePath(t *testing.T) {
+func TestPostPublishCleanupFailsOnUnsafePath(t *testing.T) {
 	cfg, _ := cleanupFixtureConfig(t)
-	cfg.Pipeline.Spool.DeleteAudioAfterArchive = true
-	cfg.Pipeline.Workspace.CleanupAfterArchive = false
+	cfg.Pipeline.Spool.DeleteAudioAfterPublish = true
+	cfg.Pipeline.Workspace.CleanupAfterPublish = false
 
 	manifestPath := manifestPathFor(cfg)
 	store := &manifest.LocalStore{}
@@ -186,27 +186,27 @@ func TestPostArchiveCleanupFailsOnUnsafePath(t *testing.T) {
 		t.Fatalf("Save() error = %v", err)
 	}
 
-	_, err = executeStages(context.Background(), cfg, []stage.Stage{archiveSuccessStage{}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}})
+	_, err = executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}})
 	if err == nil || !strings.Contains(err.Error(), "refusing to delete path outside root") {
 		t.Fatalf("executeStages() error = %v, want safe-path failure", err)
 	}
 }
 
-func TestPostArchiveCleanupNotRunWhenPromotionIsMissing(t *testing.T) {
-	cfg, seed, runID := archiveStageCleanupFixture(t)
-	cfg.Pipeline.Spool.DeleteAudioAfterArchive = true
-	cfg.Pipeline.Workspace.CleanupAfterArchive = true
-	cfg.Pipeline.Archive.PromoteArtifacts = []config.ArchivePromotionRule{
-		{Source: "narratio.transcript.merged", Dest: "transcripts/merged.json", Required: boolPtr(true)},
+func TestPostPublishCleanupNotRunWhenOutputIsMissing(t *testing.T) {
+	cfg, seed, runID := publishStageCleanupFixture(t)
+	cfg.Pipeline.Spool.DeleteAudioAfterPublish = true
+	cfg.Pipeline.Workspace.CleanupAfterPublish = true
+	cfg.Pipeline.Publish.Outputs = []config.PublishOutputRule{
+		{Source: "narratio.transcript.base", Dest: "transcripts/base.json", Required: boolPtr(true)},
 	}
 
-	archiveStageImpl, err := stage.Select("archive")
+	publishStageImpl, err := stage.Select("publish")
 	if err != nil {
-		t.Fatalf("Select(archive) error = %v", err)
+		t.Fatalf("Select(publish) error = %v", err)
 	}
-	_, err = executeStages(context.Background(), cfg, []stage.Stage{archiveStageImpl}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}})
-	if err == nil || !strings.Contains(err.Error(), "required promotion source unavailable") {
-		t.Fatalf("executeStages() error = %v, want promotion-missing failure", err)
+	_, err = executeStages(context.Background(), cfg, []stage.Stage{publishStageImpl}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}})
+	if err == nil || !strings.Contains(err.Error(), "required output source unavailable") {
+		t.Fatalf("executeStages() error = %v, want required output source unavailable failure", err)
 	}
 
 	assertExists(t, seed.spoolAudioDir)
@@ -215,17 +215,17 @@ func TestPostArchiveCleanupNotRunWhenPromotionIsMissing(t *testing.T) {
 	assertExists(t, artifacts.SessionRunRootForCampaign(cfg.Pipeline.Workspace.Root, cfg.Session.Campaign, cfg.Session.SessionID, runID))
 }
 
-func TestPostArchiveCleanupNotRunWhenCurrentManifestUploadFails(t *testing.T) {
-	cfg, seed, _ := archiveStageCleanupFixture(t)
-	cfg.Pipeline.Spool.DeleteAudioAfterArchive = true
-	cfg.Pipeline.Workspace.CleanupAfterArchive = true
+func TestPostPublishCleanupNotRunWhenCurrentManifestUploadFails(t *testing.T) {
+	cfg, seed, _ := publishStageCleanupFixture(t)
+	cfg.Pipeline.Spool.DeleteAudioAfterPublish = true
+	cfg.Pipeline.Workspace.CleanupAfterPublish = true
 	failKey := seed.sessionPrefix + "current/manifest.json"
 
-	archiveStageImpl, err := stage.Select("archive")
+	publishStageImpl, err := stage.Select("publish")
 	if err != nil {
-		t.Fatalf("Select(archive) error = %v", err)
+		t.Fatalf("Select(publish) error = %v", err)
 	}
-	_, err = executeStages(context.Background(), cfg, []stage.Stage{archiveStageImpl}, RunOptions{
+	_, err = executeStages(context.Background(), cfg, []stage.Stage{publishStageImpl}, RunOptions{
 		Env: &Env{ObjectStore: &failKeyStore{delegate: &storage.FakeBackend{}, failKey: failKey}},
 	})
 	if err == nil || !strings.Contains(err.Error(), "current manifest") {
@@ -236,17 +236,17 @@ func TestPostArchiveCleanupNotRunWhenCurrentManifestUploadFails(t *testing.T) {
 	assertExists(t, seed.runWorkDir)
 }
 
-func TestPostArchiveCleanupNotRunWhenCurrentPointerUploadFails(t *testing.T) {
-	cfg, seed, _ := archiveStageCleanupFixture(t)
-	cfg.Pipeline.Spool.DeleteAudioAfterArchive = true
-	cfg.Pipeline.Workspace.CleanupAfterArchive = true
+func TestPostPublishCleanupNotRunWhenCurrentPointerUploadFails(t *testing.T) {
+	cfg, seed, _ := publishStageCleanupFixture(t)
+	cfg.Pipeline.Spool.DeleteAudioAfterPublish = true
+	cfg.Pipeline.Workspace.CleanupAfterPublish = true
 	failKey := seed.sessionPrefix + "current/run_id.txt"
 
-	archiveStageImpl, err := stage.Select("archive")
+	publishStageImpl, err := stage.Select("publish")
 	if err != nil {
-		t.Fatalf("Select(archive) error = %v", err)
+		t.Fatalf("Select(publish) error = %v", err)
 	}
-	_, err = executeStages(context.Background(), cfg, []stage.Stage{archiveStageImpl}, RunOptions{
+	_, err = executeStages(context.Background(), cfg, []stage.Stage{publishStageImpl}, RunOptions{
 		Env: &Env{ObjectStore: &failKeyStore{delegate: &storage.FakeBackend{}, failKey: failKey}},
 	})
 	if err == nil || !strings.Contains(err.Error(), "current run pointer") {
@@ -270,7 +270,7 @@ func cleanupFixtureConfig(t *testing.T) (*config.Config, cleanupSeed) {
 	t.Helper()
 
 	cfg := testConfig(t)
-	cfg.Pipeline.Archive = &config.ArchiveConfig{Enabled: boolPtr(true), UploadRun: boolPtr(true)}
+	cfg.Pipeline.Publish = &config.PublishConfig{Enabled: boolPtr(true), UploadRun: boolPtr(true)}
 	cfg.Pipeline.Spool.Root = filepath.Join(t.TempDir(), "spool")
 
 	runID := "20260516T010203Z-1a2b3c4d"
@@ -320,7 +320,7 @@ func cleanupFixtureConfig(t *testing.T) (*config.Config, cleanupSeed) {
 	}
 }
 
-func archiveStageCleanupFixture(t *testing.T) (*config.Config, cleanupSeed, string) {
+func publishStageCleanupFixture(t *testing.T) (*config.Config, cleanupSeed, string) {
 	t.Helper()
 
 	cfg, seed := cleanupFixtureConfig(t)
@@ -329,11 +329,11 @@ func archiveStageCleanupFixture(t *testing.T) (*config.Config, cleanupSeed, stri
 		Bucket:     "my-dnd-archive",
 		RootPrefix: "dnd",
 	}
-	cfg.Pipeline.Archive = &config.ArchiveConfig{
+	cfg.Pipeline.Publish = &config.PublishConfig{
 		Enabled:   boolPtr(true),
 		UploadRun: boolPtr(true),
-		PromoteArtifacts: []config.ArchivePromotionRule{
-			{Source: "narratio.transcript.trimmed", Dest: "transcripts/trimmed.json", Required: boolPtr(true)},
+		Outputs: []config.PublishOutputRule{
+			{Source: "narratio.transcript.final_trimmed", Dest: "transcripts/final.trimmed.json", Required: boolPtr(true)},
 			{Source: "narratio.artifact.session_recap", Dest: "artifacts/session_recap.md", Required: boolPtr(true)},
 		},
 	}
@@ -344,7 +344,7 @@ func archiveStageCleanupFixture(t *testing.T) (*config.Config, cleanupSeed, stri
 			},
 		},
 	}
-	writeArchiveFixtureRunFiles(
+	writePublishFixtureRunFiles(
 		t,
 		seed.runWorkDir,
 		artifacts.SessionWorkDirForCampaign(cfg.Pipeline.Workspace.Root, cfg.Session.Campaign, cfg.Session.SessionID),
@@ -367,18 +367,18 @@ func archiveStageCleanupFixture(t *testing.T) (*config.Config, cleanupSeed, stri
 	return cfg, seed, runID
 }
 
-func writeArchiveFixtureRunFiles(t *testing.T, runWorkDir, sessionRoot string) {
+func writePublishFixtureRunFiles(t *testing.T, runWorkDir, sessionRoot string) {
 	t.Helper()
 	mustWriteFile(t, filepath.Join(runWorkDir, "prepare", "inputs", "session.yml"), "session_id: 2026-05-03\n")
 	mustWriteFile(t, filepath.Join(runWorkDir, "transcribe", "outputs", "transcripts", "raw", "speaker.json"), "{}\n")
-	mustWriteFile(t, filepath.Join(runWorkDir, "trim", "outputs", "transcripts", "trimmed.json"), "{\"segments\":[]}\n")
+	mustWriteFile(t, filepath.Join(runWorkDir, "trim", "outputs", "transcripts", "final.trimmed.json"), "{\"segments\":[]}\n")
 	mustWriteFile(t, filepath.Join(runWorkDir, "analyze", "outputs", "artifacts", "session_recap.md"), "# recap\n")
 	mustWriteFile(t, filepath.Join(runWorkDir, "polish", "reports", "audita.report.json"), "{}\n")
 	mustWriteFile(t, filepath.Join(runWorkDir, "merge", "config", "seriatim.generated.yml"), "key: value\n")
 	mustWriteFile(t, filepath.Join(runWorkDir, "logs", "audita.stderr.log"), "stderr\n")
 	mustWriteFile(t, filepath.Join(runWorkDir, "manifest.json"), "{}\n")
 
-	mustWriteFile(t, filepath.Join(sessionRoot, "transcripts", "trimmed.json"), "{\"segments\":[]}\n")
+	mustWriteFile(t, filepath.Join(sessionRoot, "transcripts", "final.trimmed.json"), "{\"segments\":[]}\n")
 	mustWriteFile(t, filepath.Join(sessionRoot, "artifacts", "session_recap.md"), "# recap\n")
 }
 

internal/app/remote_locks.go

@@ -13,9 +13,9 @@ import (
 )
 
 type effectiveLocks struct {
-	Static []config.ArchiveLockRule
-	Remote []config.ArchiveLockRule
-	All    []config.ArchiveLockRule
+	Static []config.PublishLockRule
+	Remote []config.PublishLockRule
+	All    []config.PublishLockRule
 	Key    string
 }
 
@@ -34,7 +34,7 @@ func remoteLocksKey(cfg *config.Config) (string, error) {
 	return artifacts.S3SessionLocksKey(sessionPrefix), nil
 }
 
-func loadRemoteLockStore(ctx context.Context, cfg *config.Config, store storage.ObjectStore) (*config.ArchiveLockStore, string, error) {
+func loadRemoteLockStore(ctx context.Context, cfg *config.Config, store storage.ObjectStore) (*config.PublishLockStore, string, error) {
 	key, err := remoteLocksKey(cfg)
 	if err != nil {
 		return nil, "", err
@@ -44,9 +44,9 @@ func loadRemoteLockStore(ctx context.Context, cfg *config.Config, store storage.
 		return nil, key, fmt.Errorf("check remote locks %q: %w", key, err)
 	}
 	if !exists {
-		return &config.ArchiveLockStore{}, key, nil
+		return &config.PublishLockStore{}, key, nil
 	}
-	tmp, err := downloadObjectToTemp(ctx, store, key, "narratio-locks-*.yml")
+	tmp, err := storage.DownloadObjectToTemp(ctx, store, key, "narratio-locks-*.yml")
 	if err != nil {
 		return nil, key, fmt.Errorf("download remote locks %q: %w", key, err)
 	}
@@ -55,7 +55,7 @@ func loadRemoteLockStore(ctx context.Context, cfg *config.Config, store storage.
 	if err != nil {
 		return nil, key, fmt.Errorf("read remote locks %q: %w", key, err)
 	}
-	lockStore, err := config.LoadArchiveLockStoreBytes("s3://"+s3BucketName(cfg.Pipeline)+"/"+key, data, cfg.Pipeline.Scriptorium)
+	lockStore, err := config.LoadPublishLockStoreBytes("s3://"+s3BucketName(cfg.Pipeline)+"/"+key, data, cfg.Pipeline.Scriptorium)
 	if err != nil {
 		return nil, key, err
 	}
@@ -63,45 +63,45 @@ func loadRemoteLockStore(ctx context.Context, cfg *config.Config, store storage.
 }
 
 func loadEffectiveLocks(ctx context.Context, cfg *config.Config, store storage.ObjectStore) (*effectiveLocks, error) {
-	staticLocks := staticArchiveLocks(cfg)
+	staticLocks := staticPublishLocks(cfg)
 	if store == nil {
 		return &effectiveLocks{
 			Static: staticLocks,
-			All:    append([]config.ArchiveLockRule(nil), staticLocks...),
+			All:    append([]config.PublishLockRule(nil), staticLocks...),
 		}, nil
 	}
 	lockStore, key, err := loadRemoteLockStore(ctx, cfg, store)
 	if err != nil {
 		return nil, err
 	}
-	remoteLocks := append([]config.ArchiveLockRule(nil), lockStore.Locks...)
+	remoteLocks := append([]config.PublishLockRule(nil), lockStore.Locks...)
 	return &effectiveLocks{
 		Static: staticLocks,
 		Remote: remoteLocks,
-		All:    config.MergeArchiveLockRules(staticLocks, remoteLocks),
+		All:    config.MergePublishLockRules(staticLocks, remoteLocks),
 		Key:    key,
 	}, nil
 }
 
-func staticArchiveLocks(cfg *config.Config) []config.ArchiveLockRule {
-	if cfg == nil || cfg.Pipeline == nil || cfg.Pipeline.Archive == nil {
+func staticPublishLocks(cfg *config.Config) []config.PublishLockRule {
+	if cfg == nil || cfg.Pipeline == nil || cfg.Pipeline.Publish == nil {
 		return nil
 	}
-	return append([]config.ArchiveLockRule(nil), cfg.Pipeline.Archive.Locks...)
+	return append([]config.PublishLockRule(nil), cfg.Pipeline.Publish.Locks...)
 }
 
-func applyEffectiveLocks(cfg *config.Config, locks []config.ArchiveLockRule) {
+func applyEffectiveLocks(cfg *config.Config, locks []config.PublishLockRule) {
 	if cfg == nil || cfg.Pipeline == nil {
 		return
 	}
-	if cfg.Pipeline.Archive == nil {
-		cfg.Pipeline.Archive = &config.ArchiveConfig{}
+	if cfg.Pipeline.Publish == nil {
+		cfg.Pipeline.Publish = &config.PublishConfig{}
 	}
-	cfg.Pipeline.Archive.Locks = append([]config.ArchiveLockRule(nil), locks...)
+	cfg.Pipeline.Publish.Locks = append([]config.PublishLockRule(nil), locks...)
 }
 
-func uploadRemoteLockStore(ctx context.Context, store storage.ObjectStore, key string, lockStore *config.ArchiveLockStore) error {
-	data, err := config.MarshalArchiveLockStore(lockStore)
+func uploadRemoteLockStore(ctx context.Context, store storage.ObjectStore, key string, lockStore *config.PublishLockStore) error {
+	data, err := config.MarshalPublishLockStore(lockStore)
 	if err != nil {
 		return err
 	}
@@ -124,8 +124,8 @@ func uploadRemoteLockStore(ctx context.Context, store storage.ObjectStore, key s
 	return nil
 }
 
-func lockSourceSet(locks []config.ArchiveLockRule) map[string]config.ArchiveLockRule {
-	out := make(map[string]config.ArchiveLockRule, len(locks))
+func lockSourceSet(locks []config.PublishLockRule) map[string]config.PublishLockRule {
+	out := make(map[string]config.PublishLockRule, len(locks))
 	for _, lock := range locks {
 		source := strings.TrimSpace(lock.Source)
 		if source == "" {

internal/app/remote_session_test.go

@@ -19,7 +19,7 @@ func TestExecuteRemoteSessionFallbackLoadsFromObjectStore(t *testing.T) {
 	workspaceRoot := t.TempDir()
 	pipelinePath, campaignPath, _ := writeValidConfigFiles(t, workspaceRoot)
 	fake := &storage.FakeBackend{}
-	remoteKey := seedRemoteSessionConfig(t, fake, "2026-05-03", `session_id: "{{ session_id }}"
+	remoteKey := seedRemoteSessionConfig(t, fake, "2026-05-03", `session_id: 2026-05-03
 inputs:
   audio_s3:
     prefix: audio/
@@ -29,14 +29,14 @@ inputs:
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"plan", "--config", pipelinePath, "--campaign", campaignPath, "--session-id", "2026-05-03"}, &stdout, &stderr)
+	code := Execute([]string{"session", "plan", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath}, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
 	}
 	if storeInitCalls != 1 {
 		t.Fatalf("object store init calls = %d, want 1", storeInitCalls)
 	}
-	if !strings.Contains(stdout.String(), "narratio plan: workdir prepared") {
+	if !strings.Contains(stdout.String(), "narratio session plan: workdir prepared") {
 		t.Fatalf("stdout = %q, want plan output", stdout.String())
 	}
 	if _, ok := fake.Objects[remoteKey]; !ok {
@@ -56,7 +56,7 @@ func TestExecuteRemoteSessionFallbackLoadsSecretsBeforeObjectStoreInit(t *testin
 	addSecretsToPipelineConfig(t, pipelinePath, secretsDir, accessKeyEnv, secretKeyEnv)
 
 	fake := &storage.FakeBackend{}
-	seedRemoteSessionConfig(t, fake, "2026-05-03", `session_id: "{{ session_id }}"
+	seedRemoteSessionConfig(t, fake, "2026-05-03", `session_id: 2026-05-03
 inputs:
   audio_s3:
     prefix: audio/
@@ -77,7 +77,7 @@ inputs:
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"plan", "--config", pipelinePath, "--campaign", campaignPath, "--session-id", "2026-05-03"}, &stdout, &stderr)
+	code := Execute([]string{"session", "plan", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath}, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("exit code = %d, want 0; stdout=%q stderr=%q", code, stdout.String(), stderr.String())
 	}
@@ -92,7 +92,7 @@ func TestExecuteExplicitLocalSessionPrecedenceSkipsRemote(t *testing.T) {
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"plan", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "--session-id", "2026-05-03"}, &stdout, &stderr)
+	code := Execute([]string{"session", "plan", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
 	}
@@ -110,7 +110,7 @@ func TestExecuteLocalSessionDiscoveryPrecedenceSkipsRemote(t *testing.T) {
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"plan", "--config", pipelinePath, "--campaign", campaignPath, "--session-id", "2026-05-03"}, &stdout, &stderr)
+	code := Execute([]string{"session", "plan", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath}, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
 	}
@@ -129,7 +129,7 @@ func TestExecuteRemoteSessionMissingObjectFailsClearly(t *testing.T) {
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"plan", "--config", pipelinePath, "--campaign", campaignPath, "--session-id", "2026-05-03"}, &stdout, &stderr)
+	code := Execute([]string{"session", "plan", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath}, &stdout, &stderr)
 	if code == 0 {
 		t.Fatal("exit code = 0, want non-zero")
 	}
@@ -149,12 +149,12 @@ func TestExecuteRemoteSessionRequiresSessionID(t *testing.T) {
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"plan", "--config", pipelinePath, "--campaign", campaignPath}, &stdout, &stderr)
+	code := Execute([]string{"session", "plan", "--config", pipelinePath, "--campaign-file", campaignPath}, &stdout, &stderr)
 	if code == 0 {
 		t.Fatal("exit code = 0, want non-zero")
 	}
-	if !strings.Contains(stderr.String(), "remote session loading requires --session-id") {
-		t.Fatalf("stderr = %q, want session-id guidance", stderr.String())
+	if !strings.Contains(stderr.String(), "plan: session_id is required") {
+		t.Fatalf("stderr = %q, want session_id guidance", stderr.String())
 	}
 	if storeInitCalls != 0 {
 		t.Fatalf("object store init calls = %d, want 0", storeInitCalls)
@@ -177,7 +177,7 @@ func TestExecuteRemoteSessionStorageInitErrorFailsClearly(t *testing.T) {
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"plan", "--config", pipelinePath, "--campaign", campaignPath, "--session-id", "2026-05-03"}, &stdout, &stderr)
+	code := Execute([]string{"session", "plan", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath}, &stdout, &stderr)
 	if code == 0 {
 		t.Fatal("exit code = 0, want non-zero")
 	}
@@ -196,7 +196,7 @@ func TestExecuteRemoteSessionMalformedYAMLFailsStrictDecode(t *testing.T) {
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"plan", "--config", pipelinePath, "--campaign", campaignPath, "--session-id", "2026-05-03"}, &stdout, &stderr)
+	code := Execute([]string{"session", "plan", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath}, &stdout, &stderr)
 	if code == 0 {
 		t.Fatal("exit code = 0, want non-zero")
 	}
@@ -205,6 +205,48 @@ func TestExecuteRemoteSessionMalformedYAMLFailsStrictDecode(t *testing.T) {
 	}
 }
 
+func TestExecuteRemoteSessionTemplateFailsConcreteSessionCheck(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, campaignPath, _ := writeValidConfigFiles(t, workspaceRoot)
+	fake := &storage.FakeBackend{}
+	seedRemoteSessionConfig(t, fake, "2026-05-03", `session_id: "{{ session_id }}"
+inputs:
+  audio_s3:
+    prefix: audio/
+`)
+	var storeInitCalls int
+	restoreAppConfigTestGlobals(t, fake, &storeInitCalls, []string{filepath.Join(t.TempDir(), "session.yml")})
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	code := Execute([]string{"session", "plan", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath}, &stdout, &stderr)
+	if code == 0 {
+		t.Fatal("exit code = 0, want non-zero")
+	}
+	if !strings.Contains(stderr.String(), "session.yml must be concrete") || !strings.Contains(stderr.String(), "run narratio session init") {
+		t.Fatalf("stderr = %q, want concrete session guidance", stderr.String())
+	}
+}
+
+func TestExecuteRemoteSessionMismatchFails(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, campaignPath, _ := writeValidConfigFiles(t, workspaceRoot)
+	fake := &storage.FakeBackend{}
+	seedRemoteSessionConfig(t, fake, "2026-05-03", "session_id: 2026-05-04\ninputs:\n  audio_s3:\n    prefix: audio/\n")
+	var storeInitCalls int
+	restoreAppConfigTestGlobals(t, fake, &storeInitCalls, []string{filepath.Join(t.TempDir(), "session.yml")})
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	code := Execute([]string{"session", "plan", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath}, &stdout, &stderr)
+	if code == 0 {
+		t.Fatal("exit code = 0, want non-zero")
+	}
+	if !strings.Contains(stderr.String(), "session_id mismatch") {
+		t.Fatalf("stderr = %q, want session_id mismatch", stderr.String())
+	}
+}
+
 func restoreAppConfigTestGlobals(t *testing.T, fake *storage.FakeBackend, storeInitCalls *int, sessionDefaults []string) {
 	t.Helper()
 	origStoreFn := newObjectStoreFromConfigFn

internal/app/restore.go

@@ -8,6 +8,7 @@ import (
 	"io"
 	"log/slog"
 	"os"
+	"strings"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
 	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
@@ -22,27 +23,20 @@ var executeRestorePlanFn = executeRestorePlan
 
 // Restore validates restore CLI/config inputs and storage preflight for future restore phases.
 func Restore(ctx context.Context, args []string, out io.Writer) error {
+	positionalSessionID, args := pullLeadingSessionID(args)
 	fs := flag.NewFlagSet("restore", flag.ContinueOnError)
 	fs.SetOutput(out)
 
-	var pipelinePath string
-	var campaignPath string
-	var sessionPath string
-	var sessionID string
-	var previousSessionID string
+	var flags commonConfigFlags
 	var dryRun bool
 	var force bool
 	var includeAudio bool
-	fs.StringVar(&pipelinePath, "config", "", "path to pipeline.yml (optional; defaults searched)")
-	fs.StringVar(&campaignPath, "campaign", "", "path to campaign.yml (optional; defaults searched)")
-	fs.StringVar(&sessionPath, "session", "", "path to session.yml")
-	fs.StringVar(&sessionID, "session-id", "", "session identifier for session.yml templates")
-	fs.StringVar(&previousSessionID, "previous-session-id", "", "previous session identifier for session.yml templates")
+	addCommonConfigFlags(fs, &flags)
 	fs.BoolVar(&dryRun, "dry-run", false, "plan restore actions without writing local files")
 	fs.BoolVar(&force, "force", false, "overwrite local conflicts with remote state")
-	fs.BoolVar(&includeAudio, "include-audio", false, "include archived session-level audio objects")
+	fs.BoolVar(&includeAudio, "include-audio", false, "include remote session-level audio objects")
 	fs.Usage = func() {
-		_, _ = fmt.Fprintln(out, "Usage: narratio restore [--config <path>] [--campaign <path>] [--session <path>] [--session-id <value>] [--previous-session-id <value>] [--dry-run] [--force] [--include-audio]")
+		_, _ = fmt.Fprintln(out, "Usage: narratio session restore <session_id> [--config <path>] [--campaign <id>] [--campaign-file <path>] [--session <path>] [--previous-session-id <value>] [--dry-run] [--force] [--include-audio]")
 		_, _ = fmt.Fprintln(out)
 		_, _ = fmt.Fprintln(out, "Flags:")
 		fs.PrintDefaults()
@@ -54,13 +48,13 @@ func Restore(ctx context.Context, args []string, out io.Writer) error {
 		}
 		return fmt.Errorf("restore: invalid flags: %w", err)
 	}
-	if fs.NArg() != 0 {
-		return fmt.Errorf("restore: unexpected positional arguments")
+	if err := resolveParsedSessionID("restore", positionalSessionID, fs, &flags.sessionID); err != nil {
+		return err
 	}
-	cfg, err := loadCommandConfig(ctx, pipelinePath, campaignPath, sessionPath, config.SessionLoadOptions{
-		SessionID:         sessionID,
-		PreviousSessionID: previousSessionID,
-	})
+	if strings.TrimSpace(flags.sessionID) == "" {
+		return fmt.Errorf("restore: session_id is required")
+	}
+	cfg, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.campaignFilePath, flags.sessionPath, flags.sessionOptions())
 	if err != nil {
 		return fmt.Errorf("restore: %w", err)
 	}

internal/app/restore_discovery.go

@@ -3,7 +3,6 @@ package app
 import (
 	"context"
 	"fmt"
-	"os"
 	"strings"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
@@ -12,7 +11,7 @@ import (
 	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
 )
 
-// RemoteCurrentState captures discovered committed remote archive state for one session.
+// RemoteCurrentState captures discovered committed remote published current state for one session.
 type RemoteCurrentState struct {
 	Bucket             string
 	SessionPrefix      string
@@ -32,80 +31,24 @@ func discoverRemoteCurrentState(ctx context.Context, cfg *config.Config, store s
 		return nil, fmt.Errorf("remote object store is required")
 	}
 
-	bucket := artifacts.ResolveArchiveBucket(cfg, nil)
+	bucket := artifacts.ResolvePublishBucket(cfg, nil)
 	if strings.TrimSpace(bucket) == "" {
-		return nil, fmt.Errorf("archive bucket is required")
+		return nil, fmt.Errorf("publish bucket is required")
 	}
-	sessionPrefix, err := artifacts.ResolveArchiveSessionPrefix(cfg, nil)
+	sessionPrefix, err := artifacts.ResolvePublishSessionPrefix(cfg, nil)
 	if err != nil {
-		return nil, fmt.Errorf("resolve archive session prefix: %w", err)
-	}
-	currentManifestKey, currentRunIDKey := artifacts.ResolveArchiveCurrentStateKeys(sessionPrefix)
-
-	exists, err := store.Exists(ctx, currentRunIDKey)
-	if err != nil {
-		return nil, fmt.Errorf("check remote current run pointer %q: %w", currentRunIDKey, err)
-	}
-	if !exists {
-		return nil, fmt.Errorf("remote current run pointer missing: %q", currentRunIDKey)
-	}
-
-	runIDPath, err := downloadObjectToTemp(ctx, store, currentRunIDKey, "narratio-restore-current-run-id-*.txt")
-	if err != nil {
-		return nil, fmt.Errorf("download remote current run pointer %q: %w", currentRunIDKey, err)
-	}
-	defer func() { _ = os.Remove(runIDPath) }()
-
-	runIDData, err := os.ReadFile(runIDPath)
-	if err != nil {
-		return nil, fmt.Errorf("read downloaded run pointer %q: %w", currentRunIDKey, err)
-	}
-	runID := strings.TrimSpace(string(runIDData))
-	if runID == "" {
-		return nil, fmt.Errorf("remote current run pointer %q is empty", currentRunIDKey)
-	}
-
-	exists, err = store.Exists(ctx, currentManifestKey)
-	if err != nil {
-		return nil, fmt.Errorf("check remote current manifest %q: %w", currentManifestKey, err)
-	}
-	if !exists {
-		return nil, fmt.Errorf("remote current manifest missing: %q", currentManifestKey)
-	}
-
-	manifestPath, err := downloadObjectToTemp(ctx, store, currentManifestKey, "narratio-restore-current-manifest-*.json")
-	if err != nil {
-		return nil, fmt.Errorf("download remote current manifest %q: %w", currentManifestKey, err)
-	}
-	defer func() { _ = os.Remove(manifestPath) }()
-
-	manifestStore := &manifest.LocalStore{}
-	remoteManifest, err := manifestStore.Load(ctx, manifestPath)
-	if err != nil {
-		return nil, fmt.Errorf("remote current manifest decode failed: %w", err)
+		return nil, fmt.Errorf("resolve publish session prefix: %w", err)
 	}
+	currentManifestKey, currentRunIDKey := artifacts.ResolveCurrentStateKeys(sessionPrefix)
 
 	requestedSession := strings.TrimSpace(cfg.Session.SessionID)
 	requestedCampaign := strings.TrimSpace(cfg.Session.Campaign)
-	manifestSession := strings.TrimSpace(remoteManifest.SessionID)
-	manifestCampaign := strings.TrimSpace(remoteManifest.Campaign)
-
-	if manifestSession != requestedSession {
-		return nil, fmt.Errorf(
-			"remote current manifest session_id %q does not match requested session_id %q",
-			manifestSession,
-			requestedSession,
-		)
-	}
-	if manifestCampaign == "" {
-		return nil, fmt.Errorf("remote current manifest campaign is required")
-	}
-	if manifestCampaign != requestedCampaign {
-		return nil, fmt.Errorf(
-			"remote current manifest campaign %q does not match requested campaign %q",
-			manifestCampaign,
-			requestedCampaign,
-		)
+	current, err := artifacts.LoadCurrentState(ctx, store, sessionPrefix, artifacts.CurrentStateValidation{
+		ExpectedSessionID: requestedSession,
+		ExpectedCampaign:  requestedCampaign,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("remote %w", err)
 	}
 
 	return &RemoteCurrentState{
@@ -113,27 +56,9 @@ func discoverRemoteCurrentState(ctx context.Context, cfg *config.Config, store s
 		SessionPrefix:      sessionPrefix,
 		CurrentRunIDKey:    currentRunIDKey,
 		CurrentManifestKey: currentManifestKey,
-		RunID:              runID,
-		SessionID:          manifestSession,
-		Campaign:           manifestCampaign,
-		Manifest:           remoteManifest,
+		RunID:              current.RunID,
+		SessionID:          strings.TrimSpace(current.Manifest.SessionID),
+		Campaign:           strings.TrimSpace(current.Manifest.Campaign),
+		Manifest:           current.Manifest,
 	}, nil
 }
-
-func downloadObjectToTemp(ctx context.Context, store storage.ObjectStore, key, pattern string) (string, error) {
-	tmp, err := os.CreateTemp("", pattern)
-	if err != nil {
-		return "", fmt.Errorf("create temp file: %w", err)
-	}
-	path := tmp.Name()
-	if err := tmp.Close(); err != nil {
-		_ = os.Remove(path)
-		return "", fmt.Errorf("close temp file: %w", err)
-	}
-
-	if err := store.Download(ctx, key, path); err != nil {
-		_ = os.Remove(path)
-		return "", err
-	}
-	return path, nil
-}

internal/app/restore_discovery_test.go

@@ -102,7 +102,7 @@ func TestDiscoverRemoteCurrentStateSessionMismatchFails(t *testing.T) {
 	store.SeedObject(storage.FakeObject{Key: manifestKey, Data: restoreManifestJSON(t, "wrong-session", cfg.Session.Campaign)})
 
 	_, err := discoverRemoteCurrentState(context.Background(), cfg, store)
-	if err == nil || !strings.Contains(err.Error(), "does not match requested session_id") {
+	if err == nil || !strings.Contains(err.Error(), "does not match expected session_id") {
 		t.Fatalf("error = %v, want session mismatch failure", err)
 	}
 }
@@ -116,7 +116,7 @@ func TestDiscoverRemoteCurrentStateCampaignMismatchFails(t *testing.T) {
 	store.SeedObject(storage.FakeObject{Key: manifestKey, Data: restoreManifestJSON(t, cfg.Session.SessionID, "wrong-campaign")})
 
 	_, err := discoverRemoteCurrentState(context.Background(), cfg, store)
-	if err == nil || !strings.Contains(err.Error(), "does not match requested campaign") {
+	if err == nil || !strings.Contains(err.Error(), "does not match expected campaign") {
 		t.Fatalf("error = %v, want campaign mismatch failure", err)
 	}
 }
@@ -208,7 +208,7 @@ func restoreDiscoveryConfig() *config.Config {
 
 func restoreDiscoveryKeys(cfg *config.Config) (sessionPrefix, manifestKey, runIDKey string) {
 	sessionPrefix = artifacts.S3SessionPrefix(cfg.Pipeline.Storage.S3.RootPrefix, cfg.Session.Campaign, cfg.Session.SessionID)
-	manifestKey, runIDKey = artifacts.ResolveArchiveCurrentStateKeys(sessionPrefix)
+	manifestKey, runIDKey = artifacts.ResolveCurrentStateKeys(sessionPrefix)
 	return sessionPrefix, manifestKey, runIDKey
 }
 

internal/app/restore_execute.go

@@ -11,6 +11,7 @@ import (
 	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
 	"gitea.maximumdirect.net/eric/narratio/internal/audio"
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
 )
 
@@ -114,10 +115,7 @@ func executeRestoreDownloadAction(
 		}
 	}
 
-	if err := os.Chmod(tmpPath, 0o644); err != nil {
-		return fmt.Errorf("set file permissions: %w", err)
-	}
-	if err := os.Rename(tmpPath, safeLocalPath); err != nil {
+	if err := fileops.InstallDownloadedTempFile(tmpPath, safeLocalPath, 0o644); err != nil {
 		return fmt.Errorf("install file atomically: %w", err)
 	}
 	removeTmp = false

internal/app/restore_execution_test.go

@@ -32,14 +32,14 @@ func TestExecuteRestoreNonDryRunRestoresDurableFiles(t *testing.T) {
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"restore", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath}, &stdout, &stderr)
+	code := Execute([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
 	}
 	if stderr.Len() != 0 {
 		t.Fatalf("stderr = %q, want empty", stderr.String())
 	}
-	if !strings.Contains(stdout.String(), "Restored session archive for sample-campaign/2026-05-03") {
+	if !strings.Contains(stdout.String(), "Restored session state for sample-campaign/2026-05-03") {
 		t.Fatalf("stdout = %q, want completion summary", stdout.String())
 	}
 
@@ -74,7 +74,7 @@ func TestExecuteRestoreIncludeAudioRestoresAudio(t *testing.T) {
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"restore", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "--include-audio"}, &stdout, &stderr)
+	code := Execute([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--include-audio"}, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
 	}
@@ -100,7 +100,7 @@ func TestExecuteRestoreIncludeAudioUsesCacheAfterWorkspaceDeletion(t *testing.T)
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"restore", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "--include-audio"}, &stdout, &stderr)
+	code := Execute([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--include-audio"}, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("first restore exit code = %d, want 0; stderr=%q", code, stderr.String())
 	}
@@ -115,7 +115,7 @@ func TestExecuteRestoreIncludeAudioUsesCacheAfterWorkspaceDeletion(t *testing.T)
 	}
 	stdout.Reset()
 	stderr.Reset()
-	code = Execute([]string{"restore", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "--include-audio"}, &stdout, &stderr)
+	code = Execute([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--include-audio"}, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("second restore exit code = %d, want 0; stderr=%q", code, stderr.String())
 	}
@@ -128,23 +128,29 @@ func TestExecuteRestoreIncludeAudioUsesCacheAfterWorkspaceDeletion(t *testing.T)
 func TestExecuteRestoreRestoresPreviousCacheWhenPresent(t *testing.T) {
 	workspaceRoot := t.TempDir()
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
+	appendRestoreWorkflowPreviousInputConfig(t, pipelinePath, sessionPath)
 
 	fake := &storage.FakeBackend{}
-	cfg, sessionPrefix, _, _ := seedRestoreCommittedState(t, fake, pipelinePath, campaignPath, sessionPath)
-	seedRestoreObject(fake, sessionPrefix+"previous/manifest.json", []byte(`{"session_id":"2026-04-26"}`))
-	seedRestoreObject(fake, sessionPrefix+"previous/artifacts/session_recap.md", []byte("# previous recap\n"))
+	cfg, _, _, _ := seedRestoreCommittedState(t, fake, pipelinePath, campaignPath, sessionPath)
+	seedRestorePreviousCurrent(t, fake, cfg, "# previous recap\n")
 
 	restoreWithStoreAndRealPhases(t, fake)
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"restore", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath}, &stdout, &stderr)
+	code := Execute([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
 	}
 
 	sessionRoot := artifacts.SessionWorkDirForCampaign(workspaceRoot, cfg.Session.Campaign, cfg.Session.SessionID)
-	mustReadEquals(t, filepath.Join(sessionRoot, "previous", "manifest.json"), `{"session_id":"2026-04-26"}`)
+	previousManifestBytes, err := os.ReadFile(filepath.Join(sessionRoot, "previous", "manifest.json"))
+	if err != nil {
+		t.Fatalf("read restored previous manifest: %v", err)
+	}
+	if !strings.Contains(string(previousManifestBytes), `"session_id":"2026-04-26"`) {
+		t.Fatalf("restored previous manifest = %q, want previous session id", string(previousManifestBytes))
+	}
 	mustReadEquals(t, filepath.Join(sessionRoot, "previous", "artifacts", "session_recap.md"), "# previous recap\n")
 	report := mustReadRestoreReport(t, filepath.Join(sessionRoot, "reports", "restore-latest.json"))
 	if report.Execution.Downloaded != 3 {
@@ -152,6 +158,33 @@ func TestExecuteRestoreRestoresPreviousCacheWhenPresent(t *testing.T) {
 	}
 }
 
+func TestExecuteRestoreDryRunReportsPreviousCacheWithoutWriting(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
+	appendRestoreWorkflowPreviousInputConfig(t, pipelinePath, sessionPath)
+
+	fake := &storage.FakeBackend{}
+	cfg, _, _, _ := seedRestoreCommittedState(t, fake, pipelinePath, campaignPath, sessionPath)
+	seedRestorePreviousCurrent(t, fake, cfg, "# previous recap\n")
+
+	restoreWithStoreAndRealPhases(t, fake)
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	code := Execute([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--dry-run"}, &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
+	}
+	if !strings.Contains(stdout.String(), "previous/artifacts/session_recap.md") {
+		t.Fatalf("stdout = %q, want planned previous-cache artifact", stdout.String())
+	}
+
+	sessionRoot := artifacts.SessionWorkDirForCampaign(workspaceRoot, cfg.Session.Campaign, cfg.Session.SessionID)
+	if _, err := os.Stat(filepath.Join(sessionRoot, "previous", "artifacts", "session_recap.md")); !os.IsNotExist(err) {
+		t.Fatalf("previous artifact should not be written during dry-run; stat err=%v", err)
+	}
+}
+
 func TestExecuteRestoreConflictWithoutForceDoesNotOverwrite(t *testing.T) {
 	workspaceRoot := t.TempDir()
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
@@ -167,7 +200,7 @@ func TestExecuteRestoreConflictWithoutForceDoesNotOverwrite(t *testing.T) {
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"restore", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath}, &stdout, &stderr)
+	code := Execute([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
 	if code == 0 {
 		t.Fatal("exit code = 0, want non-zero")
 	}
@@ -199,7 +232,7 @@ func TestExecuteRestoreForceOverwritesDifferingFile(t *testing.T) {
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"restore", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "--force"}, &stdout, &stderr)
+	code := Execute([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--force"}, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
 	}
@@ -213,10 +246,11 @@ func TestExecuteRestoreForceOverwritesDifferingFile(t *testing.T) {
 func TestExecuteRestoreForceOverwritesDifferingPreviousCacheFile(t *testing.T) {
 	workspaceRoot := t.TempDir()
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
+	appendRestoreWorkflowPreviousInputConfig(t, pipelinePath, sessionPath)
 
 	fake := &storage.FakeBackend{}
-	cfg, sessionPrefix, _, _ := seedRestoreCommittedState(t, fake, pipelinePath, campaignPath, sessionPath)
-	seedRestoreObject(fake, sessionPrefix+"previous/artifacts/session_recap.md", []byte("# remote previous recap\n"))
+	cfg, _, _, _ := seedRestoreCommittedState(t, fake, pipelinePath, campaignPath, sessionPath)
+	seedRestorePreviousCurrent(t, fake, cfg, "# remote previous recap\n")
 
 	sessionRoot := artifacts.SessionWorkDirForCampaign(workspaceRoot, cfg.Session.Campaign, cfg.Session.SessionID)
 	mustWriteTestFile(t, filepath.Join(sessionRoot, "previous", "artifacts", "session_recap.md"), "# local previous recap\n")
@@ -225,7 +259,7 @@ func TestExecuteRestoreForceOverwritesDifferingPreviousCacheFile(t *testing.T) {
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"restore", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "--force"}, &stdout, &stderr)
+	code := Execute([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--force"}, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
 	}
@@ -251,7 +285,7 @@ func TestExecuteRestoreLockConflictFailsAndWritesNothing(t *testing.T) {
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"restore", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath}, &stdout, &stderr)
+	code := Execute([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
 	if code == 0 {
 		t.Fatal("exit code = 0, want non-zero")
 	}
@@ -298,7 +332,7 @@ func TestExecuteRestoreInvalidManifestDoesNotCorruptExistingManifest(t *testing.
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"restore", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "--force"}, &stdout, &stderr)
+	code := Execute([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--force"}, &stdout, &stderr)
 	if code == 0 {
 		t.Fatal("exit code = 0, want non-zero")
 	}
@@ -393,7 +427,7 @@ func seedRestoreCommittedState(t *testing.T, fake *storage.FakeBackend, pipeline
 	}
 
 	sessionPrefix := artifacts.S3SessionPrefix(cfg.Pipeline.Storage.S3.RootPrefix, cfg.Session.Campaign, cfg.Session.SessionID)
-	manifestKey, runIDKey := artifacts.ResolveArchiveCurrentStateKeys(sessionPrefix)
+	manifestKey, runIDKey := artifacts.ResolveCurrentStateKeys(sessionPrefix)
 
 	seedRestoreObject(fake, runIDKey, []byte("20260519T010203Z-a1b2c3d4\n"))
 	seedRestoreObject(fake, manifestKey, restoreManifestJSON(t, cfg.Session.SessionID, cfg.Session.Campaign))
@@ -401,6 +435,50 @@ func seedRestoreCommittedState(t *testing.T, fake *storage.FakeBackend, pipeline
 	return cfg, sessionPrefix, manifestKey, runIDKey
 }
 
+func appendRestoreWorkflowPreviousInputConfig(t *testing.T, pipelinePath, sessionPath string) {
+	t.Helper()
+	appendRestoreWorkflowScriptoriumConfig(t, pipelinePath, `
+scriptorium:
+  binary: scriptorium
+  artifacts:
+    session_recap:
+      enabled: true
+      prompt_id: dnd.session_recap
+      output_path: artifacts/session_recap.md
+      inputs:
+        previous_recap:
+          source: narratio.previous_session.artifact.session_recap
+          required: true
+`)
+	appendRestoreWorkflowScriptoriumConfig(t, sessionPath, `
+previous_session_id: 2026-04-26
+`)
+}
+
+func seedRestorePreviousCurrent(t *testing.T, fake *storage.FakeBackend, cfg *config.Config, artifactBody string) {
+	t.Helper()
+	seedRestorePreviousCurrentManifestOnly(t, fake, cfg)
+	previousPrefix := artifacts.S3SessionPrefix(cfg.Pipeline.Storage.S3.RootPrefix, cfg.Session.Campaign, cfg.Session.PreviousSessionID)
+	seedRestoreObject(fake, previousPrefix+"artifacts/session_recap.md", []byte(artifactBody))
+}
+
+func seedRestorePreviousCurrentManifestOnly(t *testing.T, fake *storage.FakeBackend, cfg *config.Config) {
+	t.Helper()
+	previousPrefix := artifacts.S3SessionPrefix(cfg.Pipeline.Storage.S3.RootPrefix, cfg.Session.Campaign, cfg.Session.PreviousSessionID)
+	manifestKey, runIDKey := artifacts.ResolveCurrentStateKeys(previousPrefix)
+	previousRunID := "20260426T010203Z-a1b2c3d4"
+	seedRestoreObject(fake, runIDKey, []byte(previousRunID+"\n"))
+
+	m := manifest.New(cfg.Session.PreviousSessionID, nowUTC())
+	m.Campaign = cfg.Session.Campaign
+	m.RunID = previousRunID
+	data, err := json.Marshal(m)
+	if err != nil {
+		t.Fatalf("marshal previous restore manifest: %v", err)
+	}
+	seedRestoreObject(fake, manifestKey, append(data, '\n'))
+}
+
 func mustReadEquals(t *testing.T, path, want string) {
 	t.Helper()
 	data, err := os.ReadFile(path)

internal/app/restore_plan.go

@@ -2,6 +2,7 @@ package app
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"io"
 	"os"
@@ -13,6 +14,8 @@ import (
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
 	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/pathsafe"
+	"gitea.maximumdirect.net/eric/narratio/internal/previouscache"
 )
 
 // RestoreActionKind identifies one restore planner action.
@@ -114,6 +117,12 @@ func buildRestorePlan(ctx context.Context, cfg *config.Config, current *RemoteCu
 		actions = append(actions, action)
 	}
 
+	previousActions, err := buildPreviousCacheRestoreActions(ctx, cfg, sessionPaths, store, opts.Force)
+	if err != nil {
+		return nil, err
+	}
+	actions = append(actions, previousActions...)
+
 	sort.Slice(actions, func(i, j int) bool {
 		if actions[i].LocalRelativePath == actions[j].LocalRelativePath {
 			return actions[i].RemoteKey < actions[j].RemoteKey
@@ -195,7 +204,7 @@ func restoreLocalRelativePathForKey(sessionPrefix, currentManifestKey, key strin
 		return cleanRel, true, nil
 	}
 	if cleanRel == config.PathPreviousDirSegment || strings.HasPrefix(cleanRel, config.PathPreviousDirSegment+"/") {
-		return cleanRel, true, nil
+		return "", false, nil
 	}
 	if includeAudio && (cleanRel == config.PathAudioDirSegment || strings.HasPrefix(cleanRel, config.PathAudioDirSegment+"/")) {
 		return cleanRel, true, nil
@@ -208,19 +217,46 @@ func joinWithinSessionRoot(sessionRoot, relative string) (string, error) {
 	if strings.TrimSpace(sessionRoot) == "" {
 		return "", fmt.Errorf("session root is required")
 	}
-	cleanRel := path.Clean(strings.TrimSpace(relative))
-	if cleanRel == "." || cleanRel == "" {
-		return "", fmt.Errorf("relative path is required")
+	joined, err := pathsafe.JoinSlashRelativeUnderRoot(sessionRoot, filepath.ToSlash(strings.TrimSpace(relative)))
+	if err != nil {
+		if errors.Is(err, pathsafe.ErrRelativePathRequired) {
+			return "", fmt.Errorf("relative path is required")
+		}
+		if errors.Is(err, pathsafe.ErrRelativePathEscape) || errors.Is(err, pathsafe.ErrRelativePathAbsolute) {
+			return "", fmt.Errorf("relative path escapes session root")
+		}
+		return "", fmt.Errorf("join relative path under session root: %w", err)
 	}
-	if cleanRel == ".." || strings.HasPrefix(cleanRel, "../") || strings.HasPrefix(cleanRel, "/") {
-		return "", fmt.Errorf("relative path escapes session root")
+	return joined, nil
+}
+
+func buildPreviousCacheRestoreActions(
+	ctx context.Context,
+	cfg *config.Config,
+	sessionPaths artifacts.SessionPaths,
+	store storage.ObjectStore,
+	force bool,
+) ([]RestoreAction, error) {
+	if cfg == nil || cfg.Pipeline == nil || cfg.Pipeline.Scriptorium == nil {
+		return nil, nil
 	}
-	abs := filepath.Clean(filepath.Join(sessionRoot, filepath.FromSlash(cleanRel)))
-	root := filepath.Clean(sessionRoot)
-	if abs != root && !strings.HasPrefix(abs, root+string(filepath.Separator)) {
-		return "", fmt.Errorf("resolved local path escapes session root")
+	requirements := artifacts.CollectPreviousArtifactRequirements(cfg.Pipeline.Scriptorium.Artifacts)
+	if len(requirements) == 0 {
+		return nil, nil
 	}
-	return abs, nil
+	plan, err := previouscache.BuildPlan(ctx, cfg, sessionPaths, requirements, store)
+	if err != nil {
+		return nil, fmt.Errorf("plan previous-session cache restore: %w", err)
+	}
+	actions := make([]RestoreAction, 0, len(plan.Records))
+	for _, record := range plan.Records {
+		action, err := classifyRestoreAction(ctx, store, storage.ObjectInfo{Key: record.RemoteKey}, record.LocalRelativePath, record.LocalPath, force)
+		if err != nil {
+			return nil, fmt.Errorf("classify previous-session cache object %q: %w", record.RemoteKey, err)
+		}
+		actions = append(actions, action)
+	}
+	return actions, nil
 }
 
 func classifyRestoreAction(
@@ -302,7 +338,7 @@ func classifyRestoreAction(
 	if err != nil {
 		return RestoreAction{}, fmt.Errorf("checksum local file: %w", err)
 	}
-	remotePath, err := downloadObjectToTemp(ctx, store, action.RemoteKey, "narratio-restore-plan-remote-*.tmp")
+	remotePath, err := storage.DownloadObjectToTemp(ctx, store, action.RemoteKey, "narratio-restore-plan-remote-*.tmp")
 	if err != nil {
 		return RestoreAction{}, fmt.Errorf("download remote object: %w", err)
 	}

internal/app/restore_plan_test.go

@@ -22,7 +22,7 @@ func TestRestorePlanDefaultScope(t *testing.T) {
 	seedRestoreObject(store, current.SessionPrefix+"artifacts/session_recap.md", []byte("# recap\n"))
 	seedRestoreObject(store, current.SessionPrefix+"audio/alice.flac", []byte("audio"))
 	seedRestoreObject(store, current.SessionPrefix+"runs/20260519T010203Z-a1b2/manifest.json", []byte("{}"))
-	seedRestoreObject(store, current.SessionPrefix+"logs/archive.log", []byte("log"))
+	seedRestoreObject(store, current.SessionPrefix+"logs/publish.log", []byte("log"))
 
 	plan, err := buildRestorePlan(context.Background(), cfg, current, store, RestorePlanOptions{})
 	if err != nil {
@@ -86,6 +86,27 @@ func TestRestorePlanExistingAudioUsesSizeWithoutRemoteChecksumDownload(t *testin
 }
 
 func TestRestorePlanIncludesPreviousCacheByDefault(t *testing.T) {
+	cfg := restorePlanConfig(t)
+	configureRestorePlanPreviousRequirement(cfg, true)
+	current := restorePlanCurrentState(t, cfg)
+	store := &storage.FakeBackend{}
+
+	seedRestoreObject(store, current.CurrentManifestKey, []byte(`{"session_id":"2026-05-03"}`))
+	seedRestorePreviousCurrent(t, store, cfg, "# previous recap\n")
+
+	plan, err := buildRestorePlan(context.Background(), cfg, current, store, RestorePlanOptions{})
+	if err != nil {
+		t.Fatalf("buildRestorePlan() error = %v", err)
+	}
+
+	got := actionRelPaths(plan.Actions)
+	want := []string{"manifest.json", "previous/artifacts/session_recap.md", "previous/manifest.json"}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("action local paths = %#v, want %#v", got, want)
+	}
+}
+
+func TestRestorePlanIgnoresCurrentSessionArchivedPreviousCache(t *testing.T) {
 	cfg := restorePlanConfig(t)
 	current := restorePlanCurrentState(t, cfg)
 	store := &storage.FakeBackend{}
@@ -100,12 +121,76 @@ func TestRestorePlanIncludesPreviousCacheByDefault(t *testing.T) {
 	}
 
 	got := actionRelPaths(plan.Actions)
-	want := []string{"manifest.json", "previous/artifacts/session_recap.md", "previous/manifest.json"}
+	want := []string{"manifest.json"}
 	if !reflect.DeepEqual(got, want) {
 		t.Fatalf("action local paths = %#v, want %#v", got, want)
 	}
 }
 
+func TestRestorePlanMissingOptionalPreviousCacheSkipsArtifact(t *testing.T) {
+	cfg := restorePlanConfig(t)
+	configureRestorePlanPreviousRequirement(cfg, false)
+	current := restorePlanCurrentState(t, cfg)
+	store := &storage.FakeBackend{}
+
+	seedRestoreObject(store, current.CurrentManifestKey, []byte(`{"session_id":"2026-05-03"}`))
+	seedRestorePreviousCurrentManifestOnly(t, store, cfg)
+
+	plan, err := buildRestorePlan(context.Background(), cfg, current, store, RestorePlanOptions{})
+	if err != nil {
+		t.Fatalf("buildRestorePlan() error = %v", err)
+	}
+
+	got := actionRelPaths(plan.Actions)
+	want := []string{"manifest.json", "previous/manifest.json"}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("action local paths = %#v, want %#v", got, want)
+	}
+}
+
+func TestRestorePlanMissingRequiredPreviousCacheFails(t *testing.T) {
+	cfg := restorePlanConfig(t)
+	configureRestorePlanPreviousRequirement(cfg, true)
+	current := restorePlanCurrentState(t, cfg)
+	store := &storage.FakeBackend{}
+
+	seedRestoreObject(store, current.CurrentManifestKey, []byte(`{"session_id":"2026-05-03"}`))
+	seedRestorePreviousCurrentManifestOnly(t, store, cfg)
+
+	_, err := buildRestorePlan(context.Background(), cfg, current, store, RestorePlanOptions{})
+	if err == nil || !strings.Contains(err.Error(), "required previous-session artifact") {
+		t.Fatalf("buildRestorePlan() error = %v, want required previous artifact failure", err)
+	}
+}
+
+func TestRestorePlanPreviousCacheConflictRequiresForce(t *testing.T) {
+	cfg := restorePlanConfig(t)
+	configureRestorePlanPreviousRequirement(cfg, true)
+	current := restorePlanCurrentState(t, cfg)
+	store := &storage.FakeBackend{}
+
+	seedRestoreObject(store, current.CurrentManifestKey, []byte(`{"session_id":"2026-05-03"}`))
+	seedRestorePreviousCurrent(t, store, cfg, "# remote previous recap\n")
+	sessionRoot := artifacts.SessionWorkDirForCampaign(cfg.Pipeline.Workspace.Root, cfg.Session.Campaign, cfg.Session.SessionID)
+	mustWriteTestFile(t, filepath.Join(sessionRoot, "previous", "artifacts", "session_recap.md"), "# local previous recap\n")
+
+	plan, err := buildRestorePlan(context.Background(), cfg, current, store, RestorePlanOptions{})
+	if err != nil {
+		t.Fatalf("buildRestorePlan() error = %v", err)
+	}
+	if plan.ConflictCount != 1 {
+		t.Fatalf("ConflictCount = %d, want 1", plan.ConflictCount)
+	}
+
+	plan, err = buildRestorePlan(context.Background(), cfg, current, store, RestorePlanOptions{Force: true})
+	if err != nil {
+		t.Fatalf("buildRestorePlan(force) error = %v", err)
+	}
+	if plan.ConflictCount != 0 {
+		t.Fatalf("force ConflictCount = %d, want 0", plan.ConflictCount)
+	}
+}
+
 func TestRestorePlanClassifiesSameAndConflict(t *testing.T) {
 	cfg := restorePlanConfig(t)
 	current := restorePlanCurrentState(t, cfg)
@@ -207,6 +292,10 @@ func restorePlanConfig(t *testing.T) *config.Config {
 	return &config.Config{
 		Pipeline: &config.PipelineConfig{
 			Workspace: config.WorkspaceConfig{Root: workspaceRoot},
+			Storage: config.StorageConfig{S3: &config.StorageS3Config{
+				Bucket:     "test-bucket",
+				RootPrefix: "dnd",
+			}},
 		},
 		Session: &config.SessionConfig{
 			SessionID: "2026-05-03",
@@ -215,10 +304,28 @@ func restorePlanConfig(t *testing.T) *config.Config {
 	}
 }
 
+func configureRestorePlanPreviousRequirement(cfg *config.Config, required bool) {
+	cfg.Session.PreviousSessionID = "2026-04-26"
+	cfg.Pipeline.Scriptorium = &config.ScriptoriumConfig{
+		Artifacts: map[string]config.ScriptoriumArtifactConfig{
+			"session_recap": {
+				Enabled:    true,
+				OutputPath: "artifacts/session_recap.md",
+				Inputs: map[string]config.ScriptoriumInputConfig{
+					"previous_recap": {
+						Source:   "narratio.previous_session.artifact.session_recap",
+						Required: required,
+					},
+				},
+			},
+		},
+	}
+}
+
 func restorePlanCurrentState(t *testing.T, cfg *config.Config) *RemoteCurrentState {
 	t.Helper()
 	sessionPrefix := artifacts.S3SessionPrefix("dnd", cfg.Session.Campaign, cfg.Session.SessionID)
-	manifestKey, runIDKey := artifacts.ResolveArchiveCurrentStateKeys(sessionPrefix)
+	manifestKey, runIDKey := artifacts.ResolveCurrentStateKeys(sessionPrefix)
 	return &RemoteCurrentState{
 		Bucket:             "test-bucket",
 		SessionPrefix:      sessionPrefix,

internal/app/restore_report.go

@@ -201,7 +201,7 @@ func writeRestoreSuccessSummary(out io.Writer, report *RestoreReport) error {
 	if report == nil {
 		return fmt.Errorf("restore report is required")
 	}
-	if _, err := fmt.Fprintf(out, "Restored session archive for %s/%s\n", report.Campaign, report.SessionID); err != nil {
+	if _, err := fmt.Fprintf(out, "Restored session state for %s/%s\n", report.Campaign, report.SessionID); err != nil {
 		return err
 	}
 	if _, err := fmt.Fprintf(out, "Remote run: %s\n", report.RunID); err != nil {

internal/app/restore_test.go

@@ -18,7 +18,7 @@ func TestExecuteRestoreHelp(t *testing.T) {
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
 
-	code := Execute([]string{"restore", "--help"}, &stdout, &stderr)
+	code := Execute([]string{"session", "restore", "--help"}, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("exit code = %d, want 0", code)
 	}
@@ -26,7 +26,7 @@ func TestExecuteRestoreHelp(t *testing.T) {
 		t.Fatalf("stderr = %q, want empty", stderr.String())
 	}
 	out := stdout.String()
-	if !strings.Contains(out, "Usage: narratio restore") {
+	if !strings.Contains(out, "Usage: narratio session restore <session_id>") {
 		t.Fatalf("stdout = %q, want restore usage", out)
 	}
 	if !strings.Contains(out, "--include-audio") {
@@ -79,11 +79,10 @@ func TestExecuteRestoreRecognizedAndReturnsNYI(t *testing.T) {
 	var stderr bytes.Buffer
 	code := Execute(
 		[]string{
-			"restore",
+			"session", "restore", "2026-05-03",
 			"--config", pipelinePath,
-			"--campaign", campaignPath,
+			"--campaign-file", campaignPath,
 			"--session", sessionPath,
-			"--session-id", "2026-05-03",
 			"--dry-run",
 			"--force",
 			"--include-audio",
@@ -124,7 +123,7 @@ func TestExecuteRestoreRejectsUnexpectedPositionalArguments(t *testing.T) {
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"restore", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "extra"}, &stdout, &stderr)
+	code := Execute([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "extra"}, &stdout, &stderr)
 	if code == 0 {
 		t.Fatal("exit code = 0, want non-zero")
 	}
@@ -146,7 +145,7 @@ func TestExecuteRestoreFailsWhenStorageBackendNotConfigured(t *testing.T) {
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"restore", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath}, &stdout, &stderr)
+	code := Execute([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
 	if code == 0 {
 		t.Fatal("exit code = 0, want non-zero")
 	}
@@ -174,7 +173,7 @@ func TestExecuteRestoreDiscoveryErrorSurfaced(t *testing.T) {
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"restore", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath}, &stdout, &stderr)
+	code := Execute([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
 	if code == 0 {
 		t.Fatal("exit code = 0, want non-zero")
 	}
@@ -263,11 +262,10 @@ func TestExecuteRestoreLoadsSecretsBeforeObjectStoreInit(t *testing.T) {
 	var stderr bytes.Buffer
 	code := Execute(
 		[]string{
-			"restore",
+			"session", "restore", "2026-05-03",
 			"--config", pipelinePath,
-			"--campaign", campaignPath,
+			"--campaign-file", campaignPath,
 			"--session", sessionPath,
-			"--session-id", "2026-05-03",
 			"--dry-run",
 		},
 		&stdout,
@@ -315,7 +313,7 @@ func TestExecuteRestoreNonDryRunConflictFailsBeforeNYI(t *testing.T) {
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"restore", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath}, &stdout, &stderr)
+	code := Execute([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
 	if code == 0 {
 		t.Fatal("exit code = 0, want non-zero")
 	}
@@ -367,11 +365,11 @@ func TestExecuteRestoreNonDryRunForceExecutesPlan(t *testing.T) {
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"restore", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "--force"}, &stdout, &stderr)
+	code := Execute([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--force"}, &stdout, &stderr)
 	if code != 0 {
 		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
 	}
-	if !strings.Contains(stdout.String(), "Restored session archive for sample-campaign/2026-05-03") {
+	if !strings.Contains(stdout.String(), "Restored session state for sample-campaign/2026-05-03") {
 		t.Fatalf("stdout = %q, want completion summary", stdout.String())
 	}
 	if stderr.Len() != 0 {

internal/app/restore_workflow_test.go

@@ -46,11 +46,10 @@ func TestRestoreThenRunStageForceAnalyzeUsesRestoredDurableState(t *testing.T) {
 	var stderr bytes.Buffer
 	restoreCode := Execute(
 		[]string{
-			"restore",
+			"session", "restore", cfg.Session.SessionID,
 			"--config", pipelinePath,
-			"--campaign", campaignPath,
+			"--campaign-file", campaignPath,
 			"--session", sessionPath,
-			"--session-id", cfg.Session.SessionID,
 		},
 		&stdout,
 		&stderr,
@@ -85,14 +84,12 @@ func TestRestoreThenRunStageForceAnalyzeUsesRestoredDurableState(t *testing.T) {
 	stderr.Reset()
 	runStageCode := Execute(
 		[]string{
-			"run-stage",
+			"run-stage", "analyze", cfg.Session.SessionID,
 			"--config", pipelinePath,
-			"--campaign", campaignPath,
+			"--campaign-file", campaignPath,
 			"--session", sessionPath,
-			"--session-id", cfg.Session.SessionID,
 			"--force",
 			"--artifacts", "player_handout",
-			"analyze",
 		},
 		&stdout,
 		&stderr,
@@ -170,20 +167,22 @@ scriptorium:
       output_path: artifacts/session_recap.md
       inputs:
         transcript:
-          source: narratio.transcript.trimmed
+          source: narratio.transcript.final_trimmed
           required: true
         previous_recap:
           source: narratio.previous_session.artifact.session_recap
           required: true
+`)
+	appendRestoreWorkflowScriptoriumConfig(t, sessionPath, `
+previous_session_id: 2026-04-26
 `)
 
 	fakeStore := &storage.FakeBackend{}
 	cfg, sessionPrefix, manifestKey, runIDKey := seedRestoreCommittedState(t, fakeStore, pipelinePath, campaignPath, sessionPath)
 	seedRestoreObject(fakeStore, runIDKey, []byte("20260519T010203Z-a1b2c3d4\n"))
 	seedRestoreObject(fakeStore, manifestKey, restoreWorkflowManifestJSON(t, cfg.Session.SessionID, cfg.Session.Campaign))
-	seedRestoreObject(fakeStore, sessionPrefix+"transcripts/trimmed.json", []byte(`{"segments":[]}`+"\n"))
-	seedRestoreObject(fakeStore, sessionPrefix+"previous/manifest.json", []byte(`{"session_id":"2026-04-26"}`))
-	seedRestoreObject(fakeStore, sessionPrefix+"previous/artifacts/session_recap.md", []byte("# previous recap\n"))
+	seedRestoreObject(fakeStore, sessionPrefix+"transcripts/final.trimmed.json", []byte(`{"segments":[]}`+"\n"))
+	seedRestorePreviousCurrent(t, fakeStore, cfg, "# previous recap\n")
 
 	restoreWithStoreAndRealPhases(t, fakeStore)
 
@@ -191,11 +190,10 @@ scriptorium:
 	var stderr bytes.Buffer
 	restoreCode := Execute(
 		[]string{
-			"restore",
+			"session", "restore", cfg.Session.SessionID,
 			"--config", pipelinePath,
-			"--campaign", campaignPath,
+			"--campaign-file", campaignPath,
 			"--session", sessionPath,
-			"--session-id", cfg.Session.SessionID,
 		},
 		&stdout,
 		&stderr,
@@ -208,8 +206,14 @@ scriptorium:
 	}
 
 	sessionRoot := artifacts.SessionWorkDirForCampaign(workspaceRoot, cfg.Session.Campaign, cfg.Session.SessionID)
-	mustReadEquals(t, filepath.Join(sessionRoot, "transcripts", "trimmed.json"), `{"segments":[]}`+"\n")
-	mustReadEquals(t, filepath.Join(sessionRoot, "previous", "manifest.json"), `{"session_id":"2026-04-26"}`)
+	mustReadEquals(t, filepath.Join(sessionRoot, "transcripts", "final.trimmed.json"), `{"segments":[]}`+"\n")
+	previousManifestBytes, err := os.ReadFile(filepath.Join(sessionRoot, "previous", "manifest.json"))
+	if err != nil {
+		t.Fatalf("read restored previous manifest: %v", err)
+	}
+	if !strings.Contains(string(previousManifestBytes), `"session_id":"2026-04-26"`) {
+		t.Fatalf("restored previous manifest = %q, want previous session id", string(previousManifestBytes))
+	}
 	mustReadEquals(t, filepath.Join(sessionRoot, "previous", "artifacts", "session_recap.md"), "# previous recap\n")
 
 	scriptoriumFake := &scriptorium.FakeRunner{}
@@ -236,14 +240,12 @@ scriptorium:
 	stderr.Reset()
 	runStageCode := Execute(
 		[]string{
-			"run-stage",
+			"run-stage", "analyze", cfg.Session.SessionID,
 			"--config", pipelinePath,
-			"--campaign", campaignPath,
+			"--campaign-file", campaignPath,
 			"--session", sessionPath,
-			"--session-id", cfg.Session.SessionID,
 			"--force",
 			"--artifacts", "session_recap",
-			"analyze",
 		},
 		&stdout,
 		&stderr,
@@ -261,7 +263,7 @@ scriptorium:
 		t.Fatalf("scriptorium run requests = %d, want 1", len(scriptoriumFake.RunRequests))
 	}
 	req := scriptoriumFake.RunRequests[0]
-	if got := req.InputPaths["transcript"]; got != filepath.Join(sessionRoot, "transcripts", "trimmed.json") {
+	if got := req.InputPaths["transcript"]; got != filepath.Join(sessionRoot, "transcripts", "final.trimmed.json") {
 		t.Fatalf("transcript input = %q, want trimmed transcript path", got)
 	}
 	if got := req.InputPaths["previous_recap"]; got != filepath.Join(sessionRoot, "previous", "artifacts", "session_recap.md") {

internal/app/resume.go

@@ -1,113 +0,0 @@
-package app
-
-import (
-	"context"
-	"flag"
-	"fmt"
-	"io"
-
-	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
-	"gitea.maximumdirect.net/eric/narratio/internal/config"
-	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
-)
-
-// Resume continues execution from the first non-succeeded stage in the manifest.
-func Resume(ctx context.Context, args []string, out io.Writer) error {
-	fs := flag.NewFlagSet("resume", flag.ContinueOnError)
-	fs.SetOutput(io.Discard)
-
-	var pipelinePath string
-	var campaignPath string
-	var sessionPath string
-	var sessionID string
-	var previousSessionID string
-	var force bool
-	var selectedArtifacts artifactSelectionFlag
-	fs.StringVar(&pipelinePath, "config", "", "path to pipeline.yml (optional; defaults searched)")
-	fs.StringVar(&campaignPath, "campaign", "", "path to campaign.yml (optional; defaults searched)")
-	fs.StringVar(&sessionPath, "session", "", "path to session.yml")
-	fs.StringVar(&sessionID, "session-id", "", "session identifier for session.yml templates")
-	fs.StringVar(&previousSessionID, "previous-session-id", "", "previous session identifier for session.yml templates")
-	fs.BoolVar(&force, "force", false, "force stage execution")
-	fs.Var(&selectedArtifacts, "artifacts", "artifact names to execute during analyze (comma-separated or repeatable)")
-
-	if err := fs.Parse(args); err != nil {
-		return fmt.Errorf("resume: invalid flags: %w", err)
-	}
-	if fs.NArg() != 0 {
-		return fmt.Errorf("resume: unexpected positional arguments")
-	}
-	cfg, err := loadCommandConfig(ctx, pipelinePath, campaignPath, sessionPath, config.SessionLoadOptions{
-		SessionID:         sessionID,
-		PreviousSessionID: previousSessionID,
-	})
-	if err != nil {
-		return fmt.Errorf("resume: %w", err)
-	}
-	if err := config.Validate(cfg); err != nil {
-		return fmt.Errorf("resume: %w", err)
-	}
-	normalizedArtifacts, err := selectedArtifacts.Normalize()
-	if err != nil {
-		return fmt.Errorf("resume: invalid --artifacts: %w", err)
-	}
-	if err := validateSelectedAnalyzeArtifacts(cfg, normalizedArtifacts); err != nil {
-		return fmt.Errorf("resume: %w", err)
-	}
-
-	full := BuildFullPlan()
-	selected := full
-	if !force {
-		m, err := loadManifestIfPresent(ctx, cfg)
-		if err != nil {
-			return fmt.Errorf("resume: %w", err)
-		}
-		if m != nil {
-			start := firstNonSucceededIndex(full, m)
-			if start >= len(full) {
-				_, err := fmt.Fprintf(out, "narratio resume: session %s has no remaining stages\n", cfg.Session.SessionID)
-				return err
-			}
-			selected = full[start:]
-		}
-	}
-
-	summary, err := executeStagesFn(ctx, cfg, selected, RunOptions{
-		Force:             force,
-		SelectedArtifacts: normalizedArtifacts,
-	})
-	if err != nil {
-		return fmt.Errorf("resume: %w", err)
-	}
-
-	_, err = fmt.Fprintf(
-		out,
-		"narratio resume: session %s; executed=%d skipped=%d; manifest=%s\n",
-		summary.SessionID,
-		len(summary.Executed),
-		len(summary.Skipped),
-		summary.ManifestPath,
-	)
-	return err
-}
-
-func loadManifestIfPresent(ctx context.Context, cfg *config.Config) (*manifest.Manifest, error) {
-	path := artifacts.SessionManifestPathForCampaign(
-		cfg.Pipeline.Workspace.Root,
-		cfg.Session.Campaign,
-		cfg.Session.SessionID,
-	)
-	exists, err := fileExists(path)
-	if err != nil {
-		return nil, fmt.Errorf("check manifest %q: %w", path, err)
-	}
-	if !exists {
-		return nil, nil
-	}
-	store := &manifest.LocalStore{}
-	m, err := store.Load(ctx, path)
-	if err != nil {
-		return nil, fmt.Errorf("load manifest %q: %w", path, err)
-	}
-	return m, nil
-}

internal/app/run.go

@@ -14,31 +14,20 @@ func Run(ctx context.Context, args []string, out io.Writer) error {
 	fs := flag.NewFlagSet("run", flag.ContinueOnError)
 	fs.SetOutput(io.Discard)
 
-	var pipelinePath string
-	var campaignPath string
-	var sessionPath string
-	var sessionID string
-	var previousSessionID string
+	var flags commonConfigFlags
 	var force bool
 	var selectedArtifacts artifactSelectionFlag
-	fs.StringVar(&pipelinePath, "config", "", "path to pipeline.yml (optional; defaults searched)")
-	fs.StringVar(&campaignPath, "campaign", "", "path to campaign.yml (optional; defaults searched)")
-	fs.StringVar(&sessionPath, "session", "", "path to session.yml")
-	fs.StringVar(&sessionID, "session-id", "", "session identifier for session.yml templates")
-	fs.StringVar(&previousSessionID, "previous-session-id", "", "previous session identifier for session.yml templates")
+	addCommonConfigFlags(fs, &flags)
 	fs.BoolVar(&force, "force", false, "force stage execution (reserved for future behavior)")
-	fs.Var(&selectedArtifacts, "artifacts", "artifact names to execute during analyze (comma-separated or repeatable)")
+	fs.Var(&selectedArtifacts, "artifacts", "configured artifact names to execute and publish (comma-separated or repeatable)")
 
-	if err := fs.Parse(args); err != nil {
-		return fmt.Errorf("run: invalid flags: %w", err)
+	if err := parseSessionAwareFlags("run", fs, args, &flags.sessionID); err != nil {
+		return err
 	}
-	if fs.NArg() != 0 {
-		return fmt.Errorf("run: unexpected positional arguments")
+	if flags.sessionID == "" {
+		return fmt.Errorf("run: session_id is required")
 	}
-	cfg, err := loadCommandConfig(ctx, pipelinePath, campaignPath, sessionPath, config.SessionLoadOptions{
-		SessionID:         sessionID,
-		PreviousSessionID: previousSessionID,
-	})
+	cfg, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.campaignFilePath, flags.sessionPath, flags.sessionOptions())
 	if err != nil {
 		return fmt.Errorf("run: %w", err)
 	}
@@ -49,7 +38,7 @@ func Run(ctx context.Context, args []string, out io.Writer) error {
 	if err != nil {
 		return fmt.Errorf("run: invalid --artifacts: %w", err)
 	}
-	if err := validateSelectedAnalyzeArtifacts(cfg, normalizedArtifacts); err != nil {
+	if err := validateSelectedArtifacts(cfg, normalizedArtifacts); err != nil {
 		return fmt.Errorf("run: %w", err)
 	}
 

internal/app/run_control.go

@@ -1,8 +1,12 @@
 package app
 
 import (
+	"context"
+	"fmt"
 	"time"
 
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
 	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
 	"gitea.maximumdirect.net/eric/narratio/internal/stage"
 )
@@ -43,13 +47,25 @@ func stageSucceeded(m *manifest.Manifest, name string) bool {
 	return sr != nil && sr.Status == manifest.StatusSucceeded
 }
 
-func firstNonSucceededIndex(stages []stage.Stage, m *manifest.Manifest) int {
-	for i, s := range stages {
-		if !stageSucceeded(m, s.Name()) {
-			return i
-		}
+func loadManifestIfPresent(ctx context.Context, cfg *config.Config) (*manifest.Manifest, error) {
+	path := artifacts.SessionManifestPathForCampaign(
+		cfg.Pipeline.Workspace.Root,
+		cfg.Session.Campaign,
+		cfg.Session.SessionID,
+	)
+	exists, err := fileExists(path)
+	if err != nil {
+		return nil, fmt.Errorf("check manifest %q: %w", path, err)
 	}
-	return len(stages)
+	if !exists {
+		return nil, nil
+	}
+	store := &manifest.LocalStore{}
+	m, err := store.Load(ctx, path)
+	if err != nil {
+		return nil, fmt.Errorf("load manifest %q: %w", path, err)
+	}
+	return m, nil
 }
 
 func canonicalStageNames() []string {

internal/app/run_control_test.go

@@ -8,18 +8,6 @@ import (
 	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
 )
 
-func TestFirstNonSucceededIndex(t *testing.T) {
-	stages := BuildFullPlan()
-	m := manifest.New("2026-05-03", time.Now().UTC())
-	m.MarkStageSucceeded("prepare", time.Now().UTC(), nil)
-	m.MarkStageSucceeded("transcribe", time.Now().UTC(), nil)
-
-	got := firstNonSucceededIndex(stages, m)
-	if got != 2 {
-		t.Fatalf("firstNonSucceededIndex() = %d, want 2", got)
-	}
-}
-
 func TestDecideStageActions(t *testing.T) {
 	stages := BuildFullPlan()[:2]
 	m := manifest.New("2026-05-03", time.Now().UTC())
@@ -44,7 +32,7 @@ func TestDecideStageActions(t *testing.T) {
 
 func TestDownstreamStageNames(t *testing.T) {
 	got := downstreamStageNames("polish")
-	want := []string{"normalize", "trim", "analyze", "archive", "notify"}
+	want := []string{"normalize", "trim", "analyze", "publish", "notify"}
 	if !reflect.DeepEqual(got, want) {
 		t.Fatalf("downstreamStageNames(polish) = %#v, want %#v", got, want)
 	}
@@ -65,11 +53,11 @@ func TestInvalidateDownstreamSucceededStages(t *testing.T) {
 	m.MarkStageSucceeded("normalize", now, nil)
 	m.MarkStageSucceeded("trim", now, nil)
 	m.MarkStageFailed("analyze", now, "analysis failed")
-	m.MarkStageSucceeded("archive", now, nil)
+	m.MarkStageSucceeded("publish", now, nil)
 	m.MarkStageSucceeded("notify", now, nil)
 
 	got := invalidateDownstreamSucceededStages(m, "polish", now.Add(1*time.Second))
-	want := []string{"normalize", "trim", "archive", "notify"}
+	want := []string{"normalize", "trim", "publish", "notify"}
 	if !reflect.DeepEqual(got, want) {
 		t.Fatalf("invalidateDownstreamSucceededStages() = %#v, want %#v", got, want)
 	}

internal/app/run_stage.go

@@ -5,53 +5,73 @@ import (
 	"flag"
 	"fmt"
 	"io"
+	"strings"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
 )
 
 // RunStage executes exactly one selected stage.
 func RunStage(ctx context.Context, args []string, out io.Writer) error {
+	var stageName string
+	var positionalSessionID string
+	if len(args) >= 2 && !isCLIFlagToken(args[0]) && !isCLIFlagToken(args[1]) {
+		stageName = strings.TrimSpace(args[0])
+		positionalSessionID = strings.TrimSpace(args[1])
+		args = append([]string(nil), args[2:]...)
+	}
+
 	fs := flag.NewFlagSet("run-stage", flag.ContinueOnError)
 	fs.SetOutput(io.Discard)
 
-	var pipelinePath string
-	var campaignPath string
-	var sessionPath string
-	var sessionID string
-	var previousSessionID string
+	var flags commonConfigFlags
 	var force bool
 	var selectedArtifacts artifactSelectionFlag
-	fs.StringVar(&pipelinePath, "config", "", "path to pipeline.yml (optional; defaults searched)")
-	fs.StringVar(&campaignPath, "campaign", "", "path to campaign.yml (optional; defaults searched)")
-	fs.StringVar(&sessionPath, "session", "", "path to session.yml")
-	fs.StringVar(&sessionID, "session-id", "", "session identifier for session.yml templates")
-	fs.StringVar(&previousSessionID, "previous-session-id", "", "previous session identifier for session.yml templates")
+	addCommonConfigFlags(fs, &flags)
 	fs.BoolVar(&force, "force", false, "force stage execution (reserved for future behavior)")
-	fs.Var(&selectedArtifacts, "artifacts", "artifact names to execute during analyze (comma-separated or repeatable)")
+	fs.Var(&selectedArtifacts, "artifacts", "configured artifact names to execute or publish (comma-separated or repeatable)")
 
 	if err := fs.Parse(args); err != nil {
 		return fmt.Errorf("run-stage: invalid flags: %w", err)
 	}
-	if fs.NArg() != 1 {
-		return fmt.Errorf("run-stage: expected exactly one stage name")
+	if stageName == "" {
+		switch fs.NArg() {
+		case 2:
+			stageName = strings.TrimSpace(fs.Arg(0))
+			positionalSessionID = strings.TrimSpace(fs.Arg(1))
+		case 1:
+			if strings.TrimSpace(flags.sessionID) == "" {
+				return fmt.Errorf("run-stage: expected stage name and session_id")
+			}
+			stageName = strings.TrimSpace(fs.Arg(0))
+		default:
+			return fmt.Errorf("run-stage: expected stage name and session_id")
+		}
+	} else if fs.NArg() != 0 {
+		return fmt.Errorf("run-stage: unexpected positional arguments")
+	}
+	if err := applyPositionalSessionID("run-stage", positionalSessionID, &flags.sessionID); err != nil {
+		return err
+	}
+	if strings.TrimSpace(flags.sessionID) == "" {
+		return fmt.Errorf("run-stage: session_id is required")
 	}
 	normalizedArtifacts, err := selectedArtifacts.Normalize()
 	if err != nil {
 		return fmt.Errorf("run-stage: invalid --artifacts: %w", err)
 	}
-	stageName := fs.Arg(0)
-	if len(normalizedArtifacts) > 0 && stageName != "analyze" {
-		return fmt.Errorf("run-stage: --artifacts is only supported for stage \"analyze\"")
+	if len(normalizedArtifacts) > 0 && stageName != "analyze" && stageName != "publish" {
+		return fmt.Errorf("run-stage: --artifacts is only supported for stages \"analyze\" and \"publish\"")
 	}
 
 	summary, err := runSingleStageCommand(ctx, singleStageCommand{
 		CommandName:       "run-stage",
 		StageName:         stageName,
-		PipelinePath:      pipelinePath,
-		CampaignPath:      campaignPath,
-		SessionPath:       sessionPath,
-		SessionID:         sessionID,
-		PreviousSessionID: previousSessionID,
+		PipelinePath:      flags.pipelinePath,
+		CampaignPath:      flags.campaignPath,
+		CampaignFilePath:  flags.campaignFilePath,
+		SessionPath:       flags.sessionPath,
+		SessionID:         flags.sessionID,
+		PreviousSessionID: flags.previousSessionID,
 		Force:             force,
 		SelectedArtifacts: normalizedArtifacts,
 	})
@@ -76,24 +96,16 @@ func Analyze(ctx context.Context, args []string, out io.Writer) error {
 	fs := flag.NewFlagSet("analyze", flag.ContinueOnError)
 	fs.SetOutput(io.Discard)
 
-	var pipelinePath string
-	var campaignPath string
-	var sessionPath string
-	var sessionID string
-	var previousSessionID string
+	var flags commonConfigFlags
 	var selectedArtifacts artifactSelectionFlag
-	fs.StringVar(&pipelinePath, "config", "", "path to pipeline.yml (optional; defaults searched)")
-	fs.StringVar(&campaignPath, "campaign", "", "path to campaign.yml (optional; defaults searched)")
-	fs.StringVar(&sessionPath, "session", "", "path to session.yml")
-	fs.StringVar(&sessionID, "session-id", "", "session identifier for session.yml templates")
-	fs.StringVar(&previousSessionID, "previous-session-id", "", "previous session identifier for session.yml templates")
-	fs.Var(&selectedArtifacts, "artifacts", "artifact names to execute during analyze (comma-separated or repeatable)")
+	addCommonConfigFlags(fs, &flags)
+	fs.Var(&selectedArtifacts, "artifacts", "configured artifact names to execute during analyze (comma-separated or repeatable)")
 
-	if err := fs.Parse(args); err != nil {
-		return fmt.Errorf("analyze: invalid flags: %w", err)
+	if err := parseSessionAwareFlags("analyze", fs, args, &flags.sessionID); err != nil {
+		return err
 	}
-	if fs.NArg() != 0 {
-		return fmt.Errorf("analyze: unexpected positional arguments")
+	if strings.TrimSpace(flags.sessionID) == "" {
+		return fmt.Errorf("analyze: session_id is required")
 	}
 	normalizedArtifacts, err := selectedArtifacts.Normalize()
 	if err != nil {
@@ -103,11 +115,12 @@ func Analyze(ctx context.Context, args []string, out io.Writer) error {
 	summary, err := runSingleStageCommand(ctx, singleStageCommand{
 		CommandName:       "analyze",
 		StageName:         "analyze",
-		PipelinePath:      pipelinePath,
-		CampaignPath:      campaignPath,
-		SessionPath:       sessionPath,
-		SessionID:         sessionID,
-		PreviousSessionID: previousSessionID,
+		PipelinePath:      flags.pipelinePath,
+		CampaignPath:      flags.campaignPath,
+		CampaignFilePath:  flags.campaignFilePath,
+		SessionPath:       flags.sessionPath,
+		SessionID:         flags.sessionID,
+		PreviousSessionID: flags.previousSessionID,
 		Force:             true,
 		SelectedArtifacts: normalizedArtifacts,
 	})
@@ -125,11 +138,59 @@ func Analyze(ctx context.Context, args []string, out io.Writer) error {
 	return err
 }
 
+// Publish force-runs the publish stage.
+func Publish(ctx context.Context, args []string, out io.Writer) error {
+	fs := flag.NewFlagSet("publish", flag.ContinueOnError)
+	fs.SetOutput(io.Discard)
+
+	var flags commonConfigFlags
+	var selectedArtifacts artifactSelectionFlag
+	addCommonConfigFlags(fs, &flags)
+	fs.Var(&selectedArtifacts, "artifacts", "configured artifact names to publish (comma-separated or repeatable)")
+
+	if err := parseSessionAwareFlags("publish", fs, args, &flags.sessionID); err != nil {
+		return err
+	}
+	if strings.TrimSpace(flags.sessionID) == "" {
+		return fmt.Errorf("publish: session_id is required")
+	}
+	normalizedArtifacts, err := selectedArtifacts.Normalize()
+	if err != nil {
+		return fmt.Errorf("publish: invalid --artifacts: %w", err)
+	}
+
+	summary, err := runSingleStageCommand(ctx, singleStageCommand{
+		CommandName:       "publish",
+		StageName:         "publish",
+		PipelinePath:      flags.pipelinePath,
+		CampaignPath:      flags.campaignPath,
+		CampaignFilePath:  flags.campaignFilePath,
+		SessionPath:       flags.sessionPath,
+		SessionID:         flags.sessionID,
+		PreviousSessionID: flags.previousSessionID,
+		Force:             true,
+		SelectedArtifacts: normalizedArtifacts,
+	})
+	if err != nil {
+		return err
+	}
+
+	_, err = fmt.Fprintf(
+		out,
+		"narratio publish: executed=%d skipped=%d force=true; manifest=%s\n",
+		len(summary.Executed),
+		len(summary.Skipped),
+		summary.ManifestPath,
+	)
+	return err
+}
+
 type singleStageCommand struct {
 	CommandName       string
 	StageName         string
 	PipelinePath      string
 	CampaignPath      string
+	CampaignFilePath  string
 	SessionPath       string
 	SessionID         string
 	PreviousSessionID string
@@ -143,7 +204,7 @@ func runSingleStageCommand(ctx context.Context, req singleStageCommand) (*RunSum
 		return nil, fmt.Errorf("%s: %w", req.CommandName, err)
 	}
 
-	cfg, err := loadCommandConfig(ctx, req.PipelinePath, req.CampaignPath, req.SessionPath, config.SessionLoadOptions{
+	cfg, err := loadCommandConfig(ctx, req.PipelinePath, req.CampaignPath, req.CampaignFilePath, req.SessionPath, config.SessionLoadOptions{
 		SessionID:         req.SessionID,
 		PreviousSessionID: req.PreviousSessionID,
 	})
@@ -153,7 +214,7 @@ func runSingleStageCommand(ctx context.Context, req singleStageCommand) (*RunSum
 	if err := config.Validate(cfg); err != nil {
 		return nil, fmt.Errorf("%s: %w", req.CommandName, err)
 	}
-	if err := validateSelectedAnalyzeArtifacts(cfg, req.SelectedArtifacts); err != nil {
+	if err := validateSelectedArtifacts(cfg, req.SelectedArtifacts); err != nil {
 		return nil, fmt.Errorf("%s: %w", req.CommandName, err)
 	}
 

internal/app/run_stage_test.go

@@ -13,7 +13,7 @@ import (
 	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
 )
 
-func TestResumeStartsAfterCompletedStages(t *testing.T) {
+func TestRunContinuesAfterCompletedStages(t *testing.T) {
 	workspaceRoot := t.TempDir()
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
 	manifestPath := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03", "manifest.json")
@@ -32,12 +32,12 @@ func TestResumeStartsAfterCompletedStages(t *testing.T) {
 	mustWriteTestFile(t, filepath.Join(workRoot, "inputs", "glossary.yml"), "terms: []\n")
 
 	var out bytes.Buffer
-	err := Resume(context.Background(), []string{"--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath}, &out)
+	err := Run(context.Background(), []string{"2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &out)
 	if err != nil {
-		t.Fatalf("Resume() error = %v", err)
+		t.Fatalf("Run() error = %v", err)
 	}
-	if !strings.Contains(out.String(), "executed=7 skipped=0") {
-		t.Fatalf("output = %q, want executed=7 skipped=0", out.String())
+	if !strings.Contains(out.String(), "executed=7 skipped=2") {
+		t.Fatalf("output = %q, want executed=7 skipped=2", out.String())
 	}
 
 	loaded, err := store.Load(context.Background(), manifestPath)
@@ -49,14 +49,14 @@ func TestResumeStartsAfterCompletedStages(t *testing.T) {
 	}
 }
 
-func TestResumeNoRemainingStages(t *testing.T) {
+func TestRunNoRemainingStagesRecordsSkippedStages(t *testing.T) {
 	workspaceRoot := t.TempDir()
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
 	manifestPath := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03", "manifest.json")
 
 	store := &manifest.LocalStore{}
 	m := manifest.New("2026-05-03", time.Date(2026, 5, 3, 10, 0, 0, 0, time.UTC))
-	for _, name := range []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim", "analyze", "archive", "notify"} {
+	for _, name := range []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim", "analyze", "publish", "notify"} {
 		m.MarkStageSucceeded(name, time.Date(2026, 5, 3, 10, 1, 0, 0, time.UTC), nil)
 	}
 	if err := store.Save(context.Background(), manifestPath, m); err != nil {
@@ -64,20 +64,20 @@ func TestResumeNoRemainingStages(t *testing.T) {
 	}
 
 	var out bytes.Buffer
-	err := Resume(context.Background(), []string{"--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath}, &out)
+	err := Run(context.Background(), []string{"2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &out)
 	if err != nil {
-		t.Fatalf("Resume() error = %v", err)
+		t.Fatalf("Run() error = %v", err)
 	}
-	if !strings.Contains(out.String(), "has no remaining stages") {
-		t.Fatalf("output = %q, want no remaining stages", out.String())
+	if !strings.Contains(out.String(), "executed=0 skipped=9") {
+		t.Fatalf("output = %q, want executed=0 skipped=9", out.String())
 	}
 }
 
-func TestResumeForceRerunsSucceeded(t *testing.T) {
+func TestRunForceRerunsSucceeded(t *testing.T) {
 	workspaceRoot := t.TempDir()
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Type", "application/json")
-		_, _ = w.Write([]byte(`{"source":"resume-force-test","segments":[{"speaker":"alice"}]}`))
+		_, _ = w.Write([]byte(`{"source":"run-force-test","segments":[{"speaker":"alice"}]}`))
 	}))
 	defer srv.Close()
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot, srv.URL)
@@ -85,7 +85,7 @@ func TestResumeForceRerunsSucceeded(t *testing.T) {
 
 	store := &manifest.LocalStore{}
 	m := manifest.New("2026-05-03", time.Date(2026, 5, 3, 10, 0, 0, 0, time.UTC))
-	for _, name := range []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim", "analyze", "archive", "notify"} {
+	for _, name := range []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim", "analyze", "publish", "notify"} {
 		m.MarkStageSucceeded(name, time.Date(2026, 5, 3, 10, 1, 0, 0, time.UTC), nil)
 	}
 	if err := store.Save(context.Background(), manifestPath, m); err != nil {
@@ -93,9 +93,9 @@ func TestResumeForceRerunsSucceeded(t *testing.T) {
 	}
 
 	var out bytes.Buffer
-	err := Resume(context.Background(), []string{"--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "--force"}, &out)
+	err := Run(context.Background(), []string{"2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--force"}, &out)
 	if err != nil {
-		t.Fatalf("Resume() error = %v", err)
+		t.Fatalf("Run() error = %v", err)
 	}
 	if !strings.Contains(out.String(), "executed=9 skipped=0") {
 		t.Fatalf("output = %q, want forced full rerun", out.String())
@@ -107,11 +107,11 @@ func TestRunStageExecutesOnlySelectedStage(t *testing.T) {
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
 	manifestPath := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03", "manifest.json")
 	workRoot := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03")
-	mustWriteTestFile(t, filepath.Join(workRoot, "transcripts", "merged.json"), `{"segments":[]}`)
+	mustWriteTestFile(t, filepath.Join(workRoot, "transcripts", "base.json"), `{"segments":[]}`)
 	mustWriteTestFile(t, filepath.Join(workRoot, "inputs", "glossary.yml"), "terms: []\n")
 
 	var out bytes.Buffer
-	err := RunStage(context.Background(), []string{"--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "polish"}, &out)
+	err := RunStage(context.Background(), []string{"polish", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &out)
 	if err != nil {
 		t.Fatalf("RunStage() error = %v", err)
 	}
@@ -137,7 +137,7 @@ func TestRunStageSkipAndForce(t *testing.T) {
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
 	manifestPath := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03", "manifest.json")
 	workRoot := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03")
-	mustWriteTestFile(t, filepath.Join(workRoot, "transcripts", "merged.json"), `{"segments":[]}`)
+	mustWriteTestFile(t, filepath.Join(workRoot, "transcripts", "base.json"), `{"segments":[]}`)
 	mustWriteTestFile(t, filepath.Join(workRoot, "inputs", "glossary.yml"), "terms: []\n")
 
 	store := &manifest.LocalStore{}
@@ -148,7 +148,7 @@ func TestRunStageSkipAndForce(t *testing.T) {
 	}
 
 	var out bytes.Buffer
-	err := RunStage(context.Background(), []string{"--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "polish"}, &out)
+	err := RunStage(context.Background(), []string{"polish", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &out)
 	if err != nil {
 		t.Fatalf("RunStage() error = %v", err)
 	}
@@ -157,7 +157,7 @@ func TestRunStageSkipAndForce(t *testing.T) {
 	}
 
 	out.Reset()
-	err = RunStage(context.Background(), []string{"--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "--force", "polish"}, &out)
+	err = RunStage(context.Background(), []string{"polish", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--force"}, &out)
 	if err != nil {
 		t.Fatalf("RunStage(force) error = %v", err)
 	}
@@ -166,17 +166,17 @@ func TestRunStageSkipAndForce(t *testing.T) {
 	}
 }
 
-func TestRunStageForceMarksDownstreamStaleAndResumeContinuesFromStale(t *testing.T) {
+func TestRunStageForceMarksDownstreamStaleAndRunContinuesFromStale(t *testing.T) {
 	workspaceRoot := t.TempDir()
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
 	manifestPath := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03", "manifest.json")
 	workRoot := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03")
-	mustWriteTestFile(t, filepath.Join(workRoot, "transcripts", "merged.json"), `{"segments":[]}`)
+	mustWriteTestFile(t, filepath.Join(workRoot, "transcripts", "base.json"), `{"segments":[]}`)
 	mustWriteTestFile(t, filepath.Join(workRoot, "inputs", "glossary.yml"), "terms: []\n")
 
 	store := &manifest.LocalStore{}
 	seed := manifest.New("2026-05-03", time.Date(2026, 5, 3, 10, 0, 0, 0, time.UTC))
-	for _, name := range []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim", "analyze", "archive", "notify"} {
+	for _, name := range []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim", "analyze", "publish", "notify"} {
 		seed.MarkStageSucceeded(name, time.Date(2026, 5, 3, 10, 1, 0, 0, time.UTC), nil)
 	}
 	if err := store.Save(context.Background(), manifestPath, seed); err != nil {
@@ -184,7 +184,7 @@ func TestRunStageForceMarksDownstreamStaleAndResumeContinuesFromStale(t *testing
 	}
 
 	var out bytes.Buffer
-	err := RunStage(context.Background(), []string{"--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "--force", "polish"}, &out)
+	err := RunStage(context.Background(), []string{"polish", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--force"}, &out)
 	if err != nil {
 		t.Fatalf("RunStage(force) error = %v", err)
 	}
@@ -196,19 +196,19 @@ func TestRunStageForceMarksDownstreamStaleAndResumeContinuesFromStale(t *testing
 	if err != nil {
 		t.Fatalf("load manifest after force: %v", err)
 	}
-	for _, name := range []string{"normalize", "trim", "analyze", "archive", "notify"} {
+	for _, name := range []string{"normalize", "trim", "analyze", "publish", "notify"} {
 		if afterForce.Stages[name] == nil || afterForce.Stages[name].Status != manifest.StatusStale {
 			t.Fatalf("stage %q = %#v, want stale", name, afterForce.Stages[name])
 		}
 	}
 
 	out.Reset()
-	err = Resume(context.Background(), []string{"--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath}, &out)
+	err = Run(context.Background(), []string{"2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &out)
 	if err != nil {
-		t.Fatalf("Resume() error = %v", err)
+		t.Fatalf("Run() error = %v", err)
 	}
-	if !strings.Contains(out.String(), "executed=5 skipped=0") {
-		t.Fatalf("output = %q, want resume to execute normalize..notify", out.String())
+	if !strings.Contains(out.String(), "executed=5 skipped=4") {
+		t.Fatalf("output = %q, want run to execute stale downstream stages", out.String())
 	}
 }
 
@@ -217,10 +217,10 @@ func TestRunStageTrimExecutes(t *testing.T) {
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
 	manifestPath := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03", "manifest.json")
 	workRoot := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03")
-	mustWriteTestFile(t, filepath.Join(workRoot, "transcripts", "normalized.json"), `{"segments":[{"id":1},{"id":2}]}`)
+	mustWriteTestFile(t, filepath.Join(workRoot, "transcripts", "final.json"), `{"segments":[{"id":1},{"id":2}]}`)
 
 	var out bytes.Buffer
-	err := RunStage(context.Background(), []string{"--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "trim"}, &out)
+	err := RunStage(context.Background(), []string{"trim", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &out)
 	if err != nil {
 		t.Fatalf("RunStage(trim) error = %v", err)
 	}
@@ -246,10 +246,10 @@ func TestRunStageNormalizeExecutes(t *testing.T) {
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
 	manifestPath := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03", "manifest.json")
 	workRoot := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03")
-	mustWriteTestFile(t, filepath.Join(workRoot, "transcripts", "processed.json"), `{"segments":[{"id":1},{"id":2}]}`)
+	mustWriteTestFile(t, filepath.Join(workRoot, "transcripts", "polished.json"), `{"segments":[{"id":1},{"id":2}]}`)
 
 	var out bytes.Buffer
-	err := RunStage(context.Background(), []string{"--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "normalize"}, &out)
+	err := RunStage(context.Background(), []string{"normalize", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &out)
 	if err != nil {
 		t.Fatalf("RunStage(normalize) error = %v", err)
 	}

internal/app/runner.go

@@ -11,7 +11,6 @@ import (
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/notify"
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/scriptorium"
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/seriatim"
-	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/whisperx"
 	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
@@ -46,7 +45,7 @@ func executeStages(ctx context.Context, cfg *config.Config, stages []stage.Stage
 	if env.Config == nil {
 		env.Config = cfg
 	}
-	env.SelectedAnalyzeArtifacts = append([]string(nil), opts.SelectedArtifacts...)
+	env.SelectedArtifactKeys = append([]string(nil), opts.SelectedArtifacts...)
 	if env.ArtifactStore == nil {
 		env.ArtifactStore = artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root)
 	}
@@ -83,9 +82,6 @@ func executeStages(ctx context.Context, cfg *config.Config, stages []stage.Stage
 	if env.Scriptorium == nil {
 		env.Scriptorium = scriptorium.NewSubprocessRunner()
 	}
-	if env.Storage == nil {
-		env.Storage = &storage.NoopBackend{}
-	}
 	if env.ObjectStore == nil && needsObjectStoreForRun(env.Config, stages) {
 		objectStore, err := newCommandObjectStore(ctx, env.Config, nil)
 		if err != nil {
@@ -96,7 +92,7 @@ func executeStages(ctx context.Context, cfg *config.Config, stages []stage.Stage
 	if needsRemoteLocksForRun(env.Config, stages) {
 		locks, err := loadEffectiveLocks(ctx, env.Config, env.ObjectStore)
 		if err != nil {
-			return nil, fmt.Errorf("load remote archive locks: %w", err)
+			return nil, fmt.Errorf("load remote publish locks: %w", err)
 		}
 		applyEffectiveLocks(env.Config, locks.All)
 	}
@@ -234,14 +230,14 @@ func executeStages(ctx context.Context, cfg *config.Config, stages []stage.Stage
 		env.Logger.Info("stage succeeded", "stage", s.Name())
 	}
 
-	if err := runPostArchiveCleanup(ctx, env, manifestPath, m, executed); err != nil {
+	if err := runPostPublishCleanup(ctx, env, manifestPath, m, executed); err != nil {
 		failedAt := nowUTC()
 		runManifest.MarkFailed(failedAt, err.Error())
 		syncRunManifestIdentityFromSession(m, runManifest)
 		if saveErr := runManifestStore.SaveRun(ctx, runManifestPath, runManifest); saveErr != nil {
-			return nil, fmt.Errorf("post-archive cleanup failed (%v) and run-manifest save failed (%v)", err, saveErr)
+			return nil, fmt.Errorf("post-publish cleanup failed (%v) and run-manifest save failed (%v)", err, saveErr)
 		}
-		return nil, fmt.Errorf("post-archive cleanup: %w", err)
+		return nil, fmt.Errorf("post-publish cleanup: %w", err)
 	}
 	completedAt := nowUTC()
 	runManifest.MarkSucceeded(completedAt)
@@ -568,16 +564,16 @@ func needsObjectStoreForRun(cfg *config.Config, stages []stage.Stage) bool {
 			return true
 		}
 	}
-	if !stageRequested("archive") {
+	if !stageRequested("publish") {
 		return false
 	}
-	if cfg.Pipeline.Archive == nil {
+	if cfg.Pipeline.Publish == nil {
 		return false
 	}
-	if cfg.Pipeline.Archive.Enabled != nil && !*cfg.Pipeline.Archive.Enabled {
+	if cfg.Pipeline.Publish.Enabled != nil && !*cfg.Pipeline.Publish.Enabled {
 		return false
 	}
-	if cfg.Pipeline.Archive.UploadRun != nil && !*cfg.Pipeline.Archive.UploadRun {
+	if cfg.Pipeline.Publish.UploadRun != nil && !*cfg.Pipeline.Publish.UploadRun {
 		return false
 	}
 	return true
@@ -587,23 +583,23 @@ func needsRemoteLocksForRun(cfg *config.Config, stages []stage.Stage) bool {
 	if cfg == nil || cfg.Pipeline == nil || cfg.Session == nil {
 		return false
 	}
-	archiveRequested := false
+	publishRequested := false
 	for _, s := range stages {
-		if s != nil && s.Name() == "archive" {
-			archiveRequested = true
+		if s != nil && s.Name() == "publish" {
+			publishRequested = true
 			break
 		}
 	}
-	if !archiveRequested {
+	if !publishRequested {
 		return false
 	}
-	if cfg.Pipeline.Archive == nil {
+	if cfg.Pipeline.Publish == nil {
 		return false
 	}
-	if cfg.Pipeline.Archive.Enabled != nil && !*cfg.Pipeline.Archive.Enabled {
+	if cfg.Pipeline.Publish.Enabled != nil && !*cfg.Pipeline.Publish.Enabled {
 		return false
 	}
-	if cfg.Pipeline.Archive.UploadRun != nil && !*cfg.Pipeline.Archive.UploadRun {
+	if cfg.Pipeline.Publish.UploadRun != nil && !*cfg.Pipeline.Publish.UploadRun {
 		return false
 	}
 	return cfg.Pipeline.Storage.S3 != nil

internal/app/runner_test.go

@@ -54,7 +54,7 @@ func (s captureSelectedArtifactsStage) Name() string           { return s.name }
 func (s captureSelectedArtifactsStage) Declares() stage.IODecl { return stage.IODecl{} }
 func (s captureSelectedArtifactsStage) Run(_ context.Context, env *stage.Env, _ *manifest.Manifest) (*stage.StageResult, error) {
 	if s.captured != nil {
-		*s.captured = append((*s.captured)[:0], env.SelectedAnalyzeArtifacts...)
+		*s.captured = append((*s.captured)[:0], env.SelectedArtifactKeys...)
 	}
 	return &stage.StageResult{Metadata: map[string]any{"captured": true}}, nil
 }
@@ -78,12 +78,12 @@ type selectedAnalyzeArtifactStage struct {
 func (s selectedAnalyzeArtifactStage) Name() string           { return "analyze" }
 func (s selectedAnalyzeArtifactStage) Declares() stage.IODecl { return stage.IODecl{} }
 func (s selectedAnalyzeArtifactStage) Run(_ context.Context, env *stage.Env, m *manifest.Manifest) (*stage.StageResult, error) {
-	if len(env.SelectedAnalyzeArtifacts) != len(s.expected) {
-		return nil, fmt.Errorf("selected artifacts len = %d, want %d", len(env.SelectedAnalyzeArtifacts), len(s.expected))
+	if len(env.SelectedArtifactKeys) != len(s.expected) {
+		return nil, fmt.Errorf("selected artifacts len = %d, want %d", len(env.SelectedArtifactKeys), len(s.expected))
 	}
 	for i := range s.expected {
-		if env.SelectedAnalyzeArtifacts[i] != s.expected[i] {
-			return nil, fmt.Errorf("selected artifacts[%d] = %q, want %q", i, env.SelectedAnalyzeArtifacts[i], s.expected[i])
+		if env.SelectedArtifactKeys[i] != s.expected[i] {
+			return nil, fmt.Errorf("selected artifacts[%d] = %q, want %q", i, env.SelectedArtifactKeys[i], s.expected[i])
 		}
 	}
 
@@ -248,16 +248,16 @@ func TestNeedsObjectStoreForRunPrepareWithPreviousRequirements(t *testing.T) {
 	}
 }
 
-func TestExecuteStagesArchiveFailsWhenRequiredRecapPromotionMissingForSelectedArtifacts(t *testing.T) {
+func TestExecuteStagesPublishSkipsRequiredUnselectedConfiguredOutput(t *testing.T) {
 	cfg := testConfig(t)
 	cfg.Pipeline.Storage.S3 = &config.StorageS3Config{
 		Bucket:     "my-dnd-archive",
 		RootPrefix: "dnd",
 	}
-	cfg.Pipeline.Archive = &config.ArchiveConfig{
+	cfg.Pipeline.Publish = &config.PublishConfig{
 		Enabled:   boolPtr(true),
 		UploadRun: boolPtr(true),
-		PromoteArtifacts: []config.ArchivePromotionRule{
+		Outputs: []config.PublishOutputRule{
 			{Source: "narratio.artifact.session_recap", Dest: "artifacts/session_recap.md", Required: boolPtr(true)},
 		},
 	}
@@ -283,28 +283,45 @@ func TestExecuteStagesArchiveFailsWhenRequiredRecapPromotionMissingForSelectedAr
 		t.Fatalf("Save manifest error = %v", err)
 	}
 
-	archiveStageImpl, err := stage.Select("archive")
+	publishStageImpl, err := stage.Select("publish")
 	if err != nil {
-		t.Fatalf("Select(archive) error = %v", err)
+		t.Fatalf("Select(publish) error = %v", err)
 	}
 
-	_, err = executeStages(
+	summary, err := executeStages(
 		context.Background(),
 		cfg,
 		[]stage.Stage{
 			selectedAnalyzeArtifactStage{expected: []string{"player_handout"}},
-			archiveStageImpl,
+			publishStageImpl,
 		},
 		RunOptions{
 			SelectedArtifacts: []string{"player_handout"},
 			Env:               &Env{ObjectStore: &storage.FakeBackend{}},
 		},
 	)
-	if err == nil {
-		t.Fatal("expected archive promotion failure, got nil")
+	if err != nil {
+		t.Fatalf("executeStages() error = %v", err)
 	}
-	if !strings.Contains(err.Error(), "required promotion source unavailable") {
-		t.Fatalf("error = %q, want required promotion source unavailable", err.Error())
+	if len(summary.Executed) != 2 || summary.Executed[0] != "analyze" || summary.Executed[1] != "publish" {
+		t.Fatalf("executed = %#v, want analyze and publish", summary.Executed)
+	}
+
+	loadedManifest, err := store.Load(context.Background(), summary.ManifestPath)
+	if err != nil {
+		t.Fatalf("Load manifest error = %v", err)
+	}
+	meta := loadedManifest.Stages["publish"].Metadata
+	skipped, ok := meta["skipped_unselected_outputs"].([]any)
+	if !ok || len(skipped) != 1 {
+		t.Fatalf("skipped_unselected_outputs = %#v, want one item", meta["skipped_unselected_outputs"])
+	}
+	item, ok := skipped[0].(map[string]any)
+	if !ok {
+		t.Fatalf("skipped item = %#v, want object", skipped[0])
+	}
+	if item["source"] != "narratio.artifact.session_recap" || item["dest"] != "artifacts/session_recap.md" || item["required"] != true {
+		t.Fatalf("skipped item = %#v, want required session_recap published output", item)
 	}
 }
 
@@ -325,7 +342,7 @@ func TestExecuteStagesPlaceholderSuccessUpdatesManifest(t *testing.T) {
 		t.Fatalf("Load manifest error = %v", err)
 	}
 
-	for _, name := range []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim", "analyze", "archive", "notify"} {
+	for _, name := range []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim", "analyze", "publish", "notify"} {
 		sr := m.Stages[name]
 		if sr == nil {
 			t.Fatalf("missing stage record %q", name)
@@ -408,12 +425,12 @@ func TestExecuteStagesPlaceholderSuccessUpdatesManifest(t *testing.T) {
 			}
 			continue
 		}
-		if name == "archive" {
-			if sr.Metadata == nil || sr.Metadata["stage"] != "archive" {
-				t.Fatalf("archive metadata missing stage=archive: %#v", sr.Metadata)
+		if name == "publish" {
+			if sr.Metadata == nil || sr.Metadata["stage"] != "publish" {
+				t.Fatalf("publish metadata missing stage=publish: %#v", sr.Metadata)
 			}
 			if sr.Metadata["skipped"] != true {
-				t.Fatalf("archive metadata missing skipped=true for test config without archive section: %#v", sr.Metadata)
+				t.Fatalf("publish metadata missing skipped=true for test config without publish section: %#v", sr.Metadata)
 			}
 			continue
 		}
@@ -505,7 +522,7 @@ func TestExecuteStagesForceSuccessInvalidatesDownstreamSucceededStages(t *testin
 	store := &manifest.LocalStore{}
 
 	existing := manifest.New(cfg.Session.SessionID, time.Date(2026, 5, 3, 1, 0, 0, 0, time.UTC))
-	for _, stageName := range []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim", "archive", "notify"} {
+	for _, stageName := range []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim", "publish", "notify"} {
 		existing.MarkStageSucceeded(stageName, time.Date(2026, 5, 3, 1, 1, 0, 0, time.UTC), nil)
 	}
 	existing.MarkStageFailed("analyze", time.Date(2026, 5, 3, 1, 1, 0, 0, time.UTC), "previous analyze failure")
@@ -536,7 +553,7 @@ func TestExecuteStagesForceSuccessInvalidatesDownstreamSucceededStages(t *testin
 	if loaded.Stages["polish"] == nil || loaded.Stages["polish"].Status != manifest.StatusSucceeded {
 		t.Fatalf("polish status = %#v, want succeeded", loaded.Stages["polish"])
 	}
-	for _, stageName := range []string{"normalize", "trim", "archive", "notify"} {
+	for _, stageName := range []string{"normalize", "trim", "publish", "notify"} {
 		if loaded.Stages[stageName] == nil || loaded.Stages[stageName].Status != manifest.StatusStale {
 			t.Fatalf("%s status = %#v, want stale", stageName, loaded.Stages[stageName])
 		}
@@ -712,7 +729,7 @@ func TestExecuteStagesRunManifestRecordsSkippedStage(t *testing.T) {
 	}
 }
 
-func TestExecuteStagesRunLocalArtifactsAndCanonicalPromotion(t *testing.T) {
+func TestExecuteStagesRunLocalArtifactsAndCanonicalSync(t *testing.T) {
 	cfg := testConfig(t)
 	stages := []stage.Stage{
 		BuildFullPlan()[0], // prepare
@@ -744,7 +761,7 @@ func TestExecuteStagesRunLocalArtifactsAndCanonicalPromotion(t *testing.T) {
 		filepath.Join(runRoot, "merge", "logs", "seriatim.stdout.log"),
 		filepath.Join(runRoot, "polish", "config", "audita.generated.yml"),
 		filepath.Join(runRoot, "normalize", "logs", "seriatim.normalize.stdout.log"),
-		filepath.Join(runRoot, "trim", "outputs", "transcripts", "trimmed.json"),
+		filepath.Join(runRoot, "trim", "outputs", "transcripts", "final.trimmed.json"),
 	}
 	for _, p := range runLocalChecks {
 		if _, statErr := os.Stat(p); statErr != nil {
@@ -754,14 +771,14 @@ func TestExecuteStagesRunLocalArtifactsAndCanonicalPromotion(t *testing.T) {
 
 	canonicalChecks := []string{
 		filepath.Join(paths.TranscriptsRawDir, "alice.json"),
-		filepath.Join(paths.TranscriptsDir, "merged.json"),
-		filepath.Join(paths.TranscriptsDir, "processed.json"),
-		filepath.Join(paths.TranscriptsDir, "normalized.json"),
-		filepath.Join(paths.TranscriptsDir, "trimmed.json"),
+		filepath.Join(paths.TranscriptsDir, "base.json"),
+		filepath.Join(paths.TranscriptsDir, "polished.json"),
+		filepath.Join(paths.TranscriptsDir, "final.json"),
+		filepath.Join(paths.TranscriptsDir, "final.trimmed.json"),
 	}
 	for _, p := range canonicalChecks {
 		if _, statErr := os.Stat(p); statErr != nil {
-			t.Fatalf("canonical promoted artifact missing at %q: %v", p, statErr)
+			t.Fatalf("canonical published artifact missing at %q: %v", p, statErr)
 		}
 	}
 
@@ -847,7 +864,7 @@ func TestAdapterBackedStageFailureMarksManifestFailed(t *testing.T) {
 		{name: "merge", env: &Env{Seriatim: &seriatim.FakeRunner{Err: errors.New("merge fail")}}},
 		{name: "polish", env: &Env{Audita: &audita.FakeRunner{Err: errors.New("polish fail")}}},
 		{name: "analyze", env: &Env{Scriptorium: &scriptorium.FakeRunner{RunErr: errors.New("analyze fail")}}},
-		{name: "archive", env: &Env{ObjectStore: &storage.FakeBackend{UploadErr: errors.New("archive fail")}}},
+		{name: "publish", env: &Env{ObjectStore: &storage.FakeBackend{UploadErr: errors.New("publish fail")}}},
 		{name: "notify", env: &Env{Notifier: &notify.FakeSender{Err: errors.New("notify fail")}}},
 	}
 
@@ -902,7 +919,7 @@ func TestAdapterBackedStageFailureMarksManifestFailed(t *testing.T) {
 				if ensureErr != nil {
 					t.Fatalf("EnsureLayout() error = %v", ensureErr)
 				}
-				if err := os.WriteFile(filepath.Join(paths.TranscriptsDir, "merged.json"), []byte(`{"segments":[]}`), 0o644); err != nil {
+				if err := os.WriteFile(filepath.Join(paths.TranscriptsDir, "base.json"), []byte(`{"segments":[]}`), 0o644); err != nil {
 					t.Fatalf("write merged transcript: %v", err)
 				}
 				if err := os.WriteFile(filepath.Join(paths.InputsDir, "glossary.yml"), []byte("terms: []\n"), 0o644); err != nil {
@@ -914,7 +931,7 @@ func TestAdapterBackedStageFailureMarksManifestFailed(t *testing.T) {
 				if ensureErr != nil {
 					t.Fatalf("EnsureLayout() error = %v", ensureErr)
 				}
-				if err := os.WriteFile(filepath.Join(paths.TranscriptsDir, "processed.json"), []byte(`{"segments":[]}`), 0o644); err != nil {
+				if err := os.WriteFile(filepath.Join(paths.TranscriptsDir, "polished.json"), []byte(`{"segments":[]}`), 0o644); err != nil {
 					t.Fatalf("write processed transcript: %v", err)
 				}
 				cfg.Pipeline.Scriptorium = &config.ScriptoriumConfig{
@@ -932,8 +949,8 @@ func TestAdapterBackedStageFailureMarksManifestFailed(t *testing.T) {
 					},
 				}
 			}
-			if tc.name == "archive" {
-				cfg.Pipeline.Archive = &config.ArchiveConfig{
+			if tc.name == "publish" {
+				cfg.Pipeline.Publish = &config.PublishConfig{
 					Enabled:   boolPtr(true),
 					UploadRun: boolPtr(true),
 				}
@@ -944,13 +961,13 @@ func TestAdapterBackedStageFailureMarksManifestFailed(t *testing.T) {
 				runID := "20260516T010203Z-0a1b2c3d"
 				runWorkDir := filepath.Join(cfg.Pipeline.Workspace.Root, "work", cfg.Session.Campaign, cfg.Session.SessionID, runID)
 				if err := os.MkdirAll(filepath.Join(runWorkDir, "inputs"), 0o755); err != nil {
-					t.Fatalf("mkdir archive inputs dir: %v", err)
+					t.Fatalf("mkdir publish inputs dir: %v", err)
 				}
 				if err := os.WriteFile(filepath.Join(runWorkDir, "inputs", "session.yml"), []byte("session_id: 2026-05-03\n"), 0o644); err != nil {
-					t.Fatalf("write archive fixture session.yml: %v", err)
+					t.Fatalf("write publish fixture session.yml: %v", err)
 				}
 				if err := os.WriteFile(filepath.Join(runWorkDir, "manifest.json"), []byte("{}\n"), 0o644); err != nil {
-					t.Fatalf("write archive fixture manifest.json: %v", err)
+					t.Fatalf("write publish fixture manifest.json: %v", err)
 				}
 
 				seed := manifest.New(cfg.Session.SessionID, time.Now().UTC())
@@ -964,7 +981,7 @@ func TestAdapterBackedStageFailureMarksManifestFailed(t *testing.T) {
 					seed.MarkStageSucceeded(name, time.Now().UTC(), nil)
 				}
 				if err := tc.env.ManifestStore.Save(context.Background(), manifestPathFor(cfg), seed); err != nil {
-					t.Fatalf("seed archive manifest: %v", err)
+					t.Fatalf("seed publish manifest: %v", err)
 				}
 			}
 
@@ -998,7 +1015,7 @@ func testConfig(t *testing.T) *config.Config {
 	pipelinePath := filepath.Join(cfgDir, "pipeline.yml")
 
 	mustWriteFile(t, pipelinePath, "workspace:\n  root: "+workspace+"\n")
-	mustWriteFile(t, campaignPath, "campaign: sample-campaign\ninputs:\n  speakers_file: ./speakers.yml\n  autocorrect_file: ./autocorrect.yml\n  glossary_file: ./glossary.yml\n")
+	mustWriteFile(t, campaignPath, "campaign_id: sample-campaign\ninputs:\n  speakers_file: ./speakers.yml\n  autocorrect_file: ./autocorrect.yml\n  glossary_file: ./glossary.yml\n")
 	mustWriteFile(t, sessionPath, "session_id: 2026-05-03\ncampaign: sample-campaign\ninputs:\n  audio_dir: ./audio\n")
 	mustWriteFile(t, filepath.Join(cfgDir, "speakers.yml"), "alice: alice.flac\n")
 	mustWriteFile(t, filepath.Join(cfgDir, "autocorrect.yml"), "[]\n")
@@ -1007,7 +1024,7 @@ func testConfig(t *testing.T) *config.Config {
 
 	return &config.Config{
 		Pipeline:     &config.PipelineConfig{Workspace: config.WorkspaceConfig{Root: workspace}},
-		Campaign:     &config.CampaignConfig{Campaign: "sample-campaign"},
+		Campaign:     &config.CampaignConfig{CampaignID: "sample-campaign"},
 		PipelinePath: pipelinePath,
 		CampaignPath: campaignPath,
 		SessionPath:  sessionPath,
@@ -1050,12 +1067,10 @@ func TestBuildDefaultRunnersWithOmittedToolSections(t *testing.T) {
   root: ` + t.TempDir() + `
 whisperx:
   transcribe_url: https://example.com/transcribe
-analyzer:
-  timeout: 20m
 notification:
   timeout: 10s
 `
-	campaignYAML := `campaign: sample-campaign
+	campaignYAML := `campaign_id: sample-campaign
 inputs:
   speakers_file: ./speakers.yml
   autocorrect_file: ./autocorrect.yml

internal/app/session_args.go

@@ -0,0 +1,95 @@
+package app
+
+import (
+	"flag"
+	"fmt"
+	"strings"
+)
+
+func isCLIFlagToken(arg string) bool {
+	return strings.HasPrefix(arg, "-") && arg != "-"
+}
+
+func pullLeadingSessionID(args []string) (string, []string) {
+	if len(args) == 0 || isCLIFlagToken(args[0]) {
+		return "", args
+	}
+	rest := append([]string(nil), args[1:]...)
+	return strings.TrimSpace(args[0]), rest
+}
+
+func applyPositionalSessionID(command, positional string, sessionID *string) error {
+	positional = strings.TrimSpace(positional)
+	if positional == "" {
+		return nil
+	}
+	existing := strings.TrimSpace(*sessionID)
+	if existing != "" && existing != positional {
+		return fmt.Errorf("%s: positional session id %q does not match expected session id %q", command, positional, existing)
+	}
+	*sessionID = positional
+	return nil
+}
+
+func applyParsedSessionIDArg(command string, fs *flag.FlagSet, sessionID *string) error {
+	switch fs.NArg() {
+	case 0:
+		return nil
+	case 1:
+		return applyPositionalSessionID(command, fs.Arg(0), sessionID)
+	default:
+		return fmt.Errorf("%s: unexpected positional arguments", command)
+	}
+}
+
+func resolveParsedSessionID(command, positionalSessionID string, fs *flag.FlagSet, sessionID *string) error {
+	if strings.TrimSpace(positionalSessionID) == "" {
+		return applyParsedSessionIDArg(command, fs, sessionID)
+	}
+	if fs.NArg() != 0 {
+		return fmt.Errorf("%s: unexpected positional arguments", command)
+	}
+	return applyPositionalSessionID(command, positionalSessionID, sessionID)
+}
+
+func parseSessionAwareFlags(command string, fs *flag.FlagSet, args []string, sessionID *string) error {
+	positionalSessionID, args := pullLeadingSessionID(args)
+	if err := fs.Parse(args); err != nil {
+		return fmt.Errorf("%s: invalid flags: %w", command, err)
+	}
+	return resolveParsedSessionID(command, positionalSessionID, fs, sessionID)
+}
+
+func parseSessionIDAndOnePositionalArg(command, argName string, fs *flag.FlagSet, args []string, sessionID *string) (string, error) {
+	var positionalSessionID string
+	value := ""
+	if len(args) >= 2 && !isCLIFlagToken(args[0]) && !isCLIFlagToken(args[1]) {
+		positionalSessionID = strings.TrimSpace(args[0])
+		value = strings.TrimSpace(args[1])
+		args = append([]string(nil), args[2:]...)
+	}
+
+	if err := fs.Parse(args); err != nil {
+		return "", fmt.Errorf("%s: invalid flags: %w", command, err)
+	}
+	if value == "" {
+		switch fs.NArg() {
+		case 2:
+			positionalSessionID = strings.TrimSpace(fs.Arg(0))
+			value = strings.TrimSpace(fs.Arg(1))
+		case 1:
+			if strings.TrimSpace(*sessionID) == "" {
+				return "", fmt.Errorf("%s: expected session_id and %s", command, argName)
+			}
+			value = strings.TrimSpace(fs.Arg(0))
+		default:
+			return "", fmt.Errorf("%s: expected session_id and %s", command, argName)
+		}
+	} else if fs.NArg() != 0 {
+		return "", fmt.Errorf("%s: unexpected positional arguments", command)
+	}
+	if err := applyPositionalSessionID(command, positionalSessionID, sessionID); err != nil {
+		return "", err
+	}
+	return value, nil
+}