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, and may provide an optional spell-catalog overlay. Session files may override those paths for one session. The prepare stage materializes them under inputs/; configured consumers use the prepared files, never the original campaign or session source paths. Field definitions and source IDs are in Configuration.

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

Run, plan, and status output identify the resolved pipeline profile (or none) and effective configuration digest. Status distinguishes the current resolved value from the last value persisted in the session manifest, which helps diagnose profile switches without changing resume authority.

Before switching an operational profile, compare its effective meaning with the current selection through narratio config diff <left-profile> <right-profile>. The command is read-only and succeeds whether it finds differences or not. Its sorted records describe defaulted, expanded concrete configuration—not source file layout—so it can be used to review model, artifact, and publish changes without creating a session or run. Select the same campaign explicitly when profiles could resolve different campaign paths; see the CLI reference for syntax and record format.

Stage Execution and Continuation Behavior

Canonical stage order:

1. prepare
2. transcribe
3. merge
4. polish
5. normalize
6. trim
7. render
8. extract
9. analyze
10. publish
11. notify
12. cleanup

Execution rules:

• succeeded stages are skipped unless --force is set; stages with semantic configuration contracts additionally require matching versioned evidence;
• run continues interrupted or partially completed sessions by running non-succeeded stages;
• forcing a stage marks succeeded transitive dependents as stale before the replacement runs; render and extract are independent siblings; and
• an executed failure, changed self-skip, or success that replaces a different effective outcome uses the same fixed dependency relation. A repeated self-skip with the same reason and no outputs is stable and does not perpetually rerun dependent work.

Every aggregate stage except analyze currently provides semantic-configuration evidence; analyze retains its more precise per-artifact fingerprints and validator. Prepare additionally validates current stable/local/S3 source identity and the checksums of its durable prepared copies before reuse. Changed bytes, audio membership, S3 object identity, or missing/tampered copies rerun prepare and its fixed descendants without requiring --force. Changing prepare selection semantics likewise reruns all fixed descendants; changing WhisperX language/service identity reuses prepare; changing a Seriatim merge transformation reuses prepare and transcribe; and changing an Audita model reuses prepare, transcribe, and merge while rebuilding transcript refinement. A trim change invalidates both render and extract through the fixed dependency relation, while a render-only change preserves the extract sibling.

Operational timeouts, retry/concurrency tuning, executable paths, workspace/cache/spool placement, reports, diagnostics, and secret values are excluded. Configuration, models, prompts, modules, or resources loaded privately inside external tools remain unobservable to Narratio. If their contents change behind the same configured identifier, explicitly force the affected stage.

An explicit self-skip is a durable skipped stage outcome that later runs reconsider. It differs from successful no-output execution: disabled render and publish, and absent or no-executable analyze, record succeeded with metadata and no outputs. Ordinary later runs reuse those successful results; force the affected stage after enabling or configuring it. Optional artifact inputs are omitted only from the consuming artifact invocation and do not make the stage self-skip.

Single-stage execution:

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

Contiguous bounded execution uses inclusive canonical endpoints:

narratio session plan 2026-04-04 --from extract --through analyze --force
narratio run 2026-04-04 --from extract --through analyze --force

Omitting --from selects from prepare; omitting --through selects through cleanup. Force applies only within the selected range. Repeating --from, --through, or --force is rejected instead of resolving by argument order. The plan command uses the same selection contract and prints only the selected range. Planning is read-only: it clones the loaded manifest, models selected stage transitions and invalidation in memory, and invokes resume validation without writing the manifest, creating run directories, materializing files, or invoking pipeline adapters. Analyze detail separates explicit targets, prerequisite rebuilds, scheduled execution, and current reuse. This lets a coarsely stale aggregate analyze stage show zero artifact executions when its selected artifact evidence is still semantically current.

Before a bounded run or plan whose range starts after prepare, every excluded prefix stage must already have a session-manifest status of succeeded or skipped. Narratio reports the first absent, pending, running, failed, stale, or interrupted prerequisite without creating a run-local directory or changing session state. Widen --from to include that stage, or recover it explicitly before retrying. Excluded prefix stages are not resume-validated or repaired as part of the bounded invocation; selected stages still reject missing, unsafe, or manifest-inconsistent inputs at their owning boundary.

Stages after --through are not prerequisites and are never scheduled by the bounded invocation. A selected forced stage can mark one of those succeeded dependents stale through the fixed invalidation relation, but the dependent does not execute until a later invocation selects it. Production composition likewise initializes only collaborators needed by the selected range and shared session lifecycle. In particular, render does not require Notarius or Scriptorium, extract does not require Scriptorium, and analyze does not require the transcription, Seriatim, Audita, or Notarius adapters.

For the common post-transcript development loop, use:

narratio regenerate-artifacts 2026-04-04
narratio regenerate-artifacts 2026-04-04 --artifacts session_recap,player_handout

This command is a transparent expansion to a forced bounded run from extract through analyze. Extraction always rebuilds its complete configured bundle. Analysis rebuilds the selected targets and their required analysis prerequisites, or uses the normal default selection when no artifact names are given. The command does not run publish, notify, or cleanup; delivery and retention remain separate operator actions.

Inspect current artifact evidence, then publish explicitly when the regenerated set is ready:

narratio session artifacts 2026-04-04
narratio publish 2026-04-04

If planning or execution reports stale, missing, failed, or tampered analysis evidence, regenerate the affected target instead of copying an older canonical file into place or editing the manifest. See Troubleshooting: Analysis artifact evidence is not current.

Analyze checkpoints each completed configured artifact before starting later artifact work. After a partial failure or interruption, retry normally: valid earlier checkpoints are reused and execution resumes with failed, stale, or missing work in dependency order. --force is unnecessary unless the operator intends to replace otherwise-current artifacts.

Artifact Selection

For a configured artifact family, selecting its family key expands to every concrete character artifact. Select a concrete generated key to operate on one member only. Manifests and plan output retain the concrete key as the durable identity and include the family and character ID as optional provenance.

--artifacts can be used on run, session plan, run-stage, analyze, and publish. For a bounded run or plan, the selected range must contain analyze or publish.

Selection behavior:

• validates names against pipeline.scriptorium.artifacts;
• selects explicit analyze targets and permits their required configured prerequisites to be reused or rebuilt first;
• 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.

Configured Notarius references resolve only from the current manifest-backed prepared inputs. Their canonical locations are inputs/party.yml, inputs/players.yml, inputs/glossary.yml, and, when configured, inputs/spell_catalog.json. Extraction supplies Notarius with verified copies under runs/<run_id>/extract/references/ so a concurrent refresh of canonical prepared files cannot change the bytes consumed by an in-flight invocation. For a canonical party, preparation retains the validated authored party bytes at inputs/party.yml and generates inputs/players.yml from that roster. The manifest records their checksums separately, with the players input marked as derived from the party; refresh preparation after changing the roster rather than editing either prepared file. Inspect the effective stable-input inventory and prepared-file readiness with:

narratio session status 2026-04-04
narratio session validate 2026-04-04

Reference metadata records selector, source ID, session-relative path, checksum, and byte size, but never payload contents. Changing a prepared reference changes extraction identity: ordinary continuation rejects the old result, reruns Notarius, and marks successful downstream stages stale. If the prepared file is missing or inconsistent with its manifest checksum, repair the source configuration and refresh prepared state first:

narratio run-stage prepare 2026-04-04 --force

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 immutable bundle remains available for inspection, but downstream resolution requires a new current successful extraction record.

Notarius extraction validates its run-local bundle and moves it once to the unique durable bundle path. A pre-existing durable destination is a collision; no duplicate promotion tree is created.

External Command Lifecycle

When an external command is cancelled or times out, Narratio terminates its owned descendants as well as the command itself. Cancellation first requests termination where the platform supports it, then force terminates after a bounded wait. A command is not considered finished until its leader has been reaped, and descendants that keep standard output or error open cannot keep the invocation blocked. Other operating systems fail closed rather than launch a command without tree ownership.

Subprocess stdout and stderr diagnostics are separately redacted and capped at 8 MiB per invocation. Narratio does not retain configured credential values in these logs or their error tails; reaching a capture limit terminates the command tree and reports which stream exceeded the limit.

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 upload is an allowlist derived from the session manifest's declared current-run outputs, logs, and generated configurations, not a workspace scan. References to canonical session files and prior-run paths are excluded. Each declared source is opened without following symlinked ancestors or the leaf, verified as a regular file, and streamed from that verified descriptor. Unlisted files and unsafe entries are never uploaded; a run with no declared current-run diagnostics uploads no run-local files. No distinguished diagnostic file is uploaded. 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, prepared Narratio reference identities, or durable output validation changes. The semantic portion covers Notarius enablement, pipeline identity, declared reference mapping, and output contracts. Executable, timeout, working directory, and private config-file paths are operational and do not invalidate a current result. It cannot fingerprint configuration files, profiles, prompts, modules, or other references loaded transitively by Notarius itself. 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 reuse additionally tracks enabled/run-upload behavior, normalized output rules, and remote backend/bucket/region/endpoint/root identity. Credential environment names, local workspace placement, and run IDs are excluded. Regardless of semantic reuse evidence, executing publish reads independent remote locks directly and rechecks initially unlocked sources before commit selection.

Publish Workflow

Run publish only:

narratio publish 2026-04-04

Equivalent:

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

This standalone command stops after publish and does not invoke cleanup. A default full run continues through notify and cleanup.

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 and previous/** cache files into the same immutable run scope, including only explicitly configured extraction lanes;
• writes {session_prefix}/runs/{run_id}/commit.json after all declared immutable objects are uploaded and verified; and
• writes {session_prefix}/current/commit-pointer.json once, last.

current/commit-pointer.json is the remote current-state commit marker. It selects exactly one immutable commit, which declares the complete object set.

Remote Commit Migration

The immutable remote commit contract uses runs/{run_id}/commit.json to declare a run's complete object set and a small current/commit-pointer.json to select it. The pointer binds the selected commit by version, checksum, size, and storage generation; committed artifacts are also checksum- and generation-bound. Readers accept this contract now and strictly reject mismatched or unknown data.

A selected commit may carry a published_output declaration from an earlier run in the same campaign/session. Restore, previous-session caching, status, and artifact inspection use that declaration's exact immutable key and stable source; they do not reconstruct a current-run key or scan the session prefix. Other artifact types remain confined to the selected commit's own run.

When the pointer is absent, remote state is not published; republish the session to establish a committed snapshot. Remote commit state does not carry local current_pointer_written metadata.

Publish Locks

Each mutable lock is an independent strict JSON object at {session_prefix}/locks/{sha256(source)}.lock. The lowercase digest is computed from the exact canonical source. Listing validates every object in that reserved prefix and reports locks sorted by source.

Upgrades do not read, migrate, or delete the retired {session_prefix}/locks.yml object. It has no effect on publication and may be removed manually after verifying lock commands and publication behavior with the upgraded Narratio version. No migration command is required.

Operational rules:

• add uses conditional creation and reports an existing lock;
• add with --force observes the current generation and attempts one generation-matched replacement. A concurrent change is reported for an explicit operator retry;
• remove is idempotent and reports whether a lock was present;
• the initial publish lock snapshot controls output planning. A locked source carries its exact declaration from the prior current commit when available; a never-published locked source remains absent even when required;
• carried bytes are not copied. Publish verifies the prior object's exact key, size, and generation without downloading it; and
• after immutable uploads and the immutable commit, publish re-reads every initially unlocked participating source. A newly added lock prevents the current pointer from advancing, although the immutable attempt may remain. A removed initial lock may conservatively cause one carry.

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

--dry-run does not write durable session files. It still reads the selected remote current state and may read object identity/content needed to classify the plan, so it is not a network-free operation.

Default restore scope:

• the committed session manifest and the committed transcript/artifact objects declared by the selected remote commit
• previous/** when needed by configured previous-session artifact inputs; each is selected from its exact committed published_output declaration

Optional:

• --include-audio to include audio/**
• --force to overwrite eligible conflicting regular files; it never replaces directories, symlinks, or other non-regular local targets

Restore treats a local leaf symlink or any symlinked ancestor beneath the selected session root as a conflict, even when the linked content matches the selected remote object. --force does not override that conflict.

Before each install, restore validates the destination again beneath the selected session root. A target changed into a symlink, directory, or other non-regular entry is not overwritten.

Restore writes an execution report at reports/restore-latest.json.

If restore fails after beginning installation, it leaves a durable .restore-incomplete.json marker in the session root. Pipeline runs will stop until you rerun the same restore command and it completes. Restore intentionally does not try to roll back files already installed; retrying the selected remote snapshot is the recovery procedure.

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/**

manifest.json is the versioned session-progress document. Narratio accepts only narratio.session-manifest.v1. Do not edit unsupported session state to add missing markers. Move it aside and regenerate it, restore a verified current committed snapshot, or republish healthy regenerated state as the relevant workflow requires.

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}/...

Each cached audio file has an adjacent managed identity record. It binds the file to its remote object version and verified digest; deleting or altering the record simply causes Narratio to download and verify the object again. Remote audio and restored files are fully transferred into sibling temporary files and validated before they replace their canonical workspace paths.

Workspace Permissions

Ordinary Narratio workspace content is intentionally shareable with the workspace group. On POSIX systems, Narratio-created workspace, spool, and cache directories converge on setgid 02775; ordinary files, including manifests, transcripts, generated configuration, logs, reports, and Notarius artifacts, converge on 0664. Narratio explicitly applies these modes so a restrictive caller umask does not remove group write or setgid. It does not change file or directory ownership: the configured workspace's existing group is inherited.

API keys are credentials, not ordinary workspace data. Store them outside the shared workspace or in a separately restricted credential location; ordinary workspace group access must never be treated as authorization to read keys. Provision a credential directory as 0700 and credential files as 0600; these permission modes are an operator requirement and are not enforced by ConfigKit.

Every pipeline-loading command bootstraps credentials once, before the first configuration load and before any adapter is constructed. --secrets-dir selects an explicit directory (relative paths use caller CWD). Otherwise a present secrets/ beside the resolved root pipeline is used, while an absent conventional directory is skipped. Explicit missing/empty selections and invalid existing directories fail the command. ConfigKit follows a symlink used as the selected directory, but immediate entries must be regular non-symlink files. Existing environment variables—including empty values—always win.

External adapter results are individually bounded before Narratio validates or materializes them. These per-file limits do not reserve disk space: prevent hard disk exhaustion with filesystem, service, container, or volume quotas sized for the session workload.

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;
• each deletion is confined beneath its configured workspace, spool, or cache root; root, traversal, and out-of-root targets are refused;
• the final cleanup stage is gated by successful publish evidence plus:
  • pipeline.spool.delete_audio_after_publish=true
  • pipeline.workspace.cleanup_after_publish=true
  • the manifest publish record has uploaded=true, the published run ID, the exact remote commit key, and the current commit-pointer key.

Cleanup derives only the configured run-scoped spool and workspace targets, uses root-confined deletion, and does not read or mutate object storage. A failure leaves publish succeeded and the remote committed snapshot current. Retry with a normal full run: valid upstream work, including publish and notify, is skipped while the failed cleanup stage runs again. run-stage cleanup is also available when the manifest has valid publish evidence. A range ending at notify or earlier and the standalone publish command never delete local state.

Older local manifests that contain the retired cleanup-obligation field are intentionally incompatible with strict manifest decoding. If such an obligation is still outstanding, complete it with the pre-upgrade binary. Otherwise verify that the remote publication is committed, move aside or regenerate the incompatible local manifest (or restore the verified remote snapshot), and then use the cleanup stage. Manual JSON editing is not the normal migration path.

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.
• Pipeline-loading commands bootstrap filesystem secrets once before configuration resolution and object-store initialization.