# Upgrade PromptKit Sources And Definitions This guide covers the CLI and 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. Removing version selectors and changing framework definition shapes are intentional incompatible changes under the [release policy](../policy/release.md#versioning-and-compatibility). ## Application configuration Existing application fields that already select the desired sources retain their meaning. For example, this application configuration works both before and after the cutover: ```yaml promptkit_sources: - directory: ./examples/prompts - directory: ./examples/profiles - file: ./examples/framework/backends.yml schema_dir: ./examples/schemas ``` 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). ## 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}`. 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.