diff --git a/README.md b/README.md index e4c14e1..a02acee 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,8 @@ a model. For complete invocation and output behavior, see the - [Minimal configuration](examples/config.yml) and [complete configuration](examples/config.full.yml), plus a - [composed import/overlay example](examples/config.composed.yml) and + [composed import/overlay example](examples/config.composed.yml), a + [collection composition example](examples/config.collections.yml), and a [backend inheritance example](examples/config.inheritance.yml) - [Prompt definitions](examples/prompts/), [execution profiles](examples/profiles/), [schemas](examples/schemas/), and [synthetic input fixtures](examples/fixtures/) diff --git a/docs/cli.md b/docs/cli.md index 34530f3..41c8a8f 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -35,7 +35,7 @@ All command families accept `--config ` and `--config-overlay `; 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 ` flags and `--schema-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`. diff --git a/docs/config.md b/docs/config.md index ae37e2b..b2182eb 100644 --- a/docs/config.md +++ b/docs/config.md @@ -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 diff --git a/docs/development.md b/docs/development.md index 731be9f..a307b5d 100644 --- a/docs/development.md +++ b/docs/development.md @@ -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: diff --git a/docs/internal/adapters.md b/docs/internal/adapters.md index 69ad7d5..37ed1b2 100644 --- a/docs/internal/adapters.md +++ b/docs/internal/adapters.md @@ -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 diff --git a/docs/internal/overview.md b/docs/internal/overview.md index fd6826c..4535fc6 100644 --- a/docs/internal/overview.md +++ b/docs/internal/overview.md @@ -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) | diff --git a/docs/internal/sources.md b/docs/internal/sources.md index ca291f1..349d067 100644 --- a/docs/internal/sources.md +++ b/docs/internal/sources.md @@ -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 diff --git a/docs/oss/attribution.md b/docs/oss/attribution.md index e0fe6e2..845bb70 100644 --- a/docs/oss/attribution.md +++ b/docs/oss/attribution.md @@ -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 diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index cb7b784..d3c898f 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -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. diff --git a/docs/release.md b/docs/release.md index baf2de8..9cae23c 100644 --- a/docs/release.md +++ b/docs/release.md @@ -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. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index f16f003..f40ae8a 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -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