Refresh documentation and policies and simplify releases

docs/cli.md

@@ -3,10 +3,12 @@
 ## Shortest Useful Command
 
 ```sh
-audita process <transcript.json> --glossary <glossary.yaml> --output <corrected.json>
+audita process transcript.json --glossary glossary.yaml --output corrected.json
 ```
 
-This command validates input files, runs the configured correction pipeline, and writes corrected transcript JSON.
+This command runs the core workflow with your input files. For a copyable example
+using maintained inputs and explicit prerequisites, see the [README](../README.md).
+Commands here assume `audita` is on `PATH`; use `./bin/audita` after a local build.
 
 ## Command Overview
 
@@ -34,13 +36,17 @@ Input requirements:
 - exactly one transcript JSON positional argument is required;
 - `--glossary <path>` is required.
 
-Config path selection for `process`:
-1. `--config <path>`
-2. `AUDITA_CONFIG`
-3. `/usr/local/etc/audita/config.yml` (if present)
-4. `/etc/audita/config.yml` (if present)
+Place the transcript path first, followed by flags, as shown above. Flag values
+may use `--name value` or `--name=value`. Unknown flags or extra positional
+arguments are errors. Flags before a final transcript path are also accepted;
+do not interleave further flags after a positional argument consumed by the flag
+parser.
 
-For precedence and full config schema, see [`docs/config.md`](config.md).
+[Configuration discovery and precedence](config.md#loading-model) determine the
+initial settings; explicit process flags supply overrides. Configuration is loaded
+before process help is printed, so invalid discovered configuration can also make
+process help fail. Input formats belong to the
+[input-file contract](integrations/transcript-glossary-files.md).
 
 ### `process` Flag Reference
 
@@ -49,7 +55,7 @@ Core I/O flags:
 - `--glossary <path>`: glossary YAML input path (required).
 - `--output <path>`: corrected transcript JSON output file path.
 - `--report-json <path>`: machine-readable report JSON output path.
-- `--output-schema <key>`: output schema key (`bare-segments` or `audita-v1`).
+- `--output-schema <key>`: output encoder selection; see [configuration](config.md#pipeline-and-output).
 - `--modules <csv>`: comma-separated module sequence override.
 
 Primary LLM flags:
@@ -91,7 +97,11 @@ Threshold flags:
 Context and diagnostics flags:
 - `--transcript-description <text>`: background context for prompts; does not override transcript content.
 - `--work-dir <path>`: per-run diagnostics work directory.
-- `--work-dir-retention <auto|always|never>`: run-directory retention policy.
+- `--work-dir-retention <value>`: retention selection; see [configuration](config.md#thresholds-context-and-diagnostics).
+
+Flag descriptions identify their settings; defaults, accepted keys, numeric
+constraints, and inheritance rules are owned by [configuration](config.md).
+Normalization time flags use numeric seconds; LLM timeout flags use integer seconds.
 
 ### `process` Output and Exit Behavior
 
@@ -99,11 +109,16 @@ Context and diagnostics flags:
 - Without `--output`: stdout contains transcript JSON only on success.
 - `--report-json` writes a file and is never printed to stdout.
 - Stderr is human-readable diagnostics/errors.
-- On failures after diagnostics initialization, stderr includes the diagnostics directory path.
+- Processing failures include the diagnostics directory path when initialization
+  succeeded. Later report-write or retention errors can omit that path.
+- Output files may already exist when a later reporting or cleanup failure occurs.
+- Rejected/skipped corrections and warnings can occur in a successful run; inspect
+  the [report format](integrations/output-files.md#process-report) for details.
+- Diagnostic wording is human-readable and is not a machine-stable JSON channel.
 
 Exit behavior:
 - `0`: success.
-- `1`: runtime failure during processing/reporting/output paths.
+- `1`: runtime failure during processing/reporting/output or retention handling.
 - `2`: CLI usage or configuration input error.
 
 Integration references:
@@ -145,42 +160,39 @@ audita process transcript.json \
   --output corrected.json
 ```
 
-## `config validate`
+## Configuration Commands
 
-Usage:
+### `config validate`
 
 ```sh
-audita config validate --config <path>
+audita config validate --config examples/minimal-config.yml
+audita config validate --config examples/production-config.yml
 ```
 
-Behavior:
-- validates defaults merged with file config;
-- does not apply environment overrides;
-- prints `config is valid` on success.
+The only command-specific flag is `--config <path>`, which is required.
+Positional arguments are rejected. Success prints `config is valid` to stdout
+and returns zero; usage, file-read, parse, and validation errors go to stderr and
+return `2`. See [applied configuration sources](config.md#effective-precedence)
+and [validation boundaries](config.md#examples).
 
-Errors:
-- `--config` is required;
-- positional arguments are rejected;
-- validation failures are printed to stderr.
-
-## `config print-effective`
-
-Usage:
+### `config print-effective`
 
 ```sh
-audita config print-effective [--config <path>]
+audita config print-effective --config examples/minimal-config.yml
 ```
 
-Config path selection:
-1. `--config <path>` when provided
-2. `AUDITA_CONFIG`
-3. `/usr/local/etc/audita/config.yml` (if present)
-4. `/etc/audita/config.yml` (if present)
+The only command-specific flag is optional `--config <path>`. Positional
+arguments are rejected. Without an explicit file, [discovery](config.md#loading-model)
+applies. Success prints redacted configuration JSON to stdout and returns zero.
+Usage and configuration errors return `2`; serialization or stdout-write failures
+return `1`.
 
-Behavior:
-- merges defaults, optional config file, and environment overrides;
-- prints redacted JSON to stdout.
+The printed JSON reflects the effective in-memory configuration; it is not a YAML
+configuration file and is not the process-report schema. Use it to inspect merged
+settings, not as a file to pass back to the YAML loader.
 
-Errors:
-- positional arguments are rejected;
-- resolution or parse failures are printed to stderr.
+## Help
+
+Root invocation without arguments and root help print usage successfully. Use
+`--help` or `-h` for subcommand help. Help normally returns zero; process help has
+the configuration-loading caveat described above. Unknown commands return `2`.