# Migrating to Audita v2

Audita v2 adopts ConfigKit for configuration and PromptKit for LLM execution.
Version-1 configuration files, environment overlays, and retired flags are not
accepted. Copy a maintained [local](../../examples/minimal-config.yml) or
[service](../../examples/production-config.yml) example, then select real models
in the accompanying `examples/profiles/` files. A testing overlay is shown at
`examples/overlays/testing.yml`; its model choice carries no cost, speed, or
quality guarantee.

## Configuration and invocation

Use `version: 2` in a YAML main file. `--config` selects that file; otherwise
`process` and `config print-effective` look at
`/usr/local/etc/audita/config.yml`, then `/etc/audita/config.yml`.
`config validate` requires `--config`. `AUDITA_CONFIG` no longer selects a file.
Settings resolve from defaults, main file, optional `--overlay <name>` in
`overlays/<name>.yml`, then explicitly supplied setting flags. General `AUDITA_*`
environment overlays no longer apply. Unknown fields and version-1 files fail;
there is no automatic converter.

Keep transcript as the positional path and `--glossary`, `--output`, and
`--report-json` as invocation paths. Keep `pipeline.modules` / `--modules` and
`output.schema` / `--output-schema`. An explicit `pipeline.modules: []` or
`--modules ''` runs no correction modules; omission uses the default sequence.
Ordered repetitions still matter.

Move `llm.proposal.base_url` and `llm.validation.base_url` to a shared
`backends.<id>.endpoint` when both roles use one service. Move old role models to
PromptKit profile files and select them with `llm.proposal_profile` and
`llm.validation_profile`, or `--proposal-profile` and
`--validation-profile`. Omitted validation selection inherits the final proposal
selection; explicit empty or null is invalid. `profiles_dir` defaults to
`profiles` beside the main config. Complete profiles name a registered backend
and model. Per-role `--base-url`, `--validation-base-url`, `--model`, and
`--validation-model` are retired.

Move old `llm.*.api_key_env` to `backends.<id>.credential`, a scalar name of a
nonempty environment variable, such as `credential: AUDITA_SERVICE_KEY`.
Credentials on every surviving backend must resolve, including unselected
backends. Omit or set null for an unauthenticated local backend. Profiles cannot
perform another key lookup. `--llm-api-key` and `--validation-llm-api-key` are
retired. `AUDITA_LLM_API_KEY`, `OPENROUTER_API_KEY`, and
`AUDITA_VALIDATION_LLM_API_KEY` have no implicit meaning, though any of those
names can be used explicitly as a credential reference.

Replace `concurrency.total_llm`, `.proposal_llm`, and `.validation_llm` plus
`--total-llm-concurrency`, `--llm-concurrency`,
`--proposal-llm-concurrency`, and `--validation-llm-concurrency` with
`backends.<id>.concurrency` (default 1) and optional `queue_capacity` (default
1024; zero means no waiting admission). One backend capacity is shared by both
roles and all retry/repair attempts within this Audita process. It does not
coordinate other processes.

Move old role `timeout` values and `--llm-timeout-seconds` /
`--validation-llm-timeout-seconds` to profile `timeout_seconds`, a per-attempt
limit, and `llm.operation_timeout`, a Go duration such as `15m` covering the
whole logical call. Replace old `max_retries` and `--max-retries` /
`--validation-max-retries` with common `llm.transient_retries` (additional
eligible attempts per generation) and `llm.repair_attempts` (additional
generations for structurally invalid JSON). Explicit zero disables either
feature. Cancellation and the operation deadline cover capacity waiting,
backoff, generation, and repairs. PromptKit owns which failures can retry or
repair; Audita does not retry semantic rejections.

The following domain settings and explicit flags retain their meaning:

| File field | Explicit flag |
| --- | --- |
| `validation.max_prompt_tokens` | `--validation-max-prompt-tokens` |
| `chunking.target_sections` | `--target-sections` |
| `chunking.max_section_tokens`, `.min_section_tokens` | `--max-section-tokens`, `--min-section-tokens` |
| `normalization.max_segment_gap`, `.ellipsis_gap`, `.max_segment_duration`, `.max_segment_tokens` | `--normalize-max-segment-gap`, `--normalize-ellipsis-gap`, `--normalize-max-segment-duration`, `--normalize-max-segment-tokens` |
| `thresholds.glossary`, `.homophones`, `.spoken_word`, `.grammar` | `--glossary-confidence-threshold`, `--homophones-confidence-threshold`, `--spoken-word-confidence-threshold`, `--grammar-confidence-threshold` |
| `context.description` | `--transcript-description` |
| `diagnostics.work_dir`, `.retention` | `--work-dir`, `--work-dir-retention` |

Normalization gaps and durations are **numeric seconds**, so replace `4s`,
`3.5s`, and `60s` with `4.0`, `3.5`, and `60.0`. The operation timeout remains a
Go duration string. `chunking.target_sections` may be omitted or null for
automatic chunking; zero is invalid. Null is not a general synonym for omission:
nonoptional scalar settings reject it. Empty `context.description` clears
context. Retention behavior is unchanged.

Remove old implicit variables `AUDITA_MODULES`, `AUDITA_MODEL`,
`AUDITA_VALIDATION_MODEL`, `AUDITA_BASE_URL`, `AUDITA_VALIDATION_BASE_URL`,
`AUDITA_LLM_TIMEOUT_SECONDS`, `AUDITA_VALIDATION_LLM_TIMEOUT_SECONDS`,
`AUDITA_MAX_RETRIES`, `AUDITA_VALIDATION_MAX_RETRIES`,
`AUDITA_TOTAL_LLM_CONCURRENCY`, `AUDITA_LLM_CONCURRENCY`,
`AUDITA_PROPOSAL_LLM_CONCURRENCY`, `AUDITA_VALIDATION_LLM_CONCURRENCY`,
`AUDITA_VALIDATION_MAX_PROMPT_TOKENS`, `AUDITA_TARGET_SECTIONS`,
`AUDITA_MAX_SECTION_TOKENS`, `AUDITA_MIN_SECTION_TOKENS`,
`AUDITA_NORMALIZE_MAX_SEGMENT_GAP`, `AUDITA_NORMALIZE_ELLIPSIS_GAP`,
`AUDITA_NORMALIZE_MAX_SEGMENT_DURATION`, `AUDITA_NORMALIZE_MAX_SEGMENT_TOKENS`,
`AUDITA_GLOSSARY_CONFIDENCE_THRESHOLD`,
`AUDITA_HOMOPHONES_CONFIDENCE_THRESHOLD`,
`AUDITA_SPOKEN_WORD_CONFIDENCE_THRESHOLD`,
`AUDITA_GRAMMAR_CONFIDENCE_THRESHOLD`, `AUDITA_WORK_DIR`, and
`AUDITA_WORK_DIR_RETENTION`. Put those values in the named fields above or pass
their surviving explicit flags.

## Inspecting and operating

Run `audita config validate --config <file>` before processing. Use
`audita config print-effective --config <file> --view settings|profiles|explain`
to inspect redacted ConfigKit YAML, selected PromptKit profile controls, or
field origins and derivations. Each view resolves both roles offline without
calling a provider. `--overlay testing` selects the same overlay for validation,
inspection, and processing. The old effective-config JSON format is replaced by
YAML; settings YAML alone does not show profile-owned model controls.

The [process report](../integrations/output-files.md#process-report) now uses
schema `v2` and includes an `llm_summary` when execution observations are
available. Logical calls are distinct from provider attempts; usage fields carry
known and complete flags. Utilization is grouped by backend capacity rather than
old scheduler and active-concurrency fields. Retained runs write
`effective-config.redacted.yaml`, `selected-profiles.yaml`,
`config-origins.yaml`, `utilization-diagnostics.json`, and
`llm-execution.json`. Request and response artifacts remain redacted debugging
material. See [operations](../operations.md#diagnostics-directory) for retention
and paths, [configuration](../config.md) for all settings, and the
[CLI reference](../cli.md) for current flags.