Document native application configuration adoption

This commit is contained in:
2026-11-17 22:15:10 +00:00
parent 79dfe0a3ef
commit 2c3d8e4c8b
11 changed files with 118 additions and 67 deletions

View File

@@ -10,35 +10,39 @@ outcomes, see the [HTTP API reference](api.md). For migration examples, see
## Discovery And Precedence
Application settings are resolved in this order:
1. built-in Scriptorium defaults;
2. a configuration file; then
3. CLI overrides.
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`.
If neither exists, it uses built-in defaults. An explicit `--config` path must
exist and decode successfully.
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), and
[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
Configuration is decoded by ConfigKit v0.5.0 as strict YAML. Unknown fields,
empty files, multiple YAML documents, and YAML aliases/anchors are rejected.
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.
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
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.
@@ -69,28 +73,43 @@ 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.
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
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.
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. 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.
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
@@ -107,6 +126,16 @@ go run ./cmd/scriptorium render \
--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