# PromptKit v0.12.0 Adoption ## Status And Intent Drafted on 2026-10-03; source-selection and framework-inspection decisions confirmed by the maintainer on 2026-10-04. The PromptKit v0.12.0 adoption has been implemented and delivered after the complete audit passed on 2026-10-04. This document remains target and decision context, not an implementation-stage log. Release preparation remains separate; no release version has been selected or published. No significant decisions remain open within this scope. Adopt PromptKit's ConfigKit-native configuration boundary while preserving Scriptorium's simple, request-independent execution model. As established in [ADR 0004](../adr/0004-definition-boundary.md), valid prompt and profile definitions for the selected PromptKit version should work without a narrower Scriptorium field-level format. Library-only APIs are considered separately; this upgrade does not turn Scriptorium into a workflow application. The maintainer selected a native source cutover and full framework configuration inspection. The latter uses upstream's native redaction in this new interface only. These are deliberate product choices, not requirements inferred merely from new library APIs. ## Reviewed Baseline And Upstream Target The reviewed Scriptorium source is commit `bb5006517b6c27dcbe56074f1d97140bf0999c48`; the last release is v0.15.0. The completed ConfigKit adoption selects ConfigKit v0.5.0. PromptKit remains v0.11.2, with the OpenRouter and Rakestrawhome `/v2` catalog modules at v2.20260926.0. Application configuration already uses one ConfigKit loading, inheritance, resolution, validation, and inspection pipeline. Framework construction still passes `prompt_dir` and `profile_dir` into the removed PromptKit directory fields and registers application `backends` with `WithBackend`. Profile inspection substitutes an empty prompt filesystem to avoid loading prompts. Maintained prompt/profile files and inline test fixtures use the old embedded `id`, `version`, and `base_profile` syntax. The target is the published PromptKit v0.12.0 release at full commit `4b8169da286917fde7875425bb32b799b12c6af3`. The published tag and downloaded module identify that same revision. Canonical references are: - [Release notes](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/docs/releases/v0.12.0.md). - [Framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/docs/formats.md). - [Consumer and migration guide](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/docs/consumers/pkg-promptkit.md). - [Configuration ownership decision](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/docs/adr/0001-configuration-boundary.md). PromptKit now also selects ConfigKit v0.5.0, so no further ConfigKit upgrade is needed. Go 1.25.5 remains sufficient. Its catalog selections are: | Module | Version | Full source commit | | --- | --- | --- | | `promptkit-backend-openrouter/v3` | `v3.20260930.0` | `f17d208cb7ad1fb043cda2266cd3011d11b40aa0` | | `promptkit-backend-rakestrawhome/v3` | `v3.20260930.0` | `993443d88c451901f4c917fa00c204fd3b54d28d` | This review examined upstream contracts and the affected Scriptorium adapters, configuration, presentation, examples, and tests. It did not establish that the unmodified application builds against the new, incompatible construction API. ## Targeted End State ### Framework Ownership And Source Assembly Scriptorium constructs engines through PromptKit's public root package and `Config.Sources`. ConfigKit owns source composition, overlays, inheritance, presence, null values, and resource origins. PromptKit owns final definition validation, catalog contributions, backend completion, content capture, preparation, execution, and capacity coordination. An operator-selected source may contain any combination of keyed `backends`, `profiles`, and versioned `prompts`. Do not partition or filter documents by directory name, filename, or a Scriptorium copy of the framework schema. Do not independently preflight domain fields in lower-priority definitions that the final effective configuration replaces. Syntax and composition failures remain upstream loading failures. The selected application interface is an ordered `promptkit_sources` sequence. Each entry selects either a `file` or a `directory` and contributes one caller underlay, from lowest to highest priority. A directory uses `promptkit.DirectoryInputs` and strictly composes its recursively discovered YAML files. A file uses `configkit.File` with declared imports enabled, so an entry document can compose fragments. All caller groups follow PromptKit's maintained catalogs and owned defaults. No separately exposed `Sources.Main` setting is needed for this interface. For example, the target application shape is: ```yaml promptkit_sources: - directory: ./examples/prompts - directory: ./examples/profiles - file: ./deployment/promptkit.yml schema_dir: ./examples/schemas ``` Directories retain the helper's default of disabled imports. Enabling imports while also recursively discovering their YAML targets would include those files twice in the same group, which ConfigKit rejects. Use a selected entry file with imports for that layout; do not silently deduplicate, skip files, or convert composition conflicts into precedence. Under this decision, `prompt_dir`, `profile_dir`, application `backends`, and their directory flags are replaced, not retained as a second configuration model. Framework backend definitions live with the framework sources rather than passing through Scriptorium's scalar backend schema. A repeatable `--promptkit-source PATH` selects a replacement ordered source list for engine-using commands; each path selects a regular file or directory using the same rules. Only an explicitly supplied flag overrides the configured list. Application source discovery, its imports and selected overlay, explicit CLI override handling, and working-directory-relative application paths remain unchanged. `--config-overlay` still selects an application overlay; it does not implicitly select a PromptKit layer or profile. Framework priority is explicit in the source list, with import/resource containment supplied by upstream for each selected root. This is not a new global filesystem sandbox. ### Complete Definition Support The target accepts the keyed v0.12.0 formats without compatibility rewriting: profile and backend IDs are mapping keys, prompt IDs contain keyed string versions, and `extends` replaces `base_profile`. Literal IDs and references retain their exact spelling, including punctuation and meaningful whitespace; filenames do not establish identities. All supported prompt/profile fields continue to reach PromptKit, including inputs, message roles and cache metadata, inline and file content, session templates, output validation and repair, backend/endpoint selection, credentials by environment name, generation controls, and provider parameters. The upstream format reference, not this list, owns the complete contract. Presence must survive the boundary: omission, explicit zero/false/blank, and null are not interchangeable. Inheritance and layers recursively combine maps; an empty map does not clear inherited entries. Backend defaults apply after effective profile inheritance. Changing a model or backend no longer drops unrelated explicitly inherited settings. Profile null suppression and explicit zero controls must affect outbound requests as specified upstream. Partial profiles remain valid when request overrides can complete them. Scriptorium must not introduce a mandatory model, credential, default profile, or directory prerequisite that prevents such a request. With the selected source interface, engine construction may have no prompt collection; missing request selections fail through PromptKit's ordinary public errors rather than a required `prompt_dir` check. Source selection does not imply provider access or credential availability. ### Captured Definitions And Runtime Lifecycle Engine construction validates every final effective definition, including unused entries, and captures message-file content and static template syntax. Invalid unused definitions or unreadable message resources may therefore fail startup or inspection before a request selects them. An overwritten domain value is not independently rejected merely because it appears in history. ConfigKit's structural directives now also apply to framework input mappings, including dynamic provider maps. Document the reserved `extends` key and the difference from literal runtime provider parameters; do not invent a quoting escape or a second inheritance resolver. Content files use their effective field's source context, including imported and inherited content. Retain those contexts by passing actual upstream inputs; do not flatten files into synthetic mappings that lose origins. Application paths remain working-directory-relative, whereas framework message resources follow PromptKit's source-relative contract. Schema and request artifact reads remain preparation-time resources; credentials and provider operations retain their documented runtime boundaries. A server retains one constructed engine across its requests, with shared backend capacity and queue accounting. Definition/message edits require a new engine; for this scope, restarting the server is the supported way to obtain one. CLI invocations naturally construct fresh engines. No file watcher, reload endpoint, per-request server reconstruction, or durable state is added. This is not a transactional snapshot of all external files or credentials. ### Definition And Application Inspection `inspect prompt` and `inspect profile` use the same selected configuration snapshot as execution. Remove the empty-prompt-filesystem substitution. Profile inspection still does not need request inputs, schema reads, model calls, or credential values, but constructing its engine now validates and captures all selected definitions, including prompts. A partial target may be inspected without imposing preparation's completeness requirements. `config validate`, `show`, `sources`, and `explain` remain application configuration operations without constructing an engine. Under the selected source cutover, they show source selections rather than the contents of PromptKit's separately loaded definitions. They are not framework validation. The separate framework inspection family below supplies framework validation and captured provenance. ### Captured Framework Configuration Inspection Add the CLI command family `inspect configuration` with `validate`, `show`, `sources`, and `explain` operations. It uses the same application settings, source selections, and engine construction as other engine-using commands, without requiring a prompt/profile selection or request inputs. Each invocation constructs one engine; reporting uses that engine's captured public view rather than loading definitions again. - `validate` succeeds when the engine constructs successfully and produces no success report. It validates final definitions and captures message resources, not provider access, credential availability, or request-specific preparation. - `show` writes the captured effective YAML through `ConfigurationInspection.WriteEffective`. - `sources` presents structured JSON source records from `ConfigurationInspection.Sources`, including the source kinds, layers, and underlay positions needed to distinguish maintained and operator inputs. - `explain --path JSON_POINTER` uses the native explanation view and writer for effective values and history. Root and literal mapping-key paths follow the same JSON Pointer conventions as application `config explain`; IDs with slashes or punctuation must not become dotted-path lookups. Use PromptKit's public `InspectConfiguration` and its native writers and records. Surface applicable load diagnostics safely on stderr; successful reports go to stdout. Inspection does not resolve credential values, contact a provider, or watch/reopen sources after construction. Captured effective configuration is distinct from backend-completed `inspect profile` output and request-specific prepared output; none substitutes for the others. The maintainer explicitly accepts upstream's credential-shaped provider-key redaction for this new family, including effective and historical values. Fields such as `token` and `password` can therefore be redacted here while remaining visible in existing profile/prepared views. This is not blanket redaction of `extra_params`, a change to parameters sent to providers, or a change to existing inspection interfaces. Environment-reference names and ordinary unclassified content can remain visible. Reports may contain prompt text, provider data, paths, and identifiers; native redaction is not a promise that the output is safe to disclose. ### Requests, Presentation, And Disclosure Keep CLI/HTTP request independence, presence-aware execution overrides, generation/whole-run timeout separation, transient retries, execution reports, artifact policy, and public error mapping. Preserve existing serialized results unless an upstream change actually requires an application contract change. Prepared/profile numeric values alone are not proof that a zero control was sent; verify upstream presence through generation or recorded outbound requests. The dependency change alone does not require a new presence DTO. Continue mapping errors by public identity rather than message text. Environment-variable names remain visible; resolved API keys are never printed or serialized. Ordinary `extra_params` retain their selected visibility where those values are presented. Moving definitions out of application settings changes what `config` can inspect, not their sensitivity classification. Do not silently adopt broader redaction rules for existing profile/prepared inspection. ## Work Needed From The Baseline - **Dependencies and attribution:** select released PromptKit v0.12.0, tidy the module graph, and use its selected `/v3` catalogs without direct application imports. Remove obsolete `/v2` modules and `gopkg.in/yaml.v3` if no remaining imports require them. Update PromptKit/catalog component entries and exact source, COPYRIGHT, and LICENSE links in `docs/oss/attribution.md`. The reviewed grants remain LGPL-3.0-or-later for PromptKit and MIT for the catalogs; reuse the applicable local license texts. Preserve unrelated attribution entries and historical release documents. - **Application settings and CLI:** implement the selected source interface through `internal/config` and shared CLI override mapping. Retire the backend document/runtime conversion and old directory fields, add ordered source selection, and update command help and prerequisites. Application validation checks its schema and selector shape; framework acquisition and domain validation belong to engine construction. - **Shared engine wiring:** replace removed fields/options with upstream inputs and underlays, retain `SchemaDir`, `TransientRetries`, and runtime collaborator injection, and use the same construction path for execution, rendering, definition inspection, and serving. Preserve identifiable PromptKit and ConfigKit causes and safe diagnostics. Remove obsolete prompt-filesystem inspection scaffolding. - **Captured framework inspection:** add the `inspect configuration` family with `validate`, `show`, `sources`, and `explain` using the shared engine path and its public captured inspection view. Reuse native YAML/explanation writers, preserve useful source-layer information in JSON presentation, and keep application `config` independent of framework loading. Apply the approved native redaction exception only to this new family. - **Definitions and fixtures:** migrate every maintained prompt/profile file under `examples/` and `testdata/`, and inline definitions and construction helpers in CLI, HTTP, and formatting tests. Replace old inheritance syntax and move backend examples into framework definitions. Review old explicit zeros for their changed meaning instead of preserving obsolete expectations mechanically. Keep useful feature-adoption coverage; filenames need not be renamed merely to reduce historical naming. - **Focused adoption coverage:** use real ConfigKit/PromptKit boundaries for representative source order, same-group conflicts, file imports, combined documents, inherited source-relative content, exact IDs/version selection, null suppression, explicit zero/false, and partial-profile completion. Verify eager failures for unused final definitions and unchanged captured message content after file edits on an existing engine. Retain shared-server capacity, retry, cancellation, restricted artifact, output, and error tests. Cover framework inspection's effective YAML, source layers, literal-key explanations, diagnostics, and effective/historical native redaction without provider calls. Protect the distinction between application validation and framework validation, and unchanged visibility in existing profile/prepared inspection. Avoid snapshots of incidental writer prose. Own integration risks locally without recreating upstream's exhaustive parser or inheritance matrices; use offline clients or `httptest` for generation. - **Current documentation and migration guidance:** update owning contracts in `docs/config.md`, `docs/cli.md`, and `docs/operations.md`, affected internal docs, `docs/development.md`, architecture version/ownership references, README, examples, and applicable consumer guidance. Link to v0.12.0 framework contracts rather than copying their specification. Correct statements that ConfigKit does not participate in framework loading. Explain the selected source migration, framework-inspection command family and scoped redaction exception, and engine-rebuild requirement. Preserve accepted ADR decision content. Update HTTP docs only where observable behavior changes. ## Compatibility And Release Impact This is an intentional breaking adoption, not a patch-only dependency refresh. Users must migrate definitions, inheritance syntax, source assembly, and assumptions about numeric presence, recursive maps, eager validation, and file reload. Under the selected native interface they must also migrate the application source selectors and move application backend definitions into PromptKit source files. Provide small before/after examples and runnable offline migration checks when implementation lands; no automatic legacy parser or catalog alias layer is proposed. PromptKit's maintained profile IDs remain supported, not frozen to fixed model settings. Review used external catalog IDs against the selected catalogs; do not promise live provider availability or preserve every volatile inventory ID. Hashes remain opaque equality values, not cross-version identity guarantees. Under the [release policy](../policy/release.md), the eventual release must be a new pre-1.0 minor version. Do not select or publish a release in this work set. The previously completed ConfigKit work may share that release; final version, notes, and roadmap retirement belong to release preparation. ## Completion Criteria And Scope Limits Adoption is complete when the released dependency graph is selected, the approved source interface reaches the canonical framework boundary without losing definition semantics, maintained examples and fixtures use v0.12.0, and CLI/HTTP workflows and inspection meet the target above. The new framework inspection family must use captured native reports with its explicitly scoped redaction behavior, without changing existing inspection disclosure. Run the existing development checks, affected offline examples, and link/diff checks, with focused new integration tests for the actual migration risks. This work does not add conversations, appended/follow-up messages, prepared-handle coordination, semantic retry workflows, embedded configuration bundles, framework internals, or application-owned framework validation. Library availability alone does not justify additional commands, endpoints, resource controls, recurring upstream probes, or release gates. Deferred interfaces are scope choices for this adoption, not permanent prohibitions. ## Confirmed Decisions ### Native Source Cutover The maintainer accepted the ordered `promptkit_sources` file/directory interface and moving backend definitions out of application settings. This exposes combined definitions, explicit priority, imports, and full presence/null semantics through their canonical owner. It removes duplicated backend representation and avoids translating absent scalar fields into presence-aware overlays. The deliberate application schema and CLI migration accompanies the unavoidable framework format migration. Retaining the old directories and application backend surface was considered but not selected: it would reduce migration while retaining duplicate backend configuration, presence/null translation, and a less flexible source interface. ### Native Framework Inspection With A Scoped Redaction Exception The maintainer selected `inspect configuration` using the captured native view, including upstream redaction in this new interface only, rather than deferring the feature. Provenance and history make layered configuration easier to diagnose, and native writers avoid maintaining a parallel representation. The accepted tradeoff is different provider-parameter visibility between this new view and existing profile/prepared inspection. Existing API-key-only redaction choices remain otherwise unchanged. Deferral or an upstream consumer-selectable sensitivity API could avoid that difference, but neither is a prerequisite for this adoption. Do not reconstruct private configuration to bypass native writers or depend on an unpublished upstream interface.