Use artifact source IDs for archive promotion

docs/config.md

@@ -106,11 +106,11 @@ archive:
   enabled: true
   upload_run: true
   promote_artifacts:
-    - from: transcripts/trimmed.json
-      to: transcripts/trimmed.json
+    - source: narratio.transcript.trimmed
+      dest: transcripts/trimmed.json
       required: true
-    - from: artifacts/session_recap.md
-      to: artifacts/session_recap.md
+    - source: narratio.artifact.session_recap
+      dest: artifacts/session_recap.md
       required: true
 
 whisperx:
@@ -130,7 +130,8 @@ scriptorium:
 
 Operational notes:
 
-- archive promotion is explicit and path-based via `archive.promote_artifacts`.
+- archive promotion is explicit and source-based via `archive.promote_artifacts`.
+- `source` is required; `dest` is optional and derived when omitted.
 - Narratio does not auto-promote all generated analyze artifacts.
 
 ## 7. Full pipeline reference
@@ -154,9 +155,9 @@ Operational notes:
 | `pipeline.spool.delete_audio_after_archive` | bool | No | `false` |
 | `pipeline.archive.enabled` | bool | No | `true` |
 | `pipeline.archive.upload_run` | bool | No | `true` |
-| `pipeline.archive.promote_artifacts[]` | list | No | trimmed + session_recap rules |
-| `pipeline.archive.promote_artifacts[].from` | string | Yes (per rule) | none |
-| `pipeline.archive.promote_artifacts[].to` | string | Yes (per rule) | none |
+| `pipeline.archive.promote_artifacts[]` | list | No | trimmed transcript rule |
+| `pipeline.archive.promote_artifacts[].source` | string | Yes (per rule) | none |
+| `pipeline.archive.promote_artifacts[].dest` | string | No | derived from source |
 | `pipeline.archive.promote_artifacts[].required` | bool | No | `true` |
 | `pipeline.whisperx.transcribe_url` | string | Yes | none |
 | `pipeline.whisperx.language` | string | No | `en` |
@@ -248,6 +249,24 @@ Allowed `pipeline.scriptorium.artifacts.<name>.inputs.<key>.source` values:
 - `narratio.bounds.session`
 - `narratio.artifact.<configured_artifact_key>`
 
+`pipeline.archive.promote_artifacts[].source` values:
+
+- `narratio.transcript.merged`
+- `narratio.transcript.polished`
+- `narratio.transcript.full`
+- `narratio.transcript.trimmed`
+- `narratio.bounds.session`
+- `narratio.artifact.<configured_artifact_key>`
+
+Archive promotion destination rules:
+
+- `dest` must be a clean relative path (not absolute, no traversal).
+- duplicate `dest` values are rejected.
+- if `dest` is omitted:
+  - built-in sources derive their canonical destination path;
+  - configured sources derive from `pipeline.scriptorium.artifacts.<name>.output_path`;
+  - derivation failure is a config validation error.
+
 ## 8. Full session reference
 
 | Path | Type | Required | Default |

docs/internal/stage-archive.md

@@ -7,7 +7,7 @@ Publish run records and promoted session artifacts to object storage, then atomi
 Inputs:
 - session manifest and prerequisite stage records
 - run root contents under `runs/{run_id}/`
-- promotion sources from session root (`archive.promote_artifacts`)
+- promotion rules with artifact `source` IDs and archive `dest` paths (`archive.promote_artifacts`)
 
 Outputs:
 - uploaded run files under `{session_prefix}/runs/{run_id}/...`

docs/operations.md

@@ -84,10 +84,12 @@ Publish order:
 
 `current/run_id.txt` is the remote commit marker.
 
-Archive promotion is explicit and path-based:
+Archive promotion is explicit and source-based:
 - Narratio does not auto-promote all generated analyze artifacts.
+- each rule resolves `source` through the artifact resolver/catalog model, then uploads to `dest`.
 - missing required promotion sources fail archive stage.
 - missing optional promotion sources are skipped.
+- invalid resolved artifacts fail archive stage.
 
 ## Resume, retry, and safe rerun behavior
 

docs/troubleshooting.md

@@ -280,7 +280,7 @@ narratio run-stage --config /path/to/pipeline.yml --session /path/to/session.yml
 
 Safe Fix:
 - rerun or resume upstream stages to generate required files.
-- adjust promotion rules to match files that must exist.
+- adjust promotion `source`/`dest` rules to match artifacts that must exist.
 - retry after storage issue is resolved.
 
 Links: