Align PromptKit architecture documentation

This commit is contained in:
2026-10-04 13:11:48 +00:00
parent b913ef0d07
commit beaaea2f1a
8 changed files with 104 additions and 55 deletions

View File

@@ -5,20 +5,24 @@
This document covers Scriptorium-owned source locations and the restricted HTTP
artifact reader. Prompt, profile, schema, and ordinary artifact semantics are
owned by the tagged
[Promptkit format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md).
[Promptkit v0.12.0 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md).
## Application Source Locations
`internal/config` resolves `prompt_dir`, `profile_dir`, and `schema_dir` from
Scriptorium defaults, configuration files, and CLI overrides. It also resolves
the application-owned `backends` mapping into sorted engine settings.
`internal/adapter/cli` passes the directories into `promptkit.Config` and maps
each configured backend to Promptkit's public engine registration when
constructing an engine shared by the command path.
`internal/config` resolves the ordered `promptkit_sources` sequence and
`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
`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.
Scriptorium does not search, parse, validate, or overlay framework source files
itself. Promptkit owns prompt selection, profile built-ins and overlays, schema
resolution, ordinary file artifacts, and the related error identities.
Promptkit uses ConfigKit to load and compose those framework inputs according
to Promptkit's own schema and format. Scriptorium does not parse or validate
Promptkit definitions. Promptkit owns definition selection and validation,
profile built-ins and overlays, schema resolution, ordinary file artifacts,
captured framework configuration inspection, and related error identities.
The [configuration reference](../config.md) owns Scriptorium's source-location
fields and precedence. Maintained files under `examples/` are application
@@ -26,13 +30,15 @@ inputs that use Promptkit's tagged formats.
## Application Configuration Boundary
`internal/config` contains a ConfigKit-native `Document` definition. Its
fresh defaults come from Scriptorium's existing default constants; its resolver
records only actual trimming, path cleaning, and render-format normalization.
The validator reports application 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 YAML decoding and
presence semantics, including dynamic integer values in backend parameters.
`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
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
semantics. Framework configuration is separately loaded by Promptkit through
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
@@ -45,11 +51,10 @@ select one named overlay when requested. 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.
ConfigKit resolves effective sibling inheritance after source assembly and
overrides, before typed decoding. Runtime conversion and Promptkit registration
consume those resolved values through the existing `Settings` path. The
[configuration reference](../config.md#application-mapping-inheritance) owns
the application-visible inheritance behavior.
Runtime conversion consumes the resolved application values through the
existing `Settings` path. Promptkit receives selected framework sources only
after application configuration has loaded and validated; its source merge,
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
@@ -57,8 +62,11 @@ structured load diagnostics before engine construction. 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
sources. It does not resolve API-key environment values; ordinary backend
parameters remain visible by the selected inspection policy.
sources. It does not resolve credentials. `inspect configuration` separately
constructs an engine and exposes Promptkit's captured framework view; only its
framework `show` and `explain` reports receive Promptkit's native,
credential-shaped redaction. Neither inspection family is a general-purpose
filter for arbitrary sensitive values.
## Restricted HTTP Artifact Reader