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).

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

## 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.

## Stage Execution and Continuation Behavior

Canonical stage order:

1. `prepare`
2. `transcribe`
3. `merge`
4. `polish`
5. `normalize`
6. `trim`
7. `analyze`
8. `publish`
9. `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 analyze to be succeeded.
- Restore requires configured object storage and committed remote current state.
- Storage-backed commands load filesystem secrets before object-store initialization.