eric/scriptorium
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 9 Wiki Activity

Enable explicit configuration imports and overlays

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-26 18:12:27 +00:00
parent 36e7e857f5
commit 9ac7006a79
15 changed files with 204 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
docs/config.md
View File

@@ -20,8 +20,9 @@ When `--config` is omitted, Scriptorium searches
If neither exists, it uses built-in defaults. An explicit `--config` path must
exist and decode successfully.
The maintained [minimal configuration](../examples/config.yml) and
[complete configuration](../examples/config.full.yml) are copyable examples.
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
@@ -31,8 +32,7 @@ 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. Imports and selected overlays are not yet
enabled for application configuration.
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
@@ -40,6 +40,43 @@ 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. |