Document PromptKit source migration

This commit is contained in:
2026-10-04 13:04:02 +00:00
parent 411a67b241
commit b913ef0d07
6 changed files with 384 additions and 166 deletions

View File

@@ -9,7 +9,9 @@ fields, or HTTP wire behavior.
- [CLI reference](cli.md): commands, output destinations, and exit codes.
- [Configuration reference](config.md): application settings, source
locations, defaults, and credential mapping.
- [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md):
- [Promptkit source upgrade guide](consumers/upgrading-promptkit.md): concise
source-selector and definition migration examples.
- [Promptkit v0.12.0 framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md):
prompt, profile, schema, execution-setting, and framework credential
contracts.
- [HTTP API reference](api.md): route, request/response schema, status codes,
@@ -39,10 +41,17 @@ without a report.
## Deploy The Filesystem And Process
Provide the process with readable configured Promptkit prompt, profile, and
schema sources that follow the tagged framework formats. For an HTTP deployment
that accepts file artifacts, use a dedicated, narrow artifact directory rather
than a general-purpose or sensitive filesystem tree.
Provide the process with readable selected Promptkit source files/directories
and schema sources that follow the tagged framework formats. At engine
construction, Promptkit v0.12 validates every selected effective definition,
including unused definitions, and captures referenced message-file contents
and static template syntax. `serve` constructs one engine at startup; it does
not reload changed configuration or message content. Restart the process to
validate and capture a new configuration. Schema and request-artifact reads,
credential resolution, and provider work remain request-preparation or runtime
concerns. For an HTTP deployment that accepts file artifacts, use a dedicated,
narrow artifact directory rather than a general-purpose or sensitive filesystem
tree.
If application configuration uses explicit imports or a selected overlay,
deploy those files beneath the selected configuration file's canonical
@@ -87,25 +96,27 @@ and apply the same retention and access rules as for model input and output.
Before changing production inputs, profiles, or schemas:
1. use `config validate`, `config show`, or `config sources` to check the
application configuration and its selected sources without constructing an
engine; this does not verify prompt files, provider access, or credentials;
2. confirm the deployed configuration selects the intended sources and model
credentials;
3. use [`render`](cli.md) with the same request inputs and variables to confirm
1. use `config validate`, `config show`, or `config sources` to check
Scriptorium's application configuration; these do not open Promptkit sources
or construct an engine;
2. use `inspect configuration validate` to construct the engine and validate
all selected framework definitions; this does not prepare a request, check
credentials, load request-time schemas/artifacts, or contact a provider;
3. confirm the deployed configuration selects the intended sources and
environment-variable names;
4. use [`render`](cli.md) with the same request inputs and variables to confirm
preparation without a model call;
4. use [`run`](cli.md) for generation; and
5. retain or discard validation-failed output according to the caller's
5. use [`run`](cli.md) for generation; and
6. retain or discard validation-failed output according to the caller's
policy.
Inspection output can include configuration paths, names, and ordinary backend
parameters. `config explain --path` uses JSON Pointer paths and can show
displaced historical values as well as the final value. Protect both the
selected paths and the output, especially when backend parameters contain
sensitive identifiers; ConfigKit does not infer arbitrary secrets in those
parameters. Apply
access and retention controls; the application stores only API-key environment
reference names, not the resolved credential bytes.
Application configuration inspection can include paths and configured values.
Framework `inspect configuration show` and `explain` use Promptkit's native
redaction for classified credential-shaped provider fields, including
historical values, while leaving environment-reference names and ordinary
provider parameters visible. Neither report identifies arbitrary sensitive
content by value or name. Protect inspection output accordingly; Scriptorium
stores environment-variable names, not the resolved credential bytes.
The [maintained render script](../examples/render-markdown-summary.sh) is a
copyable preflight example. The CLI reference owns its complete invocation and
@@ -150,7 +161,7 @@ setting and then Promptkit's default, while explicit zero disables additional
attempts. Existing generation timeouts apply
per attempt, while the caller context covers the complete operation. Provider
`Retry-After` timing can exceed Promptkit's ordinary backoff cap; consult the
[outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/integrations/openai-compatible-chat.md)
[outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/integrations/openai-compatible-chat.md)
for details.
CLI `run` can set a [whole-run deadline](cli.md) when total execution time must