# Operations

This guide covers the implemented operator lifecycle for Narratio.

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

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

4. Inspect status:

```bash
narratio session status 2026-04-04
```

## Publish Workflow

Publish is the stage that commits remote current state.

```bash
narratio publish 2026-04-04
```

Equivalent command:

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

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

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

```bash
narratio session status 2026-04-04
```

2. if needed, inspect restore plan:

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