Update documentation for PromptKit adoption

This commit is contained in:
2026-11-18 19:25:54 +00:00
parent a2205db152
commit 50c65adac4
16 changed files with 270 additions and 347 deletions

View File

@@ -9,7 +9,7 @@ own IO and presentation mechanics, not framework decisions.
External contracts are canonical in the [CLI reference](../cli.md) and
[HTTP API reference](../api.md). Promptkit's public engine contract is
described by its tagged
[Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md).
[Go consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/pkg-promptkit.md).
## Components And Collaborators
@@ -20,11 +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 v1.2.0. The CLI supplies only
overrides, and validation ordering to ConfigKit v1.2.1. The CLI supplies only
explicitly visited application flags as overrides and renders safe structured
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.
load diagnostics on stderr. PromptKit uses the same ConfigKit release to
load framework sources under its own definition and format contract. Both
domains use ConfigKit'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.
@@ -38,7 +38,7 @@ described by its tagged
### CLI
`run` calls `promptkit.Engine.Run`; `render` calls
`promptkit.Engine.Prepare`. Both share request mapping for prompt ID/version
`promptkit.Engine.Prepare`. Both share request mapping for exact prompt ID
and profile selection, optional file inputs, variables, and presence-aware
execution overrides. Omitted framework settings remain zero values so Promptkit
resolves its own defaults and definition-required inputs.
@@ -47,10 +47,10 @@ run/render flag enters only the mapped request. The server uses the same engine
setting and retains one backend admission state. Render prepares without
generation.
`inspect prompt` maps the selected ID and optional version to
`inspect prompt` maps the selected ID to
`promptkit.Engine.InspectPrompt`, then formats Scriptorium-owned inspection
data. `inspect profile` maps an explicit profile ID to `Engine.InspectProfile`
and formats Scriptorium-owned effective profile data.
and formats Scriptorium-owned resolved profile data without backend completion.
Both paths construct the same full-source engine as execution before inspecting
the chosen definition; selected prompts are not filtered out. They do not
@@ -79,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 old-path ConfigKit inputs; directory selections
Individual files become import-enabled 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
@@ -95,6 +95,9 @@ validation, model, usage, and metadata values directly.
The optional HTTP retry count maps to `RunRequest.TransientRetries` without
mutating the shared engine. Negative values are rejected before invocation;
Promptkit controls retries and backend admission for concurrent requests.
CLI and HTTP operation budgets map to PromptKit's `OperationTimeout`; HTTP
passes the caller context through unchanged. The public sentinels determine
timeout classification, subject to the documented transport limitation.
Failure mapping uses `errors.Is` against Promptkit's public sentinels and the
HTTP reader's Scriptorium-owned containment and size errors. Wrapped reader

View File

@@ -9,11 +9,11 @@ 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 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/config` | Selects application sources through ConfigKit v1.2.1, 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) |
Framework implementation packages are provided by
[Promptkit v0.12.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md)
[PromptKit v0.23.2](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/pkg-promptkit.md)
and are not part of this repository.

View File

@@ -5,7 +5,7 @@
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 v0.12.0 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md).
[PromptKit v0.23.2 format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/formats.md).
## Application Source Locations
@@ -13,10 +13,12 @@ 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
old-path ConfigKit v0.5.0 inputs and expands directory selections with
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.
configuration underlays, one per selector. Directory inputs retain the
helper's strict-composition grouping; no selected source becomes an implicit
framework main. The shared Promptkit engine receives the selected schema
directory and retry setting, and the default OpenRouter bundle remains enabled.
Promptkit uses ConfigKit to load and compose those framework inputs according
to Promptkit's own schema and format. Scriptorium does not parse or validate
@@ -36,9 +38,9 @@ constants; its resolver records only actual leaf-level trimming, path cleaning,
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 v1.2.0 owns strict application YAML decoding and presence
semantics. Framework configuration is separately loaded by Promptkit through
its older ConfigKit under Promptkit's own schema and source contract.
meaning. ConfigKit v1.2.1 owns strict application YAML decoding and presence
semantics. Framework configuration is separately loaded by PromptKit using
the same ConfigKit release under PromptKit's own schema and source contract.
The `Load` boundary selects an explicit file or constructs a native ConfigKit
search over the ordered implicit paths. Discovery exhaustion uses defaults;