Files
narratio/docs/config.md

734 lines
40 KiB
Markdown
Raw Normal View History

# Configuration Reference
2026-05-18 22:03:59 -05:00
## Purpose
2026-05-18 22:03:59 -05:00
Narratio loads pipeline, campaign, and session YAML, with a canonical party
roster selected explicitly or through the campaign:
2026-05-18 22:03:59 -05:00
- `pipeline.yml`: pipeline/runtime settings
- `campaign.yml`: campaign identity and stable input defaults
- `session.yml`: session identity, metadata, and audio source selection
2026-05-18 22:03:59 -05:00
## Discovery and Selection
2026-05-18 22:03:59 -05:00
### `pipeline.yml`
2026-05-18 22:03:59 -05:00
An explicit `--config` selects exactly that file, including a custom filename.
Otherwise ConfigKit searches these locations in order:
1. The working directory, for `narratio.yml` then `narratio.yaml`.
2. The Go user-config directory's `narratio/` subdirectory, for those named
files followed by `config.yml`, `config.yaml`, `main.yml`, and `main.yaml`.
3. The Go user-config directory itself, for the named files.
4. `/usr/local/etc/narratio/` and then `/etc/narratio/`, each for named files
followed by the generic filenames above.
5. `/etc/`, for the named files.
On Linux, the user-config directory normally follows `XDG_CONFIG_HOME`, or
`~/.config` when it is unset. A selected invalid file fails loading; discovery
does not continue to another candidate.
### `campaign.yml`
Selection rules:
- 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`.
### `session.yml`
An explicit `--session-file` selects exactly that file. Otherwise local search
order is:
2026-05-18 22:03:59 -05:00
1. `/usr/local/etc/narratio/session.yml`
2. `/etc/narratio/session.yml`
2026-05-18 22:03:59 -05:00
If no local session exists and a `session_id` is known, Narratio loads the
session from configured object storage. Downloaded session bytes are contextless
snapshots, with remote object
provenance retained independently of locally materialized checksums.
Remote loading prefers an authored session-root `session.yml`, including updates
from `session init --remote --force`. When that object is absent, loading falls
back to the current commit's standalone prepared session. Published snapshots
remain immutable; restore validates the pointer-selected committed state.
### Native inspection and domain derivation
Native configuration inspection exposes four actual typed ConfigKit results:
app (the default pipeline scope), campaign, session, and party. Defaults,
normalization, and configuration-owned validation finish within their supported
load lifecycle. Session configuration includes applicable campaign defaults
before handoff. Completed values remain unchanged by planning or execution.
App inspection retains artifact-family declarations and needs no campaign or
party solely for expansion. Narratio derives concrete artifact catalogs, players,
resolved dependencies, and publication actions separately using the selected
canonical roster. `artifacts list` inspects those domain definitions;
`session plan` and `session artifacts` expose decisions and availability.
Native sources/explanations retain actual imports, origins, history, and recorded
resolution evidence. Comparisons load each side independently using its own
normal defaults. App-only inspection overrides apply during that invocation's
load. Safe views hide resolved credentials. Persisted preparation projections
retain reference names and do not replace the native inspection result.
See the [CLI reference](cli.md#configuration-inspection) for scopes, selectors,
path operations, overrides, comparison modes, and report shapes.
### Party selection
`--party-file` selects an exact canonical roster instead of the campaign-default
file. Explicit relative paths use the invocation directory; invalid or missing
explicit input fails without fallback. The campaign's configured party field
remains unchanged. Inspection, players, family derivation, planning, and execution
use the same selected roster. Format and validation belong in the
[party integration contract](integrations/party.md).
### Migrating to the maintained bundle
Use the [production/testing bundle](../examples/production-testing/pipeline.yml)
2026-09-07 04:55:13 +00:00
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 `overlays/testing.yml` overlay. Put ordinary artifacts and families
2026-09-07 04:55:13 +00:00
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 `artifacts list`; use
`config diff --against-overlay testing` to
2026-09-07 04:55:13 +00:00
review the overlay before running a session. Unversioned party documents are
2026-09-02 11:57:51 +00:00
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
2026-05-20 20:41:28 -05:00
2026-09-07 03:54:41 +00:00
- ConfigKit performs strict typed YAML decoding and accepts exactly one document;
unknown fields, duplicate keys, and trailing documents fail load.
- Local pipeline, campaign, session, and party documents may declare native
imports and sibling inheritance. Only the pipeline selects an overlay.
- An omitted overlay, empty overlay option, and exact `default` select the base;
another name selects `overlays/<name>.yml` relative to the pipeline root.
2026-08-10 21:32:15 +00:00
- 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.
- ConfigKit applies its acquisition limits to configuration sources and imports.
- Pipeline defaults are applied before validation.
2026-09-07 04:55:13 +00:00
- 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.
2026-08-29 15:40:23 +00:00
- Required stable files (`speakers_file`, `autocorrect_file`, `glossary_file`,
2026-09-02 12:04:35 +00:00
`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.
- The selected party is parsed when domain context or party inspection needs
it. It must be a versioned [canonical party](integrations/party.md). The
campaign supplies its default file; an explicit CLI selection replaces it
for the invocation and supplies the derived players input. `players_file` and
2026-09-02 12:04:35 +00:00
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`).
2026-05-18 22:03:59 -05:00
### Pipeline imports and overlays
Local pipeline, campaign, session, and party files can use source-root
`config.imports` and `config.sequences`. Every acquired document has its own
source-root controls, including imported fragments. Nested `config` keys are
ordinary data. `extends` is reserved for native sibling inheritance; parents
remain ordinary entries subject to Narratio's effective-domain validation.
```yaml
config:
imports:
- path: artifacts/session-recap.yml
destination: [scriptorium, artifacts, session_recap]
required: true
- dir: artifacts/families
pattern: "*.yml"
```
Imports support `path`, `dir`, and `glob` selectors, applicable filters and
relative destinations. Paths are relative to the declaring source. Missing or
empty selections are optional by default; use `required: true` when a selection
is essential. Selected invalid input fails. Destinations place content under
literal mapping keys, independent of filenames; nested imports can declare
relative destinations. Strict peer contributions must satisfy ConfigKit's
composition rules, and Narratio validates the resulting effective entries.
A selected pipeline overlay is applied after base composition. It may declare
root `config.sequences` but cannot import other files. Ordinary overlay lists
replace the lower list; declared collections can use native `replace`, `append`,
or `upsert`. Upsert replaces a whole matching record; an empty append or upsert
does not clear the lower list. Mapping and identified-list inheritance follow
native sibling rules. See the pinned [ConfigKit configuration contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/docs/config.md)
and [consumer guide](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/docs/consumers/README.md)
for full selection, composition, collection, and reserved-key semantics.
The [maintained bundle](../examples/production-testing/pipeline.yml) illustrates
these controls, family expansion, and a split roster.
Relative host-resource paths, including integration configuration files,
workspace/campaign/spool/cache roots, campaign template and stable inputs, and
session stable inputs and local audio references, resolve from the effective
value's defining source. Inherited values follow their origin. When no distinct
usable source context exists, the main source is the fallback; if it too is
contextless, the invocation directory is used. Explicit CLI-relative file paths
use the invocation directory. Artifact outputs, publish destinations, logical
IDs, and binary names retain their domain meanings.
The effective digest excludes source layout, overlay identity, and secret values;
credential reference names and resolved resource paths participate. Prepared
campaign, session, and party documents contain effective standalone values rather
than authored import directives. Session fields omitted by the author remain
eligible to inherit the receiving campaign's values.
### Upgrade from earlier configuration
- Rename source-root `configkit:` controls to `config:`. Nested `config` data
and the Go `configkit` package and secret tags have different meanings.
- Rename or move pipeline files to the discovery names above, or retain a custom
filename such as `pipeline.yml` and pass it with `--config`.
- Move conventional secrets to `/usr/local/etc/narratio/secrets`, supply them
through the environment, or pass the previous directory with `--secrets-dir`.
- Review relative resource references moved into fragments: their defining
source now supplies the base. Mark necessary imports `required: true`.
- Review lists and use `config.sequences` where append or whole-record upsert is
intended. Verify the effective result with the inspection commands.
- Prepared documents contain effective values; retain authored roots and their
companions separately for editing. Separately installed downstream tools own
their own configuration migrations.
These control-key changes require a major version for the eventual Narratio
release. This migration does not itself publish a release.
## Minimal Working Configuration
`pipeline.yml`
2026-05-18 22:03:59 -05:00
```yaml
campaigns:
root: /usr/local/share/narratio/campaigns
default_campaign_id: sample-campaign
2026-05-18 22:03:59 -05:00
whisperx:
transcribe_url: https://transcription.example.com/transcribe
2026-05-18 22:03:59 -05:00
```
`campaign.yml`
2026-05-20 20:41:28 -05:00
2026-05-18 22:03:59 -05:00
```yaml
campaign_id: sample-campaign
2026-05-20 20:41:28 -05:00
inputs:
speakers_file: ./speakers.yml
autocorrect_file: ./autocorrect.yml
glossary_file: ./glossary.yml
party_file: ./party.yml
2026-05-20 20:41:28 -05:00
```
`session.yml` (local audio)
```yaml
session_id: 2026-05-03
inputs:
audio_dir: ./audio
```
## Secrets Handling
- Do not place raw secrets in YAML.
2026-09-07 04:29:00 +00:00
- Credential fields contain environment-variable names, represented internally
as ConfigKit typed secret references (for example
2026-09-25 15:33:46 +00:00
`pipeline.notarius.credentials: [NOTARIUS_LLM_API_KEY]`). A configured reference
2026-09-07 04:29:00 +00:00
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 `/usr/local/etc/narratio/secrets` when present;
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.
2026-08-10 18:24:29 +00:00
- 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.
## Publish Configuration Summary
Publish rules live under `pipeline.publish`.
2026-05-18 22:03:59 -05:00
```yaml
publish:
2026-05-18 22:03:59 -05:00
enabled: true
upload_run: true
outputs:
- source: narratio.transcript.final_trimmed
dest: transcripts/final.trimmed.json
2026-05-18 22:03:59 -05:00
required: true
- 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
2026-05-18 22:03:59 -05:00
required: true
```
Rules:
- `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`.
2026-09-05 13:17:46 +00:00
- publish locks are independent remote session objects managed with
`narratio session locks`; they are not pipeline configuration fields.
2026-05-18 22:03:59 -05:00
## Full Schema
2026-05-18 22:03:59 -05:00
### Pipeline
| Field | Type | Required | Default / Rule |
| --- | --- | --- | --- |
| `config.imports` | list | No | native source-root import selections; see [imports and overlays](#pipeline-imports-and-overlays) |
| `pipeline.workspace.root` | string | No | `/var/lib/narratio` |
| `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 |
2026-08-10 21:32:15 +00:00
| `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` |
2026-09-07 04:29:00 +00:00
| `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_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` |
2026-08-10 21:49:44 +00:00
| `pipeline.whisperx.transcribe_url` | string | Yes | absolute `http` or `https` URL |
| `pipeline.whisperx.language` | string | No | `en` |
| `pipeline.whisperx.timeout` | duration | No | `30m` |
| `pipeline.whisperx.retries` | int | No | `3` |
| `pipeline.whisperx.retry_delay` | duration | No | `2s` |
| `pipeline.whisperx.concurrency` | int | No | `2` |
| `pipeline.seriatim.binary` | string | No | `seriatim` |
| `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` |
| `pipeline.seriatim.env.overlap_word_run_gap` | float | No | unset |
| `pipeline.seriatim.env.overlap_word_run_reorder_window` | float | No | unset |
| `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 | No | `3h` |
| `pipeline.audita.credentials[]` | list[secret reference] | No | empty; exact environment-variable names forwarded to Audita |
| `pipeline.audita.modules[]` | list[string] | No | unset; omit to use Audita defaults, set `[]` for no modules |
| `pipeline.audita.overlay` | string | No | empty; no downstream overlay override |
| `pipeline.audita.proposal_profile` | string | No | empty; no downstream proposal-profile override |
| `pipeline.audita.validation_profile` | string | No | empty; no downstream validation-profile override |
| `pipeline.audita.transcript_description` | string | No | empty |
| `pipeline.audita.config_path` | string | No | empty |
| `pipeline.audita.output_schema` | string | No | empty |
| `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 | `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 | 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 | 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` |
2026-09-25 15:33:46 +00:00
| `pipeline.notarius.credentials[]` | list[secret reference] | No | empty; exact environment-variable names forwarded to Notarius |
2026-09-28 03:09:55 +00:00
| `pipeline.notarius.config_overlay` | string | No | unset; exact Notarius ConfigKit overlay selector |
| `pipeline.notarius.config_path` | string | Conditional | required when enabled; relative paths resolve from their defining source |
| `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 their defining source |
2026-09-16 18:14:40 +00:00
| `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` |
2026-08-29 15:40:23 +00:00
| `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` |
2026-05-27 08:09:22 -05:00
| `pipeline.render.include_segment_ids` | bool | No | `true` |
| `pipeline.render.include_metadata` | bool | No | `false` |
| `pipeline.scriptorium.binary` | string | No | `scriptorium` |
| `pipeline.scriptorium.credentials[]` | list[secret reference] | No | empty; exact environment-variable names forwarded to Scriptorium |
| `pipeline.scriptorium.config_path` | string | No | empty |
| `pipeline.scriptorium.timeout` | duration | No | `10m` |
| `pipeline.scriptorium.render_debug` | bool | No | `false` |
| `pipeline.scriptorium.artifacts` | map | 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 |
### Audita Selection and Credentials
`pipeline.audita.config_path` optionally passes an Audita v2 configuration file;
when empty, Audita uses its own native config discovery. `overlay`,
`proposal_profile`, and `validation_profile` are independent, optional Audita
selectors. Empty or omitted strings add no command-line override. Narratio's
selected pipeline overlay is never inferred as an Audita overlay, and Narratio
does not create or validate Audita's backend or PromptKit profile files. Prepare
them with [Audita's v2 migration guide](https://gitea.maximumdirect.net/eric/audita/src/tag/v2.0.0/docs/migrations/v2.md).
Omit `modules` or set it to `null` to use Audita's configured default sequence.
Set `modules: []` to run no correction modules. A nonempty list is passed in
order, including repetitions. Narratio does not add a reporting or debug flag;
Audita's external configuration controls those settings.
`pipeline.audita.credentials` lists secret-reference names, not values. Narratio
resolves every listed name during pipeline loading and forwards the captured
nonempty value under that exact name to Audita. It does not inspect Audita's
configuration to discover names or map them to aliases. Audita v2 resolves
credentials for **all configured backends**, even ones not selected by the
current profiles: list every named backend credential in the selected Audita
configuration. An unauthenticated backend needs no reference. Omission, `null`,
or `[]` forwards nothing. A Narratio overlay replaces the entire list, and
`[]` clears it. See the [Audita integration contract](./integrations/audita.md)
for the subprocess and redaction boundary.
2026-09-28 03:09:55 +00:00
<a id="notarius-configuration-profile"></a>
2026-09-28 03:09:55 +00:00
### Notarius Configuration Overlay
Migration: rename `pipeline.notarius.config_profile` to `config_overlay`.
The old field is rejected; there is no compatibility alias. For Notarius v0.8+
move selected downstream files from `profiles/` to `overlays/` beside its root
configuration. This does not rename PromptKit LLM profiles.
The renamed selector also changes extraction resume evidence for named
selections: their existing extraction is regenerated on the next applicable
run, with normal dependent invalidation. Omitted/base selections do not acquire
a new invalidation solely from this rename.
`pipeline.notarius.config_overlay` optionally selects a Notarius ConfigKit
configuration overlay when extraction executes:
```yaml
notarius:
2026-09-28 03:09:55 +00:00
config_overlay: downstream-economy
```
2026-09-28 03:09:55 +00:00
When the field is omitted or `null`, Narratio supplies no downstream overlay
selector and preserves Notarius's existing configuration-selection behavior.
When present, Narratio forwards the exact string to Notarius, including an
empty string or `default`, which explicitly select Notarius's composed base
configuration. Notarius owns selector interpretation and validation; Narratio
2026-09-28 03:09:55 +00:00
does not restrict overlay names, resolve overlay files, or rewrite the value.
This selection is independent of Narratio's own `--overlay` selection. A
Narratio overlay may explicitly select a differently named Notarius overlay,
but Narratio never forwards its own overlay name automatically. It is also
2026-09-25 15:33:46 +00:00
independent of `pipeline.notarius.credentials`: an overlay may change either or
both fields according to the deployed Notarius configuration. See the
[Notarius integration contract](./integrations/notarius.md) for invocation and
failure behavior.
2026-09-25 15:33:46 +00:00
### Notarius Credentials
2026-09-25 15:33:46 +00:00
`pipeline.notarius.credentials` optionally lists environment-variable names
to forward to the Notarius child process:
```yaml
notarius:
2026-09-25 15:33:46 +00:00
credentials: [OPENROUTER_API_KEY, ANTHROPIC_API_KEY]
```
2026-09-25 15:33:46 +00:00
The list contains variable names, not credential values. Those names must
match the references used by the Notarius/PromptKit profiles that Notarius
loads. Notarius owns profile lookup; Narratio neither infers those names nor
remaps them. Omission, `null`, or `[]` forwards nothing. Each 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.
The Notarius child receives only Narratio's minimal execution environment plus
2026-09-25 15:33:46 +00:00
these exact selected names and loaded values. Other credentials are not forwarded.
Changing a value, name, presence, or absence does not invalidate extract's
semantic resume evidence. The public names remain part of safe effective
inspection, so renaming them may appear in `config diff` and change the effective
configuration digest; rotating only their values does neither. An overlay
replaces the whole list, including with `[]` to clear it.
See the [Notarius integration contract](./integrations/notarius.md) for the
delivery and redaction boundary.
2026-09-16 18:14:40 +00:00
### 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.
2026-08-29 15:40:23 +00:00
### 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
2026-09-16 18:14:40 +00:00
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
2026-08-29 15:40:23 +00:00
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 |
| --- | --- | --- | --- |
| `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 |
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.
### Scriptorium Credentials
Set `scriptorium.credentials: [OPENROUTER_API_KEY]` in the pipeline file to
forward that provider key to Scriptorium. List additional provider names only
when the selected downstream configuration needs them. The same list applies
to trim bounds generation, analysis (including character families), and their
render-debug calls. Scriptorium retains provider/profile selection; Narratio
does not pass a model-request `--api-key-env` override.
As with Audita and Notarius, names are ConfigKit secret references resolved at
pipeline load time using the existing environment/secrets bootstrap precedence,
even when no Scriptorium stage executes. Omitted, null, or empty lists forward
nothing. An overlay replaces the entire list; `[]` clears it. Captured values
are forwarded under their exact names and registered for diagnostic redaction.
Inspection and generated metadata contain names only. Credential changes do
not invalidate completed trim or analysis work; rotating values also leaves
the effective configuration digest unchanged. Other environment variables
retain the shared minimal subprocess inheritance rules.
### Scriptorium Artifact Entries
For each `pipeline.scriptorium.artifacts.<name>`:
| 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 |
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.
2026-08-10 23:18:29 +00:00
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
2026-09-02 14:38:51 +00:00
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.
2026-08-10 23:18:29 +00:00
For each artifact input `pipeline.scriptorium.artifacts.<name>.inputs.<input_name>`:
| 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 |
`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.
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 domain catalog derivation. Authors use `depends_on` only for
ordering constraints that are not already expressed by an artifact input.
Use [`narratio artifacts list`](./cli.md#artifacts-list)
2026-09-07 04:46:20 +00:00
to inspect keys, definition sources, outputs, and effective dependencies without
loading a session or creating runtime state.
### Scriptorium Artifact Families
`pipeline.scriptorium.artifact_families` declares a shared artifact template
for every canonical campaign character. Domain catalog derivation expands each
family into separate concrete artifact entries before analyze planning or
Scriptorium invocation, retaining the authored declarations in configuration.
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`) validated against effective `pipeline.publish` settings and expanded into concrete publish outputs when enabled |
An enabled family publish declaration is validated against the effective
`pipeline.publish` configuration, including its defaults; it does not require
an explicit `publish.enabled` declaration in the same source file.
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 their defining source |
2026-08-29 15:40:23 +00:00
| `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 | omission inherits the campaign spell catalog; an explicit empty string clears this optional input |
| `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.
2026-08-10 21:32:15 +00:00
- `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.