40 KiB
Configuration Reference
Purpose
Narratio resolves three YAML documents:
pipeline.yml: pipeline/runtime settingscampaign.yml: campaign identity and stable input defaultssession.yml: session identity, metadata, and audio source selection
Discovery and Selection
pipeline.yml
An explicit --config selects exactly that file, including a custom filename.
Otherwise ConfigKit searches these locations in order:
- The working directory, for
narratio.ymlthennarratio.yaml. - The Go user-config directory's
narratio/subdirectory, for those named files followed byconfig.yml,config.yaml,main.yml, andmain.yaml. - The Go user-config directory itself, for the named files.
/usr/local/etc/narratio/and then/etc/narratio/, each for named files followed by the generic filenames above./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-fileis 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
When --session is omitted, local search order is:
/usr/local/etc/narratio/session.yml/etc/narratio/session.yml
If no local session exists and a session_id is known, Narratio loads the
session from configured object storage. It selects the prepared session in the
current committed run when available; if no current pointer exists or an older
commit has no prepared session, it falls back to the session-init session.yml
object. Downloaded session bytes are contextless snapshots, with remote object
provenance retained independently of locally materialized checksums.
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
--overlay 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-overlay> <right-overlay> uses the same pipeline and
campaign selectors, resolves each named overlay with an independent ConfigKit
load, and does not accept a separate --overlay 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, overlay, 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/overlay/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 definition contributor paths, which may identify
several files for one family member. The CLI reference
owns command syntax and output conventions.
config diff compares normalized field values rather than YAML text or source
ownership. It emits native ordered added, removed, and changed records with
JSON Pointer paths and compact JSON values. Lists are compared atomically, and
changed regions may contain whole values. It 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
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
in the recommended one-definition files shown by that bundle. Convert campaign
rosters to canonical party input, 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.
- 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
defaultselect the base; another name selectsoverlays/<name>.ymlrelative to the pipeline root. - 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.
- Defaults apply only to absent fields. Explicit empty strings, zero values,
false, andnullretain 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 optionalspell_catalog_filealso inherits a campaign value when omitted by the session. party_fileis parsed when pipeline and campaign configuration are combined. It must be a versioned canonical party, is campaign-owned and derives the players input internally.players_fileand sessionparty_fileare unsupported configuration keys.- Exactly one audio mode must be configured in session input:
- local (
audio_diroraudio_files), or - S3 (
audio_s3.prefix).
- local (
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.
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
and consumer guide
for full selection, composition, collection, and reserved-key semantics.
The maintained bundle 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 toconfig:. Nestedconfigdata and the Goconfigkitpackage and secret tags have different meanings. - Rename or move pipeline files to the discovery names above, or retain a custom
filename such as
pipeline.ymland 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.sequenceswhere 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
campaigns:
root: /usr/local/share/narratio/campaigns
default_campaign_id: sample-campaign
whisperx:
transcribe_url: https://transcription.example.com/transcribe
campaign.yml
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)
session_id: 2026-05-03
inputs:
audio_dir: ./audio
Secrets Handling
- Do not place raw secrets in YAML.
- Credential fields contain environment-variable names, represented internally
as ConfigKit typed secret references (for example
pipeline.notarius.credentials: [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
nullwhen 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/secretswhen 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.
- 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 (normally0600); 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.
publish:
enabled: true
upload_run: true
outputs:
- source: narratio.transcript.final_trimmed
dest: transcripts/final.trimmed.json
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
required: true
Rules:
outputs[].sourceis required.outputs[].destmay be omitted when derivable from source.- extraction sources require an explicit
outputs[].destand publish only when a rule names that source; the Notarius index and complete bundle are not publish sources. outputs[].requireddefaults totrue.- publish locks are independent remote session objects managed with
narratio session locks; they are not pipeline configuration fields.
Full Schema
Pipeline
| Field | Type | Required | Default / Rule |
|---|---|---|---|
config.imports |
list | No | native source-root import selections; see 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 |
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 |
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 |
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 |
pipeline.notarius.credentials[] |
list[secret reference] | No | empty; exact environment-variable names forwarded to Notarius |
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 |
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.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.
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
for the subprocess and redaction boundary.
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:
notarius:
config_overlay: downstream-economy
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
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
independent of pipeline.notarius.credentials: an overlay may change either or
both fields according to the deployed Notarius configuration. See the
Notarius integration contract for invocation and
failure behavior.
Notarius Credentials
pipeline.notarius.credentials optionally lists environment-variable names
to forward to the Notarius child process:
notarius:
credentials: [OPENROUTER_API_KEY, ANTHROPIC_API_KEY]
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
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 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:
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 for the subprocess
boundary and the complete example
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 for the
current ten-lane D&D mapping and the Notarius contract
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.
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.
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 final configuration resolution. Authors use depends_on only for
ordering constraints that are not already expressed by an artifact input.
Use narratio config artifacts
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. 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) 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 |
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_diroraudio_files) or S3 mode (audio_s3.prefix), not both. audio_s3requirespipeline.storage.backend: s3and 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 for complete pipeline, campaign, session, template, and input fixtures. Keep complete copyable files there rather than duplicating them in this reference.