Rewrite config docs and add validated example files

docs/config.md

@@ -1,48 +1,81 @@
 # Audita Configuration
 
 ## Scope
-This document defines the supported versioned YAML configuration model and runtime precedence behavior.
 
-## Supported file version
+This is the canonical configuration reference for Audita.
-Current supported config file version:
-- `version: 1`
 
-Validation rules:
+It documents:
-- missing `version` fails;
+- config path resolution;
-- unsupported version fails;
+- effective precedence across defaults, file config, environment, and CLI;
-- unknown YAML fields fail (strict decoding).
+- supported `version: 1` YAML schema;
+- environment overrides;
+- CLI override relationship;
+- validation and secrets behavior.
 
-## Config path resolution
+For CLI command syntax, see [`docs/cli.md`](cli.md).
-For `audita process` and `audita config print-effective`, path resolution order is:
+
+## Loading Model
+
+Path resolution for `audita process` and `audita config print-effective`:
 1. `--config <path>`
 2. `AUDITA_CONFIG`
 3. `/usr/local/etc/audita/config.yml` (if present)
 4. `/etc/audita/config.yml` (if present)
 
-Missing-path behavior:
+Missing explicit path behavior:
-- missing `--config` path is an error;
+- missing `--config` target is an error;
-- missing `AUDITA_CONFIG` path is an error;
+- missing `AUDITA_CONFIG` target is an error.
-- missing both default paths is non-fatal.
 
-## Effective precedence
+Missing default-path files are non-fatal.
-`audita process` effective precedence:
+
+## Effective Precedence
+
+`audita process`:
 1. defaults
 2. file config
 3. environment overrides
 4. CLI overrides
 
-`audita config print-effective` uses:
+`audita config print-effective`:
 1. defaults
 2. file config
 3. environment overrides
 
-`audita config validate` intentionally uses file-only validation:
+`audita config validate`:
 1. defaults
 2. file config
 
-Environment overrides are not applied in `config validate`.
+`config validate` is intentionally file-only (no environment overrides).
+
+## Defaults
+
+Current defaults:
+- modules: `glossary,homophones,glossary,spoken_word,grammar`
+- output schema: `bare-segments`
+- primary model: `openrouter/google/gemma-4-31b-it`
+- primary base URL: `https://openrouter.ai/api/v1`
+- primary timeout: `600` seconds
+- max retries: `3`
+- total/proposal LLM concurrency: `1`
+- validation max prompt tokens: `2048`
+- max section tokens: `8192`
+- min section tokens: `2048`
+- confidence thresholds: `0.8`
+- normalization max segment gap: `4.0`
+- normalization ellipsis gap: `3.5`
+- normalization max segment duration: `60.0`
+- normalization max segment tokens: `2048`
+- transcript description: empty
+- work dir: `/tmp/audita`
+- work dir retention: `auto`
+
+## YAML Schema (`version: 1`)
+
+Supported file version:
+- `version: 1` (required)
+
+Unknown YAML fields are rejected.
 
-## Supported top-level YAML fields
 ```yaml
 version: 1
 
@@ -57,18 +90,18 @@ llm:
     base_url: https://openrouter.ai/api/v1
     model: openrouter/google/gemma-4-31b-it
     api_key_env: AUDITA_LLM_API_KEY
-    timeout: 120s
+    timeout: 600s
     max_retries: 3
   validation:
     base_url: https://openrouter.ai/api/v1
     model: openrouter/google/gemma-4-31b-it
     api_key_env: AUDITA_VALIDATION_LLM_API_KEY
-    timeout: 120s
+    timeout: 600
     max_retries: 3
 
 concurrency:
-  total_llm: 2
+  total_llm: 1
-  proposal_llm: 2
+  proposal_llm: 1
   validation_llm: 1
 
 chunking:
@@ -89,61 +122,115 @@ thresholds:
   grammar: 0.8
 
 context:
-  description: "optional transcript background context"
+  description: optional background context
 
 diagnostics:
   work_dir: /tmp/audita
   retention: auto
 ```
 
-## Module and output-schema validation
+Duration-parsing behavior:
-`pipeline.modules` keys are validated against the built-in supported module catalog.
+- `llm.*.timeout`: integer seconds or duration string; duration strings must resolve to whole seconds.
+- `normalization.*` duration-like fields: numeric seconds or duration string.
 
-Supported module keys:
+## Environment Overrides
-- `glossary`
-- `homophones`
-- `spoken_word`
-- `grammar`
 
-Repeated supported module keys are allowed.
+Modules:
+- `AUDITA_MODULES`
 
-`output.schema` is validated against the built-in output schema catalog.
+Config path:
+- `AUDITA_CONFIG`
 
-Supported output schema keys:
+Primary LLM:
-- `bare-segments`
+- `AUDITA_LLM_API_KEY` (falls back to `OPENROUTER_API_KEY` when unset)
-- `audita-v1`
+- `AUDITA_MODEL`
+- `AUDITA_BASE_URL`
+- `AUDITA_LLM_TIMEOUT_SECONDS`
+- `AUDITA_MAX_RETRIES`
 
-Unknown module keys and unknown output schema keys fail validation.
+Validation LLM:
+- `AUDITA_VALIDATION_LLM_API_KEY`
+- `AUDITA_VALIDATION_MODEL`
+- `AUDITA_VALIDATION_BASE_URL`
+- `AUDITA_VALIDATION_LLM_TIMEOUT_SECONDS`
+- `AUDITA_VALIDATION_MAX_RETRIES`
+- `AUDITA_VALIDATION_MAX_PROMPT_TOKENS`
 
-## Duration field parsing
+Concurrency:
-Duration-like fields support:
+- `AUDITA_TOTAL_LLM_CONCURRENCY`
-- numeric seconds (for example `120`, `3.5`)
+- `AUDITA_PROPOSAL_LLM_CONCURRENCY`
-- duration strings (for example `120s`, `2m`)
+- `AUDITA_VALIDATION_LLM_CONCURRENCY`
+- `AUDITA_LLM_CONCURRENCY` (legacy alias for total)
 
-LLM timeout duration strings must resolve to whole seconds.
+Chunking:
+- `AUDITA_MAX_SECTION_TOKENS`
+- `AUDITA_MIN_SECTION_TOKENS`
+- `AUDITA_TARGET_SECTIONS`
 
-## Secret handling
+Thresholds:
-Use `api_key_env` fields for secrets:
+- `AUDITA_GLOSSARY_CONFIDENCE_THRESHOLD`
-- `llm.proposal.api_key_env`
+- `AUDITA_HOMOPHONES_CONFIDENCE_THRESHOLD`
-- `llm.validation.api_key_env`
+- `AUDITA_SPOKEN_WORD_CONFIDENCE_THRESHOLD`
+- `AUDITA_GRAMMAR_CONFIDENCE_THRESHOLD`
 
-These fields store environment variable names, not secret values.
+Normalization:
+- `AUDITA_NORMALIZE_MAX_SEGMENT_GAP`
+- `AUDITA_NORMALIZE_ELLIPSIS_GAP`
+- `AUDITA_NORMALIZE_MAX_SEGMENT_DURATION`
+- `AUDITA_NORMALIZE_MAX_SEGMENT_TOKENS`
 
-Resolved secret values are redacted from:
+Diagnostics:
-- `audita config print-effective` output;
+- `AUDITA_WORK_DIR`
-- diagnostics `effective-config.json`;
+- `AUDITA_WORK_DIR_RETENTION` (`auto`, `always`, `never`)
-- report and diagnostics payloads.
+
+Transcript description:
+- no `AUDITA_*` environment variable is currently defined.
+
+## CLI Override Relationship
+
+CLI flags override file and environment values for `audita process`.
+
+The CLI supports canonical total concurrency (`--total-llm-concurrency`) and legacy alias (`--llm-concurrency`):
+- when both are provided at the same precedence layer, canonical total wins;
+- if proposal concurrency is not explicitly set and total is set via environment or CLI, proposal concurrency inherits that total;
+- validation concurrency inherits total only when validation concurrency is unset.
+
+For full flag syntax, see [`docs/cli.md`](cli.md).
+
+## Validation Rules
+
+Validation includes:
+- supported module keys only;
+- supported output schema keys only (`bare-segments`, `audita-v1`);
+- positive timeout/concurrency/token constraints;
+- `proposal_llm <= total_llm` and `validation_llm <= total_llm` when validation is set;
+- confidence thresholds in `[0.0, 1.0]`;
+- transcript description length `<= 500` characters;
+- non-empty work dir;
+- work-dir retention in `auto|always|never`.
+
+## Secrets
+
+Recommended secret handling:
+- use `llm.proposal.api_key_env` and `llm.validation.api_key_env` in file config;
+- use `AUDITA_*_API_KEY` environment overrides or CLI key flags when needed.
+
+`api_key_env` fields contain environment variable names, not secret values.
+
+Redaction behavior:
+- `audita config print-effective` redacts resolved API keys.
+- diagnostics and report paths redact configured secret values.
+
+## Examples
+
+- Minimal config: [`examples/minimal-config.yml`](../examples/minimal-config.yml)
+- Production-style config: [`examples/production-config.yml`](../examples/production-config.yml)
+- Tiny transcript input: [`examples/tiny-transcript.json`](../examples/tiny-transcript.json)
+- Tiny glossary input: [`examples/tiny-glossary.yaml`](../examples/tiny-glossary.yaml)
+
+Validate the config examples:
 
-## Commands
-Validate a file config:
 ```sh
-audita config validate --config ./audita.yml
+audita config validate --config examples/minimal-config.yml
+audita config validate --config examples/production-config.yml
 ```
-
-Print redacted effective config:
-```sh
-audita config print-effective --config ./audita.yml
-```
-
-## Compatibility notes
-Legacy compatibility flags and environment aliases remain available where implemented, but the stable configuration surface is the versioned YAML model described above.

docs/configuration.md

@@ -1,5 +0,0 @@
-# Moved: Configuration Reference
-
-The canonical configuration reference now lives at [`docs/config.md`](config.md).
-
-This file is retained temporarily as a migration shim for older links.

examples/minimal-config.yml

@@ -0,0 +1,6 @@
+version: 1
+output:
+  schema: bare-segments
+llm:
+  proposal:
+    api_key_env: AUDITA_LLM_API_KEY

examples/production-config.yml

@@ -0,0 +1,41 @@
+version: 1
+pipeline:
+  modules: [glossary, homophones, glossary, spoken_word, grammar]
+output:
+  schema: audita-v1
+llm:
+  proposal:
+    base_url: https://openrouter.ai/api/v1
+    model: openrouter/google/gemma-4-31b-it
+    api_key_env: AUDITA_LLM_API_KEY
+    timeout: 120s
+    max_retries: 3
+  validation:
+    base_url: https://openrouter.ai/api/v1
+    model: openrouter/google/gemma-4-31b-it
+    api_key_env: AUDITA_VALIDATION_LLM_API_KEY
+    timeout: 120
+    max_retries: 3
+concurrency:
+  total_llm: 2
+  proposal_llm: 2
+  validation_llm: 1
+chunking:
+  target_sections: 8
+  max_section_tokens: 8192
+  min_section_tokens: 2048
+normalization:
+  max_segment_gap: 4s
+  ellipsis_gap: 3.5s
+  max_segment_duration: 60s
+  max_segment_tokens: 2048
+thresholds:
+  glossary: 0.8
+  homophones: 0.8
+  spoken_word: 0.8
+  grammar: 0.8
+context:
+  description: "General context for domain vocabulary and speaker names."
+diagnostics:
+  work_dir: /tmp/audita
+  retention: auto

examples/tiny-glossary.yaml

@@ -0,0 +1,6 @@
+glossary:
+  - name: Audita
+    aliases:
+      - audita
+    category: product
+    summary: The Audita transcript correction CLI.

examples/tiny-transcript.json

@@ -0,0 +1,9 @@
+[
+  {
+    "id": 1,
+    "speaker": "A",
+    "start": 0.0,
+    "end": 1.2,
+    "text": "hello world"
+  }
+]