Document the Audita version 2 role migration

README.md

@@ -7,6 +7,9 @@ manage root-owned application state.
 
 ## Variables
 
+Every invocation requires caller-supplied `audita_backends` and
+`audita_llm_proposal_profile`. Neither has a role default.
+
 ```yaml
 audita_version: v2.0.1
 audita_repository_url: https://gitea.maximumdirect.net/eric/audita.git
@@ -22,7 +25,6 @@ audita_config_directory_mode: "0755"
 audita_config_file_mode: "0644"
 audita_config_version: 2
 audita_profiles_dir: null
-# Required caller inputs: audita_backends, audita_llm_proposal_profile
 audita_pipeline_modules: null
 audita_output_schema: null
 audita_llm_validation_profile: null
@@ -72,18 +74,42 @@ standalone defaults are `root:root`, directory mode `0755`, and file mode
 `0644`. Composing roles may override these generic configuration inputs for
 their own deployment policy.
 
-Backend credential references name environment variables; they must never
+Backend `credential` values are explicit environment-variable reference names,
-contain secret values. The repository-local integration suite validates the
+not secret values. Every surviving reference must resolve to a nonempty value
-rendered file with Audita rather than executing the CLI during production
+when Audita loads configuration, including references on unselected backends.
-convergence.
+An omitted or null credential permits unauthenticated local use. The role does
+not supply secret values, start a service, or probe profiles during convergence.
+
+## Migrating from the version-1 role
+
+This revision renders version-2 configuration only. Existing version-1 users
+can retain the previous role revision while planning a coordinated migration.
+The old fields have no compatibility aliases:
+
+| Previous role inputs | Version-2 destination |
+| --- | --- |
+| `audita_llm_{proposal,validation}_base_url` | `audita_backends.<id>.endpoint`; both selections may share one backend. |
+| `audita_llm_{proposal,validation}_api_key_env` | `audita_backends.<id>.credential`, an explicit environment-variable name. |
+| `audita_concurrency_{total_llm,proposal_llm,validation_llm}` | `audita_backends.<id>.concurrency` and optional `queue_capacity`; capacity is shared by roles using that backend. |
+| `audita_llm_{proposal,validation}_model` | Model in caller-owned PromptKit profile files, selected by `audita_llm_proposal_profile` and optional `audita_llm_validation_profile`. |
+| `audita_llm_{proposal,validation}_timeout` | Per-attempt `timeout_seconds` in profile files; `audita_llm_operation_timeout` separately bounds a logical call. |
+| `audita_llm_{proposal,validation}_max_retries` | `audita_llm_transient_retries` and `audita_llm_repair_attempts` are separate native budgets; old values do not map directly. |
+| Three `audita_normalization_*` gap/duration values | Same role variables, now numeric seconds rather than duration strings. |
+| `audita_diagnostics_retention` | Removed; use `audita_diagnostics_debug` and `audita_diagnostics_work_dir` for v2 debug behavior. Reporting uses `audita_reporting_enabled` and `audita_reporting_stdout_dir`. |
+
+Omitting `audita_llm_validation_profile` lets Audita inherit the proposal
+selection. `audita_llm_operation_timeout` is a Go duration string, while
+normalization times are numbers. See the tagged
+[v2 migration guide](https://gitea.maximumdirect.net/eric/audita/src/tag/v2.0.1/docs/migrations/v2.md)
+and [configuration reference](https://gitea.maximumdirect.net/eric/audita/src/tag/v2.0.1/docs/config.md)
+for exact validation and precedence rules.
 
 ## Example
 
+Inventory can supply the required choices for a local backend:
+
 ```yaml
-- hosts: audita_hosts
+# host_vars/audita_host.yml (caller-owned)
-  roles:
-    - role: ansible-role-audita
-      vars:
 audita_backends:
   local:
     endpoint: http://127.0.0.1:11434/v1
@@ -91,19 +117,40 @@ convergence.
 audita_llm_proposal_profile: local-proposal
 ```
 
-The caller supplies `profiles/local-proposal.yaml` beside the managed
+The caller also supplies `profiles/local-proposal.yaml` beside the managed
-configuration before invoking Audita.
+configuration, or selects another directory with `audita_profiles_dir`:
+
+```yaml
+# profiles/local-proposal.yaml (caller-owned)
+id: local-proposal
+backend: local
+model: replace-with-an-available-local-model
+timeout_seconds: 30
+```
+
+Choose a model available at the selected endpoint. These profile files must
+exist before invoking Audita, but need not exist before applying the role.
+The role neither deploys them nor selects a ConfigKit overlay.
+
+```yaml
+- hosts: audita_hosts
+  roles:
+    - role: ansible-role-audita
+```
 
 ## Validation
 
 The integration driver installs pinned collection dependencies, runs syntax
-checking and ansible-lint, validates a caller-supplied local configuration and
+checking and ansible-lint, and applies the role with local fixture backends and
-profile offline, and requires clean repeated convergence. It also tests a
+caller-owned profiles. It checks the temporary configuration with native
-caller-supplied Go executable with dependency management disabled after removing
+`config validate` and the effective settings and profiles views, then requires
-the managed binary. On a fresh host, the role may install Git through APT and
+clean repeated convergence. It also tests a caller-supplied Go executable with
-the Go Snap. The test uses a private temporary configuration and profile root;
+dependency management disabled after removing the managed binary. The fixture
-the role still manages the local source checkout and binary. Cleanup removes
+configuration and sibling `profiles/` directory live under the script's private
-only the private fixture root:
+temporary root, which cleanup removes. The role still mutates the local managed
+source checkout and binary; an existing system configuration is not replaced.
+These offline checks do not establish provider connectivity, runtime report
+behavior, or compatibility with the unchanged D&D suite:
 
 ```sh
 tests/integration