audita/docs/operations.md

# Audita Operations

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

## Processing

Inspect the application and PromptKit resources, prepare a transcript, then run
`audita process` with the desired destination. The [examples](../examples/README.md)
show complete projects. Processing preflight checks every configured glossary
correction and selected profile before output preparation and model work. Empty
protection and an empty pipeline are valid. A completed run can contain
recoverable model errors while still applying independently validated edits.
Correction repair sends the complete original proposal exchange and branch
history to the selected repair provider. A provider rejection ends that branch
as unavailable; other approved edits can still be applied. See
[configuration](config.md#settings) for the attempt budget and profile selection.

## Outputs and lifecycle

Reporting is enabled by default. For transcript file output, `errors.yml`,
`recoveries.yml`, and `report.md` are placed beside that file unless `--report-dir`
is supplied. For stdout transcript output they use the effective report directory.
Disabling reporting leaves its destination inactive and unprobed. Quiet mode
requires a transcript file or `/dev/null`; it suppresses optional messages, not
failures. Stdout carries transcript JSON when selected.

Before processing, Audita checks destination collisions against the transcript,
consumed application and PromptKit sources, and effective host message files. An
intentional in-place transcript replacement is allowed. A regular transcript
output is prepared in a sibling temporary file, leaving the final destination
untouched until successful publication. Pipes and devices are opened only for
delivery, and a pipe can wait for its reader. If a transcript destination changes
between a regular file and a pipe or device during processing, Audita can report a
delivery failure while preserving the new destination. Parent directories for
required outputs must already exist.

Enabled reports are initialized as `in_progress` before processing. The
transcript is published before final reports; the files do not form a single
transaction. A late report failure may therefore leave a published transcript.
Fatal errors and cancellation clean unpublished temporary resources and attempt
failed-status final reports. An uncatchable termination can leave `in_progress`
evidence. Read exit status and reports together rather than treating a file's
existence as proof of success.

## Debug evidence

The shared `--debug` flag enables retained artifacts in a run directory beneath
`diagnostics.work_dir`; selecting a work directory alone does not enable capture.
Optional debug preparation or writes can produce redacted warnings without
changing correction decisions or the required output result. Debug material can
include transcript content, prompts, responses, and correction decisions. It is
not anonymized; protect it according to the input's sensitivity. Configured
credential values are redacted at the diagnostic boundary. Repair interactions
and revalidation artifacts include proposal and attempt coordinates; the
correction ledger connects them to the original edit.

## Recovery

Exit `0` indicates completion of processing and required outputs; nonzero status
indicates an input, processing, cancellation, or required-output failure.
Recoverable model-operation failures and successful repairs or retries are
recorded separately in the ordinary YAML reports. The Markdown matrices identify
pipeline position, module, and optional operator ID. Fix the input, service, or
destination and rerun when necessary; Audita has no resume or checkpoint API.