# 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 Application settings are resolved in this order: 1. built-in Scriptorium defaults; 2. a configuration file; then 3. CLI overrides. When `--config` is omitted, Scriptorium searches `/usr/local/etc/scriptorium/config.yml` and then `/etc/scriptorium/config.yml`. If neither exists, it uses built-in defaults. An explicit `--config` path must exist and decode successfully. The maintained [minimal configuration](../examples/config.yml), [complete configuration](../examples/config.full.yml), [composed configuration](../examples/config.composed.yml), and [framework inheritance configuration](../examples/config.inheritance.yml) are copyable examples. ## Application Configuration File Configuration is decoded by ConfigKit v0.5.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. ConfigKit applies defaults, the selected file, then only explicitly supplied application CLI flags before validating the result. 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. A selected application overlay that defines `promptkit_sources` replaces the prior sequence as a whole. ### Explicit imports and selected overlays A file-backed configuration may declare `configkit.imports` with relative `path` or `glob` entries. Each entry is explicit; Scriptorium does not scan for fragments on its own. ConfigKit composes the selected file and imports by conflict, so two fragments cannot define the same field merely to establish precedence. A required missing import fails; an entry may use `optional: true` to suppress target nonexistence. Imports are resolved from the declaring file's canonical directory and remain within the selected file's canonical directory by default. Scriptorium does not widen that root. `--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. ConfigKit merges mapping fields and replaces other values, including sequences and explicit nulls, before applying explicit CLI flags. An active overlay needs a selected base file. No-source defaults-only loads cannot use imports or an active overlay. 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 ``` 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)