Document pipeline configuration migration workflow

README.md

@@ -27,7 +27,7 @@ This requires resolvable `pipeline.yml`, `campaign.yml`, and concrete
 - [Integration contracts](docs/integrations/) — external tools, formats, and
   compatibility expectations.
 - [Maintained examples](examples/README.md) — complete copyable configuration
-  and input files.
+  and input files, including the production/testing split bundle.
 
 ## Maintainer Documentation
 

docs/config.md

@@ -74,6 +74,18 @@ family members and generated publish rules participate after expansion; moving
 an equal value between eligible root/import sources does not create a
 difference.
 
+### Migrating to the maintained bundle
+
+Use the [production/testing bundle](../examples/production-testing/pipeline.yml)
+as the complete copyable migration reference. Split stable pipeline settings
+into explicit additive imports, place production/testing differences in one
+selected overlay, and retain a production `default_profile`. Convert campaign
+rosters to [canonical party input](integrations/party.md), remove a separate
+`players_file`, then express character work as families. Inspect the result
+with `config validate`, `config show`, and `config sources`; use `config diff`
+to review profiles before running a session. Unversioned parties and their
+`players_file` remain a clearly bounded legacy compatibility path.
+
 ### Identity segments
 
 Campaign IDs (`campaign_id` and `default_campaign_id`), session IDs, previous

docs/internal/overview.md

@@ -28,7 +28,7 @@ progress and artifact services resolve durable inputs and outputs.
 | --- | --- | --- |
 | Executable | `cmd/narratio` | Process entry, standard stream wiring, argument handoff, and exit status. |
 | Application orchestration | `internal/app` | Command dispatch, configuration selection, secret-file environment loading, production composition, session locking, planning, execution, restore, cleanup gates, and user-facing reporting. |
-| Configuration | [`internal/config`](configuration.md) | Presence-aware pipeline composition, strict YAML loading, discovery, defaults, normalization, session templating, and validation. |
+| Configuration | [`internal/config`](configuration.md) | Presence-aware root/import/profile composition, canonical party and family expansion, strict YAML loading, defaults, normalization, session templating, and validation. |
 | Pipeline stages | `internal/stage` | Canonical stage registry, shared stage contract, execution dependencies, and implemented stage behavior. |
 | External boundaries | `internal/adapters`, `internal/audio` | WhisperX HTTP, downstream subprocesses, notification, object storage, and S3 audio materialization behind Narratio contracts. |
 | Manifests | `internal/manifest` | Durable session progress, invocation audit state, stage transitions, validation, and atomic persistence. |

docs/policy/architecture.md

@@ -145,6 +145,14 @@ Configuration is strict, explicit, centralized, and operator-oriented.
 - Empty configured values do not silently replace meaningful defaults.
 - Validation rejects invalid composition before stage execution where
   practical.
+- Root-owned imports and one selected profile resolve deterministically through
+  the configuration owner; commands do not implement their own merge rules.
+- Canonical party rosters are campaign-owned. Their derived players projection
+  and concrete character-family artifacts are resolved before runtime stages
+  or adapters receive configuration.
+- Resume uses stage- or artifact-owned semantic evidence for observable
+  result-affecting configuration; profile identity and an effective digest are
+  provenance, never blanket cache keys.
 - Session templating remains narrow and deterministic rather than becoming a
   general configuration language.
 - Secret values are supplied indirectly and are not persisted in ordinary

docs/roadmap/implementation.md

@@ -1138,7 +1138,7 @@ example data to the new party source of truth.
 
 ## Stage 21 — Canonical Documentation And Migration Convergence
 
-**Status: Pending**
+**Status: Completed**
 
 ### Goal
 

docs/troubleshooting.md

@@ -95,6 +95,10 @@ Safe fix:
 - correct the selected profile or its overlay; or
 - correct the campaign party/family declaration that owns generated values.
 
+To review what would actually change before switching profiles, run `config
+diff` with the same pipeline and campaign selectors. It compares normalized
+effective values rather than YAML formatting or source-file layout.
+
 Relevant reference: [Configuration inspection](./config.md#read-only-effective-pipeline-inspection).
 
 ## Audio mode conflict