2026-11-18 19:25:54 +00:00
# Upgrade PromptKit Sources And Definitions
2026-10-04 13:04:02 +00:00
2026-11-18 19:25:54 +00:00
This guide covers the CLI and framework configuration cutover to
2026-11-19 14:39:10 +00:00
[PromptKit v0.23.3 ](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/configuration-migration.md )
and ConfigKit v1.2.1. See the [framework format reference ](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md )
2026-11-18 19:25:54 +00:00
for the full upstream contract.
2026-10-04 13:04:02 +00:00
2026-11-18 19:25:54 +00:00
Removing version selectors and changing framework definition shapes are
intentional incompatible changes under the [release policy ](../policy/release.md#versioning-and-compatibility ).
2026-10-04 13:04:02 +00:00
2026-11-18 19:25:54 +00:00
## Application configuration
2026-10-04 13:04:02 +00:00
2026-11-18 19:25:54 +00:00
Existing application fields that already select the desired sources retain
their meaning. For example, this application configuration works both before
and after the cutover:
2026-10-04 13:04:02 +00:00
```yaml
promptkit_sources:
- directory: ./examples/prompts
- directory: ./examples/profiles
2026-11-18 19:25:54 +00:00
- file: ./examples/framework/backends.yml
2026-10-04 13:04:02 +00:00
schema_dir: ./examples/schemas
```
2026-11-18 19:25:54 +00:00
The selected framework files must still be rewritten as described below.
Scriptorium uses one native application schema: discovery, imports, selected
overlays, source order, explicit overrides, and working-directory-relative
selector paths remain application configuration behavior. It loads framework
sources separately with PromptKit's schema. No second application schema or
legacy definition reader is provided. See the [configuration reference ](../config.md ).
2026-10-04 13:04:02 +00:00
2026-11-18 19:25:54 +00:00
## Rewrite framework definitions
2026-10-04 13:04:02 +00:00
2026-11-18 19:25:54 +00:00
Replace version-keyed prompts and keyed profile/backend mappings with lists
of records containing `id` . For example, before:
2026-10-04 13:04:02 +00:00
```yaml
prompts:
2026-11-18 19:25:54 +00:00
report:
"1":
default_profile: fast
2026-10-04 13:04:02 +00:00
messages:
- role: user
2026-11-18 19:25:54 +00:00
content: Summarize this note.
2026-10-04 13:04:02 +00:00
output:
format: text
validation_mode: none
profiles:
fast:
2026-11-18 19:25:54 +00:00
endpoint: https://example.invalid/v1
model: synthetic-model
2026-10-04 13:04:02 +00:00
```
2026-11-18 19:25:54 +00:00
After:
2026-10-04 13:04:02 +00:00
```yaml
2026-11-18 19:25:54 +00:00
prompts:
- id: report
default_profile: fast
messages:
- role: user
content: Summarize this note.
output:
format: text
validation_mode: none
2026-10-04 13:04:02 +00:00
profiles:
2026-11-18 19:25:54 +00:00
- id: fast
endpoint: https://example.invalid/v1
model: synthetic-model
2026-10-04 13:04:02 +00:00
```
2026-11-18 19:25:54 +00:00
Select prompts by exact ID; `--prompt-version` is rejected. If multiple former
versions must remain independently selectable, give them distinct IDs and
update callers. Qualified IDs such as `support/answer` are passed unchanged.
Keep relative message files beside their owning definitions. Convert framework
source controls from `configkit:` to `config:` and add `required: true` for
imports that must exist. An optional framework source header, if present, is
`version: 2` . Use sibling inheritance such as `extends: {id: base}` .
Composition now replaces a whole record when a later source selects the same
ID; supply the complete intended replacement, or create a distinct inherited
record. Null profile endpoint, credential, or provider-map settings can fall
back to the selected backend; review behavior rather than assuming null clears
backend values. Keep JSON schemas self-contained instead of depending on remote
schema references. Application selectors remain separate from these framework
semantics.
## Replace catalog selections
The default-on OpenRouter bundle supplies actual profiles such as `auto` and
`gpt-sol-latest` . Former catalog and `promptkit-openrouter-*` IDs are not
compatibility aliases. Choose an intended current bundled profile explicitly,
or define a complete local profile with the endpoint, model, and settings you
need. Do not assume a new default model. The bundle is an underlay and caller
records can replace it through ordinary composition.
For multiple independently maintained repositories, see the
[collection-discovery example ](../../examples/config.discovery.yml ). Its
entry files declare their own namespaces; checkout names do not become IDs.
The [CLI reference ](../cli.md ) demonstrates qualified rendering and the
[operations guide ](../operations.md ) describes when updates take effect.