252 lines
5.4 KiB
Markdown
252 lines
5.4 KiB
Markdown
# 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.
|
|
|
|
## 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.
|