scriptorium/docs/config.md

# Configuration Reference

This is the canonical reference for Scriptorium application settings. Prompt,
profile, schema, execution-setting, built-in profile, and framework credential
semantics are defined by the
[Promptkit v0.11.2 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/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).

## 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), and
[composed configuration](../examples/config.composed.yml) are copyable examples.

## Application Configuration File

Configuration is decoded by ConfigKit v0.4.2 as strict YAML. Unknown fields,
empty files, multiple YAML documents, and YAML aliases/anchors are rejected.
An explicit empty string is a value: it clears a file-provided optional path
or, for required `prompt_dir`, fails the command's prerequisite. A scalar
`null` is not an empty string and is rejected for scalar fields; nullable
fields such as `transient_retries` retain their documented meaning. Raw
API-key fields are not accepted.

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.

### 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 two fragments
and has a selectable [local overlay](../examples/overlays/local.yml). 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 `prompt_dir` remain relative
to the process working directory even when authored in a fragment or overlay.
These source constraints are separate from HTTP artifact containment.

| Field | Default | Meaning |
| --- | --- | --- |
| `prompt_dir` | unset | Promptkit prompt-definition source directory. `run`, `render`, `serve`, and `inspect prompt` require an effective value. |
| `profile_dir` | unset | Optional custom Promptkit profile source directory overlaid on Promptkit built-ins. |
| `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`. |
| `backends` | unset | Optional mapping of custom Promptkit backend IDs to engine-scoped connection and capacity settings. |
| `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. `api_key_env` is an environment-variable *name* and remains
visible in inspection; its environment value is never read by ConfigKit.
Ordinary backend `extra_params` values also remain visible, so keep secrets out
of those fields and protect inspection output as potentially sensitive.
`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. Neither renderer looks up credential bytes, and neither
claims to identify arbitrary secrets in unclassified parameter values.

## Custom Backends

Use `backends` when a profile selects an application-defined backend ID:

```yaml
backends:
  local-gpu:
    endpoint: http://localhost:11434/v1
    api_key_env: LOCAL_GPU_API_KEY
    extra_params:
      provider_option: enabled
    concurrency_limit: 2
    queue_capacity: 0
```

Each mapping key is the case-sensitive backend ID. `endpoint` is required;
`api_key_env`, `extra_params`, `concurrency_limit`, and `queue_capacity` are
optional. `concurrency_limit: 0` leaves the backend unlimited. Omitting
`queue_capacity` lets Promptkit use its default for a limited backend, while
an explicit `queue_capacity: 0` disables queueing.

Configuration strictly owns the YAML shape and rejects unknown fields. Promptkit
validates backend IDs, endpoints, environment-variable names, extra parameters,
and capacity relationships when Scriptorium constructs its engine. There are no
backend command-line overrides. Store only an environment-variable name in
`api_key_env`; raw API-key fields are not accepted.

## Framework Source Mapping

Scriptorium passes `prompt_dir`, `profile_dir`, and `schema_dir` to Promptkit
when constructing its engine. Scriptorium does not redefine or independently
parse those 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.11.2/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 custom profile 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.11.2/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.11.2/docs/formats.md)