audita/docs/config.md

Audita Configuration

This reference describes the version-2 configuration loader in internal/core/config. CLI command parsing and profile inspection are being connected in later work; the current CLI is not yet a usable entry point for this schema. Complete copyable examples will be migrated with that integration.

Loading and precedence

The application selects one main YAML file: an explicit --config, then /usr/local/etc/audita/config.yml if present, then /etc/audita/config.yml if present. Missing system candidates are skipped; an explicit missing or empty path, inaccessible selected file, or absence of any selected file is an error. config validate requires an explicit file. ConfigKit loads built-in defaults, the selected file, an optional named overlay from overlays/<name>.yml beside the main file, and only explicitly supplied setting overrides, in that order. Imports and secret-directory bootstrap are disabled. Unknown fields and missing, null, or non-integer version: 2 are errors. Version-1 files require migration; no compatibility loader or implicit environment configuration remains.

Validation runs after overlays, explicit overrides, and derived settings have resolved. An override can therefore repair an invalid lower-precedence setting when that setting can be decoded. ConfigKit retains field origins and derivations for effective-configuration inspection. Its effective YAML redacts resolved credentials.

Settings

Field	Default	Rule
profiles_dir	profiles	Nonempty; profile files are resolved relative to the selected main file.
backends.<id>.endpoint	None	Required nonempty endpoint for each backend. At least one backend is required.
backends.<id>.concurrency	1	Positive finite capacity; shared by both roles using that backend.
backends.<id>.queue_capacity	1024	Nonnegative; zero disables waiting admission.
backends.<id>.credential	Unset	Optional environment-variable secret reference; omission or null means unauthenticated use.
llm.proposal_profile	None	Required nonempty profile ID.
llm.validation_profile	Final proposal profile	Omission inherits the final proposal selection; explicit empty or null fails.
llm.transient_retries	2	Nonnegative additional attempts per generation.
llm.repair_attempts	2	Additional structural repair generations, from zero through three.
llm.operation_timeout	15m	Positive Go duration string per logical call.
pipeline.modules	[glossary, homophones, glossary, spoken_word, grammar]	Ordered module keys; repeats are meaningful and an explicit empty list runs no correction modules.
output.schema	bare-segments	bare-segments or audita-v1. See output formats.
validation.max_prompt_tokens	2048	Positive validation batching budget.
chunking.target_sections	Unset	Optional positive target; omission or null selects automatic chunking.
chunking.max_section_tokens	8192	Positive maximum estimate.
chunking.min_section_tokens	2048	Positive and no greater than maximum.
normalization.max_segment_gap	4.0	Nonnegative numeric seconds.
normalization.ellipsis_gap	3.5	Nonnegative numeric seconds.
normalization.max_segment_duration	60.0	Positive numeric seconds.
normalization.max_segment_tokens	2048	Positive token estimate.
thresholds.glossary, .homophones, .spoken_word, .grammar	0.8 each	Confidence thresholds in [0, 1].
context.description	Empty	Trimmed prompt context, at most 500 bytes.
diagnostics.work_dir	/tmp/audita	Nonempty artifact parent directory.
diagnostics.retention	auto	auto, always, or never; see operations.

Module keys select correction modules; validator chains remain built into them. The loader preserves module order and repetitions. Normalization time settings accept numeric seconds only. The operation timeout uses a duration string.

Credentials

A backend credential is a ConfigKit secret reference containing an environment variable name, such as credential: AUDITA_SERVICE_KEY. Every reference that survives overlay and override resolution must name a set, nonempty variable, including credentials on backends unused by the selected roles. A replacement reference resolves only the replacement; null removes the reference. General AUDITA_* and OPENROUTER_API_KEY variables have no implicit setting effect. Secret values are available to the runtime through the resolved reference, while ConfigKit's effective output and provenance contain no resolved secret values.

The CLI reference will be updated as the shared input parser and profile inspection commands are connected. Current invocation syntax belongs in CLI.