Refresh documentation and policies and simplify releases

docs/integrations/subprocess.md

@@ -1,99 +1,40 @@
 # Subprocess Integration
 
-## Scope
+This guide explains how a parent process can invoke Audita and consume its results.
+The [CLI reference](../cli.md) owns command syntax, streams, and exit semantics;
+[configuration](../config.md) owns discovery and precedence.
 
-This document describes how a parent process should invoke Audita as a subprocess.
+## Invocation
 
-It covers:
-- invocation shape;
-- stdout/stderr behavior;
-- output/report file behavior;
-- diagnostics and exit behavior.
+Use an argument array with the transcript path and required glossary argument,
+following the [process examples](../cli.md#process-examples). For machine workflows,
+select explicit transcript and report destinations rather than depending on the
+working directory or run-directory retention. Supplying a configuration path also
+makes file selection predictable; inherited environment overrides still apply.
 
-For full CLI and config references, see [`docs/cli.md`](../cli.md) and [`docs/config.md`](../config.md).
+Resolve the executable deliberately and set the child's working directory so
+relative input/output paths and reported artifact paths have a known base.
+Read stdout and stderr concurrently to avoid pipe blocking, and impose timeout
+or cancellation in the parent process when needed.
 
-## Recommended Invocation
+## Result Handling
 
-Use explicit output and report paths for machine workflows:
+Interpret the exit result according to the
+[CLI output and exit contract](../cli.md#process-output-and-exit-behavior).
+Consume transcript/report data through the
+[output-file contract](output-files.md), and treat stderr as human-readable detail.
+The report supplements the exit result: it may be absent after early failures,
+and output may have been written before a later reporting or cleanup failure.
 
-```sh
-audita process <transcript.json> \
-  --glossary <glossary.yaml> \
-  --output <output-transcript.json> \
-  --report-json <report.json>
-```
+If processing fails, preserve available evidence and follow
+[operations recovery](../operations.md#failure-inspection-and-recovery).
+For reports retained outside the run directory, account for the
+[artifact lifecycle](../operations.md#retention-behavior) before dereferencing
+reported paths. Neither the existence of an output file nor a diagnostics path
+alone establishes successful completion.
 
-Optional commonly used flags:
-- `--config <path>`
-- `--output-schema <bare-segments|audita-v1>`
-- `--work-dir <dir>`
-- `--work-dir-retention <always|auto|never>`
-- `--transcript-description <text>`
+## Related Contracts
 
-## Stdout Contract
-
-On success:
-- with `--output`: stdout is expected to be empty;
-- without `--output`: stdout contains transcript JSON only.
-
-`--report-json` output is never written to stdout.
-
-## Stderr Contract
-
-Stderr is human-readable status/error output.
-
-On failures:
-- stderr includes a concise top-level error;
-- when diagnostics are initialized, stderr includes diagnostics directory path.
-
-Do not treat stderr as a machine-stable JSON channel.
-
-## Output and Report File Contract
-
-Transcript output:
-- `--output` writes corrected transcript JSON to the provided path;
-- output write failures return nonzero.
-
-Report output:
-- `--report-json` writes machine-readable process report JSON to the provided path;
-- run diagnostics also attempt to write their own `report.json`;
-- report write failures return nonzero;
-- on failure paths, report writing is best-effort and does not mask the primary run error.
-
-## Diagnostics Contract
-
-When run-directory initialization succeeds, per-run diagnostics artifacts are written under the configured work directory.
-
-Typical artifacts include:
-- `source-transcript.json`
-- `source-transcript-parsed.json`
-- `normalized-transcript.json`
-- `normalization-summary.json`
-- `chunking-summary.json`
-- `invocation.json`
-- `effective-config.json`
-- `utilization-diagnostics.json`
-- `correction-ledger.json`
-- `report.json`
-- `error.log` (failure)
-
-Retention behavior is controlled by `--work-dir-retention` / config.
-
-## Exit Behavior
-
-Exit codes:
-- `0`: success;
-- `1`: runtime processing/output/report failure;
-- `2`: CLI usage or configuration input error.
-
-Treat any nonzero as subprocess failure.
-
-## Parent-Process Guidance
-
-For reliable orchestration:
-- read stdout and stderr concurrently to avoid pipe blocking;
-- prefer `--output` and `--report-json` for machine parsing;
-- use timeout/cancellation in the parent process;
-- inspect diagnostics path and `report.json`/`error.log` on failure.
-
-For input file contracts, see [`docs/integrations/transcript-glossary-files.md`](transcript-glossary-files.md).
+- [Transcript and glossary inputs](transcript-glossary-files.md)
+- [LLM endpoint compatibility](openai-compatible-llm.md)
+- [Configuration inspection commands](../cli.md#configuration-commands)