Retire the legacy CLI and document native operator workflows

This commit is contained in:
2026-11-20 05:08:40 +00:00
parent 10387d4aea
commit bd7136ceeb
52 changed files with 846 additions and 7067 deletions

View File

@@ -1,33 +1,23 @@
# Upgrade PromptKit Sources And Definitions
This guide covers the CLI and framework configuration cutover to
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.
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
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).
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
@@ -82,9 +72,9 @@ Convert framework source controls from `configkit:` to `config:` and add
header, if present, is `version: 2`. Use sibling inheritance such as
`extends: {id: base}`.
Across ordered `promptkit_sources` entries, a later framework underlay replaces
the whole record for the same ID. Supply the complete intended replacement,
or create a distinct inherited record. Checkouts imported by the same
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.
@@ -106,5 +96,5 @@ 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
The [CLI reference](../cli.md) defines qualified selection and prepared preview; the
[operations guide](../operations.md) describes when updates take effect.