Document Audita v2 operator migration and examples

docs/troubleshooting.md

@@ -328,7 +328,7 @@ Safe fix:
 
 - set the exact nonempty environment variable or provide an equivalently named
   file through the conventional or explicit secrets directory;
-- remove or set the field to `null` when that deployment needs no credential;
+- remove, set to `null`, or set to `[]` when that deployment needs no credential;
   and
 - use `config show`, `config sources`, and `config diff` to inspect the public
   reference name and ownership without exposing its value.
@@ -339,7 +339,43 @@ invalidate a completed extraction, but the current reference must still resolve
 for the command to proceed.
 
 Relevant references: [Secrets](./config.md#secrets-handling) and
-[Notarius credential](./config.md#notarius-credential).
+[Notarius credentials](./config.md#notarius-credentials).
+
+## Audita v2 configuration or credential failure
+
+Symptom:
+
+- Narratio rejects a retired `pipeline.audita` field during loading, reports
+  `secret.unset` or `secret.empty` for a listed credential, or Audita rejects
+  its external configuration or selected profile when polish runs.
+
+Likely causes:
+
+- the Narratio pipeline still uses v1 endpoint, model, capacity, singular key,
+  report, or retention settings;
+- the named key is missing or empty, including a present but empty process
+  environment variable that takes precedence over a secrets-directory file;
+- Audita's external v2 file references a backend credential name not forwarded
+  by `pipeline.audita.credentials`, including a backend not selected by the
+  current profile; or
+- an Audita overlay or profile selector names a missing downstream definition.
+
+Safe fix:
+
+- follow the [migration table](./operations.md#migrating-audita-and-provider-credentials)
+  and use a supported Audita v2 executable and configuration;
+- provide each needed provider-named variable through the environment or
+  secrets directory, and list that same name in `pipeline.audita.credentials`;
+- validate the external file offline with
+  `audita config validate --config <file>` before switching executables; and
+- inspect Audita's effective profile selection separately from Narratio's
+  `config show`. Narratio does not infer downstream selectors.
+
+An exit-zero polish with a valid transcript succeeds even when Audita reports
+recoverable errors or no corrections. Missing reports are allowed when Audita
+reporting is disabled externally. Edits to Audita-owned files behind unchanged
+selectors require `narratio run-stage polish <session-id> --force` to replace a
+previously successful result. See the [Audita integration contract](./integrations/audita.md).
 
 ## Notarius executable missing