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

@@ -35,7 +35,7 @@ All command families accept `--config <path>` and `--config-overlay <name>`;
positional arguments are rejected. `--config-overlay` selects one application
configuration overlay; it is separate from `--profile`, which selects a
Promptkit execution profile. See [configuration composition](config.md#explicit-imports-and-selected-overlays)
for name, root, and no-base behavior. `run`, `render`, `serve`, `inspect prompt`,
for name, root, and absent-main behavior. `run`, `render`, `serve`, `inspect prompt`,
`inspect profile`, and `inspect configuration` accept repeated
`--promptkit-source <path>` flags and `--schema-dir <dir>` where applicable.
They replace the configured source sequence in flag order. `--prompt-dir` and
@@ -254,7 +254,8 @@ loaded and passed its own validation. It does not establish that selected
Promptkit sources can construct an engine, credentials are present, or a
provider is available. `show` writes ConfigKit's resolved YAML snapshot. `sources`
writes one newline-terminated JSON array of source records in load order. Each
record has `id`, `label`, and `layer`, plus `path` when available; explicit CLI
record has `id`, `label`, and `layer`, plus `path` when available. Application
main-file and import records use the `main` layer; explicit CLI
overrides appear as synthetic sources. Defaults-only input without overrides
produces `[]` for `sources`.

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

View File

@@ -4,8 +4,8 @@ This is the contributor entry point for Scriptorium. Scriptorium is an
application that consumes the public
[Promptkit v0.12.0 package](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md);
framework implementation work belongs in Promptkit. Application configuration
uses ConfigKit v0.5.0; keep Scriptorium's schema and source selection local.
Promptkit also uses ConfigKit to load framework sources under Promptkit's own
uses ConfigKit v1.2.0; keep Scriptorium's schema and source selection local.
Promptkit uses ConfigKit v0.5.0 to load framework sources under its own
schema and format contract.
## Initial Orientation
@@ -63,10 +63,9 @@ Promptkit source, or an import of a Promptkit `internal` package.
## Baseline Validation
The Go consumer minimum is the version declared in `go.mod`, currently 1.25.5.
It is the minimum toolchain for building Scriptorium from source; the selected
Promptkit v0.12.0 dependency requires that patch level. Running a published
binary does not require a Go installation. Release validation and builds use
The Go consumer minimum is the version declared in `go.mod`, currently 1.27.0,
required by application ConfigKit v1.2.0. Running a published binary does not
require a Go installation. Release validation and builds use
the separately selected toolchain in the [release procedure](release.md).
For code changes, run:

View File

@@ -20,10 +20,11 @@ described by its tagged
exposes application and captured framework configuration inspection, and
owns output files, summaries, and exit codes.
- `internal/config` delegates application YAML decoding, default resolution,
overrides, and validation ordering to ConfigKit. The CLI supplies only
overrides, and validation ordering to ConfigKit v1.2.0. The CLI supplies only
explicitly visited application flags as overrides and renders safe structured
load diagnostics on stderr. Promptkit uses ConfigKit to load framework
sources under its own definition and format contract.
load diagnostics on stderr. Promptkit uses old-path ConfigKit v0.5.0 to load
framework sources under its own definition and format contract. Errors and
warnings are written by the owning generation's native diagnostic writer.
- `internal/adapter/http` strictly decodes request DTOs, maps them to Promptkit
public values, calls its adapter-owned `Runner` interface, and maps results
and errors to HTTP DTOs.
@@ -78,7 +79,7 @@ adapter's consumer-owned `Runner` interface, and starts the server.
The command paths assemble the engine from application-selected framework
source files and directories plus the schema directory and retry setting.
Individual files become import-enabled ConfigKit inputs; directory selections
Individual files become import-enabled old-path ConfigKit inputs; directory selections
are expanded through Promptkit's directory-input helper. Scriptorium supplies
those ordered underlays through Promptkit's public configuration API rather
than parsing or mapping framework definitions itself. The server constructs

View File

@@ -9,7 +9,7 @@ public behavior belongs in the linked contracts.
| `cmd/scriptorium` | Process entrypoint that delegates arguments and streams to the CLI adapter. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
| `internal/adapter/cli` | Parses execution, application-configuration, and captured framework-configuration inspection commands; resolves settings; constructs Promptkit engines for execution, definition inspection, and framework inspection; maps requests; and owns process output and exit behavior. | [CLI contract](../cli.md), [adapter internals](adapters.md), [source internals](sources.md) |
| `internal/adapter/http` | Owns routes, DTOs, strict decoding, limits, Promptkit request/result mapping, public error mapping, and restricted HTTP artifact reading. | [HTTP API](../api.md), [adapter internals](adapters.md), [source internals](sources.md) |
| `internal/config` | Selects application sources, supplies the application ConfigKit definition and explicit overrides, and converts resolved settings for runtime use. | [configuration contract](../config.md), [adapter internals](adapters.md), [source internals](sources.md) |
| `internal/config` | Selects application sources through ConfigKit v1.2.0, supplies the application definition and explicit overrides, and converts resolved settings for runtime use. | [configuration contract](../config.md), [adapter internals](adapters.md), [source internals](sources.md) |
| `internal/defaults` | Holds Scriptorium-owned application and HTTP defaults. | [configuration contract](../config.md) |
| `internal/format` | Formats Promptkit prepared-run and prompt/profile inspection values for CLI text or JSON output; framework-configuration output uses Promptkit's native captured view and writers. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
| `internal/report` | Projects one terminal Promptkit observation into Scriptorium-owned execution metadata. | [adapter internals](adapters.md) |

View File

@@ -13,7 +13,7 @@ owned by the tagged
`schema_dir` from application configuration and explicit CLI overrides. It
owns selector-shape validation, not framework file parsing. During engine
construction, `internal/adapter/cli` turns file selections into import-enabled
ConfigKit inputs and expands directory selections with
old-path ConfigKit v0.5.0 inputs and expands directory selections with
`promptkit.DirectoryInputs`, then passes the ordered groups as Promptkit
configuration underlays. The shared Promptkit engine receives the selected
schema directory and retry setting as well.
@@ -32,22 +32,21 @@ inputs that use Promptkit's tagged formats.
`internal/config` contains the application-owned ConfigKit-native `Document`
definition. Its fresh defaults come from Scriptorium's existing default
constants; its resolver records only actual trimming, path cleaning, and
constants; its resolver records only actual leaf-level trimming, path cleaning, and
render-format normalization. The validator reports selector-shape, retry,
size-limit, and format errors without mutating the document or exposing
rejected values. Application path values keep working-directory-relative
meaning. ConfigKit owns strict application YAML decoding and presence
meaning. ConfigKit v1.2.0 owns strict application YAML decoding and presence
semantics. Framework configuration is separately loaded by Promptkit through
ConfigKit under Promptkit's own schema and source contract.
its older ConfigKit under Promptkit's own schema and source contract.
The `Load` boundary selects an explicit file, the first existing implicit
configuration file, or ConfigKit's defaults-only source. Only absence advances
implicit discovery. One ConfigKit load applies explicit application overrides
before validation and returns a result containing the resolved document and
its frozen inspection records. `Settings` converts that document into the
existing runtime settings with backend IDs sorted; it does not read files or
apply another merge. File-backed loads enable explicit ConfigKit imports and
select one named overlay when requested. ConfigKit uses the selected file's
The `Load` boundary selects an explicit file or constructs a native ConfigKit
search over the ordered implicit paths. Discovery exhaustion uses defaults;
a selected-file error stops loading. One ConfigKit load enables imports,
applies explicitly supplied application overrides after decoding and before
resolution and validation, and returns the document and its frozen inspection
records. `Settings` copies selectors in their resolved order into runtime
settings; it does not read files or apply another merge. ConfigKit uses the selected file's
canonical directory as the source root; the application does not widen it.
Application path values retain process-working-directory-relative meaning.
@@ -58,7 +57,8 @@ definition validation, and captured inspection view remain framework-owned.
Every configuration-loading command uses this boundary. The CLI maps only
explicitly visited application flags to ConfigKit overrides and prints
structured load diagnostics before engine construction. The old application
structured load diagnostics before engine construction. Application and
framework load errors and warnings use their respective native writers. The old application
YAML decoder and merge path have been removed.
Application `config` inspection reuses the result's frozen effective,
provenance, and history views without constructing an engine or reloading

View File

@@ -34,7 +34,22 @@ License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
[Source](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3).
## ConfigKit
## ConfigKit (application)
Selected module: `go.maximumdirect.net/configkit` at `v1.2.0`.
Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
[GPL 3.0](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/LICENSE).
[Source](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e).
## ConfigKit (Promptkit dependency)
Selected module: `gitea.maximumdirect.net/eric/ConfigKit` at `v0.5.0`.
@@ -44,10 +59,10 @@ SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
[GPL 3.0](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/LICENSE).
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/configkit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/configkit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/LICENSE).
[Source](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd).
[Source](https://forge.maximumdirect.net/base-layer/configkit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd).
## Promptkit OpenRouter Catalog

View File

@@ -61,13 +61,13 @@ reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/f
and [outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/integrations/openai-compatible-chat.md)
remain Promptkit's contracts.
Scriptorium uses ConfigKit v0.5.0 for strict application YAML decoding,
Scriptorium uses ConfigKit v1.2.0 for strict application YAML decoding,
resolution, and validation flow. Scriptorium retains its application schema,
defaults, normalization, validation rules, source selection, and CLI override
mapping. Promptkit also uses ConfigKit to decode and assemble framework
sources under Promptkit's own schema and format contract; Scriptorium selects
the inputs but does not parse Promptkit definitions. ConfigKit is the shared
loading mechanism, not the owner of either domain schema or HTTP artifact
mapping. Promptkit uses its own ConfigKit v0.5.0 dependency to decode and
assemble framework sources under Promptkit's schema and format contract; Scriptorium selects
the inputs but does not parse Promptkit definitions. These ConfigKit generations
are loading mechanisms, not owners of either domain schema or HTTP artifact
containment. The [configuration contract](../config.md) owns externally
observable application behavior, while Promptkit owns framework formats.

View File

@@ -9,26 +9,26 @@ discoverability requirements.
## Prepare The Candidate
Use a POSIX shell, Git with a configured tagger identity and access to
`origin`, and the selected release toolchain, Go 1.26.11. The native host must
`origin`, and the selected release toolchain, Go 1.27.4. The native host must
support Go's race detector and have its required C compiler. If Git is
configured to sign tags, its signing tool and key must be available. Run from the
repository root. The [developer guide](development.md#baseline-validation)
explains the separate Go consumer minimum; selecting a release toolchain does
not raise that minimum.
Install Go 1.26.11 from the [official downloads](https://go.dev/dl/) or an
Install Go 1.27.4 from the [official downloads](https://go.dev/dl/) or an
equivalent package source before validation. Set `release_go_root` to its
installation directory, replacing the illustrative path below, and select it
in the release shell:
```sh
release_go_root=/path/to/go1.26.11
release_go_root=/path/to/go1.27.4
export PATH="$release_go_root/bin:$PATH"
export GOTOOLCHAIN=local
go version
```
The version output should identify `go1.26.11`. Keep this selection and the
The version output should identify `go1.27.4`. Keep this selection and the
hosted workflow's Go image in step when deliberately updating the release
toolchain. Ordinary contributor checks may use another compatible toolchain.

View File

@@ -349,6 +349,11 @@ do not sort or deduplicate it to repair a test.
## Stage 6: Update Canonical Documentation And Both ConfigKit Attributions
**Complete.** Updated the owned contracts, contributor and release guidance,
internal boundaries, and separate attributions. Both collection commands ran;
affected local links and pinned ConfigKit copyright and license files were
checked against the corresponding source revisions.
**Work**
1. Update `docs/config.md` for application ConfigKit v1.2.0 and native