audita/docs/config.md

Audita Configuration

Audita uses version 3 application configuration. See the migration guide and examples for complete projects. Command syntax is owned by the CLI reference.

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 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. 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.
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.