# Upgrade Promptkit Sources And Definitions This guide moves Scriptorium application configuration and framework files to the Promptkit v0.12.0 source model. It covers the executable CLI and HTTP application, not the former Scriptorium Go package. For exact framework semantics, see the tagged [Promptkit v0.12.0 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md) and [release notes](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/releases/v0.12.0.md). ## Move source selectors into an ordered sequence Replace the old application directory settings: ```yaml prompt_dir: ./examples/prompts profile_dir: ./examples/profiles ``` with an ordered `promptkit_sources` sequence: ```yaml promptkit_sources: - directory: ./examples/prompts - directory: ./examples/profiles - file: ./framework/backends.yml schema_dir: ./examples/schemas ``` Each item selects exactly one `file` or `directory`. Later items overlay earlier items; conflicts within one directory source group are errors. Paths are relative to the process working directory. An omitted or empty sequence selects no application-supplied framework sources, while Promptkit's selected catalog and maintained definitions remain available. A selected application overlay replaces the whole sequence, and repeated `--promptkit-source` flags replace it in command-line order rather than appending to it. The former `--prompt-dir` and `--profile-dir` flags are removed. Replace them with repeated source flags, for example: ```sh scriptorium render \ --config ./examples/config.yml \ --promptkit-source ./examples/prompts \ --promptkit-source ./examples/profiles \ --promptkit-source ./examples/framework/backends.yml \ --prompt generic.markdown_summary \ --input transcript=./examples/fixtures/transcript.md \ --input glossary=./examples/fixtures/glossary.yml ``` Use the same source selectors with `run`, `serve`, and the supported `inspect` commands. The [CLI reference](../cli.md) lists each command's accepted flags. ## Relocate backend definitions Custom backends no longer belong in Scriptorium's application configuration. Move them into a selected Promptkit framework source file. For example, move this old application section: ```yaml backends: local-gpu: endpoint: http://localhost:11434/v1 api_key_env: LOCAL_GPU_API_KEY ``` to `framework/backends.yml`: ```yaml backends: local-gpu: endpoint: http://localhost:11434/v1 api_key_env: LOCAL_GPU_API_KEY ``` Then select that file in `promptkit_sources`. Keep only the environment variable name in `api_key_env`; never put the credential value in a file or command line. ## Convert embedded identities to mapping keys Prompt, version, profile, and backend IDs are mapping keys. Old embedded `id`, `version`, and `base_profile` fields are not accepted. Change a standalone prompt definition such as: ```yaml id: meeting.summary version: "1.0.0" messages: - role: user content: Summarize this synthetic note. output: format: text validation_mode: none ``` to keyed definitions: ```yaml prompts: meeting.summary: "1.0.0": messages: - role: user content: Summarize this synthetic note. output: format: text validation_mode: none ``` Retain the other valid definition content from your source. Likewise, replace profile `base_profile: common` with `extends: common` inside the profile mapping. `extends` names an exact sibling profile ID. It is resolved while sources are composed, before Promptkit validates the final definitions. For example, move an old standalone profile: ```yaml id: fast base_profile: common timeout_seconds: 30 ``` under its keyed mapping and rename the inheritance field: ```yaml profiles: fast: extends: common timeout_seconds: 30 ``` ## Review presence, null, and map values Omitted values inherit or receive defaults; an explicit value can override them even when it is `0`, `false`, or an empty string. For example, `max_tokens: 0` is an explicit provider control, not omission. `null` is field-specific: for example, a null `model` is unspecified, null `timeout_seconds` restores its 600-second default, and null `extra_params` clears the configured provider map. Check each field in the format reference before converting old defaults or sentinel values. For example, express the intended behavior directly: ```yaml profiles: explicit-zero: temperature: 0 leave-temperature-unset: model: explicit-model overlay-provider-options: extra_params: provider_option: local clear-provider-options: extra_params: null ``` Maps overlay recursively. An empty map does not erase keys inherited from a parent or backend; use `extra_params: null` to suppress the configured map. If changing only a model or backend, review other inherited fields because they can remain effective. Do not infer inheritance or replacement from the old loader's behavior. ## Validate without a provider call `scriptorium config validate --config PATH` validates Scriptorium's application configuration, including selector shape, but does not open framework sources. Then run `scriptorium inspect configuration validate --config PATH` to build the engine and validate all selected Promptkit definitions, including unused ones. It does not prepare a request, resolve credentials, contact a provider, or load request-time schemas and artifacts. A running `serve` process captures its configuration and message content at startup; restart it after changing those inputs. See the [configuration](../config.md) and [operations](../operations.md) contracts for path ownership and runtime boundaries.