Document the Narratio v3 upgrade

README.md

@@ -131,9 +131,7 @@ falsey values are preserved. `narratio_publish_outputs`,
 `narratio_notarius_references`, `narratio_notarius_outputs`,
 `narratio_scriptorium_artifacts`, and `narratio_scriptorium_artifact_families`
 are complete native caller values, so callers may compose them before assigning
-them and the role does not merge or rewrite them. Credential lists contain
-environment-variable names only; credential values remain outside this role
-and are the caller's responsibility. The optional
+them and the role does not merge or rewrite them. The optional
 `narratio_notarius_config_overlay` selects a Notarius ConfigKit overlay without
 coupling it to Narratio's own overlay name. The optional `narratio_notarius_resume`
 and `narratio_notarius_chunk_cache` settings expose Narratio's native extraction
@@ -142,12 +140,65 @@ cache policy.
 ConfigKit imports and selected overlays are externally managed, and this role
 does not install the downstream applications, campaign content, or suite policy.
 
-Narratio v3 removes the old Audita tuning, report, retention, and singular-key
-role variables. It also replaces `narratio_notarius_llm_api_key` with
-`narratio_notarius_credentials` and renames
-`narratio_notarius_config_profile` to `narratio_notarius_config_overlay`.
-Existing deployments that cannot migrate these inputs should retain their
-previous Narratio role pin.
+## Upgrading from Narratio v2
+
+Narratio v3 removes these role variables and their native fields:
+`narratio_audita_llm_api_key`, `narratio_audita_base_url`,
+`narratio_audita_model`, `narratio_audita_total_llm_concurrency`,
+`narratio_audita_proposal_llm_concurrency`,
+`narratio_audita_validation_model`,
+`narratio_audita_validation_llm_concurrency`,
+`narratio_audita_work_dir_retention`, and `narratio_audita_report`.
+Replace `narratio_notarius_llm_api_key` with the list-valued
+`narratio_notarius_credentials`; rename `narratio_notarius_config_profile` to
+`narratio_notarius_config_overlay`. Existing deployments that cannot migrate
+these inputs should retain their previous role pin. See the tagged
+[v3.0.0 release notes](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.0.0/docs/releases/v3.0.0.md).
+
+`narratio_audita_credentials` and `narratio_notarius_credentials` are lists of
+environment-variable or secret-reference **names**, never credential values.
+Callers supply nonempty values through Narratio's run environment or supported
+secret source. Narratio resolves configured names when loading a pipeline,
+including when the downstream stage will be skipped. Audita v2 needs names for
+every credential in its configured backends, even backends not selected by the
+current profiles; Notarius names must match its selected provider profiles.
+The role does not inspect downstream files or resolve secrets. Null omits a
+list or selector, `[]` emits an explicit empty list, and `""` emits an explicit
+empty selector. A Narratio overlay replaces a credential list rather than
+appending to it.
+
+Audita v2 owns its configuration, backend/model definitions, PromptKit profiles,
+reporting, and debug policy. Configure it independently before using polish;
+the role does not generate downstream files or guess replacements for the
+removed tuning fields. The Audita overlay, proposal profile, and validation
+profile selectors are independent of each other and Narratio's selected
+overlay. The Notarius `config_overlay` selector is likewise independent; null
+adds no downstream selection, while empty, `default`, and named strings are
+passed to Notarius unchanged. Selected downstream features require compatible
+Audita and Notarius executables; this role adds no version gate. See the tagged
+[Audita](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.0.0/docs/integrations/audita.md)
+and [Notarius](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.0.0/docs/integrations/notarius.md)
+integration contracts.
+
+For Narratio itself, replace `--profile` with `--overlay` and move selected
+`profiles/<name>.yml` files to `overlays/<name>.yml` beside the pipeline root.
+Explicit ConfigKit imports from a directory named `profiles` remain valid;
+PromptKit LLM-profile files are a separate concept. Notarius's renamed
+`config_overlay` selects its own `overlays/` files, replacing its retired
+configuration-profile selection. The D&D suite's testing file and selector
+migrate later with coordinated suite integration, not in this generic role.
+
+Before opening an affected existing session, follow the tagged
+[manifest migration procedure](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.0.0/docs/operations.md#migrating-manifest-overlay-provenance):
+back up the local manifest and change only
+`effective_config.selected_profile` to `selected_overlay` (or remove the
+retired informational member), preserving local progress and checkpoints.
+Immutable remote snapshots are not edited in place. For named Notarius
+selectors, the renamed field changes extraction resume evidence: the next
+applicable run regenerates extraction with normal dependent invalidation.
+Omitted/base selection does not gain invalidation solely from the rename.
+The role performs no manifest migration, cache cleanup, or blanket forced
+reruns.
 
 ## Example
 
@@ -167,10 +218,11 @@ pipeline through Narratio as its application account and requires immediate
 clean repeated convergence. It explicitly selects `v2.1.0` and checks native
 version output, then combines missing-binary recovery with a caller-supplied Go
 executable while dependency management is disabled. A representative pipeline
-checks null omission, falsey values, caller-composed native collections, and
-the native Notarius credential-reference, `resume`, and chunk-cache fields
-before native validation and a clean repeat. The suite restores the baseline
-deployment during cleanup.
+checks null omission, falsey values, caller-composed native collections,
+credential-name lists, downstream selectors, and the native Notarius `resume`
+and chunk-cache fields. It validates named and explicit-empty configurations
+offline and requires clean repeats. The suite restores the baseline deployment
+during cleanup.
 
 ```sh
 tests/integration