From 4c203d8588c3d51959ce80021400f8009c34026b Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 30 Aug 2026 15:19:30 +0000 Subject: [PATCH] Document pipeline configuration migration workflow --- README.md | 2 +- docs/config.md | 12 ++++++++++++ docs/internal/overview.md | 2 +- docs/policy/architecture.md | 8 ++++++++ docs/roadmap/implementation.md | 2 +- docs/troubleshooting.md | 4 ++++ 6 files changed, 27 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 6f42cda..19da963 100644 --- a/README.md +++ b/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 diff --git a/docs/config.md b/docs/config.md index 14cf1bb..e0d20eb 100644 --- a/docs/config.md +++ b/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 diff --git a/docs/internal/overview.md b/docs/internal/overview.md index ea67212..b9871d0 100644 --- a/docs/internal/overview.md +++ b/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. | diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index dd94de6..99964b7 100644 --- a/docs/policy/architecture.md +++ b/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 diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index cd1cef4..d21db9c 100644 --- a/docs/roadmap/implementation.md +++ b/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 diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 247bd92..2e55d84 100644 --- a/docs/troubleshooting.md +++ b/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