2026-11-18 19:25:54 +00:00
# Upgrade PromptKit Sources And Definitions
2026-10-04 13:04:02 +00:00
2026-11-20 05:08:40 +00:00
This guide covers the earlier 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-20 05:08:40 +00:00
for the full upstream contract. The subsequent [native CLI migration ](upgrading-cli.md )
owns command, reporting, application-discovery, and source-setting changes.
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-20 05:08:40 +00:00
Framework definition migration and application acquisition are separate changes.
Rewrite older framework files as below, then select their entry file using the
current [application configuration ](../config.md#application-settings ).
The old source-selector list and top-level schema root are not current aliases;
follow the [CLI migration guide ](upgrading-cli.md#migrate-application-configuration ).
Scriptorium does not provide a legacy definition reader or embedded-definition
extraction/reload path.
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.
2026-11-19 15:17:02 +00:00
PromptKit resolves `content_file` relative to the source that supplied the
field, including imported or inherited definitions. The
[framework format reference ](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md#messages-and-templates )
describes which paths are allowed within the source root.
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}` .
2026-11-18 19:25:54 +00:00
2026-11-20 05:08:40 +00:00
The single external framework entry uses native ConfigKit import composition;
there is no application-managed source-list precedence. Native record replacement
and inheritance remain upstream-owned. Checkouts imported by the same
2026-11-19 15:17:46 +00:00
[discovery file ](../config.md#collection-checkout-discovery ) are peers:
conflicting definitions of the same ID fail instead of overriding one another.
Null profile endpoint, credential, or provider-map settings can fall
2026-11-18 19:25:54 +00:00
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.
2026-11-20 05:08:40 +00:00
The [CLI reference ](../cli.md ) defines qualified selection and prepared preview; the
2026-11-18 19:25:54 +00:00
[operations guide ](../operations.md ) describes when updates take effect.