audita/docs/config.md

# Audita Configuration

Audita uses version 3 application configuration. See the [migration guide](migrations/v3.md)
and [examples](../examples/) for complete projects. Command syntax is owned by
[the CLI reference](cli.md).

## Loading and composition

An explicit `--config` selects one main YAML file. Without it, ConfigKit searches
the working directory, user configuration directory, and Unix system directories
for `audita` configuration. If no file is found, built-in defaults apply. An
explicit invalid selection or failure of a selected file is an error; search does
not continue after a selected file fails. An omitted version uses the v3 schema;
a supplied version must be `3`.

Operator sources may use ConfigKit imports. The selected main file provides the
base for an optional `overlays/<name>.yml`, optional `glossary.yml`, and recursive
`glossary/` YAML files. Without a main source, automatic companion files are not
loaded from the working directory. ConfigKit composes sources, resolves native
inheritance, applies explicit overrides, records derived defaults, and validates
the result. Its [configuration reference](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.0/docs/config.md)
owns native composition and provenance semantics.

### PromptKit profiles and operator prompts

PromptKit loads its default catalog and Audita's embedded prompts, followed by
optional `prompts.yml` and recursive `prompts/` YAML files beside the application
main. Native imports, resource collections, inheritance, and replacement apply.
Profiles, backends, models, credentials, admission, and provider parameters belong
to PromptKit configuration; see its [format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.21.0/docs/formats.md).
The engine captures its sources for an invocation. Edit files and run a new
invocation to pick up changes. Inspection does not require model credentials.

## Pipeline and glossary selections

`glossary_collections` maps names to collections with an ordered `entries` list.
Each entry has an `id`, `name`, and `category`; `description`, `aliases`, and
`plural` provide optional context. Entries are identified within their collection
by `id`. Root `glossaries` and `protected_terms` select collection names. If root
protection is omitted, it derives from the root glossary selection.

`pipeline.stages` is an ordered list of `module` records; supported modules are
`glossary`, `homophones`, `spoken_word`, and `grammar`. The default sequence is
`glossary`, `homophones`, `glossary`, `spoken_word`, `grammar`. Repeated modules
run separately; `[]` runs normalization without model processing. An optional
nonempty, unique `id` identifies a record in evidence. Each record may override
`glossaries`, `protected_terms`, `confidence_threshold`, and fields under `llm`,
`validation`, and `context`. Omitted fields inherit their resolved root values.
Explicit empty lists and null list selections clear a selection.

Each entry receives its selected context and independent protection. Glossary
correction exempts active recognized spellings from protection for that entry;
other protected spellings remain protected. A glossary correction must have at
least one selected entry at processing preflight. Empty definitions and empty
protection remain valid configuration.

## Settings

| Setting | Default | Meaning |
| --- | --- | --- |
| `llm.proposal_profile` | unset | PromptKit profile for proposals; required for processing entries. |
| `llm.validation_profile` | effective proposal profile | Profile for model validation; null clears a selection before fallback. |
| `llm.transient_retries` | `2` | Additional transient attempts per generation. |
| `llm.repair_attempts` | `2` | Structural repairs, from zero through three. |
| `llm.operation_timeout` | `15m` | Positive duration per logical operation. |
| `validation.max_prompt_tokens` | `2048` | Positive validation batching budget. |
| `thresholds.<module>` | `0.8` | Root confidence threshold for each module, in `[0, 1]`. |
| `context.description` | empty | Prompt context; at most 500 bytes after trimming. |
| `chunking.target_sections` | unset | Optional positive target. |
| `chunking.max_section_tokens`, `chunking.min_section_tokens` | `8192`, `2048` | Positive section bounds; minimum must not exceed maximum. |
| `normalization.max_segment_gap`, `normalization.ellipsis_gap` | `4`, `3.5` | Nonnegative seconds. |
| `normalization.max_segment_duration`, `normalization.max_segment_tokens` | `60`, `2048` | Positive seconds and token estimate. |
| `output.schema` | `bare-segments` | Output format; see [output contracts](integrations/output-files.md). |
| `reporting.enabled`, `reporting.stdout_dir` | `true`, `.` | Ordinary report capture and default directory for stdout output. |
| `diagnostics.work_dir` | `/tmp/audita` | Parent directory for optional debug capture. |

Processing profiles are selected explicitly; no profile or glossary is selected
automatically. The validation selection falls back after root and per-entry
settings are combined. Null does not disable validation. Numeric zero and false
retain their field meaning, subject to validation. Inspect recorded origins and
default dependencies using the [native commands](cli.md).