narratio/docs/operations.md

# Operations Guide

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

For command syntax, see [docs/cli.md](./cli.md). For field-level config, see [docs/config.md](./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:

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

Remote session object:

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

```bash
narratio session validate 2026-04-04
```

3. (Optional) inspect stage decisions:

```bash
narratio session plan 2026-04-04
```

4. Run the pipeline:

```bash
narratio run 2026-04-04
```

5. Check state:

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

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

```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}`

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:

```bash
narratio clean 2026-04-04
```

Global cleanup:

```bash
narratio clean --all
```

Dry-run and cache variants:

```bash
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.