Establish canonical documentation paths and update README links

2026-05-24 00:47:27 +00:00
parent 76651333b1
commit 40e8b54d3b
7 changed files with 292 additions and 277 deletions
--- a/docs/config.md
+++ b/docs/config.md
@@ -0,0 +1,149 @@
+# Audita Configuration
+
+## Scope
+This document defines the supported versioned YAML configuration model and runtime precedence behavior.
+
+## Supported file version
+Current supported config file version:
+- `version: 1`
+
+Validation rules:
+- missing `version` fails;
+- unsupported version fails;
+- unknown YAML fields fail (strict decoding).
+
+## Config path resolution
+For `audita process` and `audita config print-effective`, path resolution order is:
+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 `--config` path is an error;
+- missing `AUDITA_CONFIG` path is an error;
+- missing both default paths is non-fatal.
+
+## Effective precedence
+`audita process` effective precedence:
+1. defaults
+2. file config
+3. environment overrides
+4. CLI overrides
+
+`audita config print-effective` uses:
+1. defaults
+2. file config
+3. environment overrides
+
+`audita config validate` intentionally uses file-only validation:
+1. defaults
+2. file config
+
+Environment overrides are not applied in `config validate`.
+
+## Supported top-level YAML fields
+```yaml
+version: 1
+
+pipeline:
+  modules: [glossary, homophones, glossary, spoken_word, grammar]
+
+output:
+  schema: bare-segments
+
+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: 120s
+    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: "optional transcript background context"
+
+diagnostics:
+  work_dir: /tmp/audita
+  retention: auto
+```
+
+## Module and output-schema validation
+`pipeline.modules` keys are validated against the built-in supported module catalog.
+
+Supported module keys:
+- `glossary`
+- `homophones`
+- `spoken_word`
+- `grammar`
+
+Repeated supported module keys are allowed.
+
+`output.schema` is validated against the built-in output schema catalog.
+
+Supported output schema keys:
+- `bare-segments`
+- `audita-v1`
+
+Unknown module keys and unknown output schema keys fail validation.
+
+## Duration field parsing
+Duration-like fields support:
+- numeric seconds (for example `120`, `3.5`)
+- duration strings (for example `120s`, `2m`)
+
+LLM timeout duration strings must resolve to whole seconds.
+
+## Secret handling
+Use `api_key_env` fields for secrets:
+- `llm.proposal.api_key_env`
+- `llm.validation.api_key_env`
+
+These fields store environment variable names, not secret values.
+
+Resolved secret values are redacted from:
+- `audita config print-effective` output;
+- diagnostics `effective-config.json`;
+- report and diagnostics payloads.
+
+## Commands
+Validate a file config:
+```sh
+audita config validate --config ./audita.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.