# Upgrade PromptKit Sources And Definitions This guide covers the earlier framework configuration cutover to [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) for the full upstream contract. The subsequent [native CLI migration](upgrading-cli.md) owns command, reporting, application-discovery, and source-setting changes. Removing version selectors and changing framework definition shapes are intentional incompatible changes under the [release policy](../policy/release.md#versioning-and-compatibility). ## Application configuration 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. ## Rewrite framework definitions Replace version-keyed prompts and keyed profile/backend mappings with lists of records containing `id`. For example, before: ```yaml prompts: report: "1": default_profile: fast messages: - role: user content: Summarize this note. output: format: text validation_mode: none profiles: fast: endpoint: https://example.invalid/v1 model: synthetic-model ``` After: ```yaml prompts: - id: report default_profile: fast messages: - role: user content: Summarize this note. output: format: text validation_mode: none profiles: - id: fast endpoint: https://example.invalid/v1 model: synthetic-model ``` 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. 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}`. 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 [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 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) defines qualified selection and prepared preview; the [operations guide](../operations.md) describes when updates take effect.