narratio/docs/operations.md

Operations Guide

Operator workflow for running, recovering, and publishing Narratio sessions.

For command syntax, see docs/cli.md. For field-level config, see docs/config.md.

Campaign and Session Selection

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:

narratio session init 2026-04-04 --output ./session.yml --date 2026-04-04 --title "Session 12"

Remote session object:

narratio session init 2026-04-04 --remote --force

If campaign.yml sets session_template_file, session init renders it. Template variables must resolve to concrete values.

Standard Session Workflow

1. Select pipeline/campaign/session config.
2. Validate session readiness:

narratio session validate 2026-04-04

3. (Optional) inspect stage decisions:

narratio session plan 2026-04-04

4. Run the pipeline:

narratio run 2026-04-04

5. Check state:

narratio session status 2026-04-04

Stage Execution and Continuation Behavior

Canonical stage order:

1. prepare
2. transcribe
3. merge
4. polish
5. normalize
6. trim
7. render
8. analyze
9. publish
10. 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:

narratio run-stage normalize 2026-04-04 --force

Artifact Selection

--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:

narratio publish 2026-04-04

Equivalent:

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:

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:

narratio session restore 2026-04-04 --dry-run

Apply:

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}

Durable session paths:

• manifest.json
• inputs/**
• audio/**
• transcripts/**
• artifacts/**
• previous/**
• reports/**
• logs/**
• config/**
• runs/**

Run-local layout:

• 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

Spool layout (runtime/transient):

• {spool.root}/{campaign}/{session_id}/{run_id}/...
• restore audio spool under {spool.root}/{campaign}/{session_id}/restore/audio

Cache layout (durable S3 audio cache):

• {cache.root}/s3/{bucket}/...

Cleanup

Session-scoped cleanup:

narratio clean 2026-04-04

Global cleanup:

narratio clean --all

Dry-run and cache variants:

narratio clean 2026-04-04 --dry-run --clear-cache
narratio clean --all --dry-run --clear-cache

Rules:

• 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

Operational Caveats

• Local and S3 audio modes are mutually exclusive.
• Publish requires prerequisite stages through render and analyze to be succeeded.
• Markdown publish defaults require render outputs (transcripts/final.md and transcripts/final.trimmed.md).
• Restore requires configured object storage and committed remote current state.
• Storage-backed commands load filesystem secrets before object-store initialization.