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

@@ -11,6 +11,7 @@ and the HTTP service according to the boundary your application needs.
- CLI subprocess: [subprocess integration](../integrations/subprocess.md)
- HTTP service: [HTTP API reference](../api.md)
- Application configuration: [configuration reference](../config.md)
- Existing CLI callers: [native CLI migration](upgrading-cli.md)
Go applications that need an in-process prompt framework should import
`go.maximumdirect.net/promptkit` directly. The tagged
@@ -27,7 +28,7 @@ Consumers are responsible for:
- supplying required inputs and template variables;
- supplying credentials through the chosen interface;
- protecting rendered prompts and generated artifacts as potentially
sensitive;
sensitive, including native inspection and full result reports;
- deciding whether validation-failed output is usable; and
- retrying only when another model call is acceptable.

View File

@@ -0,0 +1,95 @@
# Migrate To The Native CLI
This guide covers Scriptorium's breaking CommandKit-native CLI cutover. It does
not select a release version or change historical release notes. The
[CLI reference](../cli.md) owns current syntax, streams, and statuses;
[configuration](../config.md) owns source discovery and settings.
The earlier [PromptKit upgrade](upgrading-promptkit.md) covers framework formats,
not a compatibility layer for this interface.
## Replace Commands And Selections
| Former interface | Current interface |
| --- | --- |
| `run --prompt ID` / `--prompt-id` | `run ID`; exactly one positional prompt ID. |
| `render --prompt ID` | `promptkit show prepared ID`. |
| `inspect prompt --prompt ID` | `promptkit show prompt ID`. |
| `inspect profile --profile ID` | `promptkit show profile ID`. |
| `inspect configuration ...` | Native `config ... --scope promptkit`. |
| Application `config ...` | Native `config ... --scope app` (the default scope), including diff. |
| `--config-overlay` | `--overlay NAME`; a native overlay name, not an arbitrary path. |
| `--input NAME=PATH` | `--input-file NAME=PATH`; `--input` now means literal text. |
| `--llm-base-url` | `--endpoint` (canonical `--llm-endpoint`). |
| Duration-valued `--timeout` | Integer `--timeout-seconds` for each generation attempt. |
| `--out` / output-file flags | Caller stdout redirection. |
| `--execution-report` | `--report PATH` with native result rendering. |
Prefer native short aliases such as `--profile`, `--var`, `--input-text`, and
`--input-file`; canonical `--llm-*` spellings remain available.
There is no duplicate prompt flag, direct backend-ID override, or retained
`--profile-id` alias on generation.
Repeat mappings rather than comma-separating them. The first equals sign splits
each mapping; commas and later equals signs are literal. Input text/file
occurrences share native last-occurrence precedence.
## Migrate Application Configuration
Replace the source-selector list and top-level schema directory with
`promptkit.configuration` and `promptkit.schema_dir`.
The [maintained example](../../examples/config.yml) selects a separate framework
entry file that imports prompt/profile/backend definitions through native
ConfigKit composition. No source/schema CLI flags or compatibility conversion
remain. Do not embed framework definitions inside the application section.
Discovery now uses native cwd, user-config, home, then Unix-system presets and
their filename conventions. It is no longer limited to the two former
`config.yml` paths. Set an explicit config path when migrating unattended jobs.
Overlays remain native name selections. Application-scope native `--set` records
retain conflict rejection; order does not make duplicate paths authoritative.
There are no custom source/schema/HTTP selectors under `config`.
## Capture Artifacts And Reports
For an artifact file plus full native report, from the repository root:
```sh
scriptorium run generic.markdown_summary --config examples/config.yml \
--input-file transcript=examples/fixtures/transcript.md \
--input-file glossary=examples/fixtures/glossary.yml \
--report run-result.json --report-format json > summary.md
```
This generation example contacts the configured provider. Use native prepared
preview instead when only checking inputs/settings.
Main automatic/text output is the artifact alone, with no added newline.
Main JSON/YAML is the native result; artifact bytes use native structured
serialization. Separate reports contain that full native result, not the old
observer-derived metadata shape. `--report-format` independently chooses
text/YAML/JSON; omission leaves the format unset for native automatic rendering
(currently YAML for structured values). Extensions do not select formats.
Omit quiet to capture main output, including redirected stdout. Quiet still
allows an explicitly requested report file. Reports are available only when a
result is returned; resultless failures do not replace an existing report.
Partial delivery can leave one or both destinations written. Keep paths separate
and check status/diagnostics before treating files as fresh.
## Adjust Status And Sensitivity Handling
Completed generated-content validation failure is now domain status 4, not the
old status 2. Native usage/invalid-configuration input is 2, diff-check
differences are 3, and operational failures are 1. Presentation/file failures
can change success into failure while preserving an already nonzero domain
classification. The [CLI status table](../cli.md#server-and-statuses) owns details.
Native prompt inspection includes messages; prepared reports include rendered
content; full run reports include generated content and metadata. Framework
classified-field redaction does not make arbitrary report data safe to expose.
Requirements discovery is separate from validation/preparation: it can run
before artifacts exist, and a partial report may succeed. Read its native
completeness/issue fields. Smoke tests are explicit provider operations, not
startup checks. See [subprocess guidance](../integrations/subprocess.md) for
stream capture, cancellation, and caller responsibilities.

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.