Document prepared Notarius references

docs/config.md

@@ -60,7 +60,10 @@ remote state with an unsafe legacy identity must be migrated before use.
 - Session files must be concrete; unresolved `{{ ... }}` placeholders fail load.
 - Pipeline defaults are applied before validation.
 - Campaign and session identities must agree.
-- Stable files (`speakers_file`, `autocorrect_file`, `glossary_file`, `players_file`, `party_file`) resolve from session overrides when provided, otherwise from campaign defaults.
+- Required stable files (`speakers_file`, `autocorrect_file`, `glossary_file`,
+  `players_file`, `party_file`) and the optional `spell_catalog_file` resolve
+  from session overrides when provided, otherwise from campaign defaults. An
+  empty or omitted session spell-catalog value inherits the campaign value.
 - Exactly one audio mode must be configured in session input:
   - local (`audio_dir` or `audio_files`), or
   - S3 (`audio_s3.prefix`).
@@ -227,6 +230,7 @@ Rules:
 | `pipeline.notarius.pipeline_id` | string | Conditional | required when enabled |
 | `pipeline.notarius.timeout` | duration | No | `3h`; must be positive |
 | `pipeline.notarius.working_directory` | string | No | directory containing resolved `config_path`; relative paths resolve from the pipeline file directory |
+| `pipeline.notarius.references` | map[string]string | No | empty; maps normalized Notarius selectors to supported prepared Narratio source IDs; maximum 256 entries |
 | `pipeline.notarius.outputs` | map | Conditional | at least one entry when enabled |
 | `pipeline.render.enabled` | bool | No | `true` |
 | `pipeline.render.format` | string | No | `markdown` (only supported value) |
@@ -241,6 +245,43 @@ Rules:
 | `pipeline.scriptorium.artifacts` | map | No | empty |
 | `pipeline.notification.mode` | string | No | `noop`; the only supported notification mode until a provider is implemented |
 
+### Notarius Reference Bindings
+
+`pipeline.notarius.references` maps a Notarius CLI selector to a prepared
+Narratio source, not to a filesystem path:
+
+```yaml
+notarius:
+  references:
+    glossary: narratio.input.glossary
+    party: narratio.input.party
+    players: narratio.input.players
+    spell_catalog: narratio.input.spell_catalog
+```
+
+Supported sources are `narratio.input.party`, `narratio.input.players`,
+`narratio.input.glossary`, and `narratio.input.spell_catalog`. Each map entry is
+required by its presence: omit a binding when the selected Notarius pipeline
+does not need it. A spell-catalog binding additionally requires an effective
+campaign or session `spell_catalog_file`.
+
+Selectors accept Notarius's `slot`, `chunk.slot`, `lane.slot`,
+`lane.extract.slot`, `lane.merge.slot`, and `lane.normalize.slot` forms.
+Narratio trims whitespace around
+selectors and their dot-separated components, rejects empty components and
+`=`, rejects duplicate normalized selectors, and limits the map to 256 entries.
+It validates only selector structure and the prepared source vocabulary;
+Notarius owns target-slot declarations and media compatibility.
+
+Before extraction, Narratio resolves every binding from the current prepared
+session manifest and passes its canonical absolute `inputs/` path to Notarius.
+Missing, unsafe, empty, or checksum-inconsistent prepared evidence fails with
+guidance to force `prepare`. Bindings are sorted by normalized selector and are
+part of extraction fingerprint and resume identity. See the
+[Notarius integration contract](./integrations/notarius.md) for the subprocess
+boundary and the [complete example](../examples/pipeline.full.annotated.yml)
+for a copyable configuration.
+
 ### Notarius Output Entries
 
 For each `pipeline.notarius.outputs.<name>`:
@@ -318,6 +359,7 @@ integration.
 | `inputs.glossary_file` | string | Yes | stable input default |
 | `inputs.players_file` | string | Yes | stable input default |
 | `inputs.party_file` | string | Yes | stable input default |
+| `inputs.spell_catalog_file` | string | No | optional spell-catalog overlay default; required when a Notarius reference selects `narratio.input.spell_catalog` |
 
 ### Session
 
@@ -333,6 +375,7 @@ integration.
 | `inputs.glossary_file` | string | No | overrides campaign stable input |
 | `inputs.players_file` | string | No | overrides campaign stable input |
 | `inputs.party_file` | string | No | overrides campaign stable input |
+| `inputs.spell_catalog_file` | string | No | overrides the optional campaign spell catalog; empty or omitted inherits the campaign value |
 | `inputs.audio_dir` | string | Conditional | local audio mode |
 | `inputs.audio_files[]` | list[string] | Conditional | local audio mode |
 | `inputs.audio_s3.prefix` | string | Conditional | S3 audio mode |

docs/integrations/notarius.md

@@ -7,12 +7,14 @@ lanes from the final trimmed Seriatim transcript. Narratio owns invocation,
 safe bundle discovery, lane selection, and its own artifact metadata. Notarius
 owns pipeline definitions, lane schemas, the receipt, and bundle formats.
 
-Canonical Notarius references:
+Canonical Notarius v0.6.0 references:
 
-- [Subprocess consumer contract](https://gitea.maximumdirect.net/eric/notarius/src/branch/main/docs/consumers/subprocess.md)
-- [D&D pipeline and lane contracts](https://gitea.maximumdirect.net/eric/notarius/src/branch/main/docs/consumers/dnd-pipeline.md)
-- [Run-result receipt](https://gitea.maximumdirect.net/eric/notarius/src/branch/main/docs/integrations/run-result.md)
-- [JSON output bundle](https://gitea.maximumdirect.net/eric/notarius/src/branch/main/docs/integrations/json-output.md)
+- [CLI reference](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/cli.md)
+- [Subprocess consumer contract](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/consumers/subprocess.md)
+- [D&D pipeline and lane contracts](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/consumers/dnd-pipeline.md)
+- [Run-result receipt](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/integrations/run-result.md)
+- [JSON output bundle](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/integrations/json-output.md)
+- [D&D spell-catalog overlay](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/integrations/dnd-spell-catalog-overlays.md)
 
 The [complete Narratio example](../../examples/pipeline.full.annotated.yml)
 records the exact current constraints for all ten D&D lanes. Treat the linked
@@ -23,12 +25,41 @@ duplicate the complete schemas.
 
 When `pipeline.notarius.enabled` is true, Narratio resolves the executable,
 configuration path, input path, output directory, and working directory to
-absolute paths and invokes:
+absolute paths. Narratio requires the Notarius v0.6.0 CLI contract when
+references are configured and invokes each binding as a separate argument
+before `--json`:
 
 ```text
-notarius run <pipeline_id> --config <config_path> --input <trimmed_json> --output-dir <staging_dir> --json
+notarius run <pipeline_id> --config <config_path> --input <trimmed_json> --output-dir <staging_dir> [--reference <selector>=<prepared_path>]... --json
 ```
 
+Reference paths are absolute canonical files prepared inside the current
+Narratio session workspace. Narratio passes only configured bindings, ordered
+lexically by normalized selector, as direct argument-vector entries without
+shell interpretation. A CLI binding takes precedence over a matching external
+path in Notarius configuration. Narratio never emits `--without-reference`.
+
+The maintained D&D boundary binds only the four campaign-owned external slots:
+
+```text
+notarius run dnd-session \
+  --config <absolute config path> \
+  --input <absolute trimmed transcript path> \
+  --output-dir <absolute staging directory> \
+  --reference glossary=<absolute prepared glossary path> \
+  --reference party=<absolute prepared party path> \
+  --reference players=<absolute prepared players path> \
+  --reference spell_catalog=<absolute prepared spell catalog path> \
+  --json
+```
+
+The spell-catalog binding is omitted when the campaign does not maintain that
+optional overlay. Registry, scene-description, combat-turn, and occurrence
+handoffs generated during the same Notarius run remain in Notarius pipeline
+composition and must not be emitted as CLI references. The linked CLI and D&D
+consumer documents own selector targeting, declared slots, media compatibility,
+and generated-handoff collision rules.
+
 Standard output is reserved for the JSON receipt. Standard error is captured
 separately as diagnostic output. Narratio applies the configured timeout and
 does not interpret stdout as a receipt unless the subprocess exits successfully.
@@ -38,8 +69,9 @@ environment apply to the subprocess.
 
 ## Accepted Result
 
-Narratio accepts the Notarius v0.5.0 receipt schema
-`notarius.run-result.v2`. The receipt
+Narratio's supported invocation baseline is Notarius v0.6.0. The accepted
+receipt remains `notarius.run-result.v2`; reference flags do not change the
+receipt or ten-lane output contract. The receipt
 must identify the configured pipeline, and its `index_file` must be exactly
 `index.json` beneath the reported bundle root. The production index must name
 the management files exactly as `manifest.json`, `rejected.json`,
@@ -78,6 +110,8 @@ only explicitly named lane sources; `--artifacts` never selects Notarius lanes.
   staged bundle is promoted to durable storage.
 - Contract and external provenance metadata are preserved on lane artifact
   records and through explicit publication.
+- Undeclared selectors, incompatible reference files, and external/generated
+  reference collisions are Notarius errors and fail extraction normally.
 
 Rejection, validation, warning, and diagnostic summaries retain bounded stable
 identity, category, origin, reason-code, status, and occurrence fields without

docs/internal/adapters.md

@@ -46,7 +46,9 @@ Adapters do not own:
 - Object store only when required by selected stages/config.
 
 Notarius is composed only when extraction is enabled; the extract stage owns
-receipt, bundle, and configured-lane policy rather than the adapter.
+prepared reference resolution, receipt, bundle, and configured-lane policy.
+The adapter validates the ordered selector/absolute-path pairs and is the sole
+owner of serializing them as repeated `--reference` arguments before `--json`.
 
 Object-store construction goes through `newCommandObjectStore`, which loads
 configured filesystem secrets before adapter initialization.

docs/internal/artifacts.md

@@ -36,6 +36,11 @@ unrecognized token into a valid source. Extraction sources are registered only
 from `pipeline.notarius.outputs`; the Notarius index has no selectable source
 ID.
 
+Prepared stable source IDs are `narratio.input.players`,
+`narratio.input.party`, `narratio.input.glossary`, and
+`narratio.input.spell_catalog`. Artifact policy owns their canonical manifest
+kind and prepared filename vocabulary.
+
 ## Runtime Catalog
 
 `ArtifactCatalog` tracks:
@@ -72,6 +77,15 @@ Configured sources (`narratio.artifact.*`):
 
 - resolve only through runtime catalog availability.
 
+Prepared stable sources (`narratio.input.*`):
+
+- resolve only from the current manifest's exact prepared-input record;
+- require the policy-owned canonical path below the session root, a confined
+  non-symlink regular file, a non-empty payload, and a matching SHA-256
+  checksum; and
+- return an immutable source/path/checksum/size identity shared by extract and
+  analyze rather than falling back to campaign/session source paths.
+
 Extraction sources (`narratio.extraction.*`):
 
 - use the shared typed bundle evidence inspection in `extraction_evidence.go`;
@@ -199,7 +213,8 @@ physical layout.
   `internal/artifacts/catalog.go`, `internal/artifacts/transcripts.go`,
   `internal/artifacts/extraction_catalog.go`,
   `internal/artifacts/extraction_evidence.go`,
-  `internal/artifacts/extraction_input.go`
+  `internal/artifacts/extraction_input.go`,
+  `internal/artifacts/prepared_input.go`
 - Current state: `internal/artifacts/current_state.go`,
   `internal/artifacts/current_state_commit.go`,
   `internal/artifacts/current_state_legacy.go`

docs/internal/stage-analyze.md

@@ -14,7 +14,7 @@ Execute selected configured Scriptorium artifacts in dependency order and materi
 Supported source families:
 - built-ins: `narratio.transcript.*`, `narratio.bounds.session`
 - prepared stable inputs: `narratio.input.players`, `narratio.input.party`,
-  `narratio.input.glossary`
+  `narratio.input.glossary`, `narratio.input.spell_catalog`
 - configured artifacts: `narratio.artifact.<key>`
 - extraction lanes: `narratio.extraction.<key>`
 - previous-session cache: `narratio.previous_session.artifact.<key>`
@@ -42,7 +42,9 @@ Supported source families:
 - validates selected artifact dependency order (cycle-safe topo ordering).
 - resolves required/optional inputs per artifact source definition.
 - omits an unavailable optional input; an unavailable required input fails.
-- resolves prepared stable input sources from `inputs/*.yml` materialized by `prepare`.
+- resolves prepared stable input sources through the shared manifest-authoritative
+  identity resolver; it does not accept incidental files or fall back to
+  campaign/session source paths.
 - resolves previous-session sources from local `previous/` cache only.
 - runs optional render-debug, then artifact execution.
 - validates non-empty output files and materializes canonical outputs.

docs/internal/stage-extract.md

@@ -17,16 +17,19 @@ procedures belong in [Operations](../operations.md).
 `internal/stage/extract.go`:
 
 1. resolves the final trimmed transcript from the shared artifact catalog;
-2. resolves and fingerprints the Notarius invocation contract;
-3. creates a run-local staging directory and invokes the injected
+2. resolves every configured prepared reference through the shared
+   manifest-authoritative identity resolver before creating run-local output;
+3. fingerprints the Notarius invocation contract, including sorted reference
+   identities;
+4. creates a run-local staging directory and invokes the injected
    `notarius.Runner`;
-4. validates the v2 successful receipt, confined index, management documents,
+5. validates the v2 successful receipt, confined index, management documents,
    configured required lane descriptors, validation summaries, and regular
    payload files;
-5. atomically promotes the complete bundle to its immutable durable location;
-6. records one non-selectable `notarius_index` output and one selectable
+6. atomically promotes the complete bundle to its immutable durable location;
+7. records one non-selectable `notarius_index` output and one selectable
    `notarius_lane` output per configured lane; and
-7. registers each lane as `narratio.extraction.<output_key>` for downstream
+8. registers each lane as `narratio.extraction.<output_key>` for downstream
    Scriptorium and publish resolution.
 
 Lane records retain checksum, contract, producer run ID, and Notarius system,
@@ -35,6 +38,9 @@ root, receipt, diagnostic paths, rejection/warning summaries, producing
 Narratio run ID, the resolved trimmed-input identity, and invocation
 fingerprint. The input identity binds the exact transcript bytes, canonical
 source ID, producer stage/output/run identity, and resolution provenance.
+Reference metadata contains only selector, source ID, canonical session-relative
+path, checksum, and size; adapter requests receive selector and absolute
+prepared path, never payload contents.
 Validation completes before
 promotion, so a rejected result cannot expose a partial durable bundle.
 
@@ -47,11 +53,16 @@ with no outputs is stable and does not repeatedly invalidate downstream stages.
 `internal/stage/extract_resume.go` permits a skip only when the existing stage
 record succeeded and still matches the current invocation fingerprint. The
 fingerprint covers the resolved executable and config paths, pipeline ID,
-timeout, working directory, sorted configured output contracts, and the current
-direct trimmed-transcript identity. The same identity is resolved again for
+timeout, working directory, sorted configured output contracts, the current
+direct trimmed-transcript identity, and sorted prepared-reference identities.
+The same reference helper and transcript identity are resolved again for
 artifact evidence, so changing the current transcript bytes or producer
 identity makes the prior extraction obsolete.
 
+A valid prepared-reference change makes extraction non-resumable. Missing,
+unsafe, or checksum-inconsistent prepared evidence is a hard validation error
+with prepare-force guidance because an immediate extract rerun cannot succeed.
+
 The validator then checks the producing run identity, canonical immutable
 bundle root, path confinement and absence of symlink components, receipt
 identity, exactly one canonical index, the exact configured source set,

docs/internal/stage-prepare.md

@@ -8,6 +8,7 @@ Materialize canonical current-session inputs before processing stages.
 
 - resolved campaign, session, and pipeline configuration
 - stable input files (`speakers`, `autocorrect`, `glossary`, `players`, `party`)
+- optional spell-catalog overlay
 - one resolved local or S3 audio source
 - enabled configured artifact input requirements for previous-session sources
 
@@ -21,6 +22,7 @@ Materialize canonical current-session inputs before processing stages.
 - `inputs/glossary.yml`
 - `inputs/players.yml`
 - `inputs/party.yml`
+- optional `inputs/spell_catalog.json`
 - `audio/*.flac`
 - optional `previous/manifest.json`
 - optional `previous/artifacts/**`
@@ -34,6 +36,9 @@ Materialize canonical current-session inputs before processing stages.
 - gives distinct local source paths with the same basename deterministic unique
   prepared filenames so neither source is overwritten.
 - materializes S3 audio through spool/cache-aware logic.
+- materializes a configured spell catalog with checksum and provenance, or
+  safely removes an obsolete canonical spell catalog and its manifest record
+  when the effective input is omitted.
 - scans enabled configured artifact inputs for `narratio.previous_session.artifact.*` requirements.
 - clears managed `previous/` state on every invocation, then, when requirements exist:
   - resolves the pointer-selected previous source through the shared resolver;

docs/operations.md

@@ -36,7 +36,12 @@ narratio session init 2026-04-04 --remote --force
 
 If `campaign.yml` sets `session_template_file`, `session init` renders it. Template variables must resolve to concrete values.
 
-Campaigns must provide stable input files for speakers, autocorrect, glossary, players, and party. Session files may override those paths for one session. The `prepare` stage materializes them under `inputs/`; configured Scriptorium artifacts can reference prepared `players`, `party`, and `glossary` files with `narratio.input.players`, `narratio.input.party`, and `narratio.input.glossary`.
+Campaigns must provide stable input files for speakers, autocorrect, glossary,
+players, and party, and may provide an optional spell-catalog overlay. Session
+files may override those paths for one session. The `prepare` stage
+materializes them under `inputs/`; configured consumers use the prepared files,
+never the original campaign or session source paths. Field definitions and
+source IDs are in [Configuration](./config.md#notarius-reference-bindings).
 
 ## Standard Session Workflow
 
@@ -135,6 +140,28 @@ The directory is immutable once promoted. Configured lanes become
 the bundle and `index.json` are retained for audit and resume validation but
 are not selectable or published implicitly.
 
+Configured Notarius references resolve only from the current manifest-backed
+prepared inputs. Their canonical locations are `inputs/party.yml`,
+`inputs/players.yml`, `inputs/glossary.yml`, and, when configured,
+`inputs/spell_catalog.json`. Inspect the effective stable-input inventory and
+prepared-file readiness with:
+
+```bash
+narratio session status 2026-04-04
+narratio session validate 2026-04-04
+```
+
+Reference metadata records selector, source ID, session-relative path,
+checksum, and byte size, but never payload contents. Changing a prepared
+reference changes extraction identity: ordinary continuation rejects the old
+result, reruns Notarius, and marks successful downstream stages stale. If the
+prepared file is missing or inconsistent with its manifest checksum, repair
+the source configuration and refresh prepared state first:
+
+```bash
+narratio run-stage prepare 2026-04-04 --force
+```
+
 Starting a replacement clears the previous extraction payload from the current
 session-stage record. If that replacement fails or self-skips, the current
 record does not fall back to the earlier outputs. The earlier run manifest and
@@ -181,11 +208,12 @@ To intentionally replace the current extraction result, run:
 narratio run-stage extract 2026-04-04 --force
 ```
 
-Narratio automatically reruns extraction when its recorded invocation contract
-or durable output validation changes. It cannot fingerprint configuration
-files, profiles, prompts, modules, or references loaded transitively by
-Notarius. Force extraction after changing any of those inputs, even when the
-top-level Narratio and Notarius config paths remain the same. A forced extract
+Narratio automatically reruns extraction when its recorded invocation contract,
+prepared Narratio reference identities, or durable output validation changes.
+It cannot fingerprint configuration files, profiles, prompts, modules, or
+other references loaded transitively by Notarius itself. Force extraction after
+changing any of those inputs, even when the top-level Narratio and Notarius
+config paths remain the same. A forced extract
 marks successful downstream stages stale. Ordinary extraction failures or
 outcome changes also stale affected downstream stages, while an identical
 repeated `notarius_disabled` self-skip does not repeatedly invalidate them.

docs/roadmap/implementation.md

@@ -22,7 +22,7 @@ different contract.
 | 4 | Add deterministic Notarius v0.6 reference arguments at the subprocess adapter boundary. | Completed |
 | 5 | Resolve references in extract and bind fingerprints, resume, and metadata to their identities. | Completed |
 | 6 | Prove assembled extraction lifecycle and downstream invalidation behavior. | Completed |
-| 7 | Update canonical documentation and maintained examples for the completed feature. | Pending |
+| 7 | Update canonical documentation and maintained examples for the completed feature. | Completed |
 | 8 | Perform compatibility, quality, and repository-wide closure validation. | Pending |
 
 ## Governing Decisions

docs/troubleshooting.md

@@ -158,6 +158,66 @@ is expected audit state, not a signal to relink the old bundle manually.
 
 Relevant reference: [Operations: Extraction Workflow](./operations.md#extraction-workflow).
 
+## Prepared Notarius reference missing or inconsistent
+
+Symptom:
+
+- extraction or resume validation reports that a configured reference source is
+  unavailable, unsafe, empty, or checksum-inconsistent and recommends
+  `prepare --force`.
+
+Likely causes:
+
+- `prepare` has not run since the campaign/session stable input changed;
+- the configured source file is missing;
+- a prepared `inputs/` file or its manifest record was modified independently;
+- a spell-catalog binding exists without an effective `spell_catalog_file`.
+
+Diagnostics:
+
+```bash
+narratio session status 2026-04-04
+narratio session validate 2026-04-04
+```
+
+Safe fix:
+
+- correct the campaign/session input path, then refresh canonical prepared
+  evidence before extraction:
+
+```bash
+narratio run-stage prepare 2026-04-04 --force
+```
+
+Do not point Notarius directly at the original source path or edit the manifest
+checksum. Relevant references: [Notarius reference configuration](./config.md#notarius-reference-bindings)
+and [Operations: Extraction Workflow](./operations.md#extraction-workflow).
+
+## Notarius reference selector or generated-handoff collision
+
+Symptom:
+
+- Notarius exits nonzero with an undeclared reference-slot, incompatible media,
+  or external/generated reference collision error.
+
+Likely causes:
+
+- a selector does not identify a slot declared by the selected Notarius target;
+- a prepared file does not satisfy that slot's Notarius media contract; or
+- a CLI binding attempts to replace a same-run generated D&D handoff.
+
+Safe fix:
+
+- compare external bindings with the selected Notarius pipeline's canonical
+  consumer documentation;
+- keep only campaign-owned external slots on the CLI; and
+- leave registry, scene, combat, and occurrence handoffs to Notarius pipeline
+  composition.
+
+Narratio validates selector structure and prepared evidence, while Notarius
+owns slot declarations, media compatibility, and generated-handoff conflicts.
+Relevant reference: [Notarius integration](./integrations/notarius.md).
+
 ## Atomic Notarius promotion unsupported
 
 Symptom:
@@ -230,6 +290,8 @@ Likely causes:
 
 - the executable/config path, pipeline ID, timeout, working directory, or
   configured output contracts changed;
+- a configured prepared reference selector, source, path, checksum, or byte
+  size changed;
 - the durable bundle, index, lane set, provenance, regular-file status, or
   checksum no longer validates.
 
@@ -252,8 +314,9 @@ Safe fix:
 narratio run-stage extract 2026-04-04 --force
 ```
 
-Narratio fingerprints its invocation contract, not the contents of transitive
-Notarius inputs. Always force extraction after changing them; downstream
+Narratio fingerprints its invocation contract and prepared Narratio reference
+identities, not the contents of other transitive Notarius inputs. Always force
+extraction after changing those external inputs; downstream
 successful stages are then marked stale normally.
 
 Relevant reference: [Operations: Extraction Workflow](./operations.md#extraction-workflow).