# Configuration This is the canonical reference for Notarius configuration fields, defaults, source selection, and selectable modules. The sole application version is `6` (also accepted as `"6"`). [CLI Reference](cli.md) owns invocation syntax; [Operations](operations.md) owns physical state and recovery; integration contracts own artifact payloads. Upgrading an older deployment or caller? Use the [native migration guide](consumers/native-migration.md). ## Configuration Discovery And Precedence Configuration-consuming commands select one main file: 1. Explicit `--config`, which must not be empty. 2. Nonblank `NOTARIUS_CONFIG`. 3. `notarius.yml`, then `notarius.yaml`, in the working directory. 4. Go's user configuration directory: first its `notarius/` subdirectory, trying `notarius.yml`, `notarius.yaml`, `config.yml`, `config.yaml`, `main.yml`, `main.yaml`; then the two `notarius.*` names directly beneath it. 5. `/usr/local/etc/notarius/`, then `/etc/notarius/`, with those six names; finally `/etc/notarius.yml` and `/etc/notarius.yaml`. Generic working-directory filenames and home-directory searches are not enabled. Missing discovery candidates advance the search; a selected missing, unreadable, or invalid explicit source fails without fallback. Exhausted discovery fails. Discovery selects a main file rather than layering every candidate. Use explicit selection for services and subprocesses. One ConfigKit result contains the application and native PromptKit settings. Its source layers, from lower to higher priority, are: 1. The bundled OpenRouter resource underlay. 2. Embedded Notarius prompts/profiles and their filesystem-backed schema root. 3. Optional operator companions beside the **actual selected main file**: `prompts.yml` and recursively selected `*.yml`/`*.yaml` files in `prompts/`. These form one strict peer group: filenames do not confer priority and conflicting contributions fail. 4. The selected application main source and its native import graph. 5. The selected ConfigKit overlay. Companions are wrapperless native PromptKit settings mounted at `/promptkit`. They are optional only when absent; malformed or unreadable selected content fails. The loader does not search the invocation directory for substitute companions. A companion's imports and content-file paths retain its native source context. Main imports use their declared destinations; main-file native settings belong beneath `promptkit`. Source assembly, inheritance, typed defaults/decoding, explicit configuration overrides, application normalization, and validation use ConfigKit's native processing order. Overrides cannot repair earlier parse, composition, version, inheritance, or decoding errors. The same captured result serves inspection and engine construction, not a separate profile loader. The overlay selector is a name: `development` selects `overlays/development.yml` under the selected main source's configuration root. Empty and exact lowercase `default` select the base. A missing selected overlay fails; there is no overlay stack or extension fallback. Application overlays are distinct from PromptKit profiles. See [ConfigKit's selected-overlay contract][overlays]. Only `NOTARIUS_CONFIG` participates in application environment selection. Credential environment names are native PromptKit settings, not field-level application environment overlays. ## Maintained Examples - [Minimal](../examples/dnd-minimal/config.yml): embedded resources only, Seriatim input, generic chunking, and one spell lane. - [Complete](../examples/dnd-complete/config.yml): ordered steps and all D&D families, generated references, independent state roots, workers, cache/mode/ turn controls, and selected domain auxiliaries. Its [companion](../examples/dnd-complete/prompts.yml) demonstrates native profile and backend inheritance without replacing native queue defaults. - The complete [pipeline fragment](../examples/dnd-complete/pipelines/dnd-session.yml) and [first-step fragment](../examples/dnd-complete/pipelines/dnd-session.describe-session.yml) retain declaration-relative imports and references. Its development pipeline selects a derived profile and zero semantic correction turns. The [development overlay](../examples/dnd-complete/overlays/development.yml) demonstrates serial workers and cache bypass. The examples use separate directories so complete-example companions do not alter minimal-example selection. Use these full files as starting points; the fragments below illustrate individual settings. ## File Shape And Defaults Application fields are strict. Unknown application fields, duplicate mapping keys, blank identifiers, and identifiers duplicated after trimming are rejected. PromptKit-owned resource records use the [native format][formats], including its extension-field and strict nested-object rules; arbitrary extension fields are not automatically secret. | Root field | Type | Default / meaning | | --- | --- | --- | | `version` | integer or quoted string | Required; `6` only, without translation of older versions. | | `promptkit` | native settings | Embedded and bundled resources, overlaid by selected sources. | | `pipelines` | map | Empty; maps IDs to pipeline definitions. | | `concurrency.workers` | positive integer | `64`; one shared ready-job pool. | | `output.directory` | nonempty path | `./notarius-output`. | | `cache_directory` | path | Omitted or empty selects `os.UserCacheDir()/notarius`. | | `debug.directory` | path | Omitted selects `/tmp/notarius-debug`; explicit empty disables capture. | Nonempty relative application destinations and reference paths resolve from the file contributing the surviving declaration, including imported, overlaid, or inherited values. A child replacement keeps the child's origin. Built-in relative destinations use the selected main file's directory; invocation path overrides use the working directory. Absolute paths remain absolute. An empty output directory is invalid. Empty cache selection deliberately chooses the per-user default; on Linux this normally follows `XDG_CACHE_HOME` or `~/.cache`. Null is not a universal substitute for omission or empty: effective types and application validation still apply. Directory selection does not configure filesystem access policy or enable debug. See [Operations](operations.md) for lifecycle, permissions, and provisioning. ## Imports And Sibling Inheritance Root `config` contains native controls such as imports and sequence declarations. For example: ~~~yaml config: imports: - path: pipelines/dnd-session.yml required: true ~~~ Imports are optional by default. Paths, directory selection, destinations, sequence-item placement, source containment, and dependency-ready assembly order follow [ConfigKit's import contract][imports]. Imported fragments need not repeat the application version. A nested application field named `config` is ordinary data, not another source-control block. Mapping inheritance names a sibling, such as `extends: production` inside `pipelines`. Identified-list inheritance uses an identity mapping such as `extends: {id: parent}`. Parents must survive in the same sibling collection; these are not paths or cross-namespace references. Child mappings recursively overlay parents. Scalars and null replace inherited values; an empty mapping does not clear existing fields. Lists follow their native registered/declared composition policy. Pipeline steps are identified by `id`: native upsert replaces a matching **whole record** in place and appends new IDs. It does not patch fields of a matching step. Unidentified lists replace as whole values across layers. Explicit replace with `[]` clears a list; empty append/upsert does not. Validator lists are not automatically identified. An identified record's `extends` can retain a distinct sibling's fields before applying child changes. All surviving records remain real validated records, not template-only definitions. Every final pipeline step executes and lane IDs must be unique across the pipeline; inheriting a step's lanes does not remove them. Pipeline-level inheritance with step upsert is suitable for full variants. Omitted fields inherit; explicit zero, false, and empty collections retain their presence. Null can clear an inherited value but remains subject to that field's type and fallback semantics. Omitting `extends` retains a lower relationship; `extends: null` cancels that relationship rather than independently deleting other composed fields. `extends` is a reserved native configuration key, not ordinary module-option data. See [native inheritance][inheritance] and [sequence composition][sequences] for full rules. Explicit configuration assignments use native mapping paths. They cannot walk sequence indexes, assign the version, or introduce inheritance controls. Mapping values overlay; list values replace the whole decoded list. Inheritance/defaulting does not run again afterward. [CLI Reference](cli.md#configuration-selection) owns assignment syntax. ## PromptKit Profiles Native `promptkit` settings contain identified `backends`, `profiles`, and `prompts` lists, plus a `collections` mapping. Notarius embeds its resources in `collections.notarius`. Runtime IDs are qualified, for example `notarius/dnd-extraction` and `notarius/dnd.spells`; the bundled root backend is `openrouter`. Resource IDs are literal, not resource-version paths. A collection's local record ID omits its namespace; references to resources in that collection use the qualified runtime ID. A wrapperless companion can add a profile variant: ~~~yaml collections: notarius: profiles: - id: campaign extends: {id: dnd-extraction} model: example-model ~~~ The pipeline can then select `llm_profile: notarius/campaign`. In the main application file, place that same mapping beneath `promptkit`. The parent reference is local to the same profile list; profile/backend references otherwise name their intended exact ID. The [complete companion](../examples/dnd-complete/prompts.yml) shows a runnable inherited backend/profile combination. Later same-ID resources replace complete lower records, not selected fields. Use a distinct inherited sibling to retain a parent's fields; replacing a record with only one changed field does not implicitly keep the old definition. Native `extends`, explicit null, list policy, and source contexts apply to resources just as to other configuration. See [resource inheritance][resource-inheritance]. The embedded D&D profile selects `openrouter`, model `openai/gpt-5.6-luna`, a `240` second timeout, and `flex` service tier, leaving reasoning unset. Initial/correction pairs share their bundled default profile. Explicit application profile selections and run overrides reach producers, validators, and correction requests; validators can otherwise select their own profile. A native backend supplies endpoint, credential-environment name, optional capacity/queue controls, provider parameters, and explicit smoke metadata. Profiles may supply backend or endpoint, model, sampling/token controls, timeout, service tier, reasoning, credential policy, and provider parameters. Partial profiles are valid; preparation must complete the actual target. Resource inspection is not a backend-completed or run-overridden target prediction. Notarius injects **no backend concurrency or queue defaults**. Native admission is shared by backend ID within the engine, independently of workers; distinct IDs do not automatically share capacity even if their endpoints match. An endpoint-only profile has no backend identity. Configure native backend limits when desired; the [upstream backend contract][backends] owns defaults and queue semantics. Profile omission, explicit values, and null differ. For example, native null `endpoint` or `api_key_env` permits backend fallback, while an explicitly empty string clears those sources; zero sampling values remain intentional. Blank/null reasoning suppresses the outbound control. Changing backend/model does not automatically clear unrelated explicit inherited settings. Use the [native defaults table][profile-defaults], not inferred old-wrapper behavior. Only credential environment **names** belong in files, never values. Native secret-aware inspection preserves marked secret omissions; arbitrary prompt, source, or extension data is not promised safe to disclose. ### Prompt Output Contracts And Schemas Prompt declarations select response format, validation mode, and schema. Bundled initial, correction, and validator prompts omit structural-repair counts: Notarius inherits the upstream default, not an independent application-pinned count. Native prompt customization can explicitly change that budget. Transient provider retries are also native, distinct from application semantic turns. See [native output contracts][output-contract]. Schemas may be inline, `schema_file` relative to its contributing source, or `schema_path` within an explicit applicable `schema_root`. Exactly one schema selection is used for JSON Schema mode. Null clears an alternative; switching forms can require clearing the inherited selection. Native preparation reads and compiles schemas; configuration/preflight does not read them. Embedded Notarius prompts use their collection's filesystem-rooted schemas. A nonnull collection root takes precedence over the root `promptkit.schema_root`; absent/null collection roots fall back to that application root. A nonnull blank root is invalid. Replacing `collections.notarius.schema_root` selects the new context for its remaining path-based schemas. A missing file does not fall back to embedded or working-directory roots. Other collections are unaffected. Schema resources must be self-contained; native schema rules are in [PromptKit's schema reference][schemas]. ## Concurrency, Output, Cache, And Debug `concurrency.workers` bounds active ready extraction and lane-completion jobs together, including their validation/correction. It must be positive, has no application maximum, and is independent of CPU count and native backend limits. Explicit `1` gives serial jobs. Waiting for prerequisites occupies no worker; nested validators do not request another worker. It is not a cross-backend provider-call ceiling. `output.directory`, `cache_directory`, and `debug.directory` select independent roots. `/var/cache/notarius` is the convention for an explicitly provisioned system-wide cache, not the per-user default. No directory setting creates a permission policy or retention service. A configured debug destination alone does not enable capture. Explicit empty disables it; a nonempty invocation override can re-enable it. Native debug selection and presentation modes are independent. See [CLI Reference](cli.md#run) for invocation controls and [Operations](operations.md) for state handling. ## Pipelines Each nonblank `pipelines` key defines a configured pipeline. | Field | Type | Default / rules | | --- | --- | --- | | `llm_profile` | string | Optional qualified profile selection; explicit blank/null is invalid. | | `mode` | `strict\|permissive` | Producer terminal mode; see below. | | `max_additional_turns` | nonnegative integer | Semantic correction allowance excluding the initial response. | | `cache` | `auto\|bypass\|refresh` | Eligible model-result reuse policy. | | `input` | binding | Required. | | `chunk` | binding | Defaults to `generic`. | | `output` | binding | Defaults to `json`. | | `artifacts` | lane map | Compact single-step form, mutually exclusive with `steps`. | | `steps` | ordered list | Nonempty when selected; each record has a unique nonblank `id`, `artifacts`, and optional `references`. | | `references` | map | External reference defaults for compatible targets. | A lane ID is unique across all steps. Each lane requires `extract`, defaults `merge` to `appendorder`, and defaults `normalize` to `noop`. References and validator overrides belong on eligible bindings, not lane-wide fields. Ordered steps finish before their generated artifacts feed later steps. For each selected LLM role, profile precedence is explicit invocation override, binding `llm_profile`, pipeline `llm_profile`, then native prompt default. Deterministic roles do not receive LLM defaults/overrides and reject explicit profile assignments. A supplied empty invocation profile clears the application selection and lets the prompt default apply; configured blank profiles are invalid. ### Producer Controls Chunk, extract, merge, and normalize bindings resolve controls before execution: | Control | Precedence, highest first | Default | | --- | --- | --- | | `mode` | Binding, pipeline, application | `strict` | | `max_additional_turns` | Binding, pipeline, application | `2` | | `cache` | Explicit invocation cache, binding, pipeline, application | `auto` | Omission inherits. Zero turns disables semantic correction; a positive allowance is not a requirement to use every turn. The complete applicable validator chain assesses each usable initial/revised candidate, including the final permitted response. Native coordination owns conversation/iteration; the allowance does not count transport retries or structural repair. Deterministic work does not acquire conversations or generic retries. Strict requires an accepted result. Permissive explicitly permits only the module's supported fallback, with intrinsic shape/source/downstream checks, without claiming ordinary semantic approval or rerunning the normal chain. A whole-source D&D scene plan, empty extraction collection where valid, or safe final normalization groups/merged input are supported directions. Scene descriptions cannot use an invalid empty collection or fabricated description. Unsupported fallback construction fails; cancellation stops without fallback. Eligible cacheable work uses `auto` to read/store accepted results, `bypass` for neither, and `refresh` to skip reads and replace only after new acceptance. Failures preserve earlier acceptance. Fallback and actually affected dependent work skip both lookup and storage; unrelated predecessors remain reusable. Settings/policy changes may still reuse old accepted content; select bypass/ refresh when deliberately applying changed policy. Best-effort cache I/O does not fail otherwise successful work. [Operations](operations.md) owns recovery and physical storage, not a checkpoint/resume contract. ## Module Bindings And Validators Every module binding is an object containing `module`, even without options. | Binding field | Meaning | | --- | --- | | `module` | Registered compatible key; required. | | `llm_profile` | Optional nonblank qualified profile for an LLM-backed role. | | `mode`, `max_additional_turns`, `cache` | Resolved producer controls above. | | `options` | Selected module's strict option object. | | `references` | Declared slots on chunk/extract/merge/normalize bindings. | | `validators` | Ordered replacement chain on those producer bindings. | Omitted validators use the production default. `validators: []` replaces it with an empty chain; a nonempty list replaces it in listed order. Null is not an empty list. Validator bindings accept only `module`, optional LLM-backed `llm_profile`, and `options`; they have no separate producer mode, semantic-turn allowance, references, or nested validators. Each validator executes once per candidate assessment. Intrinsic codec/schema checks remain with an empty chain, as do source parsing, plan materialization, and necessary module/fallback/cache construction checks. Ordinary artifact citation existence/containment checks are supplied by configured validators and can be omitted by chain replacement. See [default chains](#production-validator-keys-and-default-chains). The `json` output options are: | Option | Default / rules | | --- | --- | | `include_chunk_map` | Boolean, default false; publish when enabled and available. | | `evidence_context` | Omitted disables publication; otherwise a strict object. | | `evidence_context.enabled` | Required boolean; false permits no other evidence fields. | | `evidence_context.lanes` | When enabled, required nonempty list of unique trimmed configured lane IDs. | | `evidence_context.window_units` | When enabled, nonnegative integer, default `3`; zero keeps only directly cited units. | Filtered-out configured lanes contribute no evidence. Unknown or incompatible options fail. Evidence is opt-in because it can persist source text and metadata. Logical formats belong to [chunk-map](integrations/chunk-map.md) and [evidence-context](integrations/evidence-context.md) contracts. ## References And Ordered Handoffs Reference maps bind named slots that the selected target declares. An external reference is an object with `path`. Pipeline-level maps accept only external paths; step-local and binding-local maps may also select a normalized artifact from an earlier step: ~~~yaml steps: - id: describe-session artifacts: npc-registry: extract: module: dnd/npc-registry normalize: module: dnd/npc-registry - id: extract-events references: npc_registry: artifact: step: describe-session lane: npc-registry artifacts: spells: extract: module: dnd/spells normalize: module: dnd/spells ~~~ An artifact selector contains only **step** and **lane**. The producer must be an earlier step and the selected artifact must be compatible with the consumer slot. A generated binding supplies one normalized artifact in memory, including a supported qualified fallback; it does not name a file. A configured generated dependency remains required even when that consumer slot is otherwise optional. Pipeline references are configuration defaults. A matching step-local or binding-local external path overrides a pipeline default. CLI reference bindings are then operational overrides of configured external paths; their pipeline, lane, and binding scopes and precedence are defined by the [CLI reference](cli.md#reference-selectors). A CLI file reference cannot replace a configured generated artifact handoff. Required slots must be bound after configuration and CLI reference actions are applied. A YAML reference path resolves from the file that supplies its surviving declaration, including an imported fragment or selected overlay. CLI reference paths resolve relative to the process working directory. ### D&D Reference Slots The following slot names are accepted by the implemented D&D modules when the selected target declares them: | Slot | Source and use | | --- | --- | | **party** | Optional text campaign context. This is the canonical party-roster spelling. | | **roster** | Accepted compatibility alias for **party**. | | **players** | Optional text player context. | | **glossary** | Optional text campaign glossary. | | **spell_catalog** | Optional JSON spell-catalog overlay for spell extraction and normalization. See [spell-catalog overlays](integrations/dnd-spell-catalog-overlays.md). | | **location_registry** | Required normalized location registry for location-occurrence extraction and normalization. | | **item_registry** | Required normalized item registry for item-occurrence extraction and normalization. | | **npc_registry** | Normalized NPC registry. Optional for spells and combat turns; required for NPC occurrences and enemy-event extraction and normalization. | | **scene_descriptions** | Required normalized scene-description artifact for combat-turn and enemy-event extraction. | | **combat_turns** | Required normalized combat-turn artifact for enemy-event extraction. | | **npc_occurrences** | Required normalized NPC-occurrence artifact for enemy-event extraction. | Registry-backed occurrence and enemy-event artifact slots have the following exact binding contracts. Durable semantics and wire shapes remain in their [NPC occurrence](integrations/dnd-npc-occurrence-artifacts.md), [location occurrence](integrations/dnd-location-occurrence-artifacts.md), [item occurrence](integrations/dnd-item-occurrence-artifacts.md), and [enemy-event](integrations/dnd-enemy-event-artifacts.md) contracts. | Slot | Accepted artifact kind | Media type | Maximum size | Required stage | | --- | --- | --- | --- | --- | | `npc_registry` | `dnd/npc-registry` | `application/json` | 1,048,576 bytes | extract and normalize | | `scene_descriptions` | `dnd/scene-description-list` | `application/json` | 1,048,576 bytes | extract only | | `combat_turns` | `dnd/combat-turn-list` | `application/json` | 1,048,576 bytes | extract only | | `npc_occurrences` | `dnd/npc-occurrence-list` | `application/json` | 1,048,576 bytes | extract only | | `location_registry` | `dnd/location-registry` | `application/json` | 1,048,576 bytes | location-occurrence extract and normalize | | `item_registry` | `dnd/item-registry` | `application/json` | 1,048,576 bytes | item-occurrence extract and normalize | Scene descriptions accept **party**, **players**, and **glossary**, but not **roster**. NPC occurrences require **npc_registry** for both extraction and normalization. Combat turns require **scene_descriptions** for extraction; the normalized combat-turn module may use optional **npc_registry**. Location occurrences require **location_registry** for extraction and normalization. Item occurrences require **item_registry** for extraction and normalization. Enemy-event extraction requires all four of its JSON artifact slots; its normalizer requires **npc_registry**. The [complete example](../examples/dnd-complete/config.yml) shows the ordered generated bindings. ## Production Module Keys | Kind | Keys | | --- | --- | | Input | **seriatim** | | Chunk | **generic**, **dnd/scenes** | | Extract | **dnd/spells**, **dnd/npc-registry**, **dnd/combat-turns**, **dnd/item-occurrences**, **dnd/item-registry**, **dnd/npc-occurrences**, **dnd/scene-descriptions**, **dnd/enemy-events**, **dnd/location-registry**, **dnd/location-occurrences** | | Merge | **appendorder** | | Normalize | **noop**, **dnd/spells**, **dnd/npc-registry**, **dnd/combat-turns**, **dnd/item-occurrences**, **dnd/item-registry**, **dnd/npc-occurrences**, **dnd/scene-descriptions**, **dnd/enemy-events**, **dnd/location-registry**, **dnd/location-occurrences** | | Output | **json** | `dnd/scenes` and every D&D extractor are `llm_backed`. The `dnd/npc-registry`, `dnd/location-registry`, and `dnd/item-registry` normalizers are also `llm_backed` for bounded duplicate proposals; every other D&D normalizer is `deterministic`. LLM-backed bindings use the effective [PromptKit profile](#promptkit-profiles). The complete example binds each registry in an earlier step before its occurrence consumer. The D&D artifact contracts define each emitted schema: [spells](integrations/dnd-spell-artifacts.md), [NPC registry](integrations/dnd-npc-registry-artifacts.md), [NPC occurrences](integrations/dnd-npc-occurrence-artifacts.md), [combat turns](integrations/dnd-combat-turn-artifacts.md), [item registry](integrations/dnd-item-registry-artifacts.md), [item occurrences](integrations/dnd-item-occurrence-artifacts.md), [scene descriptions](integrations/dnd-scene-description-artifacts.md), [enemy events](integrations/dnd-enemy-event-artifacts.md), [location registry](integrations/dnd-location-registry-artifacts.md), and [location occurrences](integrations/dnd-location-occurrence-artifacts.md). ## Production Validator Keys And Default Chains Available validator keys are: | Family | Keys | | --- | --- | | Generic | **generic/always_accept**, **generic/always_reject**, **generic/valid_json**, **generic/valid_json_schema** | | Spells | **extract/dnd/spells/shape**, **extract/dnd/spells/catalog**, **extract/dnd/spells/source_refs**, **extract/dnd/spells/source_relatedness** | | NPC registry | **extract/dnd/npc-registry/shape**, **extract/dnd/npc-registry/source_refs**, **extract/dnd/npc-registry/source_relatedness**, **normalize/dnd/npc-registry/identity** | | Combat turns | **extract/dnd/combat-turns/shape**, **extract/dnd/combat-turns/source_refs**, **extract/dnd/combat-turns/source_relatedness**, **normalize/dnd/combat-turns/invariants** | | Item occurrences | **extract/dnd/item-occurrences/shape**, **extract/dnd/item-occurrences/registry**, **extract/dnd/item-occurrences/source_refs**, **extract/dnd/item-occurrences/source_relatedness**, **normalize/dnd/item-occurrences/invariants** | | Item registry | **extract/dnd/item-registry/shape**, **extract/dnd/item-registry/source_refs**, **extract/dnd/item-registry/source_relatedness**, **normalize/dnd/item-registry/identity** | | NPC occurrences | **extract/dnd/npc-occurrences/shape**, **extract/dnd/npc-occurrences/registry**, **extract/dnd/npc-occurrences/source_refs**, **extract/dnd/npc-occurrences/source_relatedness**, **normalize/dnd/npc-occurrences/invariants** | | Scene descriptions | **extract/dnd/scene-descriptions/shape**, **extract/dnd/scene-descriptions/source_refs**, **extract/dnd/scene-descriptions/source_relatedness**, **extract/dnd/scene-descriptions/combat_semantics** (LLM-backed, opt-in), **normalize/dnd/scene-descriptions/invariants** | | Enemy events | **extract/dnd/enemy-events/shape**, **extract/dnd/enemy-events/engagements**, **extract/dnd/enemy-events/source_refs**, **extract/dnd/enemy-events/source_relatedness**, **normalize/dnd/enemy-events/invariants** | | Location registry | **extract/dnd/location-registry/shape**, **extract/dnd/location-registry/source_refs**, **extract/dnd/location-registry/source_relatedness**, **normalize/dnd/location-registry/identity** | | Location occurrences | **extract/dnd/location-occurrences/shape**, **extract/dnd/location-occurrences/registry**, **extract/dnd/location-occurrences/source_refs**, **extract/dnd/location-occurrences/source_relatedness**, **normalize/dnd/location-occurrences/invariants** | `extract/dnd/scene-descriptions/combat_semantics` is not in a production default chain. To opt in, replace the scene extractor validator chain with the current ordered chain plus the semantic validator last, and retain a positive semantic-turn allowance if a rejection should request a corrected scene: ~~~yaml extract: module: dnd/scene-descriptions max_additional_turns: 1 validators: - module: generic/valid_json - module: extract/dnd/scene-descriptions/shape - module: extract/dnd/scene-descriptions/source_refs - module: generic/valid_json_schema - module: extract/dnd/scene-descriptions/source_relatedness - module: extract/dnd/scene-descriptions/combat_semantics ~~~ An override replaces, rather than extends, the default chain. See [Module Bindings And Validators](#module-bindings-and-validators) for binding and profile rules, and [producer controls](#producer-controls) for semantic correction and terminal mode. The validator runs once per candidate assessment. Native transient retries and structural repair remain internal to that execution; there is no separate validator semantic-turn allowance. When no override is configured, production D&D bindings use the following ordered chains. Each row lists extract then normalize; spell chains are the same at both stages. | Lane | Extract | Normalize | | --- | --- | --- | | Spells | generic/valid_json, extract/dnd/spells/shape, extract/dnd/spells/catalog, extract/dnd/spells/source_refs, generic/valid_json_schema, extract/dnd/spells/source_relatedness | Same as extract | | NPC registry | generic/valid_json, extract/dnd/npc-registry/shape, extract/dnd/npc-registry/source_refs, generic/valid_json_schema, extract/dnd/npc-registry/source_relatedness | generic/valid_json, extract/dnd/npc-registry/shape, normalize/dnd/npc-registry/identity, extract/dnd/npc-registry/source_refs, generic/valid_json_schema, extract/dnd/npc-registry/source_relatedness | | Combat turns | generic/valid_json, extract/dnd/combat-turns/shape, extract/dnd/combat-turns/source_refs, generic/valid_json_schema, extract/dnd/combat-turns/source_relatedness | generic/valid_json, extract/dnd/combat-turns/shape, normalize/dnd/combat-turns/invariants, extract/dnd/combat-turns/source_refs, generic/valid_json_schema, extract/dnd/combat-turns/source_relatedness | | Item occurrences | generic/valid_json, extract/dnd/item-occurrences/shape, extract/dnd/item-occurrences/registry, extract/dnd/item-occurrences/source_refs, generic/valid_json_schema, extract/dnd/item-occurrences/source_relatedness | generic/valid_json, extract/dnd/item-occurrences/shape, extract/dnd/item-occurrences/registry, normalize/dnd/item-occurrences/invariants, extract/dnd/item-occurrences/source_refs, generic/valid_json_schema, extract/dnd/item-occurrences/source_relatedness | | Item registry | generic/valid_json, extract/dnd/item-registry/shape, extract/dnd/item-registry/source_refs, generic/valid_json_schema, extract/dnd/item-registry/source_relatedness | generic/valid_json, extract/dnd/item-registry/shape, normalize/dnd/item-registry/identity, extract/dnd/item-registry/source_refs, generic/valid_json_schema, extract/dnd/item-registry/source_relatedness | | NPC occurrences | generic/valid_json, extract/dnd/npc-occurrences/shape, extract/dnd/npc-occurrences/registry, extract/dnd/npc-occurrences/source_refs, generic/valid_json_schema, extract/dnd/npc-occurrences/source_relatedness | generic/valid_json, extract/dnd/npc-occurrences/shape, extract/dnd/npc-occurrences/registry, normalize/dnd/npc-occurrences/invariants, extract/dnd/npc-occurrences/source_refs, generic/valid_json_schema, extract/dnd/npc-occurrences/source_relatedness | | Scene descriptions | generic/valid_json, extract/dnd/scene-descriptions/shape, extract/dnd/scene-descriptions/source_refs, generic/valid_json_schema, extract/dnd/scene-descriptions/source_relatedness | generic/valid_json, extract/dnd/scene-descriptions/shape, normalize/dnd/scene-descriptions/invariants, extract/dnd/scene-descriptions/source_refs, generic/valid_json_schema, extract/dnd/scene-descriptions/source_relatedness | | Enemy events | generic/valid_json, extract/dnd/enemy-events/shape, extract/dnd/enemy-events/engagements, extract/dnd/enemy-events/source_refs, generic/valid_json_schema, extract/dnd/enemy-events/source_relatedness | generic/valid_json, extract/dnd/enemy-events/shape, normalize/dnd/enemy-events/invariants, extract/dnd/enemy-events/source_refs, generic/valid_json_schema, extract/dnd/enemy-events/source_relatedness | | Location registry | generic/valid_json, extract/dnd/location-registry/shape, extract/dnd/location-registry/source_refs, generic/valid_json_schema, extract/dnd/location-registry/source_relatedness | generic/valid_json, extract/dnd/location-registry/shape, normalize/dnd/location-registry/identity, extract/dnd/location-registry/source_refs, generic/valid_json_schema, extract/dnd/location-registry/source_relatedness | | Location occurrences | generic/valid_json, extract/dnd/location-occurrences/shape, extract/dnd/location-occurrences/registry, extract/dnd/location-occurrences/source_refs, generic/valid_json_schema, extract/dnd/location-occurrences/source_relatedness | generic/valid_json, extract/dnd/location-occurrences/shape, extract/dnd/location-occurrences/registry, normalize/dnd/location-occurrences/invariants, extract/dnd/location-occurrences/source_refs, generic/valid_json_schema, extract/dnd/location-occurrences/source_relatedness | Chains are only registered for the D&D extract and normalize modules shown above; select an explicit override when a different compatible chain is required. ## Validation And Inspection Configuration validation checks the selected native application document. Pipeline validation additionally resolves production modules/options, validator targets, references, generated handoffs, and statically known prompt/profile dependencies. It needs no transcript, reference bytes, credential values, provider calls, or state directories. Partial profiles pass; request-time data and dynamic selections remain runtime checks. [CLI Reference](cli.md#pipeline-commands) owns commands for both boundaries. Native whole-app and focused PromptKit inspection use the same selected result and secret-aware provenance. Profile inspection describes stored fields, not a prediction of a completed request; prepared preview is the native request boundary. See [configuration commands](cli.md#configuration-commands) and [PromptKit commands](cli.md#promptkit-commands). [formats]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md [backends]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md#backend-definitions [profile-defaults]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md#defaults-and-overrides [resource-inheritance]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md#resource-inheritance [output-contract]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md#output-contract [schemas]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md#schemas [imports]: https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/config.md#explicit-imports [overlays]: https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/config.md#selected-overlays [inheritance]: https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/config.md#sibling-inheritance [sequences]: https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/config.md#strict-document-composition