audita/docs/operations.md

Audita Operations

This guide owns physical output placement and failure handling. The CLI reference owns flags and streams, configuration owns settings, and the output contract 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.
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. For stdout transcript output, they go in reporting.stdout_dir (default .), overridden by --report-dir. --reporting=false suppresses all three reports and removes their path requirements. It does not suppress the stderr summary or fatal errors. Stdout contains only transcript JSON; file output leaves it empty.

Existing report directories and transcript-output parents must be writable. Audita checks active destinations against input, configuration, and selected profile files before model dispatch. It preflights file transcript output without truncating an existing file. With reporting enabled, all three reports are initialized as in_progress before input processing. Output is encoded fully before publication. Each file is replaced through a temporary file in its destination directory: transcript first, then errors.yml, recoveries.yml, and report.md. This is per-file replacement, not a multi-file transaction. 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 enables detailed evidence independently of reporting. One directory named run-<id> is created under diagnostics.work_dir (default /tmp/audita) and retained on success or failure. 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.