Update ConfigKit and prepare Narratio v2.1.2

.woodpecker/release.yml

@@ -2,39 +2,26 @@ when:
   - event: tag
 
 steps:
-  - name: build-release-assets
-    image: golang:1.25
+  validate-release:
+    image: golang:1.26.7
+    commands:
+      - ./scripts/check-release-candidate.sh "$CI_COMMIT_TAG"
+
+  build-release-assets:
+    image: golang:1.26.7
+    depends_on:
+      - validate-release
     commands:
       - |
         set -eu
+        case "$PWD" in
+          /*) ;;
+          *) echo "release workspace must have an absolute path" >&2; exit 1 ;;
+        esac
+        ./scripts/build-release-assets.sh "$CI_COMMIT_TAG" "$PWD/dist"
 
-        version="$CI_COMMIT_TAG"
-        dist="dist"
-        pkg="gitea.maximumdirect.net/eric/narratio/cmd/narratio"
-
-        rm -rf "$dist"
-        mkdir -p "$dist"
-
-        build_binary() {
-          goos="$1"
-          goarch="$2"
-          suffix="$3"
-          output="$dist/narratio-$version-$goos-$goarch$suffix"
-
-          CGO_ENABLED=0 GOOS="$goos" GOARCH="$goarch" \
-            go build -trimpath -ldflags "-s -w -X gitea.maximumdirect.net/eric/narratio/internal/buildinfo.Version=$version" \
-            -o "$output" "$pkg"
-        }
-
-        build_binary linux amd64 ""
-        build_binary linux arm64 ""
-        build_binary darwin amd64 ""
-        build_binary darwin arm64 ""
-        build_binary windows amd64 ".exe"
-        build_binary windows arm64 ".exe"
-
-  - name: publish-release
-    image: woodpeckerci/plugin-release
+  publish-release:
+    image: woodpeckerci/plugin-release:0.3.1
     depends_on:
       - build-release-assets
     settings:
@@ -42,6 +29,8 @@ steps:
         from_secret: GITEA_RELEASE_TOKEN
       files:
         - dist/narratio-*
+      title: Narratio ${CI_COMMIT_TAG}
+      note: docs/releases/${CI_COMMIT_TAG}.md
       checksum: sha256
       checksum-file: SHA256SUMS
       checksum-flatten: true

.woodpecker/shuffle.yml

@@ -0,0 +1,8 @@
+when:
+  - event: cron
+
+steps:
+  shuffled-race-tests:
+    image: golang:1.26
+    commands:
+      - go test -race -shuffle=on -count=3 ./...

.woodpecker/verify.yml

@@ -0,0 +1,47 @@
+when:
+  - event: [push, pull_request]
+
+steps:
+  tests:
+    image: golang:1.26
+    commands:
+      - go test ./...
+
+  race-tests:
+    image: golang:1.26
+    depends_on: tests
+    commands:
+      - go test -race ./...
+
+  static-analysis:
+    image: golang:1.26
+    depends_on: tests
+    commands:
+      - go vet ./...
+
+  build:
+    image: golang:1.26
+    depends_on: tests
+    commands:
+      - go build ./...
+
+  documentation-and-examples:
+    image: golang:1.26
+    depends_on: tests
+    commands:
+      - go test ./internal/doccheck
+      - go test ./internal/config -run '^TestExamplesLoadAndValidate$'
+
+  cross-build:
+    image: golang:1.26
+    depends_on: [race-tests, static-analysis, build, documentation-and-examples]
+    commands:
+      - |
+        set -eu
+        output_dir="$(mktemp -d)"
+        trap 'rm -rf "$output_dir"' EXIT
+        for target in linux/amd64 linux/arm64 darwin/arm64; do
+          goos="${target%/*}"
+          goarch="${target#*/}"
+          CGO_ENABLED=0 GOOS="$goos" GOARCH="$goarch" go build -o "$output_dir/narratio-$goos-$goarch" ./cmd/narratio
+        done

README.md

@@ -1,22 +1,42 @@
 # narratio
 
-Narratio is a Go orchestration application that turns D&D session audio into polished transcripts and generated session artifacts.
+Narratio is a stage-driven Go orchestrator for turning D&D session audio into
+polished transcripts, validated Notarius extraction lanes, and generated
+artifacts.
 
-It coordinates transcription, merge/polish/normalize/trim processing, artifact generation, archive publishing, and resumable run state in one operator workflow.
+It runs a deterministic workflow with manifest-driven continuation, remote
+publish, and restore support.
 
-```bash
-narratio run --session-id 2026-04-04
+```sh
+narratio run 2026-04-04
 ```
 
-This command requires discoverable `pipeline.yml` and `session.yml` files (or explicit `--config` and `--session` flags).
+This requires resolvable `pipeline.yml`, `campaign.yml`, and concrete
+`session.yml` files or their explicit command-line alternatives.
 
 ## Documentation
 
-- [Configuration](docs/config.md)
-- [CLI Reference](docs/cli.md)
-- [Operations and Recovery](docs/operations.md)
-- [Troubleshooting](docs/troubleshooting.md)
-- [Development Guide](docs/development.md)
-- [Architecture Principles](docs/architecture.md)
-- [Internal Component Contracts](docs/internal/README.md)
-- [Config Examples](examples/)
+- [CLI reference](docs/cli.md) — commands, arguments, flags, and invocation
+  behavior.
+- [Configuration](docs/config.md) — discovery, fields, defaults, and
+  validation.
+- [Operations](docs/operations.md) — runtime workflow, state, publishing,
+  recovery, and cleanup.
+- [Troubleshooting](docs/troubleshooting.md) — symptom-driven diagnosis and
+  safe remedies.
+- [Integration contracts](docs/integrations/) — external tools, formats, and
+  compatibility expectations.
+- [Maintained examples](examples/README.md) — complete copyable configuration
+  and input files, including the production/testing split bundle.
+
+## Maintainer Documentation
+
+- [Development guide](docs/development.md) — first-read orientation and
+  task-specific reading routes.
+- [Internal overview](docs/internal/overview.md) — implemented component map.
+- [Architecture](docs/policy/architecture.md) — normative boundaries and
+  invariants.
+- [Documentation policy](docs/policy/documentation.md) — canonical ownership
+  and maintenance rules.
+- [Testing policy](docs/policy/testing.md) — test value, boundaries, and
+  sufficiency.

docs/architecture.md

@@ -1,202 +0,0 @@
-# Narratio Architecture
-
-## Purpose
-
-`narratio` is a Go orchestration application for processing D&D session audio into polished transcripts and generated session artifacts.
-
-This document defines the development principles for the project. It is inward-facing: its audience is developers and LLM coding agents. It should guide future changes, not serve as a complete implementation reference.
-
-Implemented component details belong under `docs/internal/`.
-
-## Project Shape
-
-Narratio is a modular, stage-driven orchestrator.
-
-It coordinates specialized downstream systems rather than reimplementing their domains:
-
-- WhisperX handles transcription.
-- Seriatim handles deterministic transcript merge/normalization/trim behavior.
-- Audita handles transcript correction and polishing.
-- Scriptorium handles prompt execution and generated artifacts.
-
-Narratio owns orchestration, configuration loading, session/run state, local and remote path modeling, manifest persistence, stage sequencing, resume behavior, and archive semantics.
-
-Narratio should remain explicit and comprehensible. It is not intended to become a generic workflow engine.
-
-## Core Principles
-
-### Modular and composable
-
-Code should be organized around clear responsibilities. Stages, adapters, config loading, manifest persistence, path construction, and storage behavior should remain separable and independently testable.
-
-### Hexagonal boundaries
-
-External systems should be isolated behind narrow adapters. Stage logic should depend on Narratio-level interfaces and data structures, not on external SDK types, subprocess argument construction, or transport-specific details.
-
-### Standard library preference
-
-Prefer the Go standard library. Add dependencies only when they provide substantial value, are necessary for an external integration, or are a widely used de facto standard.
-
-Accepted examples include a YAML library for configuration and the AWS SDK for S3-compatible storage.
-
-### Explicit orchestration
-
-The pipeline should remain stage-driven and explicit. New behavior should be added through clear stage, adapter, config, or manifest contracts rather than implicit side effects or generic workflow abstraction.
-
-## Stage Design
-
-Each stage should have a clear scope of responsibility.
-
-A stage should define:
-
-- its purpose;
-- required input state;
-- produced output state;
-- config fields it consumes;
-- external adapters it uses;
-- manifest refs it reads or writes;
-- skip, force, and resume behavior;
-- failure behavior;
-- tests that protect its contract.
-
-Stages should avoid reaching across boundaries. If shared behavior is needed, prefer a helper or service with a narrow interface over duplicating ad hoc logic between stages.
-
-## Transactionality and Resume
-
-A stage should behave transactionally.
-
-A stage is complete only when its outputs have been written, validated, and recorded in the manifest. If a stage fails, Narratio should preserve enough local state for inspection, recovery, and resume.
-
-A failed or incomplete run must not be treated as successful. Later stages should depend on manifest-recorded success, not merely on incidental files existing on disk.
-
-## Manifest Model
-
-The manifest is the durable local ledger for a run.
-
-It should record:
-
-- run identity;
-- stage status;
-- input and output refs;
-- logs and generated config refs;
-- checksums or provenance where useful;
-- non-secret adapter and archive metadata.
-
-Resume behavior should be manifest-driven. Filesystem state may be inspected and validated, but it should not replace manifest stage state as the source of run progress.
-
-## Adapter Boundaries
-
-Adapters own external integration details.
-
-Expected boundaries:
-
-- WhisperX HTTP details stay in the WhisperX adapter.
-- Seriatim CLI construction stays in the Seriatim adapter.
-- Audita CLI construction stays in the Audita adapter.
-- Scriptorium CLI construction stays in the Scriptorium adapter.
-- Object-storage details stay behind the storage adapter interface.
-- AWS SDK types stay inside the S3 storage implementation.
-
-Stage code should express intent in Narratio terms and call adapters through narrow contracts.
-
-## Configuration Philosophy
-
-Configuration should be strict, explicit, and operator-friendly.
-
-Principles:
-
-- YAML decoding should reject unknown fields.
-- Defaults should be centralized and testable.
-- Empty configured values should not silently override meaningful defaults.
-- Session templating should remain narrow and deterministic.
-- Template support should serve operator convenience, not become a general configuration language.
-
-Narratio should not become a secondary configuration system for downstream tools. Seriatim, Audita, and Scriptorium should own their runtime defaults wherever practical. Narratio should pass required stage-contract paths and explicit operator overrides.
-
-## Path and Storage Discipline
-
-Local and remote paths are part of Narratio’s application contract.
-
-Code should use centralized path helpers for workspace, spool, session, run, artifact, log, config, and archive paths. Stages should avoid reconstructing canonical paths through scattered string concatenation.
-
-Storage backends should receive explicit bucket-relative keys. Storage implementations should not infer campaign, session, run, or root-prefix semantics.
-
-## Archive Invariants
-
-Archive behavior must preserve a clear commit boundary.
-
-A remote run is current only after the archive stage has successfully uploaded the run record, required promoted outputs, `current/manifest.json`, and finally `current/run_id.txt`.
-
-`current/run_id.txt` is the final remote commit marker and must be written last.
-
-Failed, incomplete, skipped, or uncommitted archive attempts must not be presented as current remote state. Local cleanup is permitted only after successful archive commit and only when explicitly configured.
-
-## Security and Privacy
-
-Narratio handles private campaign material.
-
-Rules:
-
-- Do not store raw secrets in pipeline or session YAML.
-- Use environment variable names or secret-file references for secret handling.
-- Do not write raw secret values to manifests, logs, generated configs, or archive metadata.
-- Treat transcripts, generated artifacts, prompts, reports, and logs as potentially sensitive.
-- Avoid logging transcript or prompt content unless there is a deliberate diagnostic reason.
-
-## Diagnostics
-
-Diagnostics should be durable and discoverable, but distinct from canonical outputs.
-
-Logs, reports, generated invocation/config files, and render-debug files support debugging. Transcript tiers and configured artifacts are pipeline products.
-
-Manifest refs should preserve that distinction.
-
-## Determinism
-
-Where practical, Narratio should prefer deterministic behavior:
-
-- stable local path layout;
-- stable remote key layout;
-- sorted upload order;
-- predictable generated config files;
-- repeatable command construction;
-- tests that do not depend on live external services.
-
-Run IDs and timestamps may be intentionally variable, but surrounding behavior should remain testable.
-
-## Testing Expectations
-
-Core behavior should be testable without live external services.
-
-Tests should cover:
-
-- config loading, defaults, and validation;
-- CLI parsing and command construction;
-- path helpers;
-- manifest transitions;
-- stage success, failure, skip, and resume behavior;
-- adapter command construction;
-- fake storage behavior;
-- archive commit ordering;
-- example config validity where practical.
-
-Live S3, WhisperX, LLM, or subprocess integration tests should be explicit integration tests, not required for ordinary unit test runs.
-
-## Documentation Expectations
-
-Documentation must follow `docs/documentation/policy.md`.
-
-Current behavior belongs in user-facing docs and `docs/internal/`. Future, planned, aspirational, experimental, or unimplemented work belongs only under `docs/roadmap/`.
-
-`docs/architecture.md` should remain concise and principle-focused. It should not duplicate the full config reference, CLI reference, operations guide, or internal stage documentation.
-
-## Non-Goals
-
-Narratio is not:
-
-- a generic DAG or workflow engine;
-- a replacement configuration layer for Seriatim, Audita, or Scriptorium;
-- a storage backend abstraction beyond the needs of this pipeline;
-- a place to embed raw secrets;
-- a place for stage logic to depend directly on AWS SDK types or downstream tool internals;
-- a prompt-authoring system.

docs/cli.md

@@ -1,60 +1,231 @@
-# CLI
+# CLI Reference
 
 ## Shortest Useful Command
 
 ```bash
-narratio run --session-id 2026-04-04
+narratio run 2026-04-04
 ```
 
-This command uses default config discovery for `pipeline.yml` and `session.yml`; both files must be discoverable unless you pass explicit `--config` and `--session` paths.
+This runs the canonical full pipeline for session `2026-04-04`.
 
 ## Command Overview
 
-Implemented commands:
+Top-level commands:
 
-- `run`: execute pipeline stages and persist manifest state.
-- `plan`: validate config, prepare workspace layout, and print stage run/skip decisions.
-- `resume`: continue from first non-succeeded stage unless forced.
-- `status`: read and print stage statuses from an existing manifest.
-- `run-stage`: execute exactly one stage.
+- `version`: print the Narratio build version.
+- `run <session_id>`: run all or one contiguous range of the canonical stage order.
+- `regenerate-artifacts <session_id>`: force-run extraction through analysis.
+- `run-stage <stage> <session_id>`: run one stage.
+- `analyze <session_id>`: force-run analyze.
+- `publish <session_id>`: force-run publish.
+- `clean <session_id>` or `clean --all`: remove local work/spool state.
+- `session <subcommand>`: session helper commands.
+- `config <subcommand>`: validate, display, source-trace, catalog, or compare resolved pipeline configuration.
 
-Unknown commands print usage and exit non-zero.
+Session subcommands:
 
-For config semantics, see [docs/config.md](./config.md). For operator lifecycle and recovery, see [docs/operations.md](./operations.md).
+- `session init <session_id>`
+- `session plan <session_id>`
+- `session validate <session_id>`
+- `session status <session_id>`
+- `session restore <session_id>`
+- `session artifacts <session_id>`
+- `session locks <session_id>`
+- `session locks add <session_id> <source>`
+- `session locks remove <session_id> <source>`
 
-## Complete Flag Reference
+## Common Config Flags
+
+Most session-aware commands accept:
+
+- `--config <pipeline.yml>`
+- `--campaign <id>`
+- `--campaign-file <campaign.yml>`
+- `--session <session.yml>`
+- `--session-id <session_id>`
+- `--previous-session-id <session_id>`
+- `--profile <name>`
+- `--secrets-dir <directory>`
+
+Rules:
+
+- `--campaign` and `--campaign-file` are mutually exclusive.
+- `--session` is not used by `session init`.
+- if both positional `<session_id>` and `--session-id` are provided, values must match.
+- `--previous-session-id` is a strict expectation: the selected session file
+  must contain the same `previous_session_id`.
+- `--profile` selects `profiles/<name>.yml` relative to the pipeline root. It
+  may be supplied once; omitted, empty, and the exact name `default` select the
+  base configuration, while an unknown named profile fails. The same selection
+  applies to all common-flag commands, including `regenerate-artifacts`.
+- `--secrets-dir` selects ConfigKit credential-file bootstrap explicitly. A
+  relative value uses caller CWD. Without the flag, a present `secrets/`
+  directory beside the resolved root pipeline is used; an absent one is skipped.
+- `clean --all` cannot be combined with campaign/session selectors.
+- notification delivery is currently limited to the configured `noop` mode; see
+  the [configuration reference](./config.md#notifications).
+
+## Session ID Input Rules
+
+Session-aware commands accept one of these forms:
+
+- positional session ID: `... <session_id>`
+- compatibility flag: `... --session-id <session_id>`
+
+When both are present, command parsing requires an exact match.
+
+Commands with additional positionals keep their command-specific order:
+
+- `run-stage <stage> <session_id>` or `run-stage <stage> --session-id <session_id>`
+- `session locks add <session_id> <source>` or `session locks add --session-id <session_id> <source>`
+- `session locks remove <session_id> <source>` or `session locks remove --session-id <session_id> <source>`
+
+## Command Reference
+
+### `config validate`, `config show`, `config sources`, `config artifacts`, and `config diff`
+
+```bash
+narratio config validate [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--profile <name>] [--secrets-dir <directory>]
+narratio config show [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--profile <name>] [--secrets-dir <directory>]
+narratio config sources [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--profile <name>] [--secrets-dir <directory>]
+narratio config artifacts [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--profile <name>] [--secrets-dir <directory>]
+narratio config diff <left-profile> <right-profile> [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--secrets-dir <directory>]
+```
+
+These commands resolve the selected profile, defaults, ordinary paths, and—if
+a campaign is selected—the campaign-owned party. They neither discover or load
+a session nor create a workspace, manifest, run, lock, adapter, or remote
+connection. Like every pipeline-loading command, they bootstrap the selected or
+conventional secrets directory before resolving configuration; `config show`
+never includes bootstrap reports or secret values in its YAML output.
+Typed credential references, including `notarius.llm_api_key`, must therefore
+resolve even though these inspection commands never construct an adapter.
+
+Campaign selection is optional for a pipeline without party-driven artifact
+families. A pipeline with `scriptorium.artifact_families` needs a selected or
+configured default campaign so Narratio can expand its concrete artifacts and
+publish rules. `--campaign` and `--campaign-file` remain mutually exclusive.
+Session, range, force, and artifact-execution flags are not accepted.
+
+`config validate` writes a concise root-path, selected-profile (or `none`), and
+effective-digest summary after successful complete validation. `config show`
+writes one deterministic, secret-free YAML document containing defaulted and
+expanded concrete configuration. It omits ConfigKit directives, artifact
+family declarations, and runtime provenance.
+
+`config sources` reports the same fully validated resolution without printing
+effective values. Its header identifies the root, ordered imports, selected
+profile and overlay, selected campaign, party source, and digest. The
+remaining tab-separated records are sorted as `path`, `role`, and `source`.
+Roles distinguish root, import, profile, centralized default, campaign, party,
+and generated family ownership. A generated party member has
+one family record and one party record at the same logical path. The output
+never reads or prints secret values.
+
+`config artifacts` prints the concrete catalog used by analysis, ordered by
+artifact key. Its tab-separated header is `key`, `source`, `definitions`,
+`enabled`, `output`, `dependencies`, `family`, `character`, `family_source`, and
+`party_source`. Definitions and effective dependencies are sorted comma-separated
+lists, and control characters in fields are escaped. Family-member rows identify
+their family, character, defining family file, and party file. An empty catalog
+prints only the header. Ordinary artifacts can be inspected without a campaign;
+party-driven families retain the campaign requirement. See
+[Scriptorium Artifact Entries](./config.md#scriptorium-artifact-entries) for the
+configuration layout.
+
+`config diff` resolves both supplied profile names independently and compares
+their fully resolved, secret-free effective mappings. It does
+not accept `--profile`; the two positional names must be distinct, declared
+profiles. When party-driven families are present, both profiles must resolve to
+the same selected campaign and party. Use `--campaign-file` if profile-specific
+campaign configuration would otherwise select different files.
+
+Equal profiles print `no differences`. Otherwise, sorted tab-separated records
+use one of these forms, with compact JSON values:
+
+```text
+added    <path>    <right-value>
+removed  <path>    <left-value>
+changed  <path>    <left-value>    <right-value>
+```
+
+Mappings are flattened to their logical field paths; lists remain one atomic
+value. The command compares defaulted concrete artifacts and publish rules, not
+profile names, source-file layout, or formatting. It succeeds when differences
+are found, making it suitable for review and migration checks.
+
+### `version`
+
+```bash
+narratio version
+```
+
+Official release binaries report their exact Git tag. Binaries built directly
+from source without release linker metadata report `dev`.
 
 ### `run`
 
-- `--config <path>`: optional explicit `pipeline.yml` path.
-- `--session <path>`: optional explicit `session.yml` path.
-- `--session-id <value>`: session template variable value.
-- `--force`: force stage execution.
-- `--artifacts <names>`: analyze artifact keys to execute (repeatable or comma-separated).
+```bash
+narratio run <session_id> [--from <stage>] [--through <stage>] [--force] [--artifacts <name[,name...]>] [...common config flags]
+```
 
-### `plan`
+Behavior:
 
-- `--config <path>`
-- `--session <path>`
-- `--session-id <value>`
-- `--force`
+- evaluates one inclusive contiguous range of the canonical stage order;
+- defaults an omitted `--from` to `prepare` and an omitted `--through` to
+  `cleanup`, so omitting both retains full-pipeline behavior;
+- rejects unknown endpoints and a `--from` endpoint after `--through`;
+- runs `render` before `extract`; an omitted or disabled Notarius
+  configuration records an explicit `notarius_disabled` self-skip;
+- resolves every selected typed credential during the initial configuration
+  load, including a Notarius credential when extract is disabled, outside the
+  selected range, or later skipped as resumable;
+- skips already-succeeded stages unless `--force` is set or a stage-specific
+  resume check finds its durable result obsolete;
+- applies `--force` only to stages in the selected range;
+- rejects repeated `--from`, `--through`, or `--force` options, including
+  `--name=value` spellings;
+- continues interrupted or partially completed sessions by running non-succeeded stages;
+- writes the session manifest as the sole durable progress ledger. Each
+  invocation also creates its run-local directory and returns an immediate
+  command summary; neither creates another durable progress record.
+- reports the resolved profile (or `none`) and effective configuration digest.
 
-### `resume`
+When `--artifacts` is present, the selected range must contain `analyze` or
+`publish`. Either consumer is sufficient, including a one-stage range.
 
-- `--config <path>`
-- `--session <path>`
-- `--session-id <value>`
-- `--force`
-- `--artifacts <names>`: analyze artifact keys to execute (repeatable or comma-separated).
+### `regenerate-artifacts`
+
+```bash
+narratio regenerate-artifacts <session_id> [--artifacts <name[,name...]>] [...common config flags]
+```
+
+Exactly equivalent to:
+
+```bash
+narratio run <session_id> --force --from extract --through analyze [caller options]
+```
+
+The command always reruns extraction. Analysis rebuilds the selected configured
+artifacts and any prerequisites required by those targets; without
+`--artifacts`, it uses the normal default analysis selection. Publish and notify
+never run. Common session/configuration options and repeatable artifact values
+pass through unchanged.
+
+The forced extraction rebuilds the complete configured Notarius bundle,
+disables Notarius checkpoint loading, and requests chunk-plan refresh.
+`--artifacts` narrows only the analysis work; it never selects Notarius lanes.
+
+Because the expansion owns `--force`, `--from`, and `--through`, callers cannot
+supply those options. The shared `run` parser reports them as duplicate
+singleton flags. The alias has no private execution options or behavior, and
+runtime diagnostics may identify the operation as `run`.
 
 ### `run-stage`
 
-- `--config <path>`
-- `--session <path>`
-- `--session-id <value>`
-- `--force`
-- `--artifacts <names>`: analyze artifact keys to execute (repeatable or comma-separated).
-- positional `<stage>`: required stage name.
+```bash
+narratio run-stage <stage> <session_id> [--force] [--artifacts <name[,name...]>] [...common config flags]
+```
 
 Valid stage names:
 
@@ -64,159 +235,251 @@ Valid stage names:
 - `polish`
 - `normalize`
 - `trim`
+- `render`
+- `extract`
 - `analyze`
-- `archive`
+- `publish`
 - `notify`
+- `cleanup`
 
-### `status`
+Rules:
 
-- `--manifest <path>`: required manifest path.
+- `--artifacts` is accepted only for `analyze` and `publish` stage targets.
 
-## Command Reference
-
-### `run`
-
-Purpose:
-- Execute configured stages in canonical order.
-
-Syntax:
+### `analyze`
 
 ```bash
-narratio run [--config <pipeline.yml>] [--session <session.yml>] [--session-id <id>] [--force] [--artifacts <name[,name...]>]
+narratio analyze <session_id> [--artifacts <name[,name...]>] [...common config flags]
 ```
 
-Success output:
-- `narratio run: session <session_id>; executed=<n> skipped=<n>; manifest=<path>`
-
-Common failure cases:
-- missing default config/session paths when flags omitted.
-- invalid template/rendered session mismatch.
-- unknown/invalid `--artifacts` value.
-- `--artifacts` with unknown configured artifact key.
-
-### `plan`
-
-Purpose:
-- Validate config, load secrets (if configured), prepare workdir, and print stage run/skip decisions.
-
-Syntax:
+Equivalent to:
 
 ```bash
-narratio plan [--config <pipeline.yml>] [--session <session.yml>] [--session-id <id>] [--force]
+narratio run-stage analyze <session_id> --force [...common config flags]
 ```
 
-Success output includes:
-- `narratio plan: workdir prepared at <path>`
-- one line per stage (`<stage>: run|skip`)
-- `totals: run=<n> skip=<n>`
+This selects only `analyze`: it does not invoke Notarius, replace extraction,
+or remove existing extract outputs. `--artifacts` narrows the forced analysis
+targets and their required analysis prerequisites.
 
-Common failure cases:
-- same config/session discovery and validation failures as `run`.
-- secrets directory read failures when `pipeline.secrets.env_dir` is configured.
-
-### `resume`
-
-Purpose:
-- Continue from session-manifest stage status.
-
-Syntax:
+### `publish`
 
 ```bash
-narratio resume [--config <pipeline.yml>] [--session <session.yml>] [--session-id <id>] [--force] [--artifacts <name[,name...]>]
+narratio publish <session_id> [--artifacts <name[,name...]>] [...common config flags]
 ```
 
-Success output:
-- `narratio resume: session <session_id> has no remaining stages`
-- or `narratio resume: session <session_id>; executed=<n> skipped=<n>; manifest=<path>`
-
-Common failure cases:
-- same discovery/template/validation failures as `run`.
-- manifest load errors when existing manifest is unreadable.
-- invalid or unknown artifact selections.
-
-### `status`
-
-Purpose:
-- Inspect one manifest file without executing stages.
-
-Syntax:
+Equivalent to:
 
 ```bash
-narratio status --manifest <manifest.json>
+narratio run-stage publish <session_id> --force [...common config flags]
 ```
 
-Success output includes:
-- `session_id: <id>`
-- `updated_at: <timestamp>`
-- `stages:` entries (`- <stage>: <status>`)
+This command selects only `publish`; it does not invoke cleanup. Use a normal
+full run to include configured cleanup, or `run-stage cleanup` to retry cleanup
+from valid publication evidence.
 
-Common failure cases:
-- missing `--manifest`.
-- unreadable or invalid manifest path.
-
-### `run-stage`
-
-Purpose:
-- Execute exactly one stage.
-
-Syntax:
+### `clean`
 
 ```bash
-narratio run-stage [--config <pipeline.yml>] [--session <session.yml>] [--session-id <id>] [--force] [--artifacts <name[,name...]>] <stage>
+narratio clean <session_id> [--dry-run] [--clear-cache] [...common config flags]
+narratio clean --all [--dry-run] [--clear-cache] [--config <pipeline.yml>]
 ```
 
-Success output:
-- `narratio run-stage: stage=<name> executed=<n> skipped=<n> force=<true|false>; manifest=<path>`
+Behavior:
 
-`--artifacts` behavior:
-- accepted only when `<stage>` is `analyze`.
-- names are normalized (trimmed, deduplicated, sorted).
-- unknown configured artifact keys fail.
+- session mode removes the selected session's local work and spool state;
+- `--all` removes all local session work and spool state;
+- cache remains unless `--clear-cache` is provided.
 
-Common failure cases:
-- missing stage positional arg.
-- unknown stage name.
-- using `--artifacts` with any non-`analyze` stage.
+See [Operations: Cleanup](./operations.md#cleanup) for manual and pipeline-stage
+deletion scope.
+
+### `session plan`
+
+```bash
+narratio session plan <session_id> [--from <stage>] [--through <stage>] [--force] [--artifacts <name[,name...]>] [...common config flags]
+```
+
+Uses the same inclusive bounds, endpoint validation, force scope, and artifact
+selection contract as `run`. It validates config and prints run/skip decisions
+for selected stages only without creating the local workdir or changing the
+manifest. Resume-capable selected stages are checked against durable evidence.
+The output includes the resolved profile (or `none`) and effective configuration
+digest without writing provenance or any manifest state.
+For `analyze`, the preview also lists explicit targets, prerequisite-only work,
+execution order, and reusable current artifacts with concise reasons. These
+artifact decisions come from the same reconciliation and work planner used by
+execution; the preview does not predict output identities.
+
+### `session validate`
+
+```bash
+narratio session validate <session_id> [...common config flags]
+```
+
+Read-only preflight checks for config validity, required inputs, audio mode,
+previous-session requirements, publish outputs, and independent remote locks.
+
+### `session status`
+
+```bash
+narratio session status <session_id> [...common config flags]
+```
+
+Prints local manifest state and, when storage is available, status for the
+pointer-selected remote commit and its declared published outputs. Current
+publish metadata reports `published`, `carried_locked`, `locked_unpublished`,
+`optional_missing`, and `unselected`; carried output lines include the run
+derived from their exact declared key, the key itself, and its declared
+destination. A separately displayed `dest` is the destination requested by the
+current configuration and may differ while an older declaration is locked.
+
+### `session init`
+
+```bash
+narratio session init <session_id> --output ./session.yml [options]
+narratio session init <session_id> --remote [options]
+```
+
+Required target selection:
+
+- exactly one of:
+  - `--output <path>`
+  - `--remote`
+
+Options:
+
+- `--config <pipeline.yml>`
+- `--campaign <id>` or `--campaign-file <campaign.yml>`
+- `--secrets-dir <directory>`
+- `--previous-session-id <id>`
+- `--date <YYYY-MM-DD>`
+- `--title <text>`
+- `--audio-dir <path>`
+- `--audio-s3-prefix <prefix>`
+- `--force`
+
+Rules:
+
+- `--audio-dir` and `--audio-s3-prefix` are mutually exclusive.
+- if campaign `session_template_file` is configured, `session init` renders it.
+- generated session YAML must be concrete (no unresolved `{{ ... }}` placeholders).
+
+### `session restore`
+
+```bash
+narratio session restore <session_id> [--dry-run] [--force] [--include-audio] [...common config flags]
+```
+
+Behavior:
+
+- discovers committed remote current state;
+- plans local restores;
+- writes an execution report;
+- blocks unresolved conflicts. `--force` permits replacement only of eligible
+  regular files.
+
+See [Operations: Restore Workflow](./operations.md#restore-workflow) for the
+default restore scope, report location, and conflict-handling workflow.
+
+### `session artifacts`
+
+```bash
+narratio session artifacts <session_id> [--remote] [...common config flags]
+```
+
+Lists effective built-in, configured Scriptorium, and configured extraction
+sources; reports planned, available, unavailable, and published state without
+reading payload bodies; and includes publish rules, lock state, and optional
+remote published-state availability. Remote inspection uses exact commit
+declarations and displays the five current publish outcomes when recorded.
+
+### `session locks`
+
+```bash
+narratio session locks <session_id> [...common config flags]
+narratio session locks add <session_id> <source> [--reason <text>] [--force] [...common config flags]
+narratio session locks remove <session_id> <source> [...common config flags]
+```
+
+Behavior:
+
+- list mode validates and reports independent remote locks sorted by source;
+- add creates one lock and reports an existing lock unless `--force` is used;
+- `--force` performs one generation-matched replacement and reports a
+  concurrent change for operator retry; and
+- remove is idempotent and reports when the source was not locked.
+
+See [Operations: Publish Locks](./operations.md#publish-locks) for lock storage
+and publication behavior.
+
+## `--artifacts` Selection Rules
+
+An artifact-family key selects all of its concrete character members. A
+concrete generated key selects only that member; mixed family and concrete
+selection is deduplicated and executed as concrete keys. The resulting plan
+and command output identify both the concrete key and, where applicable, its
+family and character ID.
+
+- accepted on `run`, `session plan`, `run-stage`, `analyze`, and `publish`;
+- repeatable and comma-separated values are combined, surrounding whitespace
+  is removed, and duplicate names are collapsed;
+- names must exist in `pipeline.scriptorium.artifacts`;
+- empty entries are invalid;
+- on `run-stage`, only `analyze` and `publish` accept the option.
+
+Effects:
+
+- selects explicit analyze targets; required configured prerequisites may be
+  reused or rebuilt before them;
+- filters publish rules that source `narratio.artifact.<name>`;
+- does not filter built-in transcript/bounds or explicitly configured
+  `narratio.extraction.<name>` publish sources; and
+- does not select or filter Notarius lanes.
 
 ## Common Workflows
 
-Default-discovery run:
+Run full pipeline:
 
 ```bash
-narratio run --session-id 2026-04-04
+narratio run 2026-04-04
 ```
 
-Run only selected analyze artifacts:
+Dry-run restore plan:
 
 ```bash
-narratio run --session-id 2026-04-04 --artifacts session_recap,player_handout
+narratio session restore 2026-04-04 --dry-run
 ```
 
-Resume with selected analyze artifacts:
+Generate a concrete session file from template/default structure:
 
 ```bash
-narratio resume --session-id 2026-04-04 --artifacts player_handout
+narratio session init 2026-04-04 --output ./session.yml --date 2026-04-04 --title "Session 12"
 ```
 
-Run only analyze stage with selected artifacts:
+Force publish only:
 
 ```bash
-narratio run-stage --session-id 2026-04-04 --artifacts player_handout analyze
+narratio publish 2026-04-04
 ```
 
-## Diagnostic / Recovery Commands
-
-Inspect stage status:
+Regenerate post-transcript artifacts without publishing:
 
 ```bash
-narratio status --manifest <manifest.json>
+narratio regenerate-artifacts 2026-04-04 --artifacts session_recap,player_handout
 ```
 
-Get manifest path from previous output:
-- `run`, `resume`, and `run-stage` print `manifest=<path>` on success.
+## Output And Exit Behavior
 
-## `--artifacts` and `--force`
+- Successful commands write their result or summary to standard output and
+  exit with status `0`.
+- Command failures and invalid invocations write an error to standard error and
+  exit with status `1`.
+- An unknown top-level command also prints the top-level usage summary to
+  standard error.
+- `session restore --help` prints its command-specific usage and exits with
+  status `0`.
 
-- `--artifacts` filters which configured artifacts are executable when analyze runs.
-- `--artifacts` does not imply `--force`.
-- If analyze is already `succeeded` and `--force` is not set, runner-level skip still applies.
+Output is intended for operator inspection. Narratio does not currently offer
+a machine-readable CLI output mode; durable machine-readable state is recorded
+in manifests and reports described in [Operations](./operations.md).

docs/config.md

@@ -1,171 +1,327 @@
-# Configuration
+# Configuration Reference
 
-## 1. Overview
+## Purpose
 
-Narratio loads two YAML files:
+Narratio resolves three YAML documents:
 
-- `pipeline.yml`: pipeline-level runtime configuration.
-- `session.yml`: per-session metadata and input selection.
+- `pipeline.yml`: pipeline/runtime settings
+- `campaign.yml`: campaign identity and stable input defaults
+- `session.yml`: session identity, metadata, and audio source selection
 
-These commands load and validate both files before running:
+## Discovery and Selection
 
-- `narratio run`
-- `narratio plan`
-- `narratio resume`
-- `narratio run-stage`
+### `pipeline.yml`
 
-Behavior:
+When `--config` is omitted, search order is:
 
-- strict YAML decode is enabled (`KnownFields(true)`): unknown fields fail.
-- session templates render before session YAML decode.
-- defaults are applied for optional pipeline fields.
-- validation enforces required fields, value formats, and cross-field constraints.
+1. `/usr/local/etc/narratio/pipeline.yml`
+2. `/etc/narratio/pipeline.yml`
 
-## 2. Config file discovery
+### `campaign.yml`
 
-Pipeline config lookup for `run`, `plan`, `resume`, and `run-stage`:
+Selection rules:
 
-- If `--config <path>` is provided, that path is used.
-- If omitted, Narratio searches in order:
-  1. `/usr/local/etc/narratio/pipeline.yml`
-  2. `/etc/narratio/pipeline.yml`
-- First existing file wins.
+- if `--campaign-file` is set, use that path;
+- else if `--campaign <id>` is set, use `{pipeline.campaigns.root}/{id}/campaign.yml`;
+- else use `{pipeline.campaigns.root}/{pipeline.campaigns.default_campaign_id}/campaign.yml`.
 
-## 3. Session file discovery and templating
+### `session.yml`
 
-Session config lookup for `run`, `plan`, `resume`, and `run-stage`:
+When `--session` is omitted, local search order is:
 
-- If `--session <path>` is provided, that path is used.
-- If omitted, Narratio searches in order:
-  1. `./session.yml`
-  2. `/usr/local/etc/narratio/session.yml`
-  3. `/etc/narratio/session.yml`
-- First existing file wins.
+1. `/usr/local/etc/narratio/session.yml`
+2. `/etc/narratio/session.yml`
 
-Template behavior:
+If local session discovery fails and a `session_id` is known, Narratio attempts remote session loading from:
 
-- Supported placeholders:
-  - `{{session_id}}`
-  - `{{ session_id }}`
-- `--session-id <value>` supplies the placeholder value.
-- unresolved placeholders fail load.
-- if rendered `session_id` mismatches `--session-id`, load fails.
+- `{root_prefix}/campaigns/{campaign}/sessions/{session_id}/session.yml`
 
-## 4. Minimal pipeline config
+using configured object storage.
+
+The downloaded remote session file is command-scoped: Narratio removes it after
+the command finishes and records only the remote object provenance alongside
+the durable copied session input.
+
+### Read-only effective pipeline inspection
+
+`narratio config validate`, `narratio config show`, `narratio config sources`,
+and `narratio config artifacts` use the same `--config`, `--campaign`,
+`--campaign-file`, and
+`--profile` selection rules as pipeline commands, but do not select, discover,
+or load a session. They resolve configured typed credential references as part
+of the ordinary ConfigKit load but expose only their environment-variable names;
+they do not create runtime state.
+`narratio config diff <left-profile> <right-profile>` uses the same pipeline and
+campaign selectors, resolves each named profile with an independent ConfigKit
+load, and does not accept a separate `--profile` flag.
+
+Campaign selection is optional only when the resolved pipeline has no
+`scriptorium.artifact_families`. When families are declared, Narratio selects a
+campaign through an explicit flag or `pipeline.campaigns.default_campaign_id`,
+then parses the campaign-owned party and expands concrete artifacts and any
+family publish rules before validation. `config validate` prints the resulting
+root, profile, and effective digest. `config show` emits the normalized
+effective pipeline YAML, with defaults and concrete expansion included but
+ConfigKit directives and family declarations omitted. This review projection is
+not promised to be a reloadable authoring document. `config sources` prints a stable
+source projection instead of effective values: root/import/profile/default
+ownership plus campaign/party and generated-family records. Canonical derived
+players trace to the party. `config artifacts` lists the concrete artifact map,
+effective dependencies, and defining sources. The [CLI reference](cli.md#config-validate-config-show-config-sources-config-artifacts-and-config-diff)
+owns command syntax and output conventions.
+
+`config diff` compares normalized field values rather than YAML text or source
+ownership. It emits sorted `added`, `removed`, and `changed` records, uses
+compact deterministic JSON values, treats lists atomically, and reports `no
+differences` when the complete effective configurations are equal. Concrete
+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. Keep production settings in the
+base, split them into explicit additive imports, and place testing differences
+in the fixed `profiles/testing.yml` overlay. Put ordinary artifacts and families
+in the recommended one-definition files shown by that bundle. Convert campaign
+rosters to [canonical party input](integrations/party.md), then express character
+work as families. Inspect the result with `config validate`, `config show`,
+`config sources`, and `config artifacts`; use `config diff default testing` to
+review the overlay before running a session. Unversioned party documents are
+rejected.
+
+### Identity segments
+
+Campaign IDs (`campaign_id` and `default_campaign_id`), session IDs, previous
+session IDs, and Narratio run IDs are opaque portable segments. They must use
+only ASCII letters, digits, `.`, `_`, and `-`; empty values, `.`/`..`, path
+separators, drive forms, whitespace, control characters, and non-ASCII text are
+rejected. Narratio does not trim or rewrite these values. Existing manifests or
+remote state with an unsafe legacy identity must be migrated before use.
+
+## Validation and Merge Rules
+
+- ConfigKit performs strict typed YAML decoding and accepts exactly one document;
+  unknown fields, duplicate keys, and trailing documents fail load.
+- A pipeline file may explicitly import additive YAML fragments through the
+  root-only `configkit.imports` list. Imported files contribute fields to one
+  logical pipeline document; they do not override fields supplied by the root
+  or another import.
+- An omitted profile, an empty profile option, and the exact name `default`
+  select the base configuration. Any other name selects
+  `profiles/<name>.yml` relative to the pipeline root.
+- Campaign, session, and canonical-party documents are strict single-source
+  ConfigKit schemas. They do not enable imports, profiles, or `configkit`
+  directives.
+- Configured timeout and retry-delay durations must be positive. An omitted
+  artifact timeout continues to inherit its configured Scriptorium timeout.
+- Session files must be concrete; unresolved `{{ ... }}` placeholders fail load.
+- Session and party inputs inspected before typed loading are limited to 8 MiB.
+- Pipeline defaults are applied before validation.
+- Defaults apply only to absent fields. Explicit empty strings, zero values,
+  `false`, and `null` retain ConfigKit's typed meaning and are then checked by
+  Narratio domain validation; they are not silently replaced by defaults.
+  Explicit null optional stage sections stay absent, while required sections
+  fail validation.
+- Campaign and session identities must agree.
+- Required stable files (`speakers_file`, `autocorrect_file`, `glossary_file`,
+  `party_file`) are campaign-owned; the first three may be overridden by the
+  session. The optional `spell_catalog_file` also inherits a campaign value
+  when omitted by the session.
+- `party_file` is parsed when pipeline and campaign configuration are combined.
+  It must be a versioned [canonical party](integrations/party.md), is
+  campaign-owned and derives the players input internally. `players_file` and
+  session `party_file` are unsupported configuration keys.
+- Exactly one audio mode must be configured in session input:
+  - local (`audio_dir` or `audio_files`), or
+  - S3 (`audio_s3.prefix`).
+
+### Pipeline imports and profiles
+
+Large pipeline configurations may be split into explicitly named fragments and
+may use fixed-path profile overlays:
 
 ```yaml
-whisperx:
-  transcribe_url: "https://transcription.example.com/transcribe"
+configkit:
+  imports:
+    - path: config/storage.yml
+    - path: config/integrations.yaml
+
+campaigns:
+  root: /usr/local/share/narratio/campaigns
 ```
 
-Why this is sufficient:
+The maintained [production/testing bundle](../examples/production-testing/pipeline.yml)
+is a complete copyable example of this structure, including canonical-party
+artifact families.
 
-- `whisperx.transcribe_url` is required.
-- `workspace.root` defaults to `/var/lib/narratio`.
-- optional sections (`seriatim`, `audita`, `archive`, `scriptorium`, `trim`, `normalize`, etc.) receive defaults or stay inactive.
+Imports are resolved relative to the directory containing the root pipeline
+file and are loaded in declaration order. Narratio does not scan directories or
+infer fragments. Each import must be a confined regular `.yml` or `.yaml` file:
+absolute paths, traversal, symlinks, directories, duplicate files, and an
+import of the root pipeline itself are rejected. Imported files cannot declare
+another `configkit` control section.
 
-## 5. Minimal session template
+Base merging is additive. A map may be extended by multiple files when every
+leaf is distinct, but a scalar, list, or map/list/scalar kind cannot be claimed
+more than once, even when the repeated values are identical. Conflict errors
+name the full field path and every source that claimed it. Narratio additionally
+rejects an artifact or artifact-family key declared by more than one base file,
+even when those files contribute disjoint children.
+
+Profile names are case-sensitive and use ConfigKit's safe fixed-path naming
+rules. Only the selected overlay is opened; a malformed unselected overlay does
+not affect a base or different-profile load. Maps merge recursively, overlay
+scalars replace base scalars, and overlay lists replace base lists completely.
+Explicit `false`, zero, empty strings, empty containers, and null values remain
+explicit inputs and are not refilled by defaults. Profiles cannot inherit,
+stack, import files, or declare another ConfigKit control section.
+
+During ConfigKit loading, Narratio applies fresh typed defaults, recorded
+entry-level defaults and normalization, read-only file-local validation, and
+ordinary path resolution before computing a deterministic effective
+configuration digest. The digest represents the normalized, secret-free
+runtime pipeline mapping; it excludes ConfigKit directives, source
+provenance, profile identity, and raw environment secret values. Equivalent
+effective mappings therefore have the same digest regardless of how fields are
+split among the root and imports.
+
+An imported field has the same meaning it would have in a monolithic root
+pipeline. In particular, ordinary relative pipeline paths continue to resolve
+from the root pipeline directory, not from the importing fragment's directory.
+
+## Minimal Working Configuration
+
+`pipeline.yml`
 
 ```yaml
-session_id: "{{ session_id }}"
-campaign: sample-campaign
+campaigns:
+  root: /usr/local/share/narratio/campaigns
+  default_campaign_id: sample-campaign
+whisperx:
+  transcribe_url: https://transcription.example.com/transcribe
+```
+
+`campaign.yml`
+
+```yaml
+campaign_id: sample-campaign
+inputs:
+  speakers_file: ./speakers.yml
+  autocorrect_file: ./autocorrect.yml
+  glossary_file: ./glossary.yml
+  party_file: ./party.yml
+```
+
+`session.yml` (local audio)
+
+```yaml
+session_id: 2026-05-03
 inputs:
   audio_dir: ./audio
-  speakers_file: ./examples/speakers.yml
-  autocorrect_file: ./examples/autocorrect.yml
-  glossary_file: ./examples/glossary.yml
 ```
 
-Usage:
+## Secrets Handling
 
-```bash
-narratio run --config /path/to/pipeline.yml --session ./session.yml --session-id 2026-05-03
-```
+- Do not place raw secrets in YAML.
+- Credential fields contain environment-variable names, represented internally
+  as ConfigKit typed secret references (for example
+  `pipeline.notarius.llm_api_key: NOTARIUS_LLM_API_KEY`). A configured reference
+  must resolve to a nonempty environment value during load.
+- Every surviving reference is resolved during ordinary pipeline loading,
+  regardless of whether its integration is disabled, outside the selected
+  stage range, or eligible for resume. Omit the field or set it to `null` when
+  that deployment should not require the credential.
+- Every command that loads a pipeline accepts `--secrets-dir <path>`. When the
+  flag is omitted, Narratio uses a present `secrets/` directory beside the
+  resolved root `pipeline.yml`; an absent conventional directory is ignored.
+  Explicit relative paths are resolved from the caller's working directory,
+  and a missing or empty explicit selection is an error.
+- Each immediate regular file whose name is a valid environment-variable name
+  supplies one value. ConfigKit removes trailing CR/LF, permits a symlink as the
+  selected directory, rejects non-hidden symlink entries, and limits input to
+  1 MiB per file, 8 MiB total, and 1024 entries. Dot-prefixed entries (including
+  files, directories, and symlinks) are ignored and omitted from bootstrap
+  reports, but still count toward the directory entry limit.
+- An existing process environment value takes precedence over a credential file.
+- On POSIX, operators must provision the directory with no group/other access
+  (normally `0700`) and files with no group/other access (normally `0600`);
+  ConfigKit validates type and bounds but does not enforce permission modes.
+- Bootstrap happens once per command, before any configuration load or adapter
+  construction. Safe reports contain filenames, paths, and statuses, never values.
 
-## 6. Production-oriented config
+## Publish Configuration Summary
+
+Publish rules live under `pipeline.publish`.
 
 ```yaml
-workspace:
-  root: /var/lib/narratio/workspace
-  cleanup_after_archive: true
-
-storage:
-  backend: s3
-  s3:
-    bucket: my-dnd-archive
-    root_prefix: dnd
-    region: us-east-1
-    access_key_id_env: OBJECT_STORAGE_KEY_ID
-    secret_access_key_env: OBJECT_STORAGE_KEY
-
-spool:
-  root: /var/spool/narratio
-  delete_audio_after_archive: true
-
-archive:
+publish:
   enabled: true
   upload_run: true
-  promote_artifacts:
-    - from: transcripts/trimmed.json
-      to: transcripts/trimmed.json
+  outputs:
+    - source: narratio.transcript.final_trimmed
+      dest: transcripts/final.trimmed.json
       required: true
-    - from: artifacts/session_recap.md
-      to: artifacts/session_recap.md
+    - source: narratio.transcript.final_markdown
+      dest: transcripts/final.md
+      required: true
+    - source: narratio.transcript.final_trimmed_markdown
+      dest: transcripts/final.trimmed.md
+      required: true
+    - source: narratio.artifact.session_recap
+      dest: artifacts/session_recap.md
       required: true
-
-whisperx:
-  transcribe_url: "https://transcription.example.com/transcribe"
-
-scriptorium:
-  artifacts:
-    session_recap:
-      enabled: true
-      prompt_id: dnd.session_recap
-      output_path: artifacts/session_recap.md
-      inputs:
-        transcript:
-          source: narratio.transcript.trimmed
-          required: true
 ```
 
-Operational notes:
+Rules:
 
-- archive promotion is explicit and path-based via `archive.promote_artifacts`.
-- Narratio does not auto-promote all generated analyze artifacts.
+- `outputs[].source` is required.
+- `outputs[].dest` may be omitted when derivable from source.
+- extraction sources require an explicit `outputs[].dest` and publish only when
+  a rule names that source; the Notarius index and complete bundle are not
+  publish sources.
+- `outputs[].required` defaults to `true`.
+- publish locks are independent remote session objects managed with
+  `narratio session locks`; they are not pipeline configuration fields.
 
-## 7. Full pipeline reference
+## Full Schema
 
-| Path | Type | Required | Default |
+### Pipeline
+
+| Field | Type | Required | Default / Rule |
 | --- | --- | --- | --- |
+| `configkit.imports[].path` | string | No | explicit additive pipeline fragment relative to the root pipeline directory; `.yml` or `.yaml` regular files only |
 | `pipeline.workspace.root` | string | No | `/var/lib/narratio` |
-| `pipeline.workspace.cleanup_after_archive` | bool | No | `false` |
-| `pipeline.secrets.env_dir` | string | Conditional | none |
-| `pipeline.storage.backend` | string | No | empty |
-| `pipeline.storage.bucket` | string | No | empty |
-| `pipeline.storage.prefix` | string | No | empty |
-| `pipeline.storage.s3.bucket` | string | Conditional | empty |
+| `pipeline.workspace.cleanup_after_publish` | bool | No | `false`; selects the published run's workspace target for final cleanup and requires effective `pipeline.publish.enabled=true` and `pipeline.publish.upload_run=true` |
+| `pipeline.campaigns.root` | string | No | `/usr/local/share/narratio/campaigns` |
+| `pipeline.campaigns.default_campaign_id` | string | No | empty |
+| `pipeline.storage.backend` | string | No | `local`; supported values are `local` and `s3` (case-insensitive) |
+| `pipeline.storage.s3.bucket` | string | Conditional | required when backend is `s3` and S3 session-audio or publish upload is enabled |
 | `pipeline.storage.s3.root_prefix` | string | No | `dnd` |
 | `pipeline.storage.s3.region` | string | No | empty |
 | `pipeline.storage.s3.endpoint` | string | No | empty |
 | `pipeline.storage.s3.force_path_style` | bool | No | `false` |
-| `pipeline.storage.s3.access_key_id_env` | string | No | `OBJECT_STORAGE_KEY_ID` |
-| `pipeline.storage.s3.secret_access_key_env` | string | No | `OBJECT_STORAGE_KEY` |
+| `pipeline.storage.s3.access_key_id` | secret reference | Conditional | unset; must be paired with `secret_access_key` |
+| `pipeline.storage.s3.secret_access_key` | secret reference | Conditional | unset; must be paired with `access_key_id` |
 | `pipeline.spool.root` | string | No | `/var/spool/narratio` |
-| `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[].required` | bool | No | `true` |
-| `pipeline.whisperx.transcribe_url` | string | Yes | none |
+| `pipeline.spool.delete_audio_after_publish` | bool | No | `false`; selects the published run's spool-audio target for final cleanup and requires effective `pipeline.publish.enabled=true` and `pipeline.publish.upload_run=true` |
+| `pipeline.cache.root` | string | No | `/var/cache/narratio` |
+| `pipeline.cache.s3_audio` | bool | No | `true` |
+| `pipeline.publish.enabled` | bool | No | `true` |
+| `pipeline.publish.upload_run` | bool | No | `true` |
+| `pipeline.publish.outputs[]` | list | No | defaults to final trimmed JSON plus final and final-trimmed Markdown outputs |
+| `pipeline.publish.outputs[].source` | string | Yes (per rule) | must reference built-in or configured artifact source |
+| `pipeline.publish.outputs[].dest` | string | Conditional | derived if omitted and source supports derivation |
+| `pipeline.publish.outputs[].required` | bool | No | `true` |
+| `pipeline.whisperx.transcribe_url` | string | Yes | absolute `http` or `https` URL |
 | `pipeline.whisperx.language` | string | No | `en` |
-| `pipeline.whisperx.timeout` | duration string | No | `30m` |
+| `pipeline.whisperx.timeout` | duration | No | `30m` |
 | `pipeline.whisperx.retries` | int | No | `3` |
-| `pipeline.whisperx.retry_delay` | duration string | No | `2s` |
+| `pipeline.whisperx.retry_delay` | duration | No | `2s` |
 | `pipeline.whisperx.concurrency` | int | No | `2` |
 | `pipeline.seriatim.binary` | string | No | `seriatim` |
-| `pipeline.seriatim.timeout` | duration string | No | `10m` |
+| `pipeline.seriatim.timeout` | duration | No | `10m` |
 | `pipeline.seriatim.output_schema` | string | No | `seriatim-intermediate` |
 | `pipeline.seriatim.coalesce_gap` | float | No | `3.0` |
 | `pipeline.seriatim.report` | bool | No | `true` |
@@ -174,8 +330,8 @@ Operational notes:
 | `pipeline.seriatim.env.backchannel_max_duration` | float | No | unset |
 | `pipeline.seriatim.env.filler_max_duration` | float | No | unset |
 | `pipeline.audita.binary` | string | No | `audita` |
-| `pipeline.audita.timeout` | duration string | No | `3h` |
-| `pipeline.audita.llm_api_key_env` | string | No | empty |
+| `pipeline.audita.timeout` | duration | No | `3h` |
+| `pipeline.audita.llm_api_key` | secret reference | No | unset |
 | `pipeline.audita.modules[]` | list[string] | No | empty |
 | `pipeline.audita.base_url` | string | No | empty |
 | `pipeline.audita.model` | string | No | empty |
@@ -188,117 +344,287 @@ Operational notes:
 | `pipeline.audita.output_schema` | string | No | empty |
 | `pipeline.audita.work_dir_retention` | string | No | empty |
 | `pipeline.audita.report` | bool | No | `true` |
-| `pipeline.normalize.output_path` | string | No | `transcripts/normalized.json` |
+| `pipeline.normalize.output_path` | string | No | `transcripts/final.json` |
 | `pipeline.normalize.output_schema` | string | No | `seriatim-intermediate` |
 | `pipeline.normalize.report` | bool | No | `true` |
-| `pipeline.trim.enabled` | bool | No | `false` |
-| `pipeline.trim.output_path` | string | Conditional | none |
-| `pipeline.trim.bounds.prompt_id` | string | Conditional | none |
+| `pipeline.trim.enabled` | bool | No | `true` |
+| `pipeline.trim.output_path` | string | No | `transcripts/final.trimmed.json` |
+| `pipeline.trim.bounds.prompt_id` | string | No | `dnd.session_bounds` |
 | `pipeline.trim.bounds.profile_id` | string | No | empty |
-| `pipeline.trim.bounds.transcript_input_name` | string | Conditional | none |
-| `pipeline.trim.bounds.output_path` | string | Conditional | none |
-| `pipeline.trim.bounds.timeout` | duration string | No | `10m` |
+| `pipeline.trim.bounds.transcript_input_name` | string | No | `transcript` |
+| `pipeline.trim.bounds.output_path` | string | No | `artifacts/session_bounds.json` |
+| `pipeline.trim.bounds.timeout` | duration | No | `10m` |
 | `pipeline.trim.bounds.render_debug` | bool | No | `false` |
-| `pipeline.trim.bounds.render_output_path` | string | Conditional | none |
+| `pipeline.trim.bounds.render_output_path` | string | Conditional | required when `render_debug` is true |
 | `pipeline.trim.seriatim.report` | bool | No | `false` |
+| `pipeline.notarius.enabled` | bool | No | `false` |
+| `pipeline.notarius.binary` | string | No | `notarius` |
+| `pipeline.notarius.llm_api_key` | secret reference | No | unset; exact environment-variable name forwarded to Notarius |
+| `pipeline.notarius.config_path` | string | Conditional | required when enabled; relative paths resolve from the pipeline file directory |
+| `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.resume` | bool | No | `false`; request compatible Notarius checkpoint reuse during ordinary executed extraction |
+| `pipeline.notarius.chunk_cache` | string | No | empty; when set, exactly `auto`, `bypass`, or `refresh` |
+| `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) |
+| `pipeline.render.title` | string | No | empty (falls back to `session.title` when set) |
+| `pipeline.render.include_timestamps` | bool | No | `true` |
+| `pipeline.render.include_segment_ids` | bool | No | `true` |
+| `pipeline.render.include_metadata` | bool | No | `false` |
 | `pipeline.scriptorium.binary` | string | No | `scriptorium` |
 | `pipeline.scriptorium.config_path` | string | No | empty |
-| `pipeline.scriptorium.timeout` | duration string | No | `10m` |
+| `pipeline.scriptorium.timeout` | duration | No | `10m` |
 | `pipeline.scriptorium.render_debug` | bool | No | `false` |
 | `pipeline.scriptorium.artifacts` | map | No | empty |
-| `pipeline.scriptorium.artifacts.<name>.enabled` | bool | No | `false` |
-| `pipeline.scriptorium.artifacts.<name>.depends_on[]` | list[string] | No | empty |
-| `pipeline.scriptorium.artifacts.<name>.render_debug` | bool | No | unset |
-| `pipeline.scriptorium.artifacts.<name>.prompt_id` | string | Conditional | none |
-| `pipeline.scriptorium.artifacts.<name>.profile_id` | string | No | empty |
-| `pipeline.scriptorium.artifacts.<name>.output_path` | string | Conditional | none |
-| `pipeline.scriptorium.artifacts.<name>.timeout` | duration string | No | empty |
-| `pipeline.scriptorium.artifacts.<name>.inputs.<key>.source` | string | Conditional | none |
-| `pipeline.scriptorium.artifacts.<name>.inputs.<key>.artifact` | string | No | empty |
-| `pipeline.scriptorium.artifacts.<name>.inputs.<key>.path` | string | No | empty |
-| `pipeline.scriptorium.artifacts.<name>.inputs.<key>.required` | bool | No | `false` |
-| `pipeline.scriptorium.artifacts.<name>.vars.<key>` | map value | No | empty |
-| `pipeline.analyzer.binary_path` | string | No | empty |
-| `pipeline.analyzer.timeout` | duration string | No | empty |
-| `pipeline.analyzer.artifacts.output_dir` | string | No | empty |
-| `pipeline.analyzer.artifacts.types[]` | list[string] | No | empty |
-| `pipeline.notification.backend` | string | No | empty |
-| `pipeline.notification.recipient` | string | No | empty |
-| `pipeline.notification.timeout` | duration string | No | empty |
+| `pipeline.scriptorium.artifact_families` | map | No | empty; expands one ordinary artifact per canonical party character |
+| `pipeline.notification.mode` | string | No | `noop`; the only supported notification mode until a provider is implemented |
 
-Scriptorium artifact-key and dependency rules:
+### Notarius Credential
 
-- artifact keys must match `^[a-z][a-z0-9_]*$`.
-- enabled artifacts require `prompt_id` and `output_path`.
-- `output_path` must be relative, traversal-safe, and under `artifacts/`.
-- configured artifact input sources use `narratio.artifact.<name>`.
-- if input source references `narratio.artifact.<name>`, artifact `<name>` must exist and must be listed in `depends_on`.
-- every `depends_on` entry must be a configured artifact key.
-- self-dependency is rejected.
-- enabled dependency cycles are rejected.
-- any artifact referenced by `depends_on` or `narratio.artifact.<name>` source must define `output_path` (even if not enabled).
+`pipeline.notarius.llm_api_key` optionally names the one environment variable
+to forward to the Notarius child process:
 
-Allowed `pipeline.scriptorium.artifacts.<name>.inputs.<key>.source` values:
+```yaml
+notarius:
+  llm_api_key: OPENROUTER_API_KEY
+```
 
-- `previous_session_artifact`
-- `narratio.transcript.merged`
-- `narratio.transcript.polished`
-- `narratio.transcript.full`
-- `narratio.transcript.trimmed`
-- `narratio.bounds.session`
-- `narratio.artifact.<configured_artifact_key>`
+The field contains the variable name, not a credential value. That name must
+match `api_key_env` in the Notarius/PromptKit profile selected by the deployed
+Notarius pipeline; Narratio does not infer or remap provider names. Omission or
+`null` forwards nothing. A non-null selected reference must resolve at pipeline
+load time through the process environment or existing secrets-directory
+bootstrap, even when Notarius is disabled, extract is outside the requested
+range, or a completed extraction can be reused.
 
-## 8. Full session reference
+The Notarius child receives only Narratio's minimal execution environment plus
+this exact selected name and loaded value. Other credentials are not forwarded.
+Changing the value, name, presence, or absence does not invalidate extract's
+semantic resume evidence. The public name remains part of safe effective
+inspection, so renaming it may appear in `config diff` and change the effective
+configuration digest; rotating only its value does neither.
 
-| Path | Type | Required | Default |
+See the [Notarius integration contract](./integrations/notarius.md) for the
+delivery and redaction boundary.
+
+### Notarius Cache Controls
+
+`pipeline.notarius.resume` defaults to `false`. When true, an executed ordinary
+extraction passes `--resume`; the deployed Notarius configuration must already
+enable checkpoint recording and should select an explicit persistent checkpoint
+root. Narratio does not inspect or generate that configuration.
+
+`pipeline.notarius.chunk_cache` is empty by default, leaving Notarius's
+configured mode in control. A nonempty value must be `auto`, `bypass`, or
+`refresh` and is passed as `--chunk_cache`. Forced extraction takes precedence
+over both fields: it omits `--resume` and passes `--chunk_cache refresh`.
+Neither field changes Narratio's semantic extraction fingerprint, so changing
+them alone does not rerun an otherwise complete durable extraction.
+
+### 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 streams it into a verified, content-addressed session
+snapshot whose absolute path is passed to Notarius. Missing, unsafe, empty,
+changed-during-copy, 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>`:
+
+| Field | Type | Required | Rule |
 | --- | --- | --- | --- |
-| `session.session_id` | string | Yes | none |
-| `session.campaign` | string | Yes | none |
-| `session.date` | string | No | empty |
-| `session.title` | string | No | empty |
-| `session.inputs.audio_dir` | string | Conditional | empty |
-| `session.inputs.audio_files[]` | list[string] | Conditional | empty |
-| `session.inputs.audio_s3.prefix` | string | Conditional | none |
-| `session.inputs.speakers_file` | string | Yes | none |
-| `session.inputs.autocorrect_file` | string | Yes | none |
-| `session.inputs.glossary_file` | string | Yes | none |
+| `lane_id` | string | Yes | unique Notarius lane ID |
+| `media_type` | string | Yes | exact accepted descriptor media type |
+| `schema_id` | string | Yes | exact accepted descriptor schema ID |
+| `schema_version` | string | Yes | exact accepted descriptor schema version |
+| `module_key` | string | No | exact accepted module key when set |
 
-Audio-source rule:
+Output names must match `^[a-z][a-z0-9_]*$` and become selectable sources named
+`narratio.extraction.<name>`. Lane IDs must be unique. Every declared output is
+required from a successful Notarius result; a missing, rejected, duplicate, or
+contract-incompatible lane fails extraction. See the
+[complete maintained example](../examples/pipeline.full.annotated.yml) for the
+current ten-lane D&D mapping and the [Notarius contract](./integrations/notarius.md)
+for compatibility ownership.
 
-- configure exactly one mode:
-  - `audio_dir`, or
-  - `audio_files` (at least one), or
-  - `audio_s3.prefix`
-- `audio_s3` cannot be combined with local audio fields.
+### Scriptorium Artifact Entries
 
-## 9. Secrets
+For each `pipeline.scriptorium.artifacts.<name>`:
 
-Narratio supports filesystem-based secret injection via `pipeline.secrets.env_dir`.
+| Field | Type | Required | Rule |
+| --- | --- | --- | --- |
+| `enabled` | bool | No | `false` if omitted |
+| `depends_on[]` | list[string] | No | explicit ordering-only edges; must reference configured artifact keys, may not self-reference, and join inferred input edges in one acyclic graph |
+| `render_debug` | bool | No | per-artifact override |
+| `prompt_id` | string | Conditional | required when artifact is enabled |
+| `profile_id` | string | No | empty |
+| `output_path` | string | Conditional | required when enabled; also required when referenced by publish/output/input rules |
+| `timeout` | duration | No | artifact override |
+| `inputs` | map | No | input key names must be non-empty |
+| `vars` | map | No | values must be string or bool; `session_id` is reserved and overwritten by Narratio |
 
-Behavior:
+Narratio adds `session_id=narratio-session-<session_id>` to every Scriptorium request for sticky upstream LLM routing. If an artifact config sets `vars.session_id`, Narratio replaces that value before invoking Scriptorium. Use a different variable name if a prompt needs the raw Narratio session ID as content.
 
-- `env_dir` may be absolute or relative.
-- relative `env_dir` resolves from current working directory.
-- files with valid env-var names (`[A-Za-z_][A-Za-z0-9_]*`) are loaded.
-- values are loaded from file contents with trailing newline trimming.
-- existing process env vars are preserved.
-- invalid names and subdirectories are skipped.
-- missing/unreadable `env_dir` fails command execution.
+Without `--artifacts`, analyze executes enabled configured artifacts. With an
+explicit `--artifacts` list, the exact named configured artifacts are the
+one-invocation targets even if their `enabled` values are false. Analyze closes
+those targets over the effective dependency graph: a current prerequisite is reused, while a
+stale, missing, or failed prerequisite is rebuilt before its dependent.
+Unrelated artifacts are not executed. Named targets and any prerequisite that
+may require rebuilding must therefore have valid executable fields. This
+override affects analyze planning only; publish uses the list only to filter
+configured `narratio.artifact.<name>` output rules.
 
-Guidance:
+For each artifact input `pipeline.scriptorium.artifacts.<name>.inputs.<input_name>`:
 
-- do not put secret values directly in YAML.
-- configure env var names in config and provide values via env/secrets files.
+| Field | Type | Required | Rule |
+| --- | --- | --- | --- |
+| `source` | string | Yes | built-in runtime source, prepared input source, `narratio.extraction.<name>`, `narratio.artifact.<name>`, or `narratio.previous_session.artifact.<name>` |
+| `required` | bool | No | optional input requirement |
 
-## 10. Examples
+`artifact` and `path` are obsolete and rejected by strict configuration
+loading. Use the canonical `source` identifier to select the input; Narratio
+does not provide adapter-specific input passthrough fields.
 
-Maintained examples:
+Each `narratio.artifact.<name>` input source automatically contributes an
+effective dependency on that configured artifact. Narratio unions these inferred
+edges with explicit `depends_on` entries, then trims, deduplicates, and sorts the
+result during final configuration resolution. Authors use `depends_on` only for
+ordering constraints that are not already expressed by an artifact input.
+Use [`narratio config artifacts`](./cli.md#config-validate-config-show-config-sources-config-artifacts-and-config-diff)
+to inspect keys, definition sources, outputs, and effective dependencies without
+loading a session or creating runtime state.
 
-- `examples/pipeline.minimal.yml`
-- `examples/pipeline.production.yml`
-- `examples/pipeline.full.annotated.yml`
-- `examples/session.template.yml`
-- `examples/session.local-audio.yml`
-- `examples/session.s3-audio.yml`
+### Scriptorium Artifact Families
 
-These examples are validated by `internal/config` tests.
+`pipeline.scriptorium.artifact_families` declares a shared artifact template
+for every canonical campaign character. Configuration resolution expands each
+family into ordinary `pipeline.scriptorium.artifacts` entries before analyze
+planning or Scriptorium invocation. Party parsing rejects unsupported document
+schemas before family expansion.
+
+For each `pipeline.scriptorium.artifact_families.<name>`:
+
+| Field | Type | Required | Rule |
+| --- | --- | --- | --- |
+| `enabled`, `prompt_id`, `profile_id`, `timeout`, `render_debug`, `depends_on`, `inputs`, `vars` | ordinary artifact fields | No | copied to each generated artifact under the corresponding ordinary rules |
+| `for_each` | string | Yes | exactly `party.characters` |
+| `output_path_pattern` | string | Yes | safe path beneath `artifacts/` with exactly one `{character_id}` token and no other brace syntax |
+| `member_vars` | map | No | maps an ordinary Scriptorium variable name to a supported canonical character selector |
+| `member_dependencies` | list | No | unique family keys; each generated member depends on the corresponding generated member of each listed family |
+| `publish` | map | No | typed family publish policy (`enabled`, `required`, `dest_pattern`) expanded into concrete publish outputs when enabled |
+
+Generated keys are `<family>_<character_id>` and generated output paths must
+not collide with explicit artifacts or another generated artifact. Families
+expand even when disabled; normal analyze selection still omits disabled
+artifacts unless they are explicitly selected by their concrete key.
+
+Supported `member_vars` selectors are `character_id`, `player.name`,
+`character.name`, `character.class_summary`, and `character.alias_summary`.
+Their resolved values are strings. A member variable may not reuse a static
+`vars` name; `session_id` remains owned and overwritten by Narratio as for any
+other Scriptorium artifact.
+
+Within a family only, an input source may use
+`narratio.member_artifact.<family>`. Resolution rewrites the source to the
+corresponding ordinary `narratio.artifact.<family>_<character_id>` source and
+infers the concrete member dependency. Use `member_dependencies` only for
+additional same-character ordering constraints that are not already inputs.
+This syntax is rejected in explicit artifacts and never reaches runtime stages
+or Scriptorium.
+
+### Notifications
+
+Narratio currently supports only `notification.mode: noop`, which is also the
+default when the section is omitted. The notify stage performs no delivery in
+this mode. Backend, recipient, timeout, and other provider settings are
+rejected by strict configuration loading until Narratio has a provider
+integration.
+
+### Campaign
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `campaign_id` | string | Yes | canonical opaque campaign identity |
+| `session_template_file` | string | No | used by `session init` when set |
+| `inputs.speakers_file` | string | Yes | stable input default |
+| `inputs.autocorrect_file` | string | Yes | stable input default |
+| `inputs.glossary_file` | string | Yes | stable input default |
+| `inputs.party_file` | string | Yes | stable campaign party source; relative paths resolve from `campaign.yml` |
+| `inputs.spell_catalog_file` | string | No | optional spell-catalog overlay default; required when a Notarius reference selects `narratio.input.spell_catalog` |
+
+### Session
+
+| Field | Type | Required in session file | Notes |
+| --- | --- | --- | --- |
+| `session_id` | string | Yes | opaque identity; must match CLI session target when provided |
+| `previous_session_id` | string | No | opaque identity; must not equal `session_id` |
+| `campaign` | string | No | opaque identity; filled from `campaign_id` during resolve if omitted |
+| `date` | string | No | metadata |
+| `title` | string | No | metadata |
+| `inputs.speakers_file` | string | No | overrides campaign stable input |
+| `inputs.autocorrect_file` | string | No | overrides campaign stable input |
+| `inputs.glossary_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 |
+
+Audio rules:
+
+- configure local mode (`audio_dir` or `audio_files`) or S3 mode (`audio_s3.prefix`), not both.
+- `audio_s3` requires `pipeline.storage.backend: s3` and a configured S3 bucket.
+
+### Storage backend selection
+
+`local` is the default and disables remote object-store operations. Configure
+`s3` explicitly before supplying `storage.s3`; a populated S3 block does not
+select a backend on its own. Unknown backend names and an S3 block paired with
+`local` are rejected during configuration validation.
+
+### Previous-session expectation
+
+`previous_session_id` is optional in a session file. When a command supplies
+`--previous-session-id`, however, the session file must contain the same value;
+an omitted or different value is rejected before the command performs work.
+
+## Maintained Examples
+
+See the [maintained examples index](../examples/README.md) for complete pipeline,
+campaign, session, template, and input fixtures. Keep complete copyable files
+there rather than duplicating them in this reference.

docs/development.md

@@ -1,92 +1,64 @@
-# Development Guide
+# Development
 
-## Purpose
-Canonical contributor workflow and engineering conventions for implemented Narratio behavior.
+This is the first-read landing page for people and LLM coding agents working on
+Narratio. It provides a concise repository orientation and routes each kind of
+change to its canonical documentation.
 
-## Repository layout
+Narratio is a stage-driven Go orchestrator for turning D&D session audio into
+polished transcripts and generated artifacts. Start with the
+[README](../README.md) for product context,
+[Architecture](policy/architecture.md) for normative system boundaries, and the
+[Internal Overview](internal/overview.md) for implemented component ownership.
 
-- `cmd/narratio/`: CLI entrypoint.
-- `internal/app/`: command handlers, plan/run/resume orchestration, cleanup gates, secrets loading.
-- `internal/config/`: strict YAML loading, defaults, and validation.
-- `internal/stage/`: stage implementations and stage registry/order.
-- `internal/adapters/`: external boundary adapters (WhisperX, Seriatim, Audita, Scriptorium, storage, notify).
-- `internal/manifest/`: session/run manifest types and persistence.
-- `internal/artifacts/`: canonical local/remote path helpers and local artifact store.
-- `docs/`: canonical documentation set.
-- `examples/`: maintained config examples used by tests.
+## Go Prerequisite
 
-## Build and test commands
+Maintained development and verification require Go 1.26. Use the official Go
+1.26 toolchain before running repository commands.
 
-- Run focused CLI behavior checks:
+## What To Read
 
-```bash
-go test ./internal/app -run TestExecute -v
-```
+| When working on | Read | Why |
+| --- | --- | --- |
+| Finding the package or component that owns current behavior | [Internal Overview](internal/overview.md) | It is the implemented component inventory and routes to focused internal documents. |
+| Application shape, boundaries, dependency direction, runtime invariants, safety properties, or dependencies | [Architecture](policy/architecture.md) | It defines the intended system shape, ownership, and non-goals. |
+| Any documentation addition or revision | [Documentation Policy](policy/documentation.md) | It defines canonical owners, audiences, current-behavior rules, and maintenance requirements. |
+| Adding, changing, reviewing, rewriting, or deleting tests | [Testing Policy](policy/testing.md) | It defines risk-based sufficiency, durable test boundaries, test-double guidance, and test lifecycle decisions. |
+| CLI composition or command behavior | [Internal Overview](internal/overview.md) and [CLI Reference](cli.md) | The overview routes to command ownership; the reference owns public syntax and invocation behavior. |
+| Configuration loading, resolution, or user-visible configuration | [Internal Overview](internal/overview.md) and [Configuration](config.md) | The overview routes to implementation ownership; the reference owns fields, defaults, discovery, and validation. |
+| Session workflow, status, restore, cleanup, or object storage | [Restore Internals](internal/command-restore.md), [Workspace Internals](internal/workspace.md), [Storage Internals](internal/storage.md), [Operations](operations.md), and [Troubleshooting](troubleshooting.md) | These separate implementation mechanics, operator procedures, and symptom-driven recovery. |
+| Pipeline sequencing or the behavior of a stage | [Internal Overview](internal/overview.md) and its focused stage documents | The overview owns the implemented stage inventory and routes to each stage contract. |
+| Adapters or external tool contracts | [Adapter Internals](internal/adapters.md) and [Integration Contracts](integrations/README.md) | The internal guide owns adapter composition and mechanics; integration documents own external formats and protocols. |
+| Manifests, artifacts, workspace paths, or publish behavior | [Manifest Internals](internal/manifest.md), [Artifact Internals](internal/artifacts.md), [Workspace Internals](internal/workspace.md), [Publish Internals](internal/stage-publish.md), and [Operations](operations.md) | These separate implementation state and resolution from operator-visible layout and lifecycle. |
+| Maintained configuration or input examples | [Configuration](config.md) and [Examples](../examples/README.md) | The reference owns field meanings; the examples directory owns complete copyable files. |
+| Preparing, validating, or publishing a release | [Release Procedure](release.md) | The maintainer procedure owns version selection, candidate validation, guarded tag publication, and optional later CI inspection. |
+| Proposed or unimplemented behavior | `docs/roadmap/` | Future work belongs only in roadmap documentation until implemented. |
 
-- Run config example load/validate checks:
+For an existing subsystem, also inspect its focused tests and package-level
+contracts before changing behavior.
 
-```bash
-go test ./internal/config -run TestExamplesLoadAndValidate -v
-```
+## Validation
 
-- Run full test suite:
+Use focused package tests while iterating. Every pull request and push runs the
+following repository-wide checks before it can be accepted:
 
-```bash
+```sh
 go test ./...
+go test -race ./...
+go vet ./...
+go build ./...
+go test ./internal/doccheck
+go test ./internal/config -run '^TestExamplesLoadAndValidate$'
 ```
 
-## Coding conventions
+The documentation check verifies local Markdown links and the dependency graph
+of the Woodpecker workflows. The configuration check loads every maintained
+pipeline and session example. Tag CI reuses this validation path before its
+asynchronous asset publication; the maintainer release boundary is documented
+in the [Release Procedure](release.md).
 
-- Keep orchestration explicit and stage-driven; do not introduce generic workflow/DAG abstractions.
-- Keep external-system details inside adapter packages; stages should consume Narratio-level contracts only.
-- Use centralized path helpers from `internal/artifacts` rather than ad hoc path concatenation.
-- Preserve manifest-driven state transitions (`running`, `succeeded`, `failed`, `skipped`, `stale`) as the source of run progress.
-- Keep user/operator docs implementation-accurate; planned work belongs only under `docs/roadmap/`.
-
-For design principles and invariants, see [docs/architecture.md](./architecture.md). For stage/adapter contracts, see [docs/internal/README.md](./internal/README.md).
-
-## Dependency policy
-
-- Prefer Go standard library where practical.
-- Add third-party dependencies only when they provide clear value for required behavior.
-- Keep dependency additions narrow to the boundary package that needs them.
-
-## Change playbooks
-
-### Add config fields
-
-1. Add fields to config structs in `internal/config`.
-2. Set defaults in `internal/config/defaults.go` when appropriate.
-3. Add validation rules in `internal/config/validate.go`.
-4. Add or update load/validate tests in `internal/config/*_test.go`.
-5. Update canonical config docs and examples:
-   - [docs/config.md](./config.md)
-   - relevant files under `examples/`
-
-### Add CLI flags or commands
-
-1. Update command parsing and behavior in `internal/app`.
-2. Add or update command tests (`TestExecute` and command-specific tests).
-3. Update [docs/cli.md](./cli.md) and, if operator workflow changes, [docs/operations.md](./operations.md).
-
-### Add or modify stages/adapters
-
-1. Implement stage behavior in `internal/stage` with clear input/output boundaries.
-2. Keep external transport/subprocess details in `internal/adapters`.
-3. Preserve manifest and promotion semantics expected by runner and archive logic.
-4. Add/update stage and adapter tests.
-5. Update internal component contracts in `docs/internal/`.
-
-### Update examples
-
-1. Keep canonical examples only in `examples/`.
-2. Ensure examples load and validate through runtime config paths.
-3. Update `internal/config/load_validate_test.go` as needed.
-4. Update links in `docs/config.md` if example filenames change.
-
-### Update docs and roadmap
-
-1. Keep implemented behavior in canonical docs (`README`, `docs/*.md`, `docs/internal/`).
-2. Keep planned/unimplemented behavior only in `docs/roadmap/`.
-3. After completing roadmap items, remove or mark them complete in `docs/roadmap/documentation.md`.
-4. Run a link/path sweep before finalizing changes.
+Woodpecker also runs `go test -race -shuffle=on -count=3 ./...` on its scheduled
+job to expose ordering and repeatability defects. Current runners cross-compile
+the supported Linux amd64 and arm64 targets and the best-effort macOS arm64
+target. The macOS cross-build establishes compilation only, not native runtime
+evidence. Add a native check only when an official runner label and successful
+native-run evidence are available.

docs/documentation/policy.md

@@ -1,356 +0,0 @@
-# Go Project Documentation Policy
-
-## Purpose
-
-Project documentation must help four audiences:
-
-1. users who need to run the application;
-2. administrators/operators who need to configure and operate it;
-3. developers who need to understand and change it safely;
-4. LLM coding agents that need clear scope, boundaries, and invariants.
-
-Docs should be accurate, concise, task-oriented, and organized by audience. Prefer links to canonical docs over repetition.
-
-## Core Rules
-
-### 1. Keep docs concise
-
-Each document should cover a defined scope and only the essentials for that scope.
-
-Avoid:
-- long background explanations;
-- repeated reference material;
-- implementation detail in user-facing docs;
-- aspirational language outside roadmap docs;
-- verbose examples where one minimal example is clearer.
-
-### 2. Document only implemented behavior outside roadmap files
-
-Unimplemented, planned, aspirational, experimental, or future work may be described only under:
-
-- `docs/roadmap/`
-
-No other documentation file, including `README.md`, should describe code, features, modules, stages, commands, config fields, or behaviors that do not currently exist.
-
-If a feature is partial, non-roadmap docs may describe only the implemented portion and its current boundary.
-
-### 3. Use canonical homes
-
-Each type of information should have one canonical location.
-
-Canonical homes:
-
-- project purpose and quickstart: `README.md`
-- development principles: `docs/architecture.md`
-- configuration reference: `docs/config.md`
-- CLI reference: `docs/cli.md`
-- operations and recovery: `docs/operations.md`
-- troubleshooting: `docs/troubleshooting.md`
-- implemented internals: `docs/internal/`
-- future work: `docs/roadmap/`
-- contributor workflow: `docs/development.md`
-- copyable examples: `examples/`
-
-Other files should summarize briefly and link to the canonical source.
-
-### 4. Keep examples real
-
-Examples should be valid, maintained, and free of secrets.
-
-Where practical:
-- example configs should load successfully;
-- example commands should match real CLI syntax;
-- important examples should be covered by tests.
-
-## Documentation Profiles
-
-All projects require:
-
-- `README.md`
-- `docs/architecture.md`
-
-Additional docs depend on the project.
-
-### Small library
-
-Recommended:
-- `docs/development.md`, if contributor conventions are non-obvious
-
-### Simple CLI
-
-Required:
-- `docs/cli.md`
-
-Recommended:
-- `docs/development.md`
-
-### Config-driven CLI
-
-Required:
-- `docs/cli.md`
-- `docs/config.md`
-
-Recommended:
-- `examples/`
-- `docs/development.md`
-
-### Stateful or operator-facing application
-
-Required:
-- `docs/cli.md`, if CLI-based
-- `docs/config.md`, if config-driven
-- `docs/operations.md`
-
-Recommended:
-- `docs/troubleshooting.md`
-- `examples/`
-- `docs/development.md`
-
-### Modular, staged, service-oriented, or orchestration application
-
-Required:
-- `docs/cli.md`, if CLI-based
-- `docs/config.md`, if config-driven
-- `docs/operations.md`
-- `docs/internal/`
-- `docs/development.md`
-
-Recommended:
-- `docs/troubleshooting.md`
-- validated examples under `examples/`
-
-## Required Documents
-
-### README.md
-
-**Audience:** users, administrators, operators
-
-The README is the outward-facing project orientation page.
-
-It should include, in order:
-
-1. concise description;
-2. elevator pitch;
-3. shortest useful command or usage example;
-4. links to targeted docs.
-
-The README should be short. It is not a manual.
-
-The “shortest useful command” means the simplest command that performs the project’s core use case. (It does not mean `app --help`.)
-
-### docs/architecture.md
-
-**Audience:** developers, LLM coding agents
-
-`docs/architecture.md` is required for every project.
-
-It is an inward-facing development policy document. It should describe how the project is intended to be built and changed.
-
-It should include:
-
-- project shape;
-- core design principles;
-- package and boundary philosophy;
-- state/persistence philosophy, if applicable;
-- external integration philosophy, if applicable;
-- error-handling and logging principles;
-- testing expectations;
-- documentation expectations;
-- architectural invariants;
-- explicit non-goals, if useful.
-
-For small projects, this file may be brief. It may simply state that the project is intentionally narrow, monolithic, and dependency-light.
-
-### docs/config.md
-
-**Audience:** administrators, operators, advanced users
-
-Required for applications with configuration files.
-
-It should include, in order:
-
-1. config file locations and discovery precedence;
-2. minimal working config;
-3. production-oriented config;
-4. full configuration reference;
-5. secrets handling, if applicable;
-6. links to maintained examples.
-
-The full configuration reference should be canonical.
-
-### docs/cli.md
-
-**Audience:** users, administrators, operators
-
-Required for CLI applications.
-
-It should include, in order:
-
-1. shortest useful command;
-2. command overview;
-3. complete flag reference;
-4. common workflows;
-5. diagnostic or recovery commands, if applicable.
-
-Explain when commands are useful, not just their syntax.
-
-### docs/operations.md
-
-**Audience:** administrators, operators
-
-Required for applications that maintain state, support resume behavior, run multiple stages, write durable artifacts, use remote storage, or require recovery procedures.
-
-It should cover:
-
-- normal workflow;
-- filesystem layout;
-- remote storage layout, if applicable;
-- logs and manifests;
-- resume/retry behavior;
-- cleanup behavior;
-- archive/backup behavior;
-- safe recovery procedures;
-- operational caveats.
-
-### docs/troubleshooting.md
-
-**Audience:** administrators, operators
-
-Recommended once recurring failure modes exist.
-
-Each entry should include:
-
-- symptom;
-- likely cause;
-- diagnostic command or inspection step;
-- safe fix;
-- relevant links.
-
-### docs/development.md
-
-**Audience:** developers, LLM coding agents
-
-Required for projects maintained by humans and LLM coding agents.
-
-It should include:
-
-- repository layout;
-- build/test commands;
-- coding conventions;
-- dependency policy;
-- how to add config fields;
-- how to add CLI flags;
-- how to add stages/modules/adapters, if applicable;
-- how to update examples;
-- documentation update expectations.
-
-### docs/internal/
-
-**Audience:** developers, LLM coding agents
-
-Required for modular, staged, service-oriented, or orchestration projects.
-
-This directory describes implemented internal components. It is not the roadmap.
-
-Use one file per major component where useful.
-
-Each component doc should include:
-
-1. purpose;
-2. inputs and outputs;
-3. boundaries;
-4. config fields used;
-5. external adapters used;
-6. state or manifest behavior, if applicable;
-7. skip/resume behavior, if applicable;
-8. failure behavior;
-9. tests to inspect before changing;
-10. architectural invariants.
-
-### docs/roadmap/
-
-**Audience:** maintainers, developers, LLM coding agents
-
-This is the only place for planned, future, aspirational, experimental, or unimplemented work.
-
-Roadmap docs should clearly distinguish:
-
-- proposed work;
-- accepted plans;
-- deferred ideas;
-- rejected ideas;
-- implementation prompts or task breakdowns, if useful.
-
-Roadmap docs should not be confused with current behavior.
-
-### docs/integrations/
-
-**Audience:** developers, LLM coding agents
-
-Required for projects that depend on external CLIs, APIs, services, protocols, or file formats where the integration contract is important to maintain.
-
-This directory contains concise, versioned reference notes for external integration contracts. It should document only the parts of the external system that this project actually uses.
-
-Use one file per integration where useful.
-
-## Examples Directory
-
-Projects with non-trivial configuration or workflows should include `examples/`.
-
-Useful examples include:
-
-- minimal working config;
-- production-oriented config;
-- full annotated config;
-- local development config;
-- remote/object-storage config;
-- minimal session/input file.
-
-Examples should be valid, maintained, tested when practical, and linked from relevant docs.
-
-## Security and Privacy
-
-Docs and examples must not include:
-
-- real API keys;
-- tokens;
-- passwords;
-- private keys;
-- private environment dumps;
-- sensitive user data;
-- raw private transcripts;
-- private infrastructure details unless intentionally public.
-
-Document secret-handling mechanisms, not actual secret values.
-
-## Maintenance Rules
-
-When docs change, verify the affected behavior.
-
-Where practical:
-
-- load example config files in tests;
-- test CLI examples or command parser behavior;
-- validate documented flags against real flags;
-- remove stale references;
-- update links after renames;
-- keep roadmap content out of non-roadmap docs.
-
-If documentation and code disagree, fix the documentation and/or open a roadmap item; do not leave aspirational behavior in current-behavior docs.
-
-Documentation is complete only when it matches the current code.
-
-## Documentation Change Checklist
-
-Before merging documentation changes, verify:
-
-- README is concise and orientation-focused.
-- `docs/architecture.md` describes development principles.
-- Future work appears only under `docs/roadmap/`.
-- User-facing docs avoid unnecessary internals.
-- Developer-facing docs preserve boundaries and invariants.
-- Config examples match the schema.
-- CLI examples match real commands and flags.
-- Defaults appear in the canonical config reference.
-- No secrets or private data are included.
-- Links are accurate.

docs/integrations/README.md

@@ -1,15 +1,36 @@
-# Integration Documentation Index
+# Integrations Index
 
 ## Audience
-Developers and LLM coding agents changing Narratio's external integration contracts.
+
+Operators, developers, and coding agents who need to understand Narratio's
+externally observable integration boundaries.
 
 ## Scope
-Implemented-only reference notes for the external systems Narratio currently integrates with.
 
-## Integration Docs
-- `audita.md`: Audita adapter invocation and validation contract.
-- `seriatim.md`: Seriatim normalize/merge/trim adapter contract.
-- `scriptorium.md`: Scriptorium run/render adapter contract.
+`docs/integrations/` is the canonical reference for protocols, invocation and
+data contracts, logical outputs, and compatibility behavior at external tool
+boundaries.
 
-## Canonical Owner
-`docs/integrations/` is the canonical home for external integration reference notes per `docs/documentation/policy.md`.
+These documents describe what Narratio sends or invokes, what it accepts in
+return, and how failures are surfaced. Internal composition and stage mechanics
+belong in [the adapter implementation guide](../internal/adapters.md) and the
+focused stage documents.
+
+## Integration Contracts
+
+- [Audita](./audita.md): transcript polishing (`audita process`).
+- [Notarius](./notarius.md): complete pipeline execution and safe JSON bundle
+  discovery (`notarius run`).
+- [Party](./party.md): canonical campaign roster input.
+- [Seriatim](./seriatim.md): merge, normalize, trim, and render operations.
+- [Scriptorium](./scriptorium.md): artifact generation and debug rendering
+  (`scriptorium run|render`).
+- [WhisperX](./whisperx.md): speaker-audio transcription over HTTP.
+
+## Related Canonical Docs
+
+- [Configuration](../config.md): operator-facing configuration reference.
+- [Adapter implementation](../internal/adapters.md): shared adapter boundary and
+  runner wiring.
+- [Internal documentation](../internal/overview.md): stage-specific integration
+  usage and component ownership.

docs/integrations/audita.md

@@ -1,66 +1,69 @@
-# Integration: audita
+# Integration: Audita
 
 ## Purpose
-Define Narratio's adapter contract for transcript polishing via Audita CLI subprocess execution.
+Define the Audita adapter contract used by the `polish` stage.
 
-## Inputs and Outputs
-Inputs (`audita.PolishRequest`):
-- merged transcript path
-- glossary path
-- output processed transcript path
-- optional report path (required when report enabled)
-- work dir
-- generated config path
-- stdout/stderr log paths
-- optional module/model/base URL and concurrency knobs
+## External Boundary
 
-Outputs (`audita.PolishResult`):
-- processed transcript path
-- optional report path
-- generated config path
-- stdout/stderr log paths
-- exit code, duration, invoked binary
-- adapter metadata
+Narratio invokes `audita process` as a subprocess for each polish operation.
+The configured timeout and parent cancellation bound the invocation. Internal
+runner composition is documented in
+[the adapter implementation guide](../internal/adapters.md).
 
-## Boundaries
-Owns:
-- Deterministic CLI argument construction for `audita process`
-- Environment bridging for API credentials
-- Invocation config emission
-- Output validation for processed transcript and report
+## Request Contract
+`PolishRequest` carries:
+- required transcript/glossary/output/work-dir paths;
+- optional report path (required when report mode is enabled);
+- generated config and stdout/stderr log paths;
+- optional per-invocation module override.
 
-Does not own:
-- Upstream/downstream stage orchestration
-- Credential sourcing policy beyond required env-var presence check
+The constructed runner owns static Audita settings: binary, timeout,
+credentials, default modules, model and endpoint settings, validation and output
+settings, report mode, and concurrency. The `polish` stage supplies only
+invocation-specific paths and may override modules for that invocation.
 
-## Config Fields Used
-Via `pipeline.audita.*` mapped in app/stage wiring:
-- `binary`, `timeout`, `llm_api_key_env`, `modules`, `base_url`, `model`
-- `transcript_description`, `config_path`, `output_schema`, `work_dir_retention`
-- `total_llm_concurrency`, `proposal_llm_concurrency`, `validation_model`, `validation_llm_concurrency`, `report`
+## Result Contract
+`PolishResult` returns:
+- processed transcript path;
+- optional report path;
+- work dir and generated-config/log paths;
+- exit code, duration, binary provenance;
+- adapter metadata map.
 
-## External Adapters Used
-- Shared subprocess helper (`internal/adapters/subprocess`) to run CLI and capture logs.
+## Validation and Failure Semantics
+Construction fails for invalid static config values, including:
+- empty binary;
+- non-positive timeout;
+- invalid base URL;
+- invalid output schema;
+- invalid work-dir retention value;
+- invalid concurrency values.
 
-## State and Manifest Behavior
-- No direct manifest writes.
-- Stage-level metadata records adapter provenance and credential-present signal.
-- Generated invocation YAML is written when `GeneratedConfigPath` is provided.
+Run fails for:
+- missing required request paths;
+- subprocess execution failure;
+- invalid processed transcript JSON (`segments` array required);
+- invalid report JSON when reporting is enabled.
 
-## Skip and Resume Behavior
-- Adapter has no skip/resume logic. Stage/runner controls this.
+Processed transcript JSON is limited to 64 MiB and optional report JSON to 16
+MiB. Both must be regular files without symlinked path components.
 
-## Failure Behavior
-- Constructor validation fails on invalid binary/timeout/schema/concurrency/URL values.
-- Run fails on missing required paths, missing required credential env var, subprocess errors, invalid processed JSON shape, or invalid report JSON.
-- Failures preserve stdout/stderr paths in returned result metadata.
+Failure results still include output/log/config/exit metadata for diagnostics.
 
-## Tests to Inspect Before Changing
-- `internal/adapters/audita/subprocess_test.go`
-- `internal/adapters/audita/fake_test.go`
-- `internal/stage/polish_test.go`
+## Deterministic Behavior
+- CLI args are built from runner config + request in a fixed order.
+- A configured typed `llm_api_key` reference is resolved during pipeline load;
+  the captured value is supplied only as the child's `AUDITA_LLM_API_KEY`
+  override and is never re-read from the parent environment.
+- Generated invocation YAML (`audita.generated.v1`) is emitted when requested.
+- Manifest writes are stage-owned; adapter itself is stateless.
 
-## Architectural Invariants
-- Processed output must be valid JSON with top-level `segments` array.
-- When report is enabled, report output must be valid JSON.
-- If `llm_api_key_env` is configured, credential must be present in environment.
+## Configuration
+
+Operator-selected values are defined under `pipeline.audita.*` in the
+[configuration reference](../config.md#pipeline).
+
+Maintained example with Audita config:
+
+- [Full annotated pipeline](../../examples/pipeline.full.annotated.yml)
+- [Production-shaped pipeline](../../examples/pipeline.production.yml)

docs/integrations/notarius.md

@@ -0,0 +1,188 @@
+# Notarius Integration Contract
+
+## Boundary
+
+Narratio uses Notarius as a subprocess to extract configured structured JSON
+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 v0.7.0 references:
+
+- [CLI reference](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.7.0/docs/cli.md)
+- [Subprocess consumer contract](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.7.0/docs/consumers/subprocess.md)
+- [D&D pipeline and lane contracts](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.7.0/docs/consumers/dnd-pipeline.md)
+- [Run-result receipt](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.7.0/docs/integrations/run-result.md)
+- [JSON output bundle](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.7.0/docs/integrations/json-output.md)
+- [D&D spell-catalog overlay](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.7.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
+Notarius documents as canonical when changing those values; Narratio does not
+duplicate the complete schemas.
+
+## Invocation
+
+When `pipeline.notarius.enabled` is true, Narratio resolves the executable,
+configuration path, input path, output directory, and working directory to
+absolute paths. Configured references require support for the `--reference`
+contract introduced in Notarius v0.6.0. Cache controls require support for the
+selected `--resume` and `--chunk_cache` flags. Notarius v0.7.0 is the tested
+cache integration baseline, not an unconditional minimum version; Narratio
+does not impose a runtime version gate. Each reference binding is a separate
+argument before `--json`:
+
+```text
+notarius run <pipeline_id> --config <config_path> --input <trimmed_json> --output-dir <staging_dir> [--resume] [--chunk_cache <mode>] [--reference <selector>=<verified_snapshot_path>]... --json
+```
+
+Reference paths are absolute stable snapshots streamed from manifest-verified
+canonical files prepared inside the current Narratio session workspace. They
+live at `cache/notarius/references/<sha256>/<prepared-basename>` and retain the
+full lowercase content digest. Narratio verifies snapshot checksum and size
+before and after the subprocess, reconstructs missing or corrupt regular files
+from a still-valid prepared source, and passes only configured bindings,
+ordered lexically by normalized selector, as direct argument-vector entries
+without shell interpretation. Symlinks, directories, other non-regular
+conflicts, and prepared-source mismatches fail rather than being deleted. A CLI
+binding takes precedence over a matching external path in Notarius
+configuration. Narratio never emits `--without-reference`.
+
+For canonical party configuration, the `party` binding is the unchanged,
+validated authored roster and the `players` binding is its generated
+projection. Both retain their established `narratio.input.party` and
+`narratio.input.players` source IDs, and both are resolved from the prepared
+manifest rather than from campaign configuration at extraction time.
+
+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 verified glossary snapshot> \
+  --reference party=<absolute verified party snapshot> \
+  --reference players=<absolute verified players snapshot> \
+  --reference spell_catalog=<absolute verified spell catalog snapshot> \
+  --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.
+It does not pass a Narratio session ID or run `notarius config validate`
+automatically; the configured working directory and Narratio's minimal child
+environment apply to the subprocess.
+
+Ordinary extraction maps `pipeline.notarius.resume: true` to `--resume` and a
+nonempty `pipeline.notarius.chunk_cache` to `--chunk_cache <mode>`. Forced
+extraction always omits `--resume` and supplies `--chunk_cache refresh`.
+Notarius owns checkpoint enablement, recording, identity, and both cache roots;
+Narratio neither reads nor synthesizes its configuration. Use explicit
+persistent roots in Notarius when reuse must span subprocess invocations.
+Changing a reference path/digest or other upstream identity input correctly
+causes a cold miss. Chunk refresh bypasses lookup and publishes the accepted
+replacement for the active source; it does not delete unrelated plans or
+checkpoint state.
+
+When `pipeline.notarius.llm_api_key` is absent or null, Narratio adds no
+credential to that environment. When configured, the field names an environment
+variable whose already-loaded nonempty value is forwarded under that exact
+name. Operators must use the same name as the `api_key_env` in the selected
+Notarius/PromptKit profile. Narratio does not inspect the Notarius configuration
+to infer a provider or destination name, and it does not forward unrelated
+credentials from its parent environment or secrets directory.
+
+The selected name is registered with Narratio's shared streaming redactor.
+Credential bytes written by the child to captured stdout, captured stderr, or
+stderr-derived failure diagnostics are replaced with `<redacted>`, including
+custom names not known to the built-in sensitive-name list. Narratio does not
+serialize the credential into arguments, stage metadata, manifests, or
+generated configuration.
+
+This captured-stream protection is not a filesystem sandbox. Notarius remains
+responsible for keeping credentials out of files it writes directly, including
+bundle artifacts and its own diagnostics. Narratio does not scan or rewrite
+arbitrary downstream files and cannot promise redaction of transformed or
+encoded credentials.
+
+## Accepted Result
+
+Narratio's tested invocation baseline is Notarius v0.7.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`,
+`warnings.json`, and `diagnostics.json`. All receipt, index, and lane paths must
+stay inside that bundle; symlinks and non-regular lane payloads are rejected.
+
+Supported receipt and index shapes tolerate unknown fields for forward
+compatibility, while required identity, validation, count, manifest,
+rejection, warning, diagnostic, and lane-list fields remain mandatory.
+Narratio applies bounded reads to the receipt, index, rejection, warning, and
+diagnostic documents. Warning and diagnostic envelopes, group counts,
+occurrence counts, truncation state, framework-owned origins, and
+receipt-to-bundle counts must be internally consistent. Optional chunk-map and
+evidence-context descriptors must carry their complete generic contract
+metadata when present.
+
+For every entry in `pipeline.notarius.outputs`, Narratio requires exactly one
+index descriptor with the configured lane ID, media type, schema ID, schema
+version, and, when configured, module key. Missing, duplicate, rejected, or
+incompatible required lanes fail extraction even if Notarius exited zero. A
+configured lane whose v2 validation summary is `rejected` or `incomplete` also
+fails extraction.
+An accepted reused producer may report `producer_attempt_count: 0`; Narratio
+preserves that valid summary rather than treating it as a missing field.
+Unconfigured lanes may remain in the preserved bundle but do not become
+selectable Narratio sources.
+
+Each accepted configured lane is registered as
+`narratio.extraction.<output_key>`. The bundle index is retained for audit and
+resume validation but is not selectable. Scriptorium and publish rules consume
+only explicitly named lane sources; `--artifacts` never selects Notarius lanes.
+
+## Failure And Compatibility Behavior
+
+- Startup and nonzero-exit errors fail extraction and retain captured diagnostics.
+- Invalid receipt JSON or an unsupported receipt schema fails before bundle use.
+- Unsafe or incompatible index data and required-lane rejection fail before the
+  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
+copying free-form external messages into Narratio manifest metadata or reading
+lane payload bodies.
+
+Configuration fields and defaults are in [Configuration](../config.md).
+Operator paths, rerun procedures, and bundle retention are in
+[Operations](../operations.md). See [Troubleshooting](../troubleshooting.md)
+for failure recovery.
+
+## Opt-in Integration Test
+
+The production-boundary cache test requires an absolute path to a locally
+built Notarius v0.7.0-compatible executable. It uses only a local
+OpenAI-compatible `httptest` provider and temporary cache/config/output roots:
+
+```sh
+NARRATIO_TEST_NOTARIUS_BINARY=/absolute/path/to/notarius \
+  GOWORK=off go test ./internal/stage \
+  -run '^TestNotariusCacheReuseIntegration$' -count=1 -v
+```
+
+When the variable is unset, the normal test suite skips this test and never
+searches `PATH`, a sibling checkout, the network, or a real provider.

docs/integrations/party.md

@@ -0,0 +1,71 @@
+# Canonical Party Input
+
+`party.yml` is a campaign-owned roster input. It must be a single, versioned
+`narratio.party.v1` document when Narratio resolves a pipeline, campaign, and
+session together.
+
+```yaml
+schema_version: narratio.party.v1
+
+characters:
+  arannis:
+    player:
+      name: Eric
+    character:
+      name: Arannis
+      alias:
+        - Ari
+        - The Grey Owl
+      classes:
+        - name: wizard
+          level: 8
+```
+
+`characters` is a non-empty mapping. Each key is a stable character ID using
+the configured-artifact key grammar: a lowercase ASCII letter followed by zero
+or more lowercase ASCII letters, digits, or underscores. Character order is
+preserved where roster order matters.
+
+Every entry has `player.name`, `character.name`, and a non-empty
+`character.classes` list. Class entries require a non-empty `name` and may
+include a positive integer `level`. The optional, intentionally singular
+`character.alias` field is a list. Names, aliases, and class names must be
+non-empty, trimmed display strings without control characters. Character names
+and aliases must be unique across the full roster under Unicode-aware
+case-insensitive comparison; player names may repeat.
+
+The document has exactly one YAML document and accepts no unknown fields.
+`schema_version` is required: a missing, wrong, or malformed value is an error.
+
+## Migration
+
+Unversioned party inputs are rejected. Replace each legacy party document with
+the versioned structure above, move each roster entry under `characters`, and
+remove separate player and session-party settings: those keys are unsupported.
+
+The configuration rules and source-relative path behavior are defined in the
+[Configuration Reference](../config.md).
+
+## Derived players document
+
+During `prepare`, Narratio copies the canonical party source bytes unchanged
+to `inputs/party.yml` and writes this deterministic players-only projection to
+`inputs/players.yml`:
+
+```yaml
+schema_version: narratio.players.v1
+players:
+    - name: Eric
+      character:
+        id: arannis
+        name: Arannis
+        alias:
+            - Ari
+            - The Grey Owl
+```
+
+There is one entry per character, sorted by stable character ID. Repeated
+player names remain separate entries. The optional `alias` list retains its
+declared order and is omitted when empty. The projection carries no class
+data. Its prepared manifest record is marked `derived_from_party`; it is not a
+separate user-provided `players_file`.

docs/integrations/scriptorium.md

@@ -1,64 +1,71 @@
-# Integration: scriptorium
+# Integration: Scriptorium
 
 ## Purpose
-Define Narratio's adapter contract for Scriptorium artifact generation and render-debug subprocess invocations.
+Define the Scriptorium adapter contract used by `analyze` and trim-bounds generation in `trim`.
 
-## Inputs and Outputs
-Inputs:
-- `RunArtifactRequest`: binary, config path, prompt/profile IDs, input map, vars map, timeout, output path, logs/config paths, optional API env and working dir
-- `RenderArtifactRequest`: same core fields for render mode
+## External Boundary
 
-Outputs (`ArtifactResult`):
-- output path
-- stdout/stderr log paths
-- generated config path
-- exit code and duration
-- command mode (`run` or `render`)
-- prompt/profile provenance
-- validation failure signal
-- adapter metadata
+Narratio invokes Scriptorium as a subprocess in these modes:
 
-## Boundaries
-Owns:
-- Deterministic CLI arg construction for `scriptorium run` and `scriptorium render`
-- Common request validation
-- Invocation config emission
-- Output existence/non-empty checks
-- Validation-failure mapping for run exit code 2
+- `scriptorium run`
+- `scriptorium render`
 
-Does not own:
-- Artifact selection policy (`analyze` stage)
-- Bounds semantic validation (`trim` stage)
+The request timeout and parent cancellation bound each invocation. Internal
+runner composition is documented in
+[the adapter implementation guide](../internal/adapters.md).
 
-## Config Fields Used
-Via `pipeline.scriptorium.*` and stage-level artifact config:
-- `binary`, `config_path`, `timeout`, `render_debug`
-- artifact-level `prompt_id`, `profile_id`, `timeout`, `inputs`, `vars`, `output_path`
+## Request Contract
+Both request types carry:
+- binary/config/prompt/profile IDs;
+- input map and vars map;
+- output path;
+- timeout;
+- generated config + stdout/stderr log paths;
+- optional API-key env var name;
+- optional working directory.
 
-## External Adapters Used
-- Shared subprocess helper (`internal/adapters/subprocess`).
+## Result Contract
+`ArtifactResult` returns:
+- output/log/generated-config paths;
+- exit code and duration;
+- command mode (`run` or `render`);
+- prompt/profile provenance;
+- `ValidationFailed` marker;
+- metadata map.
 
-## State and Manifest Behavior
-- No direct manifest writes.
-- Stage metadata records adapter outputs and command mode.
-- Generated invocation YAML is written when requested.
+## Validation and Failure Semantics
+Request validation fails for:
+- missing binary, prompt id, or output path;
+- non-positive timeout;
+- empty input/var names;
+- empty input path values;
+- missing required credential env var when `APIKeyEnv` is set.
 
-## Skip and Resume Behavior
-- Adapter has no skip/resume logic. Stage/runner controls execution.
+Run behavior:
+- subprocess errors propagate with context;
+- `run` exit code `2` is mapped to `ValidationFailed=true`;
+- successful subprocess still fails if output file is missing or empty.
 
-## Failure Behavior
-- Request validation fails for missing binary/prompt/output, invalid timeout, invalid input/var names, or missing required API env var.
-- Subprocess errors bubble with command context.
-- `run` exit code 2 is treated as `ValidationFailed=true` and surfaced as error by calling stage.
-- Successful subprocess still fails if output file is missing/empty.
+Each artifact result is limited to 64 MiB and must be a regular file without
+symlinked path components.
 
-## Tests to Inspect Before Changing
-- `internal/adapters/scriptorium/subprocess_test.go`
-- `internal/adapters/scriptorium/fake_test.go`
-- `internal/stage/analyze_test.go`
-- `internal/stage/trim_test.go`
+Render behavior:
+- subprocess errors propagate;
+- output file must exist and be non-empty.
 
-## Architectural Invariants
-- Both modes require explicit timeout > 0.
-- Input/var maps are sorted into deterministic CLI argument order.
-- Run-mode validation failures are represented explicitly, not silently skipped.
+## Deterministic Behavior
+- input and var maps are sorted into deterministic `--input` and `--var` CLI args.
+- stage wiring adds `session_id=narratio-session-<session_id>` to every Scriptorium request for sticky upstream routing, overriding any configured `vars.session_id`.
+- generated invocation YAML (`scriptorium.generated.v1`) is emitted when requested.
+- adapter is stateless and does not own artifact-selection policy.
+
+## Configuration
+
+Operator-selected values are defined under `pipeline.scriptorium.*`, including
+per-artifact settings under `pipeline.scriptorium.artifacts.*`, in the
+[configuration reference](../config.md#pipeline).
+
+Maintained examples with Scriptorium config:
+
+- [Full annotated pipeline](../../examples/pipeline.full.annotated.yml)
+- [Production-shaped pipeline](../../examples/pipeline.production.yml)

docs/integrations/seriatim.md

@@ -1,60 +1,62 @@
-# Integration: seriatim
+# Integration: Seriatim
 
 ## Purpose
-Define Narratio's adapter contract for merge, normalize, and trim subprocess invocations of Seriatim.
+Define the Seriatim adapter contract used by `merge`, `normalize`, `trim`, and `render`.
 
-## Inputs and Outputs
-Inputs:
-- `MergeRequest`: raw/normalized transcript inputs, output path, optional report, speaker/autocorrect paths, logs/config
-- `NormalizeRequest`: input transcript, output path, schema, optional report, timeout/log/config
-- `TrimRequest`: input transcript, output path, keep selector, timeout/log/config
+## External Boundary
 
-Outputs:
-- `MergeResult`, `NormalizeResult`, `TrimResult` with output paths, logs/config paths, exit code, duration, binary provenance, and metadata.
+Narratio invokes Seriatim as a subprocess in these modes:
 
-## Boundaries
-Owns:
-- Validated deterministic CLI invocation construction
-- Optional env tuning propagation for merge
-- Invocation config file emission
-- JSON output validation
+- `seriatim merge`
+- `seriatim normalize`
+- `seriatim trim`
+- `seriatim render`
 
-Does not own:
-- Transcript input selection/promotion logic (stage-owned)
-- Bounds computation (scriptorium/trim-stage-owned)
+The configured timeout and parent cancellation bound each invocation. Internal
+runner composition is documented in
+[the adapter implementation guide](../internal/adapters.md).
 
-## Config Fields Used
-Via `pipeline.seriatim.*` mapped in app/stage wiring:
-- `binary`, `timeout`, `output_schema`, `coalesce_gap`, `report`
-- `env.overlap_word_run_gap`
-- `env.overlap_word_run_reorder_window`
-- `env.backchannel_max_duration`
-- `env.filler_max_duration`
+## Request/Result Contracts
+- `MergeRequest`/`MergeResult`: multi-input merge to base transcript, optional report.
+- `NormalizeRequest`/`NormalizeResult`: transcript normalization with explicit schema.
+- `TrimRequest`/`TrimResult`: transcript trimming with required keep selector.
+- `RenderRequest`/`RenderResult`: transcript-to-markdown rendering with explicit format and render booleans.
 
-## External Adapters Used
-- Shared subprocess helper (`internal/adapters/subprocess`).
+Results include output/log/config paths, timing, exit code, and metadata.
 
-## State and Manifest Behavior
-- No direct manifest writes.
-- Stage metadata consumes adapter result fields and preserves generated config/log references.
+## Validation and Failure Semantics
+Runner construction validates:
+- binary presence;
+- timeout > 0;
+- supported output schema (`seriatim-minimal|seriatim-intermediate|seriatim-full`);
+- non-negative coalesce gap.
 
-## Skip and Resume Behavior
-- Adapter has no skip/resume logic. Runner controls stage execution.
+Invocation fails on:
+- missing required request paths/inputs;
+- invalid normalize schema override;
+- unsupported render format;
+- subprocess failure;
+- invalid JSON outputs for merge/normalize/trim;
+- missing `segments` array for normalize/trim transcript outputs;
+- empty render output files.
 
-## Failure Behavior
-- Constructor fails for invalid binary/timeout/output-schema/coalesce-gap.
-- Merge fails on missing output path/inputs/report path (if enabled), subprocess errors, invalid merged output JSON, invalid report JSON.
-- Normalize fails on missing input/output, invalid schema, subprocess errors, invalid normalized output JSON shape, invalid report JSON.
-- Trim fails on missing input/output/keep selector, subprocess errors, invalid trimmed output JSON shape.
+When report paths are provided/enabled, report files must parse as JSON.
+Each Seriatim JSON or rendered-text result is limited to 64 MiB and must be a
+regular file without symlinked path components.
 
-## Tests to Inspect Before Changing
-- `internal/adapters/seriatim/subprocess_test.go`
-- `internal/adapters/seriatim/fake_test.go`
-- `internal/stage/merge_test.go`
-- `internal/stage/normalize_test.go`
-- `internal/stage/trim_test.go`
+## Deterministic Behavior
+- argument ordering is deterministic per command construction.
+- merge env overrides are explicit (`SERIATIM_*`) and only emitted when configured.
+- generated invocation YAML (`seriatim.generated.v1`) is emitted when requested.
+- adapter does not write manifests or choose stage inputs.
 
-## Architectural Invariants
-- Supported output schemas are limited to `seriatim-minimal`, `seriatim-intermediate`, `seriatim-full`.
-- Normalize/trim outputs must include `segments` arrays.
-- Merge/normalize/trim all route through deterministic subprocess invocation.
+## Configuration
+
+Operator-selected values are defined under `pipeline.seriatim.*` and
+`pipeline.render.*` in the
+[configuration reference](../config.md#pipeline).
+
+Maintained examples with Seriatim config:
+
+- [Full annotated pipeline](../../examples/pipeline.full.annotated.yml)
+- [Production-shaped pipeline](../../examples/pipeline.production.yml)

docs/integrations/whisperx.md

@@ -0,0 +1,71 @@
+# Integration: WhisperX
+
+## Purpose
+
+WhisperX transcribes each prepared speaker audio file for Narratio's
+`transcribe` stage. Narratio uses an HTTP boundary and installs each successful
+response as that speaker's raw transcript JSON.
+
+## HTTP Boundary
+
+Narratio sends an HTTP `POST` to the configured transcription URL using
+`multipart/form-data` with:
+
+- `file`: the audio file, retaining its base filename; and
+- `language`: the configured language string.
+
+The server must return a `2xx` response whose body is valid JSON. Narratio does
+not currently require a more specific response schema at this boundary.
+
+The transcription URL must be an absolute `http` or `https` URL. The audio body
+is streamed through a fresh multipart writer for every attempt, so its memory
+use is bounded by the transport buffer rather than by the complete audio file.
+WhisperX response acquisition is capped at 10 MiB.
+
+## Request And Result Contract
+
+Each adapter request identifies a speaker, a readable audio file, and the
+destination for the raw transcript. The HTTP request carries the audio and
+language; the speaker identifier remains Narratio orchestration metadata.
+
+On success, Narratio atomically writes the response body to the requested
+destination. The adapter result reports that logical output together with the
+attempt count, final HTTP status when available, elapsed duration, and adapter
+identity metadata. A failed or invalid response is not installed as the
+transcript output.
+
+## Retry, Timeout, And Cancellation
+
+- The configured timeout applies independently to each HTTP attempt.
+- `retries` means additional attempts after the first.
+- HTTP `429`, HTTP `5xx`, attempt timeouts, and network errors are retryable.
+- Other HTTP `4xx` responses and explicit cancellation are not retryable.
+- Narratio waits the configured retry delay between attempts and aborts that
+  wait when the parent context is canceled.
+
+## Validation And Failure Semantics
+
+Client construction rejects a missing or non-HTTP(S) absolute transcription URL,
+a missing language, a non-positive timeout, negative retries, or a negative
+retry delay. A request fails before transmission when its audio or output path
+is missing.
+
+Non-`2xx` status, transport failure, response-size overflow, invalid JSON, or
+failure to install the output causes the transcription to fail. Errors include
+attempt context, and the result retains attempts, final status when available,
+and elapsed duration for diagnostics.
+
+## Determinism And Concurrency
+
+Each audio request has stable multipart field names, and successful bytes are
+installed atomically. The transcribe stage may process speaker files in
+parallel, bounded by the configured concurrency. It records results in stable
+speaker order after all work completes; any speaker failure fails the stage.
+
+## Related Canonical Docs
+
+- [Configuration](../config.md#pipeline) defines the operator-selected
+  WhisperX URL, language, timeouts, retry policy, and concurrency.
+- [Adapter implementation](../internal/adapters.md) describes internal wiring.
+- [Transcribe stage](../internal/stage-transcribe.md) describes stage mechanics,
+  durable artifacts, and manifests.

docs/internal/README.md

@@ -1,28 +0,0 @@
-# Internal Documentation Index
-
-## Audience
-Developers and LLM coding agents changing Narratio internals.
-
-## Scope
-Implementation-accurate contracts for workspace/state, manifests, stages, artifact resolution, and adapter boundaries.
-
-## Component Docs
-- `adapters.md`: external adapter map, runtime wiring, and boundary ownership.
-- `storage.md`: remote storage backend contracts and object-store invariants.
-- `manifest.md`: session/run manifest schemas, lifecycle transitions, and persistence semantics.
-- `artifacts.md`: built-in artifact registry, runtime artifact catalog, and source-resolution behavior.
-- `workspace.md`: local state model, manifests, run-local layout, promotion, and cleanup invariants.
-- `stage-prepare.md`: input materialization and provenance capture.
-- `stage-transcribe.md`: WhisperX transcript generation.
-- `stage-merge.md`: Seriatim normalization + merge.
-- `stage-polish.md`: Audita transcript polishing.
-- `stage-normalize.md`: post-polish normalization.
-- `stage-trim.md`: bounds-driven transcript trimming.
-- `stage-analyze.md`: dependency-ordered Scriptorium artifact generation for selected configured artifacts.
-- `stage-archive.md`: archive upload and current-pointer publish contract.
-
-## External Integration Notes
-- `../integrations/README.md`: canonical location for external integration contracts (`audita.md`, `seriatim.md`, `scriptorium.md`).
-
-## Canonical Owner
-`docs/internal/` is the canonical home for implemented internals per `docs/documentation/policy.md`.

docs/internal/adapters.md

@@ -1,79 +1,121 @@
 # Internal: Adapters
 
 ## Purpose
-Describe the external adapter boundaries used by Narratio stages and app orchestration, including default runtime wiring.
 
-## Inputs and outputs
-Inputs:
-- Stage requests passed through adapter interfaces (for example transcription, merge/normalize/trim, polish, artifact generation, object-store operations, notifications).
-- Resolved config values used to construct default adapters.
+Explain the adapter interfaces and production composition used by application
+and stage orchestration. Externally observable protocols and formats belong in
+the [integration contracts](../integrations/).
 
-Outputs:
-- Adapter-specific result structs (paths, metadata, status/attempt info, duration/exit details).
-- Adapter errors returned to stage/app orchestration.
+## Adapter Boundaries
 
-## Boundaries
-Owns:
-- Transport/process/SDK details at system boundaries (`HTTP`, subprocess CLI invocation, AWS SDK calls).
-- Request/response contracts in `internal/adapters/*` packages.
+Narratio stage logic depends on adapter interfaces, not transport-specific details.
 
-Does not own:
-- Stage sequencing, skip/force/resume decisions.
-- Manifest transition logic.
-- Canonical workspace path policy.
+Primary adapters:
 
-## Config fields used
-Default wiring and adapter calls consume:
-- `pipeline.whisperx.*`
-- `pipeline.seriatim.*`
-- `pipeline.audita.*`
-- `pipeline.scriptorium.*`
-- `pipeline.storage.*` and `pipeline.archive.*` (object-store construction/gating)
-- `pipeline.notification.*` (sender boundary exists; placeholder behavior today)
-
-## External adapters used
-Runtime env boundary fields (`internal/stage.Env`):
 - `whisperx.Client`
 - `seriatim.Runner`
 - `audita.Runner`
 - `scriptorium.Runner`
+- `notarius.Runner`
 - `storage.ObjectStore`
 - `notify.Sender`
-- `analyzer.Runner`
 
-Current execution usage:
-- Actively used by implemented stages: `WhisperX`, `Seriatim`, `Audita`, `Scriptorium`, `ObjectStore`, `Notifier`.
-- Present but not used by implemented stage set: `Analyzer`, legacy `storage.Backend`.
+## Ownership
 
-Default construction in app runner:
-- Auto-constructed when not injected: WhisperX HTTP client, Seriatim subprocess runner, Audita subprocess runner, Scriptorium subprocess runner, object store (only when needed), and `notify.NoopSender`.
-- Callers can inject test/fake implementations through `app.RunOptions.Env`.
+Adapters own:
 
-## State and manifest behavior
-- Adapters do not directly mutate session/run manifests.
-- Stages and runner own manifest writes and stage status transitions.
-- Adapter outputs are persisted indirectly through stage result mapping (outputs/logs/generated configs/metadata).
+- HTTP/subprocess/SDK argument and transport details.
+- Backend-specific request/response mapping.
 
-## Skip and resume behavior
-- No adapter-level skip/resume semantics.
-- Skip/resume/force behavior is decided by app runner using manifest stage state.
+Adapters do not own:
 
-## Failure behavior
-- Adapter constructors validate config-derived values and fail early on invalid required inputs.
-- Adapter run-time failures are returned to stage code with boundary context and are recorded as stage failures by runner logic.
-- Subprocess adapters preserve stdout/stderr and generated-config paths to aid diagnosis.
+- stage ordering/skip/force logic;
+- manifest transitions;
+- canonical path policy.
 
-## Tests to inspect before changing
+## Default Wiring
+
+The application composes default adapters per invocation when they were not
+injected through the stage environment, and only when the selected execution
+plan needs them:
+
+- WhisperX HTTP client for `transcribe`.
+- Seriatim subprocess runner for `merge`, `normalize`, `trim`, or `render`.
+- Audita subprocess runner for `polish`.
+- Scriptorium subprocess runner for `trim` or `analyze`.
+- Notarius subprocess runner for `extract` when extraction is enabled.
+- Noop notifier (`notify.NoopSender`) for `notify`.
+- Object store only when required by selected stages/config.
+
+Remote publish locks are loaded only for a selected, enabled publish that
+uploads a run. Shared session lifecycle setup still applies to every selected
+range, but an unselected integration is neither initialized nor validated by
+application-owned composition. Constructor, clock, randomness, remote-lock,
+and post-publish deletion boundaries are scoped to the invocation; stages still
+receive their collaborators through the stage environment. Each selected stage
+retains its own fail-fast configuration and input validation.
+
+`session plan` is outside production adapter composition. It performs
+resume validation and models selected transitions against cloned manifest
+state without constructing or invoking stage-execution adapters. The shared
+command configuration loader may still use object storage to retrieve a missing
+remote session file before planning begins.
+
+Notarius is composed only when extraction is enabled; the extract stage owns
+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`.
+It also serializes an effective resume request as `--resume` and a nonempty
+validated chunk mode as `--chunk_cache <mode>`. The extract stage, not the
+adapter, resolves force precedence before constructing the request.
+Its request may also carry one already-resolved opaque ConfigKit secret
+reference. Only the Notarius adapter reads that value, rejects an unresolved or
+empty programmatic reference, and maps the exact configured name/value into the
+shared subprocess override and sensitive-name fields. It never rereads the
+parent environment. A nil reference preserves the previous invocation.
+
+Application-owned object-store construction loads configured filesystem
+secrets before invoking the invocation's storage factory. Production commands
+use the concrete storage adapter constructor; focused tests can supply an
+in-memory backend without changing package state.
+
+## Failure Semantics
+
+- Constructor errors fail stage execution setup early.
+- Runtime adapter errors propagate to stage code and then manifest failure handling.
+- Subprocess adapters persist stage logs/generated configs through stage-managed paths.
+- Shared subprocess execution keeps private lifecycle mechanics separate from
+  Narratio's environment, diagnostics, redaction, and error policy. It starts
+  an owned process group on Linux and macOS. Every terminal path disposes of
+  that owned tree before returning. After a natural leader exit, the runner checks
+  for remaining group members and uses bounded graceful then forceful termination.
+  Cancellation, deadlines, and
+  diagnostic limits use the same terminal disposal path without losing their
+  original result classification. Child environments contain only the execution
+  baseline and adapter-specified values; configured credentials are resolved
+  once by ConfigKit and passed explicitly as sensitive values. Adapters do not
+  re-read their named environment references. Stdout and stderr are redacted while streaming into separate
+  8 MiB diagnostic captures; a bounded wait closes a stream retained by a
+  departed leader's descendant. Unsupported platforms reject owned command
+  execution.
+
+## Implementation And Tests
+
+- Composition: `internal/app/runner_composition.go`,
+  `internal/app/runner_dependencies.go`, `internal/app/object_store.go`
+- Shared subprocess mechanics: `internal/adapters/subprocess`
+- Focused adapters: `internal/adapters/{whisperx,seriatim,audita,scriptorium,notarius,storage,notify}`
 - `internal/adapters/whisperx/http_test.go`
 - `internal/adapters/seriatim/subprocess_test.go`
 - `internal/adapters/audita/subprocess_test.go`
 - `internal/adapters/scriptorium/subprocess_test.go`
+- `internal/adapters/notarius/subprocess_test.go`
 - `internal/adapters/storage/*_test.go`
-- `internal/adapters/notify/fake_test.go`
-- `internal/adapters/analyzer/fake_test.go`
 - `internal/app/runner_test.go`
 
-## Architectural invariants
-- Stage code depends on adapter interfaces, not transport-specific implementation types.
-- External SDK-specific types remain inside adapter implementations.
-- Default app wiring must remain deterministic and overrideable via injected env dependencies.
+See the [WhisperX](../integrations/whisperx.md),
+[Seriatim](../integrations/seriatim.md), [Audita](../integrations/audita.md),
+[Scriptorium](../integrations/scriptorium.md), and
+[Notarius](../integrations/notarius.md) contracts before changing an
+externally visible boundary. Operator-selected values belong in
+[Configuration](../config.md).

docs/internal/artifacts.md

@@ -1,87 +1,302 @@
 # Internal: Artifacts
 
 ## Purpose
-Define Narratio's artifact identity and resolution model for built-in transcript/bounds artifacts and runtime-configured analyze artifacts.
 
-## Inputs and outputs
-Inputs:
-- artifact sources from config/runtime (`pipeline.scriptorium.artifacts.*.inputs.*.source`)
-- session paths and optional session manifest stage outputs
-- runtime artifact catalog state for configured artifact sources
+Explain the artifact registry, runtime catalog, resolver, previous-input
+requirements, and shared remote current-state mechanics implemented by
+`internal/artifacts`. Configuration fields that accept source IDs belong in
+[Configuration](../config.md); physical placement belongs in
+[Operations](../operations.md).
 
-Outputs:
-- resolved local artifact path and provenance (`ResolvedSessionArtifact`)
-- runtime catalog entries for planned/executable/available artifacts
-- validation errors for unsupported, missing, or invalid artifact sources
+## Built-in Source IDs
 
-## Boundaries
-Owns:
-- built-in artifact registry and content validation rules
-- runtime artifact catalog for configured artifact source IDs
-- source resolution behavior for built-in and configured artifact sources
+The internal registry recognizes these stable built-in source IDs:
 
-Does not own:
-- artifact generation (stages produce files)
-- manifest transition policy
-- archive promotion behavior
+- `narratio.transcript.base`
+- `narratio.transcript.polished`
+- `narratio.transcript.final`
+- `narratio.transcript.final_trimmed`
+- `narratio.transcript.final_markdown`
+- `narratio.transcript.final_trimmed_markdown`
+- `narratio.bounds.session`
 
-## Config fields used
-- `pipeline.scriptorium.artifacts.<name>.enabled`
-- `pipeline.scriptorium.artifacts.<name>.output_path`
-- `pipeline.scriptorium.artifacts.<name>.inputs.<key>.source`
+Registry entries bind each ID to its producer, output kind, and content
+validator. The focused stage documents own their input/output flow;
+[Configuration](../config.md) owns where operators may select these IDs.
 
-## External adapters used
-- none
+## Configured, Extraction, And Previous-Session Sources
 
-## State and manifest behavior
-Built-in registry entries:
+- configured source ID format: `narratio.artifact.<artifact_key>`
+- extraction source ID format: `narratio.extraction.<output_key>`
+- previous-session source ID format: `narratio.previous_session.artifact.<artifact_key>`
 
-| Artifact ID | Canonical file | Producer stage | Output kind |
-| --- | --- | --- | --- |
-| `narratio.transcript.merged` | `transcripts/merged.json` | `merge` | `transcript_merged` |
-| `narratio.transcript.polished` | `transcripts/processed.json` | `polish` | `transcript_processed` |
-| `narratio.transcript.full` | `transcripts/normalized.json` | `normalize` | `transcript_normalized` |
-| `narratio.transcript.trimmed` | `transcripts/trimmed.json` | `trim` | `transcript_trimmed` |
-| `narratio.bounds.session` | `artifacts/session_bounds.json` | `trim` | `session_bounds` |
+All formats are validated by strict source-policy rules. Configured artifact and
+extraction keys use `^[a-z][a-z0-9_]*$`; source parsers never normalize an
+unrecognized token into a valid source. Extraction sources are registered only
+from `pipeline.notarius.outputs`; the Notarius index has no selectable source
+ID.
 
-Runtime catalog entries include built-ins and configured `narratio.artifact.<name>` sources.
+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. Canonical party mode preserves the
+party source bytes in the party record and supplies the players record from the
+deterministic `derived_from_party` projection; both remain ordinary prepared
+source IDs for consumers.
 
-Catalog states:
-- `planned`: source is registered and known for this run
-- `executable`: configured artifact is selected for analyze execution
-- `available`: artifact has a usable file path (generated this run or reused from disk)
+## Runtime Catalog
 
-Resolution behavior:
-- built-in sources resolve via manifest producer outputs first, then canonical fallback path
-- configured `narratio.artifact.<name>` sources resolve through runtime catalog availability
-- configured source lookup requires catalog context
+`ArtifactCatalog` tracks:
+
+- `planned`: source registered for run context;
+- `executable`: included in the effective analyze artifact set;
+- `available`: the source's canonical evidence owner validates its current
+  manifest record and durable bytes;
+- `provenance`: availability source.
+
+Configured definitions are always registered. Without an explicit selection,
+the effective analyze set contains enabled definitions. With `--artifacts`, the
+exact named configured definitions become the effective set for that invocation,
+regardless of their `enabled` value. The effective-set resolver itself does not
+expand dependencies. Configuration has already materialized the sorted union of
+explicit ordering edges and configured-artifact input edges, and the analyze
+work planner closes targets over that one concrete prerequisite graph.
+Availability is separate from executability. Configuration may normalize a
+family selection into its concrete generated members before this resolver runs.
+The effective set retains optional family
+and character origin metadata, but its keys, catalog sources, and runtime
+lookups remain concrete configured-artifact identities.
+Family publish policies are likewise expanded into ordinary configured-source
+publish rules during configuration resolution.
+Configured outputs, including non-executable prerequisites, become available
+only when the versioned analyze state identifies a current result whose source,
+contract, canonical configured path, size, and checksum match a confined
+no-follow regular file. An incidental canonical file is unavailable, and a
+manifest with an unsupported aggregate-only representation is rejected before
+catalog construction.
+Extraction entries are registered from configuration and become available only
+after compatible extraction evidence is hydrated.
+
+During an analyze invocation, a newly validated and atomically materialized
+configured output is marked available with its producer run ID, contract,
+checksum, and size. Later scheduled dependents therefore observe the same
+semantic identity whether their prerequisite was reused from current manifest
+evidence or produced earlier in the invocation.
+
+Current provenance values:
 
-Configured artifact provenance values:
 - `generated.current_analyze_run`
-- `filesystem.disabled_artifact_output`
+- `manifest.current_analyze_artifact`
+- `manifest.inputs.previous_cache`
+- `current_session.previous_cache`
 
-Content validation:
-- transcript built-ins: JSON with top-level `segments` array
-- bounds built-in: valid JSON
-- configured artifacts: non-empty text file
+## Resolution Rules
 
-## Skip and resume behavior
-- resolver and catalog have no direct skip/resume decisions
-- stage/runner skip-resume behavior consumes catalog/resolver results
+Built-ins:
 
-## Failure behavior
-- unsupported source -> source validation error
-- known source unavailable -> `ErrSessionArtifactNotFound`
-- configured source without catalog -> resolution error
-- resolved file with invalid content -> validation error
+- resolve only from the current manifest's succeeded registered producer;
+- require exactly one output with the registered source ID and output kind, a
+  safe session-rooted path, producer run ID, canonical checksum, and valid
+  content; and
+- verify the registered checksum against the durable bytes. Incidental files,
+  canonical filenames, duplicate outputs, failed/stale producer records, and
+  malformed evidence are unavailable.
 
-## Tests to inspect before changing
-- `internal/artifacts/artifact_resolver_test.go`
-- `internal/artifacts/catalog_test.go`
-- `internal/stage/analyze_test.go`
-- `internal/config/scriptorium_test.go`
+Configured sources (`narratio.artifact.*`):
 
-## Architectural invariants
-- built-in IDs are static and registry-backed
-- configured artifact IDs are runtime-derived (`narratio.artifact.<name>`) and catalog-backed
-- built-in/source resolution remains deterministic and validation-gated
+- resolve only through runtime catalog availability;
+- use the shared typed analyze-evidence inspection in
+  `analyze_evidence.go` for prior current-session results;
+- require the supported analyze-state and fingerprint versions, a `current`
+  record for the exact configured key and source ID, a complete contract, the
+  configured canonical relative path, positive stored size, and stored
+  checksum matching bytes read from a confined no-follow regular file; and
+- treat non-current statuses, malformed records, removed keys,
+  unsafe or missing files, and size/checksum mismatches as unavailable without
+  rewriting manifest state. Catalog construction iterates current
+  configuration, so removed or renamed records are not advertised.
+
+`narratio.member_artifact.*` is not a runtime source family. Configuration
+resolution accepts it only in an artifact-family declaration and rewrites it
+to the corresponding configured source before this catalog is built.
+
+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`;
+- require a current successful extract record with the exact configured source,
+  compatible contract and Notarius provenance, a confined regular durable
+  payload, matching checksum, and the current resolved trimmed-transcript
+  identity;
+- remain unavailable unless catalog hydration receives valid evidence. Resume
+  treats absent or obsolete evidence as a rerun decision and unsafe evidence as
+  an error; and
+- are never inferred by scanning the Notarius bundle directory.
+
+Previous-session sources (`narratio.previous_session.artifact.*`):
+
+- resolve only from one matching `previous_artifact` input record in the
+  current manifest, including its exact source ID and checksum;
+- are hydrated only from the unique `published_output` declaration for their
+  canonical source in the selected remote commit; and
+- never infer a path from a previous manifest, current configuration, basename,
+  or existing cache file.
+
+Source absence is evaluated by the consuming artifact input. An optional input
+is omitted from that invocation; a required input fails resolution. This is
+separate from a stage's lifecycle outcome.
+
+Validation by content type:
+
+- transcript JSON built-ins: JSON with top-level `segments` array;
+- transcript Markdown built-ins: non-empty text file;
+- bounds built-in: valid JSON;
+- configured/previous-session artifact files: non-empty text file.
+
+## Previous Requirement Collection
+
+`CollectPreviousArtifactRequirements`:
+
+- scans the effective configured artifact set;
+- extracts only canonical previous-session sources;
+- deduplicates by artifact key;
+- merges required and optional references (required wins);
+- returns deterministic ordering and source locations.
+
+## Current-State Helpers
+
+Artifacts package owns shared remote current-state loading mechanics used by
+restore, status and validation checks, and previous-cache planning.
+
+The selected session manifest is accepted only with
+`schema_version: narratio.session-manifest.v1` and complete stage identity.
+An unsupported local or downloaded manifest must be replaced by regeneration,
+verified restore, or republication; artifact resolution never fills in missing
+authority markers.
+
+For a new-protocol current state, the pointer-selected immutable commit is the
+complete restore authority. Callers receive its declared object identities and
+must not supplement them by listing mutable session prefixes.
+
+A `published_output` declaration must use a canonical publish-compatible source
+ID and an exact `runs/{run_id}/published/{destination}` key in the same session.
+Only this declaration type may refer to an earlier run; other declared objects
+remain confined to the selected commit's run.
+
+The reader opens each small control object directly and enforces owner-specific
+limits before decoding: 64 KiB for the mutable commit pointer, 4 MiB for the
+immutable commit manifest, and 8 MiB for the selected session manifest. These
+are exposed as `MaxCurrentCommitPointerBytes`,
+`MaxRemoteCommitManifestBytes`, and `MaxRemoteSessionManifestBytes`.
+
+Each read uses the generation and size metadata returned with its opened body.
+Actual bytes remain subject to a limit-plus-one read even if size metadata is
+absent or inaccurate. Immutable selections then retain their declared-size,
+checksum, generation, and identity checks. No current-state control object is
+downloaded through a temporary file. Artifact and previous-session downloads
+validate their complete sibling temporary file against available committed
+identity before replacing a canonical local path.
+
+Core helpers:
+
+- `LoadCurrentState`
+- `ValidateCurrentStateIdentity`
+- `RemoteCommitManifest` and `CurrentCommitPointer`
+
+Typed missing-state error:
+
+- `CurrentCommitPointerMissingError` (`ErrCurrentCommitPointerMissing`)
+
+Identity validation supports caller-provided expectations:
+
+- expected campaign;
+- expected session ID;
+- expected run ID, or pointer/manifest run-ID consistency check.
+
+Caller policy is intentionally outside artifacts helpers:
+
+- some callers fail on missing current state;
+- some callers downgrade missing state to status/findings;
+- some callers skip optional behavior when state is missing.
+
+## Remote Lock Objects
+
+The artifacts package defines the independent remote-lock payload and identity
+contract. Each canonical publish source maps to one object below the validated
+session `locks/` prefix; its filename is the lowercase SHA-256 digest of the
+exact source followed by `.lock`.
+
+Lock payloads are strict versioned JSON containing the canonical source, an
+optional reason, and a UTC creation time. Reads are bounded to
+`MaxRemoteLockObjectBytes` (64 KiB), reject unknown fields and trailing values,
+and verify that the payload source matches the key digest. Exact lookup reports
+presence explicitly, prefix listing validates every object and sorts by source,
+creation uses an absence precondition, forced replacement uses one observed
+generation, and removal is idempotent.
+
+## Key Path Helpers
+
+`internal/artifacts/paths.go` and S3-key helpers define canonical helpers for:
+
+- session/work/run paths;
+- previous-cache paths;
+- spool/cache paths;
+- S3 session/run/current-state key layout.
+
+New publication creates run-scoped immutable objects, including
+`runs/{run_id}/commit.json` and `runs/{run_id}/session-manifest.json`. The sole
+mutable selector is `current/commit-pointer.json`; readers verify its selected
+commit and declared object generations/checksums.
+
+A `published_output` declaration may identify its commit's run or an earlier
+immutable run in the same campaign/session namespace. The key parser validates
+that namespace, rejects mutable and malformed keys, and derives the originating
+run from the exact declaration. All other commit artifacts remain confined to
+the commit's own run prefix.
+
+Campaign, session, and Narratio run IDs are validated as portable opaque
+segments at configuration and artifact boundaries before they can be used in a
+workspace or S3 namespace. Previous-artifact destinations remain typed,
+multi-segment relative paths and are confined beneath `previous/artifacts`; they
+are not treated as opaque identifiers.
+
+See [Workspace Internals](workspace.md) for how callers consume local helpers
+and [Operations](../operations.md#local-state-layout) for the authoritative
+physical layout.
+
+## Invariants
+
+- source ID formats are stable contracts;
+- artifact resolution is deterministic and manifest-aware;
+- extraction sources are available only from a compatible successful manifest
+  record;
+- previous-session source resolution in `analyze` is local-only;
+- remote current-state key construction remains centralized in artifacts helpers.
+
+## Implementation And Tests
+
+- Registry and resolution: `internal/artifacts/artifact_resolver.go`,
+  `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/prepared_input.go`
+- Current state: `internal/artifacts/current_state.go`,
+  `internal/artifacts/current_state_commit.go`,
+- Paths and keys: `internal/artifacts/paths.go`,
+  `internal/artifacts/s3_keys.go`
+- Previous requirements: `internal/artifacts/previous_requirements.go`
+- Tests: `internal/artifacts/artifact_resolver_test.go`,
+  `internal/artifacts/catalog_test.go`,
+  `internal/artifacts/extraction_catalog_test.go`,
+  `internal/artifacts/current_state_test.go`,
+  `internal/artifacts/paths_model_test.go`,
+  `internal/artifacts/previous_requirements_test.go`

docs/internal/command-restore.md

@@ -0,0 +1,127 @@
+# Internal: Command Restore
+
+## Purpose
+
+Explain the implemented restore discovery, planning, installation, and
+reporting flow in `internal/app`. User invocation belongs in
+[CLI](../cli.md#session-restore), and the operator recovery procedure and
+physical restore scope belong in
+[Operations](../operations.md#restore-workflow).
+
+Restore separates remote authority, local conflict policy, and filesystem
+mutation so each remains testable independently.
+
+The public command supplies production defaults to one private,
+invocation-scoped dependency value. Discovery, planning, and execution use that
+same value, so focused sequencing tests can replace one boundary without
+mutable package hooks.
+
+## Discovery Contract
+
+Discovery delegates current-state pointer and manifest loading to
+`internal/artifacts`, then validates the result against the resolved request:
+
+- campaign must match;
+- session ID must match.
+- run ID must match the pointer-selected committed run.
+
+Restore treats any missing or invalid remote current state as a command error.
+
+## Planning Contract
+
+Restore planner action kinds:
+
+- `download`;
+- `skip_same`;
+- `conflict`.
+
+Planner behavior:
+
+- a new-protocol restore uses only the selected commit's declared artifact set;
+  each action carries that artifact's immutable key, checksum, size, and
+  generation;
+- remote-to-local mapping is traversal-safe;
+- actions are sorted by local relative path and then remote key;
+- planning opens the selected session root and inspects every target by its
+  normalized session-relative path. Missing ancestors produce a missing target;
+  an ancestor or leaf symlink is a non-regular conflict and is never opened for
+  hashing;
+- force converts differing eligible regular files from conflicts to downloads;
+  directories, symlinks, and other non-regular targets remain conflicts.
+
+For a non-dry-run restore, planning/classification happens only after acquiring
+the session lock. Runner manifest/reuse checks acquire that same lock first.
+
+Previous-cache readiness is resolved through `previouscache.Resolve` for restore,
+prepare, status, and validation. Each requirement selects the unique
+`published_output` for its canonical source in the pointer-selected commit,
+then strips only that run's immutable `published/` prefix for its safe local
+cache path. It never probes candidate objects or derives paths from manifests,
+configuration, or basenames.
+
+## Execution Contract
+
+Execution order and safety:
+
+- non-manifest downloads happen before manifest install;
+- `manifest.json` installs last;
+- downloads use sibling temp files, validate the complete object, then use an
+  atomic rename;
+- manifest replacement is validated before rename;
+- each committed object is verified against its declared checksum, size, and
+  generation before installation;
+- installation reopens the selected session root, creates only validated
+  missing directory components with workspace modes, and rejects symlinked or
+  non-regular ancestors and leaves before replacement;
+- a committed manifest already verified during discovery is retained for the
+  matching restore action and revalidated before installation, avoiding a
+  second body transfer;
+- failed installs do not roll back files already written in the same execution.
+- a durable `.restore-incomplete.json` marker is written before installation.
+  It blocks runners until a restore retry completes all verified installs and
+  the local manifest replacement, at which point it is removed.
+- restored manifest local references are rebased beneath the selected local
+  session root. Unsafe relative references and producer-machine absolute paths
+  outside the manifest's producer session root are rejected; producer-local
+  spool paths and run-local diagnostic references are not restored as
+  authority. Cleanup remains ordinary restored stage state and is not reset or
+  synthesized by restore.
+
+Audio restore path:
+
+- uses `audio.MaterializeS3Audio`;
+- integrates spool and S3 audio cache paths;
+- reuses cached audio only when its opened regular file, content digest, and
+  identity sidecar all match the selected remote object version; otherwise it
+  refreshes through the validated download path.
+
+## Reporting Contract
+
+- dry-run mode prints a summary, performs no durable session writes, and may
+  read remote current-state or object-identity data to produce that summary;
+- execution mode persists the canonical restore report described in
+  [Operations](../operations.md#restore-workflow);
+- report includes plan counts, per-action status, and execution failures.
+
+## Invariants
+
+- restore uses committed remote current state as authority;
+- one restore or status inspection observes the single pointer-selected commit
+  loaded at discovery; later pointer changes cannot add objects or substitute a
+  different run into its plan;
+- a verified `current/commit-pointer.json` and its selected immutable commit
+  establish remote commitment; when absent, republish the session;
+- restore does not execute pipeline stages.
+
+## Implementation And Tests
+
+- Discovery: `internal/app/restore_discovery.go`
+- Planning: `internal/app/restore_plan.go`, `internal/previouscache`
+- Execution: `internal/app/restore_execute.go`
+- Reporting and command coordination: `internal/app/restore_report.go`,
+  `internal/app/restore.go`
+- Tests: `internal/app/restore_discovery_test.go`,
+  `internal/app/restore_plan_test.go`,
+  `internal/app/restore_execution_test.go`,
+  `internal/app/restore_recovery_test.go`,
+  `internal/app/restore_workflow_test.go`

docs/internal/configuration.md

@@ -0,0 +1,215 @@
+# Configuration Internals
+
+User-visible fields, defaults, and selection behavior belong in the
+[Configuration Reference](../config.md). This document describes the internal
+pipeline-loading boundary implemented by `internal/config`.
+
+## Pipeline Loading
+
+`LoadPipeline` assembles and validates a pipeline in this order:
+
+1. Give ConfigKit a fresh typed `PipelineConfig` default value, the root file,
+   enabled imports, and the caller's profile selection. Omitted, empty, and
+   exact `default` selections use the base; named profiles use the fixed
+   `profiles/<name>.yml` convention.
+2. ConfigKit parses the root and declared imports, additively merges base
+   sources, applies only the selected overlay, and strictly decodes the result.
+3. The definition resolver applies recorded entry-level and inherited defaults,
+   runs deterministic domain normalization, records derived publish destinations,
+   and resolves ordinary paths relative to the root pipeline file.
+4. The definition validator performs read-only checks that require only the
+   pipeline file. Checks requiring canonical-party family expansion remain at
+   the existing explicit pipeline/campaign resolution boundary.
+5. Narratio inspects public ConfigKit metadata to reject artifact and family keys
+   declared by multiple base files, adapts source ownership records, attaches
+   runtime-only state, and computes the normalized effective digest.
+
+This ordering preserves monolithic configuration behavior. Moving a field to
+an imported fragment changes its source ownership, not its path base, default,
+or schema semantics.
+
+## Loaded Context Resolution
+
+`LoadedPipelineCampaign` carries one already composed pipeline and its selected
+campaign into session resolution. `LoadSessionWithPipelineCampaignOptions`
+loads a local session against that context, while
+`ResolveLoadedPipelineCampaign` also accepts an already loaded remote session
+or no session while a caller retrieves one. Compatibility loaders route through
+these functions after their initial pipeline and campaign reads.
+
+Application commands own pipeline and campaign discovery, campaign-file versus
+registry selection, and the corresponding mutual-exclusion rules. Once they
+have a `LoadedPipelineCampaign`, local session discovery and remote-session
+download retain that exact pipeline object and its private provenance. Removing
+a temporary downloaded session file therefore cannot invalidate the resolved
+pipeline or campaign context.
+
+Campaign and session files use independent ConfigKit definitions with imports
+and profiles disabled. Campaign files normally load directly from their source;
+session files are first read through the 8 MiB bounded-read boundary because the
+application must reject unresolved template placeholders before passing an exact
+byte snapshot to ConfigKit. Local and remotely downloaded session bytes then use
+the same typed loader and retain the existing post-load identity expectations,
+stable-input precedence, and source-relative path semantics.
+
+The application also has a separate read-only inspection resolver for `config
+validate`, `config show`, `config sources`, and `config artifacts`. It uses the same production root/profile and
+campaign selection functions, but never routes through session discovery,
+remote-session download, adapter composition, workspace
+initialization, manifest access, or cleanup. A pipeline with retained artifact
+family declarations must resolve its selected campaign before ordinary pipeline
+validation, which expands its canonical-party members and generated publish
+rules. A pipeline without those declarations may be validated by itself.
+Secret-directory bootstrap remains invocation-scoped and happens before the
+ordinary ConfigKit load because explicit typed references must resolve even for
+inspection.
+
+`MarshalEffectivePipeline` is the configuration-owned projection for `config
+show`. It serializes one explicit typed safe projection with the existing YAML
+encoder. The projection has no slots for resolution-only artifact family
+declarations or private provenance. The result has one trailing newline;
+commands do not marshal runtime objects directly.
+
+`EffectivePipelineSources` and `EffectiveCampaignSources` provide the separate
+safe provenance projection for `config sources`. Pipeline ownership begins with
+the complete logical field paths projected from the schema and classifies
+each contributor as root, import, profile, or centralized default. The
+projection replaces generated concrete member paths with paired family and
+canonical-party records, and does the same for generated publish rules.
+Campaign records identify campaign-owned fields and party inputs; canonical
+derived players point to the party source. The application command only joins these sorted
+records with selection metadata and never reparses configuration files.
+
+`EffectiveArtifactCatalog` projects the same finalized concrete artifact map for
+`config artifacts`. It derives source identity from each map key, carries sorted
+effective dependencies, aggregates ConfigKit definition contributors, and adds
+family/character/party provenance for generated members. It does not inspect
+files named after artifacts or infer another runtime graph.
+
+`config diff` uses a thin paired loader that performs two independent ConfigKit
+loads. When campaign
+resolution is needed, the command loads one selected campaign and party and
+expands both effective pipelines from that same party value. The configuration
+owner projects each normalized effective mapping directly from that same typed
+projection into sorted logical paths using JSON number preservation;
+mapping leaves are compared individually while sequence values remain atomic.
+Values are compact deterministic JSON representations for command output, not
+raw YAML fragments, ownership records, or secret material. A differing digest
+with no projected difference is treated as an internal consistency error.
+
+Campaign context construction reads the campaign-owned party source through
+`ParseParty`. The required canonical party retains its raw bytes and normalized
+roster in runtime-only `ResolvedParty` provenance. Canonical resolution creates
+a deterministic `derived_from_party` players projection. The party is the only
+configured roster authority; player and session-party fields are unsupported.
+
+## Canonical Party Domain
+
+`ParseParty` is the package-owned boundary for parsing a party source. Its
+single-source ConfigKit definition disables imports and profiles, requires
+`schema_version` through `VersionRule`, and strictly decodes the
+character-keyed typed schema before applying Narratio's party-domain checks.
+Successful metadata coordinates recover authored character-map order without a
+second YAML parse; class and alias slice order comes directly from typed decode.
+The canonical value retains a separate exact byte copy of its source so
+consumers can materialize the authored party document without reserializing it.
+Its `PlayersYAML` method deterministically derives the ID-sorted, versioned
+players-only projection.
+
+An unversioned source is rejected before resolution, family expansion, or
+prepare-stage materialization.
+
+## Validation Ownership
+
+Configuration validation remains within `internal/config`, with the public
+entry points and pipeline-domain sequencing separated from the private owners
+for core pipeline/session rules, external adapters, publish/storage, Notarius,
+Scriptorium, and shared scalar/path checks. These are package-local ownership
+boundaries rather than extension points or a general validation framework.
+
+Validation is read-only, fails fast, and does not define which of several
+independent invalid fields is reported first. Map-backed declarations are
+nevertheless traversed deterministically. Reusable domain normalization is an
+explicit preceding operation for both loaded and programmatically constructed
+pipelines. Notarius normalization commits canonical scalar, reference, and output
+values only after the complete normalization succeeds; its validator then checks
+that candidate without changing it. Scriptorium validates artifact declarations
+and outputs, dependencies and inputs, variables, referenced outputs, and the final
+dependency graph in deterministic artifact order.
+
+Diagnostics identify the relevant semantic field. Merge conflicts also
+retain every claiming source needed to correct an additive ownership conflict.
+Complete prose, punctuation, formatting, and private validation choreography are
+not compatibility contracts.
+
+## Diagnostics And Runtime Metadata
+
+Syntax, duplicate-key, merge, profile, and schema failures include the
+relevant source name and full field path. Additive conflicts report every
+claiming source so operators can repair the split without repeatedly
+rediscovering additional conflicts.
+
+The loaded pipeline retains private runtime metadata for the absolute root
+path, ordered imports, selected profile name and selection source, selected
+overlay, original ConfigKit metadata and source snapshots, effective digest,
+and leaf ownership. Base
+leaves retain their root/import owners, replaced leaves belong to the selected
+overlay, and centrally supplied values use the synthetic `default` owner. This
+metadata does not participate in YAML decoding or alter the public
+configuration model.
+
+The effective digest is SHA-256 over a versioned deterministic JSON encoding of
+the same typed safe projection used by show and diff. Runtime Notarius paths remain absolute for
+execution, but the digest substitutes their normalized logical values captured
+before root-relative resolution, so relocating an equivalent configuration
+bundle does not change provenance. Because ConfigKit and resolution metadata
+are private, the digest excludes source layout, profile name, and ownership.
+Configuration stores credentials as ConfigKit typed references. A successful
+load resolves their values inside the opaque typed boundary, while this safe
+projection serializes only `EnvName()` identities. Credential-value changes are
+therefore never hashed; reference-name changes remain ordinary provenance.
+The optional Notarius credential follows the same path even for disabled or
+resumable extraction; normalization copies the opaque reference without reading
+or resolving it again. Direct YAML serialization has a configuration-owned safe
+projection so only the reference name can leave this boundary.
+`recomputePipelineEffectiveDigest` is the single package-owned refresh point
+for later runtime expansion.
+
+## Test Surfaces
+
+`pipeline_configkit_test.go` exercises real imports and fixed-path profiles,
+base selection, unselected-overlay isolation, source attribution, and Narratio's
+unique artifact/family base-declaration rule. Existing focused configuration
+tests protect defaults, explicit-value semantics, strict decoding, validation,
+metadata, and root-relative path behavior. Application configuration-loader tests protect the
+single-read boundary by changing the pipeline file after its initial load and
+confirming local session resolution retains the original pipeline. Other
+configuration tests continue to protect defaults and validation after assembly.
+`party_test.go` protects the versioned typed party schema, domain invariants,
+authored character order, retained bytes, and deterministic players projection
+without involving campaign or runtime wiring.
+`party_resolution_test.go` protects campaign-owned party loading, canonical
+input restrictions, source provenance, and virtual players input selection.
+
+## Artifact Family Resolution
+
+Pipeline loading retains `scriptorium.artifact_families` as a resolution-only
+declaration. Once campaign party resolution establishes a canonical roster,
+configuration expands families in sorted family-key and character-ID order
+into ordinary `ScriptoriumArtifactConfig` values. The expansion owns the narrow
+`{character_id}` output substitution, closed member-variable selectors, key and
+output collision checks, and the runtime-only family-origin catalog. It then
+removes family declarations from `ScriptoriumConfig`, runs ordinary Scriptorium
+validation, and refreshes the effective pipeline digest. Stages and adapters
+therefore receive only concrete artifact maps.
+
+The catalog retains sorted family member keys plus family/character/source
+origins and the typed dependency/publish declarations for their later owners.
+`member_dependencies` add corresponding ordinary concrete dependencies, while
+the family-only `narratio.member_artifact.<family>` input form is rewritten to
+the matching ordinary configured-artifact source. The catalog records those
+resolved dependency and input identities with their declaring family and party
+member. No member-artifact source is registered as a runtime policy source.
+An enabled family publish declaration expands to ordinary configured-artifact
+publish rules before the existing publish and lock validators run. Runtime
+publication consequently receives no family wildcard or special matcher.

docs/internal/fileops.md

@@ -0,0 +1,55 @@
+# Internal: File Operations
+
+`internal/fileops` owns the narrow mechanics for atomically visible replacement of one
+byte file. Callers keep ownership of serialization, validation, cancellation,
+and destination-directory policy.
+
+## Destination Paths
+
+Ordinary workspace replacement uses standard operating-system path semantics.
+Callers with a root-scoped safety contract own that validation at their boundary.
+
+Remote object acquisition is owned by its domain caller. The caller writes a
+sibling temporary file, validates the complete result, and passes that file to
+`InstallSiblingTempFile` only when it is ready to become canonical. Callers own
+remote object selection, validation, conflict handling, and temporary-file
+cleanup.
+
+Directory bundles are not promoted by `internal/fileops`; extraction owns its
+validated Notarius bundle rename.
+
+## Cleanup Contract
+
+`RemoveAllUnderRoot` accepts an explicit root and a proper descendant, opens
+that root with `os.OpenRoot`, and removes the normalized root-relative target
+with `Root.RemoveAll`. It rejects root, traversal, and out-of-root targets; a
+missing target is successful. `RemoveFileUnderRoot` additionally requires an
+existing leaf to be regular. Command and post-publish policy remains owned by
+`internal/app`.
+
+## Bounded Reads
+
+`ReadFileBounded` opens a normal path and reads at most its caller-supplied
+limit. Credential mode policy and environment precedence remain owned by
+`internal/app`.
+
+## Replacement Contract
+
+`ReplaceFileAtomic` requires an existing destination directory. It creates a
+sibling temporary file, writes the complete byte sequence, applies the
+caller-supplied mode, closes the file, runs an optional pre-rename check, and
+replaces the destination with a rename.
+
+The pre-rename check is the last point at which a caller can cancel without
+installing a new destination. A failure before the rename leaves the old
+destination unchanged and removes the temporary file. Successful replacement
+provides atomic visibility; it makes no crash- or power-loss durability claim.
+
+Replacement follows the operating system's same-filesystem rename semantics.
+If a platform cannot replace an existing destination, the operation returns an
+error and never removes the old file as an emulation step.
+
+`WriteFileAtomic` and the copy helpers create the destination parent with the
+repository's workspace permissions. `InstallSiblingTempFile` requires the
+caller to provide an existing temporary file in the existing destination
+directory.

docs/internal/manifest.md

@@ -1,81 +1,315 @@
 # Internal: Manifest
 
 ## Purpose
-Describe Narratio's durable execution state model for session-level and run-level manifests, including lifecycle transitions and persistence behavior.
 
-## Inputs and outputs
-Inputs:
-- Session identity and run identity from app orchestration.
-- Stage transition events and stage result payloads.
+Explain the session-progress model implemented by `internal/manifest`. Physical
+manifest placement belongs in
+[Operations](../operations.md#local-state-layout).
 
-Outputs:
-- Session manifest at `{workspace.root}/work/{campaign}/{session_id}/manifest.json`.
-- Run manifest at `{workspace.root}/work/{campaign}/{session_id}/runs/{run_id}/manifest.json`.
+## Session Manifest
 
-## Boundaries
-Owns:
-- Manifest schemas (`Manifest`, `RunManifest`, stage records, error records, input/artifact records).
-- Stage status/action transition methods.
-- Persistent store contract (`manifest.Store`) and local JSON store implementation.
+`manifest.Manifest` records:
 
-Does not own:
-- Stage implementation details.
-- Path construction policy outside manifest file persistence calls.
-- CLI command behavior.
+- required `schema_version: narratio.session-manifest.v1`
+- identity (`session_id`, `campaign`, `run_id`)
+- local path metadata (`local_workdir`, `local_spool_dir`)
+- remote identity metadata (`s3_bucket`, `s3_session_prefix`, `s3_run_prefix`)
+- `inputs` records
+- durable `artifacts` records
+- per-stage `stages` map, including the ordinary cleanup stage record
 
-## Config fields used
-Manifest package itself does not read config directly.
+Session, campaign, and run identities in local and downloaded manifests must be
+portable opaque segments. Unsafe legacy identities are rejected with migration
+guidance rather than being normalized into a different workspace or remote
+namespace.
 
-Manifest identity fields are populated by app/stage orchestration from:
-- `session.session_id`
-- `session.campaign`
-- `pipeline.workspace.root`
-- `pipeline.storage.s3.*` (when archive/S3 identity is set)
+Decoding is strict at every typed manifest field. Unknown fields are rejected;
+the schema version remains `narratio.session-manifest.v1` and there is no
+compatibility reader that silently drops retired state. Cleanup progress uses
+only the cleanup entry in `stages`.
 
-## External adapters used
-- No external service adapters.
-- Uses local filesystem for persistence via `manifest.LocalStore`.
+Every persisted session manifest has a non-nil `stages` map. Each entry is
+non-nil and its embedded `name` exactly matches its map key; loading never
+invents either marker. A missing or unsupported schema version, or incomplete
+stage identity, is unsupported local state: move it aside and regenerate it,
+or restore a verified current committed snapshot when that is authoritative.
 
-## State and manifest behavior
-Session manifest model:
-- Tracks durable per-session stage state and provenance (`pending`, `running`, `succeeded`, `failed`, `skipped`, `stale`, `interrupted`).
-- Stores resolved inputs, durable artifacts, stage logs/config refs, and stage metadata.
+Prepare records independent `party` and `players` input checksums. In canonical
+party mode, the party record retains its campaign source identity while the
+players record uses `derived_from_party`; raw roster content is never embedded
+in manifest metadata. Both records remain the durable authority for consumers
+of their prepared input source IDs.
 
-Run manifest model:
-- Tracks one invocation (`run_id`) with requested stages and force mode.
-- Tracks per-stage action (`run` or `skip`) and per-stage status.
-- Tracks overall run status (`running`, `succeeded`, `failed`).
+The model admits these stage states:
 
-Persistence behavior:
-- Load validates required identity/timestamp fields and normalizes maps/records.
-- Save updates `updated_at` and writes JSON atomically (temp file + rename).
-- Session and run manifests are saved incrementally before/after stage transitions.
+- `pending`
+- `running`
+- `succeeded`
+- `failed`
+- `skipped`
+- `stale`
+- `interrupted`
 
-Relationship during execution:
-- Runner updates both manifests for every stage transition.
-- Session manifest is the durable pipeline-progress ledger.
-- Run manifest is invocation history and audit record.
-- Analyze stage outputs are persisted as `kind=scriptorium_artifact` with `source_id=narratio.artifact.<name>` for configured artifact identity.
+### Analyze-owned artifact state
 
-## Skip and resume behavior
-- Resume and skip decisions are based on session-manifest stage statuses.
-- `--force` reruns selected stages and marks downstream succeeded stages as `stale` in session manifest.
-- Run manifest records whether each stage was executed or skipped in that invocation.
+Every `analyze` stage record carries `analyze_state_version: 1` and an
+`analyze_artifacts` map keyed by normalized configured artifact key. The
+version is the authority marker: version 1 with no entries is a valid evaluated
+empty set. An absent or unsupported version is unsupported local state and is
+rejected rather than being treated as aggregate-only authority.
 
-## Failure behavior
-- Stage failure marks both manifests failed for that stage and records error messages/timestamps.
-- Save failures are returned immediately and fail the command.
-- Invalid/malformed manifest files fail load with explicit validation/decode errors.
+Each analyze artifact record has one disposition:
 
-## Tests to inspect before changing
-- `internal/manifest/manifest_test.go`
-- `internal/manifest/run_manifest_test.go`
-- `internal/manifest/store_test.go`
-- `internal/app/runner_test.go`
-- `internal/app/run_control_test.go`
-- `internal/app/resume_run_stage_test.go`
+- `current`: the configured artifact is available and carries a versioned
+  fingerprint plus a complete output record and separate output size;
+- `stale`: the recorded semantic identity is no longer current;
+- `missing`: no validated current result exists;
+- `failed`: the attempted work failed and carries a bounded diagnostic; or
+- `unselected`: the artifact was intentionally outside the evaluated set.
 
-## Architectural invariants
-- Session manifest is authoritative for stage progression across invocations.
-- Run manifest is invocation-scoped and never replaces session manifest as progress authority.
-- Manifest writes are atomic and deterministic (JSON + newline, temp rename pattern).
+Records bind their normalized key and dependencies, fingerprint contract when
+evaluated, canonical session-relative output identity when current, producing
+Narratio run, update time, and bounded non-secret Scriptorium provenance and
+diagnostic paths. A current output includes its configured source ID, contract,
+checksum, and positive byte size. Non-current records cannot carry an output,
+so an older file is not advertised through stale, missing, failed, or
+unselected state.
+
+Family-produced records additionally retain optional `family` and
+`character_id` provenance supplied by configuration resolution. These fields
+do not replace the concrete configured key or infer family membership from a
+name, so older records without them remain valid.
+
+The session-stage collection is the reconciled authority across invocations.
+These records remain analyze-owned data inside the fixed stage; they are not
+dynamic stages or generic subtasks.
+
+Analyze checkpoints one complete validated candidate collection after each
+successful artifact and before exposing that artifact to later work. It saves a
+detached manifest candidate and installs its version, collection, and updated
+timestamp into live state only after the store reports success. Aggregate stage
+outputs are ordinary result outputs rebuilt in configured-key order from current
+session records only.
+
+Successful incremental execution replaces only evaluated artifact records and
+preserves valid unrelated current records. Rebuilt outputs are compared by
+bytes and contract: an unchanged identity permits an unselected dependent with
+the same recomputed fingerprint to remain current, while a changed identity
+removes output authority from every unselected transitive dependent by marking
+it stale. A partial analyze invocation can therefore succeed while unrelated
+configured records remain stale. Existing canonical files never create current
+records without validated execution and a successful checkpoint.
+
+Aggregate analyze status is deliberately coarser than this collection. Resume
+validation may skip a succeeded aggregate record when the selected artifact
+closure is current even if unrelated records are stale. Conversely, a stale
+aggregate record may cross the ordinary runner boundary and perform zero
+Scriptorium calls when reconciliation proves every selected artifact current;
+ordinary successful stage completion then restores the aggregate status.
+
+On an artifact error, analyze installs a complete retry collection on the live
+manifest before returning. The active record is failed without output, current
+transitive dependents are stale, unrelated current records survive, and only
+earlier checkpointed completions remain current. The runner's ordinary failure
+path marks aggregate analyze failed, clears aggregate outputs, invalidates
+delivery dependents, and saves that collection. A terminal session-save failure
+is joined with the original adapter, validation, filesystem, cancellation, or
+checkpoint cause.
+
+If an artifact checkpoint fails, analyze rolls its working collection back to
+the last committed collection before constructing the active failed record.
+Newly materialized canonical bytes therefore remain incidental and cannot
+become current authority. A later ordinary run reconciles the durable records,
+reuses earlier current artifacts, and resumes with the failed or stale work.
+The same recovery applies after process interruption: the aggregate record may
+be non-successful, but every completed artifact checkpoint remains reusable.
+
+## Remote Commit Manifest
+
+`artifacts.RemoteCommitManifest` is a separate, versioned remote snapshot
+contract. It is not a serialized session manifest and contains no local
+post-publication assertion such as `current_pointer_written`. A remote commit
+identifies one campaign, session, and run and declares its immutable artifact
+set. Each artifact has a typed source, immutable destination key, SHA-256
+checksum, size, and storage generation.
+
+`current/commit-pointer.json` is the sole mutable selector for the new
+contract. It identifies exactly one run-scoped `runs/{run_id}/commit.json` and
+binds that object by checksum, size, and generation. Readers strictly reject
+unknown fields, version mismatches, pointer/commit identity mismatches, and
+objects that do not match their declaration.
+
+An absent commit pointer means no remote state is published. Republish to
+establish a current immutable snapshot.
+
+## Persistence Semantics
+
+`manifest.LocalStore`:
+
+- accepts only the exact supported session-manifest schema version;
+- rejects unknown fields and multiple JSON values;
+- validates stage-map identity without synthesizing missing maps, records, or
+  names;
+- retains only representation-preserving collection normalization;
+- writes through a sibling temporary file and atomic replacement visibility;
+- updates `updated_at` on save.
+
+Manifest replacement provides atomic visibility, not a crash- or power-loss
+durability guarantee. Callers reload after a returned save error before retrying.
+An analyze checkpoint error leaves the prior manifest as per-artifact authority.
+The runner then attempts to persist the bounded failed/stale retry collection;
+if that terminal save also fails, its error is joined with the originating
+failure and the next invocation must reconcile from the last readable manifest.
+
+## Execution Semantics
+
+Planning and execution share one pure pre-execution decision over the recorded
+stage status, force selection, and normalized resume-validation result. That
+decision identifies run versus reuse and any required stale and dependent
+invalidation transition. Planning applies it only to a cloned manifest.
+Execution remains the sole owner of observed stage results and persistence.
+
+For each selected stage, the application runner computes semantic evidence,
+performs any eligible resume validation, applies the pre-execution decision,
+and persists required invalidation before either reusing the existing success
+or beginning an attempt. The same one-stage execution owner marks the attempt
+running before invoking the stage and then records and persists its failed,
+skipped, or successful terminal state before a later stage may start. On
+success it records outputs, logs, generated configuration references, metadata,
+and—when the stage implements the optional contract—a versioned
+semantic-configuration fingerprint. Artifact
+records may include optional contract and external provenance objects; old
+manifests remain compatible when those fields are absent. A successful forced
+rerun marks only succeeded transitive dependent session-stage records stale.
+The application owns a fixed dependency relation distinct from execution order;
+dependents are returned in canonical order. Render and extract therefore never
+stale one another, while either can stale analyze, publish, notify, and cleanup.
+
+Starting an execution clears the current session-stage record's prior outputs,
+logs, generated configuration references, metadata, and semantic fingerprint.
+Failed and skipped
+transitions enforce the same clearing rule directly, while success repopulates
+only fields returned by the new result. Marking a record stale does not clear
+those details because resume validation and diagnosis may still require them
+before execution begins.
+
+Aggregate lifecycle clearing deliberately preserves the analyze-owned
+per-artifact collection. This lets later reconciliation replace only evaluated
+entries without erasing unrelated current results. Other stages retain their
+existing aggregate-only lifecycle behavior and are forbidden from carrying the
+analyze-specific fields.
+
+A stage may explicitly return a skipped disposition and stable reason. The
+runner persists that outcome in the session manifest, clears older outputs,
+logs, generated configuration references, and metadata, then applies any
+bounded details from the current skip and continues. This self-skip is distinct from deciding not to execute an
+already-succeeded stage and is reconsidered on later runs. Skipped results
+cannot contain outputs. An intentional self-skip records the current semantic
+fingerprint because it is a completed, reusable stage result; failed or
+interrupted work never promotes one.
+
+When an already-succeeded stage is skipped, the session manifest deliberately
+retains its existing succeeded record because it remains the cross-invocation
+progress authority. If a stage supplies semantic configuration evidence, reuse first
+requires the persisted positive schema version and lowercase SHA-256 digest to
+match the current resolved stage semantics. Missing semantic evidence, malformed
+evidence, or a mismatch makes the stage and its fixed transitive dependents
+stale. The existing stage-specific resume
+validator runs only after this semantic check succeeds; both checks are
+required. Extraction, analyze, and cleanup have resume validators and may
+reject an otherwise eligible skip when their selected durable evidence is
+obsolete; the runner marks the aggregate record stale and executes it.
+Analyze's validator can still accept a partial selection when only unrelated
+artifact records are stale.
+
+Implemented reuse coverage is deliberately split between aggregate semantic
+evidence and focused durable validators:
+
+| Work | Reuse authority | Focused owners |
+| --- | --- | --- |
+| prepare | aggregate semantic fingerprint | [prepare](stage-prepare.md) |
+| transcribe | aggregate semantic fingerprint | [transcribe](stage-transcribe.md), [WhisperX](../integrations/whisperx.md) |
+| merge | aggregate semantic fingerprint | [merge](stage-merge.md), [Seriatim](../integrations/seriatim.md) |
+| polish | aggregate semantic fingerprint | [polish](stage-polish.md), [Audita](../integrations/audita.md) |
+| normalize | aggregate semantic fingerprint | [normalize](stage-normalize.md), [Seriatim](../integrations/seriatim.md) |
+| trim | aggregate semantic fingerprint | [trim](stage-trim.md), [Scriptorium](../integrations/scriptorium.md), [Seriatim](../integrations/seriatim.md) |
+| render | aggregate semantic fingerprint | [render](stage-render.md), [Seriatim](../integrations/seriatim.md) |
+| extract | aggregate semantic fingerprint plus reference/output validator | [extract](stage-extract.md), [Notarius](../integrations/notarius.md) |
+| analyze artifacts | per-artifact fingerprint, reconciliation, and output validator | [analyze](stage-analyze.md), [Scriptorium](../integrations/scriptorium.md) |
+| publish | aggregate semantic fingerprint plus immediate lock/commit checks | [publish](stage-publish.md), [storage adapter](adapters.md) |
+| notify | aggregate delivery-mode fingerprint | [pipeline overview](overview.md), [configuration](../config.md#notifications) |
+| cleanup | aggregate semantic fingerprint plus publish-evidence and target-absence validator | [cleanup](stage-cleanup.md), [workspace](workspace.md) |
+
+These contracts record resolved choices Narratio can observe, not operational
+runner tuning. External model, module, prompt, profile, and configuration-file
+contents that a tool privately loads remain outside the contract when their
+configured identifier is unchanged; operators must force the affected work
+after such a private content change.
+
+The session manifest is the authoritative stage-progress ledger across
+invocations. It retains the most recently resolved invocation's bounded
+configuration provenance. It identifies the selected profile name and source
+(`default` or `cli`) plus the effective configuration digest, but never a raw
+secret or profile content. This provenance is informational: it does not
+participate in stage resume or cache decisions. A profile change therefore
+invalidates only stages whose semantic configuration changed. When a private
+external-tool model, module, prompt, or profile changes behind an unchanged
+configured identifier, use `--force` for the affected work.
+
+`session plan` computes the same current fingerprint and applies the shared
+decision and invalidation rules to a cloned manifest. It predicts the runner
+decision without persisting session state. The semantic fingerprint owner
+hashes deterministic JSON from stage-owned typed structs; stage providers must
+exclude secrets, complete effective-configuration dumps, and operational
+values that cannot affect canonical results. Concrete coverage is owned by the
+focused stage and integration documents linked above.
+
+Before an explicitly bounded execution starts after `prepare`, the application
+reads the session manifest and accepts only `succeeded` or `skipped` for every
+excluded canonical prefix stage. The first other status or absent record fails
+the request before layout mutation, adapter initialization, session-manifest
+writes, or run-directory creation. Excluded prefix records are not passed to
+resume validators. Records after the selected end are not prerequisites and
+may be made stale by selected work without being scheduled.
+
+After a publish commits remotely, any configured local cleanup is first recorded
+as a session-manifest obligation before deletion begins. Each target becomes
+complete only after its confined deletion (or safe absence check) and a
+successful manifest save. An incomplete obligation is retried when publish
+executes again and retains the committed run and remote identity that authorized
+it; an invocation that does not execute publish does not perform cleanup.
+
+Each invocation derives campaign, session, run, local-path, and remote-prefix
+metadata from the validated resolved configuration as one projection. A persisted
+session manifest must agree on campaign and session identity before execution;
+the current projection is refreshed for every invocation while stage progress,
+inputs, and durable artifacts remain session history.
+
+For handled failures after the session identity transition, the runner records
+the failure on the session ledger and atomically attempts its save while
+preserving the originating error. Abrupt process death remains an accepted case
+where the last session transition can require operator interpretation.
+
+## Invariants
+
+- stage resume/skip decisions are session-manifest driven.
+- semantic fingerprint comparison precedes stage-specific resume validation.
+- only successful and intentional-skipped results promote current semantic
+  evidence.
+- running, failed, and self-skipped stages do not retain result payloads from
+  an earlier success.
+- stale stages retain prior details until replacement execution starts.
+- force reruns stale succeeded stages in the fixed dependency relation.
+- the session manifest is the only durable local progress ledger.
+- remote commitment is established by a verified current pointer and remote
+  commit relationship, never by a mutable session-manifest boolean.
+
+## Implementation And Tests
+
+- Models and transitions: `internal/manifest/manifest.go`
+- Remote commit model and readers: `internal/artifacts/remote_commit.go`,
+  `internal/artifacts/current_state_commit.go`,
+- Persistence and validation: `internal/manifest/store.go`
+- Package tests: `internal/manifest/*_test.go`
+- Assembled execution behavior: `internal/app/runner_test.go`,
+  `internal/app/run_stage_test.go`

docs/internal/overview.md

@@ -0,0 +1,140 @@
+# Internal Overview
+
+This document is the implemented component map for Narratio. Normative system
+boundaries and dependency direction belong in
+[Architecture](../policy/architecture.md). User and operator contracts belong
+in the [CLI](../cli.md), [Configuration](../config.md),
+[Operations](../operations.md), and [Troubleshooting](../troubleshooting.md).
+Externally observable tool and format contracts belong under
+[Integrations](../integrations/).
+
+## Execution Path
+
+```text
+cmd/narratio -> internal/app -> configuration and production composition
+             -> internal/stage -> adapters and external systems
+             -> manifests and artifact resolution -> durable local/remote output
+```
+
+The executable delegates process behavior to the application boundary. The
+application resolves configuration, composes concrete collaborators, acquires
+session safety controls, and runs commands. Pipeline commands execute the
+canonical stage sequence through adapter interfaces, while manifests record
+progress and artifact services resolve durable inputs and outputs.
+
+The pipeline runner follows one explicit invocation lifecycle: inspect bounded
+prerequisites without mutation, prepare the workspace layout, acquire one
+session lock, load or create the authoritative session manifest, compose only
+the collaborators needed by the selected range, execute each selected stage in
+order, and then return the summary. Cleanup, when selected, is the ordinary
+final stage rather than runner finalization work.
+The lock remains held from manifest initialization through finalization, and a
+failed stage or required manifest save prevents later stages from starting.
+
+## Components
+
+| Area | Implemented owners | Responsibility |
+| --- | --- | --- |
+| 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, and user-facing reporting. |
+| Configuration | [`internal/config`](configuration.md) | ConfigKit-backed pipeline imports and profiles, 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, stage transitions, validation, and atomic persistence. |
+| Artifacts and paths | `internal/artifacts`, `internal/pathsafe` | Artifact identities and resolution, local and remote path/key models, current-state discovery, and confined relative destinations. |
+| Previous-session cache | `internal/previouscache` | Deterministic planning and materialization requirements for configured previous-session inputs. |
+| Artifact policy | `internal/artifactpolicy` | Source and destination policy, configured artifact identity validation, and publish destination safety. |
+| Shared models and file operations | `internal/artifactmodel`, `internal/contracts`, [`internal/fileops`](fileops.md) | Transcript and artifact data contracts plus atomic single-file replacement, bounded reads, workspace modes, and root-scoped cleanup helpers. |
+| Logging | `internal/logging` | Application logger construction and shared structured logging behavior. |
+
+The application boundary composes concrete implementations. Stages depend on
+Narratio-level contracts; external transport and SDK details remain in
+adapters. The normative rules for these relationships remain in
+[Architecture](../policy/architecture.md).
+
+Command execution normalizes one private dependency value per invocation.
+Pipeline configuration-path discovery, configuration reads, secret-directory
+reads, remote downloads, object-store construction, and restore phase functions
+use that value throughout the command. Public command entry points supply the
+canonical discovery and production defaults, while focused tests may provide
+invocation-owned discovery candidates or replace only the external or sequencing
+boundary they exercise without mutating package state.
+
+Pipeline execution and `session plan` share the same inclusive contiguous-range
+model and the same pure pre-execution decision over recorded status, force, and
+normalized resume validation. Planning applies that decision and modeled
+selected-stage transitions to cloned session state; it does not persist, create
+invocation state, initialize stage-execution adapters, or claim to observe an
+execution result. Command configuration loading can still retrieve a
+missing session file through configured remote storage. It retains the initially
+composed pipeline and selected campaign while resolving either a local or
+downloaded remote session, so one invocation cannot mix pipeline revisions.
+Analyze planning additionally exposes the artifact closure's targets,
+prerequisite rebuilds, execution order, and current reuse.
+
+## Pipeline Stage Set
+
+The implemented canonical order is:
+
+1. [`prepare`](stage-prepare.md)
+2. [`transcribe`](stage-transcribe.md)
+3. [`merge`](stage-merge.md)
+4. [`polish`](stage-polish.md)
+5. [`normalize`](stage-normalize.md)
+6. [`trim`](stage-trim.md)
+7. [`render`](stage-render.md)
+8. [`extract`](stage-extract.md)
+9. [`analyze`](stage-analyze.md)
+10. [`publish`](stage-publish.md)
+11. `notify` (no-op)
+12. [`cleanup`](stage-cleanup.md)
+
+`notify` currently has no persisted pipeline outputs and uses the explicit
+`noop` notification mode. Its versioned semantic evidence records that delivery
+mode and excludes adapter credentials and response data. The focused stage
+documents own implementation mechanics. The
+[CLI](../cli.md) and [Operations](../operations.md) own user-visible invocation
+and execution semantics.
+
+Execution order and invalidation are separate application contracts. The stage
+registry owns the flat execution sequence. The application orchestration owner
+uses a fixed, validated dependency relation to find transitive dependents in
+canonical order. In particular, `render` and `extract` are sibling consumers of
+trimmed transcript state: neither invalidates the other, while either can stale
+`analyze`, `publish`, `notify`, and `cleanup`. Cleanup is a dependent of notify,
+so any earlier replacement can stale a prior cleanup result.
+
+## Focused Documentation
+
+- [Configuration Internals](configuration.md): pipeline imports and profiles,
+  field ownership, decoding, and root-relative path semantics.
+- [Adapter Internals](adapters.md): external adapter boundaries, composition,
+  failure behavior, and test surfaces.
+- [Artifact Internals](artifacts.md): source identities, runtime catalog,
+  resolution, previous requirements, and current-state helpers.
+- [Manifest Internals](manifest.md): session records, persistence, and execution
+  transitions.
+- [Storage Internals](storage.md): object-store interface and S3 behavior.
+- [Workspace Internals](workspace.md): local layout, locking, and cleanup
+  guardrails.
+- [Restore Internals](command-restore.md): discovery, planning, execution, and
+  reporting.
+- [`prepare`](stage-prepare.md)
+- [`transcribe`](stage-transcribe.md)
+- [`merge`](stage-merge.md)
+- [`polish`](stage-polish.md)
+- [`normalize`](stage-normalize.md)
+- [`trim`](stage-trim.md)
+- [`render`](stage-render.md)
+- [`extract`](stage-extract.md)
+- [`analyze`](stage-analyze.md)
+- [`publish`](stage-publish.md)
+- [`cleanup`](stage-cleanup.md)
+
+Use this map to find an owner, then read its focused documentation and tests
+before changing behavior.
+
+The stage registry is implemented in `internal/stage/placeholders.go` and its
+ordering is protected by `internal/app/planner_test.go`. Cross-invocation skip,
+force, failure, and invalidation behavior is exercised in
+`internal/app/runner_test.go` and `internal/app/run_stage_test.go`.

docs/internal/stage-analyze.md

@@ -1,84 +1,210 @@
 # Stage: analyze
 
 ## Purpose
-Execute selected configured Scriptorium artifacts in deterministic dependency order and promote successful outputs to canonical session artifact paths.
 
-## Inputs and Outputs
-Inputs:
-- configured artifact definitions from `pipeline.scriptorium.artifacts`
-- selected artifact filter from runtime (`--artifacts`) when provided
-- resolved artifact input sources declared per artifact (`inputs.*.source`)
-- optional previous-session file inputs (`previous_session_artifact`)
+Reconcile configured Scriptorium artifacts, execute only required work in
+dependency order, and safely materialize validated outputs.
 
-Outputs:
-- one promoted output file per executed configured artifact at that artifact's configured `output_path`
-- stage metadata containing generated artifact entries and reused disabled-artifact entries
+## Inputs
 
-## Boundaries
-Owns:
-- runtime artifact catalog construction for analyze execution
-- selected-artifact planning and dependency ordering
-- per-artifact input resolution, var resolution, timeout/render-debug resolution
-- Scriptorium run/render invocation for each selected artifact
-- run-local output generation and canonical promotion
+- ordinary configured artifacts from `pipeline.scriptorium.artifacts`; canonical
+  party artifact families have already expanded into this map during
+  configuration resolution, including corresponding member dependencies and
+  rewritten member-artifact input sources. Each artifact's dependency list is
+  already the normalized union of explicit ordering edges and configured-artifact
+  input edges.
+- optional selected artifact keys supplied through the stage environment
+- built-in, configured, extraction, and previous-session source references in
+  artifact inputs
 
-Does not own:
-- transcript generation/processing stages
-- archive promotion policy
-- per-artifact resume semantics
+Supported source families:
+- built-ins: `narratio.transcript.*`, `narratio.bounds.session`
+- prepared stable inputs: `narratio.input.players`, `narratio.input.party`,
+  `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>`
 
-## Config Fields Used
-- `session.session_id`
-- `session.campaign`
-- `pipeline.workspace.root`
-- `pipeline.scriptorium.binary`
-- `pipeline.scriptorium.config_path`
-- `pipeline.scriptorium.timeout`
-- `pipeline.scriptorium.render_debug`
-- `pipeline.scriptorium.artifacts.<name>.*`
-  - `enabled`
-  - `depends_on`
-  - `prompt_id`
-  - `profile_id`
-  - `timeout`
-  - `output_path`
-  - `render_debug`
-  - `inputs`
-  - `vars`
+## Outputs
 
-## External Adapters Used
-- Scriptorium adapter:
-  - optional `RenderArtifact` (render debug)
-  - `RunArtifact` (artifact generation)
+- one current per-artifact manifest record per validated materialized output
+- stage metadata describing selected/generated/reused artifacts
 
-## State and Manifest Behavior
-- If `pipeline.scriptorium` is absent, stage returns success metadata with `skipped=true`.
-- If no artifacts are configured, stage returns success metadata with `skipped=true`.
-- If zero artifacts are executable after `enabled` + `--artifacts` filtering, stage returns success metadata with `skipped=true`.
-- Builds runtime catalog with built-ins and configured artifacts.
-- Non-executable configured artifacts are marked available only when their configured output file exists and is valid on disk.
-- Executes selected configured artifacts in topological order with deterministic tie-breaking.
-- For each generated artifact, records metadata fields including `name`, `source_id`, `output_kind`, `path`, `prompt_id`, `profile_id`, and `provenance`.
-- Reused disabled artifacts are recorded separately in `reused_artifacts` with provenance `filesystem.disabled_artifact_output`.
+## Key Behavior
 
-## Skip and Resume Behavior
-- Runner-level skip applies when analyze is already `succeeded` and `--force` is not set.
-- Analyze remains stage-scoped for resume/skip; there is no per-artifact resume state.
-- `--artifacts` filters which configured artifacts are executable when analyze runs; it does not imply `--force`.
+- when `pipeline.scriptorium` is absent or no configured artifact is
+  executable, completes successfully and records explanatory metadata. Before
+  returning, it reconciles and checkpoints the complete session collection:
+  records removed from configuration are dropped, while valid records for
+  configured but unselected artifacts remain authoritative. This is not an
+  explicit self-skip: the session manifest records success, satisfies publish's
+  prerequisite, and an ordinary later run reuses the result while the effective
+  set remains empty. Enabling or selecting an artifact later makes missing
+  versioned evidence non-resumable and schedules it without requiring force.
+- builds a runtime artifact catalog containing built-ins, configured artifacts,
+  and configured extraction lanes. Extraction availability is hydrated only
+  from compatible successful extraction evidence.
+- uses enabled configured artifacts by default. An explicit `--artifacts`
+  selection is a one-invocation override that makes exactly the named
+  configured artifacts explicit targets even when disabled. The work planner
+  adds required configured prerequisites, reuses current ones, and schedules
+  stale, missing, or otherwise non-current prerequisites before dependents.
+- makes a non-executable configured artifact reusable only when its current
+  manifest record and durable output pass the configured-artifact evidence
+  contract; an incidental or stale canonical file is unavailable.
+- validates selected artifact dependency order (cycle-safe topo ordering).
+- consumes only the concrete dependency graph finalized by configuration;
+  planning, prerequisite closure, execution, reuse, invalidation, and semantic
+  evidence do not infer a second graph from inputs.
+- resolves required/optional inputs per artifact source definition into an
+  ordered semantic identity. Each identity records the configured input name,
+  canonical source ID, required policy, explicit presence, source contract,
+  checksum, size, and a source-based logical identity. Workspace paths and
+  producer run IDs are excluded.
+- orders input identities by configured input name independently of Go map
+  iteration. Runtime adapter paths remain a separate execution-only map.
+- omits an unavailable optional input from the adapter request while retaining
+  explicit absence in its semantic identity; an unavailable required input
+  fails.
+- 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.
+- reuses checksums and sizes from validated prepared, extraction, and current
+  configured-artifact evidence. Other resolved inputs are hashed as confined
+  regular files with streaming reads and the central resolved-artifact size
+  limit.
+- owns a versioned SHA-256 fingerprint contract with one fixed-field canonical
+  JSON payload and no map serialization. Configured artifacts are fingerprinted
+  in deterministic dependency order.
+- fingerprints the normalized artifact key, prompt and profile identifiers,
+  effective render-debug behavior, session-relative output identity, sorted
+  dependency keys, ordered input declarations and semantic identities,
+  validated current dependency-output identities, and sorted effective
+  Scriptorium variables (including Narratio's sticky session variable).
+- provides read-only reconciliation that classifies each configured record as
+  current, stale, missing, failed, or otherwise non-resumable, and
+  separately identifies manifest records removed from current configuration.
+  A record is current only when its fingerprint version and value match and its
+  configured output still passes manifest-authoritative evidence validation.
+- owns a read-only typed work planner. Its explicit targets are enabled
+  artifacts by default or the exact normalized `--artifacts` selection when
+  supplied. It closes targets over configured prerequisites, orders the closure
+  topologically, reuses current members, and schedules every non-current member
+  before its dependents.
+- force applies only to explicit targets. A current prerequisite is reused
+  unless it is itself an explicit forced target; disabled prerequisites may be
+  rebuilt when required, while unrelated disabled artifacts are excluded.
+- the work plan carries explicit targets, prerequisite-only work, deterministic
+  execution and reuse lists, invalidated and removed records, and a cloned
+  reconciled starting collection. Valid unrelated configured records survive
+  reconciliation, removed records are omitted, and incidental files never
+  become current without manifest-backed regeneration.
+- implements aggregate resume validation by running the same read-only catalog,
+  fingerprint reconciliation, and work planner used by execution. A succeeded
+  aggregate record is reusable exactly when the selected closure schedules no
+  artifact work and no removed configuration records require a checkpoint;
+  stale unrelated records do not block a partial selection.
+- exposes the typed artifact decision to `session plan`. Planning applies it to
+  a cloned manifest after modeling earlier selected stage transitions, so
+  aggregate run/skip and artifact execute/reuse decisions match the ordinary
+  runner without creating durable state or invoking Scriptorium.
+- executes only the work plan's scheduled entries. Manifest-validated current
+  prerequisites remain available through the runtime catalog without invoking
+  Scriptorium; newly produced prerequisites enter that catalog with the same
+  contract, checksum, and size identity used for persisted current evidence.
+- before the first adapter call, checkpoints the reconciled starting collection
+  when it removed configuration records or cleared obsolete authority. After
+  each successful artifact, checkpoints the complete collection before making
+  that artifact available to the next scheduled dependent.
+- keeps adapter output in the invocation's run-local analyze directory until
+  it is a safe, non-empty, bounded regular file with a calculated checksum and
+  complete output contract. Canonical replacement uses the shared atomic file
+  operation boundary and verifies that the installed checksum matches the
+  validated run-local bytes.
+- records each successful artifact's freshly computed fingerprint, canonical
+  relative output path, contract, checksum, size, producer run ID, bounded
+  Scriptorium provenance, logs, and generated configuration references in the
+  analyze-owned manifest collection.
+- preserves valid unrelated current records during partial execution. If a
+  rebuilt output's bytes and contract are unchanged, unselected dependents may
+  remain current. If that semantic identity changes, unselected transitive
+  dependents become stale without being executed; dependents included in the
+  invocation are evaluated in dependency order instead.
+- returns aggregate outputs from every current session record in normalized-key
+  order after the complete reconciled collection has been checkpointed;
+  unrelated stale records do not make an otherwise successful partial
+  invocation fail.
+- 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.
 
-## Failure Behavior
-- Fails on invalid dependency ordering, unavailable required configured inputs, invalid built-in input prerequisites, render/run adapter failures, validation-failed adapter results, or missing/empty outputs.
-- Required configured dependency missing from catalog availability fails clearly before invocation.
-- Optional missing inputs are omitted.
+## Failure Semantics
 
-## Tests to Inspect Before Changing
-- `internal/stage/analyze_test.go`
-- `internal/artifacts/catalog_test.go`
-- `internal/artifacts/artifact_resolver_test.go`
-- `internal/adapters/scriptorium/subprocess_test.go`
+- required missing configured/previous-session inputs fail.
+- missing required prepared stable input source includes prepare rerun guidance.
+- missing required previous-session source includes prepare rerun guidance.
+- missing required `narratio.transcript.final_markdown` or
+  `narratio.transcript.final_trimmed_markdown` inputs includes render rerun
+  guidance.
+- dependency cycles or unavailable required dependencies fail.
+- adapter validation failures fail stage.
+- a scheduled artifact failure installs a retry collection on the live manifest
+  with the active artifact marked `failed`, a bounded error, and no output
+  authority. Current transitive dependents become stale without execution.
+- earlier artifacts remain current only after their run-local output passed
+  validation, canonical materialization, and a successful complete-collection
+  manifest checkpoint; unattempted later artifacts retain their reconciled
+  session state.
+- unrelated current records survive a partial failure. Old canonical bytes for
+  the failed artifact and newly materialized bytes whose checkpoint fails are
+  incidental, not current evidence.
+- a checkpoint failure stops the queue immediately. The in-memory retry
+  collection starts from the last successful checkpoint, marks the active
+  artifact failed without output authority, and stales its current transitive
+  dependents.
+- the runner's ordinary error path marks aggregate analyze failed, clears its
+  aggregate outputs, invalidates publish, notify, and cleanup through the
+  application dependency relation, and persists the live retry collection.
+  Terminal-save errors are joined with the original artifact or checkpoint
+  failure.
 
-## Architectural Invariants
-- Configured artifacts are identified by `narratio.artifact.<name>` source IDs.
-- Artifact-to-artifact references rely on explicit `depends_on` declarations validated in config.
-- Generated analyze outputs are treated uniformly as Scriptorium artifacts.
-- Successful outputs must exist and be non-empty before promotion.
+## Invariants
+
+- `analyze` performs no remote storage calls for previous-session source resolution.
+- input-identity resolution is read-only: it does not invoke adapters,
+  materialize outputs, update status, or create run-local files.
+- fingerprints exclude timeouts, retries, timestamps, producer and Narratio run
+  IDs, executable and config paths, workspace roots, diagnostic locations, and
+  executable or private transitive configuration contents. A change that is
+  visible only inside Scriptorium—such as a file privately loaded by its config
+  path—requires an explicit forced regeneration.
+- output provenance and metadata are deterministic per execution.
+- a canonical file without current per-artifact manifest evidence is never
+  promoted to current state.
+- an ordinary retry after interruption or partial failure reuses every valid
+  earlier checkpoint and schedules only failed, stale, missing, or otherwise
+  non-current work in dependency order.
+
+## Related Contracts And Tests
+
+- [Configuration](../config.md#scriptorium-artifact-entries) owns artifact
+  fields and source-selection rules, including
+  [artifact families](../config.md#scriptorium-artifact-families).
+- [CLI](../cli.md) owns user-visible artifact selection.
+- [Scriptorium](../integrations/scriptorium.md) owns the subprocess contract.
+- Implementation and tests: `internal/stage/analyze.go`,
+  `internal/stage/analyze_artifact_execution.go`,
+  `internal/stage/analyze_execution_state.go`,
+  `internal/stage/analyze_input_identity.go`,
+  `internal/stage/analyze_fingerprint.go`,
+  `internal/stage/analyze_reconciliation.go`, `internal/stage/analyze_plan.go`,
+  `internal/stage/analyze_resume.go`, `internal/stage/analyze_test.go`,
+  `internal/stage/analyze_checkpoint_test.go`,
+  `internal/stage/analyze_input_identity_test.go`,
+  `internal/stage/analyze_fingerprint_test.go`,
+  `internal/stage/analyze_reconciliation_test.go`,
+  `internal/stage/analyze_plan_test.go`,
+  `internal/stage/analyze_incremental_execution_test.go`,
+  `internal/stage/analyze_failure_test.go`,
+  `internal/stage/analyze_resume_test.go`, and
+  `internal/app/analyze_checkpoint_recovery_test.go`.

docs/internal/stage-archive.md

@@ -1,68 +0,0 @@
-# Stage: archive
-
-## Purpose
-Publish run records and promoted session artifacts to object storage, then atomically advance the remote current pointer.
-
-## Inputs and Outputs
-Inputs:
-- session manifest and prerequisite stage records
-- run root contents under `runs/{run_id}/`
-- promotion sources from session root (`archive.promote_artifacts`)
-
-Outputs:
-- uploaded run files under `{session_prefix}/runs/{run_id}/...`
-- uploaded promoted artifacts under `{session_prefix}/...`
-- `{session_prefix}/current/manifest.json`
-- `{session_prefix}/current/run_id.txt` written last
-
-## Boundaries
-Owns:
-- Archive enable/disable gate behavior
-- Prerequisite stage success enforcement
-- Run file collection and upload (excluding `audio/`)
-- Promotion rule resolution and upload
-- Commit pointer publish order
-
-Does not own:
-- Stage execution before archive
-- Post-archive local cleanup policy execution (handled by app cleanup logic)
-
-## Config Fields Used
-- `pipeline.archive.enabled`
-- `pipeline.archive.upload_run`
-- `pipeline.archive.promote_artifacts`
-- `pipeline.storage.s3.bucket`
-- `pipeline.storage.s3.root_prefix`
-- `pipeline.workspace.root`
-- `session.campaign`
-- `session.session_id`
-
-## External Adapters Used
-- Object storage backend (`env.ObjectStore`) for upload/list primitives.
-
-## State and Manifest Behavior
-- Requires `prepare`, `transcribe`, `merge`, `polish`, `normalize`, `trim`, and `analyze` status `succeeded`.
-- Resolves bucket/prefix from manifest identity first, then config fallback.
-- Writes metadata including:
-  - upload counts/paths
-  - `current_manifest_key`
-  - `current_run_id_key`
-  - `current_pointer_written`
-- On skipped archive path, returns metadata with `skipped=true` and pointer not written.
-
-## Skip and Resume Behavior
-- Stage may self-skip (metadata skip) when archive disabled or run upload disabled.
-- Runner-level skip also applies for previously succeeded stage unless forced.
-
-## Failure Behavior
-- Fails on missing prerequisite success, missing object store when required, missing run root, missing required promotion source, upload failures, or pointer write failures.
-- Pointer semantics are fail-safe: `current/run_id.txt` is not written if prior required uploads fail.
-
-## Tests to Inspect Before Changing
-- `internal/stage/archive_test.go`
-- `internal/app/post_archive_cleanup_test.go`
-
-## Architectural Invariants
-- Run upload excludes `audio/` subtree.
-- `current/manifest.json` uploads before `current/run_id.txt`.
-- `current/run_id.txt` is the remote publish commit marker.

docs/internal/stage-cleanup.md

@@ -0,0 +1,54 @@
+# Stage: cleanup
+
+## Purpose
+
+Remove explicitly configured local data for the run selected by a successful
+publish commit. Cleanup is the twelfth and final canonical stage, after
+`notify`.
+
+## Authorization And Targets
+
+Cleanup is disabled unless at least one of these policies is true:
+
+- `pipeline.spool.delete_audio_after_publish`
+- `pipeline.workspace.cleanup_after_publish`
+
+An enabled cleanup requires the manifest's publish stage to be succeeded with
+`uploaded=true`, a canonical `published_run_id`, and the exact remote commit and
+current commit-pointer keys for the manifest campaign/session prefix. The
+configured campaign and session must match the manifest. Cleanup derives its
+only possible targets through the canonical artifact path helpers:
+
+- the published run's session spool-audio directory; and
+- the published run's workspace run directory.
+
+It does not scan parent directories, infer the newest run, or read object
+storage. Every deletion uses the root-confined file operation, which rejects a
+root itself, traversal, symlink escape, and out-of-root targets.
+
+## Execution And Resume
+
+Disabled cleanup records an explicit skipped result. Enabled cleanup removes
+targets in deterministic policy order and treats an already-missing target as
+success. A successful record contains the published run ID and completed policy
+names.
+
+A previous cleanup success is reusable only while its semantic configuration
+matches and every selected target remains absent. A recreated target makes the
+stage non-resumable. A failure is recorded against cleanup; publish remains
+succeeded and remote current state is unchanged. On a later normal full run,
+valid upstream stages are skipped and cleanup is retried without republishing.
+
+`narratio publish` selects publish only and never invokes cleanup. A bounded run
+through `notify` or any earlier endpoint also excludes it. Operators may run
+`narratio run-stage cleanup <session_id>` directly; missing, failed, malformed,
+or identity-mismatched publication evidence fails before deletion.
+
+## Implementation And Tests
+
+- Planning and evidence validation: `internal/stage/cleanup_plan.go`
+- Execution and resume: `internal/stage/cleanup.go`
+- Root-confined deletion: `internal/fileops/cleanup.go`
+- Focused tests: `internal/stage/cleanup_plan_test.go`,
+  `internal/stage/cleanup_test.go`, and
+  `internal/app/cleanup_orchestration_test.go`

docs/internal/stage-extract.md

@@ -0,0 +1,140 @@
+# Internal: Extract Stage
+
+## Responsibility
+
+`extract` runs after `render` and before `analyze`. It converts the canonical
+`narratio.transcript.final_trimmed` JSON into configured Notarius lane artifacts.
+An omitted or disabled Notarius section makes the stage explicitly self-skip
+with reason `notarius_disabled`, no outputs, and no Notarius runner.
+
+The external protocol is documented in the
+[Notarius integration contract](../integrations/notarius.md). Configuration
+fields belong in [Configuration](../config.md), and physical paths and force
+procedures belong in [Operations](../operations.md).
+
+## Lifecycle
+
+`internal/stage/extract.go`:
+
+1. resolves the final trimmed transcript from the shared artifact catalog;
+2. resolves every configured prepared reference through the shared
+   manifest-authoritative identity resolver before creating run-local output;
+3. resolves each reference to a stable content-addressed session snapshot,
+   reusing verified bytes or reconstructing a missing/corrupt regular entry,
+   and rejects any source change observed while copying;
+4. fingerprints the byte- and provenance-bearing Notarius invocation evidence,
+   including sorted reference identities;
+5. creates a run-local staging directory and invokes the injected
+   `notarius.Runner`, carrying the optional already-resolved credential
+   reference without exposing its value, plus effective resume and chunk-cache
+   controls after force precedence;
+6. revalidates the reference snapshots, then validates the v2 successful
+   receipt, confined index, management documents, configured required lane
+   descriptors, validation summaries, and regular payload files;
+7. atomically promotes the complete bundle to its immutable durable location;
+8. records one non-selectable `notarius_index` output and one selectable
+   `notarius_lane` output per configured lane; and
+9. 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,
+run, pipeline, and lane provenance. Stage metadata retains the durable bundle
+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 stable
+snapshot path, never payload contents. Snapshot bytes must
+match the prepared identity both before and after Notarius runs, so a concurrent
+prepared-file replacement cannot make recorded provenance describe different
+bytes from those supplied to Notarius.
+Validation completes before the single durable rename, so a rejected result
+cannot expose a partial durable bundle.
+
+Snapshot destinations are owned by `internal/artifacts` under
+`cache/notarius/references/<sha256>/<prepared-basename>`. They contain no run ID
+or timestamp and can be reused across invocations. Identical bytes and basename
+share a verified file; changed bytes select a different digest directory.
+Unsafe path components and non-regular conflicts fail without recursive
+deletion. Snapshot paths are delivery details and never become manifest output
+evidence or prerequisites for reuse of an already complete extract bundle.
+
+Any executed extraction outcome that replaces a different effective outcome
+marks succeeded analysis and delivery dependents stale. Render is an independent
+sibling and remains current. Repeating the same disabled self-skip with no
+outputs is stable and does not repeatedly invalidate dependent stages.
+
+## Resume Validation
+
+Before the focused validator runs, the application compares extract's versioned
+semantic fingerprint. It covers enablement, Notarius pipeline identity, sorted
+reference selector/source mappings, sorted declared output contracts, and each
+canonical `narratio.extraction.<key>` output identity. It excludes executable,
+timeout, working directory, config path, and private Notarius config contents.
+Credential presence, reference name, and resolved value are likewise
+operational-only and excluded. Ordinary command loading still resolves a
+selected reference before resume evaluation, but a credential-only change does
+not rerun a valid completed extraction or stale its dependents.
+
+`internal/stage/extract_resume.go` then permits a skip only when the existing
+stage record still matches the current byte- and provenance-bearing invocation
+evidence. That evidence covers the current direct trimmed-transcript identity,
+sorted prepared-reference identities, pipeline identity, and configured output
+contracts. The same reference helper and transcript identity are resolved again
+for artifact evidence, so changing current transcript bytes, reference bytes,
+or producer identity makes the prior extraction obsolete. Operational runner
+settings do not invalidate otherwise current durable evidence. This includes
+`resume` and `chunk_cache`; changing them alone cannot make a complete
+extraction non-resumable. If extraction executes, ordinary runs forward the
+configured values, while force disables resume and selects `refresh`.
+
+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,
+contracts and provenance, regular-file status, and stored checksums. Missing or
+obsolete results are non-resumable and run again; unsafe filesystem conditions
+return an error rather than silently accepting or replacing data.
+
+Neither contract can observe files imported by Notarius configuration, profile
+contents, prompt/module definitions, or other transitive inputs. Operators must
+force extraction after changing any such private input behind a stable
+identifier.
+
+## Failure Behavior
+
+Adapter startup, timeout, nonzero exit, receipt decoding, path confinement,
+index compatibility, inconsistent warning or diagnostic envelopes,
+required-lane rejection or incomplete validation, payload inspection,
+checksum, or installation errors fail the stage through ordinary manifest
+transition handling.
+Stdout receipt and stderr diagnostics remain separate. Downstream stages are
+not given selectable extraction sources unless the complete configured result
+has passed validation and installation.
+
+When a replacement attempt begins, the current session-stage record no longer
+advertises payload from the previous success. A failed replacement therefore
+has no current outputs, logs, generated configuration references, or metadata,
+while the earlier immutable promoted bundle remains available for audit and
+recovery.
+
+## Implementation And Focused Tests
+
+- Stage execution, selection, and resume validation: `internal/stage/extract.go`,
+  `internal/stage/extract_resume.go`,
+  `internal/stage/extract_test.go`,
+  `internal/stage/semantic_contracts_delivery.go`
+- Stable snapshot materialization and verification:
+  `internal/stage/extract_references.go`
+- Subprocess boundary: `internal/adapters/notarius/subprocess.go`,
+  `internal/adapters/notarius/subprocess_test.go`
+- Catalog hydration: `internal/artifacts/extraction_catalog.go`,
+  `internal/artifacts/extraction_catalog_test.go`
+- Composition and downstream behavior: `internal/app/runner_test.go`,
+  `internal/stage/analyze_test.go`, `internal/stage/publish_test.go`
+- Opt-in Notarius v0.7.0 production-boundary coverage:
+  `internal/stage/notarius_cache_integration_test.go`

docs/internal/stage-merge.md

@@ -1,63 +1,51 @@
 # Stage: merge
 
 ## Purpose
-Normalize per-speaker raw transcripts and merge them into one merged transcript via Seriatim.
 
-## Inputs and Outputs
-Inputs:
+Normalize raw transcript inputs and merge into base transcript via Seriatim.
+
+## Inputs
+
 - `transcripts/raw/*.json`
 - `inputs/speakers.yml`
 - `inputs/autocorrect.yml`
 
-Outputs:
-- `transcripts/merged.json`
-- optional `artifacts/seriatim.report.json` (when report enabled)
+## Outputs
 
-## Boundaries
-Owns:
-- Raw transcript discovery/validation
-- Per-input normalize calls to Seriatim
-- Final merge call to Seriatim
-- Run-local log/config/report path wiring
-- Promotion of merged/report outputs to canonical paths
+- `transcripts/base.json`
+- optional `artifacts/seriatim.report.json`
 
-Does not own:
-- Transcript polishing or downstream artifact generation
+## Key Behavior
 
-## Config Fields Used
-- `session.session_id`
-- `session.campaign`
-- `pipeline.workspace.root`
-- `pipeline.seriatim.binary`
-- `pipeline.seriatim.timeout`
-- `pipeline.seriatim.output_schema`
-- `pipeline.seriatim.coalesce_gap`
-- `pipeline.seriatim.report`
-- `pipeline.seriatim.env.*`
+- discovers and validates raw transcript inputs.
+- normalizes each raw transcript (`seriatim.Normalize`) into run-local scratch output.
+- merges normalized inputs (`seriatim.Run`) into base transcript.
+- validates merged transcript and optional report JSON.
+- materializes canonical outputs and records stage logs/generated configs.
 
-## External Adapters Used
-- Seriatim adapter:
-  - `Normalize` for each raw input
-  - `Run` for final merge
+## Invariants
 
-## State and Manifest Behavior
-- Reads transcript inputs from transcribe stage outputs in manifest when present; falls back to canonical raw directory.
-- Writes run-local outputs/logs/config under `runs/{run_id}/merge/...` when enabled.
-- Promotes canonical merged transcript and optional report.
-- Records normalized-input provenance and adapter metadata in stage metadata.
+- merge always consumes normalized forms of raw inputs.
+- base transcript must validate before stage success.
+- report output is config-gated.
 
-## Skip and Resume Behavior
-- Runner-level skip applies when already succeeded and not forced.
-- Forced rerun of this or upstream stages can stale downstream succeeded stages via runner invalidation.
+## Resume Evidence
 
-## Failure Behavior
-- Fails on missing/invalid raw transcripts, missing speakers/autocorrect files, normalize failure, merge failure, invalid merged output JSON, or invalid report JSON when enabled.
+Merge records a versioned semantic-configuration fingerprint for the Seriatim
+merge operation, output schema, coalesce gap, and every configured advanced
+merge transformation. A change reruns merge and stales only its fixed
+descendants; prepare and transcribe remain reusable. Binary path, timeout,
+report emission, logs, and diagnostic retention are operational exclusions.
 
-## Tests to Inspect Before Changing
-- `internal/stage/merge_test.go`
-- `internal/adapters/seriatim/subprocess_test.go`
+Configuration or resources loaded privately inside Seriatim are outside
+Narratio's observable contract and require `--force` when changed. An existing
+successful merge record without evidence reruns once when selected.
 
-## Architectural Invariants
-- Merge consumes normalized forms of each raw transcript.
-- Merged transcript must validate before promotion.
-- Report output is optional and gated by config.
+## Related Contracts And Tests
+
+- [Seriatim](../integrations/seriatim.md) owns subprocess and output semantics.
+- [Configuration](../config.md#pipeline) owns operator-selected Seriatim values.
+- Implementation and tests: `internal/stage/merge.go`,
+  `internal/stage/merge_test.go`,
+  `internal/stage/semantic_contracts_initial.go`, and
+  `internal/stage/semantic_contracts_initial_test.go`

docs/internal/stage-normalize.md

@@ -1,56 +1,42 @@
 # Stage: normalize
 
 ## Purpose
-Normalize the processed transcript into a deterministic intermediate schema for trim and optionally emit a normalize report.
 
-## Inputs and Outputs
-Inputs:
-- `transcripts/processed.json`
+Normalize polished transcript into final transcript using Seriatim.
 
-Outputs:
-- `transcripts/normalized.json` (or configured normalize output path)
+## Inputs
+
+- `transcripts/polished.json`
+
+## Outputs
+
+- `transcripts/final.json` (or configured normalize output path)
 - optional `artifacts/seriatim.normalize.report.json`
 
-## Boundaries
-Owns:
-- Processed transcript discovery/validation
-- Normalize request construction and invocation
-- Optional normalize report wiring
-- Promotion of normalized transcript and optional report
+## Key Behavior
 
-Does not own:
-- Bounds detection or segment trimming
+- resolves polished transcript only from verified manifest output evidence.
+- applies `pipeline.normalize` config or default normalize config.
+- runs Seriatim normalize with configured timeout/binary.
+- validates normalized transcript and optional report.
+- materializes canonical outputs and records logs/generated configs.
 
-## Config Fields Used
-- `session.session_id`
-- `session.campaign`
-- `pipeline.workspace.root`
-- `pipeline.normalize.output_path`
-- `pipeline.normalize.output_schema`
-- `pipeline.normalize.report`
-- `pipeline.seriatim.binary`
-- `pipeline.seriatim.timeout`
+## Invariants
 
-## External Adapters Used
-- Seriatim adapter (`Normalize`).
+- final transcript must validate as processed transcript JSON (`segments` array).
+- normalize defaults are applied when `pipeline.normalize` is unset.
 
-## State and Manifest Behavior
-- Reads processed transcript from polish outputs in manifest when present; falls back to canonical path.
-- Uses run-local output/report/log/config paths when run layout is enabled.
-- Promotes canonical normalized transcript and optional normalize report.
-- Records adapter/result metadata including source path selection.
+## Resume Semantics
 
-## Skip and Resume Behavior
-- Runner-level skip applies when already succeeded and not forced.
-- Forced reruns can stale downstream succeeded stages.
+The versioned semantic fingerprint covers the Seriatim normalize operation,
+output schema and canonical output identity, plus the configured transcript
+transformations. Seriatim's executable and timeout and optional report
+generation are operational and do not invalidate the normalized transcript.
 
-## Failure Behavior
-- Fails on missing/invalid processed transcript, adapter error, invalid normalized output, or invalid report output when report enabled.
+## Related Contracts And Tests
 
-## Tests to Inspect Before Changing
-- `internal/stage/normalize_test.go`
-- `internal/adapters/seriatim/subprocess_test.go`
-
-## Architectural Invariants
-- Normalized output must validate as processed-transcript-compatible JSON (`segments` array required).
-- Default normalize config is applied when `pipeline.normalize` is unset.
+- [Seriatim](../integrations/seriatim.md) owns subprocess and output semantics.
+- [Configuration](../config.md#pipeline) owns normalize fields and defaults.
+- Implementation and tests: `internal/stage/normalize.go`,
+  `internal/stage/normalize_test.go`,
+  `internal/stage/semantic_contracts_refinement.go`

docs/internal/stage-polish.md

@@ -1,69 +1,54 @@
 # Stage: polish
 
 ## Purpose
-Polish merged transcript with Audita and produce a processed transcript for downstream normalization/analyze.
 
-## Inputs and Outputs
-Inputs:
-- `transcripts/merged.json`
+Run Audita polishing on base transcript and produce polished transcript.
+
+## Inputs
+
+- `transcripts/base.json`
 - `inputs/glossary.yml`
 
-Outputs:
-- `transcripts/processed.json`
-- optional `artifacts/audita.report.json` (when report enabled)
+## Outputs
 
-## Boundaries
-Owns:
-- Merged transcript discovery/validation
-- Audita invocation request construction
-- Run-local logs/config/work-dir/report wiring
-- Promotion of processed transcript and optional report
+- `transcripts/polished.json`
+- optional `artifacts/audita.report.json`
 
-Does not own:
-- Upstream merge normalization
-- Downstream normalize/trim/analyze logic
+## Key Behavior
 
-## Config Fields Used
-- `session.session_id`
-- `session.campaign`
-- `pipeline.workspace.root`
-- `pipeline.audita.binary`
-- `pipeline.audita.timeout`
-- `pipeline.audita.llm_api_key_env`
-- `pipeline.audita.modules`
-- `pipeline.audita.base_url`
-- `pipeline.audita.model`
-- `pipeline.audita.transcript_description`
-- `pipeline.audita.config_path`
-- `pipeline.audita.output_schema`
-- `pipeline.audita.work_dir_retention`
-- `pipeline.audita.total_llm_concurrency`
-- `pipeline.audita.proposal_llm_concurrency`
-- `pipeline.audita.validation_model`
-- `pipeline.audita.validation_llm_concurrency`
-- `pipeline.audita.report`
+- resolves base transcript only from verified merge manifest output evidence.
+- invokes an Audita runner configured with static model/runtime options; the
+  invocation supplies paths and modules.
+- validates processed transcript structure (`segments` array required).
+- validates optional report JSON.
+- materializes canonical outputs; records logs/generated config and adapter metadata.
 
-## External Adapters Used
-- Audita adapter (`env.Audita.Run`).
+## Invariants
 
-## State and Manifest Behavior
-- Reads merged transcript from merge manifest outputs when available; falls back to canonical merged path.
-- Uses run-local output/report/log/config/scratch paths when run layout is enabled.
-- Promotes canonical `transcripts/processed.json` and optional report.
-- Records adapter invocation metadata, credential presence signal, and output provenance in stage metadata.
+- polished transcript schema validation is mandatory.
+- report output is config-gated.
 
-## Skip and Resume Behavior
-- Runner-level skip applies when already succeeded and not forced.
-- Forced rerun can stale downstream succeeded stages via runner invalidation.
+## Resume Semantics
 
-## Failure Behavior
-- Fails on missing/invalid merged transcript, missing glossary, adapter error, invalid processed output shape (`segments` array required), or invalid report JSON when enabled.
+The versioned semantic fingerprint covers the Audita service endpoint, model,
+validation model, module set, transcript description, output schema, selected
+external configuration path, and canonical polished-transcript identity. Module
+ordering is normalized because the configured modules form a set. Audita's
+executable, timeouts, concurrency, report and debug behavior, work retention,
+and resolved credential value are operational and do not invalidate a
+successful result. The public credential reference name may participate in
+configuration provenance but never exposes its resolved value.
 
-## Tests to Inspect Before Changing
-- `internal/stage/polish_test.go`
-- `internal/adapters/audita/subprocess_test.go`
+Narratio can fingerprint a selected model, module, or configuration identifier,
+but it cannot inspect content that Audita privately resolves behind that stable
+identifier. Force `polish` after changing such private content without changing
+its identifier.
 
-## Architectural Invariants
-- Processed transcript must contain a top-level `segments` array.
-- Report behavior is strictly config-gated.
-- Stage output canonicalization always ends at `transcripts/processed.json`.
+## Related Contracts And Tests
+
+- [Audita](../integrations/audita.md) owns subprocess, validation, and failure
+  semantics.
+- [Configuration](../config.md#pipeline) owns operator-selected Audita values.
+- Implementation and tests: `internal/stage/polish.go`,
+  `internal/stage/polish_test.go`,
+  `internal/stage/semantic_contracts_refinement.go`

docs/internal/stage-prepare.md

@@ -1,74 +1,99 @@
 # Stage: prepare
 
 ## Purpose
-Materialize all required session inputs into canonical local workspace paths and record input provenance in the session manifest.
 
-## Inputs and Outputs
-Inputs:
-- `session.yml` (resolved session config)
-- `pipeline.resolved.yml` (materialized from resolved pipeline config)
-- `speakers.yml`
-- `autocorrect.yml`
-- `glossary.yml`
-- audio source:
-  - local (`session.inputs.audio_dir` or `session.inputs.audio_files`), or
-  - S3 (`session.inputs.audio_s3.prefix`)
+Materialize canonical current-session inputs before processing stages.
 
-Outputs:
+## Inputs
+
+- 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
+
+## Outputs
+
+- `inputs/campaign.yml`
 - `inputs/session.yml`
 - `inputs/pipeline.resolved.yml`
 - `inputs/speakers.yml`
 - `inputs/autocorrect.yml`
 - `inputs/glossary.yml`
-- `audio/*.flac` in session workdir
-- `manifest.Inputs` records with checksums and source metadata
+- `inputs/players.yml`
+- `inputs/party.yml`
+- optional `inputs/spell_catalog.json`
+- `audio/*.flac`
+- optional `previous/manifest.json`
+- optional `previous/artifacts/**`
+- deterministic `manifest.inputs` entries (checksums + provenance)
 
-## Boundaries
-Owns:
-- Input path resolution and validation
-- Local copy/materialization of configs and audio files
-- S3 audio download to run-scoped spool, then copy into work audio dir
+## Key Behavior
 
-Does not own:
-- Transcript generation/processing
-- Archive publish behavior
+- validates required config/store state.
+- enforces local audio vs S3 audio mutual exclusivity.
+- rejects duplicate explicit local audio sources after resolution.
+- 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.
+- copies the validated canonical party bytes unchanged and deterministically
+  generates the prepared players projection.
+- 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;
+  - downloads previous manifest/artifacts;
+  - records previous inputs in `manifest.inputs`.
 
-## Config Fields Used
-- `session.session_id`
-- `session.campaign`
-- `session.inputs.speakers_file`
-- `session.inputs.autocorrect_file`
-- `session.inputs.glossary_file`
-- `session.inputs.audio_dir`
-- `session.inputs.audio_files`
-- `session.inputs.audio_s3.prefix`
-- `pipeline.workspace.root`
-- `pipeline.spool.root`
-- `pipeline.storage.s3.bucket`
-- `pipeline.storage.s3.root_prefix`
+Required previous-session inputs fail when unavailable; optional missing inputs
+are typed skipped results. Each requirement resolves only from its unique
+`published_output` declaration in the pointer-selected remote commit. Prepare
+strips that selected run's immutable `published/` prefix to derive the local
+cache path, then validates the committed checksum, size, and generation.
 
-## External Adapters Used
-- Object storage backend (`env.ObjectStore`) for S3 audio list/download when `audio_s3` is configured.
+## Invariants
 
-## State and Manifest Behavior
-- Ensures workspace layout exists.
-- Writes resolved config and input files to canonical `inputs/` paths.
-- Records all prepared inputs into `manifest.Inputs` (sorted deterministically by kind/path).
-- For S3 audio, records `S3Bucket`, `S3Key`, `S3Size`, `S3ETag`, and `SpoolPath` in each audio input record.
+- only `prepare` hydrates canonical `previous/` cache state.
+- managed previous artifacts are stored under `previous/artifacts/**` without
+  duplicate `artifacts/artifacts/` nesting.
+- managed `previous/` state represents only the current requirement set.
+- `manifest.inputs` ordering is deterministic (`kind`, `path`).
 
-## Skip and Resume Behavior
-- Runner-level skip applies when stage already `succeeded` and `--force` is not set.
-- Stage itself is deterministic/idempotent for unchanged inputs (`copyFileIfChanged`, `writeBytesIfChanged`).
+## Resume Evidence
 
-## Failure Behavior
-- Fails on missing required files, invalid audio source combinations, no discoverable `.flac` files, duplicate audio basenames, missing object store for S3 mode, or S3 list/download failures.
+Prepare records a versioned semantic-configuration fingerprint for the
+resolved campaign/session selection, local-versus-S3 audio mode and canonical
+audio names, stable-input ownership/presence, previous-session identity, and
+the party mode plus canonical players projection version, and the effective
+previous-artifact requirement set. A change reruns prepare and
+stales its fixed descendants. Existing successful records without this
+evidence rerun once when selected.
 
-## Tests to Inspect Before Changing
-- `internal/stage/prepare_test.go`
-- `internal/app/session_cli_test.go`
-- `internal/config/load_validate_test.go`
+Workspace, spool, and cache placement and absolute source relocation are not
+semantic when logical selection, canonical names, and bytes are equivalent.
+The fingerprint deliberately does not read or rehash large audio. Prepared
+input checksums remain the content provenance. Before reusing success, prepare
+validates every durable prepared copy and compares current stable-input bytes,
+canonical party and derived-player bytes, local audio membership/checksums, or
+S3 key/size/entity-tag identity with that provenance. Source relocation with
+equivalent names and bytes remains reusable; changed or unavailable evidence
+causes a normal prepare rerun.
 
-## Architectural Invariants
-- `audio_dir`/`audio_files` and `audio_s3` are mutually exclusive.
-- Audio files must be `.flac`.
-- Canonical `inputs/*` and `audio/*` paths are the durable source for downstream stages.
+## Related Contracts And Tests
+
+- [Configuration](../config.md) owns audio selection, stable input fields, and
+  previous-session settings.
+- [Operations](../operations.md) owns physical input, audio, spool, cache, and
+  previous-state layout.
+- [Storage Internals](storage.md) and [Artifact Internals](artifacts.md) explain
+  the internal collaborators.
+- Implementation and tests: `internal/stage/prepare.go`,
+  `internal/stage/prepare_test.go`,
+  `internal/stage/prepare_resume.go`,
+  `internal/stage/prepare_resume_test.go`,
+  `internal/stage/semantic_contracts_initial.go`,
+  `internal/stage/semantic_contracts_initial_test.go`,
+  `internal/audio/s3_audio_test.go`,
+  `internal/previouscache/*_test.go`

docs/internal/stage-publish.md

@@ -0,0 +1,147 @@
+# Stage: publish
+
+## Purpose
+
+Upload run/session outputs to object storage and atomically advance remote current state.
+
+## Inputs
+
+- successful preceding stages from the [canonical stage set](overview.md#pipeline-stage-set)
+- declared run-local diagnostic files
+- resolved publish output rules
+- independent per-source remote lock objects read at planning start
+- the validated prior current commit when an initially locked source may carry
+- durable previous-session cache files when present
+
+## Outputs
+
+- uploaded session manifest, declared run-local diagnostics, and selected
+  publish outputs;
+- uploaded durable previous-session cache files when present;
+- immutable run-scoped commit manifest; and
+- current commit pointer, written last.
+
+Exact remote placement and the operator workflow belong in
+[Operations](../operations.md#publish-workflow).
+
+## Key Behavior
+
+`publish.go` retains the transaction-owning `Run` path. Source discovery,
+manifest-derived archive metadata, confined opening, and checksum validation
+live in `publish_sources.go`; artifact-catalog matching, selection, required
+and optional rules, destination resolution, and collision inputs live in
+`publish_outputs.go`. Copying, hashing, immutable upload, reuse checks, and
+remote verification live in `publish_transfer.go`; committed-manifest,
+immutable-commit, and current-pointer encoding and writes live in
+`publish_commit.go`. `publish_output_plan.go` owns the deterministic, I/O-free
+five-outcome model and its secret-free metadata projection.
+
+- when publishing or run upload is disabled, completes successfully with no
+  outputs and records explanatory metadata. This is not an explicit self-skip:
+  the session manifest records success. Enablement and upload policy are
+  fingerprinted, so changing either automatically makes the prior result
+  non-resumable.
+- validates prerequisite stage success and object-store availability.
+- derives a deterministic run-archive allowlist from the session manifest's
+  declared current-run outputs, logs, and generated configurations. References
+  outside the current run root, including canonical session files and prior-run
+  diagnostics, are not archive candidates. No distinguished diagnostic file is
+  read or uploaded.
+- opens each archive candidate beneath its archive root without following
+  symlinked ancestors or leaf entries, verifies that it is a regular file and
+  checks a declared checksum when present, then streams the opened descriptor.
+- derives the durable previous-cache archive from its validated manifest using
+  the same confinement and regular-file checks.
+- resolves publish output sources through runtime artifact catalog and
+  manifest-aware resolution. Configured Scriptorium outputs are publishable
+  only from validated `current` per-artifact analyze evidence; an incidental
+  canonical file, aggregate output, stale/failed/unselected record, or
+  mismatched path, size, or checksum remains unavailable. Built-in and
+  extraction sources likewise require their own current manifest evidence.
+- publishes extraction lanes only through explicit configured output rules;
+  neither run-local nor durable Notarius bundles are scanned or uploaded wholesale.
+- selected artifact filter applies to configured artifact sources only.
+- plans every configured output into exactly one source-sorted outcome:
+  `published`, `carried_locked`, `locked_unpublished`, `optional_missing`, or
+  `unselected`.
+- an initially locked selected output carries its exact prior
+  `published_output` declaration when one exists. The declaration may point to
+  an earlier run in the same session and retains its source, key, checksum,
+  size, and generation; the bytes are not copied.
+- verifies a carried object's exact key, size, and generation through object
+  metadata without downloading or opening the local output source.
+- an initially locked source with no prior declaration remains absent even
+  when the output rule is required. Optional missing unlocked outputs remain
+  absent; required missing unlocked outputs fail.
+- creates one complete immutable source-to-destination mapping before upload;
+- uploads and verifies every declared immutable object and the commit manifest;
+- writes the immutable commit from the combined new and exact carried
+  declarations.
+- rereads every initially unlocked participating source after the immutable
+  commit. A newly present lock aborts selection, leaving the uploaded immutable
+  attempt unselected. Removing an initial lock may conservatively produce one
+  carry because the initial snapshot controls the plan.
+- updates `current/commit-pointer.json` exactly once, last, and writes no other
+  mutable publication control record.
+
+## Metadata Signals
+
+Includes counts/lists for:
+- run uploads
+- published output uploads
+- previous uploads
+- one `publish_output_outcomes` collection containing all five output states,
+  exact declared keys, and key-derived origin runs where applicable
+- remote commit and current-pointer key paths
+- the run identifier selected by the commit
+
+## Invariants
+
+- `current/commit-pointer.json` is the remote commit marker and is written last.
+- run files, selected outputs, previous-cache files, and the committed session
+  manifest are all declared by an immutable commit under the run prefix.
+- run and previous uploads contain only manifest-declared regular files opened
+  from verified descriptors; symlinks, special files, replacement races, and
+  undeclared entries are rejected or ignored before uploads begin.
+- run-local diagnostics, including Notarius receipt and stderr files, are
+  archived only when recorded by the session manifest. A run with no declared
+  current-run diagnostics legitimately uploads none.
+- independent publish locks are not overridden by `--force`; every initially
+  unlocked relevant source is reread immediately before current-state
+  selection.
+- successful uploaded publication records the exact run ID, remote commit key,
+  and current-pointer key consumed by the later cleanup stage.
+
+## Resume Semantics
+
+The versioned semantic fingerprint covers enabled behavior, run-upload policy,
+normalized source/destination/required output rules, and the remote backend,
+bucket, region, endpoint, and root-prefix identity. Rule ordering is
+canonicalized. Credential
+environment names, path-addressing transport mode, local workspace placement,
+and run identifiers are excluded. Independent remote locks remain mutable state
+and are read directly by publish at planning and commit boundaries; semantic
+evidence does not replace those safety checks.
+
+The commit boundary and cleanup authorization are normative architecture invariants; see
+[Architecture](../policy/architecture.md#publish-commit-boundary).
+
+Publish never deletes local state. The standalone `publish` command selects
+only this stage; a full run selects notify and cleanup afterward.
+
+## Related Contracts And Tests
+
+- [Configuration](../config.md#publish-configuration-summary) owns output
+  rules.
+- [Operations](../operations.md#publish-locks) owns remote lock lifecycle and
+  physical remote state.
+- [Artifact Internals](artifacts.md) explains source resolution and current-state
+  helpers.
+- Implementation and tests: `internal/stage/publish.go`,
+  `internal/stage/publish_sources.go`, `internal/stage/publish_outputs.go`,
+  `internal/stage/publish_output_plan.go`,
+  `internal/stage/publish_transfer.go`, `internal/stage/publish_commit.go`,
+  `internal/stage/publish_test.go`,
+  `internal/stage/semantic_contracts_delivery.go`,
+  `internal/app/operator_helpers_test.go`, and
+  `internal/app/cleanup_orchestration_test.go`

docs/internal/stage-render.md

@@ -0,0 +1,60 @@
+# Stage: render
+
+## Purpose
+
+Render Markdown transcript artifacts from normalized JSON transcripts via Seriatim.
+It runs after `trim` and before `extract` in the canonical sequence. Render and
+extract are independent sibling consumers: replacing render output does not
+invalidate extraction, but it does invalidate succeeded analysis and delivery
+records that may consume rendered transcripts.
+
+## Inputs
+
+- `narratio.transcript.final` (`transcripts/final.json`)
+- `narratio.transcript.final_trimmed` (`transcripts/final.trimmed.json`)
+
+## Outputs
+
+- `narratio.transcript.final_markdown` -> `transcripts/final.md`
+- `narratio.transcript.final_trimmed_markdown` -> `transcripts/final.trimmed.md`
+
+## Key Behavior
+
+- uses `pipeline.render` settings (enabled/format/title/booleans).
+- resolves inputs only from verified manifest output evidence.
+- writes run-local outputs first, then materializes canonical session outputs.
+- records input provenance, output paths, adapter metadata, logs, and generated config refs.
+- when `pipeline.render.enabled=false`, completes successfully with no outputs
+  and records explanatory metadata. This is not an explicit self-skip: both
+  manifests record success. Because enablement is fingerprinted, enabling
+  render later automatically makes the prior result non-resumable.
+
+## Failure Semantics
+
+- missing normalized input fails with normalize rerun guidance.
+- missing trimmed input fails with trim rerun guidance.
+- adapter/subprocess failure fails stage.
+- empty render output files fail validation.
+
+## Invariants
+
+- only `format: markdown` is supported.
+- render stage owns production of built-in Markdown transcript sources.
+
+## Resume Semantics
+
+The versioned semantic fingerprint covers enablement, final format, resolved
+title (including the session-title fallback), timestamp, segment-ID and
+metadata inclusion, both canonical input identities, and both Markdown output
+identities. Seriatim's executable, timeout, and report behavior are operational
+and do not invalidate rendered transcripts. A render-only change leaves the
+independent `extract` sibling reusable while invalidating their shared
+downstream consumers.
+
+## Related Contracts And Tests
+
+- [Seriatim](../integrations/seriatim.md) owns render subprocess behavior.
+- [Configuration](../config.md#pipeline) owns render fields and defaults.
+- Implementation and tests: `internal/stage/render.go`,
+  `internal/stage/render_test.go`,
+  `internal/stage/semantic_contracts_refinement.go`

docs/internal/stage-transcribe.md

@@ -1,58 +1,56 @@
 # Stage: transcribe
 
 ## Purpose
-Generate per-speaker raw transcripts from prepared audio using WhisperX.
 
-## Inputs and Outputs
-Inputs:
-- `audio/*.flac` prepared by `prepare`
+Generate raw per-speaker transcripts from prepared audio using WhisperX.
 
-Outputs:
-- `transcripts/raw/<speaker>.json` for each input audio file
+## Inputs
 
-## Boundaries
-Owns:
-- Discovering prepared audio inputs
-- Deriving speaker ids from audio basenames
-- Parallel WhisperX invocation with bounded concurrency
-- Validating produced JSON and promoting run-local outputs
+- `audio/*.flac` from `prepare`
 
-Does not own:
-- Transcript merge/polish/normalize/trim/analyze
+## Outputs
 
-## Config Fields Used
-- `session.session_id`
-- `session.campaign`
-- `pipeline.workspace.root`
-- `pipeline.whisperx.transcribe_url`
-- `pipeline.whisperx.language`
-- `pipeline.whisperx.timeout`
-- `pipeline.whisperx.retries`
-- `pipeline.whisperx.retry_delay`
-- `pipeline.whisperx.concurrency`
+- `transcripts/raw/<speaker>.json`
 
-## External Adapters Used
-- WhisperX adapter (`env.WhisperX.Transcribe`).
+## Key Behavior
 
-## State and Manifest Behavior
-- Uses run-local output paths under `runs/{run_id}/transcribe/outputs/...` when run layout is enabled.
-- Validates each generated transcript JSON before promotion.
-- Promotes canonical outputs to `transcripts/raw/*.json`.
-- Records per-file metadata (attempts/status/duration/output path) in stage metadata.
+- discovers prepared audio from manifest inputs or canonical audio directory.
+- derives the transcript identity from the prepared `.flac` filename.
+- dispatches one WhisperX request per prepared file through a bounded errgroup.
+- validates each output as JSON.
+- writes run-local outputs then materializes canonical transcript outputs only
+  after every planned request succeeds.
 
-## Skip and Resume Behavior
-- Runner-level skip applies for previously succeeded stage unless forced.
-- On forced upstream reruns, downstream succeeded stages can be marked `stale` by runner logic.
+## Invariants
 
-## Failure Behavior
-- Fails if no prepared audio exists, duplicate speaker basenames are detected, adapter output path mismatches expected path, any output JSON is invalid, or one worker fails.
-- Cancels in-flight workers after first terminal error.
+- prepared audio identities must be unique; prepare disambiguates distinct
+  source paths that share a basename.
+- output path returned by adapter must match requested output path.
+- an empty adapter result path means the requested path; adapters cannot select
+  an alternate destination.
+- each successful output is validated before stage success, and cancellation or
+  incomplete dispatch cannot be reported as a successful result.
 
-## Tests to Inspect Before Changing
-- `internal/stage/transcribe_test.go`
-- `internal/app/whisperx_wiring_test.go`
+## Resume Evidence
 
-## Architectural Invariants
-- Speaker identity is derived from `.flac` basename and must be unique.
-- Every successful speaker output must be valid JSON before promotion.
-- Canonical raw transcript set is the only supported merge input surface.
+Transcribe records a versioned semantic-configuration fingerprint containing
+the Narratio-visible WhisperX service URL and recognition language. Changes to
+either rerun transcription and stale its fixed descendants while leaving
+prepare reusable. Retry count/delay, concurrency, timeout, credentials, and
+diagnostic locations are operational and do not change this evidence.
+
+WhisperX models or private service configuration not exposed by Narratio's
+adapter contract cannot be fingerprinted; use `--force` after changing them.
+An existing successful transcribe record without evidence reruns once when
+selected.
+
+## Related Contracts And Tests
+
+- [WhisperX](../integrations/whisperx.md) owns HTTP, retry, timeout, and
+  cancellation semantics.
+- [Configuration](../config.md#pipeline) owns concurrency and other
+  operator-selected values.
+- Implementation and tests: `internal/stage/transcribe.go`,
+  `internal/stage/transcribe_test.go`,
+  `internal/stage/semantic_contracts_initial.go`, and
+  `internal/stage/semantic_contracts_initial_test.go`

docs/internal/stage-trim.md

@@ -1,75 +1,57 @@
 # Stage: trim
 
 ## Purpose
-Optionally trim the normalized transcript to session bounds; always produce a durable trimmed transcript.
 
-## Inputs and Outputs
-Inputs:
-- `transcripts/normalized.json`
+Produce a final-trimmed transcript. By default, the stage generates bounds and
+applies a bounds-driven trim.
 
-Outputs:
-- `transcripts/trimmed.json` (or configured trim output path)
+## Inputs
+
+- `transcripts/final.json`
+
+## Outputs
+
+- `transcripts/final.trimmed.json` (or configured trim output path)
 - when trim enabled: `artifacts/session_bounds.json`
 
-## Boundaries
-Owns:
-- Trim-enabled switch behavior
-- Bounds generation via Scriptorium artifact run
-- Bounds validation against normalized transcript
-- Keep-selector derivation and Seriatim trim invocation
-- Copy-through behavior when disabled or bounds indicate unchanged transcript
+## Key Behavior
 
-Does not own:
-- Upstream normalization
-- Downstream artifact analysis
+When `trim.enabled=true`:
+- runs Scriptorium bounds artifact generation;
+- optionally runs render-debug output generation;
+- validates bounds payload against transcript;
+- derives keep selector;
+- either copies unchanged transcript or runs Seriatim trim;
+- validates trimmed transcript and materializes bounds output.
 
-## Config Fields Used
-- `session.session_id`
-- `session.campaign`
-- `pipeline.workspace.root`
-- `pipeline.trim.enabled`
-- `pipeline.trim.output_path`
-- `pipeline.trim.bounds.prompt_id`
-- `pipeline.trim.bounds.profile_id`
-- `pipeline.trim.bounds.timeout`
-- `pipeline.trim.bounds.output_path`
-- `pipeline.trim.bounds.transcript_input_name`
-- `pipeline.trim.bounds.render_debug`
-- `pipeline.trim.bounds.render_output_path`
-- `pipeline.seriatim.binary`
-- `pipeline.seriatim.timeout`
-- `pipeline.scriptorium.binary`
-- `pipeline.scriptorium.config_path`
-- `pipeline.scriptorium.timeout`
+When `trim.enabled=false`:
+- copies normalized transcript to trimmed output.
 
-## External Adapters Used
-- Scriptorium adapter:
-  - optional `RenderArtifact` for bounds debug render
-  - `RunArtifact` for bounds output
-- Seriatim adapter:
-  - `Trim` when bounds indicate trimming is required
+## Invariants
 
-## State and Manifest Behavior
-- Reads normalized transcript from normalize manifest outputs when available; falls back to canonical path.
-- Uses run-local outputs/logs/reports/config/scratch paths when run layout is enabled.
-- Promotes canonical trimmed transcript; promotes session bounds when trim enabled.
-- Records bounds diagnostics, trim action, keep selector, and adapter metadata.
+- normalized transcript is required input.
+- bounds output exists only in enabled trim path.
+- render-debug output is diagnostic and not a declared stage output.
 
-## Skip and Resume Behavior
-- Runner-level skip applies when already succeeded and not forced.
-- Forced reruns can stale downstream succeeded stages.
-- When `trim.enabled=false`, stage still succeeds by copying normalized to trimmed output.
+## Resume Semantics
 
-## Failure Behavior
-- Fails on missing/invalid normalized transcript.
-- With trim enabled, fails on missing adapters/config, bounds generation/validation errors, invalid bounds JSON, invalid range/segment ids, trim adapter failures, or invalid trimmed output.
+The versioned semantic fingerprint covers enablement, the bounds prompt and
+profile identifiers, the Scriptorium configuration identity, transcript input
+name, sticky session variable, bounds and trimmed output identities, and the
+Seriatim trim operation. Diagnostic bounds rendering, diagnostic output paths,
+timeouts, executable paths, and optional reports are operational and do not
+invalidate the canonical trimmed transcript.
 
-## Tests to Inspect Before Changing
-- `internal/stage/trim_test.go`
-- `internal/adapters/scriptorium/subprocess_test.go`
-- `internal/adapters/seriatim/subprocess_test.go`
+Narratio cannot inspect prompt, profile, or configuration content that
+Scriptorium or Seriatim privately resolves behind a stable identifier. Force
+`trim` after changing such private content without changing its identifier.
 
-## Architectural Invariants
-- Trim never falls back to processed transcript; normalized transcript is required input.
-- `session_bounds` output exists only for enabled trim path.
-- Render-debug artifacts are diagnostics and not declared stage outputs.
+## Related Contracts And Tests
+
+- [Scriptorium](../integrations/scriptorium.md) owns bounds generation and
+  debug-render subprocess behavior.
+- [Seriatim](../integrations/seriatim.md) owns transcript trimming behavior.
+- [Configuration](../config.md#pipeline) owns trim fields and defaults.
+- Implementation and tests: `internal/stage/trim.go`,
+  `internal/stage/trim_test.go`,
+  `internal/stage/semantic_contracts_refinement.go`

docs/internal/storage.md

@@ -1,71 +1,72 @@
 # Internal: Storage
 
 ## Purpose
-Document Narratio's remote storage backend contracts and implementations under `internal/adapters/storage`.
 
-## Inputs and outputs
-Inputs:
-- Resolved storage config (`pipeline.storage.*`).
-- Bucket-relative object keys and local file paths from stage/app orchestration.
+Explain the object-store interface and S3 implementation used by Narratio.
+Remote key layout and lifecycle belong in [Operations](../operations.md), while
+operator-selected storage fields and credential mechanisms belong in
+[Configuration](../config.md).
 
-Outputs:
-- Listed/downloaded/uploaded object metadata (`ObjectInfo`).
-- Existence checks and storage-layer errors.
+## Primary Contract
 
-## Boundaries
-Owns:
-- Remote object-store interface and implementation details.
-- S3 client wiring and API calls.
-- Object key normalization and upload/download/list primitives.
+`storage.ObjectStore` interface:
 
-Does not own:
-- Session/run prefix semantics.
-- Archive commit order semantics.
-- Manifest updates.
+- `List(ctx, prefix)`
+- `Read(ctx, key)` returns an object body and the generation observed with it
+- `Download(ctx, key, localPath)`
+- `Upload(ctx, localPath, key, opts)`
+- `UploadConditional(ctx, source, key, opts, condition)`
+- `Delete(ctx, key)` removes one object and succeeds when it is already absent
+- `Exists(ctx, key)`
 
-## Config fields used
-- `pipeline.storage.backend`
-- `pipeline.storage.s3.bucket`
-- `pipeline.storage.s3.region`
-- `pipeline.storage.s3.endpoint`
-- `pipeline.storage.s3.force_path_style`
-- `pipeline.storage.s3.access_key_id_env`
-- `pipeline.storage.s3.secret_access_key_env`
+Key invariant:
+- callers pass full bucket-relative keys;
+- storage implementations do not infer campaign/session/run prefixes.
 
-## External adapters used
-Storage package contracts:
-- `ObjectStore` (active remote object-store boundary): `List`, `Download`, `Upload`, `Exists`.
-- `Backend` (archive request boundary): currently implemented with `NoopBackend` only.
+`ReadObjectBounded` is the shared mechanism for small control objects. It opens
+one object version, returns the metadata observed with that body, rejects an
+oversized known size before transfer, and still performs a context-aware
+limit-plus-one read. It closes the body on every exit. Callers own the policy
+limit and add the control-object category to errors; this helper is not used for
+large artifact payloads.
 
-Implementations:
-- `S3Backend`: AWS SDK-backed `ObjectStore` implementation.
-- `FakeBackend`: deterministic test `ObjectStore` and archive backend.
-- `NoopBackend`: deterministic no-op archive backend for compatibility wiring.
+## Composition
 
-## State and manifest behavior
-- Storage implementations are stateless with respect to manifest/session lifecycle.
-- Caller supplies fully-qualified bucket-relative keys.
-- Storage layer does not infer campaign/session/run/root-prefix semantics.
-- Caller controls publish ordering; storage layer executes individual operations in the order invoked.
+`NewObjectStoreFromConfig` constructs the S3-backed implementation from
+resolved configuration. The application loads configured filesystem secrets
+before calling it. The storage adapter consumes already-resolved values; it does
+not own discovery, defaults, or configuration validation.
 
-## Skip and resume behavior
-- No storage-level skip/resume behavior.
-- Skip/resume decisions are made by stage/app logic before storage calls occur.
+## S3 Backend Behavior
 
-## Failure behavior
-- `NewObjectStoreFromConfig` fails when no remote backend is configured or required S3 config is missing.
-- `S3Backend` constructor fails when required bucket is missing or AWS client setup fails.
-- CRUD operations return contextual errors (including not-found behavior via `Exists`).
-- Key normalization is applied before operations (`\\` to `/`, leading slash trimmed).
+- normalizes object keys.
+- `List` paginates and returns normalized `ObjectInfo`.
+- A truncated S3 listing must supply a new, non-empty continuation token;
+  otherwise listing fails with bucket and prefix context instead of looping.
+- `Download` writes local files with parent directory creation.
+- `Upload` streams local file and returns remote metadata.
+- `Read` binds a returned body to its S3 ETag. `UploadConditional` maps an ETag
+  match or absence precondition directly to the provider request and reports a
+  failed precondition without performing a local check-then-write replacement.
+- `Delete` maps one normalized key to the provider delete-object operation and
+  treats an absent object as success.
+- `Exists` maps not-found responses to `false`.
 
-## Tests to inspect before changing
-- `internal/adapters/storage/factory_test.go`
-- `internal/adapters/storage/s3_backend_test.go`
-- `internal/adapters/storage/fake_test.go`
-- `internal/adapters/storage/keys_test.go`
-- `internal/adapters/storage/archive.go` + consumers in stage tests (`prepare`, `archive`)
+## Invariants
 
-## Architectural invariants
-- Callers pass full bucket-relative keys.
-- Storage backends must not prepend or infer narratio prefixes.
-- Remote transport details remain isolated to storage adapter implementations.
+- storage layer is stateless regarding manifest/stage progression.
+- bounded reads never retain more than the caller's limit plus one byte and do
+  not replace owner-specific size policy.
+- publish ordering semantics are owned by stage/app code, not storage adapters.
+- A caller that installs remote content into a canonical workspace path first
+  writes a sibling temporary file, validates the complete object against its
+  owner-specific contract, and only then replaces the destination. Temporary
+  files used solely for remote comparisons are removed by their callers and do
+  not represent installed workspace state.
+
+## Implementation And Tests
+
+- Contract and S3 adapter: `internal/adapters/storage`
+- Composition: `internal/app/object_store.go`
+- Tests: `internal/adapters/storage/*_test.go`,
+  `internal/app/object_store_test.go`

docs/internal/workspace.md

@@ -1,68 +1,103 @@
-# Workspace internals
+# Internal: Workspace
 
 ## Purpose
-Define the local durable and run-local workspace model used by stages, manifests, resume, and archive.
 
-## Inputs and Outputs
-Inputs:
-- `pipeline.workspace.root`
-- `session.campaign`
-- `session.session_id`
-- generated `run_id`
+Explain the helpers that construct local session and run paths, coordinate
+single-writer access, and confine cleanup. The authoritative physical layout and
+retention workflow belong in [Operations](../operations.md#local-state-layout).
 
-Outputs:
-- Session manifest at `{workspace.root}/work/{campaign}/{session_id}/manifest.json`
-- Run manifest at `{workspace.root}/work/{campaign}/{session_id}/runs/{run_id}/manifest.json`
-- Canonical durable session directories and run-local stage trees
+## Path Ownership
 
-## Boundaries
-Owns:
-- Session-level path layout (`inputs/`, `audio/`, `transcripts/`, `artifacts/`, `reports/`, `logs/`, `config/`, `current/`, `runs/`)
-- Run-local stage sandbox layout under `runs/{run_id}/{stage}/`
-- Session lock acquisition/release (`.lock`)
+`internal/artifacts` owns canonical session, run, spool, cache, and
+previous-cache path construction. `SessionPathsFor` provides the session-scoped
+path model, and layout creation goes through `EnsureLayoutFor`. Callers should
+consume those helpers instead of rebuilding relative paths.
 
-Does not own:
-- Stage business logic
-- Remote archive semantics (documented in `stage-archive.md`)
-- CLI argument parsing
+`internal/pathsafe` validates relative destinations. `internal/fileops` opens
+explicit cleanup roots and removes only normalized proper descendants through
+the resulting root handle.
 
-## Config Fields Used
-- `pipeline.workspace.root`
-- `pipeline.workspace.cleanup_after_archive`
-- `pipeline.spool.root`
-- `pipeline.spool.delete_audio_after_archive`
-- `session.campaign`
-- `session.session_id`
+`internal/fileops` owns the ordinary workspace mode contract. On POSIX,
+`WorkspaceDirectoryMode` is setgid `02775` and `WorkspaceFileMode` is `0664`.
+`EnsureWorkspaceDirectory` reapplies the directory mode after creation so a
+restrictive umask cannot remove group access, while retaining existing ownership
+and group. Credential paths are outside this contract; the platform-specific
+operational requirements are in [Operations](../operations.md#workspace-permissions).
 
-## External Adapters Used
-None directly in this subsystem. Stages may use object storage adapters and then write local outputs into this layout.
+## Run-Local Stage Layout
 
-## State and Manifest Behavior
-- Session state is persisted in the session manifest (`manifest.Manifest`).
-- Invocation history is persisted per run in run manifests under `runs/{run_id}/manifest.json`.
-- During each run, stage outputs are often written run-local first (`runs/{run_id}/{stage}/outputs/...`) and promoted to canonical session paths after stage success.
-- `manifest.Artifacts` entries record `ProducerRunID` for durable outputs.
-- For S3 audio sessions, `prepare` records spool/work paths and S3 provenance in `manifest.Inputs`.
+`internal/stage/run_local.go` maps stage outputs and diagnostics into an
+invocation-scoped layout. Successful outputs are validated and atomically
+materialized into canonical session paths before stage success. Managed
+previous-session cache paths remain session-durable and are never redirected
+into run-local output space.
 
-## Skip and Resume Behavior
-- Skip/resume decisions are made in `internal/app` (`run_control.go`, `resume.go`) using stage status in the session manifest.
-- `--force` reruns selected stages and marks downstream previously-succeeded stages as `stale`.
-- Workspace layout is idempotent (`EnsureLayoutFor`) and reused across runs.
+Extraction uses run-local receipt, stderr, and output-root helpers, then
+validates and renames the external bundle to the unique immutable Notarius
+bundle path supplied by `internal/artifacts`. Exact physical paths belong in
+[Operations](../operations.md#extraction-workflow).
 
-## Failure Behavior
-- Failures preserve manifests and run-local files for inspection.
-- Lock conflicts fail fast via `ErrLockConflict`.
-- Cleanup can fail post-archive; failure is recorded in archive stage metadata and returned by the run.
+Prepared references delivered to Notarius use session-durable paths owned by
+`internal/artifacts` beneath
+`cache/notarius/references/<sha256>/<prepared-basename>`. These verified
+content-addressed snapshots are outside run-local layout, survive ordinary
+published-run cleanup, and are excluded from publish and restore enumeration.
 
-## Tests to Inspect Before Changing
-- `internal/artifacts/local_test.go`
-- `internal/stage/run_local_test.go`
-- `internal/app/run_control_test.go`
-- `internal/app/resume_run_stage_test.go`
-- `internal/app/post_archive_cleanup_test.go`
+## Locking
 
-## Architectural Invariants
-- Session root is campaign-aware: `{workspace.root}/work/{campaign}/{session_id}`.
-- Run roots are always nested: `runs/{run_id}` under the session root.
-- Run-local output promotion must end in canonical session paths.
-- Cleanup only targets run-scoped directories and must never delete configured root directories.
+`artifacts.LocalStore` enforces the single-writer session lock via an
+operating-system lock held on `.lock` (`ErrLockConflict` on contention). The
+file retains owner metadata after release or process death; its existence is
+not evidence that a lock is active. Command and restore flows wait for this
+lock only while their context remains active, and report a release failure.
+
+The runner assigns every invocation a run-workspace identity but creates the
+physical directory only before an executing stage that requires it. Fully
+reused invocations and cleanup-only invocations therefore do not accumulate
+empty run directories.
+
+## Cleanup Semantics
+
+The canonical cleanup stage:
+
+- runs after notify only when selected by the invocation range;
+- requires a succeeded publish record with `uploaded=true`, the published run
+  ID, remote commit key, and current commit-pointer key;
+- consumes the resolved cleanup policy described in
+  [Configuration](../config.md);
+- refuses unsafe deletes (root delete, traversal, and out-of-root targets);
+- treats missing targets as successful, idempotent deletion; and
+- uses its ordinary failed/succeeded manifest stage record for retry. A later
+  full run can skip reusable upstream stages and retry cleanup without
+  republishing.
+
+Manual cleanup uses the same root-confined deletion mechanism. Invocation
+syntax and exact deletion scope belong in [CLI](../cli.md#clean) and
+[Operations](../operations.md#cleanup).
+
+## Invariants
+
+- campaign-aware session root is mandatory.
+- manifest-driven stage state is durable across runs.
+- cleanup guardrails prevent destructive root/out-of-scope deletion.
+- restore installation is confined to validated relative paths beneath the
+  selected session root.
+- ordinary workspace paths retain group-writable directory and file modes across
+  nested creation, replacement, and Notarius promotion.
+
+## Implementation And Tests
+
+- Path model and local store: `internal/artifacts/paths.go`,
+  `internal/artifacts/local.go`
+- Run-local materialization: `internal/stage/run_local.go`
+- Immutable bundle installation: `internal/stage/extract.go`
+- Workspace modes: `internal/fileops/modes.go`
+- Cleanup confinement: `internal/fileops/cleanup.go`,
+  `internal/stage/cleanup.go`, `internal/stage/cleanup_plan.go`, and
+  `internal/app/cleanup_targets.go`
+- Tests: `internal/artifacts/paths_model_test.go`,
+  `internal/artifacts/local_test.go`, `internal/stage/run_local_test.go`,
+  `internal/fileops/modes_posix_test.go`,
+  `internal/fileops/cleanup_test.go`, `internal/app/cleanup_targets_test.go`,
+  `internal/stage/cleanup_test.go`, and
+  `internal/app/cleanup_orchestration_test.go`

docs/operations.md

@@ -1,149 +1,689 @@
-# Operations
+# Operations Guide
 
-This guide describes the implemented operator lifecycle for Narratio.
+Operator workflow for running, recovering, and publishing Narratio sessions.
 
-For field-level configuration, see [docs/config.md](./config.md). For full command/flag reference, see [docs/cli.md](./cli.md).
+For command syntax, see [docs/cli.md](./cli.md). For field-level config, see [docs/config.md](./config.md).
 
-## Normal workflow (S3-first path)
+## Campaign and Session Selection
 
-1. Upload session `.flac` files to object storage under the session audio prefix.
-2. Run Narratio:
+Campaign selection priority:
+
+- `--campaign-file`
+- `--campaign`
+- `pipeline.campaigns.default_campaign_id`
+
+Session source priority:
+
+- `--session`
+- local default search paths
+- remote session object (S3) when local session file is not found and storage is configured
+
+## Session Initialization
+
+Use `session init` to generate a concrete session file for local or remote use.
+
+Local file:
 
 ```bash
-narratio run --session-id 2026-04-04
+narratio session init 2026-04-04 --output ./session.yml --date 2026-04-04 --title "Session 12"
 ```
 
-3. Read success output:
-- `narratio run: session <session_id>; executed=<n> skipped=<n>; manifest=<path>`
-- use `manifest=<path>` with `status` for inspection.
+Remote session object:
 
-Notes:
-- default config/session discovery applies unless `--config` and `--session` are passed.
-- S3 audio mode requires `session.inputs.audio_s3.prefix` and valid object-store access.
+```bash
+narratio session init 2026-04-04 --remote --force
+```
 
-## Local filesystem layout and state artifacts
+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, 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
+
+1. Select pipeline/campaign/session config.
+2. Validate session readiness:
+
+```bash
+narratio session validate 2026-04-04
+```
+
+3. (Optional) inspect stage decisions:
+
+```bash
+narratio session plan 2026-04-04
+```
+
+4. Run the pipeline:
+
+```bash
+narratio run 2026-04-04
+```
+
+5. Check state:
+
+```bash
+narratio session status 2026-04-04
+```
+
+Run, plan, and status output identify the resolved pipeline profile (or `none`)
+and effective configuration digest. Status distinguishes the current resolved
+value from the last value persisted in the session manifest, which helps
+diagnose profile switches without changing resume authority.
+
+Before switching an operational profile, compare its effective meaning with the
+production base through `narratio config diff default <profile>`.
+The command is read-only and succeeds whether it finds differences or not. Its
+sorted records describe defaulted, expanded concrete configuration—not source
+file layout—so it can be used to review model, artifact, and publish changes
+without creating a session or run. Use `narratio config artifacts` to review the
+concrete artifact identities, definitions, outputs, and dependencies. Select the
+same campaign explicitly when profiles could resolve different campaign paths;
+see the [CLI reference](cli.md#config-validate-config-show-config-sources-config-artifacts-and-config-diff)
+for syntax and record format.
+
+## Stage Execution and Continuation Behavior
+
+Canonical stage order:
+
+1. `prepare`
+2. `transcribe`
+3. `merge`
+4. `polish`
+5. `normalize`
+6. `trim`
+7. `render`
+8. `extract`
+9. `analyze`
+10. `publish`
+11. `notify`
+12. `cleanup`
+
+Execution rules:
+
+- succeeded stages are skipped unless `--force` is set; stages with semantic
+  configuration contracts additionally require matching versioned evidence;
+- `run` continues interrupted or partially completed sessions by running non-succeeded stages;
+- forcing a stage marks succeeded transitive dependents as `stale` before the
+  replacement runs; render and extract are independent siblings; and
+- an executed failure, changed self-skip, or success that replaces a different
+  effective outcome uses the same fixed dependency relation. A
+  repeated self-skip with the same reason and no outputs is stable and does not
+  perpetually rerun dependent work.
+
+Every aggregate stage except analyze currently provides semantic-configuration
+evidence; analyze retains its more precise per-artifact fingerprints and
+validator.
+Prepare additionally validates current stable/local/S3 source identity and the
+checksums of its durable prepared copies before reuse. Changed bytes, audio
+membership, S3 object identity, or missing/tampered copies rerun prepare and
+its fixed descendants without requiring `--force`. Changing prepare selection
+semantics likewise reruns all fixed descendants; changing
+WhisperX language/service identity reuses prepare; changing a Seriatim merge
+transformation reuses prepare and transcribe; and changing an Audita model
+reuses prepare, transcribe, and merge while rebuilding transcript refinement.
+A trim change invalidates both render and extract through the fixed dependency
+relation, while a render-only change preserves the extract sibling.
+
+Operational timeouts, retry/concurrency tuning, executable paths,
+workspace/cache/spool placement, reports, diagnostics, and secret values are
+excluded. Configuration, models, prompts, modules, or resources loaded
+privately inside external tools remain unobservable to Narratio. If their
+contents change behind the same configured identifier, explicitly force the
+affected stage.
+
+An explicit self-skip is a durable `skipped` stage outcome that later runs
+reconsider. It differs from successful no-output execution: disabled `render`
+and `publish`, and absent or no-executable `analyze`, record `succeeded` with
+metadata and no outputs. Ordinary later runs reuse those successful results;
+force the affected stage after enabling or configuring it. Optional artifact
+inputs are omitted only from the consuming artifact invocation and do not make
+the stage self-skip.
+
+Single-stage execution:
+
+```bash
+narratio run-stage normalize 2026-04-04 --force
+```
+
+Contiguous bounded execution uses inclusive canonical endpoints:
+
+```bash
+narratio session plan 2026-04-04 --from extract --through analyze --force
+narratio run 2026-04-04 --from extract --through analyze --force
+```
+
+Omitting `--from` selects from `prepare`; omitting `--through` selects through
+`cleanup`. Force applies only within the selected range. Repeating `--from`,
+`--through`, or `--force` is rejected instead of resolving by argument order.
+The plan command uses the same selection contract and prints only the selected
+range. Planning is read-only: it clones the loaded manifest, models selected
+stage transitions and invalidation in memory, and invokes resume validation
+without writing the manifest, creating run directories, materializing files,
+or invoking pipeline adapters. Analyze detail separates explicit targets,
+prerequisite rebuilds, scheduled execution, and current reuse. This lets a
+coarsely stale aggregate analyze stage show zero artifact executions when its
+selected artifact evidence is still semantically current.
+
+Before a bounded run or plan whose range starts after `prepare`, every excluded
+prefix stage must already have a session-manifest status of `succeeded` or
+`skipped`. Narratio reports the first absent, pending, running, failed, stale,
+or interrupted prerequisite without creating a run-local directory or changing
+session state. Widen `--from` to include that stage, or recover it explicitly
+before retrying. Excluded prefix stages are not resume-validated or repaired as
+part of the bounded invocation; selected stages still reject missing, unsafe,
+or manifest-inconsistent inputs at their owning boundary.
+
+Stages after `--through` are not prerequisites and are never scheduled by the
+bounded invocation. A selected forced stage can mark one of those succeeded
+dependents stale through the fixed invalidation relation, but the dependent
+does not execute until a later invocation selects it. Production composition
+likewise initializes only collaborators needed by the selected range and
+shared session lifecycle. In particular, render does not require Notarius or
+Scriptorium, extract does not require Scriptorium, and analyze does not require
+the transcription, Seriatim, Audita, or Notarius adapters.
+
+## Artifact Development Workflows
+
+Choose the narrowest workflow that matches the intended replacement:
+
+| Intent | Command | Preserved and rebuilt state |
+| --- | --- | --- |
+| Rebuild analysis only | [`narratio analyze 2026-04-04`](./cli.md#analyze) | Preserves transcripts and the current extraction bundle; force-runs selected analysis artifacts and their required analysis prerequisites. |
+| Rebuild extraction and analysis | [`narratio regenerate-artifacts 2026-04-04`](./cli.md#regenerate-artifacts) | Preserves transcripts; force-runs the complete configured extraction bundle, then selected analysis. `--artifacts` narrows analysis only. |
+| Continue bounded work normally | [`narratio run 2026-04-04 --from extract --through analyze`](./cli.md#run) | Uses ordinary resume decisions: current extraction and analysis can be skipped, while incomplete or obsolete work runs. |
+
+All three stop before publication. Inspect the results and run
+[`narratio publish`](./cli.md#publish) separately when delivery is intended.
+
+For the extraction-plus-analysis development loop, use:
+
+```bash
+narratio regenerate-artifacts 2026-04-04
+narratio regenerate-artifacts 2026-04-04 --artifacts session_recap,player_handout
+```
+
+This command is a transparent expansion to a forced bounded `run` from
+`extract` through `analyze`. Extraction always rebuilds its complete configured
+bundle. Analysis rebuilds the selected targets and their required analysis
+prerequisites, or uses the normal default selection when no artifact names are
+given. The command does not run publish, notify, or cleanup; delivery and
+retention remain separate operator actions.
+
+Inspect current artifact evidence, then publish explicitly when the regenerated
+set is ready:
+
+```bash
+narratio session artifacts 2026-04-04
+narratio publish 2026-04-04
+```
+
+If planning or execution reports stale, missing, failed, or tampered
+analysis evidence, regenerate the affected target instead of copying an older
+canonical file into place or editing the manifest. See
+[Troubleshooting: Analysis artifact evidence is not current](./troubleshooting.md#analysis-artifact-evidence-is-not-current).
+
+Analyze checkpoints each completed configured artifact before starting later
+artifact work. After a partial failure or interruption, retry normally: valid
+earlier checkpoints are reused and execution resumes with failed, stale, or
+missing work in dependency order. `--force` is unnecessary unless the operator
+intends to replace otherwise-current artifacts.
+
+## Artifact Selection
+
+For a configured artifact family, selecting its family key expands to every
+concrete character artifact. Select a concrete generated key to operate on one
+member only. Manifests and plan output retain the concrete key as the durable
+identity and include the family and character ID as optional provenance.
+
+`--artifacts` can be used on `run`, `session plan`, `run-stage`, `analyze`, and
+`publish`. For a bounded run or plan, the selected range must contain `analyze`
+or `publish`.
+
+Selection behavior:
+
+- validates names against `pipeline.scriptorium.artifacts`;
+- selects explicit analyze targets and permits their required configured
+  prerequisites to be reused or rebuilt first;
+- filters publish rules for `narratio.artifact.<name>` sources only;
+- does not suppress built-in transcript, bounds, or explicitly configured
+  `narratio.extraction.<name>` publish sources; and
+- never partially selects Notarius lanes.
+
+## Extraction Workflow
+
+When Notarius is omitted or disabled, `extract` records an explicit skipped
+outcome with reason `notarius_disabled` and no outputs. A later invocation
+reconsiders the skipped stage, so enabling Notarius does not require force.
+
+When Notarius extraction is enabled, the stage consumes the final trimmed JSON
+and preserves the complete validated Notarius bundle at:
+
+- `artifacts/notarius/{narratio_run_id}/`
+
+The directory is immutable once promoted. Configured lanes become
+`narratio.extraction.<name>` sources for Scriptorium and explicit publish rules;
+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`. Extraction supplies Notarius with verified,
+content-addressed copies under
+`cache/notarius/references/<sha256>/<prepared-basename>`. The full lowercase
+SHA-256 digest identifies the reference bytes, so retries and later invocations
+reuse the same path while changed bytes select a new path. Older snapshots are
+retained and are not current artifact evidence. A concurrent refresh of
+canonical prepared files therefore cannot change the bytes consumed by an
+in-flight invocation.
+For a canonical party, preparation retains the validated authored party bytes
+at `inputs/party.yml` and generates `inputs/players.yml` from that roster.
+The manifest records their checksums separately, with the players input marked
+as derived from the party; refresh preparation after changing the roster rather
+than editing either prepared file.
+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 immutable bundle
+remains available for inspection, but downstream resolution requires a new
+current successful extraction record.
+
+Notarius extraction validates its run-local bundle and moves it once to the
+unique durable bundle path. A pre-existing durable destination is a collision;
+no duplicate promotion tree is created.
+
+`pipeline.notarius.resume` and `pipeline.notarius.chunk_cache` control work
+inside an executed Notarius invocation. Ordinary extraction forwards their
+configured values. Forced extraction always disables checkpoint loading and
+requests chunk-plan `refresh`, even when the configured mode is `bypass`.
+Refresh regenerates and replaces only the active input's accepted chunk plan;
+it is not cache deletion.
+
+Notarius checkpoint recording must be enabled in the deployed Notarius
+configuration. Narratio neither creates a Notarius pipeline/configuration nor
+reads it to infer checkpoint availability. Configure explicit persistent
+Notarius chunk-plan and checkpoint roots when reuse must survive separate
+Narratio subprocesses. A changed reference, transcript, selected profile,
+profile content, endpoint, or other Notarius checkpoint identity input can
+produce a legitimate cold miss.
+
+There are two independent resume boundaries: Narratio may skip a completed
+`extract` stage without invoking Notarius, while `--resume` allows Notarius to
+reuse compatible accepted work only after Narratio has decided extraction must
+execute. Deleting Narratio's local reference snapshots does not invalidate a
+complete durable extraction; missing snapshots are reconstructed only when a
+later extraction actually runs.
+
+## External Command Lifecycle
+
+When an external command is cancelled or times out, Narratio terminates its
+owned descendants as well as the command itself. Cancellation first requests
+termination where the platform supports it, then force terminates after a
+bounded wait. A command is not considered finished until its leader has been
+reaped, and descendants that keep standard output or error open cannot keep
+the invocation blocked. Other operating systems fail closed rather than launch
+a command without tree ownership.
+
+Subprocess stdout and stderr diagnostics are separately redacted and capped at
+8 MiB per invocation. Narratio does not retain configured credential values in
+these logs or their error tails; reaching a capture limit terminates the command
+tree and reports which stream exceeded the limit.
+
+Run-local diagnostics are:
+
+- `runs/{run_id}/extract/notarius.receipt.json`
+- `runs/{run_id}/extract/notarius.stderr.log`
+- `runs/{run_id}/extract/notarius-output/` before durable promotion
+
+The run upload is an allowlist derived from the session manifest's declared
+current-run outputs, logs, and generated configurations, not a workspace scan.
+References to canonical session files and prior-run paths are excluded. Each
+declared source is opened without following symlinked ancestors or the leaf,
+verified as a regular file, and streamed from that verified descriptor.
+Unlisted files and unsafe entries are never uploaded; a run with no declared
+current-run diagnostics uploads no run-local files. No distinguished diagnostic
+file is uploaded. The durable bundle is never scanned for implicit publication;
+only lanes named by explicit `pipeline.publish.outputs` rules are uploaded.
+
+To intentionally replace the current extraction result, run:
+
+```bash
+narratio run-stage extract 2026-04-04 --force
+```
+
+Narratio automatically reruns extraction when its recorded invocation contract,
+prepared Narratio reference identities, or durable output validation changes.
+The semantic portion covers Notarius enablement, pipeline identity, declared
+reference mapping, and output contracts. Executable, timeout, working directory,
+and private config-file paths are operational and do not invalidate a current
+result.
+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.
+
+Publish reuse additionally tracks enabled/run-upload behavior, normalized
+output rules, and remote backend/bucket/region/endpoint/root identity.
+Credential environment names, local workspace placement, and run IDs are
+excluded. Regardless of semantic reuse evidence, executing publish reads
+independent remote locks directly and rechecks initially unlocked sources
+before commit selection.
+
+## Publish Workflow
+
+Run publish only:
+
+```bash
+narratio publish 2026-04-04
+```
+
+Equivalent:
+
+```bash
+narratio run-stage publish 2026-04-04 --force
+```
+
+This standalone command stops after publish and does not invoke cleanup. A
+default full `run` continues through notify and cleanup.
+
+Publish commit model:
+
+- uploads eligible run files under `{session_prefix}/runs/{run_id}/`, excluding
+  audio and the run-local Notarius staging bundle;
+- uploads configured published outputs and `previous/**` cache files into the
+  same immutable run scope, including only explicitly configured extraction
+  lanes;
+- writes `{session_prefix}/runs/{run_id}/commit.json` after all declared
+  immutable objects are uploaded and verified; and
+- writes `{session_prefix}/current/commit-pointer.json` once, last.
+
+`current/commit-pointer.json` is the remote current-state commit marker. It
+selects exactly one immutable commit, which declares the complete object set.
+
+## Remote Commit Migration
+
+The immutable remote commit contract uses
+`runs/{run_id}/commit.json` to declare a run's complete object set and a small
+`current/commit-pointer.json` to select it. The pointer binds the selected
+commit by version, checksum, size, and storage generation; committed artifacts
+are also checksum- and generation-bound. Readers accept this contract now and
+strictly reject mismatched or unknown data.
+
+A selected commit may carry a `published_output` declaration from an earlier
+run in the same campaign/session. Restore, previous-session caching, status,
+and artifact inspection use that declaration's exact immutable key and stable
+source; they do not reconstruct a current-run key or scan the session prefix.
+Other artifact types remain confined to the selected commit's own run.
+
+When the pointer is absent, remote state is not published; republish the
+session to establish a committed snapshot. Remote commit state does not carry
+local `current_pointer_written` metadata.
+
+## Publish Locks
+
+Each mutable lock is an independent strict JSON object at
+`{session_prefix}/locks/{sha256(source)}.lock`. The lowercase digest is computed
+from the exact canonical source. Listing validates every object in that
+reserved prefix and reports locks sorted by source.
+
+Upgrades do not read, migrate, or delete the retired `{session_prefix}/locks.yml`
+object. It has no effect on publication and may be removed manually after
+verifying lock commands and publication behavior with the upgraded Narratio
+version. No migration command is required.
+
+Operational rules:
+
+- add uses conditional creation and reports an existing lock;
+- add with `--force` observes the current generation and attempts one
+  generation-matched replacement. A concurrent change is reported for an
+  explicit operator retry;
+- remove is idempotent and reports whether a lock was present;
+- the initial publish lock snapshot controls output planning. A locked source
+  carries its exact declaration from the prior current commit when available;
+  a never-published locked source remains absent even when required;
+- carried bytes are not copied. Publish verifies the prior object's exact key,
+  size, and generation without downloading it; and
+- after immutable uploads and the immutable commit, publish re-reads every
+  initially unlocked participating source. A newly added lock prevents the
+  current pointer from advancing, although the immutable attempt may remain.
+  A removed initial lock may conservatively cause one carry.
+
+Examples:
+
+```bash
+narratio session locks 2026-04-04
+narratio session locks add 2026-04-04 narratio.artifact.session_recap --reason "manual edits" --force
+narratio session locks remove 2026-04-04 narratio.artifact.session_recap
+```
+
+## Restore Workflow
+
+Use restore when local durable session state is missing or stale and remote committed current state is authoritative.
+
+Dry run:
+
+```bash
+narratio session restore 2026-04-04 --dry-run
+```
+
+Apply:
+
+```bash
+narratio session restore 2026-04-04
+```
+
+`--dry-run` does not write durable session files. It still reads the selected
+remote current state and may read object identity/content needed to classify the
+plan, so it is not a network-free operation.
+
+Default restore scope:
+
+- the committed session manifest and the committed transcript/artifact objects
+  declared by the selected remote commit
+- `previous/**` when needed by configured previous-session artifact inputs;
+  each is selected from its exact committed `published_output` declaration
+
+Optional:
+
+- `--include-audio` to include `audio/**`
+- `--force` to overwrite eligible conflicting regular files; it never replaces
+  directories, symlinks, or other non-regular local targets
+
+Restore treats a local leaf symlink or any symlinked ancestor beneath the
+selected session root as a conflict, even when the linked content matches the
+selected remote object. `--force` does not override that conflict.
+
+Before each install, restore validates the destination again beneath the
+selected session root. A target changed into a symlink, directory, or other
+non-regular entry is not overwritten.
+
+Restore writes an execution report at `reports/restore-latest.json`.
+
+If restore fails after beginning installation, it leaves a durable
+`.restore-incomplete.json` marker in the session root. Pipeline runs will stop
+until you rerun the same restore command and it completes. Restore intentionally
+does not try to roll back files already installed; retrying the selected remote
+snapshot is the recovery procedure.
+
+## Local State Layout
 
 Session root:
-- `{workspace.root}/work/{campaign}/{session_id}/`
 
-Primary state:
-- `manifest.json`: session-level stage state.
-- `runs/{run_id}/manifest.json`: invocation-level state.
-- `.lock`: session lock while a run is active.
+- `{workspace.root}/work/{campaign}/{session_id}`
 
-Canonical session directories:
-- `inputs/`
-- `audio/`
-- `transcripts/`
-- `artifacts/`
-- `reports/`
-- `logs/`
-- `config/`
-- `current/`
-- `runs/`
+Durable session paths:
 
-Run-local stage directories:
-- `runs/{run_id}/{stage}/` with stage-local `outputs/`, `logs/`, `reports/`, `config/`, `scratch/`.
+- `manifest.json`
+- `inputs/**`
+- `audio/**`
+- `transcripts/**`
+- `artifacts/**`
+- `previous/**`
+- `reports/**`
+- `logs/**`
+- `config/**`
+- `runs/**`
+- `cache/notarius/references/<sha256>/<prepared-basename>`
 
-Behavior:
-- directory creation is idempotent.
-- stage outputs are generally generated run-local first, then promoted to canonical paths on success.
+`manifest.json` is the versioned session-progress document. Narratio accepts
+only `narratio.session-manifest.v1`. Do not edit unsupported session state to
+add missing markers. Move it aside and regenerate it, restore a verified
+current committed snapshot, or republish healthy regenerated state as the
+relevant workflow requires.
 
-## Analyze artifact execution lifecycle
+Validated Notarius bundles live below `artifacts/notarius/{run_id}/`; receipt,
+stderr, and pre-promotion output remain in the producing run's `extract`
+directory as described in [Extraction Workflow](#extraction-workflow).
+Stable reference snapshots live in the session cache path above. Ordinary
+published-run cleanup removes its selected run-local target but retains this
+cache, and publish/restore never enumerate it as an artifact. Remove a snapshot
+or digest directory manually only while no command is active for the session;
+regular missing or corrupt content is reconstructed on the next executed
+extraction, while symlinks, directories, and other unsafe conflicts must be
+investigated and removed deliberately.
 
-Analyze executes configured artifacts from `pipeline.scriptorium.artifacts`.
+Run-local layout:
 
-Execution model:
-- executable set = enabled artifacts, filtered by `--artifacts` when provided.
-- artifact-to-artifact dependencies are declared via `depends_on`.
-- selected artifacts run in deterministic dependency order.
-- after each successful artifact run, output is promoted to configured canonical `output_path`.
+- `runs/{run_id}/{stage}/outputs`
+- `runs/{run_id}/{stage}/logs`
+- `runs/{run_id}/{stage}/reports`
+- `runs/{run_id}/{stage}/config`
+- `runs/{run_id}/{stage}/scratch`
 
-Configured artifact source reuse:
-- a non-executable configured artifact can satisfy inputs if its configured output file already exists and is valid.
-- reused configured artifact provenance is `filesystem.disabled_artifact_output`.
+Spool layout (runtime/transient):
 
-`--artifacts` behavior:
-- accepted on `run`, `resume`, and `run-stage analyze`.
-- filters analyze execution only; does not force stage rerun.
+- `{spool.root}/{campaign}/{session_id}/{run_id}/...`
+- restore audio spool under `{spool.root}/{campaign}/{session_id}/restore/audio`
 
-## Remote archive layout and publish contract
+Cache layout (durable S3 audio cache):
 
-When archive is enabled and run upload is enabled, archive publishes under:
+- `{cache.root}/s3/{bucket}/...`
 
-- session prefix: `{root_prefix}/campaigns/{campaign}/sessions/{session_id}/`
-- run prefix: `{session_prefix}/runs/{run_id}/`
+Each cached audio file has an adjacent managed identity record. It binds the
+file to its remote object version and verified digest; deleting or altering the
+record simply causes Narratio to download and verify the object again.
+Remote audio and restored files are fully transferred into sibling temporary
+files and validated before they replace their canonical workspace paths.
 
-Archive uploads:
-- run record files from run root (excluding `audio/`).
-- promoted files from explicit `archive.promote_artifacts` rules.
+### Workspace Permissions
 
-Publish order:
-1. upload `current/manifest.json`
-2. upload `current/run_id.txt` last
+Ordinary Narratio workspace content is intentionally shareable with the
+workspace group. On POSIX systems, Narratio-created workspace, spool, and cache
+directories converge on setgid `02775`; ordinary files, including manifests,
+transcripts, generated configuration, logs, reports, and Notarius artifacts,
+converge on `0664`. Narratio explicitly applies these modes so a restrictive
+caller umask does not remove group write or setgid. It does not change file or
+directory ownership: the configured workspace's existing group is inherited.
 
-`current/run_id.txt` is the remote commit marker.
+API keys are credentials, not ordinary workspace data. Store them outside the
+shared workspace or in a separately restricted credential location; ordinary
+workspace group access must never be treated as authorization to read keys.
+Provision a credential directory as `0700` and credential files as `0600`;
+these permission modes are an operator requirement and are not enforced by
+ConfigKit.
 
-Archive promotion is explicit and path-based:
-- Narratio does not auto-promote all generated analyze artifacts.
-- missing required promotion sources fail archive stage.
-- missing optional promotion sources are skipped.
+Every pipeline-loading command bootstraps credentials once, before the first
+configuration load and before any adapter is constructed. `--secrets-dir`
+selects an explicit directory (relative paths use caller CWD). Otherwise a
+present `secrets/` beside the resolved root pipeline is used, while an absent
+conventional directory is skipped. Explicit missing/empty selections and
+invalid existing directories fail the command. ConfigKit follows a symlink used
+as the selected directory, but immediate entries must be regular non-symlink
+files. Existing environment variables—including empty values—always win.
 
-## Resume, retry, and safe rerun behavior
+S3 `access_key_id` and `secret_access_key` are an optional pair of typed
+environment references. When both are absent, the AWS SDK retains its default
+credential provider chain. When both are configured, Narratio supplies their
+load-time resolved values through an explicit static provider. Audita's optional
+`llm_api_key` is likewise captured at pipeline load and supplied only through
+the child process's `AUDITA_LLM_API_KEY` override.
 
-Default skip:
-- `run` and `run-stage` skip already-succeeded stages unless `--force` is set.
+External adapter results are individually bounded before Narratio validates or
+materializes them. These per-file limits do not reserve disk space: prevent hard
+disk exhaustion with filesystem, service, container, or volume quotas sized for
+the session workload.
 
-Resume:
-- `resume` starts at first non-succeeded stage.
-- `resume --force` runs full stage order.
+## Cleanup
 
-Forced reruns:
-- force-rerunning an upstream succeeded stage marks downstream succeeded stages as `stale`.
-
-Safe rerun pattern:
-1. rerun the changed stage with `--force`.
-2. run `resume` to rebuild downstream stages.
-
-## Cleanup behavior
-
-Cleanup is considered only when archive stage executed and succeeded.
-
-Cleanup toggles:
-- `pipeline.spool.delete_audio_after_archive=true` deletes run-scoped spool audio.
-- `pipeline.workspace.cleanup_after_archive=true` deletes run-scoped local run directory.
-
-Cleanup eligibility gates:
-- archive enabled
-- archive run upload enabled
-- run record upload completed
-- current pointer write completed (`current/run_id.txt` written)
-
-No cleanup for failed/incomplete/unarchived/archive-skipped runs.
-
-## Failure and recovery playbooks
-
-After failure, Narratio keeps:
-- session manifest
-- run manifest
-- run-local artifacts/logs/config/reports
-
-Failed or incomplete runs remain local-only.
-
-Recommended recovery:
-
-1. inspect state:
+Session-scoped cleanup:
 
 ```bash
-narratio status --manifest <manifest-path>
+narratio clean 2026-04-04
 ```
 
-2. fix root cause (config/input/credentials/service availability).
-3. continue with `resume`, or targeted `run-stage --force` followed by `resume`.
+Global cleanup:
 
-## Operational caveats
+```bash
+narratio clean --all
+```
 
-- `status` requires explicit `--manifest`; there is no session-id lookup command.
-- local and S3 audio input modes are mutually exclusive.
-- archive publish requires upstream stages through `analyze` to be `succeeded`.
-- required promotion rules can fail when selected analyze artifacts did not generate a required file path.
+Dry-run and cache variants:
+
+```bash
+narratio clean 2026-04-04 --dry-run --clear-cache
+narratio clean --all --dry-run --clear-cache
+```
+
+Rules:
+
+- `clean` deletes work/spool session state;
+- cache is preserved unless `--clear-cache` is set;
+- each deletion is confined beneath its configured workspace, spool, or cache
+  root; root, traversal, and out-of-root targets are refused;
+- the final cleanup stage is gated by successful publish evidence plus:
+  - `pipeline.spool.delete_audio_after_publish=true`
+  - `pipeline.workspace.cleanup_after_publish=true`
+  - the manifest publish record has `uploaded=true`, the published run ID, the
+    exact remote commit key, and the current commit-pointer key.
+
+Cleanup derives only the configured run-scoped spool and workspace targets,
+uses root-confined deletion, and does not read or mutate object storage. A
+failure leaves publish succeeded and the remote committed snapshot current.
+Retry with a normal full run: valid upstream work, including publish and notify,
+is skipped while the failed cleanup stage runs again. `run-stage cleanup` is
+also available when the manifest has valid publish evidence. A range ending at
+`notify` or earlier and the standalone `publish` command never delete local
+state.
+
+Older local manifests that contain the retired cleanup-obligation field are
+intentionally incompatible with strict manifest decoding. If such an
+obligation is still outstanding, complete it with the pre-upgrade binary.
+Otherwise verify that the remote publication is committed, move aside or
+regenerate the incompatible local manifest (or restore the verified remote
+snapshot), and then use the cleanup stage. Manual JSON editing is not the
+normal migration path.
+
+## Operational Caveats
+
+- Local and S3 audio modes are mutually exclusive.
+- Publish requires prerequisite stages through `render` and `analyze` to be succeeded.
+- Markdown publish defaults require render outputs (`transcripts/final.md` and `transcripts/final.trimmed.md`).
+- Restore requires configured object storage and committed remote current state.
+- Pipeline-loading commands bootstrap filesystem secrets once before configuration
+  resolution and object-store initialization.

docs/policy/architecture.md

@@ -0,0 +1,305 @@
+# Architecture
+
+This document defines Narratio's intended high-level architecture and the
+invariants that changes must preserve. Implemented component details belong in
+the [Internal Overview](../internal/overview.md) and its linked documents.
+Significant architectural decision history belongs under `docs/adr/` when such
+records exist.
+
+## System Shape
+
+Narratio is a small Go application that turns D&D session audio into polished
+transcripts and generated session artifacts. It is an explicit, stage-driven
+orchestrator, not a general workflow engine.
+
+Narratio coordinates specialized external systems rather than reimplementing
+their domains:
+
+- WhisperX performs transcription;
+- Seriatim performs deterministic transcript processing and rendering;
+- Audita performs transcript correction and polishing;
+- Notarius extracts validated structured artifact bundles; and
+- Scriptorium executes prompts and produces configured artifacts.
+
+Narratio owns orchestration, configuration resolution, session and run state,
+artifact and path modeling, manifest persistence, stage sequencing, resume,
+restore, cleanup gates, and publish semantics. External contracts are defined
+in the [integration documentation](../integrations/).
+
+The pipeline has one canonical ordered stage set. Configuration may enable,
+disable, or parameterize supported behavior, but it must not turn that sequence
+into an arbitrary DAG or hide orchestration in generic workflow abstractions.
+An invocation selects either the full sequence or one inclusive contiguous
+range of it. Execution remains flat and canonical even though invalidation is
+dependency-aware: the application owns a separate fixed relation used only to
+stale transitive dependents, including dependents outside a selected range.
+The implemented stage inventory belongs in the
+[Internal Overview](../internal/overview.md).
+
+Narratio is contract-first without being abstraction-heavy. Interfaces and
+extension points should protect demonstrated boundaries. New abstraction is not
+itself an architectural goal.
+
+## Ownership And Dependency Direction
+
+The application boundary owns command dispatch, configuration selection,
+production composition, session locking, and top-level lifecycle. It may depend
+on concrete implementations to assemble a run.
+
+Stage orchestration expresses intent in Narratio-level data and interfaces.
+Stages may depend on configuration, manifest, artifact, path, and adapter
+contracts, but they must not depend on transport-specific request types,
+subprocess argument construction, cloud SDK types, or downstream tool internals.
+
+Adapters translate between Narratio contracts and external systems. They own
+HTTP, subprocess, notification, and object-storage mechanics, including command
+construction, transport behavior, provider response handling, and external
+error adaptation. External dependency types must remain inside the adapter that
+owns them unless that dependency is the adapter's explicit public contract.
+WhisperX HTTP behavior, Seriatim, Audita, Notarius, and Scriptorium command
+construction, notification transport, and object-storage SDK details remain
+behind these boundaries.
+
+State and path services must not infer stage policy. Storage implementations
+receive explicit bucket-relative keys and do not infer campaign, session, run,
+or root-prefix semantics. Manifest persistence records transitions but does not
+choose orchestration policy. Artifact resolution identifies and validates
+artifacts but does not execute producers.
+
+Dependencies should remain narrow and point toward Narratio-owned contracts.
+Prefer the Go standard library. Add an external dependency only when it provides
+a clear correctness, security, interoperability, or complexity benefit, and
+confine it to the boundary that needs it.
+
+## Stage Boundaries
+
+Each stage has one explicit responsibility and declares:
+
+- required input state;
+- produced output state;
+- configuration it consumes;
+- external adapters it uses;
+- manifest references and metadata it reads or writes;
+- skip, force, invalidation, and resume behavior; and
+- failure behavior.
+
+Stages write and validate run-local results before materializing canonical
+outputs where that distinction applies. A stage is complete only after its
+required outputs have been written, validated, and recorded in durable manifest
+state. Later stages depend on recorded success and artifact resolution, not
+merely on incidental files existing on disk.
+
+A failed or interrupted stage must not be presented as successful. Failure
+should preserve enough local state and diagnostics for inspection, recovery,
+and resume. Forcing a stage invalidates succeeded transitive dependents
+according to a fixed application-owned relation that is separate from canonical
+execution order. The relation is validated against the stage inventory and is
+not configurable.
+
+A stage may explicitly self-skip with a stable reason and no outputs. That
+outcome is persisted, clears older outputs owned by the stage, and is
+reconsidered on a later invocation. A stage may also validate whether an
+otherwise successful recorded result is still resumable; an obsolete result
+is staled and rerun, while an unsafe condition that prevents a sound decision
+stops execution.
+
+Shared behavior should live behind a narrow service or helper with one clear
+owner. Stages must not reach across boundaries or reproduce adapter, manifest,
+artifact, or path policy ad hoc.
+
+## Manifest, Resume, And Restore
+
+The session manifest is the durable ledger for progress across invocations. It
+records session and run identity, stage state, input and output references,
+diagnostic references, checksums or provenance where useful, and non-secret
+adapter and publish metadata.
+
+Resume and skip decisions are manifest-driven. Filesystem state may be
+inspected and validated, but file presence alone does not replace recorded
+stage state. Each invocation retains an in-memory command summary and a
+run-local workspace identity, but neither is a durable progress ledger. The
+physical run directory is created on demand only when an executing stage
+requires it; a fully reused invocation or a cleanup-only invocation does not
+leave an empty run directory.
+
+Restore treats committed remote current state as its authority. It must plan
+deterministically, confine remote-to-local paths, protect local conflicts, and
+install the validated session manifest after other restored durable files. The
+physical workflow and recovery procedures belong in
+[Operations](../operations.md).
+
+Restore and runner transitions for one session use the same local lock. A
+durable incomplete-restore marker blocks runner reuse after a partial restore;
+safe retry, rather than rollback of arbitrary local effects, is the recovery
+mechanism. Restored manifest-local references must be confined to the selected
+local session root, never trusted as producer-machine absolute paths.
+
+For the immutable remote-commit protocol, a restore or status operation binds
+to one pointer-selected commit and only its declared object identities. A force
+flag may replace an eligible regular managed file, but never turns a directory
+or other non-regular conflict into a successful restore.
+
+## Configuration
+
+Configuration is strict, explicit, centralized, and operator-oriented.
+
+- YAML decoding rejects unknown fields.
+- Defaults are centralized and testable.
+- Empty configured values do not silently replace meaningful defaults.
+- Validation rejects invalid configuration 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
+  configuration.
+
+Narratio must not become a second configuration system for downstream tools.
+External systems own their runtime defaults wherever practical; Narratio passes
+the paths required by its stage contracts and explicit operator overrides. The
+field-level contract and credential-supply mechanisms belong in
+[Configuration](../config.md).
+
+## Artifacts, Paths, And Storage
+
+Artifact identities and local and remote paths are application contracts.
+Canonical helpers own workspace, spool, cache, session, run, input, transcript,
+artifact, log, report, configuration, and publish-current paths. Callers must
+not reconstruct canonical paths through scattered string concatenation.
+
+Reusable audio cache entries require a typed record that binds a confined,
+no-follow regular file and its digest to the selected remote object identity.
+Size alone and unqualified multipart ETags are not content-integrity evidence.
+
+Artifact resolution is deterministic and manifest-aware. Producers materialize
+canonical outputs before reporting success, and consumers resolve declared
+artifact identities rather than infer files from unrelated directory contents.
+External artifact bundles become current only through validated immutable
+promotion and manifest records; directory presence alone never establishes
+availability.
+
+Writes, moves, replacements, and deletions must use narrow, explicit,
+root-confined destinations. Symlinks, traversal, broad roots, and ambiguous
+relative destinations must not expand the scope of an operation. Cleanup is
+permitted only through explicit operator action or the configured final cleanup
+stage, and it must preserve durable cache unless cache removal is explicitly
+requested.
+
+Physical layout, retention, and operational lifecycle belong in
+[Operations](../operations.md). Logical external formats and durable integration
+contracts belong under [Integrations](../integrations/).
+
+## Publish Commit Boundary
+
+Publish has one explicit remote commit boundary. A remote run becomes current
+only after Narratio has successfully uploaded its immutable run-scoped objects,
+the immutable commit manifest, and finally the current commit pointer.
+
+`current/commit-pointer.json` is the sole mutable selector and must be written
+exactly once, last. Failed, incomplete, skipped, or uncommitted publish attempts
+must not be presented as current remote state. Publish locks remain authoritative
+and are not bypassed by a forced run. Each mutable remote lock is an independent
+per-source object; lock mutations use provider-enforced generation preconditions.
+Publish revalidates every initially unlocked participating source after writing
+the immutable commit and before pointer selection. A lock observed then leaves
+the prior committed snapshot current. A lock created after that final check may
+race the pointer write; the commit protocol does not claim a stronger distributed
+transaction boundary.
+
+Automatic local cleanup is permitted only after a successful publish commit,
+only when explicitly configured, and only through the path-safety guardrails.
+It is the final ordinary pipeline stage after `notify`. The stage derives its
+exact run-scoped targets from validated publish metadata and the configured
+campaign/session identity; it never infers a target from directory contents or
+rereads remote storage. A cleanup failure makes the invocation incomplete while
+leaving publish succeeded and the committed remote snapshot authoritative. A
+normal later full run reuses valid upstream stages and retries cleanup.
+
+The standalone `publish` command selects only publish and therefore never
+invokes cleanup. Operators may select cleanup directly only when the manifest
+contains valid successful publication evidence.
+
+## Security, Privacy, And Diagnostics
+
+Narratio distinguishes ordinary workspace data from credentials. Campaign and
+session material—including manifests, transcripts, prompts, generated
+configuration, logs, reports, diagnostics, and Notarius artifacts—is
+intentionally shareable with the configured workspace group. API-key material
+is sensitive and is not covered by the ordinary workspace-sharing policy.
+
+Narratio supports Linux on amd64 and arm64. macOS arm64 is best effort: it has
+a cross-build gate and release asset, but no native runtime release gate.
+Windows and macOS amd64 are unsupported and have no compatibility promise or
+release asset.
+
+On supported systems, Narratio-created ordinary workspace directories converge on
+setgid `02775` and ordinary workspace files on `0664`, even when the caller's
+umask is restrictive. This preserves the existing workspace group for nested
+creation and atomic replacements without changing ownership. API-key storage
+uses a separate restrictive contract.
+
+Raw secrets must not be stored in pipeline, campaign, or session YAML or written
+to manifests, logs, generated configuration, reports, publish metadata,
+documentation, or examples. Pipeline configuration names environment variables;
+command-owned startup may populate previously unset variables from ConfigKit's
+explicit or conventional secrets directory. This bootstrap occurs once per
+invocation before any typed configuration load or adapter construction and is
+not hidden inside library loaders. Safe bootstrap diagnostics may identify
+files and statuses but never values. Diagnostics should avoid transcript and
+prompt content unless a deliberate, bounded inspection mechanism requires it.
+
+Logs, reports, generated invocation files, generated configuration, and render
+debug files are diagnostics, not canonical pipeline products. They should be
+durable and discoverable where configured, and manifest references must preserve
+the distinction between diagnostics and artifacts.
+
+Documentation security rules belong in the
+[Documentation Policy](documentation.md). Credential supply belongs in
+[Configuration](../config.md), while permissions, sensitive runtime-artifact
+handling, and recovery belong in [Operations](../operations.md).
+
+## Determinism And Testability
+
+Narratio prefers deterministic behavior where practical, including stable local
+and remote layouts, sorted operation order, predictable generated
+configuration, repeatable command construction, deterministic artifact
+resolution, and reproducible planning.
+
+Run IDs and timestamps may be intentionally variable, but surrounding behavior
+must remain controllable in tests. Core behavior should be testable without live
+external services; expensive, nondeterministic, destructive, or external
+boundaries should be replaceable with focused test doubles. General testing
+philosophy and sufficiency rules belong in the [Testing Policy](testing.md).
+
+## Documentation And Decision Records
+
+Documentation follows the [Documentation Policy](documentation.md). Current
+behavior belongs in its canonical user, operator, integration, architecture, or
+internal owner. Proposed behavior and implementation status belong under
+`docs/roadmap/`.
+
+Significant architectural decisions may be recorded under `docs/adr/` using the
+format and lifecycle defined by the documentation policy. ADR acceptance does
+not establish that a decision has been implemented.
+
+## Architectural Non-Goals
+
+Narratio does not aim to provide:
+
+- a generic DAG or workflow engine;
+- a replacement configuration layer for WhisperX, Seriatim, Audita,
+  Scriptorium, or other downstream tools;
+- a storage abstraction broader than the needs of this pipeline;
+- stage logic coupled directly to cloud SDKs, transports, subprocess details,
+  or downstream implementation internals;
+- raw-secret persistence;
+- implicit cross-stage behavior that bypasses manifest and artifact contracts;
+  or
+- a prompt-authoring system.

docs/policy/documentation.md

@@ -0,0 +1,150 @@
+# Documentation Policy
+
+## Purpose
+
+This policy assigns each documentation topic to one canonical owner. Its goal is
+to keep Narratio documentation accurate, concise, discoverable, and resistant
+to drift for users, operators, developers, integrators, and LLM coding agents.
+
+## Core Rules
+
+### One Canonical Owner
+
+Each authoritative fact belongs in one document. A non-owning document may give
+a short, stable summary for orientation, but it must link to the canonical owner
+instead of repeating volatile details.
+
+Volatile details include commands, flags, configuration fields and defaults,
+stage or integration keys, schemas, file names, paths, status codes, retry
+behavior, and runtime guarantees. If readers could reasonably treat a statement
+as a contract, maintain it only in the owning document.
+
+### Current And Future Behavior
+
+Outside `docs/roadmap/`, documentation describes implemented behavior only.
+Partial features may be described only to their implemented boundary.
+
+ADRs are the narrow exception: an ADR may record an accepted architectural
+decision before implementation, but acceptance must not be presented as proof
+that the behavior exists. The roadmap owns implementation status and sequencing
+until the decision is implemented. Current architecture, user, operator,
+integration, and internal documentation are updated when the behavior lands.
+
+### Audience And Detail
+
+Write for the document's stated audience and include only the detail needed for
+its owned topic. User and operator docs should not expose implementation detail.
+Developer docs should link to user-facing and external contracts rather than
+restate them.
+
+### Examples
+
+Complete copyable files belong in `examples/`. Documentation may use the
+smallest illustrative snippet needed to explain its owned topic, but should link
+to maintained examples instead of embedding a second complete copy.
+
+Examples must be valid, secret-free, and tested where practical. Commands and
+configuration used in documentation should match the application.
+
+### Security And Privacy
+
+Documentation and examples must not contain real credentials, private keys,
+private environment dumps, sensitive source material, or private infrastructure
+details unless intentionally public. Document secret-handling mechanisms, not
+secret values.
+
+## Canonical Ownership
+
+| Topic | Canonical owner | Owned content | Content owned elsewhere |
+| --- | --- | --- | --- |
+| Product orientation and minimal end-to-end quickstart | `README.md` | What Narratio is, why it is useful, one shortest successful invocation, and links onward. | Complete command reference, configuration reference, operational procedures, implementation detail. |
+| Contributor entry point | `docs/development.md` | Task-oriented reading guide, minimal contributor orientation, baseline validation commands, and links to canonical docs. | Package inventory, architecture rules, subsystem behavior, detailed change recipes. |
+| Maintainer release procedure | `docs/release.md` | Version selection, candidate preparation and validation, guarded tag publication, release completion boundary, failure recovery, and optional asynchronous inspection. | Script implementation mechanics, current application contracts, and historical release summaries. |
+| Historical release summary | `docs/releases/<tag>.md` | Immutable summary, compatibility, upgrade, and changes for one released version. | Current maintainer procedure and current application contract details. |
+| Current application architecture | `docs/policy/architecture.md` | System shape, normative ownership, dependency direction, architectural boundaries, invariants, safety properties, and non-goals. | Concrete package inventory, implementation mechanics, contributor procedures, decision history, future work. |
+| Documentation organization | `docs/policy/documentation.md` | Documentation ownership, audience boundaries, maintenance rules, and ADR/document lifecycle. | Application architecture or product behavior. |
+| Testing policy | `docs/policy/testing.md` | Test philosophy, risk-based sufficiency, test boundaries, doubles, coverage guidance, regression-test policy, and criteria for adding, rewriting, or deleting tests. | Subsystem behavior, application contracts, subsystem-specific test inventories, and implementation plans. |
+| CLI contract | `docs/cli.md` | Commands, arguments, flags, invocation semantics, output conventions, and exit behavior. | End-to-end operating procedures, configuration field definitions, runtime filesystem layout, stage implementation details. |
+| Configuration contract | `docs/config.md` | Discovery and precedence, file schemas, fields, defaults, environment overrides, validation rules, and user-selectable stage or integration settings. | Complete example files, CLI syntax, runtime state lifecycle, implementation details. |
+| Operations | `docs/operations.md` | Runtime workflows, physical filesystem and remote-state layout, output and diagnostic handling, resume, cleanup, permissions, recovery, and operational limits. | CLI flag syntax, configuration field definitions, logical artifact schemas, implementation mechanics. |
+| Troubleshooting | `docs/troubleshooting.md` | Symptom-driven diagnosis, likely causes, safe inspection steps and remedies, and links to relevant contracts. | CLI syntax, configuration definitions, operational procedures, integration contracts, implementation mechanics. |
+| Public HTTP contract, if introduced | `docs/api.md` | Routes, authentication, media types, request and response schemas, status codes, pagination, caching, idempotency, rate limits, and HTTP retry semantics. | Client walkthroughs, upstream or downstream integration internals, implementation detail. |
+| Consumer guidance, if a public package or API is introduced | `docs/consumers/` | Task-oriented use of the public interface, minimal client examples, and consumer responsibilities. | HTTP wire semantics, external protocol contracts, internal implementation detail. |
+| External and durable integration contracts | `docs/integrations/` | External file formats and protocols, upstream and downstream contracts, logical artifact paths and schemas, media types, and compatibility behavior. | Physical runtime placement and lifecycle, internal transformations, CLI syntax, configuration defaults. |
+| Implemented component inventory | `docs/internal/overview.md` | Current packages and components, their implemented responsibilities, and links to focused internal docs. | Normative architecture, contributor reading policy, external contracts. |
+| Internal component behavior | Other files under `docs/internal/` | Implementation flow, internal collaborators and state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. |
+| Architectural decision history | `docs/adr/` | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, task sequencing. |
+| Future work and implementation status | `docs/roadmap/` | Proposed, accepted, deferred, or rejected work; implementation status; sequencing; and task breakdowns. | Implemented behavior reference and architectural decision rationale. |
+| Complete copyable artifacts | `examples/` | Maintained configuration, inputs, and other files intended to be copied or run. | Field-by-field reference, command reference, prose explanation. |
+
+Documents that do not exist are required only when the corresponding interface
+or responsibility exists. Do not create placeholder API, consumer, integration,
+or operations documents for behavior the application does not have.
+
+## Boundary Rules
+
+### Orientation
+
+The README owns product orientation. The developer guide routes contributors.
+Architecture owns normative structure. Internal overview owns the current
+concrete component map. These documents may link to one another but should not
+maintain parallel package or behavior descriptions.
+
+### Commands, Configuration, Operations, And Troubleshooting
+
+CLI documentation answers how to invoke the application. Configuration
+documentation answers what settings mean. Operations answers what happens to
+runtime state and how to operate or recover the application. Troubleshooting
+starts from observable symptoms and links readers to the owning command,
+configuration, operational, or integration contract. When a workflow crosses
+these topics, choose the document that owns the task and link to the other
+contracts.
+
+### Contracts And Implementation
+
+Integration and API documents define externally observable shapes and
+semantics. Internal documents explain how Narratio implements or consumes those
+contracts. Internal docs may name a field, file, or protocol to identify a
+dependency, but must link to its canonical contract for the definition.
+
+### Security Topics
+
+This policy owns what documentation and examples may contain. Architecture owns
+application security invariants. Configuration owns credential-supply
+mechanisms. Operations owns permissions and handling of sensitive runtime
+artifacts. Troubleshooting owns safe diagnostic and remediation guidance.
+Internal docs own implementation mechanisms only.
+
+## Architecture Decision Records
+
+Use sequentially numbered ADR filenames such as
+`0001-record-architecture-decisions.md`. Follow the lightweight Nygard format:
+
+1. title;
+2. status;
+3. date;
+4. context;
+5. decision;
+6. alternatives considered;
+7. consequences.
+
+Treat the decision content of an accepted ADR as immutable. When a decision
+changes, create a new ADR and update the earlier ADR's status to superseded.
+Rejected architectural alternatives belong in the ADR; rejected product ideas
+belong in the roadmap.
+
+## Maintenance
+
+When behavior changes, update its canonical owner in the same change. If
+ownership moves, remove the old definition and replace it with a link where
+navigation remains useful.
+
+Before completing documentation work:
+
+- verify affected behavior and examples;
+- check commands, flags, fields, defaults, schemas, and paths against their
+  implementation;
+- keep unimplemented behavior in the roadmap, subject to the ADR exception;
+- remove stale references and validate links;
+- confirm that non-owning documents summarize and link rather than redefine;
+- confirm that no secrets or sensitive private data were added.

docs/policy/testing.md

@@ -0,0 +1,296 @@
+# Testing Policy
+
+## Purpose
+
+Our tests exist to make **incorrect changes expensive and correct changes cheap**.
+
+We do not optimize for test count, line coverage, exhaustive isolation, or the fewest possible tests. We optimize for sufficient confidence in important behavior while imposing as little unnecessary friction as possible on future development.
+
+## Every test has a cost
+
+Testing is not an unqualified good. Every test imposes both an immediate cost and a continuing lifetime cost.
+
+A test must be:
+
+- written and reviewed;
+- understood by future maintainers and coding agents;
+- executed in local and CI workflows;
+- diagnosed when it fails;
+- updated when legitimate behavior changes;
+- maintained as fixtures, APIs, and dependencies evolve; and
+- removed or rewritten when it becomes redundant, brittle, misleading, or obsolete.
+
+Tests also create cognitive and architectural friction. They can constrain refactoring, duplicate policy, slow feedback loops, add noise to failures, and cause harmless implementation changes to require unrelated edits across the suite.
+
+A test is warranted only when the confidence it provides justifies these costs.
+
+Apply this cost-benefit analysis at two levels:
+
+1. **Per test:** What realistic defect does this test detect, how consequential would that defect be, and is that protection worth the test's lifetime cost?
+2. **Across the suite:** Does this collection provide materially more confidence than a smaller, simpler suite would?
+
+The preferred test suite is a **lean suite that provides sufficient confidence in the risks that matter, without redundant or low-value tests**. We seek sufficient confidence with the least unnecessary testing friction, not the fewest possible tests.
+
+Some friction is intentional. Tests should make dangerous changes—such as breaking compatibility, corrupting data, violating security boundaries, or reintroducing subtle bugs—require deliberate review. They should not make ordinary internal changes needlessly expensive.
+
+The cost of a test is not a reason to omit testing by default. Do not cite maintenance cost abstractly. When omitting a plausible test, be able to state why the protected failure is low-risk, already covered, obvious, reversible, or cheaper to detect elsewhere. For consequential, subtle, or difficult-to-observe behavior, the presumption should favor testing.
+
+## Default testing style
+
+Use a **classical/Detroit-style** approach:
+
+- Test observable behavior, resulting state, contracts, and invariants.
+- Use real internal collaborators when they are fast and deterministic.
+- Use fakes, stubs, or mocks primarily at expensive, nondeterministic, destructive, or external boundaries.
+- Prefer package-level behavioral tests over tests coupled to private helpers or internal call sequences.
+- Treat exact collaborator interactions as testable behavior only when the interaction itself is a requirement.
+
+Examples of appropriate seams include clocks, randomness, subprocesses, remote APIs, object storage, email, and paid LLM calls.
+
+## Test execution requirements
+
+Tests in the default suite must be deterministic, offline, and independent of real credentials. They must not invoke paid APIs or depend on mutable external services. Tests that require live infrastructure must be explicitly opt-in and clearly separated from the default suite.
+
+Control clocks, randomness, environment variables, and other process-global or machine-specific state when they affect behavior. Tests should be safe to run repeatedly and alongside other tests without depending on execution order or state left by an earlier test.
+
+## What deserves tests
+
+Prioritize tests for:
+
+1. Public and package-level contracts.
+2. Domain rules and important invariants.
+3. Boundary conditions and malformed input.
+4. Failure handling, cancellation, retries, recovery, and partial success.
+5. Serialization, schemas, compatibility, and round trips.
+6. Previously observed or plausible regressions.
+7. Representative integration and end-to-end workflows.
+
+A package-level contract is behavior relied upon by another package or major collaborator, not every observable detail of a package implementation.
+
+For behavior involving **data integrity, destructive operations, compatibility, security, concurrency, idempotency, or recovery**, presume that durable tests are required unless the behavior is already credibly protected at another layer.
+
+Do not add tests merely because a function, branch, or line exists. Do not add a test when the same meaningful risk is already adequately protected elsewhere.
+
+## Choose the right test boundary
+
+Test through the narrowest stable boundary that expresses the behavior clearly.
+
+This is often the package API, but it may instead be:
+
+- a smaller pure function when dense domain logic is most clearly isolated there;
+- a package-level operation when several internal collaborators jointly produce the behavior; or
+- a larger integration boundary when correctness emerges from interaction with a real dependency.
+
+Do not force all behavior through oversized end-to-end tests. Do not test every private helper merely because it exists. Choose the boundary that gives durable confidence with the least incidental coupling.
+
+## Test behavior, not implementation
+
+A test should protect a decision, contract, or invariant—not memorialize the current implementation.
+
+Before adding or retaining a test, ask:
+
+> What realistic defect would this test catch?
+
+A test is suspect when its main purpose is to detect that someone:
+
+- changed an internal constant;
+- renamed or split a private helper;
+- reordered equivalent internal operations;
+- changed incidental formatting;
+- replaced one correct algorithm with another; or
+- refactored internal object structure without changing behavior.
+
+Refactoring should normally require no test edits unless the refactored structure is itself part of the contract.
+
+A test can be factually correct and still have negative value. Accurately describing current behavior is not enough; the protected behavior must be important enough to justify the future friction.
+
+## Expected effects of different changes
+
+Use the following expectations when evaluating test failures and test maintenance:
+
+| Change | Expected effect on tests |
+|---|---|
+| Internal refactor that preserves behavior | Existing tests should normally remain unchanged and continue to pass. |
+| Change to an internal default with no contractual significance | Behavioral tests should normally remain unchanged; tests should derive expectations from configuration or relationships rather than duplicate the old value. |
+| Intentional change to public behavior, policy, schema, or compatibility guarantees | The relevant tests should be reviewed and changed deliberately. |
+| Accidental violation of a contract or invariant | Tests should fail; fix the production code rather than rewriting the tests to accept the defect. |
+
+A test failing is not the same as a test needing to be edited. Many tests may correctly fail because of one production defect. The maintenance smell is a correct internal change that requires unrelated expectation updates throughout the suite.
+
+## Separate mechanism from policy
+
+Configurable thresholds and defaults must not be duplicated throughout the test suite.
+
+For example, do not encode an internal concurrency limit indirectly:
+
+```go
+// Production policy:
+const maxConcurrency = 4
+
+// Brittle test:
+err := startProcesses(5)
+require.Error(t, err)
+```
+
+Instead, test the mechanism relationally:
+
+```go
+const limit = 2
+runner := NewRunner(limit)
+
+require.NoError(t, runner.Start(limit))
+require.ErrorIs(t, runner.Start(limit+1), ErrTooMuchConcurrency)
+```
+
+The test should prove:
+
+- the configured limit is accepted; and
+- one beyond the configured limit is rejected.
+
+The production default should be tested exactly only when its literal value is itself a public, operational, safety, protocol, or compatibility requirement.
+
+Apply the same rule to limits, timeouts, capacities, retry counts, and ranges: test relationships and behavior, not duplicated literals.
+
+For concurrency limits, test both kinds of behavior when relevant:
+
+1. **Configuration enforcement:** invalid or excessive requested values are handled correctly.
+2. **Runtime enforcement:** observed peak concurrency never exceeds the configured limit.
+
+Use a test-controlled limit and measure the behavior relative to that limit. Do not merely assert today's default value.
+
+## Avoid semantic duplication across layers
+
+Each behavior should have a clear test owner.
+
+- Parser tests own parsing cases.
+- Validator tests own validation rules.
+- Domain tests own transformations and invariants.
+- Adapter tests own external integration behavior.
+- Orchestrator tests own coordination and failure propagation.
+- CLI tests own argument and configuration mapping.
+- End-to-end tests prove that representative assembled workflows work.
+
+Higher-level tests should not repeat every lower-level case. A single intentional policy change should not require unrelated edits across many test files.
+
+Tests that are individually reasonable may still be collectively redundant. Evaluate the marginal value of each additional test in light of the protection already provided by the rest of the suite.
+
+## Use test doubles deliberately
+
+Choose the least elaborate test double that provides the required control or observation.
+
+As a default:
+
+1. Prefer real collaborators when they are fast and deterministic.
+2. Use small in-memory fakes when realistic stateful behavior is helpful.
+3. Use stubs when a dependency only needs to provide controlled responses.
+4. Use mocks when the interaction itself is contractual.
+
+Mocks are appropriate when the contract includes facts such as:
+
+- a notification is sent exactly once;
+- a transaction is committed only after successful writes;
+- cancellation reaches a subprocess;
+- an expensive API is called no more than once; or
+- a security audit event is emitted.
+
+Do not use mocks merely to isolate every object or reproduce the implementation's call graph.
+
+## Go-specific guidance
+
+Use:
+
+- table-driven tests for meaningful behavioral categories and boundaries;
+- `t.TempDir()` for real filesystem behavior;
+- `httptest.Server` for realistic HTTP interactions;
+- fuzz tests for parsers, normalization, path handling, and broad input spaces;
+- golden files only when the complete output is intentionally stable;
+- integration tests where correctness depends on component interaction; and
+- a small number of representative end-to-end tests.
+
+Avoid exact error-string assertions unless the wording is itself contractual. Prefer `errors.Is`, `errors.As`, typed errors, or structured error fields.
+
+At CLI boundaries, prefer exit classifications, structured output, and the smallest stable semantic fragment needed to identify the error. Do not snapshot complete diagnostic wording unless it is contractual.
+
+Golden-file updates must require an explicit local flag. CI must not update golden files automatically, and reviewers must inspect the semantic diff before accepting an update.
+
+Keep tests readable and direct. Test helpers and fixture frameworks must earn their own maintenance cost; do not build elaborate test infrastructure for small or isolated needs.
+
+## Coverage
+
+Coverage is a diagnostic, not a target.
+
+Use it to find untested critical branches and unexpectedly weak packages. Do not write low-value tests solely to increase a percentage, and do not infer test quality from coverage alone.
+
+Pure domain logic will often warrant higher coverage than CLI wiring or external adapters. Uneven coverage is acceptable when it reflects risk.
+
+Increasing coverage is valuable only when the newly covered behavior protects a meaningful risk at an acceptable cost.
+
+## Regression tests
+
+A bug fix should normally include a regression test that fails before the fix and passes afterward.
+
+Retain the test when the defect could realistically recur and its consequences justify the ongoing cost. Prefer the narrowest durable test of the violated contract or invariant; do not preserve accidental implementation details from the original bug.
+
+Not every historical bug requires a permanent test. If the underlying design has made recurrence impossible, the test has become redundant, or a stronger invariant test now subsumes it, remove or consolidate it.
+
+## Deleting or rewriting tests
+
+Tests are maintained code, not permanent historical artifacts.
+
+Delete or rewrite a test when its maintenance cost exceeds the confidence it provides.
+
+Strong candidates include tests that:
+
+- require updates after harmless internal changes;
+- directly assert private constants without protecting a real contract;
+- duplicate the same policy across several layers;
+- verify mock choreography rather than outcomes;
+- snapshot large amounts of incidental output;
+- test trivial private helpers already exercised through stable package behavior;
+- protect risks already covered more effectively elsewhere;
+- are flaky, misleading, obsolete, or disproportionately expensive to diagnose; or
+- no longer correspond to a plausible failure mode.
+
+Several brittle tests may encode one genuine requirement. Replace them with one durable behavior-level or invariant test rather than preserving all of them.
+
+Deleting a low-value test can improve the quality of the suite by reducing noise, maintenance burden, and friction around legitimate change.
+
+## Reviewing a proposed test
+
+Use the following questions when the value, boundary, or durability of a proposed test is not self-evident. Significant test additions should be reviewable against them, but written answers are not required for every routine test.
+
+1. What realistic defect would it catch?
+2. How likely is that defect?
+3. How consequential would it be?
+4. Is the behavior already protected elsewhere?
+5. At which layer should this behavior be owned?
+6. Does the test assert a durable contract or an incidental implementation detail?
+7. Could the implementation be refactored without changing the behavior and without editing this test?
+8. What should cause this test to fail?
+9. What legitimate changes should not cause this test to fail?
+10. What ongoing maintenance, execution, and diagnostic cost will the test impose?
+11. Is there a smaller or more direct test that protects the same risk?
+
+Do not add the test when its expected lifetime cost exceeds its expected protective value.
+
+When deciding not to test plausible behavior, record or be able to explain why the risk is low, already protected, obvious, reversible, or cheaper to detect elsewhere.
+
+## Definition of sufficient
+
+A test suite is sufficient when:
+
+- important contracts and invariants are protected;
+- meaningful boundaries and failure modes are exercised;
+- realistic and consequential regressions are credibly protected against silent recurrence;
+- behavior involving data integrity, destructive operations, compatibility, security, concurrency, idempotency, and recovery is credibly protected;
+- important external boundaries have realistic integration coverage;
+- representative complete workflows are tested;
+- failures provide useful signal rather than redundant noise;
+- legitimate internal changes usually do not require test edits; and
+- additional tests would mostly repeat existing protection or preserve inconsequential implementation details.
+
+Sufficiency is a risk judgment, not a coverage percentage or test count. Reassess it as the application, its users, and the consequences of failure evolve.
+
+The governing rule is:
+
+> Test heavily where failure is consequential, subtle, or difficult to detect after the fact. Test lightly where failure is obvious, reversible, and inexpensive—and retain no test whose lifetime cost exceeds the confidence it provides.

docs/release.md

@@ -0,0 +1,104 @@
+# Releasing Narratio
+
+This document is the maintainer procedure for creating a Narratio source and
+binary release. The synchronous release boundary is a successful push of one
+new tag to `origin`; Woodpecker and Gitea publication happen later and do not
+change that result.
+
+## Go prerequisite
+
+Release preparation requires the maintained Go 1.26 baseline. Tag CI currently
+uses the explicitly pinned `golang:1.26.7` image for candidate validation and
+asset construction; that asynchronous work does not change the tag-push
+completion boundary.
+
+## Choose a version and write its note
+
+Narratio is past `v1.0.0`. Use an unused stable tag in the exact form
+`vMAJOR.MINOR.PATCH`:
+
+- increment `MINOR` for backward-compatible features;
+- increment `PATCH` for backward-compatible fixes; and
+- reserve a new `MAJOR` for an intentional breaking documented contract.
+
+Before preparing the candidate, create
+`docs/releases/vMAJOR.MINOR.PATCH.md` with this structure:
+
+```markdown
+# Narratio vMAJOR.MINOR.PATCH
+
+This release ...
+
+## Summary
+
+## Compatibility
+
+## Upgrade
+
+## Changes
+```
+
+The compatibility section identifies relevant CLI, configuration, artifact,
+integration, or operating-contract changes. The upgrade section states the
+required operator action, or explicitly says that no special action is
+required. Release notes are immutable historical summaries; link to the
+current canonical documentation for detailed behavior.
+
+Commit the note and all candidate changes, then use the ordinary development
+workflow to push that commit to `main`. Do not create a release tag before the
+candidate is committed and `origin/main` contains the exact same commit.
+
+## Validate the candidate
+
+Run the shared checker from any directory:
+
+```sh
+scripts/check-release-candidate.sh vMAJOR.MINOR.PATCH
+```
+
+It validates the version and matching note, module hygiene, formatting,
+whitespace, uncached tests, race tests, static checks, documentation, examples,
+and three official cross-build assets. It uses `GOWORK=off`, does not contact
+application services, CI, or Gitea, and does not create tags or modify tracked
+source. Fix any failure on `main`, commit it, push it normally, and rerun the
+checker.
+
+The checker builds Linux assets for `amd64` and `arm64` and a macOS asset for
+`arm64`. The macOS cross-build proves compilation; it is not native macOS
+runtime evidence.
+
+## Publish the tag
+
+From a clean checkout on `main` whose `HEAD` equals `origin/main`, run:
+
+```sh
+scripts/release.sh vMAJOR.MINOR.PATCH
+```
+
+The command fetches and checks `origin/main`, re-runs candidate validation,
+then fetches and checks again before creating an explicitly unsigned lightweight
+tag for the originally recorded commit. It refuses dirty, divergent, changed,
+or already-tagged candidates. It pushes only:
+
+```text
+refs/tags/vMAJOR.MINOR.PATCH:refs/tags/vMAJOR.MINOR.PATCH
+```
+
+It never commits changes, pushes `main`, force-pushes, moves a tag, or pushes
+all tags. A successful push of that exact ref completes the release command;
+the command prints the tag and commit, then returns without waiting for CI,
+querying Gitea, downloading assets, or checking checksums.
+
+If a failure occurs before the tag is created, correct the candidate on `main`
+and repeat validation. If the push fails after local tag creation, the local tag
+is intentionally retained for inspection and the command must not be retried
+blindly. Once the upstream tag has been pushed, it is immutable. Correct any
+defect or failed asynchronous publication with a new patch version, a new
+release note, and the complete procedure again.
+
+## Optional asynchronous inspection
+
+After a successful tag push, a human may later inspect the tag-triggered
+Woodpecker run and the corresponding Gitea release for binaries and checksums.
+This is optional follow-up only. Automated releasers must not wait for, poll,
+or treat CI/Gitea completion as a condition of the successful tag push.

docs/releases/README.md

@@ -0,0 +1,28 @@
+# Release Notes
+
+This directory contains immutable historical release notes for Narratio.
+Future notes are created with the matching stable version and use this minimum
+structure:
+
+```markdown
+# Narratio vMAJOR.MINOR.PATCH
+
+This release ...
+
+## Summary
+
+## Compatibility
+
+## Upgrade
+
+## Changes
+```
+
+See the [release procedure](../release.md) for creating a candidate and tag.
+When asynchronous publication succeeds, the corresponding Gitea release is the
+canonical source for downloadable binaries and checksums.
+
+- [v2.0.0](v2.0.0.md)
+- [v1.7.0](v1.7.0.md)
+- [v1.6.0](v1.6.0.md)
+- [v1.5.0](v1.5.0.md)

docs/releases/v1.5.0.md

@@ -0,0 +1,47 @@
+# Narratio v1.5.0
+
+Narratio v1.5.0 makes repeated post-transcript artifact development faster and
+more explicit while retaining the fixed, stage-driven pipeline model.
+
+## Highlights
+
+- The canonical pipeline now completes deterministic rendering before
+  extraction, cleanly separating transcript-generating stages from
+  artifact-generating stages.
+- `narratio run` and `narratio session plan` accept inclusive `--from` and
+  `--through` bounds. Excluded transcript stages are not executed or
+  invalidated by a bounded artifact-regeneration run.
+- `narratio regenerate-artifacts SESSION` is an exact convenience alias for a
+  forced run from `extract` through `analyze`, including focused
+  `--artifacts` selections.
+- Configured Scriptorium artifacts now have independent,
+  manifest-authoritative freshness. Narratio reuses validated current work,
+  rebuilds stale prerequisites in dependency order, and persists successful,
+  failed, and newly stale artifact state when an analysis invocation only
+  partially succeeds.
+- Publish consumes only configured artifacts backed by current manifest
+  evidence; incidental or tampered files are not promoted as current output.
+
+## Reliability And Administration
+
+- Bounded prerequisites are checked again under the session lock before any
+  run mutation, closing a concurrent-run race.
+- Analysis fingerprints are stable across executable and configuration path
+  changes and continue to cover only Narratio-observable semantic inputs.
+- Runner composition now carries one validated execution plan from command
+  parsing through prerequisite validation, adapter composition, manifest
+  recording, and stage execution.
+- `narratio version` reports the exact tag embedded in official release
+  binaries; ordinary source builds report `dev`.
+
+## Upgrade Notes
+
+- Existing unbounded commands and direct `run-stage`, `analyze`, and `publish`
+  workflows retain their meanings.
+- Manifests written before artifact-level analysis state remain readable.
+  Legacy aggregate analysis success is not sufficient freshness evidence, so
+  the first analysis evaluation after upgrading may regenerate configured
+  artifacts once.
+- Narratio cannot observe executable contents or configuration, prompt,
+  profile, module, and other files loaded privately by Scriptorium. Explicitly
+  force affected artifacts after changing those private inputs.

docs/releases/v1.6.0.md

@@ -0,0 +1,74 @@
+# Narratio v1.6.0
+
+Narratio v1.6.0 makes large pipeline configurations easier to organize,
+inspect, and vary while adding character-oriented artifact generation and a
+guarded, reproducible release procedure.
+
+## Summary
+
+Pipeline configuration can now be assembled from explicit additive imports and
+a selected production or testing profile. Campaigns can own a canonical,
+versioned party roster, and Scriptorium artifact families can expand one
+definition into concrete per-character artifacts, dependencies, variables, and
+publish rules.
+
+New read-only configuration commands expose the fully resolved pipeline,
+source provenance, semantic digest, and profile differences before a session is
+run. Stage reuse now records configuration-sensitive semantic evidence so
+profile or configuration changes cannot silently reuse incompatible work.
+
+## Compatibility
+
+This is a backward-compatible feature release. Existing monolithic pipeline
+files, concrete Scriptorium artifacts, publish rules, and configurations
+without profiles remain supported. When profiles are declared and no explicit
+profile is selected, Narratio uses the configured production default.
+
+An unversioned party file plus a separate players file remains available as an
+isolated legacy compatibility path, but it cannot drive artifact families. New
+campaigns and new party-oriented features should use the `narratio.party.v1`
+schema. Existing manifests remain readable; missing legacy semantic evidence
+is treated as stale rather than trusted.
+
+Narratio continues to consume the documented Notarius D&D pipeline contract.
+The release workflow still cross-compiles Linux, macOS, and Windows binaries
+for `amd64` and `arm64`; cross-compilation is not native runtime evidence for
+macOS or Windows.
+
+## Upgrade
+
+No special action is required for existing monolithic configurations that do
+not adopt profiles or artifact families. On the first run after upgrading,
+stages recorded by older manifests may regenerate once because those records do
+not contain the new semantic configuration evidence.
+
+To adopt the new configuration model, use the maintained
+`examples/production-testing` bundle as a migration reference: split stable
+settings into explicit imports, define a production default and optional
+testing profile, convert campaign party data to `narratio.party.v1`, remove the
+separate players file, and then introduce character artifact families. Review
+the result with `narratio config validate`, `config show`, `config sources`, and
+`config diff` before running a session.
+
+Campaign, session, previous-session, and run identifiers must satisfy the
+documented portable identity grammar. Existing manifests or remote state with
+unsafe legacy identifiers must be migrated before use.
+
+## Changes
+
+- Added root-owned, non-recursive additive pipeline imports with strict,
+  source-aware conflict detection.
+- Added named pipeline profiles with an explicit production default and
+  deliberate command-line selection.
+- Added `config validate`, `config show`, `config sources`, and `config diff`
+  for read-only inspection of resolved configuration and provenance.
+- Added the strict `narratio.party.v1` campaign roster, including stable
+  character IDs, player and character names, optional aliases, and classes.
+- Added deterministic players derivation and canonical party delivery to
+  downstream integrations.
+- Added character-oriented artifact families, corresponding member
+  dependencies, family selection, and generated publish policies.
+- Added semantic configuration fingerprints and stage-specific resume checks
+  across transcript and artifact stages.
+- Added shared release candidate, asset build, and guarded tag-publication
+  scripts, with tag-triggered publication remaining asynchronous.

docs/releases/v1.7.0.md

@@ -0,0 +1,100 @@
+# Narratio v1.7.0
+
+Narratio v1.7.0 completes the maintainability refactor begun after v1.6.0. It
+simplifies filesystem and process handling, makes resumable work more precise,
+replaces legacy local and remote state with explicit authorities, and turns
+cleanup into the final ordinary pipeline stage.
+
+## Summary
+
+The session manifest is now the sole durable local progress ledger. Analyze
+checkpoints successful artifacts individually, allowing an interrupted or
+partially failed analysis to resume at the first incomplete artifact without
+rerunning successful siblings unless forced.
+
+Remote publication now commits immutable run state before advancing one
+verified current pointer. Publish locks are independent per-source objects;
+locked outputs retain their previously committed declarations rather than
+being overwritten or silently omitted. Local cleanup runs after notification
+as a separately recorded, safely retryable stage.
+
+The release also adopts Go 1.26, simplifies ordinary file operations around
+Narratio's trusted group-owned workspace model, improves subprocess lifecycle
+handling, decomposes several large orchestration and validation components,
+and removes mutable global test seams.
+
+## Compatibility
+
+This is a minor release with deliberate removal of compatibility paths that
+were deprecated and documented as subject to removal:
+
+- Campaigns must use one versioned `narratio.party.v1` `party.yml`. Separate
+  players files, session-level party overrides, and unversioned party documents
+  are rejected.
+- Session manifests must declare `schema_version:
+  narratio.session-manifest.v1` and satisfy the current strict schema. Older
+  unversioned state and manifests containing the retired
+  `post_publish_cleanup` obligation are rejected rather than migrated.
+- Remote current state must be selected by
+  `current/commit-pointer.json` and its referenced immutable run commit. Legacy
+  current-state layouts are no longer inferred.
+- The retired aggregate `locks.yml` object is ignored. Publish locks now live
+  as independent strict objects under the session lock prefix.
+- Run manifests are no longer produced or consumed. The session manifest owns
+  durable stage progress; invocation summaries and run workspaces remain
+  operational data rather than a second progress authority.
+
+The CLI and current pipeline/configuration formats otherwise remain compatible.
+Building and maintaining Narratio now requires Go 1.26. Cross-built Linux,
+macOS, and Windows assets remain available for `amd64` and `arm64`.
+
+## Upgrade
+
+Before upgrading a campaign that still uses compatibility data:
+
+1. Replace legacy party/player inputs with the documented
+   [`narratio.party.v1`](../integrations/party.md) campaign roster.
+2. If a local manifest contains an outstanding `post_publish_cleanup`
+   obligation, complete it with the pre-upgrade binary. Otherwise verify the
+   remote commit, move aside or regenerate the incompatible manifest, or
+   restore a verified committed snapshot. Do not migrate state by manually
+   editing JSON.
+3. Republish sessions that do not yet have a valid immutable run commit and
+   `current/commit-pointer.json`; legacy remote layouts are not current state in
+   v1.7.0.
+4. Recreate any required publication locks with `narratio session locks add`.
+   After verifying the new locks and publication behavior, the ignored legacy
+   `locks.yml` object may be removed manually.
+
+Existing compatible session manifests and already committed remote snapshots
+need no special action. Consult [Operations](../operations.md) and
+[Troubleshooting](../troubleshooting.md) for recovery procedures.
+
+## Changes
+
+- Upgraded the maintained development and release baseline to Go 1.26.
+- Reworked subprocess execution and Windows process-tree supervision while
+  preserving contextual wait and cleanup failures.
+- Replaced custom confined ordinary I/O and directory-promotion machinery with
+  simpler standard-library operations while retaining bounded reads, atomic
+  single-file visibility, workspace modes, validated downloads, and
+  root-confined destructive operations.
+- Removed legacy party, manifest, artifact-discovery, remote-current, and lock
+  compatibility paths.
+- Consolidated durable progress in the session manifest and removed the run
+  manifest domain model.
+- Unified runner planning and execution decisions, separated invocation
+  lifecycle responsibilities, and avoided creating empty run workspaces for
+  fully reused or cleanup-only invocations.
+- Added per-artifact analyze execution, checkpointing, reconciliation, and
+  recovery.
+- Decomposed configuration validation by domain and made validation diagnostics
+  deterministic without treating incidental ordering or wording as a contract.
+- Introduced immutable remote publish commits, one final current pointer,
+  explicit output planning, safe cross-run carried outputs, and independent
+  per-artifact remote locks.
+- Added `cleanup` as the final canonical stage after `notify`, with validated
+  publish evidence, safe retry, explicit selection, and no separate cleanup
+  obligation.
+- Replaced mutable command test hooks with invocation-scoped dependencies and
+  improved structural test diagnostics.

docs/releases/v2.0.0.md

@@ -0,0 +1,94 @@
+# Narratio v2.0.0
+
+Narratio v2.0.0 replaces its configuration infrastructure with ConfigKit,
+simplifies the supported release platforms, and makes artifact definitions and
+their effective dependency graph directly inspectable.
+
+## Summary
+
+Pipeline roots now use ConfigKit v0.1.2 for strict YAML loading, explicit
+imports, fixed-path named profiles, provenance, defaults, and typed credential
+references. The recommended production layout keeps production values in the
+base, defines each ordinary artifact and artifact family in its own imported
+file, and keeps testing changes in `profiles/testing.yml`.
+
+Configured-artifact inputs now create their dependency edges automatically.
+`narratio config artifacts` reports the finalized concrete catalog, including
+generated party-family members, without loading a session or initializing
+runtime adapters.
+
+## Compatibility
+
+This is a breaking configuration and platform release. There is no runtime
+fallback for the retired Narratio composition/profile catalog, `pipeline.secrets`
+or `secrets.env_dir`, credential `_env` fields, or the previous YAML
+presence/default behavior. Defaults apply only to absent values; explicit empty,
+zero, false, and null values retain their typed meaning and may fail Narratio
+domain validation.
+
+The maintained binaries are Linux amd64, Linux arm64, and macOS arm64. Windows
+and macOS amd64 builds are no longer produced or supported. Existing v1 release
+notes remain historical descriptions of their releases.
+
+Inspection commands still avoid session, manifest, workspace, adapter, and
+remote-service activity, but they are not credential-free loaders: every
+explicit typed credential reference in the selected effective configuration must
+resolve; references replaced or removed by that profile need not resolve.
+Pipelines containing artifact families also require a campaign so the canonical
+party can be expanded.
+`config show` is a secret-safe review projection, not a promised reloadable
+authoring file.
+
+## Upgrade
+
+Migrate each operational bundle before running v2:
+
+1. Replace old composition syntax with root-owned
+   [`configkit.imports`](../config.md#pipeline-imports-and-profiles). Imports are
+   additive base sources; they do not override one another.
+2. Fold the old production overlay into the base pipeline. Move testing changes
+   to `profiles/testing.yml`; compare the two independent resolutions with
+   `narratio config diff default testing`.
+3. Follow the maintained
+   [`examples/production-testing`](../../examples/production-testing/pipeline.yml)
+   layout: one explicit artifact entry per `artifacts/<key>.yml` and one family
+   entry per `artifact-families/<key>.yml`. The map key, not the filename, is the
+   stable artifact identity.
+4. Move credential files to an untracked `secrets/` directory beside
+   `pipeline.yml`, or pass `--secrets-dir`. Rename S3 fields to `access_key_id`
+   and `secret_access_key`, and rename the Audita field to `llm_api_key`.
+5. For static S3 credentials, configure both S3 references (commonly
+   `OBJECT_STORAGE_KEY_ID` and `OBJECT_STORAGE_KEY`) and make them resolvable.
+   To use instance roles, workload identity, shared SDK files, or another AWS SDK
+   discovery provider, omit both references. A partial pair is invalid.
+6. Remove a `depends_on` entry when it only duplicates a
+   `narratio.artifact.<key>` input. Keep explicit entries that express ordering
+   without supplying the upstream output as an input.
+7. Review ConfigKit's stricter explicit-value/null semantics and correct values
+   that previously acquired defaults after being explicitly empty. Do not use
+   `config show` output as a source migration mechanism.
+8. Run `config validate`, `config show`, `config sources`, and `config artifacts`
+   with the same profile, campaign, and secrets selection intended for runtime.
+   Resolve the campaign-owned party whenever families are present.
+9. Update deployment and download automation to one of the three maintained
+   platform assets before removing the v1 binary.
+
+The [configuration reference](../config.md), [CLI reference](../cli.md), and
+[maintained examples](../../examples/README.md) are the canonical detailed
+guides.
+
+## Changes
+
+- Adopted ConfigKit v0.1.2 across pipeline, campaign, session, and party loading
+  while keeping Narratio domain validation and post-campaign expansion explicit.
+- Added ConfigKit imports and fixed `profiles/<name>.yml` pipeline overlays,
+  unified safe effective show/diff/digest projection, and source provenance.
+- Added invocation-scoped ConfigKit secrets-directory bootstrap and typed S3 and
+  Audita credential references without exposing resolved values.
+- Inferred, normalized, and validated configured-artifact input dependencies as
+  part of the one concrete graph consumed by analyze planning and resume logic.
+- Added `config artifacts` with stable concrete identities, definition sources,
+  effective dependencies, and generated family/party provenance.
+- Added the maintained production-base/testing-overlay artifact authoring layout.
+- Reduced release assets and active platform support to Linux amd64/arm64 and
+  macOS arm64.

docs/releases/v2.1.0.md

@@ -0,0 +1,70 @@
+# Narratio v2.1.0
+
+This release adds explicit Notarius credential forwarding and cache reuse,
+with predictable forced regeneration and clearer artifact-development guidance.
+
+## Summary
+
+Narratio can pass one typed API-key reference to Notarius and opt into reuse of
+its accepted execution checkpoints. Stable, verified reference snapshots allow
+unchanged references to retain their cache identity across Narratio invocations.
+Configuration loading now uses ConfigKit v0.3.0.
+
+## Compatibility
+
+The new `notarius.llm_api_key`, `notarius.resume`, and `notarius.chunk_cache`
+fields are optional. Existing v2 configuration needs no schema migration.
+Configured credential references must resolve during configuration loading,
+even when extraction will not execute; omitted references add no requirement.
+
+Forced extraction now omits Notarius checkpoint loading and requests chunk-plan
+refresh. This includes `regenerate-artifacts`, which remains an alias for a
+forced run from extract through analyze. `analyze` continues to force analysis
+only, preserving extraction results and transcripts.
+
+Notarius v0.7.0 is the tested cache integration baseline, not an unconditional
+minimum-version gate. The executable must support the flags selected for the
+invocation, including `--chunk_cache refresh` for forced extraction. Reference
+bindings retain the contract introduced in Notarius v0.6.0. Receipt and artifact
+schemas are unchanged; reused producers may report zero production attempts.
+
+Supported release platforms remain Linux amd64/arm64 and best-effort macOS
+arm64. macOS validation is cross-compilation, not native runtime testing.
+
+## Upgrade
+
+No special migration is required for existing v2 configuration. To use the new
+features:
+
+- Declare `notarius.llm_api_key` with the environment-variable name expected by
+  the deployed Notarius profile, supplying its value through the existing
+  environment or secrets-directory mechanism.
+- Enable checkpoint recording in Notarius configuration before setting
+  Narratio's `notarius.resume: true`. Prefer explicit persistent Notarius cache
+  roots for service deployments. An optional `notarius.chunk_cache` overrides
+  its ordinary chunk-plan policy.
+- Expect an initial checkpoint miss when moving from old run-local reference
+  paths to stable session snapshots. No migration or deletion of old caches is
+  required. Force refreshes the current input's plan, not the whole cache.
+- Use `narratio analyze SESSION` for analysis-only iteration, and
+  `narratio regenerate-artifacts SESSION` when extraction should also be rebuilt.
+
+See [Configuration](../config.md), the
+[Notarius integration contract](../integrations/notarius.md), and
+[Artifact Development Workflows](../operations.md#artifact-development-workflows)
+for current details.
+
+## Changes
+
+- Upgraded ConfigKit from v0.1.2 to v0.3.0 and isolated pipeline-discovery tests
+  from machine configuration.
+- Added optional typed Notarius credentials, exact-name environment delivery,
+  safe configuration projections, and captured-stream redaction for custom names.
+- Added Notarius resume and chunk-cache controls with force taking precedence.
+- Added verified, content-addressed session reference snapshots that survive
+  ordinary run cleanup without becoming published artifacts.
+- Preserved relative-workspace support for snapshot delivery and confinement.
+- Kept credentials and cache-policy controls outside extract's semantic resume
+  identity, so operational changes alone do not invalidate completed results.
+- Added an opt-in real Notarius integration test using a local provider to
+  verify reuse, partial-failure recovery, and forced refresh without paid calls.

docs/releases/v2.1.1.md

@@ -0,0 +1,33 @@
+# Narratio v2.1.1
+
+This release fixes configuration loading for publish rules that explicitly set
+requiredness while relying on a derived destination.
+
+## Summary
+
+Publish rules with a derivable source and omitted `dest` now load correctly
+whether `required` is omitted, explicitly true, or explicitly false. Previously,
+explicit requiredness could trigger ConfigKit's `resolve.unrecorded_change`
+diagnostic instead of accepting valid configuration.
+
+## Compatibility
+
+This is a backward-compatible bookkeeping correction. Publish schemas,
+destination derivation, requiredness defaults, and YAML syntax support are
+unchanged. Explicit destinations and explicit false values remain intact.
+No ConfigKit upgrade or publication/storage behavior change is involved.
+
+## Upgrade
+
+No special upgrade action or configuration migration is required. Operators
+need not add a derivable `dest`, remove explicit `required` values, or change
+flow-style YAML to block-style YAML. See the
+[configuration reference](../config.md#publish-configuration-summary).
+
+## Changes
+
+- Recorded derived publish destinations at ConfigKit's atomic sequence boundary
+  while retaining field-level resolution records.
+- Added real load/validation and safe effective-configuration regression coverage
+  for built-in and configured-artifact sources, explicit requiredness, and an
+  explicit destination that must remain unchanged.

docs/releases/v2.1.2.md

@@ -0,0 +1,26 @@
+# Narratio v2.1.2
+
+This release allows secrets directories to contain hidden metadata without
+preventing credential loading.
+
+## Summary
+
+ConfigKit v0.3.1 ignores dot-prefixed entries such as `.git`, `.gitignore`, and
+`.DS_Store` during secrets bootstrap. These entries no longer block otherwise
+valid credentials from loading and are omitted from bootstrap reports.
+
+## Compatibility
+
+This is a backward-compatible dependency bug fix. Configuration schemas,
+existing-environment precedence, and validation of non-hidden entries are
+unchanged. Hidden entries still count toward the directory entry limit.
+
+## Upgrade
+
+No special upgrade action or configuration migration is required. See the
+[credential configuration reference](../config.md) for secrets-directory usage.
+
+## Changes
+
+- Updated ConfigKit from v0.3.0 to v0.3.1.
+- Clarified hidden-entry handling in the secrets-directory documentation.

docs/roadmap/fix-publish-output-destination-resolution.md

@@ -0,0 +1,171 @@
+# Bugfix Request: Preserve Publish Destination Derivation with Explicit Rules
+
+Status: Implemented; release target v2.1.1
+
+## Summary
+
+Narratio should successfully derive a publish destination when a valid
+`publish.outputs` rule omits `dest`, regardless of whether that rule explicitly
+sets `required`. Narratio v2.1.0 currently rejects this valid configuration in
+some cases with a ConfigKit `resolve.unrecorded_change` diagnostic.
+
+This is a configuration-resolution bookkeeping defect, not a YAML formatting
+restriction. The fix should preserve the existing public configuration
+contract: operators may omit a derivable destination and may independently set
+`required` to either `true` or `false`.
+
+## Observed Behavior
+
+A pipeline containing a rule equivalent to the following fails during native
+configuration loading:
+
+```yaml
+publish:
+  outputs: [{"source": "narratio.transcript.final", "required": true}]
+```
+
+Narratio reports:
+
+```text
+error [resolve.unrecorded_change] /publish/outputs: application resolution changed a value without a covering record
+```
+
+The same failure is possible with ordinary block-style YAML when `required` is
+explicit and `dest` is omitted. Flow-style YAML is valid input and is not the
+cause of the defect.
+
+The existing destination-derivation tests do not expose this case because
+their rules also omit `required`. Narratio then supplies the default value for
+`required` and records a change covering the complete `publish.outputs`
+sequence. That broader record happens to cover the destination mutation as
+well, masking the missing resolution record that occurs when `required` is
+already explicit.
+
+## Expected Contract
+
+The current configuration contract remains unchanged:
+
+- `publish.outputs[].source` is required;
+- `publish.outputs[].dest` may be omitted when Narratio can derive it from the
+  selected built-in or configured artifact source;
+- `publish.outputs[].required` defaults to `true`, but an operator may set it
+  explicitly to either `true` or `false`; and
+- equivalent valid YAML representations have equivalent configuration
+  semantics.
+
+For example, both rules below should load and validate, retain their explicit
+requiredness, and receive the canonical derived destination:
+
+```yaml
+publish:
+  outputs:
+    - source: narratio.transcript.final
+      required: true
+    - source: narratio.transcript.final_markdown
+      required: false
+```
+
+## Root Cause
+
+ConfigKit intentionally treats sequences as atomic when comparing values
+before and after application resolution. Changing a field within one
+`publish.outputs` entry is therefore observed as a change to the
+`/publish/outputs` sequence.
+
+Narratio currently derives each missing destination by recording a
+normalization at the individual `publish.outputs[index].dest` path. That child
+record does not cover the atomic parent-sequence change. A separate
+container-level record is currently created only when Narratio also defaults
+an omitted `required` value, so configurations with explicit `required` values
+lose that incidental coverage.
+
+## Recommended Fix
+
+Make Narratio's publish-output resolution bookkeeping conform to ConfigKit's
+atomic-sequence contract. Whenever resolution derives one or more destinations
+inside `publish.outputs`, the recorded resolution changes must cover the
+`/publish/outputs` container. Destination derivation must not depend on an
+unrelated `required` default being applied in the same list.
+
+The implementation may retain more specific provenance where useful, but it
+must provide valid container-level coverage for the sequence mutation. Do not
+change ConfigKit's sequence comparison semantics merely to accommodate this
+call site.
+
+## Scope
+
+- Correct destination derivation for publish rules that explicitly set
+  `required` and omit a derivable `dest`.
+- Preserve explicit `required: true` and `required: false` values.
+- Preserve canonical destination derivation for built-in transcript sources
+  and configured artifact sources.
+- Add focused regression coverage through Narratio's real configuration load
+  and validation boundary.
+- Prepare a backward-compatible patch release after the fix passes the normal
+  repository validation.
+
+## Non-goals
+
+- Changing the `publish.outputs` schema, defaults, source vocabulary, or
+  destination derivation rules.
+- Requiring operators or configuration generators to supply `dest` when it is
+  derivable.
+- Requiring operators to omit explicit `required: true` values.
+- Treating flow-style YAML or JSON-compatible YAML values as unsupported.
+- Changing ConfigKit's documented atomic treatment of sequences.
+- Adding storage, publication, or network integration behavior.
+
+## Regression Coverage
+
+Add one focused package-level behavioral test that loads and validates a
+pipeline with omitted destinations and explicit requiredness. A representative
+list should include both `required: true` and `required: false`, then assert
+that:
+
+- loading and validation succeed;
+- each destination is derived from its source; and
+- each explicit `required` value is preserved.
+
+Using the compact flow-style representation that exposed the integration
+failure is reasonable, while the existing block-style cases continue to cover
+omitted `required`. The test should exercise the public configuration behavior,
+not ConfigKit call choreography or Narratio's private recording mechanism.
+
+No network service, object store, credential, or test double is required.
+
+## Target End State
+
+All valid publish rules with derivable sources behave consistently across
+these cases:
+
+| `dest` | `required` | Result |
+| --- | --- | --- |
+| omitted | omitted | destination derived; required defaults to `true` |
+| omitted | `true` | destination derived; explicit `true` retained |
+| omitted | `false` | destination derived; explicit `false` retained |
+| explicit | either value | explicit destination and requiredness retained |
+
+`narratio config validate`, `narratio config show`, and ordinary pipeline
+loading accept the corrected cases without an unrecorded-change diagnostic.
+No operator configuration migration or workaround is required.
+
+## Release
+
+This is a backward-compatible correction to documented configuration behavior
+and should be released as Narratio `v2.1.1`. The release note should identify
+the corrected explicit-required/derived-destination interaction and state that
+no special upgrade action is required.
+
+## Acceptance Criteria
+
+- The focused regression test fails against v2.1.0 behavior and passes after
+  the fix.
+- Publish rules with explicit `required: true` or `required: false` and omitted
+  derivable destinations load and validate successfully.
+- Derived destinations and explicit requiredness appear correctly in the safe
+  effective configuration.
+- Existing destination derivation, publish validation, imports, profiles, and
+  configuration inspection tests remain green.
+- The complete repository validation and release-candidate checks pass.
+- The correction is published as the immutable `v2.1.1` tag with the required
+  release note.

docs/roadmap/runtime-artifacts.md

@@ -1,762 +0,0 @@
-# Roadmap: Runtime-Defined Scriptorium Artifacts
-
-## Status
-
-Implementation roadmap for a pre-release hard cutover.
-
-## Purpose
-
-Narratio currently treats artifact generation as a narrow `analyze` stage that supports a hard-coded `session_recap` artifact. This roadmap describes how to generalize artifact generation so operators can define Scriptorium-backed output artifacts at runtime through `pipeline.yml`.
-
-The goal is to keep Narratio as a fixed pipeline orchestrator while making the artifact generation step configurable, composable, deterministic, and easy to regenerate selectively.
-
-## Desired Outcome
-
-Operators should be able to define artifacts such as session recaps, player handouts, NPC summaries, quest logs, entity maps, or other campaign-specific outputs without changing Narratio code.
-
-A configured artifact is declared under:
-
-```text
-pipeline.scriptorium.artifacts.<name>
-```
-
-Each configured artifact becomes a canonical runtime artifact source ID:
-
-```text
-narratio.artifact.<name>
-```
-
-For example:
-
-```yaml
-scriptorium:
-  artifacts:
-    session_recap:
-      enabled: true
-      prompt_id: dnd_session.session_recap
-      output_path: artifacts/session_recap.md
-      inputs:
-        transcript:
-          source: narratio.transcript.trimmed
-          required: true
-```
-
-This artifact is addressable by later artifacts as:
-
-```text
-narratio.artifact.session_recap
-```
-
-A dependent artifact can then consume it explicitly:
-
-```yaml
-scriptorium:
-  artifacts:
-    player_handout:
-      enabled: true
-      depends_on:
-        - session_recap
-      prompt_id: dnd_session.player_handout
-      output_path: artifacts/player_handout.md
-      inputs:
-        recap:
-          source: narratio.artifact.session_recap
-          required: true
-        transcript:
-          source: narratio.transcript.trimmed
-          required: true
-```
-
-## Resolved Design Decisions
-
-The following decisions are settled for the initial implementation:
-
-1. Configured artifact outputs must live under Narratio's internal artifact output directory, initially `artifacts/`.
-2. The artifact output directory should be defined as an internal default in `internal/config/defaults.go`, but no public configuration knob should be exposed yet.
-3. Artifact `output_path` should remain explicit in the initial implementation to avoid guessing file extensions or output formats.
-4. A disabled artifact may still be referenced as an input if its declared output already exists on disk and passes basic validation.
-5. A disabled artifact is not executable during the current analyze run.
-6. Artifact-to-artifact references require an explicit `depends_on` entry. Narratio should fail fast if the dependency declaration is missing.
-7. The manifest remains stage-oriented: `analyze` succeeds or fails as a full stage.
-8. Analyze-stage metadata may record per-artifact output details for provenance and later resolution, but not for intra-stage resume semantics.
-9. `--artifacts` should be added as a CLI filter for selective artifact generation.
-10. `--artifacts` does not imply `--force`; it only changes which configured artifacts are treated as executable when `analyze` actually runs.
-11. Because Narratio is still pre-release, the hard-coded `session_recap` behavior should be removed immediately rather than deprecated gradually.
-
-## Scope
-
-This roadmap covers:
-
-- introducing a runtime artifact catalog;
-- generalizing configured Scriptorium artifact execution;
-- supporting `narratio.artifact.<name>` source IDs;
-- adding explicit artifact dependencies;
-- supporting disabled-but-resolvable artifact inputs;
-- adding selective artifact execution via `--artifacts`;
-- recording generated artifacts in analyze-stage metadata and/or manifest outputs;
-- removing hard-coded `session_recap` behavior;
-- updating tests and documentation.
-
-## Non-Goals
-
-This feature should not turn Narratio into a general workflow engine.
-
-The initial implementation should not add:
-
-- arbitrary shell-command artifacts;
-- arbitrary user-defined stages;
-- loops or conditional branching;
-- automatic archive promotion of generated artifacts;
-- semantic knowledge of particular artifact types;
-- per-artifact resume semantics within a successful or failed analyze stage;
-- automatic dependency inference without `depends_on`.
-
-Narratio should continue to orchestrate a fixed pipeline. The configurable part is the set of Scriptorium artifact invocations performed during the `analyze` stage.
-
-## Current State
-
-Narratio already has several relevant pieces in place:
-
-- `pipeline.scriptorium.artifacts` is modeled as a map of artifact definitions.
-- The Scriptorium adapter already accepts generic run/render requests.
-- The artifact resolver already understands canonical artifact source IDs.
-- The `analyze` stage already resolves inputs, optionally runs render-debug, invokes Scriptorium, verifies output, and records metadata.
-
-The main limitation is that `analyze` currently treats `session_recap` as the only executable artifact and rejects other enabled artifact definitions.
-
-## Target Architecture
-
-### Runtime Artifact Catalog
-
-Introduce a per-run artifact catalog that tracks built-in artifacts and configured artifacts.
-
-Conceptually:
-
-```text
-ArtifactCatalog
-├── built-in artifacts
-│   ├── narratio.transcript.merged
-│   ├── narratio.transcript.polished
-│   ├── narratio.transcript.full
-│   ├── narratio.transcript.trimmed
-│   └── narratio.bounds.session
-│
-└── configured artifacts
-    ├── narratio.artifact.session_recap
-    ├── narratio.artifact.player_handout
-    └── narratio.artifact.npc_summary
-```
-
-The catalog should distinguish between three states:
-
-```text
-planned       valid configured or built-in artifact known to Narratio
-available     artifact has been produced or otherwise resolved
-executable    configured artifact selected for execution in this analyze run
-```
-
-Configured artifacts can be planned without being executable. This distinction is important for disabled artifacts and for `--artifacts` filtering.
-
-### Configured Artifact Source IDs
-
-Configured artifact keys map directly to source IDs:
-
-```text
-pipeline.scriptorium.artifacts.<name>
-→ narratio.artifact.<name>
-```
-
-`session_recap` should no longer be a special built-in analyze artifact. Instead, it is just a conventional configured artifact key:
-
-```yaml
-scriptorium:
-  artifacts:
-    session_recap:
-      enabled: true
-      prompt_id: dnd_session.session_recap
-      output_path: artifacts/session_recap.md
-```
-
-`narratio.artifact.session_recap` remains valid only because `session_recap` is configured.
-
-### Artifact Output Directory
-
-Add an internal default artifact output directory, initially:
-
-```text
-artifacts
-```
-
-This default should live in `internal/config/defaults.go` or the existing equivalent defaults location.
-
-For the initial implementation:
-
-- expose no public config knob for the artifact output directory;
-- require each configured artifact to provide an explicit `output_path`;
-- validate that each configured artifact `output_path` is run-relative;
-- validate that each configured artifact `output_path` is under the internal artifact output directory;
-- reject output paths that escape the run workspace or use path traversal.
-
-This preserves future configurability without forcing Narratio to guess output extensions or formats now.
-
-### Enabled, Disabled, and Selected Artifacts
-
-Configured artifacts should have three distinct execution states:
-
-```text
-enabled by config       artifact has enabled: true
-selected for execution  artifact remains executable after --artifacts filtering
-disabled for execution  artifact is not executable, but may be resolvable from disk
-```
-
-Without `--artifacts`, all configured artifacts with `enabled: true` are selected for execution.
-
-With `--artifacts`, only the named artifacts are selected for execution. All other configured artifacts are treated as disabled for the current analyze invocation, regardless of their configured `enabled` value.
-
-Disabled artifacts may still be resolved as inputs if their configured `output_path` exists on disk and passes validation.
-
-### Disabled Artifact Resolution
-
-If artifact `B` references artifact `A`, and `A` is disabled for execution, Narratio should attempt to resolve `A` from disk.
-
-This should succeed only when:
-
-1. `A` is defined in `pipeline.scriptorium.artifacts`;
-2. `A` has a valid `output_path`;
-3. the output path exists in the current run workspace;
-4. the output is non-empty, or otherwise passes any available artifact-specific validation.
-
-The resolved provenance should make the source clear, for example:
-
-```text
-filesystem.disabled_artifact_output
-```
-
-If the file does not exist or fails validation, the dependent artifact should fail before invoking Scriptorium.
-
-Example error wording:
-
-```text
-artifact player_handout requires narratio.artifact.session_recap, but session_recap is disabled for execution and artifacts/session_recap.md does not exist
-```
-
-### Explicit Dependencies
-
-Artifact-to-artifact references require explicit `depends_on` entries.
-
-If artifact `B` has an input source of `narratio.artifact.A`, then `B.depends_on` must include `A`.
-
-This should fail:
-
-```yaml
-scriptorium:
-  artifacts:
-    player_handout:
-      enabled: true
-      prompt_id: dnd_session.player_handout
-      output_path: artifacts/player_handout.md
-      inputs:
-        recap:
-          source: narratio.artifact.session_recap
-          required: true
-```
-
-This should pass:
-
-```yaml
-scriptorium:
-  artifacts:
-    player_handout:
-      enabled: true
-      depends_on:
-        - session_recap
-      prompt_id: dnd_session.player_handout
-      output_path: artifacts/player_handout.md
-      inputs:
-        recap:
-          source: narratio.artifact.session_recap
-          required: true
-```
-
-`depends_on` values refer to configured artifact keys, not full source IDs.
-
-Dependency validation should fail on:
-
-- references to unknown artifact keys;
-- missing `depends_on` entries for artifact-to-artifact input references;
-- self-dependencies;
-- dependency cycles among executable artifacts.
-
-Dependencies on disabled artifacts are permitted, but the disabled dependency must resolve from disk before the dependent artifact runs.
-
-### Execution Order
-
-The analyze stage should execute selected artifacts in dependency order.
-
-Rules:
-
-- selected artifacts are executable;
-- disabled artifacts are never executed;
-- selected artifacts may depend on other selected artifacts;
-- selected artifacts may depend on disabled artifacts if those disabled artifacts resolve from disk;
-- independent selected artifacts run in deterministic sorted-name order.
-
-Use topological sorting over selected artifacts, while validating dependency references across the full configured artifact set.
-
-### Input Resolution
-
-Input resolution should use the artifact catalog and existing artifact resolver behavior.
-
-For each configured artifact input:
-
-- built-in sources resolve through existing resolver behavior;
-- `previous_session_artifact` preserves existing behavior;
-- `narratio.artifact.<name>` resolves through the runtime artifact catalog;
-- selected dependencies resolve after being produced earlier in the same analyze execution;
-- disabled dependencies resolve from their configured output path on disk;
-- optional missing inputs are omitted;
-- required missing inputs fail before Scriptorium is invoked.
-
-### Analyze Stage Generalization
-
-The `analyze` stage should become the generic Scriptorium artifact stage.
-
-High-level flow:
-
-1. Load configured Scriptorium artifacts.
-2. Apply the `--artifacts` filter, if present.
-3. If no artifacts are selected for execution, return success metadata with `skipped=true`.
-4. Build the runtime artifact catalog.
-5. Validate artifact names, output paths, source IDs, dependencies, selected artifacts, and required fields.
-6. Resolve any disabled dependencies that are required by selected artifacts.
-7. Sort selected artifacts by dependency order.
-8. For each selected artifact:
-   - resolve configured inputs;
-   - build the Scriptorium run request;
-   - optionally run Scriptorium render-debug;
-   - run Scriptorium;
-   - fail on validation-failed result;
-   - verify the output exists and is non-empty;
-   - record artifact output metadata;
-   - register `narratio.artifact.<name>` as available in the catalog.
-9. Return aggregate analyze-stage metadata containing all generated and reused artifacts relevant to the run.
-
-The Scriptorium adapter should remain generic. It should not decide which artifacts run, how dependencies work, or how artifacts are registered.
-
-### Manifest and Metadata
-
-The manifest should remain stage-oriented.
-
-This means:
-
-- `analyze` succeeds or fails as a full stage;
-- if `analyze` has already succeeded and the user does not force it, the runner skips it as a full stage;
-- Narratio should not implement per-artifact resume in the first version.
-
-However, analyze-stage metadata should still record artifact outputs for provenance and future resolution.
-
-Recommended metadata shape:
-
-```json
-{
-  "skipped": false,
-  "artifacts": [
-    {
-      "name": "session_recap",
-      "source_id": "narratio.artifact.session_recap",
-      "output_kind": "scriptorium_artifact",
-      "path": "artifacts/session_recap.md",
-      "prompt_id": "dnd_session.session_recap",
-      "profile_id": "local-gemma-31b",
-      "provenance": "generated.current_analyze_run"
-    },
-    {
-      "name": "player_handout",
-      "source_id": "narratio.artifact.player_handout",
-      "output_kind": "scriptorium_artifact",
-      "path": "artifacts/player_handout.md",
-      "prompt_id": "dnd_session.player_handout",
-      "profile_id": "local-gemma-31b",
-      "provenance": "generated.current_analyze_run"
-    }
-  ],
-  "reused_artifacts": [
-    {
-      "name": "session_recap",
-      "source_id": "narratio.artifact.session_recap",
-      "path": "artifacts/session_recap.md",
-      "provenance": "filesystem.disabled_artifact_output"
-    }
-  ]
-}
-```
-
-The exact struct can differ from this example, but it should preserve:
-
-- artifact name;
-- canonical source ID;
-- output path;
-- prompt/profile provenance for generated artifacts;
-- reused-vs-generated provenance.
-
-### Resume and Force Behavior
-
-Keep resume behavior stage-level.
-
-Recommended semantics:
-
-```text
-No --force, analyze already succeeded:
-  runner skips analyze, regardless of --artifacts.
-
---force, no --artifacts:
-  analyze regenerates all configured artifacts with enabled: true.
-
---force --artifacts player_handout:
-  analyze treats only player_handout as executable.
-  all other configured artifacts are disabled for execution.
-  disabled dependencies may be reused from disk.
-
---artifacts player_handout on a not-yet-completed analyze stage:
-  analyze runs only player_handout.
-  disabled dependencies may be reused from disk.
-```
-
-`--artifacts` should not imply `--force`. It is an execution filter, not a resume override.
-
-### `--artifacts` CLI Flag
-
-Add an `--artifacts` flag to commands that can execute or resume the analyze stage.
-
-The flag should accept one or more configured artifact names. Internally, normalize values to a set of artifact keys.
-
-Recommended behavior:
-
-- validate all requested artifact names against `pipeline.scriptorium.artifacts`;
-- reject unknown artifact names before running stages;
-- treat requested artifacts as the only executable artifacts for the analyze stage;
-- treat all other configured artifacts as disabled for execution;
-- allow disabled artifacts to satisfy dependencies from disk as described above;
-- if `--artifacts` is used while executing a stage other than `analyze`, either reject it or ignore it with a clear validation error. Prefer rejection.
-
-The exact CLI parsing style can follow Narratio's existing conventions. Both comma-separated and repeatable values are acceptable if the CLI package supports them cleanly, but the internal representation should be a set of artifact keys.
-
-### Archive Behavior
-
-Do not automatically archive every generated artifact.
-
-Artifact generation and archive promotion should remain separate concerns. Operators should continue to use `archive.promote_artifacts` to decide which generated files should be promoted or uploaded.
-
-Example:
-
-```yaml
-archive:
-  promote_artifacts:
-    - from: artifacts/session_recap.md
-      to: artifacts/session_recap.md
-      required: true
-    - from: artifacts/player_handout.md
-      to: artifacts/player_handout.md
-      required: false
-```
-
-A later enhancement may add opt-in automatic promotion of configured artifacts, but explicit promotion should remain the default.
-
-## Implementation Plan
-
-### Phase 1: Config Model and Defaults
-
-Add or update the configured artifact model to include:
-
-- `enabled`;
-- `depends_on`;
-- `prompt_id`;
-- `profile_id`;
-- `output_path`;
-- `timeout`;
-- `render_debug`;
-- `inputs`;
-- `vars`.
-
-Add an internal default artifact output directory in `internal/config/defaults.go`, initially set to `artifacts`.
-
-Validation rules:
-
-- artifact names must match a conservative identifier pattern such as `^[a-z][a-z0-9_]*$`;
-- selected/executable artifacts require `prompt_id` and `output_path`;
-- configured artifacts that may be referenced while disabled require `output_path`;
-- configured artifact output paths must be run-relative;
-- configured artifact output paths must live under the internal artifact output directory;
-- configured artifact output paths must not escape the run workspace;
-- `narratio.artifact.<name>` input sources must refer to configured artifact keys;
-- any `narratio.artifact.<name>` input source must have a matching `depends_on` entry;
-- `depends_on` entries must refer to configured artifact keys;
-- dependencies must not contain self-references or executable cycles;
-- input names and var names must remain compatible with the Scriptorium adapter's validation rules;
-- unknown YAML fields must continue to fail strict decode.
-
-Tests:
-
-- valid single configured artifact;
-- valid multiple independent artifacts;
-- valid artifact-to-artifact dependency;
-- valid dependency on disabled artifact with output path;
-- invalid artifact name;
-- missing required fields;
-- output path outside `artifacts/`;
-- dependency on missing artifact;
-- missing `depends_on` for artifact input source;
-- self-dependency;
-- cycle detection;
-- typo in `narratio.artifact.<name>` source;
-- unknown YAML fields still fail strict decode.
-
-### Phase 2: CLI Filtering
-
-Add the `--artifacts` flag and carry the selected artifact set into the run execution options.
-
-Implementation notes:
-
-- parse values according to existing CLI conventions;
-- normalize to artifact key strings;
-- validate against configured artifact definitions after config load;
-- make the selected set available to the analyze stage;
-- reject use with commands or stages where analyze cannot run.
-
-Tests:
-
-- no `--artifacts` means all enabled artifacts are selected;
-- one requested artifact is selected;
-- multiple requested artifacts are selected;
-- unknown requested artifact fails;
-- `--artifacts` does not imply `--force`;
-- `--artifacts` with already-succeeded analyze stage is skipped unless forced;
-- `--artifacts` on unsupported stage command fails clearly.
-
-### Phase 3: Runtime Artifact Catalog
-
-Introduce an internal artifact catalog abstraction.
-
-Responsibilities:
-
-- register built-in artifact definitions;
-- register configured artifact definitions;
-- map configured artifact keys to `narratio.artifact.<name>` IDs;
-- track planned, available, and executable artifact states;
-- expose lookup by canonical source ID;
-- record generated provenance;
-- record disabled-from-disk provenance.
-
-Keep the catalog narrow. It should not execute Scriptorium and should not understand prompt semantics.
-
-Tests:
-
-- built-in source lookup;
-- configured source registration;
-- duplicate/conflicting source handling;
-- planned but unavailable artifact lookup;
-- selected artifact state;
-- disabled artifact state;
-- registering an artifact as available after generation;
-- registering a disabled artifact as available from disk;
-- resolving a configured artifact from analyze metadata if that behavior is implemented.
-
-### Phase 4: Resolver Integration
-
-Update artifact resolution so configured artifact IDs are resolved through the runtime catalog.
-
-Resolution behavior:
-
-- built-in sources continue using existing resolver behavior;
-- configured artifact sources resolve from catalog availability/provenance;
-- selected configured artifacts become available after generation;
-- disabled configured artifacts may become available from disk;
-- missing optional configured artifact inputs are omitted;
-- missing required configured artifact inputs fail clearly.
-
-Tests:
-
-- configured artifact consumes a built-in transcript source;
-- configured artifact consumes another configured artifact produced earlier in the same analyze run;
-- configured artifact consumes a disabled artifact resolved from disk;
-- required disabled artifact missing on disk fails;
-- required configured artifact missing fails;
-- optional missing configured artifact is omitted;
-- reused artifact provenance is recorded distinctly from generated artifact provenance.
-
-### Phase 5: Analyze Stage Generalization
-
-Refactor `analyze` to execute selected configured artifacts.
-
-Implementation notes:
-
-- remove the hard-coded `session_recap` selection path;
-- remove the hard-coded rejection of non-`session_recap` artifacts;
-- preserve skip behavior when Scriptorium config is absent or no artifacts are selected;
-- build the runtime artifact catalog;
-- apply `--artifacts` filtering;
-- validate selected artifacts and their dependencies;
-- pre-resolve disabled dependencies from disk where required;
-- compute deterministic dependency order;
-- execute selected artifacts one at a time in dependency order;
-- keep render-debug behavior at global and artifact levels;
-- keep Scriptorium adapter invocation generic;
-- after each successful run, register the artifact as available in the catalog;
-- aggregate generated and reused artifact metadata.
-
-Tests:
-
-- no Scriptorium config skips;
-- empty artifact map skips;
-- no selected artifacts skips;
-- disabled artifacts do not run;
-- one selected artifact runs;
-- multiple independent artifacts run in deterministic order;
-- dependent selected artifact receives prior selected artifact as input;
-- dependent selected artifact receives disabled-from-disk artifact as input;
-- render-debug works for configured artifacts;
-- Scriptorium validation failure fails the stage;
-- missing required input fails the stage;
-- successful outputs are non-empty and recorded;
-- artifact filter executes only requested artifacts.
-
-### Phase 6: Manifest and Stage Metadata
-
-Update analyze-stage metadata and manifest output recording to support dynamic configured artifacts.
-
-Recommended behavior:
-
-- every generated configured artifact gets `source_id: narratio.artifact.<name>`;
-- every generated configured artifact gets a generic output kind such as `scriptorium_artifact`;
-- reused disabled artifacts are recorded separately from generated artifacts;
-- metadata is sufficient for debugging, provenance, and future resolver support;
-- metadata does not create per-artifact resume semantics.
-
-Because this is a pre-release hard cutover, do not preserve a special legacy `session_recap` output kind unless a current internal test or archive path still requires it temporarily. Prefer updating tests and examples to treat `session_recap` as an ordinary configured artifact.
-
-Tests:
-
-- metadata records one generated configured artifact;
-- metadata records multiple generated configured artifacts;
-- metadata records reused disabled artifact provenance;
-- `session_recap` is recorded as a normal configured artifact;
-- manifest still treats `analyze` as a single succeeded or failed stage;
-- runner skip behavior remains stage-level.
-
-### Phase 7: Archive and Promotion Review
-
-Review archive behavior after dynamic artifacts are recorded.
-
-Implementation notes:
-
-- do not automatically promote every configured artifact;
-- keep `archive.promote_artifacts` explicit;
-- update default or example promotion rules to use configured `session_recap` output path;
-- ensure required promotion rules fail clearly when selected artifact generation did not produce a required file.
-
-Tests:
-
-- generated artifact can be promoted by explicit archive rule;
-- required archive promotion fails if selected artifact was not generated and no file exists;
-- optional archive promotion skips cleanly if file is absent;
-- hard cutover does not rely on hard-coded `session_recap` generation.
-
-### Phase 8: Documentation and Examples
-
-Status: complete.
-
-Update documentation after the implementation is complete.
-
-Recommended documentation changes:
-
-- update `docs/config.md` with the generalized artifact configuration model;
-- update `docs/internal/artifacts.md` to describe the runtime artifact catalog;
-- update `docs/stages/analyze.md` to describe generic Scriptorium artifact generation;
-- update Scriptorium integration docs only if the adapter contract changes;
-- update full annotated pipeline examples;
-- add at least one example with multiple artifacts and one dependency;
-- document `--artifacts` behavior and its relationship to `--force`;
-- remove documentation stating that only `session_recap` is supported.
-
-Documentation should make clear that:
-
-- configured artifact source IDs use `narratio.artifact.<name>`;
-- `depends_on` uses artifact keys, not full source IDs;
-- artifact-to-artifact source references require explicit `depends_on`;
-- disabled artifacts can be reused from disk when required by selected artifacts;
-- `--artifacts` filters execution but does not imply `--force`;
-- archive promotion remains explicit;
-- per-artifact resume is not part of the initial implementation.
-
-## Migration Strategy
-
-Because Narratio is pre-release, perform a hard cutover.
-
-Required changes:
-
-1. Remove the hard-coded `session_recap` analyze behavior.
-2. Require `session_recap` to be declared under `pipeline.scriptorium.artifacts.session_recap` if the operator wants a session recap.
-3. Treat `narratio.artifact.session_recap` as valid only when `session_recap` is a configured artifact key.
-4. Update config examples to show `session_recap` as a normal configured artifact.
-5. Update tests to stop assuming that `session_recap` is a built-in analyze artifact.
-6. Keep archive promotion explicit and path-based.
-
-Example replacement config:
-
-```yaml
-scriptorium:
-  binary: scriptorium
-  config_path: /etc/scriptorium/config.yml
-  timeout: 10m
-  render_debug: false
-  artifacts:
-    session_recap:
-      enabled: true
-      prompt_id: dnd_session.session_recap
-      profile_id: local-gemma-31b
-      output_path: artifacts/session_recap.md
-      timeout: 20m
-      inputs:
-        transcript:
-          source: narratio.transcript.trimmed
-          required: true
-        prior_recap:
-          source: previous_session_artifact
-          artifact: artifacts/session_recap.md
-          required: false
-      vars:
-        artifact_title: Session Recap
-```
-
-## Acceptance Criteria
-
-The feature is complete when:
-
-- operators can define more than one enabled Scriptorium artifact in `pipeline.yml`;
-- Narratio runs selected artifacts in deterministic dependency order;
-- configured artifacts are addressable as `narratio.artifact.<name>`;
-- one configured artifact can consume another configured artifact as an input;
-- artifact-to-artifact input references require explicit `depends_on`;
-- disabled artifacts can satisfy dependencies from existing on-disk outputs;
-- missing required disabled artifacts fail clearly;
-- optional missing inputs are omitted;
-- `--artifacts` can selectively execute valid configured artifact names;
-- `--artifacts` does not imply `--force`;
-- render-debug behavior works for all configured artifacts;
-- generated and reused artifacts are recorded in analyze-stage metadata;
-- `session_recap` is no longer hard-coded and works as a normal configured artifact;
-- archive promotion remains explicit;
-- tests cover config validation, dependency sorting, disabled artifact resolution, resolver behavior, CLI filtering, analyze execution, archive interactions, and metadata.
-
-## Suggested Implementation Order
-
-1. Config model, defaults, and validation.
-2. CLI parsing and propagation of `--artifacts` selection.
-3. Runtime artifact catalog.
-4. Resolver integration for configured artifacts.
-5. Analyze stage generalization.
-6. Stage metadata and manifest output recording.
-7. Archive behavior review.
-8. Documentation and examples.
-
-This order keeps the most static pieces first, then moves into execution behavior once the configuration contract is explicit and well tested.

examples/README.md

@@ -0,0 +1,79 @@
+# Maintained Examples
+
+These files are safe, copyable starting points for Narratio configuration and
+input structure. Replace placeholder identifiers, storage names, integration
+URLs, and paths for the target environment. Field meanings and defaults belong
+in the [configuration reference](../docs/config.md).
+
+## Pipeline Configuration
+
+- [Minimal pipeline](pipeline.minimal.yml): campaign discovery plus the required
+  WhisperX URL.
+- [Production-shaped pipeline](pipeline.production.yml): S3 storage, publish,
+  external tools, and configured Scriptorium artifacts.
+- [Production-base/testing-overlay bundle](production-testing/pipeline.yml):
+  explicit `conf.d` imports, one ordinary artifact per `artifacts/<key>.yml`,
+  one family per `artifact-families/<key>.yml`, and the fixed
+  `profiles/testing.yml` overlay. Production values live in the base. The
+  bundle demonstrates an input-only artifact dependency, two character families
+  sharing the campaign party, and a testing-only disabled artifact. Inspect it
+  offline with:
+
+  ```sh
+  narratio config validate --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml
+  narratio config show --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml --profile testing
+  narratio config sources --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml --profile testing
+  narratio config artifacts --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml --profile testing
+  narratio config diff default testing --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml
+  ```
+
+  These inspection commands load configuration and resolve explicit credential
+  references, but do not load a session or create runtime state. This bundle is
+  intentionally local-storage and credential-reference free so the walkthrough
+  needs no tools or cloud services.
+- [Full annotated pipeline](pipeline.full.annotated.yml): every implemented
+  pipeline section with explanatory comments.
+- [Extraction subset pipeline](pipeline.extraction-subset.yml): a focused
+  Scriptorium artifact consuming only three declared Notarius lanes.
+
+The existing `internal/config` example test loads and validates each pipeline
+with the sample campaign and a compatible local- or S3-audio session.
+
+## Campaign And Session Configuration
+
+- [Sample campaign](campaigns/sample-campaign/campaign.yml), its
+  [session template](campaigns/sample-campaign/session.template.yml), and its
+  adjacent stable inputs provide a complete campaign directory shape.
+- [Local-audio session](session.local-audio.yml) and
+  [S3-audio session](session.s3-audio.yml) are concrete session files.
+- [Session template](session.template.yml) and the campaign-local equivalent
+  demonstrate the narrow placeholder syntax consumed by `session init`; they
+  are templates, not runtime session files.
+
+## Input Fixtures
+
+- [Speakers](speakers.yml), [autocorrect](autocorrect.yml), and
+  [glossary](glossary.yml) show the standalone input shapes.
+- The sample campaign references its local
+  [speakers](campaigns/sample-campaign/speakers.yml),
+  [autocorrect](campaigns/sample-campaign/autocorrect.yml),
+  [glossary](campaigns/sample-campaign/glossary.yml), and canonical
+  [party](campaigns/sample-campaign/party.yml) fixture, plus an optional
+  [spell-catalog overlay](campaigns/sample-campaign/spell_catalog.json) that
+  follows the Notarius v0.7 contract. Narratio derives the players projection
+  from this party source.
+- [Sample speaker audio](audio/sample-speaker.flac) is a text placeholder that
+  reserves the expected filename and directory shape. Replace it with a real
+  FLAC file before running transcription.
+
+The examples contain environment-variable names but no credential values. Set
+`OBJECT_STORAGE_KEY_ID`, `OBJECT_STORAGE_KEY`, `AUDITA_LLM_API_KEY`, and
+`NOTARIUS_LLM_API_KEY` to nonempty synthetic or real values before loading the
+examples that reference them. They use fictional campaign content and reserved
+example domains.
+
+For a deployed bundle, keep credential files out of source control in a
+`secrets/` directory beside the root `pipeline.yml`, one file per referenced
+environment-variable name, or select another directory with `--secrets-dir`.
+Static S3 credentials are optional: omit both S3 credential references to use
+the AWS SDK discovery chain.

examples/campaigns/sample-campaign/autocorrect.yml

@@ -0,0 +1 @@
+[]

examples/campaigns/sample-campaign/campaign.yml

@@ -0,0 +1,8 @@
+campaign_id: sample-campaign
+session_template_file: ./session.template.yml
+inputs:
+  speakers_file: ./speakers.yml
+  autocorrect_file: ./autocorrect.yml
+  glossary_file: ./glossary.yml
+  party_file: ./party.yml
+  spell_catalog_file: ./spell_catalog.json

examples/campaigns/sample-campaign/glossary.yml

@@ -0,0 +1 @@
+[]

examples/campaigns/sample-campaign/party.yml

@@ -0,0 +1,26 @@
+schema_version: narratio.party.v1
+
+characters:
+  arannis:
+    player:
+      name: Rowan Hale
+    character:
+      name: Arannis
+      alias:
+        - Ari
+        - The Grey Owl
+      classes:
+        - name: wizard
+          level: 8
+  brenna:
+    player:
+      name: Rowan Hale
+    character:
+      name: Brenna
+      alias:
+        - Shield of Dawn
+      classes:
+        - name: paladin
+          level: 6
+        - name: warlock
+          level: 2

examples/campaigns/sample-campaign/session.template.yml

@@ -0,0 +1,3 @@
+session_id: "{{ session_id }}"
+inputs:
+  audio_dir: ./audio

examples/campaigns/sample-campaign/speakers.yml

@@ -0,0 +1,5 @@
+match:
+  - speaker: "Example Speaker"
+    match:
+      - "Example_Speaker"
+      - "Example"

examples/campaigns/sample-campaign/spell_catalog.json

@@ -0,0 +1,18 @@
+{
+  "schema_version": "notarius.dnd.spell-catalog-overlay.v1",
+  "catalogs": [
+    {
+      "id": "narratio.sample-campaign",
+      "ruleset": "dnd-5e-2014",
+      "source": {
+        "title": "Narratio sample campaign spell names"
+      },
+      "spells": [
+        {
+          "name": "Aegis of Emberfall",
+          "aliases": ["Emberfall Aegis"]
+        }
+      ]
+    }
+  ]
+}

examples/pipeline.extraction-subset.yml

@@ -0,0 +1,59 @@
+# Purpose-specific extraction example: a Scriptorium session brief consumes
+# only the three Notarius lanes it needs.
+
+campaigns:
+  root: /usr/local/share/narratio/campaigns
+  default_campaign_id: sample-campaign
+
+whisperx:
+  transcribe_url: "https://transcription.example.com/transcribe"
+
+notarius:
+  enabled: true
+  binary: notarius
+  config_path: /usr/local/etc/notarius/config.yml
+  pipeline_id: dnd-session
+  timeout: 3h
+  references:
+    glossary: narratio.input.glossary
+    party: narratio.input.party
+    players: narratio.input.players
+    spell_catalog: narratio.input.spell_catalog
+  outputs:
+    npc_registry:
+      lane_id: npc-registry
+      media_type: application/json
+      schema_id: notarius.dnd.npc_registry
+      schema_version: v1
+      module_key: dnd/npc-registry
+    location_registry:
+      lane_id: location-registry
+      media_type: application/json
+      schema_id: notarius.dnd.location_registry
+      schema_version: v1
+      module_key: dnd/location-registry
+    scene_descriptions:
+      lane_id: scene-descriptions
+      media_type: application/json
+      schema_id: notarius.dnd.scene_descriptions
+      schema_version: v1
+      module_key: dnd/scene-descriptions
+
+scriptorium:
+  binary: scriptorium
+  config_path: /usr/local/etc/scriptorium/config.yml
+  artifacts:
+    session_brief:
+      enabled: true
+      prompt_id: dnd.session_brief
+      output_path: artifacts/session_brief.md
+      inputs:
+        npcs:
+          source: narratio.extraction.npc_registry
+          required: true
+        locations:
+          source: narratio.extraction.location_registry
+          required: true
+        scenes:
+          source: narratio.extraction.scene_descriptions
+          required: true

examples/pipeline.full.annotated.yml

@@ -4,21 +4,17 @@
 workspace:
   # Optional: defaults to /var/lib/narratio.
   root: /var/lib/narratio/workspace
-  # Optional: remove run-scoped workdir after successful archive commit.
-  cleanup_after_archive: false
+  # Optional: remove run-scoped workdir after successful publish commit.
+  cleanup_after_publish: false
 
-# Optional: local secret file loader (directory of ENV_VAR_NAME files).
-# secrets:
-#   env_dir: ./secrets
+# Credential files, when used, belong in a sibling secrets/ directory or in the
+# directory selected with --secrets-dir; they are not pipeline configuration.
 
 storage:
-  # Optional storage backend selector; use "s3" for archive + S3 audio workflows.
+  # Defaults to "local". Use "s3" explicitly for publish + S3 audio workflows.
   backend: s3
-  # Compatibility fields retained in schema.
-  bucket: ""
-  prefix: ""
   s3:
-    # Required when using S3 audio or S3 archive uploads.
+    # Required when using S3 audio or S3 publish uploads.
     bucket: my-dnd-archive
     # Optional; defaults to "dnd".
     root_prefix: dnd
@@ -27,30 +23,47 @@ storage:
     endpoint: ""
     force_path_style: false
     # Optional; defaults shown explicitly.
-    access_key_id_env: OBJECT_STORAGE_KEY_ID
-    secret_access_key_env: OBJECT_STORAGE_KEY
+    access_key_id: OBJECT_STORAGE_KEY_ID
+    secret_access_key: OBJECT_STORAGE_KEY
+
+campaigns:
+  # Optional; defaults to /usr/local/share/narratio/campaigns.
+  root: /usr/local/share/narratio/campaigns
+  # Optional command default when --campaign is omitted.
+  default_campaign_id: sample-campaign
 
 spool:
   # Optional; defaults to /var/spool/narratio.
   root: /var/spool/narratio
-  # Optional cleanup of run-scoped spool audio after successful archive commit.
-  delete_audio_after_archive: false
+  # Optional cleanup of run-scoped spool audio after successful publish commit.
+  delete_audio_after_publish: false
 
-archive:
+publish:
   # Optional booleans; defaults are true.
   enabled: true
   upload_run: true
-  # Optional promotion rules; required files fail archive if missing.
-  promote_artifacts:
-    - from: transcripts/trimmed.json
-      to: transcripts/trimmed.json
+  # Optional publish output rules; sources use Narratio artifact source IDs.
+  outputs:
+    - source: narratio.transcript.final_trimmed
+      dest: transcripts/final.trimmed.json
       required: true
-    - from: artifacts/session_recap.md
-      to: artifacts/session_recap.md
+    - source: narratio.transcript.final_markdown
+      dest: transcripts/final.md
       required: true
-    - from: artifacts/player_handout.md
-      to: artifacts/player_handout.md
+    - source: narratio.transcript.final_trimmed_markdown
+      dest: transcripts/final.trimmed.md
+      required: true
+    - source: narratio.artifact.session_recap
+      dest: artifacts/session_recap.md
+      required: true
+    - source: narratio.artifact.player_handout
+      dest: artifacts/player_handout.md
       required: false
+    # Extraction lanes publish only when named explicitly; the bundle and index
+    # are never implicit publish sources.
+    - source: narratio.extraction.npc_registry
+      dest: artifacts/extraction/npc-registry.json
+      required: true
 
 whisperx:
   # Required.
@@ -80,7 +93,7 @@ audita:
   # Optional overrides; defaults shown explicitly where applicable.
   binary: audita
   timeout: 3h
-  llm_api_key_env: AUDITA_LLM_API_KEY
+  llm_api_key: AUDITA_LLM_API_KEY
   modules: [glossary, homophones, spoken_word, grammar]
   base_url: ""
   model: ""
@@ -96,25 +109,112 @@ audita:
 
 normalize:
   # Optional; defaults shown explicitly.
-  output_path: transcripts/normalized.json
+  output_path: transcripts/final.json
   output_schema: seriatim-intermediate
   report: true
 
 trim:
-  # Keep disabled unless bounds prompt integration is configured.
-  enabled: false
-  output_path: transcripts/trimmed.json
+  # Optional; defaults shown explicitly.
+  enabled: true
+  output_path: transcripts/final.trimmed.json
   bounds:
     prompt_id: dnd.session_bounds
-    profile_id: local-fast
+    profile_id: ""
     transcript_input_name: transcript
-    output_path: reports/session_bounds.json
+    output_path: artifacts/session_bounds.json
     timeout: 10m
     render_debug: false
-    render_output_path: reports/session_bounds.render.json
   seriatim:
     report: false
 
+notarius:
+  # Optional structured extraction after render and before analyze.
+  enabled: true
+  binary: notarius
+  # Optional environment-variable reference. Match this name to api_key_env in
+  # the selected Notarius/PromptKit profile; never put the credential here.
+  llm_api_key: NOTARIUS_LLM_API_KEY
+  config_path: /usr/local/etc/notarius/config.yml
+  pipeline_id: dnd-session
+  timeout: 3h
+  working_directory: /usr/local/etc/notarius
+  # Reuse compatible accepted Notarius checkpoints during executed extraction.
+  # The Notarius config must enable recording and provide persistent cache roots.
+  resume: true
+  # auto uses or creates a source-addressed chunk plan. Forced Narratio
+  # extraction overrides this with refresh and disables checkpoint loading.
+  chunk_cache: auto
+  # External campaign references use prepared Narratio source IDs. Omit an
+  # optional binding when the selected Notarius pipeline does not need it.
+  references:
+    glossary: narratio.input.glossary
+    party: narratio.input.party
+    players: narratio.input.players
+    spell_catalog: narratio.input.spell_catalog
+  # Each key creates source narratio.extraction.<key>. These constraints match
+  # the current Notarius D&D lane contracts; update them with Notarius.
+  outputs:
+    item_registry:
+      lane_id: item-registry
+      media_type: application/json
+      schema_id: notarius.dnd.item_registry
+      schema_version: v1
+      module_key: dnd/item-registry
+    npc_registry:
+      lane_id: npc-registry
+      media_type: application/json
+      schema_id: notarius.dnd.npc_registry
+      schema_version: v1
+      module_key: dnd/npc-registry
+    location_registry:
+      lane_id: location-registry
+      media_type: application/json
+      schema_id: notarius.dnd.location_registry
+      schema_version: v1
+      module_key: dnd/location-registry
+    scene_descriptions:
+      lane_id: scene-descriptions
+      media_type: application/json
+      schema_id: notarius.dnd.scene_descriptions
+      schema_version: v1
+      module_key: dnd/scene-descriptions
+    item_occurrences:
+      lane_id: item-occurrences
+      media_type: application/json
+      schema_id: notarius.dnd.item_occurrences
+      schema_version: v1
+      module_key: dnd/item-occurrences
+    spells:
+      lane_id: spells
+      media_type: application/json
+      schema_id: notarius.dnd.spells
+      schema_version: v1
+      module_key: dnd/spells
+    combat_turns:
+      lane_id: combat-turns
+      media_type: application/json
+      schema_id: notarius.dnd.combat_turns
+      schema_version: v1
+      module_key: dnd/combat-turns
+    npc_occurrences:
+      lane_id: npc-occurrences
+      media_type: application/json
+      schema_id: notarius.dnd.npc_occurrences
+      schema_version: v1
+      module_key: dnd/npc-occurrences
+    location_occurrences:
+      lane_id: location-occurrences
+      media_type: application/json
+      schema_id: notarius.dnd.location_occurrences
+      schema_version: v1
+      module_key: dnd/location-occurrences
+    enemy_events:
+      lane_id: enemy-events
+      media_type: application/json
+      schema_id: notarius.dnd.enemy_events
+      schema_version: v1
+      module_key: dnd/enemy-events
+
 scriptorium:
   binary: scriptorium
   config_path: /usr/local/etc/scriptorium/config.yml
@@ -130,12 +230,19 @@ scriptorium:
       timeout: 10m
       inputs:
         transcript:
-          source: narratio.transcript.trimmed
+          source: narratio.transcript.final_trimmed
           required: true
         previous_recap:
-          source: previous_session_artifact
-          artifact: session_recap
-          path: ""
+          source: narratio.previous_session.artifact.session_recap
+          required: false
+        players:
+          source: narratio.input.players
+          required: true
+        party:
+          source: narratio.input.party
+          required: true
+        glossary:
+          source: narratio.input.glossary
           required: false
       vars:
         session_id: true
@@ -160,23 +267,13 @@ scriptorium:
           source: narratio.artifact.session_recap
           required: true
         transcript:
-          source: narratio.transcript.trimmed
+          source: narratio.transcript.final_trimmed
           required: true
       vars:
         session_id: true
         campaign_name: true
         output_kind: player_handout
 
-analyzer:
-  # Optional adapter settings.
-  binary_path: ""
-  timeout: 2m
-  artifacts:
-    output_dir: ""
-    types: []
-
 notification:
-  # Optional notification settings.
-  backend: ""
-  recipient: ""
-  timeout: 30s
+  # No delivery provider is currently implemented.
+  mode: noop

examples/pipeline.minimal.yml

@@ -1,2 +1,6 @@
+campaigns:
+  root: /usr/local/share/narratio/campaigns
+  default_campaign_id: sample-campaign
+
 whisperx:
   transcribe_url: "https://transcription.example.com/transcribe"

examples/pipeline.production.yml

@@ -1,6 +1,6 @@
 workspace:
   root: /var/lib/narratio/workspace
-  cleanup_after_archive: true
+  cleanup_after_publish: true
 
 storage:
   backend: s3
@@ -8,25 +8,35 @@ storage:
     bucket: my-dnd-archive
     root_prefix: dnd
     region: us-east-1
-    access_key_id_env: OBJECT_STORAGE_KEY_ID
-    secret_access_key_env: OBJECT_STORAGE_KEY
+    access_key_id: OBJECT_STORAGE_KEY_ID
+    secret_access_key: OBJECT_STORAGE_KEY
+
+campaigns:
+  root: /usr/local/share/narratio/campaigns
+  default_campaign_id: sample-campaign
 
 spool:
   root: /var/spool/narratio
-  delete_audio_after_archive: true
+  delete_audio_after_publish: true
 
-archive:
+publish:
   enabled: true
   upload_run: true
-  promote_artifacts:
-    - from: transcripts/trimmed.json
-      to: transcripts/trimmed.json
+  outputs:
+    - source: narratio.transcript.final_trimmed
+      dest: transcripts/final.trimmed.json
       required: true
-    - from: artifacts/session_recap.md
-      to: artifacts/session_recap.md
+    - source: narratio.transcript.final_markdown
+      dest: transcripts/final.md
       required: true
-    - from: artifacts/player_handout.md
-      to: artifacts/player_handout.md
+    - source: narratio.transcript.final_trimmed_markdown
+      dest: transcripts/final.trimmed.md
+      required: true
+    - source: narratio.artifact.session_recap
+      dest: artifacts/session_recap.md
+      required: true
+    - source: narratio.artifact.player_handout
+      dest: artifacts/player_handout.md
       required: false
 
 whisperx:
@@ -47,7 +57,7 @@ seriatim:
 audita:
   binary: audita
   timeout: 3h
-  llm_api_key_env: AUDITA_LLM_API_KEY
+  llm_api_key: AUDITA_LLM_API_KEY
   modules: [glossary, homophones, spoken_word, grammar]
   output_schema: audita-v1
   work_dir_retention: auto
@@ -57,13 +67,10 @@ audita:
   report: true
 
 normalize:
-  output_path: transcripts/normalized.json
+  output_path: transcripts/final.json
   output_schema: seriatim-intermediate
   report: true
 
-trim:
-  enabled: false
-
 scriptorium:
   binary: scriptorium
   config_path: /usr/local/etc/scriptorium/config.yml
@@ -78,11 +85,19 @@ scriptorium:
       timeout: 10m
       inputs:
         transcript:
-          source: narratio.transcript.trimmed
+          source: narratio.transcript.final_trimmed
           required: true
         previous_recap:
-          source: previous_session_artifact
-          artifact: session_recap
+          source: narratio.previous_session.artifact.session_recap
+          required: false
+        players:
+          source: narratio.input.players
+          required: true
+        party:
+          source: narratio.input.party
+          required: true
+        glossary:
+          source: narratio.input.glossary
           required: false
       vars:
         session_id: true
@@ -103,14 +118,11 @@ scriptorium:
           source: narratio.artifact.session_recap
           required: true
         transcript:
-          source: narratio.transcript.trimmed
+          source: narratio.transcript.final_trimmed
           required: true
       vars:
         session_id: true
         output_kind: player_handout
 
-analyzer:
-  timeout: 2m
-
 notification:
-  timeout: 30s
+  mode: noop

examples/production-testing/artifact-families/character_items.yml

@@ -0,0 +1,20 @@
+scriptorium:
+  artifact_families:
+    character_items:
+      enabled: true
+      for_each: party.characters
+      prompt_id: dnd.character_items
+      profile_id: production-placeholder
+      output_path_pattern: artifacts/characters/{character_id}/items.md
+      inputs:
+        character_meta:
+          source: narratio.member_artifact.character_meta
+          required: true
+      member_vars:
+        character_id: character_id
+        character_name: character.name
+        aliases: character.alias_summary
+      publish:
+        enabled: true
+        required: false
+        dest_pattern: artifacts/characters/{character_id}/items.md

examples/production-testing/artifact-families/character_meta.yml

@@ -0,0 +1,13 @@
+scriptorium:
+  artifact_families:
+    character_meta:
+      enabled: true
+      for_each: party.characters
+      prompt_id: dnd.character_meta
+      profile_id: production-placeholder
+      output_path_pattern: artifacts/characters/{character_id}/meta.md
+      member_vars:
+        character_id: character_id
+        character_name: character.name
+        player_name: player.name
+        class_summary: character.class_summary

examples/production-testing/artifacts/player_handout.yml

@@ -0,0 +1,11 @@
+scriptorium:
+  artifacts:
+    player_handout:
+      enabled: true
+      prompt_id: dnd.player_handout
+      profile_id: production-placeholder
+      output_path: artifacts/player-handout.md
+      inputs:
+        recap:
+          source: narratio.artifact.session_recap
+          required: true

examples/production-testing/artifacts/session_recap.yml

@@ -0,0 +1,11 @@
+scriptorium:
+  artifacts:
+    session_recap:
+      enabled: true
+      prompt_id: dnd.session_recap
+      profile_id: production-placeholder
+      output_path: artifacts/session-recap.md
+      inputs:
+        transcript:
+          source: narratio.transcript.final_trimmed
+          required: true

examples/production-testing/conf.d/platform.yml

@@ -0,0 +1,12 @@
+workspace:
+  root: ./workspace
+
+campaigns:
+  root: ../../campaigns
+  default_campaign_id: sample-campaign
+
+cache:
+  root: ./cache
+
+spool:
+  root: ./spool

examples/production-testing/conf.d/publish.yml

@@ -0,0 +1,7 @@
+publish:
+  enabled: true
+  upload_run: false
+  outputs:
+    - source: narratio.transcript.final_markdown
+      dest: transcripts/final.md
+      required: true

examples/production-testing/conf.d/storage.yml

@@ -0,0 +1,2 @@
+storage:
+  backend: local

examples/production-testing/conf.d/transcript.yml

@@ -0,0 +1,18 @@
+whisperx:
+  transcribe_url: https://transcription.example.com/transcribe
+  language: en
+
+seriatim:
+  binary: seriatim
+  output_schema: seriatim-intermediate
+
+audita:
+  binary: audita
+  modules: [glossary, grammar]
+  output_schema: audita-v1
+  model: narratio-production-model-placeholder
+  validation_model: narratio-production-validator-placeholder
+
+normalize:
+  output_path: transcripts/final.json
+  output_schema: seriatim-intermediate

examples/production-testing/pipeline.yml

@@ -0,0 +1,14 @@
+# Copyable production-base/testing-overlay entry point. ConfigKit expands only
+# these explicit path and glob imports; Narratio never scans directories itself.
+configkit:
+  imports:
+    - path: conf.d/platform.yml
+    - path: conf.d/storage.yml
+    - path: conf.d/transcript.yml
+    - path: conf.d/publish.yml
+    - glob: artifacts/*.yml
+    - glob: artifact-families/*.yml
+
+scriptorium:
+  binary: scriptorium
+  config_path: ./scriptorium/config.yml

examples/production-testing/profiles/testing.yml

@@ -0,0 +1,18 @@
+audita:
+  model: narratio-testing-model-placeholder
+  validation_model: narratio-testing-validator-placeholder
+
+scriptorium:
+  artifacts:
+    session_recap:
+      profile_id: testing-placeholder
+    player_handout:
+      profile_id: testing-placeholder
+    testing_notes:
+      enabled: false
+      output_path: artifacts/testing-notes.md
+  artifact_families:
+    character_meta:
+      profile_id: testing-placeholder
+    character_items:
+      profile_id: testing-placeholder

examples/session.local-audio.yml

@@ -1,9 +1,5 @@
 session_id: 2026-05-03
-campaign: sample-campaign
 date: 2026-05-03
 title: Sample Session
 inputs:
   audio_dir: ./audio
-  speakers_file: ./examples/speakers.yml
-  autocorrect_file: ./examples/autocorrect.yml
-  glossary_file: ./examples/glossary.yml

examples/session.s3-audio.yml

@@ -1,10 +1,6 @@
 session_id: 2026-05-03
-campaign: sample-campaign
 date: 2026-05-03
 title: Sample Session
 inputs:
   audio_s3:
     prefix: audio/
-  speakers_file: ./examples/speakers.yml
-  autocorrect_file: ./examples/autocorrect.yml
-  glossary_file: ./examples/glossary.yml

examples/session.template.yml

@@ -1,7 +1,3 @@
 session_id: "{{ session_id }}"
-campaign: sample-campaign
 inputs:
   audio_dir: ./audio
-  speakers_file: ./examples/speakers.yml
-  autocorrect_file: ./examples/autocorrect.yml
-  glossary_file: ./examples/glossary.yml

examples/speakers.yml

@@ -1,5 +1,5 @@
 match:
-  - speaker: "Eric Rakestraw"
+  - speaker: "Example Speaker"
     match:
-      - "Eric_Rakestraw"
-      - "Eric"
+      - "Example_Speaker"
+      - "Example"

go.mod

@@ -1,12 +1,16 @@
 module gitea.maximumdirect.net/eric/narratio
 
-go 1.25.0
+go 1.26.0
 
 require (
+	gitea.maximumdirect.net/eric/ConfigKit v0.3.1
 	github.com/aws/aws-sdk-go-v2/config v1.32.17
 	github.com/aws/aws-sdk-go-v2/credentials v1.19.16
 	github.com/aws/aws-sdk-go-v2/service/s3 v1.101.0
 	github.com/aws/smithy-go v1.25.1
+	github.com/google/go-cmp v0.7.0
+	golang.org/x/sync v0.22.0
+	golang.org/x/sys v0.47.0
 	gopkg.in/yaml.v3 v3.0.1
 )
 
@@ -25,4 +29,5 @@ require (
 	github.com/aws/aws-sdk-go-v2/service/sso v1.30.17 // indirect
 	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.21 // indirect
 	github.com/aws/aws-sdk-go-v2/service/sts v1.42.1 // indirect
+	go.yaml.in/yaml/v4 v4.0.0-rc.6 // indirect
 )

go.sum

@@ -1,3 +1,5 @@
+gitea.maximumdirect.net/eric/ConfigKit v0.3.1 h1:etfTI/dxO3NnS18La0V6IeUh/Iv+3PjVfEyaN8hTuOM=
+gitea.maximumdirect.net/eric/ConfigKit v0.3.1/go.mod h1:tYWpsrbLyu05r8+1MapWp5fN6ZrX9I8hU2xEPedYmYk=
 github.com/aws/aws-sdk-go-v2 v1.41.7 h1:DWpAJt66FmnnaRIOT/8ASTucrvuDPZASqhhLey6tLY8=
 github.com/aws/aws-sdk-go-v2 v1.41.7/go.mod h1:4LAfZOPHNVNQEckOACQx60Y8pSRjIkNZQz1w92xpMJc=
 github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.10 h1:gx1AwW1Iyk9Z9dD9F4akX5gnN3QZwUB20GGKH/I+Rho=
@@ -34,6 +36,14 @@ github.com/aws/aws-sdk-go-v2/service/sts v1.42.1 h1:F/M5Y9I3nwr2IEpshZgh1GeHpOIt
 github.com/aws/aws-sdk-go-v2/service/sts v1.42.1/go.mod h1:mTNxImtovCOEEuD65mKW7DCsL+2gjEH+RPEAexAzAio=
 github.com/aws/smithy-go v1.25.1 h1:J8ERsGSU7d+aCmdQur5Txg6bVoYelvQJgtZehD12GkI=
 github.com/aws/smithy-go v1.25.1/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+go.yaml.in/yaml/v4 v4.0.0-rc.6 h1:1h7H1ohdUh93/FyE4YaDa1Zh64K6VVbjF4K6WUxMtH4=
+go.yaml.in/yaml/v4 v4.0.0-rc.6/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
+golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
+golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
+golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

internal/adapters/analyzer/fake.go

@@ -1,40 +0,0 @@
-package analyzer
-
-import "context"
-
-// NoopRunner is a deterministic no-op analyzer adapter.
-type NoopRunner struct{}
-
-// Run returns the requested output path with placeholder metadata.
-func (n *NoopRunner) Run(ctx context.Context, req AnalyzeRequest) (AnalyzeResult, error) {
-	if err := ctx.Err(); err != nil {
-		return AnalyzeResult{}, err
-	}
-	return AnalyzeResult{ArtifactPath: req.OutputPath, Metadata: map[string]any{"placeholder": true}}, nil
-}
-
-// FakeRunner captures analyze requests and returns deterministic responses.
-type FakeRunner struct {
-	Requests []AnalyzeRequest
-	Err      error
-	Result   AnalyzeResult
-}
-
-// Run records request and returns configured response.
-func (f *FakeRunner) Run(ctx context.Context, req AnalyzeRequest) (AnalyzeResult, error) {
-	if err := ctx.Err(); err != nil {
-		return AnalyzeResult{}, err
-	}
-	f.Requests = append(f.Requests, req)
-	if f.Err != nil {
-		return AnalyzeResult{}, f.Err
-	}
-	res := f.Result
-	if res.ArtifactPath == "" {
-		res.ArtifactPath = req.OutputPath
-	}
-	if res.Metadata == nil {
-		res.Metadata = map[string]any{"fake": true}
-	}
-	return res, nil
-}

internal/adapters/analyzer/fake_test.go

@@ -1,31 +0,0 @@
-package analyzer
-
-import (
-	"context"
-	"errors"
-	"testing"
-)
-
-func TestFakeRunnerCapturesRequestAndReturnsPath(t *testing.T) {
-	fake := &FakeRunner{}
-	req := AnalyzeRequest{ArtifactType: "session-log", OutputPath: "artifacts/session-log.md"}
-
-	res, err := fake.Run(context.Background(), req)
-	if err != nil {
-		t.Fatalf("Run() error = %v", err)
-	}
-	if len(fake.Requests) != 1 || fake.Requests[0].ArtifactType != "session-log" {
-		t.Fatalf("requests = %#v, want captured request", fake.Requests)
-	}
-	if res.ArtifactPath != req.OutputPath {
-		t.Fatalf("artifact path = %q, want %q", res.ArtifactPath, req.OutputPath)
-	}
-}
-
-func TestFakeRunnerError(t *testing.T) {
-	fake := &FakeRunner{Err: errors.New("boom")}
-	_, err := fake.Run(context.Background(), AnalyzeRequest{})
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-}

internal/adapters/analyzer/runner.go

@@ -1,28 +0,0 @@
-// Package analyzer declares the adapter contract for artifact analysis generation.
-package analyzer
-
-import "context"
-
-// TODO: implement analyzer integration once the analyzer contract is finalized.
-
-// Runner is the adapter boundary for analyzer invocations.
-type Runner interface {
-	Run(ctx context.Context, req AnalyzeRequest) (AnalyzeResult, error)
-}
-
-// AnalyzeRequest describes one analyzer artifact generation request.
-type AnalyzeRequest struct {
-	ArtifactType            string
-	ProcessedTranscriptPath string
-	ContextReferences       []string
-	OutputPath              string
-	GeneratedConfigPath     string
-	StdoutLogPath           string
-	StderrLogPath           string
-}
-
-// AnalyzeResult describes analyzer output.
-type AnalyzeResult struct {
-	ArtifactPath string
-	Metadata     map[string]any
-}

internal/adapters/audita/fake.go

@@ -4,10 +4,9 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
-	"os"
 	"path/filepath"
 
-	"gitea.maximumdirect.net/eric/narratio/internal/adapters/subprocess"
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 )
 
 // NoopRunner is a deterministic no-op audita adapter.
@@ -84,17 +83,17 @@ func materializePlaceholders(req PolishRequest) error {
 			"merged_transcript_path": req.MergedTranscriptPath,
 			"output_path":            req.OutputProcessedPath,
 		}
-		if err := subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, 0o644); err != nil {
+		if err := writeGeneratedYAML(req.GeneratedConfigPath, payload); err != nil {
 			return fmt.Errorf("write generated config %q: %w", req.GeneratedConfigPath, err)
 		}
 	}
 	if req.StdoutLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StdoutLogPath, []byte("audita noop/fake stdout placeholder\n"), 0o644); err != nil {
+		if err := fileops.WriteFileAtomic(req.StdoutLogPath, []byte("audita noop/fake stdout placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stdout log %q: %w", req.StdoutLogPath, err)
 		}
 	}
 	if req.StderrLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StderrLogPath, []byte("audita noop/fake stderr placeholder\n"), 0o644); err != nil {
+		if err := fileops.WriteFileAtomic(req.StderrLogPath, []byte("audita noop/fake stderr placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stderr log %q: %w", req.StderrLogPath, err)
 		}
 	}
@@ -117,14 +116,14 @@ func writeJSONIfRequested(path string, payload any) error {
 	if path == "" {
 		return nil
 	}
-	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+	if err := fileops.EnsureWorkspaceDirectory(filepath.Dir(path)); err != nil {
 		return fmt.Errorf("create parent directory %q: %w", filepath.Dir(path), err)
 	}
 	data, err := json.Marshal(payload)
 	if err != nil {
 		return fmt.Errorf("marshal placeholder json for %q: %w", path, err)
 	}
-	if err := subprocess.WriteFileAtomic(path, data, 0o644); err != nil {
+	if err := fileops.WriteFileAtomic(path, data, fileops.WorkspaceFileMode); err != nil {
 		return fmt.Errorf("write placeholder json %q: %w", path, err)
 	}
 	return nil

internal/adapters/audita/fake_test.go

@@ -14,7 +14,7 @@ func TestFakeRunnerCapturesRequestAndReturnsPath(t *testing.T) {
 	dir := t.TempDir()
 	req := PolishRequest{
 		GeneratedConfigPath: filepath.Join(dir, "config", "audita.yml"),
-		OutputProcessedPath: filepath.Join(dir, "transcripts", "processed.json"),
+		OutputProcessedPath: filepath.Join(dir, "transcripts", "polished.json"),
 		StdoutLogPath:       filepath.Join(dir, "logs", "audita.stdout.log"),
 		StderrLogPath:       filepath.Join(dir, "logs", "audita.stderr.log"),
 	}

internal/adapters/audita/generated_config.go

@@ -0,0 +1,19 @@
+package audita
+
+import (
+	"fmt"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
+	"gopkg.in/yaml.v3"
+)
+
+func writeGeneratedYAML(path string, payload any) error {
+	data, err := yaml.Marshal(payload)
+	if err != nil {
+		return fmt.Errorf("marshal generated YAML for %q: %w", path, err)
+	}
+	if err := fileops.WriteFileAtomic(path, data, fileops.WorkspaceFileMode); err != nil {
+		return fmt.Errorf("write generated YAML %q: %w", path, err)
+	}
+	return nil
+}

internal/adapters/audita/runner.go

@@ -6,8 +6,6 @@ import (
 	"time"
 )
 
-// TODO: implement a real Audita subprocess/service adapter.
-
 // Runner is the adapter boundary for audita polish invocations.
 type Runner interface {
 	Run(ctx context.Context, req PolishRequest) (PolishResult, error)
@@ -15,25 +13,15 @@ type Runner interface {
 
 // PolishRequest describes an audita invocation.
 type PolishRequest struct {
-	GeneratedConfigPath      string
-	MergedTranscriptPath     string
-	OutputProcessedPath      string
-	GlossaryPath             string
-	ReportPath               string
-	WorkDir                  string
-	Modules                  []string
-	BaseURL                  string
-	Model                    string
-	TranscriptDescription    string
-	ConfigPath               string
-	OutputSchema             string
-	WorkDirRetention         string
-	TotalLLMConcurrency      *int
-	ProposalLLMConcurrency   *int
-	ValidationModel          string
-	ValidationLLMConcurrency *int
-	StdoutLogPath            string
-	StderrLogPath            string
+	GeneratedConfigPath  string
+	MergedTranscriptPath string
+	OutputProcessedPath  string
+	GlossaryPath         string
+	ReportPath           string
+	WorkDir              string
+	Modules              []string
+	StdoutLogPath        string
+	StderrLogPath        string
 }
 
 // PolishResult describes a polish output.

internal/adapters/audita/subprocess.go

@@ -5,19 +5,26 @@ import (
 	"encoding/json"
 	"fmt"
 	"net/url"
-	"os"
 	"strconv"
 	"strings"
 	"time"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/subprocess"
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 )
 
+// MaxProcessedOutputBytes bounds Audita's processed-transcript JSON result.
+const MaxProcessedOutputBytes int64 = 64 * 1024 * 1024
+
+// MaxReportOutputBytes bounds Audita's optional report JSON result.
+const MaxReportOutputBytes int64 = 16 * 1024 * 1024
+
 // SubprocessRunnerConfig defines deterministic settings for Audita CLI execution.
 type SubprocessRunnerConfig struct {
 	Binary                   string
 	Timeout                  time.Duration
-	LLMAPIKeyEnv             string
+	LLMAPIKey                string
+	LLMAPIKeyReference       string
 	Modules                  []string
 	BaseURL                  string
 	Model                    string
@@ -36,7 +43,8 @@ type SubprocessRunnerConfig struct {
 type SubprocessRunner struct {
 	binary                   string
 	timeout                  time.Duration
-	llmAPIKeyEnv             string
+	llmAPIKey                string
+	llmAPIKeyReference       string
 	modules                  []string
 	baseURL                  string
 	model                    string
@@ -55,7 +63,8 @@ type SubprocessRunner struct {
 func NewSubprocessRunnerFromConfigValues(
 	binary string,
 	timeout string,
-	llmAPIKeyEnv string,
+	llmAPIKey string,
+	llmAPIKeyReference string,
 	modules []string,
 	baseURL string,
 	model string,
@@ -79,7 +88,8 @@ func NewSubprocessRunnerFromConfigValues(
 	return NewSubprocessRunner(SubprocessRunnerConfig{
 		Binary:                   binary,
 		Timeout:                  parsedTimeout,
-		LLMAPIKeyEnv:             llmAPIKeyEnv,
+		LLMAPIKey:                llmAPIKey,
+		LLMAPIKeyReference:       llmAPIKeyReference,
 		Modules:                  modules,
 		BaseURL:                  baseURL,
 		Model:                    model,
@@ -103,6 +113,9 @@ func NewSubprocessRunner(cfg SubprocessRunnerConfig) (*SubprocessRunner, error)
 	if cfg.Timeout <= 0 {
 		return nil, fmt.Errorf("audita timeout must be > 0")
 	}
+	if (cfg.LLMAPIKey == "") != (strings.TrimSpace(cfg.LLMAPIKeyReference) == "") {
+		return nil, fmt.Errorf("audita credential value and reference must be provided together")
+	}
 	for i, module := range cfg.Modules {
 		if strings.TrimSpace(module) == "" {
 			return nil, fmt.Errorf("audita module at index %d is empty", i)
@@ -145,7 +158,8 @@ func NewSubprocessRunner(cfg SubprocessRunnerConfig) (*SubprocessRunner, error)
 	return &SubprocessRunner{
 		binary:                   strings.TrimSpace(cfg.Binary),
 		timeout:                  cfg.Timeout,
-		llmAPIKeyEnv:             strings.TrimSpace(cfg.LLMAPIKeyEnv),
+		llmAPIKey:                cfg.LLMAPIKey,
+		llmAPIKeyReference:       strings.TrimSpace(cfg.LLMAPIKeyReference),
 		modules:                  modules,
 		baseURL:                  strings.TrimSpace(cfg.BaseURL),
 		model:                    strings.TrimSpace(cfg.Model),
@@ -188,16 +202,10 @@ func (r *SubprocessRunner) Run(ctx context.Context, req PolishRequest) (PolishRe
 	}
 	args := r.buildArgs(req, reqModules)
 
-	credentialEnvVar := strings.TrimSpace(r.llmAPIKeyEnv)
-	credentialPresent := false
+	credentialPresent := r.llmAPIKeyReference != ""
 	env := map[string]string{}
-	if credentialEnvVar != "" {
-		credential, ok := os.LookupEnv(credentialEnvVar)
-		if !ok || strings.TrimSpace(credential) == "" {
-			return PolishResult{}, fmt.Errorf("audita: required credential environment variable %s is not set", credentialEnvVar)
-		}
-		env["AUDITA_LLM_API_KEY"] = credential
-		credentialPresent = true
+	if credentialPresent {
+		env["AUDITA_LLM_API_KEY"] = r.llmAPIKey
 	}
 
 	if req.GeneratedConfigPath != "" {
@@ -207,12 +215,13 @@ func (r *SubprocessRunner) Run(ctx context.Context, req PolishRequest) (PolishRe
 	}
 
 	runRes, err := subprocess.Run(ctx, subprocess.RunRequest{
-		Executable:    r.binary,
-		Args:          args,
-		Timeout:       r.timeout,
-		EnvOverrides:  env,
-		StdoutLogPath: req.StdoutLogPath,
-		StderrLogPath: req.StderrLogPath,
+		Executable:      r.binary,
+		Args:            args,
+		Timeout:         r.timeout,
+		EnvOverrides:    env,
+		DiagnosticOwner: "audita",
+		StdoutLogPath:   req.StdoutLogPath,
+		StderrLogPath:   req.StderrLogPath,
 	})
 	if err != nil {
 		wrappedMessage := fmt.Sprintf(
@@ -261,7 +270,7 @@ func (r *SubprocessRunner) Run(ctx context.Context, req PolishRequest) (PolishRe
 			"total_llm_concurrency":      r.totalLLMConcurrency,
 			"proposal_llm_concurrency":   r.proposalLLMConcurrency,
 			"validation_llm_concurrency": r.validationLLMConcurrency,
-			"credential_env_var":         r.llmAPIKeyEnv,
+			"credential_env_var":         r.llmAPIKeyReference,
 			"credential_present":         credentialPresent,
 		},
 	}, nil
@@ -291,7 +300,7 @@ func (r *SubprocessRunner) failureResult(req PolishRequest, modules []string, ru
 			"total_llm_concurrency":      r.totalLLMConcurrency,
 			"proposal_llm_concurrency":   r.proposalLLMConcurrency,
 			"validation_llm_concurrency": r.validationLLMConcurrency,
-			"credential_env_var":         r.llmAPIKeyEnv,
+			"credential_env_var":         r.llmAPIKeyReference,
 			"credential_present":         credentialPresent,
 		},
 	}
@@ -367,16 +376,16 @@ func (r *SubprocessRunner) writeInvocationConfig(req PolishRequest, args []strin
 		"output_path":                req.OutputProcessedPath,
 		"report_path":                req.ReportPath,
 		"work_dir":                   req.WorkDir,
-		"credential_env_var":         r.llmAPIKeyEnv,
+		"credential_env_var":         r.llmAPIKeyReference,
 		"credential_present":         credentialPresent,
 	}
-	return subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, 0o644)
+	return writeGeneratedYAML(req.GeneratedConfigPath, payload)
 }
 
 func validateProcessedOutput(path string) error {
-	data, err := os.ReadFile(path)
+	data, err := readAuditaResult(path, MaxProcessedOutputBytes, "processed transcript")
 	if err != nil {
-		return fmt.Errorf("read file: %w", err)
+		return err
 	}
 
 	var payload map[string]any
@@ -405,9 +414,9 @@ func addSubprocessStreamHint(message string, runErr error) string {
 }
 
 func validateJSONFile(path string) error {
-	data, err := os.ReadFile(path)
+	data, err := readAuditaResult(path, MaxReportOutputBytes, "report")
 	if err != nil {
-		return fmt.Errorf("read file: %w", err)
+		return err
 	}
 	var v any
 	if err := json.Unmarshal(data, &v); err != nil {
@@ -415,3 +424,11 @@ func validateJSONFile(path string) error {
 	}
 	return nil
 }
+
+func readAuditaResult(path string, limit int64, category string) ([]byte, error) {
+	data, err := fileops.ReadFileBounded(path, limit)
+	if err != nil {
+		return nil, fmt.Errorf("audita %s result exceeds or cannot be read within %d-byte limit: %w", category, limit, err)
+	}
+	return data, nil
+}

internal/adapters/audita/subprocess_test.go

@@ -6,16 +6,12 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
-	"runtime"
 	"strings"
 	"testing"
 	"time"
 )
 
 func TestSubprocessRunnerSuccessArgsEnvAndValidation(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("helper wrapper script uses /bin/sh")
-	}
 
 	t.Setenv("GO_WANT_AUDITA_HELPER", "1")
 	t.Setenv("AUDITA_HELPER_MODE", "success")
@@ -31,7 +27,8 @@ func TestSubprocessRunnerSuccessArgsEnvAndValidation(t *testing.T) {
 	runner, err := NewSubprocessRunner(SubprocessRunnerConfig{
 		Binary:                   wrapper,
 		Timeout:                  mustParseAuditaDuration(t, "2s"),
-		LLMAPIKeyEnv:             "OPENAI_KEY_SOURCE",
+		LLMAPIKey:                "super-secret",
+		LLMAPIKeyReference:       "OPENAI_KEY_SOURCE",
 		Modules:                  []string{"glossary", "homophones", "glossary"},
 		BaseURL:                  "https://openrouter.ai/api/v1",
 		Model:                    "openrouter/google/gemma-4-31b-it",
@@ -48,13 +45,14 @@ func TestSubprocessRunnerSuccessArgsEnvAndValidation(t *testing.T) {
 	if err != nil {
 		t.Fatalf("NewSubprocessRunner() error = %v", err)
 	}
+	t.Setenv("OPENAI_KEY_SOURCE", "changed-after-resolution")
 
 	dir := t.TempDir()
 	req := PolishRequest{
 		GeneratedConfigPath:  filepath.Join(dir, "audita.generated.yml"),
-		MergedTranscriptPath: filepath.Join(dir, "merged.json"),
+		MergedTranscriptPath: filepath.Join(dir, "base.json"),
 		GlossaryPath:         filepath.Join(dir, "glossary.yml"),
-		OutputProcessedPath:  filepath.Join(dir, "processed.json"),
+		OutputProcessedPath:  filepath.Join(dir, "polished.json"),
 		ReportPath:           filepath.Join(dir, "audita.report.json"),
 		WorkDir:              filepath.Join(dir, "artifacts", "audita-work"),
 		StdoutLogPath:        filepath.Join(dir, "audita.stdout.log"),
@@ -132,47 +130,31 @@ func TestSubprocessRunnerSuccessArgsEnvAndValidation(t *testing.T) {
 	}
 }
 
-func TestSubprocessRunnerMissingConfiguredCredentialFails(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("helper wrapper script uses /bin/sh")
-	}
-	runner := mustAuditaRunner(t, SubprocessRunnerConfig{
-		Binary:       writeAuditaHelperWrapper(t),
-		Timeout:      mustParseAuditaDuration(t, "2s"),
-		LLMAPIKeyEnv: "MISSING_AUDITA_KEY",
-		Modules:      []string{"glossary"},
-		BaseURL:      "https://openrouter.ai/api/v1",
-		Model:        "openrouter/google/gemma-4-31b-it",
-		Report:       false,
+func TestSubprocessRunnerRejectsIncompleteResolvedCredential(t *testing.T) {
+	_, err := NewSubprocessRunner(SubprocessRunnerConfig{
+		Binary:             writeAuditaHelperWrapper(t),
+		Timeout:            mustParseAuditaDuration(t, "2s"),
+		LLMAPIKeyReference: "MISSING_AUDITA_KEY",
 	})
-	req := auditaReqForTest(t, false)
-
-	_, err := runner.Run(context.Background(), req)
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-	if !strings.Contains(err.Error(), "required credential environment variable MISSING_AUDITA_KEY is not set") {
-		t.Fatalf("error = %q, want missing credential guidance", err.Error())
+	if err == nil || !strings.Contains(err.Error(), "credential value and reference must be provided together") {
+		t.Fatalf("NewSubprocessRunner() error = %v, want credential pair error", err)
 	}
 }
 
 func TestSubprocessRunnerUnconfiguredCredentialEnvOmitsCredential(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("helper wrapper script uses /bin/sh")
-	}
 	t.Setenv("GO_WANT_AUDITA_HELPER", "1")
 	t.Setenv("AUDITA_HELPER_MODE", "success")
 	recordPath := filepath.Join(t.TempDir(), "record.json")
 	t.Setenv("AUDITA_HELPER_RECORD_PATH", recordPath)
 
 	runner := mustAuditaRunner(t, SubprocessRunnerConfig{
-		Binary:       writeAuditaHelperWrapper(t),
-		Timeout:      mustParseAuditaDuration(t, "2s"),
-		LLMAPIKeyEnv: "",
-		Modules:      []string{"glossary"},
-		BaseURL:      "https://openrouter.ai/api/v1",
-		Model:        "openrouter/google/gemma-4-31b-it",
-		Report:       false,
+		Binary:    writeAuditaHelperWrapper(t),
+		Timeout:   mustParseAuditaDuration(t, "2s"),
+		LLMAPIKey: "",
+		Modules:   []string{"glossary"},
+		BaseURL:   "https://openrouter.ai/api/v1",
+		Model:     "openrouter/google/gemma-4-31b-it",
+		Report:    false,
 	})
 	req := auditaReqForTest(t, false)
 
@@ -189,10 +171,7 @@ func TestSubprocessRunnerUnconfiguredCredentialEnvOmitsCredential(t *testing.T)
 	}
 }
 
-func TestSubprocessRunnerInheritsParentEnvironment(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("helper wrapper script uses /bin/sh")
-	}
+func TestSubprocessRunnerOmitsUnspecifiedParentEnvironment(t *testing.T) {
 	t.Setenv("GO_WANT_AUDITA_HELPER", "1")
 	t.Setenv("AUDITA_HELPER_MODE", "success")
 	t.Setenv("AUDITA_INHERITED_MARKER", "inherited-from-parent")
@@ -200,13 +179,13 @@ func TestSubprocessRunnerInheritsParentEnvironment(t *testing.T) {
 	t.Setenv("AUDITA_HELPER_RECORD_PATH", recordPath)
 
 	runner := mustAuditaRunner(t, SubprocessRunnerConfig{
-		Binary:       writeAuditaHelperWrapper(t),
-		Timeout:      mustParseAuditaDuration(t, "2s"),
-		Modules:      []string{"glossary"},
-		BaseURL:      "https://openrouter.ai/api/v1",
-		Model:        "openrouter/google/gemma-4-31b-it",
-		Report:       false,
-		LLMAPIKeyEnv: "",
+		Binary:    writeAuditaHelperWrapper(t),
+		Timeout:   mustParseAuditaDuration(t, "2s"),
+		Modules:   []string{"glossary"},
+		BaseURL:   "https://openrouter.ai/api/v1",
+		Model:     "openrouter/google/gemma-4-31b-it",
+		Report:    false,
+		LLMAPIKey: "",
 	})
 	req := auditaReqForTest(t, false)
 	if _, err := runner.Run(context.Background(), req); err != nil {
@@ -214,27 +193,24 @@ func TestSubprocessRunnerInheritsParentEnvironment(t *testing.T) {
 	}
 
 	rec := readAuditaHelperRecord(t, recordPath)
-	if rec.Env["AUDITA_INHERITED_MARKER"] != "inherited-from-parent" {
-		t.Fatalf("AUDITA_INHERITED_MARKER = %q, want inherited-from-parent", rec.Env["AUDITA_INHERITED_MARKER"])
+	if rec.Env["AUDITA_INHERITED_MARKER"] != "" {
+		t.Fatalf("AUDITA_INHERITED_MARKER = %q, want omitted from the child environment", rec.Env["AUDITA_INHERITED_MARKER"])
 	}
 }
 
 func TestSubprocessRunnerOmitsModulesFlagWhenNotConfigured(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("helper wrapper script uses /bin/sh")
-	}
 	t.Setenv("GO_WANT_AUDITA_HELPER", "1")
 	t.Setenv("AUDITA_HELPER_MODE", "success")
 	recordPath := filepath.Join(t.TempDir(), "record.json")
 	t.Setenv("AUDITA_HELPER_RECORD_PATH", recordPath)
 
 	runner := mustAuditaRunner(t, SubprocessRunnerConfig{
-		Binary:       writeAuditaHelperWrapper(t),
-		Timeout:      mustParseAuditaDuration(t, "2s"),
-		LLMAPIKeyEnv: "",
-		BaseURL:      "https://openrouter.ai/api/v1",
-		Model:        "openrouter/google/gemma-4-31b-it",
-		Report:       false,
+		Binary:    writeAuditaHelperWrapper(t),
+		Timeout:   mustParseAuditaDuration(t, "2s"),
+		LLMAPIKey: "",
+		BaseURL:   "https://openrouter.ai/api/v1",
+		Model:     "openrouter/google/gemma-4-31b-it",
+		Report:    false,
 	})
 	req := auditaReqForTest(t, false)
 	if _, err := runner.Run(context.Background(), req); err != nil {
@@ -249,19 +225,16 @@ func TestSubprocessRunnerOmitsModulesFlagWhenNotConfigured(t *testing.T) {
 }
 
 func TestSubprocessRunnerOmitsBaseURLAndModelFlagsWhenNotConfigured(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("helper wrapper script uses /bin/sh")
-	}
 	t.Setenv("GO_WANT_AUDITA_HELPER", "1")
 	t.Setenv("AUDITA_HELPER_MODE", "success")
 	recordPath := filepath.Join(t.TempDir(), "record.json")
 	t.Setenv("AUDITA_HELPER_RECORD_PATH", recordPath)
 
 	runner := mustAuditaRunner(t, SubprocessRunnerConfig{
-		Binary:       writeAuditaHelperWrapper(t),
-		Timeout:      mustParseAuditaDuration(t, "2s"),
-		LLMAPIKeyEnv: "",
-		Report:       false,
+		Binary:    writeAuditaHelperWrapper(t),
+		Timeout:   mustParseAuditaDuration(t, "2s"),
+		LLMAPIKey: "",
+		Report:    false,
 	})
 	req := auditaReqForTest(t, false)
 	if _, err := runner.Run(context.Background(), req); err != nil {
@@ -279,22 +252,20 @@ func TestSubprocessRunnerOmitsBaseURLAndModelFlagsWhenNotConfigured(t *testing.T
 }
 
 func TestSubprocessRunnerSubprocessFailure(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("helper wrapper script uses /bin/sh")
-	}
 	t.Setenv("GO_WANT_AUDITA_HELPER", "1")
 	t.Setenv("AUDITA_HELPER_MODE", "fail")
 	t.Setenv("OPENAI_KEY_SOURCE", "super-secret")
 	t.Setenv("AUDITA_HELPER_RECORD_PATH", filepath.Join(t.TempDir(), "record.json"))
 
 	runner := mustAuditaRunner(t, SubprocessRunnerConfig{
-		Binary:       writeAuditaHelperWrapper(t),
-		Timeout:      mustParseAuditaDuration(t, "2s"),
-		LLMAPIKeyEnv: "OPENAI_KEY_SOURCE",
-		Modules:      []string{"glossary"},
-		BaseURL:      "https://openrouter.ai/api/v1",
-		Model:        "openrouter/google/gemma-4-31b-it",
-		Report:       true,
+		Binary:             writeAuditaHelperWrapper(t),
+		Timeout:            mustParseAuditaDuration(t, "2s"),
+		LLMAPIKey:          "super-secret",
+		LLMAPIKeyReference: "OPENAI_KEY_SOURCE",
+		Modules:            []string{"glossary"},
+		BaseURL:            "https://openrouter.ai/api/v1",
+		Model:              "openrouter/google/gemma-4-31b-it",
+		Report:             true,
 	})
 	req := auditaReqForTest(t, true)
 	_, err := runner.Run(context.Background(), req)
@@ -310,25 +281,26 @@ func TestSubprocessRunnerSubprocessFailure(t *testing.T) {
 	if !strings.Contains(err.Error(), req.StdoutLogPath) || !strings.Contains(err.Error(), req.StderrLogPath) {
 		t.Fatalf("error = %q, want stdout/stderr log paths", err.Error())
 	}
+	if strings.Contains(err.Error(), "super-secret") {
+		t.Fatalf("failure diagnostic exposed credential value: %q", err.Error())
+	}
 }
 
 func TestSubprocessRunnerSubprocessFailureAddsStderrDescriptorHint(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("helper wrapper script uses /bin/sh")
-	}
 	t.Setenv("GO_WANT_AUDITA_HELPER", "1")
 	t.Setenv("AUDITA_HELPER_MODE", "fail_bad_fd")
 	t.Setenv("OPENAI_KEY_SOURCE", "super-secret")
 	t.Setenv("AUDITA_HELPER_RECORD_PATH", filepath.Join(t.TempDir(), "record.json"))
 
 	runner := mustAuditaRunner(t, SubprocessRunnerConfig{
-		Binary:       writeAuditaHelperWrapper(t),
-		Timeout:      mustParseAuditaDuration(t, "2s"),
-		LLMAPIKeyEnv: "OPENAI_KEY_SOURCE",
-		Modules:      []string{"glossary"},
-		BaseURL:      "https://openrouter.ai/api/v1",
-		Model:        "openrouter/google/gemma-4-31b-it",
-		Report:       true,
+		Binary:             writeAuditaHelperWrapper(t),
+		Timeout:            mustParseAuditaDuration(t, "2s"),
+		LLMAPIKey:          "super-secret",
+		LLMAPIKeyReference: "OPENAI_KEY_SOURCE",
+		Modules:            []string{"glossary"},
+		BaseURL:            "https://openrouter.ai/api/v1",
+		Model:              "openrouter/google/gemma-4-31b-it",
+		Report:             true,
 	})
 	req := auditaReqForTest(t, true)
 	_, err := runner.Run(context.Background(), req)
@@ -341,22 +313,20 @@ func TestSubprocessRunnerSubprocessFailureAddsStderrDescriptorHint(t *testing.T)
 }
 
 func TestSubprocessRunnerMissingOutputFails(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("helper wrapper script uses /bin/sh")
-	}
 	t.Setenv("GO_WANT_AUDITA_HELPER", "1")
 	t.Setenv("AUDITA_HELPER_MODE", "missing_output")
 	t.Setenv("OPENAI_KEY_SOURCE", "super-secret")
 	t.Setenv("AUDITA_HELPER_RECORD_PATH", filepath.Join(t.TempDir(), "record.json"))
 
 	runner := mustAuditaRunner(t, SubprocessRunnerConfig{
-		Binary:       writeAuditaHelperWrapper(t),
-		Timeout:      mustParseAuditaDuration(t, "2s"),
-		LLMAPIKeyEnv: "OPENAI_KEY_SOURCE",
-		Modules:      []string{"glossary"},
-		BaseURL:      "https://openrouter.ai/api/v1",
-		Model:        "openrouter/google/gemma-4-31b-it",
-		Report:       false,
+		Binary:             writeAuditaHelperWrapper(t),
+		Timeout:            mustParseAuditaDuration(t, "2s"),
+		LLMAPIKey:          "super-secret",
+		LLMAPIKeyReference: "OPENAI_KEY_SOURCE",
+		Modules:            []string{"glossary"},
+		BaseURL:            "https://openrouter.ai/api/v1",
+		Model:              "openrouter/google/gemma-4-31b-it",
+		Report:             false,
 	})
 	req := auditaReqForTest(t, false)
 	_, err := runner.Run(context.Background(), req)
@@ -369,22 +339,20 @@ func TestSubprocessRunnerMissingOutputFails(t *testing.T) {
 }
 
 func TestSubprocessRunnerInvalidOutputJSONFails(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("helper wrapper script uses /bin/sh")
-	}
 	t.Setenv("GO_WANT_AUDITA_HELPER", "1")
 	t.Setenv("AUDITA_HELPER_MODE", "invalid_output")
 	t.Setenv("OPENAI_KEY_SOURCE", "super-secret")
 	t.Setenv("AUDITA_HELPER_RECORD_PATH", filepath.Join(t.TempDir(), "record.json"))
 
 	runner := mustAuditaRunner(t, SubprocessRunnerConfig{
-		Binary:       writeAuditaHelperWrapper(t),
-		Timeout:      mustParseAuditaDuration(t, "2s"),
-		LLMAPIKeyEnv: "OPENAI_KEY_SOURCE",
-		Modules:      []string{"glossary"},
-		BaseURL:      "https://openrouter.ai/api/v1",
-		Model:        "openrouter/google/gemma-4-31b-it",
-		Report:       false,
+		Binary:             writeAuditaHelperWrapper(t),
+		Timeout:            mustParseAuditaDuration(t, "2s"),
+		LLMAPIKey:          "super-secret",
+		LLMAPIKeyReference: "OPENAI_KEY_SOURCE",
+		Modules:            []string{"glossary"},
+		BaseURL:            "https://openrouter.ai/api/v1",
+		Model:              "openrouter/google/gemma-4-31b-it",
+		Report:             false,
 	})
 	req := auditaReqForTest(t, false)
 	_, err := runner.Run(context.Background(), req)
@@ -397,22 +365,20 @@ func TestSubprocessRunnerInvalidOutputJSONFails(t *testing.T) {
 }
 
 func TestSubprocessRunnerSegmentsMissingFails(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("helper wrapper script uses /bin/sh")
-	}
 	t.Setenv("GO_WANT_AUDITA_HELPER", "1")
 	t.Setenv("AUDITA_HELPER_MODE", "segments_missing")
 	t.Setenv("OPENAI_KEY_SOURCE", "super-secret")
 	t.Setenv("AUDITA_HELPER_RECORD_PATH", filepath.Join(t.TempDir(), "record.json"))
 
 	runner := mustAuditaRunner(t, SubprocessRunnerConfig{
-		Binary:       writeAuditaHelperWrapper(t),
-		Timeout:      mustParseAuditaDuration(t, "2s"),
-		LLMAPIKeyEnv: "OPENAI_KEY_SOURCE",
-		Modules:      []string{"glossary"},
-		BaseURL:      "https://openrouter.ai/api/v1",
-		Model:        "openrouter/google/gemma-4-31b-it",
-		Report:       false,
+		Binary:             writeAuditaHelperWrapper(t),
+		Timeout:            mustParseAuditaDuration(t, "2s"),
+		LLMAPIKey:          "super-secret",
+		LLMAPIKeyReference: "OPENAI_KEY_SOURCE",
+		Modules:            []string{"glossary"},
+		BaseURL:            "https://openrouter.ai/api/v1",
+		Model:              "openrouter/google/gemma-4-31b-it",
+		Report:             false,
 	})
 	req := auditaReqForTest(t, false)
 	_, err := runner.Run(context.Background(), req)
@@ -425,22 +391,20 @@ func TestSubprocessRunnerSegmentsMissingFails(t *testing.T) {
 }
 
 func TestSubprocessRunnerInvalidReportJSONFails(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("helper wrapper script uses /bin/sh")
-	}
 	t.Setenv("GO_WANT_AUDITA_HELPER", "1")
 	t.Setenv("AUDITA_HELPER_MODE", "invalid_report")
 	t.Setenv("OPENAI_KEY_SOURCE", "super-secret")
 	t.Setenv("AUDITA_HELPER_RECORD_PATH", filepath.Join(t.TempDir(), "record.json"))
 
 	runner := mustAuditaRunner(t, SubprocessRunnerConfig{
-		Binary:       writeAuditaHelperWrapper(t),
-		Timeout:      mustParseAuditaDuration(t, "2s"),
-		LLMAPIKeyEnv: "OPENAI_KEY_SOURCE",
-		Modules:      []string{"glossary"},
-		BaseURL:      "https://openrouter.ai/api/v1",
-		Model:        "openrouter/google/gemma-4-31b-it",
-		Report:       true,
+		Binary:             writeAuditaHelperWrapper(t),
+		Timeout:            mustParseAuditaDuration(t, "2s"),
+		LLMAPIKey:          "super-secret",
+		LLMAPIKeyReference: "OPENAI_KEY_SOURCE",
+		Modules:            []string{"glossary"},
+		BaseURL:            "https://openrouter.ai/api/v1",
+		Model:              "openrouter/google/gemma-4-31b-it",
+		Report:             true,
 	})
 	req := auditaReqForTest(t, true)
 	_, err := runner.Run(context.Background(), req)
@@ -453,21 +417,22 @@ func TestSubprocessRunnerInvalidReportJSONFails(t *testing.T) {
 }
 
 func TestSubprocessRunnerConstructorValidation(t *testing.T) {
-	_, err := NewSubprocessRunnerFromConfigValues("", "3h", "AUDITA_LLM_API_KEY", []string{"glossary"}, "https://openrouter.ai/api/v1", "openrouter/google/gemma-4-31b-it", "", "", "", "", nil, nil, "", nil, true)
+	_, err := NewSubprocessRunnerFromConfigValues("", "3h", "synthetic-secret", "AUDITA_LLM_API_KEY", []string{"glossary"}, "https://openrouter.ai/api/v1", "openrouter/google/gemma-4-31b-it", "", "", "", "", nil, nil, "", nil, true)
 	if err == nil {
 		t.Fatal("expected binary validation error")
 	}
-	_, err = NewSubprocessRunnerFromConfigValues("audita", "bad", "AUDITA_LLM_API_KEY", []string{"glossary"}, "https://openrouter.ai/api/v1", "openrouter/google/gemma-4-31b-it", "", "", "", "", nil, nil, "", nil, true)
+	_, err = NewSubprocessRunnerFromConfigValues("audita", "bad", "synthetic-secret", "AUDITA_LLM_API_KEY", []string{"glossary"}, "https://openrouter.ai/api/v1", "openrouter/google/gemma-4-31b-it", "", "", "", "", nil, nil, "", nil, true)
 	if err == nil {
 		t.Fatal("expected timeout parse error")
 	}
 	_, err = NewSubprocessRunner(SubprocessRunnerConfig{
-		Binary:       "audita",
-		Timeout:      mustParseAuditaDuration(t, "1s"),
-		LLMAPIKeyEnv: "AUDITA_LLM_API_KEY",
-		Modules:      []string{"glossary"},
-		BaseURL:      "://",
-		Model:        "openrouter/google/gemma-4-31b-it",
+		Binary:             "audita",
+		Timeout:            mustParseAuditaDuration(t, "1s"),
+		LLMAPIKey:          "synthetic-secret",
+		LLMAPIKeyReference: "AUDITA_LLM_API_KEY",
+		Modules:            []string{"glossary"},
+		BaseURL:            "://",
+		Model:              "openrouter/google/gemma-4-31b-it",
 	})
 	if err == nil {
 		t.Fatal("expected base url validation error")
@@ -571,7 +536,7 @@ func mustAuditaRunner(t *testing.T, cfg SubprocessRunnerConfig) *SubprocessRunne
 func auditaReqForTest(t *testing.T, withReport bool) PolishRequest {
 	t.Helper()
 	dir := t.TempDir()
-	merged := filepath.Join(dir, "merged.json")
+	merged := filepath.Join(dir, "base.json")
 	glossary := filepath.Join(dir, "glossary.yml")
 	writeAuditaTestFile(t, merged, `{"segments":[]}`)
 	writeAuditaTestFile(t, glossary, "terms: []\n")
@@ -579,7 +544,7 @@ func auditaReqForTest(t *testing.T, withReport bool) PolishRequest {
 		GeneratedConfigPath:  filepath.Join(dir, "audita.generated.yml"),
 		MergedTranscriptPath: merged,
 		GlossaryPath:         glossary,
-		OutputProcessedPath:  filepath.Join(dir, "processed.json"),
+		OutputProcessedPath:  filepath.Join(dir, "polished.json"),
 		WorkDir:              filepath.Join(dir, "artifacts", "audita-work"),
 		StdoutLogPath:        filepath.Join(dir, "audita.stdout.log"),
 		StderrLogPath:        filepath.Join(dir, "audita.stderr.log"),

internal/adapters/notarius/fake.go

@@ -0,0 +1,24 @@
+package notarius
+
+import "context"
+
+// FakeRunner is a configurable in-memory runner for stage tests.
+type FakeRunner struct {
+	Requests []RunRequest
+	Result   RunResult
+	Err      error
+}
+
+// Run records the request and returns the configured result or error.
+func (f *FakeRunner) Run(ctx context.Context, req RunRequest) (RunResult, error) {
+	if err := ctx.Err(); err != nil {
+		return RunResult{}, err
+	}
+	copyRequest := req
+	copyRequest.References = append([]ReferenceBinding(nil), req.References...)
+	f.Requests = append(f.Requests, copyRequest)
+	if f.Err != nil {
+		return RunResult{}, f.Err
+	}
+	return f.Result, nil
+}

internal/adapters/notarius/runner.go

@@ -0,0 +1,166 @@
+// Package notarius declares the adapter contract for Notarius CLI invocations.
+package notarius
+
+import (
+	"context"
+	"time"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+)
+
+const ReceiptSchemaVersion = "notarius.run-result.v2"
+
+// Runner is the adapter boundary for a complete Notarius pipeline invocation.
+type Runner interface {
+	Run(ctx context.Context, req RunRequest) (RunResult, error)
+}
+
+// ReferenceBinding maps one normalized Notarius selector to an absolute
+// external reference path.
+type ReferenceBinding struct {
+	Selector string
+	Path     string
+}
+
+// RunRequest contains the resolved inputs and diagnostic destinations for one invocation.
+type RunRequest struct {
+	Binary string
+	// LLMAPIKey is an optional already-resolved credential reference.
+	LLMAPIKey        *configkit.Secret
+	ConfigPath       string
+	PipelineID       string
+	InputPath        string
+	OutputRoot       string
+	WorkingDirectory string
+	ReceiptPath      string
+	LogPath          string
+	Timeout          time.Duration
+	Resume           bool
+	ChunkCache       string
+	References       []ReferenceBinding
+}
+
+// Receipt is the transport-neutral successful run receipt.
+type Receipt struct {
+	SchemaVersion             string
+	RunID                     string
+	PipelineID                string
+	OutputDirectory           string
+	IndexFile                 string
+	NormalizedOutputCount     int
+	RejectedOutputCount       int
+	WarningGroupCount         int
+	WarningOccurrenceCount    int
+	DiagnosticGroupCount      int
+	DiagnosticOccurrenceCount int
+	DiagnosticsTruncated      bool
+	ValidationStatus          string
+	ValidationSummaries       []ValidationSummary
+	DebugDirectory            string
+}
+
+// ValidationSummary retains the bounded outcome of one Notarius producer result.
+type ValidationSummary struct {
+	Stage                string
+	StepID               string
+	LaneID               string
+	ModuleKey            string
+	ChunkID              string
+	Status               string
+	RejectingValidators  []string
+	ReasonCodes          []string
+	IncompleteValidators []string
+	ProducerAttemptCount int
+	TerminalAction       string
+}
+
+// LaneDescriptor identifies one normalized lane payload discovered through the index.
+type LaneDescriptor struct {
+	LaneID        string
+	File          string
+	Path          string
+	MediaType     string
+	ModuleKey     string
+	SchemaID      string
+	SchemaName    string
+	SchemaVersion string
+}
+
+// PipelineDescriptor identifies a pipeline-wide artifact discovered through the index.
+type PipelineDescriptor struct {
+	ArtifactKind  string
+	File          string
+	Path          string
+	MediaType     string
+	SchemaID      string
+	SchemaName    string
+	SchemaVersion string
+}
+
+// Index describes the validated bundle-management and artifact paths.
+type Index struct {
+	Path            string
+	ManifestFile    string
+	ManifestPath    string
+	RejectedFile    string
+	RejectedPath    string
+	WarningsFile    string
+	WarningsPath    string
+	DiagnosticsFile string
+	DiagnosticsPath string
+	Lanes           []LaneDescriptor
+	ChunkMap        *PipelineDescriptor
+	EvidenceContext *PipelineDescriptor
+}
+
+// RejectionSummary retains structured rejection identity without free-form messages.
+type RejectionSummary struct {
+	Stage         string
+	StepID        string
+	LaneID        string
+	ModuleKey     string
+	ChunkID       string
+	ValidatorName string
+	ReasonCode    string
+}
+
+// WarningSummary retains structured warning identity without free-form messages.
+type WarningSummary struct {
+	Disposition     string
+	Category        string
+	ReasonCode      string
+	Origin          DiagnosticOrigin
+	OccurrenceCount int
+}
+
+// DiagnosticOrigin identifies the framework-owned pipeline location of a finding.
+type DiagnosticOrigin struct {
+	Stage        string
+	StepID       string
+	LaneID       string
+	ModuleKey    string
+	ValidatorKey string
+}
+
+// DiagnosticSummary retains bounded advisory or observation group metadata.
+type DiagnosticSummary struct {
+	Disposition     string
+	Category        string
+	ReasonCode      string
+	Origin          DiagnosticOrigin
+	OccurrenceCount int
+}
+
+// RunResult describes a successfully decoded and validated Notarius bundle.
+type RunResult struct {
+	Receipt     Receipt
+	Index       Index
+	BundleRoot  string
+	ReceiptPath string
+	LogPath     string
+	ExitCode    int
+	Duration    time.Duration
+	Rejections  []RejectionSummary
+	Warnings    []WarningSummary
+	Diagnostics []DiagnosticSummary
+}

internal/adapters/notarius/subprocess.go

@@ -0,0 +1,818 @@
+package notarius
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/adapters/subprocess"
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
+	"gitea.maximumdirect.net/eric/narratio/internal/notariusref"
+	"gitea.maximumdirect.net/eric/narratio/internal/pathsafe"
+)
+
+const (
+	maxReceiptBytes          = 1 << 20
+	maxIndexBytes            = 4 << 20
+	maxSummaryBytes          = 4 << 20
+	canonicalIndexFile       = "index.json"
+	canonicalManifestFile    = "manifest.json"
+	canonicalRejectedFile    = "rejected.json"
+	canonicalWarningsFile    = "warnings.json"
+	canonicalDiagnosticsFile = "diagnostics.json"
+	warningsSchemaVersion    = "notarius.warnings.v2"
+	diagnosticsSchemaVersion = "notarius.diagnostics.v1"
+	maxWarningGroups         = 128
+	maxDiagnosticGroups      = 256
+	maxFindingSamples        = 3
+)
+
+type subprocessRun func(context.Context, subprocess.RunRequest) (subprocess.RunResult, error)
+
+// SubprocessRunner invokes Notarius through its public CLI.
+type SubprocessRunner struct {
+	run subprocessRun
+}
+
+// NewSubprocessRunner constructs a production Notarius subprocess runner.
+func NewSubprocessRunner() *SubprocessRunner {
+	return &SubprocessRunner{run: subprocess.Run}
+}
+
+// Run executes a complete Notarius pipeline and discovers its published bundle.
+func (r *SubprocessRunner) Run(ctx context.Context, req RunRequest) (RunResult, error) {
+	if r == nil || r.run == nil {
+		return RunResult{}, fmt.Errorf("notarius subprocess runner is nil")
+	}
+	references, err := validateRunRequest(req)
+	if err != nil {
+		return RunResult{}, err
+	}
+	var envOverrides map[string]string
+	var sensitiveEnvNames []string
+	if req.LLMAPIKey != nil {
+		if !req.LLMAPIKey.IsResolved() {
+			return RunResult{}, fmt.Errorf("notarius LLM API credential must be resolved and nonempty")
+		}
+		name := req.LLMAPIKey.EnvName()
+		value := req.LLMAPIKey.Value()
+		if value == "" {
+			return RunResult{}, fmt.Errorf("notarius LLM API credential must be resolved and nonempty")
+		}
+		envOverrides = map[string]string{name: value}
+		sensitiveEnvNames = []string{name}
+	}
+
+	args := []string{
+		"run", req.PipelineID,
+		"--config", req.ConfigPath,
+		"--input", req.InputPath,
+		"--output-dir", req.OutputRoot,
+	}
+	if req.Resume {
+		args = append(args, "--resume")
+	}
+	if req.ChunkCache != "" {
+		args = append(args, "--chunk_cache", req.ChunkCache)
+	}
+	for _, reference := range references {
+		args = append(args, "--reference", reference.Selector+"="+reference.Path)
+	}
+	args = append(args, "--json")
+	processResult, err := r.run(ctx, subprocess.RunRequest{
+		Executable:        req.Binary,
+		Args:              args,
+		WorkingDir:        req.WorkingDirectory,
+		Timeout:           req.Timeout,
+		DiagnosticOwner:   "notarius",
+		StdoutLogPath:     req.ReceiptPath,
+		StderrLogPath:     req.LogPath,
+		EnvOverrides:      envOverrides,
+		SensitiveEnvNames: sensitiveEnvNames,
+	})
+	baseResult := RunResult{
+		ReceiptPath: req.ReceiptPath,
+		LogPath:     req.LogPath,
+		ExitCode:    processResult.ExitCode,
+		Duration:    processResult.Duration,
+	}
+	if err != nil {
+		return baseResult, fmt.Errorf("run notarius pipeline %q: %w", req.PipelineID, err)
+	}
+
+	receipt, err := loadReceipt(req.ReceiptPath, req.PipelineID)
+	if err != nil {
+		return baseResult, err
+	}
+	bundleRoot, err := validateBundleRoot(req.OutputRoot, receipt.OutputDirectory)
+	if err != nil {
+		return baseResult, err
+	}
+	indexPath, err := resolveRegularFile(bundleRoot, receipt.IndexFile)
+	if err != nil {
+		return baseResult, fmt.Errorf("resolve receipt index file: %w", err)
+	}
+	index, err := loadIndex(bundleRoot, indexPath)
+	if err != nil {
+		return baseResult, err
+	}
+	rejections, err := loadRejections(index.RejectedPath)
+	if err != nil {
+		return baseResult, err
+	}
+	warnings, err := loadWarnings(index.WarningsPath)
+	if err != nil {
+		return baseResult, err
+	}
+	diagnostics, diagnosticOccurrences, diagnosticsTruncated, err := loadDiagnostics(index.DiagnosticsPath)
+	if err != nil {
+		return baseResult, err
+	}
+	if receipt.NormalizedOutputCount != len(index.Lanes) || receipt.RejectedOutputCount != len(rejections) ||
+		receipt.WarningGroupCount != len(warnings) || receipt.DiagnosticGroupCount != len(diagnostics) {
+		return baseResult, fmt.Errorf("notarius receipt counts do not match published bundle")
+	}
+	warningOccurrences, err := sumWarningOccurrences(warnings)
+	if err != nil {
+		return baseResult, err
+	}
+	if receipt.WarningOccurrenceCount != warningOccurrences ||
+		receipt.DiagnosticOccurrenceCount != diagnosticOccurrences ||
+		receipt.DiagnosticsTruncated != diagnosticsTruncated {
+		return baseResult, fmt.Errorf("notarius receipt occurrence counts do not match published bundle")
+	}
+
+	baseResult.Receipt = receipt
+	baseResult.Index = index
+	baseResult.BundleRoot = bundleRoot
+	baseResult.Rejections = rejections
+	baseResult.Warnings = warnings
+	baseResult.Diagnostics = diagnostics
+	return baseResult, nil
+}
+
+func validateRunRequest(req RunRequest) ([]ReferenceBinding, error) {
+	if strings.TrimSpace(req.Binary) == "" {
+		return nil, fmt.Errorf("notarius binary is required")
+	}
+	if strings.TrimSpace(req.PipelineID) == "" {
+		return nil, fmt.Errorf("notarius pipeline id is required")
+	}
+	if req.Timeout <= 0 {
+		return nil, fmt.Errorf("notarius timeout must be positive")
+	}
+	if !validChunkCacheMode(req.ChunkCache) {
+		return nil, fmt.Errorf("notarius chunk cache mode must be empty, auto, bypass, or refresh")
+	}
+	for label, path := range map[string]string{
+		"config":            req.ConfigPath,
+		"input":             req.InputPath,
+		"output root":       req.OutputRoot,
+		"working directory": req.WorkingDirectory,
+		"receipt":           req.ReceiptPath,
+		"log":               req.LogPath,
+	} {
+		if strings.TrimSpace(path) == "" {
+			return nil, fmt.Errorf("notarius %s path is required", label)
+		}
+		if !filepath.IsAbs(path) {
+			return nil, fmt.Errorf("notarius %s path must be absolute", label)
+		}
+	}
+	if filepath.Clean(req.ReceiptPath) == filepath.Clean(req.LogPath) {
+		return nil, fmt.Errorf("notarius receipt and log paths must be different")
+	}
+	references := make([]ReferenceBinding, 0, len(req.References))
+	selectors := make(map[string]struct{}, len(req.References))
+	for index, binding := range req.References {
+		selector, err := notariusref.NormalizeSelector(binding.Selector)
+		if err != nil {
+			return nil, fmt.Errorf("notarius reference %d selector: %w", index, err)
+		}
+		if _, duplicate := selectors[selector]; duplicate {
+			return nil, fmt.Errorf("notarius reference selector %q is duplicated", selector)
+		}
+		selectors[selector] = struct{}{}
+		if strings.TrimSpace(binding.Path) == "" {
+			return nil, fmt.Errorf("notarius reference %q path is required", selector)
+		}
+		if !filepath.IsAbs(binding.Path) {
+			return nil, fmt.Errorf("notarius reference %q path must be absolute", selector)
+		}
+		references = append(references, ReferenceBinding{Selector: selector, Path: binding.Path})
+	}
+	if err := requireRegularFile(req.ConfigPath); err != nil {
+		return nil, fmt.Errorf("validate notarius config path: %w", err)
+	}
+	if err := requireRegularFile(req.InputPath); err != nil {
+		return nil, fmt.Errorf("validate notarius input path: %w", err)
+	}
+	if err := requireDirectory(req.OutputRoot); err != nil {
+		return nil, fmt.Errorf("validate notarius output root: %w", err)
+	}
+	if err := requireDirectory(req.WorkingDirectory); err != nil {
+		return nil, fmt.Errorf("validate notarius working directory: %w", err)
+	}
+	if err := validateLogDestination(req.ReceiptPath); err != nil {
+		return nil, fmt.Errorf("validate notarius receipt path: %w", err)
+	}
+	if err := validateLogDestination(req.LogPath); err != nil {
+		return nil, fmt.Errorf("validate notarius log path: %w", err)
+	}
+	return references, nil
+}
+
+func validChunkCacheMode(mode string) bool {
+	switch mode {
+	case "", "auto", "bypass", "refresh":
+		return true
+	default:
+		return false
+	}
+}
+
+type receiptDocument struct {
+	SchemaVersion             string                      `json:"schema_version"`
+	RunID                     string                      `json:"run_id"`
+	PipelineID                string                      `json:"pipeline_id"`
+	OutputDirectory           string                      `json:"output_directory"`
+	IndexFile                 string                      `json:"index_file"`
+	NormalizedOutputCount     *int                        `json:"normalized_output_count"`
+	RejectedOutputCount       *int                        `json:"rejected_output_count"`
+	WarningGroupCount         *int                        `json:"warning_group_count"`
+	WarningOccurrenceCount    *int                        `json:"warning_occurrence_count"`
+	DiagnosticGroupCount      *int                        `json:"diagnostic_group_count"`
+	DiagnosticOccurrenceCount *int                        `json:"diagnostic_occurrence_count"`
+	DiagnosticsTruncated      *bool                       `json:"diagnostics_truncated"`
+	ValidationStatus          string                      `json:"validation_status"`
+	ValidationSummaries       []validationSummaryDocument `json:"validation_summaries"`
+	DebugDirectory            string                      `json:"debug_directory"`
+}
+
+type validationSummaryDocument struct {
+	Stage                string   `json:"stage"`
+	StepID               string   `json:"step_id"`
+	LaneID               string   `json:"lane_id"`
+	ModuleKey            string   `json:"module_key"`
+	ChunkID              string   `json:"chunk_id"`
+	Status               string   `json:"status"`
+	RejectingValidators  []string `json:"rejecting_validators"`
+	ReasonCodes          []string `json:"reason_codes"`
+	IncompleteValidators []string `json:"incomplete_validators"`
+	ProducerAttemptCount *int     `json:"producer_attempt_count"`
+	TerminalAction       string   `json:"terminal_action"`
+}
+
+func validValidationStatus(value string) bool {
+	switch value {
+	case "approved", "rejected", "incomplete":
+		return true
+	default:
+		return false
+	}
+}
+
+func validateValidationSummaries(documents []validationSummaryDocument) ([]ValidationSummary, error) {
+	summaries := make([]ValidationSummary, 0, len(documents))
+	for _, document := range documents {
+		if document.Status != "complete" && document.Status != "rejected" && document.Status != "incomplete" {
+			return nil, fmt.Errorf("notarius validation summary status %q is invalid", document.Status)
+		}
+		if document.ProducerAttemptCount == nil || *document.ProducerAttemptCount < 0 || !validTerminalAction(document.TerminalAction) {
+			return nil, fmt.Errorf("notarius validation summary is missing required fields")
+		}
+		summaries = append(summaries, ValidationSummary{
+			Stage: document.Stage, StepID: document.StepID, LaneID: document.LaneID,
+			ModuleKey: document.ModuleKey, ChunkID: document.ChunkID, Status: document.Status,
+			RejectingValidators:  append([]string(nil), document.RejectingValidators...),
+			ReasonCodes:          append([]string(nil), document.ReasonCodes...),
+			IncompleteValidators: append([]string(nil), document.IncompleteValidators...),
+			ProducerAttemptCount: *document.ProducerAttemptCount, TerminalAction: document.TerminalAction,
+		})
+	}
+	return summaries, nil
+}
+
+func validTerminalAction(value string) bool {
+	switch value {
+	case "accepted", "reject_output", "warn_continue", "fail_run":
+		return true
+	default:
+		return false
+	}
+}
+
+func loadReceipt(path, pipelineID string) (Receipt, error) {
+	var document receiptDocument
+	if err := decodeBoundedJSON(path, maxReceiptBytes, &document); err != nil {
+		return Receipt{}, fmt.Errorf("decode notarius receipt: %w", err)
+	}
+	if document.SchemaVersion != ReceiptSchemaVersion {
+		return Receipt{}, fmt.Errorf("unsupported notarius receipt schema version %q", document.SchemaVersion)
+	}
+	if strings.TrimSpace(document.RunID) == "" || strings.TrimSpace(document.PipelineID) == "" ||
+		strings.TrimSpace(document.OutputDirectory) == "" || strings.TrimSpace(document.ValidationStatus) == "" ||
+		document.NormalizedOutputCount == nil ||
+		document.RejectedOutputCount == nil || document.WarningGroupCount == nil ||
+		document.WarningOccurrenceCount == nil || document.DiagnosticGroupCount == nil ||
+		document.DiagnosticOccurrenceCount == nil || document.DiagnosticsTruncated == nil {
+		return Receipt{}, fmt.Errorf("notarius receipt is missing required fields")
+	}
+	if document.IndexFile != canonicalIndexFile {
+		return Receipt{}, fmt.Errorf("notarius receipt index_file %q is incompatible; want %q", document.IndexFile, canonicalIndexFile)
+	}
+	if document.PipelineID != pipelineID {
+		return Receipt{}, fmt.Errorf("notarius receipt pipeline id %q does not match requested pipeline %q", document.PipelineID, pipelineID)
+	}
+	if *document.NormalizedOutputCount < 0 || *document.RejectedOutputCount < 0 ||
+		*document.WarningGroupCount < 0 || *document.WarningOccurrenceCount < 0 ||
+		*document.DiagnosticGroupCount < 0 || *document.DiagnosticOccurrenceCount < 0 {
+		return Receipt{}, fmt.Errorf("notarius receipt counts must be non-negative")
+	}
+	if !validValidationStatus(document.ValidationStatus) {
+		return Receipt{}, fmt.Errorf("notarius receipt validation_status %q is invalid", document.ValidationStatus)
+	}
+	validationSummaries, err := validateValidationSummaries(document.ValidationSummaries)
+	if err != nil {
+		return Receipt{}, err
+	}
+	if !filepath.IsAbs(document.OutputDirectory) {
+		return Receipt{}, fmt.Errorf("notarius receipt output directory must be absolute")
+	}
+	if document.DebugDirectory != "" && !filepath.IsAbs(document.DebugDirectory) {
+		return Receipt{}, fmt.Errorf("notarius receipt debug directory must be absolute when present")
+	}
+	return Receipt{
+		SchemaVersion:             document.SchemaVersion,
+		RunID:                     document.RunID,
+		PipelineID:                document.PipelineID,
+		OutputDirectory:           filepath.Clean(document.OutputDirectory),
+		IndexFile:                 document.IndexFile,
+		NormalizedOutputCount:     *document.NormalizedOutputCount,
+		RejectedOutputCount:       *document.RejectedOutputCount,
+		WarningGroupCount:         *document.WarningGroupCount,
+		WarningOccurrenceCount:    *document.WarningOccurrenceCount,
+		DiagnosticGroupCount:      *document.DiagnosticGroupCount,
+		DiagnosticOccurrenceCount: *document.DiagnosticOccurrenceCount,
+		DiagnosticsTruncated:      *document.DiagnosticsTruncated,
+		ValidationStatus:          document.ValidationStatus,
+		ValidationSummaries:       validationSummaries,
+		DebugDirectory:            document.DebugDirectory,
+	}, nil
+}
+
+type indexDocument struct {
+	ManifestFile    string            `json:"manifest_file"`
+	OutputFiles     *[]laneDocument   `json:"output_files"`
+	RejectedFile    string            `json:"rejected_file"`
+	WarningsFile    string            `json:"warnings_file"`
+	DiagnosticsFile string            `json:"diagnostics_file"`
+	ChunkMap        *pipelineDocument `json:"chunk_map"`
+	EvidenceContext *pipelineDocument `json:"evidence_context"`
+}
+
+type laneDocument struct {
+	LaneID        string `json:"lane_id"`
+	File          string `json:"file"`
+	MediaType     string `json:"media_type"`
+	ModuleKey     string `json:"module_key"`
+	SchemaID      string `json:"schema_id"`
+	SchemaName    string `json:"schema_name"`
+	SchemaVersion string `json:"schema_version"`
+}
+
+type pipelineDocument struct {
+	ArtifactKind  string `json:"artifact_kind"`
+	File          string `json:"file"`
+	MediaType     string `json:"media_type"`
+	SchemaID      string `json:"schema_id"`
+	SchemaName    string `json:"schema_name"`
+	SchemaVersion string `json:"schema_version"`
+}
+
+func loadIndex(bundleRoot, indexPath string) (Index, error) {
+	var document indexDocument
+	if err := decodeBoundedJSON(indexPath, maxIndexBytes, &document); err != nil {
+		return Index{}, fmt.Errorf("decode notarius index: %w", err)
+	}
+	for _, field := range []struct {
+		name string
+		got  string
+		want string
+	}{
+		{name: "manifest_file", got: document.ManifestFile, want: canonicalManifestFile},
+		{name: "rejected_file", got: document.RejectedFile, want: canonicalRejectedFile},
+		{name: "warnings_file", got: document.WarningsFile, want: canonicalWarningsFile},
+		{name: "diagnostics_file", got: document.DiagnosticsFile, want: canonicalDiagnosticsFile},
+	} {
+		if field.got != field.want {
+			return Index{}, fmt.Errorf("notarius index %s %q is incompatible; want %q", field.name, field.got, field.want)
+		}
+	}
+	if document.OutputFiles == nil {
+		return Index{}, fmt.Errorf("notarius index is missing required output_files")
+	}
+
+	index := Index{
+		Path:            indexPath,
+		ManifestFile:    document.ManifestFile,
+		RejectedFile:    document.RejectedFile,
+		WarningsFile:    document.WarningsFile,
+		DiagnosticsFile: document.DiagnosticsFile,
+	}
+	var err error
+	if index.ManifestPath, err = resolveRegularFile(bundleRoot, index.ManifestFile); err != nil {
+		return Index{}, fmt.Errorf("resolve notarius manifest file: %w", err)
+	}
+	if index.RejectedPath, err = resolveRegularFile(bundleRoot, index.RejectedFile); err != nil {
+		return Index{}, fmt.Errorf("resolve notarius rejection file: %w", err)
+	}
+	if index.WarningsPath, err = resolveRegularFile(bundleRoot, index.WarningsFile); err != nil {
+		return Index{}, fmt.Errorf("resolve notarius warning file: %w", err)
+	}
+	if index.DiagnosticsPath, err = resolveRegularFile(bundleRoot, index.DiagnosticsFile); err != nil {
+		return Index{}, fmt.Errorf("resolve notarius diagnostics file: %w", err)
+	}
+
+	seenLanes := make(map[string]struct{}, len(*document.OutputFiles))
+	for _, lane := range *document.OutputFiles {
+		if strings.TrimSpace(lane.LaneID) == "" || strings.TrimSpace(lane.File) == "" {
+			return Index{}, fmt.Errorf("notarius lane descriptors require lane_id and file")
+		}
+		if _, exists := seenLanes[lane.LaneID]; exists {
+			return Index{}, fmt.Errorf("notarius index contains duplicate lane id %q", lane.LaneID)
+		}
+		seenLanes[lane.LaneID] = struct{}{}
+		path, err := resolveRegularFile(bundleRoot, lane.File)
+		if err != nil {
+			return Index{}, fmt.Errorf("resolve notarius lane %q file: %w", lane.LaneID, err)
+		}
+		index.Lanes = append(index.Lanes, LaneDescriptor{
+			LaneID: lane.LaneID, File: lane.File, Path: path, MediaType: lane.MediaType,
+			ModuleKey: lane.ModuleKey, SchemaID: lane.SchemaID, SchemaName: lane.SchemaName,
+			SchemaVersion: lane.SchemaVersion,
+		})
+	}
+	if document.ChunkMap != nil {
+		index.ChunkMap, err = resolvePipelineDescriptor(bundleRoot, "chunk_map", *document.ChunkMap)
+		if err != nil {
+			return Index{}, err
+		}
+	}
+	if document.EvidenceContext != nil {
+		index.EvidenceContext, err = resolvePipelineDescriptor(bundleRoot, "evidence_context", *document.EvidenceContext)
+		if err != nil {
+			return Index{}, err
+		}
+	}
+	return index, nil
+}
+
+func resolvePipelineDescriptor(bundleRoot, label string, document pipelineDocument) (*PipelineDescriptor, error) {
+	if strings.TrimSpace(document.ArtifactKind) == "" || strings.TrimSpace(document.File) == "" ||
+		strings.TrimSpace(document.MediaType) == "" || strings.TrimSpace(document.SchemaID) == "" ||
+		strings.TrimSpace(document.SchemaName) == "" || strings.TrimSpace(document.SchemaVersion) == "" {
+		return nil, fmt.Errorf("notarius %s descriptor is missing required fields", label)
+	}
+	path, err := resolveRegularFile(bundleRoot, document.File)
+	if err != nil {
+		return nil, fmt.Errorf("resolve notarius %s file: %w", label, err)
+	}
+	return &PipelineDescriptor{
+		ArtifactKind: document.ArtifactKind, File: document.File, Path: path,
+		MediaType: document.MediaType, SchemaID: document.SchemaID,
+		SchemaName: document.SchemaName, SchemaVersion: document.SchemaVersion,
+	}, nil
+}
+
+type rejectionDocument struct {
+	Rejected *[]struct {
+		Stage         string `json:"stage"`
+		StepID        string `json:"step_id"`
+		LaneID        string `json:"lane_id"`
+		ModuleKey     string `json:"module_key"`
+		ChunkID       string `json:"chunk_id"`
+		ValidatorName string `json:"validator_name"`
+		ReasonCode    string `json:"reason_code"`
+		Message       string `json:"message"`
+	} `json:"rejected"`
+}
+
+func loadRejections(path string) ([]RejectionSummary, error) {
+	var document rejectionDocument
+	if err := decodeBoundedJSON(path, maxSummaryBytes, &document); err != nil {
+		return nil, fmt.Errorf("decode notarius rejections: %w", err)
+	}
+	if document.Rejected == nil {
+		return nil, fmt.Errorf("notarius rejection document is missing rejected array")
+	}
+	summaries := make([]RejectionSummary, 0, len(*document.Rejected))
+	for _, item := range *document.Rejected {
+		if strings.TrimSpace(item.Stage) == "" || strings.TrimSpace(item.Message) == "" {
+			return nil, fmt.Errorf("notarius rejection entries require stage and message")
+		}
+		summaries = append(summaries, RejectionSummary{
+			Stage: item.Stage, StepID: item.StepID, LaneID: item.LaneID,
+			ModuleKey: item.ModuleKey, ChunkID: item.ChunkID,
+			ValidatorName: item.ValidatorName, ReasonCode: item.ReasonCode,
+		})
+	}
+	return summaries, nil
+}
+
+type findingGroupDocument struct {
+	Disposition     string                   `json:"disposition"`
+	Category        string                   `json:"category"`
+	ReasonCode      string                   `json:"reason_code"`
+	Origin          diagnosticOriginDocument `json:"origin"`
+	OccurrenceCount *int                     `json:"occurrence_count"`
+	Samples         *[]struct {
+		Scope      string `json:"scope"`
+		Message    string `json:"message"`
+		ChunkID    string `json:"chunk_id"`
+		ChunkIndex *int   `json:"chunk_index"`
+	} `json:"samples"`
+	OmittedSampleCount *int `json:"omitted_sample_count"`
+}
+
+type diagnosticOriginDocument struct {
+	Stage        string `json:"stage"`
+	StepID       string `json:"step_id"`
+	LaneID       string `json:"lane_id"`
+	ModuleKey    string `json:"module_key"`
+	ValidatorKey string `json:"validator_key"`
+}
+
+type warningDocument struct {
+	SchemaVersion   string                  `json:"schema_version"`
+	GroupCount      *int                    `json:"group_count"`
+	OccurrenceCount *int                    `json:"occurrence_count"`
+	Groups          *[]findingGroupDocument `json:"groups"`
+}
+
+func loadWarnings(path string) ([]WarningSummary, error) {
+	var document warningDocument
+	if err := decodeBoundedJSON(path, maxSummaryBytes, &document); err != nil {
+		return nil, fmt.Errorf("decode notarius warnings: %w", err)
+	}
+	if document.SchemaVersion != warningsSchemaVersion || document.GroupCount == nil ||
+		document.OccurrenceCount == nil || document.Groups == nil {
+		return nil, fmt.Errorf("notarius warning document is missing or incompatible required fields")
+	}
+	if *document.GroupCount < 0 || *document.GroupCount > maxWarningGroups || *document.OccurrenceCount < 0 ||
+		*document.GroupCount != len(*document.Groups) {
+		return nil, fmt.Errorf("notarius warning document counts are inconsistent")
+	}
+	summaries := make([]WarningSummary, 0, len(*document.Groups))
+	occurrences := 0
+	for _, group := range *document.Groups {
+		if err := validateFindingGroup(group); err != nil {
+			return nil, fmt.Errorf("notarius warning group: %w", err)
+		}
+		if group.Disposition != "warning" {
+			return nil, fmt.Errorf("notarius warning group disposition %q is invalid", group.Disposition)
+		}
+		if *group.OccurrenceCount > int(^uint(0)>>1)-occurrences {
+			return nil, fmt.Errorf("notarius warning occurrence count overflows")
+		}
+		occurrences += *group.OccurrenceCount
+		summaries = append(summaries, WarningSummary{
+			Disposition: group.Disposition, Category: group.Category, ReasonCode: group.ReasonCode,
+			Origin: diagnosticOrigin(group.Origin), OccurrenceCount: *group.OccurrenceCount,
+		})
+	}
+	if occurrences != *document.OccurrenceCount {
+		return nil, fmt.Errorf("notarius warning document occurrence count is inconsistent")
+	}
+	return summaries, nil
+}
+
+type diagnosticDocument struct {
+	SchemaVersion                string                  `json:"schema_version"`
+	GroupCount                   *int                    `json:"group_count"`
+	OccurrenceCount              *int                    `json:"occurrence_count"`
+	Truncated                    *bool                   `json:"truncated"`
+	UnrepresentedOccurrenceCount *int                    `json:"unrepresented_occurrence_count"`
+	Groups                       *[]findingGroupDocument `json:"groups"`
+}
+
+func loadDiagnostics(path string) ([]DiagnosticSummary, int, bool, error) {
+	var document diagnosticDocument
+	if err := decodeBoundedJSON(path, maxSummaryBytes, &document); err != nil {
+		return nil, 0, false, fmt.Errorf("decode notarius diagnostics: %w", err)
+	}
+	if document.SchemaVersion != diagnosticsSchemaVersion || document.GroupCount == nil ||
+		document.OccurrenceCount == nil || document.Truncated == nil ||
+		document.UnrepresentedOccurrenceCount == nil || document.Groups == nil {
+		return nil, 0, false, fmt.Errorf("notarius diagnostics document is missing or incompatible required fields")
+	}
+	if *document.GroupCount < 0 || *document.GroupCount > maxDiagnosticGroups || *document.OccurrenceCount < 0 ||
+		*document.UnrepresentedOccurrenceCount < 0 || *document.GroupCount != len(*document.Groups) {
+		return nil, 0, false, fmt.Errorf("notarius diagnostics document counts are inconsistent")
+	}
+	if !*document.Truncated && *document.UnrepresentedOccurrenceCount != 0 {
+		return nil, 0, false, fmt.Errorf("notarius diagnostics document has unrepresented occurrences without truncation")
+	}
+	summaries := make([]DiagnosticSummary, 0, len(*document.Groups))
+	representedOccurrences := 0
+	for _, group := range *document.Groups {
+		if err := validateFindingGroup(group); err != nil {
+			return nil, 0, false, fmt.Errorf("notarius diagnostic group: %w", err)
+		}
+		if group.Disposition != "advisory" && group.Disposition != "observation" {
+			return nil, 0, false, fmt.Errorf("notarius diagnostic group disposition %q is invalid", group.Disposition)
+		}
+		if *group.OccurrenceCount > int(^uint(0)>>1)-representedOccurrences {
+			return nil, 0, false, fmt.Errorf("notarius diagnostic occurrence count overflows")
+		}
+		representedOccurrences += *group.OccurrenceCount
+		summaries = append(summaries, DiagnosticSummary{
+			Disposition: group.Disposition, Category: group.Category, ReasonCode: group.ReasonCode,
+			Origin: diagnosticOrigin(group.Origin), OccurrenceCount: *group.OccurrenceCount,
+		})
+	}
+	if *document.UnrepresentedOccurrenceCount > int(^uint(0)>>1)-representedOccurrences ||
+		representedOccurrences+*document.UnrepresentedOccurrenceCount != *document.OccurrenceCount {
+		return nil, 0, false, fmt.Errorf("notarius diagnostics document occurrence count is inconsistent")
+	}
+	return summaries, *document.OccurrenceCount, *document.Truncated, nil
+}
+
+func validateFindingGroup(group findingGroupDocument) error {
+	if strings.TrimSpace(group.Disposition) == "" || strings.TrimSpace(group.Category) == "" ||
+		strings.TrimSpace(group.ReasonCode) == "" || !validDiagnosticOriginStage(group.Origin.Stage) ||
+		!validDiagnosticCategory(group.Disposition, group.Category) ||
+		group.OccurrenceCount == nil || *group.OccurrenceCount <= 0 || group.Samples == nil ||
+		group.OmittedSampleCount == nil || *group.OmittedSampleCount < 0 {
+		return fmt.Errorf("missing required fields")
+	}
+	if len(*group.Samples) == 0 || len(*group.Samples) > maxFindingSamples ||
+		*group.OmittedSampleCount != *group.OccurrenceCount-len(*group.Samples) {
+		return fmt.Errorf("sample counts are inconsistent")
+	}
+	for _, sample := range *group.Samples {
+		if strings.TrimSpace(sample.Scope) == "" || strings.TrimSpace(sample.Message) == "" ||
+			(sample.ChunkIndex != nil && *sample.ChunkIndex < 0) {
+			return fmt.Errorf("samples require scope and message")
+		}
+	}
+	return nil
+}
+
+func validDiagnosticCategory(disposition, category string) bool {
+	switch disposition {
+	case "warning":
+		return category == "configuration" || category == "degradation" ||
+			category == "validation_incomplete" || category == "fallback"
+	case "advisory":
+		return category == "data_quality"
+	case "observation":
+		return category == "normalization"
+	default:
+		return false
+	}
+}
+
+func validDiagnosticOriginStage(stage string) bool {
+	switch stage {
+	case "references", "chunk", "extract", "merge", "normalize":
+		return true
+	default:
+		return false
+	}
+}
+
+func diagnosticOrigin(document diagnosticOriginDocument) DiagnosticOrigin {
+	return DiagnosticOrigin{
+		Stage: document.Stage, StepID: document.StepID, LaneID: document.LaneID,
+		ModuleKey: document.ModuleKey, ValidatorKey: document.ValidatorKey,
+	}
+}
+
+func sumWarningOccurrences(values []WarningSummary) (int, error) {
+	total := 0
+	for _, value := range values {
+		if value.OccurrenceCount > int(^uint(0)>>1)-total {
+			return 0, fmt.Errorf("notarius warning occurrence count overflows")
+		}
+		total += value.OccurrenceCount
+	}
+	return total, nil
+}
+
+func decodeBoundedJSON(path string, limit int64, destination any) error {
+	data, err := fileops.ReadFileBounded(path, limit)
+	if err != nil {
+		return fmt.Errorf("notarius JSON result exceeds or cannot be read within %d-byte limit: %w", limit, err)
+	}
+	if err := json.Unmarshal(data, destination); err != nil {
+		return err
+	}
+	return nil
+}
+
+func validateBundleRoot(outputRoot, bundleRoot string) (string, error) {
+	root := filepath.Clean(outputRoot)
+	bundle := filepath.Clean(bundleRoot)
+	relative, err := filepath.Rel(root, bundle)
+	if err != nil {
+		return "", fmt.Errorf("compare notarius output paths: %w", err)
+	}
+	if relative == "." || relative == ".." || strings.HasPrefix(relative, ".."+string(filepath.Separator)) {
+		return "", fmt.Errorf("notarius output directory %q is not beneath output root %q", bundleRoot, outputRoot)
+	}
+	if err := requireDirectoryTree(root, relative); err != nil {
+		return "", fmt.Errorf("validate notarius output directory: %w", err)
+	}
+	return bundle, nil
+}
+
+func resolveRegularFile(root, logicalPath string) (string, error) {
+	resolved, err := pathsafe.JoinSlashRelativeUnderRoot(root, logicalPath)
+	if err != nil {
+		return "", err
+	}
+	relative, err := filepath.Rel(root, resolved)
+	if err != nil {
+		return "", err
+	}
+	if err := requireRegularFileTree(root, relative); err != nil {
+		return "", err
+	}
+	return resolved, nil
+}
+
+func requireDirectoryTree(root, relative string) error {
+	if err := requireDirectory(root); err != nil {
+		return err
+	}
+	current := root
+	for _, component := range strings.Split(relative, string(filepath.Separator)) {
+		current = filepath.Join(current, component)
+		if err := requireDirectory(current); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func requireRegularFileTree(root, relative string) error {
+	components := strings.Split(relative, string(filepath.Separator))
+	if len(components) == 0 {
+		return fmt.Errorf("regular file path is required")
+	}
+	if err := requireDirectory(root); err != nil {
+		return err
+	}
+	current := root
+	for _, component := range components[:len(components)-1] {
+		current = filepath.Join(current, component)
+		if err := requireDirectory(current); err != nil {
+			return err
+		}
+	}
+	return requireRegularFile(filepath.Join(current, components[len(components)-1]))
+}
+
+func requireDirectory(path string) error {
+	info, err := os.Lstat(path)
+	if err != nil {
+		return err
+	}
+	if info.Mode()&os.ModeSymlink != 0 || !info.IsDir() {
+		return fmt.Errorf("path %q must be a directory without symlinks", path)
+	}
+	return nil
+}
+
+func requireRegularFile(path string) error {
+	info, err := os.Lstat(path)
+	if err != nil {
+		return err
+	}
+	if info.Mode()&os.ModeSymlink != 0 || !info.Mode().IsRegular() {
+		return fmt.Errorf("path %q must be a regular file without symlinks", path)
+	}
+	return nil
+}
+
+func validateLogDestination(path string) error {
+	if err := requireDirectory(filepath.Dir(path)); err != nil {
+		return err
+	}
+	info, err := os.Lstat(path)
+	if errors.Is(err, os.ErrNotExist) {
+		return nil
+	}
+	if err != nil {
+		return err
+	}
+	if info.Mode()&os.ModeSymlink != 0 || !info.Mode().IsRegular() {
+		return fmt.Errorf("path %q must be absent or a regular file without symlinks", path)
+	}
+	return nil
+}

internal/adapters/notarius/subprocess_test.go

@@ -0,0 +1,923 @@
+package notarius
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+	sharedsubprocess "gitea.maximumdirect.net/eric/narratio/internal/adapters/subprocess"
+)
+
+func TestSubprocessRunnerBuildsExactInvocationAndDiscoversBundle(t *testing.T) {
+	req := validRunRequest(t)
+	var captured sharedsubprocess.RunRequest
+	runner := &SubprocessRunner{run: func(_ context.Context, processReq sharedsubprocess.RunRequest) (sharedsubprocess.RunResult, error) {
+		captured = processReq
+		writeValidBundleAndReceipt(t, req, true)
+		return sharedsubprocess.RunResult{ExitCode: 0, Duration: 2 * time.Second}, nil
+	}}
+
+	result, err := runner.Run(context.Background(), req)
+	if err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	wantArgs := []string{
+		"run", "dnd-session", "--config", req.ConfigPath, "--input", req.InputPath,
+		"--output-dir", req.OutputRoot, "--json",
+	}
+	if !reflect.DeepEqual(captured.Args, wantArgs) {
+		t.Fatalf("subprocess args = %#v, want %#v", captured.Args, wantArgs)
+	}
+	if captured.Executable != req.Binary || captured.WorkingDir != req.WorkingDirectory || captured.Timeout != req.Timeout {
+		t.Fatalf("subprocess request = %#v", captured)
+	}
+	if captured.StdoutLogPath != req.ReceiptPath || captured.StderrLogPath != req.LogPath {
+		t.Fatalf("stream paths = stdout %q stderr %q", captured.StdoutLogPath, captured.StderrLogPath)
+	}
+	if captured.EnvOverrides != nil {
+		t.Fatalf("environment overrides = %#v, want inherited environment only", captured.EnvOverrides)
+	}
+	for _, arg := range captured.Args {
+		if arg == "--session-id" {
+			t.Fatal("subprocess args unexpectedly contain --session-id")
+		}
+	}
+
+	if result.Receipt.SchemaVersion != ReceiptSchemaVersion || result.Receipt.RunID != "notarius-run-1" {
+		t.Fatalf("receipt = %#v", result.Receipt)
+	}
+	if len(result.Receipt.ValidationSummaries) != 1 || result.Receipt.ValidationSummaries[0].LaneID != "npc-registry" ||
+		result.Receipt.ValidationSummaries[0].Status != "complete" {
+		t.Fatalf("validation summaries = %#v", result.Receipt.ValidationSummaries)
+	}
+	if len(result.Index.Lanes) != 1 || result.Index.Lanes[0].LaneID != "npc-registry" {
+		t.Fatalf("lanes = %#v", result.Index.Lanes)
+	}
+	if result.Index.ChunkMap == nil || result.Index.ChunkMap.ArtifactKind != "chunk_map" {
+		t.Fatalf("chunk map = %#v", result.Index.ChunkMap)
+	}
+	if result.Index.EvidenceContext == nil || result.Index.EvidenceContext.ArtifactKind != "evidence_context" {
+		t.Fatalf("evidence context = %#v", result.Index.EvidenceContext)
+	}
+	if len(result.Rejections) != 1 || result.Rejections[0].LaneID != "spells" || result.Rejections[0].ReasonCode != "invalid_spell" {
+		t.Fatalf("rejections = %#v", result.Rejections)
+	}
+	if len(result.Warnings) != 1 || result.Warnings[0].Category != "degradation" || result.Warnings[0].ReasonCode != "normalized_name" {
+		t.Fatalf("warnings = %#v", result.Warnings)
+	}
+	if len(result.Diagnostics) != 1 || result.Diagnostics[0].Category != "data_quality" || result.Diagnostics[0].ReasonCode != "low_confidence" {
+		t.Fatalf("diagnostics = %#v", result.Diagnostics)
+	}
+}
+
+func TestSubprocessRunnerMapsCacheControlsToArguments(t *testing.T) {
+	tests := []struct {
+		name       string
+		resume     bool
+		chunkCache string
+		want       []string
+	}{
+		{name: "resume", resume: true, want: []string{"--resume"}},
+		{name: "auto", chunkCache: "auto", want: []string{"--chunk_cache", "auto"}},
+		{name: "bypass", chunkCache: "bypass", want: []string{"--chunk_cache", "bypass"}},
+		{name: "refresh", chunkCache: "refresh", want: []string{"--chunk_cache", "refresh"}},
+		{name: "resume and mode", resume: true, chunkCache: "auto", want: []string{"--resume", "--chunk_cache", "auto"}},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			req := validRunRequest(t)
+			req.Resume = test.resume
+			req.ChunkCache = test.chunkCache
+			var captured sharedsubprocess.RunRequest
+			runner := &SubprocessRunner{run: func(_ context.Context, processReq sharedsubprocess.RunRequest) (sharedsubprocess.RunResult, error) {
+				captured = processReq
+				writeValidBundleAndReceipt(t, req, false)
+				return sharedsubprocess.RunResult{ExitCode: 0}, nil
+			}}
+
+			if _, err := runner.Run(context.Background(), req); err != nil {
+				t.Fatalf("Run() error = %v", err)
+			}
+			want := []string{
+				"run", req.PipelineID, "--config", req.ConfigPath, "--input", req.InputPath,
+				"--output-dir", req.OutputRoot,
+			}
+			want = append(want, test.want...)
+			want = append(want, "--json")
+			if !reflect.DeepEqual(captured.Args, want) {
+				t.Fatalf("subprocess args = %#v, want %#v", captured.Args, want)
+			}
+		})
+	}
+}
+
+func TestSubprocessRunnerRejectsInvalidChunkCacheBeforeLaunch(t *testing.T) {
+	for _, mode := range []string{"AUTO", "invalid", " auto "} {
+		t.Run(mode, func(t *testing.T) {
+			req := validRunRequest(t)
+			req.ChunkCache = mode
+			started := false
+			runner := &SubprocessRunner{run: func(context.Context, sharedsubprocess.RunRequest) (sharedsubprocess.RunResult, error) {
+				started = true
+				return sharedsubprocess.RunResult{}, nil
+			}}
+			_, err := runner.Run(context.Background(), req)
+			if err == nil || !strings.Contains(err.Error(), "chunk cache mode") {
+				t.Fatalf("Run() error = %v, want chunk cache validation failure", err)
+			}
+			if started {
+				t.Fatal("subprocess started with invalid chunk cache mode")
+			}
+		})
+	}
+}
+
+func TestSubprocessRunnerForwardsLoadedCredentialWithoutRereadingEnvironment(t *testing.T) {
+	const envName = "NARRATIO_NOTARIUS_CUSTOM_LLM_KEY"
+	const loadedValue = "loaded-notarius-credential"
+	credential := loadTestCredential(t, envName, loadedValue)
+	t.Setenv(envName, "changed-parent-credential")
+
+	req := validRunRequest(t)
+	req.LLMAPIKey = credential
+	var captured sharedsubprocess.RunRequest
+	runner := &SubprocessRunner{run: func(_ context.Context, processReq sharedsubprocess.RunRequest) (sharedsubprocess.RunResult, error) {
+		captured = processReq
+		writeValidBundleAndReceipt(t, req, false)
+		return sharedsubprocess.RunResult{ExitCode: 0}, nil
+	}}
+	if _, err := runner.Run(context.Background(), req); err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	if len(captured.EnvOverrides) != 1 || captured.EnvOverrides[envName] != loadedValue {
+		t.Fatal("subprocess did not receive exactly the loaded credential override")
+	}
+	if !reflect.DeepEqual(captured.SensitiveEnvNames, []string{envName}) {
+		t.Fatalf("sensitive environment names = %#v, want configured reference name", captured.SensitiveEnvNames)
+	}
+	wantArgs := []string{
+		"run", req.PipelineID, "--config", req.ConfigPath, "--input", req.InputPath,
+		"--output-dir", req.OutputRoot, "--json",
+	}
+	if !reflect.DeepEqual(captured.Args, wantArgs) {
+		t.Fatalf("subprocess args = %#v, want %#v", captured.Args, wantArgs)
+	}
+}
+
+func TestSubprocessRunnerRejectsInvalidProgrammaticCredentialBeforeLaunch(t *testing.T) {
+	for _, test := range []struct {
+		name      string
+		reference configkit.Secret
+	}{
+		{name: "unresolved", reference: configkit.SecretEnv("NARRATIO_NOTARIUS_UNRESOLVED_KEY")},
+		{name: "empty", reference: configkit.SecretEnv("")},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			req := validRunRequest(t)
+			req.LLMAPIKey = &test.reference
+			started := false
+			runner := &SubprocessRunner{run: func(context.Context, sharedsubprocess.RunRequest) (sharedsubprocess.RunResult, error) {
+				started = true
+				return sharedsubprocess.RunResult{}, nil
+			}}
+			_, err := runner.Run(context.Background(), req)
+			if err == nil || !strings.Contains(err.Error(), "resolved and nonempty") {
+				t.Fatalf("Run() error = %v, want credential validation failure", err)
+			}
+			if started {
+				t.Fatal("subprocess started with an invalid credential")
+			}
+		})
+	}
+}
+
+func TestSubprocessRunnerBuildsOrderedReferenceArguments(t *testing.T) {
+	req := validRunRequest(t)
+	referenceRoot := t.TempDir()
+	req.References = []ReferenceBinding{
+		{Selector: " party ", Path: filepath.Join(referenceRoot, "party context=primary.json")},
+		{Selector: " npc-registry . extract . glossary ", Path: filepath.Join(referenceRoot, "glossary.json")},
+	}
+	originalReferences := append([]ReferenceBinding(nil), req.References...)
+	var captured sharedsubprocess.RunRequest
+	runner := &SubprocessRunner{run: func(_ context.Context, processReq sharedsubprocess.RunRequest) (sharedsubprocess.RunResult, error) {
+		captured = processReq
+		writeValidBundleAndReceipt(t, req, false)
+		return sharedsubprocess.RunResult{ExitCode: 0}, nil
+	}}
+
+	if _, err := runner.Run(context.Background(), req); err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	wantArgs := []string{
+		"run", req.PipelineID,
+		"--config", req.ConfigPath,
+		"--input", req.InputPath,
+		"--output-dir", req.OutputRoot,
+		"--reference", "party=" + req.References[0].Path,
+		"--reference", "npc-registry.extract.glossary=" + req.References[1].Path,
+		"--json",
+	}
+	if !reflect.DeepEqual(captured.Args, wantArgs) {
+		t.Fatalf("subprocess args = %#v, want %#v", captured.Args, wantArgs)
+	}
+	if !reflect.DeepEqual(req.References, originalReferences) {
+		t.Fatalf("Run() mutated caller references = %#v, want %#v", req.References, originalReferences)
+	}
+}
+
+func TestSubprocessRunnerRejectsInvalidReferencesBeforeLaunch(t *testing.T) {
+	tests := []struct {
+		name       string
+		references func(string) []ReferenceBinding
+		wantErr    string
+	}{
+		{
+			name: "invalid selector",
+			references: func(root string) []ReferenceBinding {
+				return []ReferenceBinding{{Selector: "lane.prepare.party", Path: filepath.Join(root, "party.json")}}
+			},
+			wantErr: "selector",
+		},
+		{
+			name: "duplicate normalized selector",
+			references: func(root string) []ReferenceBinding {
+				return []ReferenceBinding{
+					{Selector: "lane.party", Path: filepath.Join(root, "party.json")},
+					{Selector: " lane . party ", Path: filepath.Join(root, "party-2.json")},
+				}
+			},
+			wantErr: "duplicated",
+		},
+		{
+			name: "empty path",
+			references: func(string) []ReferenceBinding {
+				return []ReferenceBinding{{Selector: "party", Path: "  "}}
+			},
+			wantErr: "path is required",
+		},
+		{
+			name: "relative path",
+			references: func(string) []ReferenceBinding {
+				return []ReferenceBinding{{Selector: "party", Path: "references/party.json"}}
+			},
+			wantErr: "path must be absolute",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			req := validRunRequest(t)
+			req.References = tt.references(t.TempDir())
+			started := false
+			runner := &SubprocessRunner{run: func(context.Context, sharedsubprocess.RunRequest) (sharedsubprocess.RunResult, error) {
+				started = true
+				return sharedsubprocess.RunResult{}, nil
+			}}
+
+			_, err := runner.Run(context.Background(), req)
+			if err == nil || !strings.Contains(err.Error(), tt.wantErr) {
+				t.Fatalf("Run() error = %v, want containing %q", err, tt.wantErr)
+			}
+			if started {
+				t.Fatal("subprocess started after request validation failure")
+			}
+		})
+	}
+}
+
+func TestSubprocessRunnerUsesMinimalEnvironmentAndSeparatesStreams(t *testing.T) {
+	const envName = "NARRATIO_NOTARIUS_CUSTOM_CAPTURE_KEY"
+	const canary = "notarius-captured-stream-canary"
+	const unrelated = "NARRATIO_NOTARIUS_UNRELATED_PARENT_KEY"
+	req := validRunRequest(t)
+	req.LLMAPIKey = loadTestCredential(t, envName, canary)
+	writeValidBundleAndReceipt(t, req, false)
+	receiptFixture := req.ReceiptPath + ".fixture"
+	data, err := os.ReadFile(req.ReceiptPath)
+	if err != nil {
+		t.Fatalf("ReadFile(receipt) error = %v", err)
+	}
+	var receipt map[string]any
+	if err := json.Unmarshal(data, &receipt); err != nil {
+		t.Fatalf("decode receipt fixture: %v", err)
+	}
+	receipt["credential_echo"] = canary
+	writeJSONFile(t, receiptFixture, receipt)
+	if err := os.Remove(req.ReceiptPath); err != nil {
+		t.Fatalf("Remove(receipt) error = %v", err)
+	}
+
+	captureDir := filepath.Join(filepath.Dir(req.ReceiptPath), "capture")
+	if err := os.Mkdir(captureDir, 0o755); err != nil {
+		t.Fatalf("Mkdir(capture) error = %v", err)
+	}
+	script := writeShellScript(t, `#!/bin/sh
+pwd > "$NOTARIUS_CAPTURE_DIR/working-directory"
+printf '%s' "$NOTARIUS_INHERITED_VALUE" > "$NOTARIUS_CAPTURE_DIR/environment"
+if [ "$`+envName+`" != '`+canary+`' ]; then
+  printf 'selected credential mismatch\n' >&2
+  exit 8
+fi
+if [ -n "$`+unrelated+`" ]; then
+  printf 'unrelated credential inherited\n' >&2
+  exit 9
+fi
+printf '%s\n' "$`+envName+`" >&2
+cat "$NOTARIUS_RECEIPT_FIXTURE"
+`)
+	req.Binary = script
+	t.Setenv("NOTARIUS_CAPTURE_DIR", captureDir)
+	t.Setenv("NOTARIUS_INHERITED_VALUE", "inherited-value")
+	t.Setenv("NOTARIUS_RECEIPT_FIXTURE", receiptFixture)
+	t.Setenv(unrelated, "unrelated-parent-credential")
+
+	if _, err := NewSubprocessRunner().Run(context.Background(), req); err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	assertTextFile(t, filepath.Join(captureDir, "working-directory"), req.WorkingDirectory+"\n")
+	assertTextFile(t, filepath.Join(captureDir, "environment"), "")
+	assertRedactedCredentialFile(t, req.LogPath, canary)
+	receiptBytes, err := os.ReadFile(req.ReceiptPath)
+	if err != nil {
+		t.Fatalf("ReadFile(receipt) error = %v", err)
+	}
+	assertRedactedCredentialBytes(t, receiptBytes, canary)
+}
+
+func TestSubprocessRunnerRedactsCredentialOnProcessFailure(t *testing.T) {
+	const envName = "NARRATIO_NOTARIUS_CUSTOM_FAILURE_KEY"
+	const canary = "notarius-failure-stream-canary"
+	req := validRunRequest(t)
+	req.LLMAPIKey = loadTestCredential(t, envName, canary)
+	req.Binary = writeShellScript(t, `#!/bin/sh
+printf '%s\n' "$`+envName+`"
+printf '%s\n' "$`+envName+`" >&2
+exit 7
+`)
+	_, err := NewSubprocessRunner().Run(context.Background(), req)
+	if err == nil {
+		t.Fatal("Run() error = nil, want process failure")
+	}
+	if strings.Contains(err.Error(), canary) || !strings.Contains(err.Error(), "<redacted>") {
+		t.Fatal("process failure did not return redacted diagnostics")
+	}
+	assertRedactedCredentialFile(t, req.ReceiptPath, canary)
+	assertRedactedCredentialFile(t, req.LogPath, canary)
+}
+
+func TestSubprocessRunnerReturnsProcessFailuresWithoutParsingStdout(t *testing.T) {
+	tests := []struct {
+		name       string
+		scriptBody string
+		timeout    time.Duration
+		cancel     bool
+		want       string
+	}{
+		{name: "nonzero", scriptBody: "printf '{malformed receipt'; printf 'failed\\n' >&2; exit 7\n", timeout: time.Second, want: "exit code 7"},
+		{name: "timeout", scriptBody: "sleep 5\n", timeout: 20 * time.Millisecond, want: "timed out"},
+		{name: "cancellation", scriptBody: "sleep 5\n", timeout: time.Second, cancel: true, want: "canceled"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			req := validRunRequest(t)
+			req.Binary = writeShellScript(t, "#!/bin/sh\n"+test.scriptBody)
+			req.Timeout = test.timeout
+			ctx := context.Background()
+			if test.cancel {
+				cancelCtx, cancel := context.WithCancel(ctx)
+				ctx = cancelCtx
+				time.AfterFunc(20*time.Millisecond, cancel)
+			}
+			_, err := NewSubprocessRunner().Run(ctx, req)
+			if err == nil || !strings.Contains(err.Error(), test.want) {
+				t.Fatalf("Run() error = %v, want fragment %q", err, test.want)
+			}
+			if strings.Contains(err.Error(), "decode notarius receipt") {
+				t.Fatalf("Run() parsed stdout after process failure: %v", err)
+			}
+		})
+	}
+}
+
+func TestSubprocessRunnerReturnsSharedSubprocessErrorWithoutReadingReceipt(t *testing.T) {
+	req := validRunRequest(t)
+	if err := os.WriteFile(req.ReceiptPath, []byte("not json"), 0o644); err != nil {
+		t.Fatalf("WriteFile(receipt) error = %v", err)
+	}
+	wantErr := errors.New("process failed")
+	runner := &SubprocessRunner{run: func(context.Context, sharedsubprocess.RunRequest) (sharedsubprocess.RunResult, error) {
+		return sharedsubprocess.RunResult{ExitCode: 9}, wantErr
+	}}
+	_, err := runner.Run(context.Background(), req)
+	if !errors.Is(err, wantErr) {
+		t.Fatalf("Run() error = %v, want wrapped process error", err)
+	}
+	if strings.Contains(err.Error(), "decode") {
+		t.Fatalf("Run() parsed receipt after failure: %v", err)
+	}
+}
+
+func TestLoadReceiptValidation(t *testing.T) {
+	root := t.TempDir()
+	valid := map[string]any{
+		"schema_version": ReceiptSchemaVersion, "run_id": "run-1", "pipeline_id": "pipeline-1",
+		"output_directory": filepath.Join(root, "outputs", "run-1"), "index_file": "index.json",
+		"normalized_output_count": 1, "rejected_output_count": 0,
+		"warning_group_count": 0, "warning_occurrence_count": 0,
+		"diagnostic_group_count": 0, "diagnostic_occurrence_count": 0,
+		"diagnostics_truncated": false, "validation_status": "approved", "future_field": true,
+	}
+	tests := []struct {
+		name      string
+		mutate    func(map[string]any)
+		raw       []byte
+		wantOK    bool
+		wantError string
+	}{
+		{name: "unknown fields tolerated", wantOK: true},
+		{name: "malformed", raw: []byte("{")},
+		{name: "unsupported version", mutate: func(v map[string]any) { v["schema_version"] = "notarius.run-result.v1" }},
+		{name: "missing field", mutate: func(v map[string]any) { delete(v, "run_id") }},
+		{name: "pipeline mismatch", mutate: func(v map[string]any) { v["pipeline_id"] = "other" }},
+		{name: "relative output", mutate: func(v map[string]any) { v["output_directory"] = "run-1" }},
+		{name: "negative count", mutate: func(v map[string]any) { v["warning_group_count"] = -1 }},
+		{name: "invalid validation status", mutate: func(v map[string]any) { v["validation_status"] = "valid" }},
+		{
+			name: "nested index", mutate: func(v map[string]any) { v["index_file"] = "nested/index.json" },
+			wantError: `index_file "nested/index.json"`,
+		},
+		{
+			name: "cleanable index", mutate: func(v map[string]any) { v["index_file"] = "./index.json" },
+			wantError: `index_file "./index.json"`,
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			path := filepath.Join(root, strings.ReplaceAll(test.name, " ", "-")+".json")
+			values := cloneMap(valid)
+			if test.mutate != nil {
+				test.mutate(values)
+			}
+			if test.raw != nil {
+				if err := os.WriteFile(path, test.raw, 0o644); err != nil {
+					t.Fatalf("WriteFile() error = %v", err)
+				}
+			} else {
+				writeJSONFile(t, path, values)
+			}
+			_, err := loadReceipt(path, "pipeline-1")
+			if test.wantOK && err != nil {
+				t.Fatalf("loadReceipt() error = %v", err)
+			}
+			if !test.wantOK && err == nil {
+				t.Fatal("loadReceipt() error = nil, want validation failure")
+			}
+			if test.wantError != "" && !strings.Contains(err.Error(), test.wantError) {
+				t.Fatalf("loadReceipt() error = %v, want fragment %q", err, test.wantError)
+			}
+		})
+	}
+
+	oversized := filepath.Join(root, "oversized.json")
+	if err := os.WriteFile(oversized, []byte(strings.Repeat("x", maxReceiptBytes+1)), 0o644); err != nil {
+		t.Fatalf("WriteFile(oversized) error = %v", err)
+	}
+	if _, err := loadReceipt(oversized, "pipeline-1"); err == nil || !strings.Contains(err.Error(), "exceeds") {
+		t.Fatalf("loadReceipt(oversized) error = %v", err)
+	}
+}
+
+func TestValidateBundleRootRejectsEscapesAndSymlinks(t *testing.T) {
+	root := t.TempDir()
+	outputRoot := filepath.Join(root, "output")
+	if err := os.Mkdir(outputRoot, 0o755); err != nil {
+		t.Fatalf("Mkdir(output root) error = %v", err)
+	}
+	validBundle := filepath.Join(outputRoot, "run-1")
+	if err := os.Mkdir(validBundle, 0o755); err != nil {
+		t.Fatalf("Mkdir(bundle) error = %v", err)
+	}
+	if _, err := validateBundleRoot(outputRoot, validBundle); err != nil {
+		t.Fatalf("validateBundleRoot(valid) error = %v", err)
+	}
+
+	outside := filepath.Join(root, "output-other")
+	if err := os.Mkdir(outside, 0o755); err != nil {
+		t.Fatalf("Mkdir(outside) error = %v", err)
+	}
+	for name, candidate := range map[string]string{"equal root": outputRoot, "escape": root, "prefix confusion": outside} {
+		t.Run(name, func(t *testing.T) {
+			if _, err := validateBundleRoot(outputRoot, candidate); err == nil {
+				t.Fatalf("validateBundleRoot(%q) error = nil", candidate)
+			}
+		})
+	}
+	symlink := filepath.Join(outputRoot, "linked")
+	if err := os.Symlink(outside, symlink); err != nil {
+		t.Skipf("Symlink() unavailable: %v", err)
+	}
+	if _, err := validateBundleRoot(outputRoot, symlink); err == nil {
+		t.Fatal("validateBundleRoot(symlink) error = nil")
+	}
+}
+
+func TestLoadIndexRejectsMalformedUnsafeAndUnsupportedDocuments(t *testing.T) {
+	tests := []struct {
+		name       string
+		indexValue any
+		prepare    func(*testing.T, string)
+		wantError  string
+	}{
+		{name: "malformed", indexValue: json.RawMessage(`{"manifest_file":`)},
+		{name: "unsupported output shape", indexValue: map[string]any{"manifest_file": "manifest.json", "output_files": map[string]any{}, "rejected_file": "rejected.json", "warnings_file": "warnings.json"}},
+		{name: "missing management path", indexValue: map[string]any{"output_files": []any{}, "rejected_file": "rejected.json", "warnings_file": "warnings.json"}},
+		{name: "renamed manifest", indexValue: func() any {
+			value := validIndexValue([]any{})
+			value["manifest_file"] = "metadata.json"
+			return value
+		}(), wantError: `manifest_file "metadata.json"`},
+		{name: "cleanable manifest", indexValue: func() any {
+			value := validIndexValue([]any{})
+			value["manifest_file"] = "./manifest.json"
+			return value
+		}(), wantError: `manifest_file "./manifest.json"`},
+		{name: "renamed rejections", indexValue: func() any {
+			value := validIndexValue([]any{})
+			value["rejected_file"] = "rejections.json"
+			return value
+		}(), wantError: `rejected_file "rejections.json"`},
+		{name: "renamed warnings", indexValue: func() any {
+			value := validIndexValue([]any{})
+			value["warnings_file"] = "diagnostics/warnings.json"
+			return value
+		}(), wantError: `warnings_file "diagnostics/warnings.json"`},
+		{name: "duplicate lane", indexValue: validIndexValue([]any{
+			map[string]any{"lane_id": "npc", "file": "lanes/npc.json"},
+			map[string]any{"lane_id": "npc", "file": "lanes/npc.json"},
+		})},
+		{name: "absolute logical path", indexValue: validIndexValue([]any{map[string]any{"lane_id": "npc", "file": "/tmp/npc.json"}})},
+		{name: "lexical traversal", indexValue: validIndexValue([]any{map[string]any{"lane_id": "npc", "file": "../outside.json"}})},
+		{name: "root prefix confusion", indexValue: validIndexValue([]any{map[string]any{"lane_id": "npc", "file": "../bundle-other/npc.json"}})},
+		{name: "file symlink", indexValue: validIndexValue([]any{map[string]any{"lane_id": "npc", "file": "lanes/npc.json"}}), prepare: func(t *testing.T, bundle string) {
+			if err := os.Symlink(filepath.Join(bundle, "manifest.json"), filepath.Join(bundle, "lanes", "npc.json")); err != nil {
+				t.Skipf("Symlink() unavailable: %v", err)
+			}
+		}},
+		{name: "directory symlink", indexValue: validIndexValue([]any{map[string]any{"lane_id": "npc", "file": "linked/npc.json"}}), prepare: func(t *testing.T, bundle string) {
+			if err := os.Symlink(filepath.Join(bundle, "lanes"), filepath.Join(bundle, "linked")); err != nil {
+				t.Skipf("Symlink() unavailable: %v", err)
+			}
+		}},
+		{name: "missing management file", indexValue: validIndexValue([]any{}), prepare: func(t *testing.T, bundle string) {
+			if err := os.Remove(filepath.Join(bundle, "manifest.json")); err != nil {
+				t.Fatalf("Remove(manifest) error = %v", err)
+			}
+		}},
+		{name: "incomplete pipeline descriptor", indexValue: func() any {
+			value := validIndexValue([]any{})
+			value["chunk_map"] = map[string]any{"artifact_kind": "chunk_map", "file": "chunk-map.json"}
+			return value
+		}()},
+		{name: "pipeline descriptor escape", indexValue: func() any {
+			value := validIndexValue([]any{})
+			value["evidence_context"] = map[string]any{
+				"artifact_kind": "evidence_context", "file": "../evidence.json", "media_type": "application/json",
+				"schema_id": "evidence", "schema_name": "Evidence", "schema_version": "v1",
+			}
+			return value
+		}()},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			bundle := createBundleSkeleton(t)
+			indexPath := filepath.Join(bundle, "index.json")
+			if raw, ok := test.indexValue.(json.RawMessage); ok {
+				if err := os.WriteFile(indexPath, raw, 0o644); err != nil {
+					t.Fatalf("WriteFile(index) error = %v", err)
+				}
+			} else {
+				writeJSONFile(t, indexPath, test.indexValue)
+			}
+			if test.prepare != nil {
+				test.prepare(t, bundle)
+			}
+			if _, err := loadIndex(bundle, indexPath); err == nil {
+				t.Fatal("loadIndex() error = nil, want failure")
+			} else if test.wantError != "" && !strings.Contains(err.Error(), test.wantError) {
+				t.Fatalf("loadIndex() error = %v, want fragment %q", err, test.wantError)
+			}
+		})
+	}
+
+	bundle := createBundleSkeleton(t)
+	oversizedIndex := filepath.Join(bundle, "index.json")
+	if err := os.WriteFile(oversizedIndex, []byte(strings.Repeat("x", maxIndexBytes+1)), 0o644); err != nil {
+		t.Fatalf("WriteFile(oversized index) error = %v", err)
+	}
+	if _, err := loadIndex(bundle, oversizedIndex); err == nil || !strings.Contains(err.Error(), "exceeds") {
+		t.Fatalf("loadIndex(oversized) error = %v", err)
+	}
+}
+
+func TestLoadDiagnosticSummariesValidateBoundsAndTolerateUnknownFields(t *testing.T) {
+	root := t.TempDir()
+	rejectedPath := filepath.Join(root, "rejected.json")
+	warningsPath := filepath.Join(root, "warnings.json")
+	diagnosticsPath := filepath.Join(root, "diagnostics.json")
+	writeJSONFile(t, rejectedPath, map[string]any{"rejected": []any{map[string]any{
+		"stage": "validate", "lane_id": "spells", "reason_code": "invalid", "message": "do not retain this", "future": true,
+	}}, "future": true})
+	writeJSONFile(t, warningsPath, findingEnvelope(warningsSchemaVersion, []any{findingGroup("warning", "degradation", "bounded", "normalize", 2)}, 2, false, 0))
+	writeJSONFile(t, diagnosticsPath, findingEnvelope(diagnosticsSchemaVersion, []any{findingGroup("advisory", "data_quality", "low_confidence", "normalize", 3)}, 4, true, 1))
+	rejections, err := loadRejections(rejectedPath)
+	if err != nil || len(rejections) != 1 || rejections[0].ReasonCode != "invalid" {
+		t.Fatalf("loadRejections() = %#v, %v", rejections, err)
+	}
+	warnings, err := loadWarnings(warningsPath)
+	if err != nil || len(warnings) != 1 || warnings[0].Category != "degradation" || warnings[0].OccurrenceCount != 2 {
+		t.Fatalf("loadWarnings() = %#v, %v", warnings, err)
+	}
+	diagnostics, occurrences, truncated, err := loadDiagnostics(diagnosticsPath)
+	if err != nil || len(diagnostics) != 1 || occurrences != 4 || !truncated || diagnostics[0].Category != "data_quality" {
+		t.Fatalf("loadDiagnostics() = %#v, %d, %t, %v", diagnostics, occurrences, truncated, err)
+	}
+
+	for name, path := range map[string]string{"rejections": rejectedPath, "warnings": warningsPath, "diagnostics": diagnosticsPath} {
+		t.Run("malformed "+name, func(t *testing.T) {
+			if err := os.WriteFile(path, []byte("{"), 0o644); err != nil {
+				t.Fatalf("WriteFile() error = %v", err)
+			}
+			var err error
+			if name == "rejections" {
+				_, err = loadRejections(path)
+			} else if name == "warnings" {
+				_, err = loadWarnings(path)
+			} else {
+				_, _, _, err = loadDiagnostics(path)
+			}
+			if err == nil {
+				t.Fatal("summary decoder error = nil")
+			}
+		})
+	}
+	oversized := filepath.Join(root, "oversized.json")
+	if err := os.WriteFile(oversized, []byte(strings.Repeat("x", maxSummaryBytes+1)), 0o644); err != nil {
+		t.Fatalf("WriteFile(oversized) error = %v", err)
+	}
+	if _, err := loadWarnings(oversized); err == nil || !strings.Contains(err.Error(), "exceeds") {
+		t.Fatalf("loadWarnings(oversized) error = %v", err)
+	}
+	if _, err := loadRejections(oversized); err == nil || !strings.Contains(err.Error(), "exceeds") {
+		t.Fatalf("loadRejections(oversized) error = %v", err)
+	}
+	if _, _, _, err := loadDiagnostics(oversized); err == nil || !strings.Contains(err.Error(), "exceeds") {
+		t.Fatalf("loadDiagnostics(oversized) error = %v", err)
+	}
+}
+
+func TestFakeRunnerCapturesRequestsAndHonorsContextAndError(t *testing.T) {
+	req := RunRequest{PipelineID: "pipeline", References: []ReferenceBinding{{Selector: "party", Path: "/references/party.json"}}}
+	want := RunResult{BundleRoot: "/bundle"}
+	fake := &FakeRunner{Result: want}
+	got, err := fake.Run(context.Background(), req)
+	if err != nil || !reflect.DeepEqual(got, want) || !reflect.DeepEqual(fake.Requests, []RunRequest{req}) {
+		t.Fatalf("Run() = %#v, %v; requests = %#v", got, err, fake.Requests)
+	}
+	req.References[0].Path = "/references/changed.json"
+	if fake.Requests[0].References[0].Path != "/references/party.json" {
+		t.Fatalf("fake retained aliased request references: %#v", fake.Requests[0].References)
+	}
+
+	wantErr := errors.New("configured failure")
+	fake.Err = wantErr
+	if _, err := fake.Run(context.Background(), req); !errors.Is(err, wantErr) {
+		t.Fatalf("Run(configured error) = %v", err)
+	}
+	canceled, cancel := context.WithCancel(context.Background())
+	cancel()
+	before := len(fake.Requests)
+	if _, err := fake.Run(canceled, req); !errors.Is(err, context.Canceled) || len(fake.Requests) != before {
+		t.Fatalf("Run(canceled) error = %v; requests = %d", err, len(fake.Requests))
+	}
+}
+
+func validRunRequest(t *testing.T) RunRequest {
+	t.Helper()
+	root := t.TempDir()
+	configPath := filepath.Join(root, "notarius.yml")
+	inputPath := filepath.Join(root, "input.json")
+	outputRoot := filepath.Join(root, "outputs")
+	workingDirectory := filepath.Join(root, "work")
+	diagnostics := filepath.Join(root, "diagnostics")
+	for _, directory := range []string{outputRoot, workingDirectory, diagnostics} {
+		if err := os.Mkdir(directory, 0o755); err != nil {
+			t.Fatalf("Mkdir(%q) error = %v", directory, err)
+		}
+	}
+	if err := os.WriteFile(configPath, []byte("pipelines: {}\n"), 0o644); err != nil {
+		t.Fatalf("WriteFile(config) error = %v", err)
+	}
+	if err := os.WriteFile(inputPath, []byte("{}\n"), 0o644); err != nil {
+		t.Fatalf("WriteFile(input) error = %v", err)
+	}
+	return RunRequest{
+		Binary: "notarius", ConfigPath: configPath, PipelineID: "dnd-session", InputPath: inputPath,
+		OutputRoot: outputRoot, WorkingDirectory: workingDirectory,
+		ReceiptPath: filepath.Join(diagnostics, "receipt.json"), LogPath: filepath.Join(diagnostics, "stderr.log"),
+		Timeout: time.Second,
+	}
+}
+
+func loadTestCredential(t *testing.T, envName, value string) *configkit.Secret {
+	t.Helper()
+	t.Setenv(envName, value)
+	type testConfig struct {
+		Credential *configkit.Secret `yaml:"credential"`
+	}
+	result, err := configkit.Load(configkit.Bytes("credential.yml", []byte("credential: "+envName+"\n")), configkit.Options[testConfig]{})
+	if err != nil {
+		t.Fatalf("load test credential: %v", err)
+	}
+	return result.Config.Credential
+}
+
+func assertRedactedCredentialFile(t *testing.T, path, canary string) {
+	t.Helper()
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("ReadFile(%q) error = %v", path, err)
+	}
+	assertRedactedCredentialBytes(t, data, canary)
+}
+
+func assertRedactedCredentialBytes(t *testing.T, data []byte, canary string) {
+	t.Helper()
+	text := string(data)
+	if strings.Contains(text, canary) || !strings.Contains(text, "<redacted>") {
+		t.Fatal("captured stream did not contain the required redaction marker")
+	}
+}
+
+func TestValidateValidationSummariesAcceptsReusedProducerWithoutAttempts(t *testing.T) {
+	zero := 0
+	summaries, err := validateValidationSummaries([]validationSummaryDocument{{
+		Stage: "chunk", Status: "complete", ProducerAttemptCount: &zero, TerminalAction: "accepted",
+	}})
+	if err != nil {
+		t.Fatalf("validateValidationSummaries() error = %v", err)
+	}
+	if len(summaries) != 1 || summaries[0].ProducerAttemptCount != 0 {
+		t.Fatalf("summaries = %#v, want one reused producer with zero attempts", summaries)
+	}
+
+	negative := -1
+	if _, err := validateValidationSummaries([]validationSummaryDocument{{
+		Stage: "chunk", Status: "complete", ProducerAttemptCount: &negative, TerminalAction: "accepted",
+	}}); err == nil {
+		t.Fatal("validateValidationSummaries() negative producer attempts error = nil")
+	}
+}
+
+func writeValidBundleAndReceipt(t *testing.T, req RunRequest, includeUnknown bool) {
+	t.Helper()
+	bundle := filepath.Join(req.OutputRoot, "notarius-run-1")
+	if err := os.MkdirAll(filepath.Join(bundle, "lanes"), 0o755); err != nil {
+		t.Fatalf("MkdirAll(bundle) error = %v", err)
+	}
+	for path, data := range map[string]string{
+		"manifest.json":         `{}`,
+		"lanes/npc.json":        `{}`,
+		"chunk-map.json":        `{}`,
+		"evidence-context.json": `{}`,
+	} {
+		if err := os.WriteFile(filepath.Join(bundle, filepath.FromSlash(path)), []byte(data), 0o644); err != nil {
+			t.Fatalf("WriteFile(%q) error = %v", path, err)
+		}
+	}
+	rejection := map[string]any{"stage": "validate", "lane_id": "spells", "reason_code": "invalid_spell", "message": strings.Repeat("external detail", 20)}
+	if includeUnknown {
+		rejection["future"] = true
+	}
+	writeJSONFile(t, filepath.Join(bundle, "rejected.json"), map[string]any{"rejected": []any{rejection}, "future": true})
+	writeJSONFile(t, filepath.Join(bundle, "warnings.json"), findingEnvelope(warningsSchemaVersion, []any{findingGroup("warning", "degradation", "normalized_name", "normalize", 2)}, 2, false, 0))
+	writeJSONFile(t, filepath.Join(bundle, "diagnostics.json"), findingEnvelope(diagnosticsSchemaVersion, []any{findingGroup("advisory", "data_quality", "low_confidence", "normalize", 3)}, 4, true, 1))
+	index := validIndexValue([]any{map[string]any{
+		"lane_id": "npc-registry", "file": "lanes/npc.json", "media_type": "application/json",
+		"module_key": "dnd/npc-registry", "schema_id": "notarius.dnd.npc_registry",
+		"schema_name": "NPCRegistry", "schema_version": "v1", "future": true,
+	}})
+	index["chunk_map"] = map[string]any{
+		"artifact_kind": "chunk_map", "file": "chunk-map.json", "media_type": "application/json",
+		"schema_id": "notarius.chunk_map", "schema_name": "ChunkMap", "schema_version": "v1", "future": true,
+	}
+	index["evidence_context"] = map[string]any{
+		"artifact_kind": "evidence_context", "file": "evidence-context.json", "media_type": "application/json",
+		"schema_id": "notarius.evidence_context", "schema_name": "EvidenceContext", "schema_version": "v1", "future": true,
+	}
+	index["future"] = true
+	writeJSONFile(t, filepath.Join(bundle, "index.json"), index)
+	receipt := map[string]any{
+		"schema_version": ReceiptSchemaVersion, "run_id": "notarius-run-1", "pipeline_id": req.PipelineID,
+		"output_directory": bundle, "index_file": "index.json", "normalized_output_count": 1,
+		"rejected_output_count": 1, "warning_group_count": 1, "warning_occurrence_count": 2,
+		"diagnostic_group_count": 1, "diagnostic_occurrence_count": 4,
+		"diagnostics_truncated": true, "validation_status": "rejected",
+		"validation_summaries": []any{map[string]any{
+			"stage": "normalize", "lane_id": "npc-registry", "status": "complete",
+			"producer_attempt_count": 1, "terminal_action": "accepted",
+		}},
+	}
+	if includeUnknown {
+		receipt["future"] = true
+	}
+	writeJSONFile(t, req.ReceiptPath, receipt)
+}
+
+func createBundleSkeleton(t *testing.T) string {
+	t.Helper()
+	bundle := filepath.Join(t.TempDir(), "bundle")
+	if err := os.MkdirAll(filepath.Join(bundle, "lanes"), 0o755); err != nil {
+		t.Fatalf("MkdirAll(bundle) error = %v", err)
+	}
+	for _, name := range []string{"manifest.json", "rejected.json", "warnings.json", "diagnostics.json", "lanes/npc.json", "chunk-map.json"} {
+		if err := os.WriteFile(filepath.Join(bundle, filepath.FromSlash(name)), []byte("{}"), 0o644); err != nil {
+			t.Fatalf("WriteFile(%q) error = %v", name, err)
+		}
+	}
+	return bundle
+}
+
+func validIndexValue(lanes []any) map[string]any {
+	return map[string]any{
+		"manifest_file": "manifest.json", "output_files": lanes,
+		"rejected_file": "rejected.json", "warnings_file": "warnings.json", "diagnostics_file": "diagnostics.json",
+	}
+}
+
+func findingGroup(disposition, category, reasonCode, origin string, occurrences int) map[string]any {
+	return map[string]any{
+		"disposition": disposition, "category": category, "reason_code": reasonCode,
+		"origin": map[string]any{"stage": origin, "lane_id": "npc-registry"}, "occurrence_count": occurrences,
+		"samples":              []any{map[string]any{"scope": "lane:npc-registry", "message": "external detail"}},
+		"omitted_sample_count": occurrences - 1,
+	}
+}
+
+func findingEnvelope(schema string, groups []any, occurrences int, truncated bool, unrepresented int) map[string]any {
+	value := map[string]any{
+		"schema_version": schema, "group_count": len(groups), "occurrence_count": occurrences,
+		"groups": groups,
+	}
+	if schema == diagnosticsSchemaVersion {
+		value["truncated"] = truncated
+		value["unrepresented_occurrence_count"] = unrepresented
+	}
+	return value
+}
+
+func writeJSONFile(t *testing.T, path string, value any) {
+	t.Helper()
+	data, err := json.Marshal(value)
+	if err != nil {
+		t.Fatalf("json.Marshal() error = %v", err)
+	}
+	if err := os.WriteFile(path, data, 0o644); err != nil {
+		t.Fatalf("WriteFile(%q) error = %v", path, err)
+	}
+}
+
+func writeShellScript(t *testing.T, body string) string {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "notarius-helper")
+	if err := os.WriteFile(path, []byte(body), 0o755); err != nil {
+		t.Fatalf("WriteFile(script) error = %v", err)
+	}
+	return path
+}
+
+func assertTextFile(t *testing.T, path, want string) {
+	t.Helper()
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("ReadFile(%q) error = %v", path, err)
+	}
+	if string(data) != want {
+		t.Fatalf("ReadFile(%q) = %q, want %q", path, string(data), want)
+	}
+}
+
+func cloneMap(source map[string]any) map[string]any {
+	result := make(map[string]any, len(source))
+	for key, value := range source {
+		result[key] = value
+	}
+	return result
+}

internal/adapters/scriptorium/fake.go

@@ -4,7 +4,7 @@ import (
 	"context"
 	"fmt"
 
-	"gitea.maximumdirect.net/eric/narratio/internal/adapters/subprocess"
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 )
 
 // NoopRunner is a deterministic no-op scriptorium adapter.
@@ -142,7 +142,7 @@ func (f *FakeRunner) RenderArtifact(ctx context.Context, req RenderArtifactReque
 
 func materializeRunPlaceholders(req RunArtifactRequest) error {
 	if req.OutputPath != "" {
-		if err := subprocess.WriteFileAtomic(req.OutputPath, []byte("scriptorium noop/fake run artifact\n"), 0o644); err != nil {
+		if err := fileops.WriteFileAtomic(req.OutputPath, []byte("scriptorium noop/fake run artifact\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write run output %q: %w", req.OutputPath, err)
 		}
 	}
@@ -154,17 +154,17 @@ func materializeRunPlaceholders(req RunArtifactRequest) error {
 			"prompt_id":   req.PromptID,
 			"output_path": req.OutputPath,
 		}
-		if err := subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, 0o644); err != nil {
+		if err := writeGeneratedYAML(req.GeneratedConfigPath, payload); err != nil {
 			return fmt.Errorf("write generated config %q: %w", req.GeneratedConfigPath, err)
 		}
 	}
 	if req.StdoutLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StdoutLogPath, []byte("scriptorium noop/fake run stdout placeholder\n"), 0o644); err != nil {
+		if err := fileops.WriteFileAtomic(req.StdoutLogPath, []byte("scriptorium noop/fake run stdout placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stdout log %q: %w", req.StdoutLogPath, err)
 		}
 	}
 	if req.StderrLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StderrLogPath, []byte("scriptorium noop/fake run stderr placeholder\n"), 0o644); err != nil {
+		if err := fileops.WriteFileAtomic(req.StderrLogPath, []byte("scriptorium noop/fake run stderr placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stderr log %q: %w", req.StderrLogPath, err)
 		}
 	}
@@ -173,7 +173,7 @@ func materializeRunPlaceholders(req RunArtifactRequest) error {
 
 func materializeRenderPlaceholders(req RenderArtifactRequest) error {
 	if req.OutputPath != "" {
-		if err := subprocess.WriteFileAtomic(req.OutputPath, []byte("{\"schema\":\"scriptorium.render.v1\",\"placeholder\":true}\n"), 0o644); err != nil {
+		if err := fileops.WriteFileAtomic(req.OutputPath, []byte("{\"schema\":\"scriptorium.render.v1\",\"placeholder\":true}\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write render output %q: %w", req.OutputPath, err)
 		}
 	}
@@ -185,17 +185,17 @@ func materializeRenderPlaceholders(req RenderArtifactRequest) error {
 			"prompt_id":   req.PromptID,
 			"output_path": req.OutputPath,
 		}
-		if err := subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, 0o644); err != nil {
+		if err := writeGeneratedYAML(req.GeneratedConfigPath, payload); err != nil {
 			return fmt.Errorf("write generated config %q: %w", req.GeneratedConfigPath, err)
 		}
 	}
 	if req.StdoutLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StdoutLogPath, []byte("scriptorium noop/fake render stdout placeholder\n"), 0o644); err != nil {
+		if err := fileops.WriteFileAtomic(req.StdoutLogPath, []byte("scriptorium noop/fake render stdout placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stdout log %q: %w", req.StdoutLogPath, err)
 		}
 	}
 	if req.StderrLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StderrLogPath, []byte("scriptorium noop/fake render stderr placeholder\n"), 0o644); err != nil {
+		if err := fileops.WriteFileAtomic(req.StderrLogPath, []byte("scriptorium noop/fake render stderr placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stderr log %q: %w", req.StderrLogPath, err)
 		}
 	}

internal/adapters/scriptorium/generated_config.go

@@ -0,0 +1,19 @@
+package scriptorium
+
+import (
+	"fmt"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
+	"gopkg.in/yaml.v3"
+)
+
+func writeGeneratedYAML(path string, payload any) error {
+	data, err := yaml.Marshal(payload)
+	if err != nil {
+		return fmt.Errorf("marshal generated YAML for %q: %w", path, err)
+	}
+	if err := fileops.WriteFileAtomic(path, data, fileops.WorkspaceFileMode); err != nil {
+		return fmt.Errorf("write generated YAML %q: %w", path, err)
+	}
+	return nil
+}

internal/adapters/scriptorium/subprocess.go

@@ -9,8 +9,12 @@ import (
 	"time"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/subprocess"
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 )
 
+// MaxOutputFileBytes bounds one Scriptorium artifact result.
+const MaxOutputFileBytes int64 = 64 * 1024 * 1024
+
 // SubprocessRunner invokes Scriptorium through its public CLI.
 type SubprocessRunner struct{}
 
@@ -52,13 +56,17 @@ func (r *SubprocessRunner) RunArtifact(ctx context.Context, req RunArtifactReque
 		}
 	}
 
+	envOverrides, sensitiveNames := credentialEnvironment(req.APIKeyEnv)
 	runRes, runErr := subprocess.Run(ctx, subprocess.RunRequest{
-		Executable:    req.Binary,
-		Args:          args,
-		WorkingDir:    req.WorkingDir,
-		Timeout:       req.Timeout,
-		StdoutLogPath: req.StdoutLogPath,
-		StderrLogPath: req.StderrLogPath,
+		Executable:        req.Binary,
+		Args:              args,
+		WorkingDir:        req.WorkingDir,
+		Timeout:           req.Timeout,
+		EnvOverrides:      envOverrides,
+		SensitiveEnvNames: sensitiveNames,
+		DiagnosticOwner:   "scriptorium",
+		StdoutLogPath:     req.StdoutLogPath,
+		StderrLogPath:     req.StderrLogPath,
 	})
 
 	result := ArtifactResult{
@@ -134,13 +142,17 @@ func (r *SubprocessRunner) RenderArtifact(ctx context.Context, req RenderArtifac
 		}
 	}
 
+	envOverrides, sensitiveNames := credentialEnvironment(req.APIKeyEnv)
 	runRes, runErr := subprocess.Run(ctx, subprocess.RunRequest{
-		Executable:    req.Binary,
-		Args:          args,
-		WorkingDir:    req.WorkingDir,
-		Timeout:       req.Timeout,
-		StdoutLogPath: req.StdoutLogPath,
-		StderrLogPath: req.StderrLogPath,
+		Executable:        req.Binary,
+		Args:              args,
+		WorkingDir:        req.WorkingDir,
+		Timeout:           req.Timeout,
+		EnvOverrides:      envOverrides,
+		SensitiveEnvNames: sensitiveNames,
+		DiagnosticOwner:   "scriptorium",
+		StdoutLogPath:     req.StdoutLogPath,
+		StderrLogPath:     req.StderrLogPath,
 	})
 
 	result := ArtifactResult{
@@ -223,6 +235,15 @@ func validateCommonRunRequest(
 	return true, nil
 }
 
+func credentialEnvironment(apiKeyEnv string) (map[string]string, []string) {
+	name := strings.TrimSpace(apiKeyEnv)
+	if name == "" {
+		return nil, nil
+	}
+	value, _ := os.LookupEnv(name)
+	return map[string]string{name: value}, []string{name}
+}
+
 func buildRunArgs(req RunArtifactRequest) []string {
 	args := []string{"run", "--prompt", strings.TrimSpace(req.PromptID)}
 	if cfgPath := strings.TrimSpace(req.ConfigPath); cfgPath != "" {
@@ -321,18 +342,15 @@ func writeInvocationConfig(path string, payload invocationPayload) error {
 		"render_format":        payload.RenderFormat,
 		"render_prompt_logged": payload.RenderPromptStore,
 	}
-	return subprocess.WriteYAMLAtomic(path, data, 0o644)
+	return writeGeneratedYAML(path, data)
 }
 
 func validateNonEmptyOutput(path string) error {
-	info, err := os.Stat(path)
+	data, err := fileops.ReadFileBounded(path, MaxOutputFileBytes)
 	if err != nil {
-		return fmt.Errorf("stat file: %w", err)
+		return fmt.Errorf("scriptorium artifact output exceeds or cannot be read within %d-byte limit: %w", MaxOutputFileBytes, err)
 	}
-	if info.IsDir() {
-		return fmt.Errorf("path is a directory")
-	}
-	if info.Size() <= 0 {
+	if len(data) == 0 {
 		return fmt.Errorf("file is empty")
 	}
 	return nil

internal/adapters/scriptorium/subprocess_test.go

@@ -6,16 +6,12 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
-	"runtime"
 	"strings"
 	"testing"
 	"time"
 )
 
 func TestSubprocessRunnerRunSuccessBuildsDeterministicArgsAndCapturesLogs(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("helper wrapper script uses /bin/sh")
-	}
 
 	t.Setenv("GO_WANT_SCRIPTORIUM_HELPER", "1")
 	t.Setenv("SCRIPTORIUM_HELPER_MODE", "run_success")
@@ -31,7 +27,7 @@ func TestSubprocessRunnerRunSuccessBuildsDeterministicArgsAndCapturesLogs(t *tes
 		ConfigPath:          "/etc/scriptorium/config.yml",
 		PromptID:            "dnd.session_recap",
 		ProfileID:           "local-quality",
-		InputPaths:          map[string]string{"transcript": filepath.Join(dir, "processed.json"), "other": filepath.Join(dir, "other.md")},
+		InputPaths:          map[string]string{"transcript": filepath.Join(dir, "polished.json"), "other": filepath.Join(dir, "other.md")},
 		Vars:                map[string]string{"session_id": "2026-05-03", "campaign_name": "Icewind Dale"},
 		OutputPath:          filepath.Join(dir, "artifacts", "session_recap.md"),
 		StdoutLogPath:       filepath.Join(dir, "logs", "scriptorium.run.stdout.log"),
@@ -95,9 +91,6 @@ func TestSubprocessRunnerRunSuccessBuildsDeterministicArgsAndCapturesLogs(t *tes
 }
 
 func TestSubprocessRunnerRunExitCodeOneFails(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("helper wrapper script uses /bin/sh")
-	}
 	t.Setenv("GO_WANT_SCRIPTORIUM_HELPER", "1")
 	t.Setenv("SCRIPTORIUM_HELPER_MODE", "fail_exit1")
 	t.Setenv("SCRIPTORIUM_HELPER_RECORD_PATH", filepath.Join(t.TempDir(), "record.json"))
@@ -118,9 +111,6 @@ func TestSubprocessRunnerRunExitCodeOneFails(t *testing.T) {
 }
 
 func TestSubprocessRunnerRunExitCodeTwoReturnsValidationFailureAndPreservesOutput(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("helper wrapper script uses /bin/sh")
-	}
 	t.Setenv("GO_WANT_SCRIPTORIUM_HELPER", "1")
 	t.Setenv("SCRIPTORIUM_HELPER_MODE", "fail_exit2_with_output")
 	t.Setenv("SCRIPTORIUM_HELPER_RECORD_PATH", filepath.Join(t.TempDir(), "record.json"))
@@ -144,9 +134,6 @@ func TestSubprocessRunnerRunExitCodeTwoReturnsValidationFailureAndPreservesOutpu
 }
 
 func TestSubprocessRunnerRunMissingOutputOnSuccessFails(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("helper wrapper script uses /bin/sh")
-	}
 	t.Setenv("GO_WANT_SCRIPTORIUM_HELPER", "1")
 	t.Setenv("SCRIPTORIUM_HELPER_MODE", "run_success_missing_output")
 	t.Setenv("SCRIPTORIUM_HELPER_RECORD_PATH", filepath.Join(t.TempDir(), "record.json"))
@@ -166,9 +153,6 @@ func TestSubprocessRunnerRunMissingOutputOnSuccessFails(t *testing.T) {
 }
 
 func TestSubprocessRunnerRenderSuccess(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("helper wrapper script uses /bin/sh")
-	}
 	t.Setenv("GO_WANT_SCRIPTORIUM_HELPER", "1")
 	t.Setenv("SCRIPTORIUM_HELPER_MODE", "render_success")
 	recordPath := filepath.Join(t.TempDir(), "record.json")
@@ -180,7 +164,7 @@ func TestSubprocessRunnerRenderSuccess(t *testing.T) {
 	req := RenderArtifactRequest{
 		Binary:              wrapper,
 		PromptID:            "dnd.session_recap",
-		InputPaths:          map[string]string{"transcript": filepath.Join(dir, "processed.json")},
+		InputPaths:          map[string]string{"transcript": filepath.Join(dir, "polished.json")},
 		OutputPath:          filepath.Join(dir, "artifacts", "session_recap.render.json"),
 		StdoutLogPath:       filepath.Join(dir, "logs", "scriptorium.render.stdout.log"),
 		StderrLogPath:       filepath.Join(dir, "logs", "scriptorium.render.stderr.log"),
@@ -285,7 +269,7 @@ type scriptoriumHelperRecord struct {
 func runReqForTest(t *testing.T, binary string) RunArtifactRequest {
 	t.Helper()
 	dir := t.TempDir()
-	transcriptPath := filepath.Join(dir, "processed.json")
+	transcriptPath := filepath.Join(dir, "polished.json")
 	writeScriptoriumFile(t, transcriptPath, `{"segments":[]}`)
 	return RunArtifactRequest{
 		Binary:              binary,