# Audita Operations

This guide owns physical output placement and failure handling. The
[CLI reference](cli.md) owns flags and streams, [configuration](config.md) owns
settings, and the [output contract](integrations/output-files.md) owns schemas.

## Normal Workflow

1. Validate a version-2 configuration and its selected profiles with
   `audita config validate --config config.yml`.
2. Prepare a transcript and glossary following the [input contract](integrations/transcript-glossary-files.md).
3. Run `audita process input.json --config config.yml --glossary glossary.yaml --output corrected.json`.
4. Check the exit status, stderr summary, corrected transcript, and reports.
   A completed run can contain recoverable model errors and still apply
   corrections that passed every required validator.

## Required Output Files

Reporting is enabled by default. For file transcript output, `errors.yml`,
`recoveries.yml`, and `report.md` go in the transcript output's parent directory
unless `--report-dir` is explicitly supplied. For stdout transcript output, they
go in the effective `reporting.stdout_dir` (default `.`), including a
`--report-dir` override. A config-file or overlay value for
`reporting.stdout_dir` alone does not redirect file-output reports. An active
selected report directory must be nonblank. `--reporting=false` suppresses all
three reports and leaves their destination inactive, so it is not probed merely
because `--report-dir` was supplied. It does not suppress the stderr summary or
fatal errors. Stdout contains only transcript JSON; file output leaves it empty.

Existing report directories and parents for regular transcript files must be
writable. Audita prevents report writes from overwriting transcript, glossary,
loaded configuration, or loaded profile sources, and rejects conflicting output
destinations. The final transcript may intentionally replace its own input after
successful processing; other input/configuration/profile sources remain protected.
Preparation never truncates an existing transcript. Device and pipe destinations
(such as `/dev/null` and named pipes) receive ordinary writes at publication time;
they are not opened during preflight or replaced with regular files. A pipe write
can wait for its reader, and stream write errors are fatal. With reporting enabled,
reports still use the output path's parent unless an explicit `--report-dir`
selects another directory; disable reporting when that placement is unsuitable
for a stream destination.

With reporting enabled, all three reports are initialized as `in_progress` before
input processing. Output is encoded fully before publication. Each regular output
file is replaced through a temporary file on its destination filesystem:
transcript first, then `errors.yml`,
`recoveries.yml`, and `report.md`. This is per-file replacement, not a
multi-file transaction. New files honor the process umask; replacing an existing
file preserves its permission bits. A late report error may leave the transcript
published; the process exits nonzero and attempts failed-status reports. On fatal processing
or cancellation, no completed transcript is published, but partial reports are
finalized where possible. An uncatchable termination can leave `in_progress`.

## Diagnostics Directory

`--debug` or `diagnostics.debug` enables detailed evidence independently of
reporting. One directory named `run-<id>` is created under
`diagnostics.work_dir` (default `/tmp/audita`), which `--work-dir` can override,
and retained on success or failure. Selecting `--work-dir` alone does not enable
capture. Without debug, no directory or payload files are created. The parent
is created when needed only for debug. Failure to
write optional debug evidence prints a redacted stderr diagnostic but does not
change correction decisions or the exit status.

Debug evidence includes invocation and effective settings, configuration
origins, selected profiles, redacted source and normalized snapshots,
normalization and initial chunk summaries, all captured proposed candidates
and validator decisions in `correction-ledger.json`, execution/utilization
records, and model interaction files. Individual artifact writes can fail; a
directory's existence does not prove every file was written. These files can
contain transcript text and prompt/response payloads. Configured backend
credentials are redacted, but the transcript itself is not anonymized. Protect
and retain the directory according to the sensitivity of the input.

## Failure Inspection and Recovery

Exit `0` means processing and every enabled required output completed. Exit
`1` means cancellation, fatal processing, or required-output failure. Exit `2`
identifies usage or configuration/destination selection errors. Recoverable
model-operation failures appear in `errors.yml` as one record per affected
work unit; they do not automatically make the run fail. `recoveries.yml`
records successful operations that needed retry, repair, or proposal filtering.
`report.md` shows every initial chunk and configured module instance, including
interrupted and unattempted work. Ordinary reports omit transcript excerpts and
full decision ledgers; enable debug when those are needed.

Read stderr and report status first. If a required output failed after a
transcript was published, do not treat the file alone as proof of a completed
run. Fix the input, service, or destination problem and rerun. Audita has no
resume/checkpoint API.