narratio/docs/operations.md

Operations

This guide covers the implemented operator lifecycle for Narratio.

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

Normal Workflow

1. Ensure pipeline.yml, campaign.yml, and session.yml are available.
2. Ensure session audio is available (local audio_dir/audio_files or S3 prefix).
3. Run:

narratio run 2026-04-04

4. Inspect status:

narratio session status 2026-04-04

Publish Workflow

Publish is the stage that commits remote current state.

narratio publish 2026-04-04

Equivalent command:

narratio run-stage publish 2026-04-04 --force

Publish uploads:

• run history files under {session_prefix}/runs/{run_id}/ (excluding audio/)
• configured published outputs from pipeline.publish.outputs
• previous/** cache files when present
• current/manifest.json
• current/run_id.txt last

current/run_id.txt is the remote commit marker.

Published Outputs and Locks

Published output behavior:

• outputs are source-based rules in pipeline.publish.outputs.
• required missing unlocked sources fail publish.
• optional missing unlocked sources are skipped.
• selected artifacts (--artifacts) only filter configured narratio.artifact.<key> output rules.
• built-in transcript and bounds output rules are not filtered by --artifacts.

Lock behavior:

• static locks: pipeline.publish.locks.
• mutable locks: {session_prefix}/locks.yml.
• effective lock set is static + mutable; static wins on duplicate sources.
• locked outputs are intentional skips and do not fail publish.
• lock commands mutate only remote mutable locks.

Restore Workflow

Use restore when local durable session state is missing/stale and committed remote current state is authoritative.

Preview:

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

Apply:

narratio session restore 2026-04-04

Default restore scope:

• manifest.json
• transcripts/**
• artifacts/**
• previous/** when required by configured previous-session artifact inputs

Optional:

• add --include-audio to restore audio/**.

Restore reads committed current state only (current/run_id.txt, current/manifest.json).

Workspace and State Layout

Session root:

• {workspace.root}/work/{campaign}/{session_id}/

Durable session state:

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

Run-local stage layout:

• runs/{run_id}/{stage}/outputs|logs|reports|config|scratch

Stages typically write run-local outputs first, then materialize canonical session outputs on success.

Resume and Force Rules

• run and run-stage skip succeeded stages unless --force is set.
• resume starts at the first non-succeeded stage.
• force-rerunning an upstream succeeded stage marks downstream succeeded stages as stale.
• --force does not bypass publish locks.

Cleanup

Automatic post-publish cleanup is considered only when publish executes successfully and commits current state.

Config toggles:

• pipeline.spool.delete_audio_after_publish=true
• pipeline.workspace.cleanup_after_publish=true

Manual cleanup:

narratio clean 2026-04-04
narratio clean --all

Cache is preserved by default. Use --clear-cache to remove matching S3 audio cache entries.

Failure and Recovery

After stage failure, Narratio keeps manifests and run-local files for inspection.

Standard recovery flow:

1. inspect status:

narratio session status 2026-04-04

2. if needed, inspect restore plan:

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

3. fix root cause.
4. continue with resume, or rerun a stage with --force then resume.

Operational Caveats

• local and S3 audio modes are mutually exclusive.
• publish requires prerequisite stages through analyze to be succeeded.
• restore requires configured object storage and committed current state.
• session status and session artifacts --remote both report remote published-output availability when storage is configured.