# Operations

This is the canonical reference for operating implemented Notarius runs.

## Normal Run

A run reads one source file, resolves one configured pipeline, calls the
configured OpenAI-compatible LLM profile, writes durable JSON output, and writes
diagnostics for inspection.

```sh
go run ./cmd/notarius run dnd-session \
  --config examples/dnd-spells.config.yml \
  --input examples/seriatim-minimal-transcript.json \
  --output-dir ./notarius-output \
  --diagnostics-dir /tmp/notarius
```

The command prints a success line with the pipeline ID, approved and rejected
artifact counts, and the output path.

## Output Directory

Durable output is written to:

```text
<output-root>/<run-id>/
```

The default output root is `./notarius-output`. Use `--output-dir` to choose a
different root.

The `json` output module writes these files:

- `index.json`: file index with paths to the manifest, artifact files,
  rejected artifacts, and warnings.
- `manifest.json`: run manifest with resolved pipeline provenance, top-level
  module metadata, module keys, validation status, and timing.
- `artifacts/<artifact-type>.json`: approved artifacts grouped by artifact
  type. For the current D&D spell extractor, this includes
  `artifacts/dnd.spell_cast.json` when spell-cast artifacts are approved.
- `rejected.json`: rejected candidates and validator decisions.
- `warnings.json`: warnings reported by pipeline modules or the output encoder.

Output writes are atomic per file. Logical output file names must be clean,
relative, slash-separated paths and must not contain `..`.

## Diagnostics Directory

Diagnostics are written under:

```text
<diagnostics-work-dir>/<run-id>/
```

The default diagnostics work directory is `/tmp/notarius`. It can be set with
`diagnostics.work_dir`, `NOTARIUS_WORK_DIR`, or `--diagnostics-dir`.

Implemented diagnostics artifacts:

- `invocation.json`: command metadata such as operation, config path, input
  path, selected lanes, run ID, and pipeline digest when available.
- `effective-config.json`: resolved config with API keys redacted.
- `resolved-pipeline.json`: resolved module bindings and pipeline digest.
- `run-manifest.json`: the same run manifest written to durable output when it
  is available, including top-level module metadata when present.
- `warnings.json`: warning list.
- `run-report.json`: counts, status, output path, diagnostics path, and run ID.
- `error.log`: failure message, written after diagnostics directory creation
  when a run fails.

`source-document.json` is supported by the diagnostics writer but is not written
by the current CLI run workflow.

## Retention

Diagnostics retention is configured with `diagnostics.retention`,
`NOTARIUS_DIAGNOSTICS_RETENTION`, or the default `auto`.

- `auto`: keep failed runs and successful runs with warnings; remove successful
  warning-free runs.
- `always`: keep every diagnostics run directory.
- `never`: remove successful run directories; failed runs are still retained.

Unknown retention values are rejected during config validation.

## Failures

Failures before diagnostics directory creation, such as a missing config file or
an unusable diagnostics work directory, are printed to stderr and may not have a
diagnostics run directory.

Failures after diagnostics directory creation are printed to stderr and written
to `error.log`. Depending on where the failure occurred, diagnostics may also
include invocation metadata, redacted effective config, resolved pipeline data,
the run manifest, warnings, and a run report.

If durable output writing fails after the pipeline completes, diagnostics are
retained for inspection and may include `run-manifest.json`, `warnings.json`,
`run-report.json`, and `error.log`.

## Warnings

A successful run with warnings exits with code `0`, prints a warning count to
stderr, and writes warnings to durable output and diagnostics when retained.

The run manifest `validation_status` indicates whether final artifacts were
approved or rejected after validation.

## Cleanup

It is safe to remove specific old run directories after their output and
diagnostics are no longer needed:

```sh
rm -rf /tmp/notarius/run-1234567890
rm -rf ./notarius-output/run-1234567890
```

Use exact run-directory paths. Avoid broad cleanup commands against parent
directories unless they are part of your own operational policy.

## Operational Limits

There is no command to resume a failed run. Re-run `notarius run` after fixing
the cause.

Provider retries are limited to the OpenAI-compatible client retry behavior
configured by the effective LLM profile. There is no separate CLI retry command.

Notarius writes local files only. Remote storage and archive management are not
part of the implemented CLI.