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.
A longer exempt name still takes precedence over a shorter protected spelling
inside it. 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.correction_repair_profile` | effective proposal profile | Profile for correction repair; null clears an inherited selection before fallback. |
| `llm.correction_repair_attempts` | `1` | Nonnegative repair attempts per correction; zero disables correction repair. |
| `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. |

For example, an entry can disable correction repair or select another profile:

```yaml
llm:
  proposal_profile: local
  correction_repair_attempts: 2
pipeline:
  stages:
    - module: grammar
      llm:
        correction_repair_profile: review
    - module: spoken_word
      llm:
        correction_repair_attempts: 0
```

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. An explicit root correction repair profile is inherited
by each entry unless overridden or cleared with null; otherwise the entry uses
its effective proposal profile. The repair profile is checked only when its
attempt budget is positive. Each correction repair attempt is a logical call
that can also use the configured transient retries and structural repairs. 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).