# Configuration Reference This is the canonical reference for Scriptorium application settings. Prompt, profile, backend, schema, execution-setting, built-in profile, and framework credential semantics are defined by the [Promptkit v0.12.0 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md). For command syntax, see the [CLI reference](cli.md); for HTTP request shapes and outcomes, see the [HTTP API reference](api.md). For migration examples, see [Upgrading Promptkit sources and definitions](consumers/upgrading-promptkit.md). ## Discovery And Precedence ConfigKit assembles the selected main source, imports, and overlay, resolves inheritance, and decodes the result with Scriptorium's typed defaults. It then applies explicitly supplied application CLI values, records application normalization, and validates the result. Source, composition, inheritance, and decoding failures happen before CLI assignment and cannot be repaired by it; an override can correct a decoded value before application validation. When `--config` is omitted, Scriptorium searches `/usr/local/etc/scriptorium/config.yml` and then `/etc/scriptorium/config.yml`. ConfigKit performs this ordered search for each load. If neither exists, it uses built-in defaults; an error in a selected candidate does not cause a fallback. An explicit `--config` path must exist and decode successfully, including when an empty path is explicitly supplied. The maintained [minimal configuration](../examples/config.yml), [complete configuration](../examples/config.full.yml), [composed configuration](../examples/config.composed.yml), [collection configuration](../examples/config.collections.yml), and [framework inheritance configuration](../examples/config.inheritance.yml) are copyable examples. ## Application Configuration File Application configuration is decoded by ConfigKit v1.2.0 as strict YAML. Unknown fields, empty files, multiple YAML documents, and YAML aliases/anchors are rejected. An explicit empty string is a value and may clear a file-provided optional string. A scalar `null` is not an empty string and is rejected for non-nullable fields; nullable fields such as `transient_retries` retain their documented meaning. Raw API-key fields and unknown application fields are rejected. Only explicitly supplied application CLI flags override decoded settings. Paths in the application document remain relative to the process working directory, not to the file's directory. Load diagnostics are printed safely on stderr; invalid application configuration exits with status 1. ### Promptkit source selectors `promptkit_sources` is an ordered sequence of explicit Promptkit source selectors. Each item must set exactly one of `file` or `directory`: ```yaml promptkit_sources: - directory: ./examples/prompts - directory: ./examples/profiles - file: ./examples/framework/backends.yml schema_dir: ./examples/schemas ``` Omitting the field or setting it to `[]` (or `null`) selects no application-supplied framework sources; Promptkit's selected catalog and maintained definitions still apply. A later sequence item overlays an earlier one. Files within a selected directory are composed together, so conflicting definitions in that group fail instead of using filename order as precedence. An explicit file may use ConfigKit imports. The complete framework format and source rules belong to the [Promptkit v0.12.0 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md). Selector paths are relative to the process working directory, not to the application configuration file. Application validation checks the selector shape but does not open or validate Promptkit sources. `config validate` therefore does not prove that selected sources can build an engine; use `inspect configuration validate` for that separate check. Repeated `--promptkit-source` flags replace the entire configured selector sequence and preserve flag order. Without an authored collection policy, a selected overlay replaces `promptkit_sources` as a whole; a declared sequence policy may instead combine the lists. ### Explicit imports and selected overlays Application files declare imports under root `config.imports`. Native `path`, `dir`, and `glob` selectors, filters, recursion, destinations, and item placement are available as described in the [pinned ConfigKit contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/config.md). Imports are optional by default; set `required: true` when absence must fail. The old `optional` field is not supported. Directory selection has no default filename filter; author a pattern when only YAML files are intended. ConfigKit composes peer sources strictly, rather than using filename order to resolve conflicts. Imports are resolved relative to their declaring file within the native source root. Scriptorium does not widen that root. Root `config.sequences` can declare an identity key and merge mode for a collection. Scriptorium does not register or infer an identity for `promptkit_sources`: absent an authored policy, unkeyed lists replace across precedence boundaries. The [collection example](../examples/config.collections.yml) declares `file` identity with `upsert`, combines imported file selectors, and lets an overlay add another. CLI list overrides still replace the whole list. These application root `config` controls do not change the separate Promptkit v0.12.0 framework format: its selected framework files use the [Promptkit contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md) and its older ConfigKit controls. `--config-overlay NAME` selects one file at `overlays/NAME.yml` below that root. The name must use letters, digits, `_`, or `-`; it is not a path. Empty and exact lowercase `default` select no overlay. There is no fallback, case folding, inherited stack, or automatic selection; a missing selected overlay fails. Mappings merge and explicit nulls replace; sequence behavior depends on any authored collection policy. Defaults-only loading can enable imports, but an absent main has no import declarations. This CLI supplies no independent overlay root, so an active overlay cannot be located without a selected main context. That is not a general ConfigKit restriction. The [composed example](../examples/config.composed.yml) imports the application [source-selection fragment](../examples/config-fragments/sources.yml) and has a selectable [local overlay](../examples/overlays/local.yml). That fragment selects the [framework backend file](../examples/framework/backends.yml) through `promptkit_sources`; backend definitions are not imported into the application document. From the repository root: ```bash go run ./cmd/scriptorium render \ --config ./examples/config.composed.yml --config-overlay local \ --prompt generic.markdown_summary \ --input transcript=./examples/fixtures/transcript.md \ --input glossary=./examples/fixtures/glossary.yml ``` Inspect the collection overlay and render without contacting a provider: ```bash go run ./cmd/scriptorium config show --config ./examples/config.collections.yml --config-overlay collection go run ./cmd/scriptorium render --config ./examples/config.collections.yml --config-overlay collection \ --prompt generic.markdown_summary \ --input transcript=./examples/fixtures/transcript.md \ --input glossary=./examples/fixtures/glossary.yml ``` Import and overlay file locations are constrained by ConfigKit; application path values such as `promptkit_sources`, `schema_dir`, and `server.artifact_root` remain relative to the process working directory even when authored in a fragment or overlay. These source constraints are separate from Promptkit message-resource paths and HTTP artifact containment. | Field | Default | Meaning | | --- | --- | --- | | `promptkit_sources` | empty sequence | Ordered file/directory sources for Promptkit backends, profiles, and prompts. | | `schema_dir` | `.` | Promptkit schema source directory for relative schema paths. | | `server.addr` | `:8080` | Address used by `serve`. | | `server.artifact_root` | unset | Root that enables HTTP `file` input references. | | `server.max_request_bytes` | `16777216` | Maximum encoded HTTP request-body bytes; `0` disables the limit. | | `server.max_artifact_bytes` | `16777216` | Maximum HTTP file-input artifact bytes; `0` disables the limit. | | `server.max_response_bytes` | `16777216` | Maximum encoded HTTP response bytes; `0` disables the limit. | | `defaults.render_format` | `text` | Default prepared-run output format: `text` or `json`. | | `transient_retries` | Promptkit default | Optional nonnegative count of additional built-in transient generation attempts. Omitted or `null` delegates to Promptkit; `0` disables additional attempts. | The size fields must be zero or greater. The [HTTP API](api.md) defines how each limit is enforced and reported. `server.artifact_root` configures an HTTP deployment boundary; see [operations](operations.md) for deployment handling. The `config validate`, `config show`, `config sources`, and `config explain` commands inspect this application configuration without creating a Promptkit engine. `show` is a resolved inspection snapshot, not necessarily a reloadable file. Application validation does not check framework sources, backend connectivity, or credential availability. Use `inspect configuration` for Promptkit's separately captured framework configuration; its four operations are documented in the [CLI reference](cli.md#framework-configuration-inspection). `config explain --path /server/addr` uses JSON Pointer syntax to show the selected field's current value and history from defaults, files, overlays, explicit CLI overrides, and normalization. `--path ''` selects the root. History includes replaced and removed values; `show` presents the final resolved snapshot. The application schema rejects raw credential fields, but do not treat inspection as a general-purpose filter for sensitive strings. ## Framework Source Mapping Scriptorium assembles selected Promptkit source files and directories in the order described above, then constructs the Promptkit engine. Framework definitions and custom backends belong in those selected source files, not in the Scriptorium application configuration. Message `content_file` paths use the defining source's resource context and are captured when the engine is constructed; schema and request-artifact loading remain preparation-time operations. Scriptorium does not redefine or independently parse framework file formats. - Prompt selection, versions, message templates, inputs, output contracts, and session IDs are Promptkit contracts. - Profile fields, numeric ranges, execution defaults, overlay precedence, built-in profiles, and credential rules are Promptkit contracts. - Schema path behavior and generated-content validation are Promptkit contracts. See the [tagged Promptkit format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md) for all of those definitions. The files under [`examples/prompts`](../examples/prompts/), [`examples/profiles`](../examples/profiles/), and [`examples/schemas`](../examples/schemas/) are maintained Scriptorium application inputs using that tagged format. Promptkit supplies the opt-in profile IDs `promptkit-openrouter-standard` and `promptkit-openrouter-auto`. They can be selected as a prompt default or request profile, and selected application sources retain precedence. Their effective model settings may change with a catalog upgrade; use a complete application-owned profile when fixed settings are required. See the tagged format reference for the maintained-profile contract. ## Credentials And Outbound Behavior Scriptorium maps `--api-key-env` and HTTP `model.api_key_env` into Promptkit request overrides. Keep secret values in environment variables and store only their names in configuration or framework source files. Do not place raw keys in configuration, prompts, profiles, CLI arguments, examples, or HTTP payloads. An optional `api_key_env` whose environment value is absent or empty can result in an unauthenticated provider request. A profile that declares credentials required still fails as an invalid request when no credential source is selected, and fails with `ErrAPIKeyEnvMissing` when its selected environment source is absent or empty. Scriptorium never reads or emits the environment value itself. Unset optional provider controls are omitted from compatible provider requests. A positive Promptkit `repair_attempts` budget can add provider calls, latency, token use, and cost; see the tagged format reference for its permitted values and validation-mode requirements. Promptkit's built-in client makes up to two additional attempts for eligible transient HTTP statuses by default. The application `transient_retries` setting changes that budget for its constructed engine; an explicit `run` request override takes precedence. This can increase latency, request count, and cost. Each initial or repair generation has its own transient budget; an injected client retains its own retry behavior. The tagged integration contract owns eligibility and timing. Promptkit's [OpenAI-compatible integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/integrations/openai-compatible-chat.md) defines outbound authentication, provider request mapping, transport limits, and timeout layering. ## Related References - [CLI reference](cli.md) - [HTTP API reference](api.md) - [Operations guide](operations.md) - [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md)