audita/docs/migrations/v3.md

Migrating to application configuration v3

Audita 3.1.x uses application configuration schema v2. For the cutover to schema v3, set version: 3 in the application file and move glossary entries into configuration. Use the configuration reference and maintained examples for the new formats.

• Replace pipeline.modules with ordered pipeline.stages records containing module and any per-entry overrides. An explicit empty list runs normalization.
• Define named glossary_collections in configuration or its companion imports; select them using glossaries and protected_terms. Rename each legacy entry's summary to description to preserve its prompt context. Remove --glossary and --modules from invocations.
• Move profiles and backends out of the application configuration and retired profiles_dir layout into PromptKit resources. Use its current list records, IDs, credential sources, and backend admission settings. Select proposal and validation profiles in application llm settings.
• Use the shared --debug flag for capture; diagnostics.work_dir remains the parent directory. Review report and output destinations before running.
• Completion counts are hidden by default. Use --verbose to see them on stderr, including when ordinary reports are disabled. --debug also shows counts unless followed by --quiet. See CLI reporting.

Inspect configuration and resources before processing, then try a controlled small transcript. Processing preflight checks every glossary correction and selected role before preparing outputs or invoking a model. See operations for lifecycle and recovery.