Add operations and troubleshooting documentation

docs/operations.md

@@ -0,0 +1,113 @@
+# Audita Operations
+
+## Scope
+
+This document covers operational behavior for `audita process` as currently implemented:
+- run lifecycle;
+- output and report files;
+- diagnostics artifacts;
+- run-directory retention behavior;
+- failure inspection and recovery.
+
+For command syntax, see [`docs/cli.md`](cli.md).
+
+## Process Run Lifecycle
+
+A `process` run performs these high-level steps:
+1. load effective config (defaults + optional file + env + CLI);
+2. create a per-run diagnostics directory;
+3. load transcript JSON and glossary YAML;
+4. parse/validate input schemas;
+5. normalize transcript and compute chunking;
+6. run configured modules/validators;
+7. serialize output schema and write transcript output;
+8. build and write process report;
+9. apply run-directory retention.
+
+If a failure happens after diagnostics initialization, the run writes failure details and returns nonzero.
+
+## Output Files
+
+Transcript output:
+- when `--output <path>` is set, corrected transcript JSON is written to that file;
+- when `--output` is omitted, corrected transcript JSON is written to stdout.
+
+Report output:
+- when `--report-json <path>` is set, Audita writes a process report JSON file;
+- the run directory also writes its own `report.json` artifact.
+
+On success with `--output`, stdout is expected to be empty.
+
+## Diagnostics Directory
+
+By default, runs use `work_dir` from effective config (default `/tmp/audita`).
+Each run directory is created under the work dir using a generated ID like `run-<unix-nanos>`.
+
+Top-level diagnostics artifacts:
+- `source-transcript.json`
+- `source-transcript-parsed.json`
+- `normalized-transcript.json`
+- `normalization-summary.json`
+- `chunking-summary.json`
+- `utilization-diagnostics.json`
+- `correction-ledger.json`
+- `invocation.json`
+- `effective-config.json` (redacted)
+- `report.json`
+- `error.log` (failure runs)
+
+Report diagnostics metadata includes resolved paths to these artifacts.
+
+## Correction Ledger and Utilization Diagnostics
+
+`correction-ledger.json` records correction dispositions:
+- `applied`
+- `skipped`
+- `rejected`
+- `failed`
+
+`utilization-diagnostics.json` records effective concurrency and execution timing summaries for run/module/validator activity.
+
+## Retention Behavior
+
+Retention is controlled by `work_dir_retention` (`auto|always|never`).
+
+Current behavior:
+- failed runs are always retained;
+- `always`: successful runs are retained;
+- `auto`: successful runs are retained only when skipped/rejected corrections occurred; clean successful runs are removed;
+- `never`: successful runs are currently retained (same net retention outcome as `always` in current implementation).
+
+Even when a successful run directory is removed under `auto`, an explicit `--report-json` file is still preserved at its target path.
+
+## Failure Inspection
+
+For failed runs:
+1. read stderr for the top-level failure and diagnostics path;
+2. open `error.log` in the reported run directory;
+3. inspect run `report.json` (`status`, `error_phase`, `error_message`);
+4. inspect related artifacts referenced by report diagnostics metadata.
+
+Typical `error_phase` values include:
+- `transcript_read`
+- `glossary_read`
+- `transcript_schema`
+- `glossary_schema`
+- `chunking`
+- `runner_setup`
+- `runner_execution`
+- `output_schema`
+- `serialization`
+- `output_write`
+- `stdout_write`
+
+## Recovery Guidance
+
+Safe recovery pattern:
+1. correct the immediate input/config/output-path problem;
+2. rerun with `--work-dir-retention always` during debugging;
+3. once stable, restore your normal retention mode.
+
+Not implemented:
+- resume/checkpoint APIs
+- remote diagnostics/report storage