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.

Campaigns must provide stable input files for speakers, autocorrect, glossary, players, and party. Session files may override those paths for one session. The prepare stage materializes them under inputs/; configured Scriptorium artifacts can reference prepared players, party, and glossary files with narratio.input.players, narratio.input.party, and narratio.input.glossary.

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. extract
8. render
9. analyze
10. publish
11. notify

Execution rules:

• succeeded stages are skipped unless --force is set;
• run continues interrupted or partially completed sessions by running non-succeeded stages;
• forcing an upstream stage marks succeeded downstream stages as stale before the replacement runs; and
• an executed failure, changed self-skip, or success that replaces a different effective upstream outcome also marks succeeded downstream stages stale. A repeated self-skip with the same reason and no outputs is stable and does not perpetually rerun downstream work.

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, bounds, or explicitly configured narratio.extraction.<name> publish sources; and
• never partially selects Notarius lanes.

Extraction Workflow

When Notarius is omitted or disabled, extract records an explicit skipped outcome with reason notarius_disabled and no outputs. A later invocation reconsiders the skipped stage, so enabling Notarius does not require force.

When Notarius extraction is enabled, the stage consumes the final trimmed JSON and preserves the complete validated Notarius bundle at:

• artifacts/notarius/{narratio_run_id}/

The directory is immutable once promoted. Configured lanes become narratio.extraction.<name> sources for Scriptorium and explicit publish rules; the bundle and index.json are retained for audit and resume validation but are not selectable or published implicitly.

Starting a replacement clears the previous extraction payload from the current session-stage record. If that replacement fails or self-skips, the current record does not fall back to the earlier outputs. The earlier run manifest and immutable bundle remain available for inspection, but downstream resolution requires a new current successful extraction record.

Atomic Notarius bundle promotion is supported on Linux, macOS, and Windows. On other operating systems, extraction fails before copying the bundle into a temporary promotion tree because Narratio has no verified atomic no-replace directory primitive there. This is an extraction limitation, not a broader platform-support guarantee for every Narratio workflow.

Run-local diagnostics are:

• runs/{run_id}/extract/notarius.receipt.json
• runs/{run_id}/extract/notarius.stderr.log
• runs/{run_id}/extract/notarius-output/ before durable promotion

The run-record upload excludes the complete extract/notarius-output/** subtree. The receipt and stderr files remain eligible run-record diagnostics. The durable bundle is never scanned for implicit publication; only lanes named by explicit pipeline.publish.outputs rules are uploaded.

To intentionally replace the current extraction result, run:

narratio run-stage extract 2026-04-04 --force

Narratio automatically reruns extraction when its recorded invocation contract or durable output validation changes. It cannot fingerprint configuration files, profiles, prompts, modules, or references loaded transitively by Notarius. Force extraction after changing any of those inputs, even when the top-level Narratio and Notarius config paths remain the same. A forced extract marks successful downstream stages stale. Ordinary extraction failures or outcome changes also stale affected downstream stages, while an identical repeated notarius_disabled self-skip does not repeatedly invalidate them.

Publish Workflow

Run publish only:

narratio publish 2026-04-04

Equivalent:

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

Publish commit model:

• uploads eligible run files under {session_prefix}/runs/{run_id}/, excluding audio and the run-local Notarius staging bundle;
• uploads configured published outputs, including only explicitly configured extraction lanes;
• 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/**

Validated Notarius bundles live below artifacts/notarius/{run_id}/; receipt, stderr, and pre-promotion output remain in the producing run's extract directory as described in Extraction Workflow.

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.