Retire the legacy CLI and document native operator workflows
This commit is contained in:
487
docs/cli.md
487
docs/cli.md
@@ -1,377 +1,186 @@
|
||||
# CLI Reference
|
||||
|
||||
This is the canonical contract for invoking Scriptorium. Configuration discovery,
|
||||
precedence, application source locations, and server settings are defined in the
|
||||
[configuration reference](config.md). The [HTTP API reference](api.md) owns
|
||||
service request and response behavior.
|
||||
|
||||
## Shortest Useful Command
|
||||
|
||||
```bash
|
||||
go run ./cmd/scriptorium render \
|
||||
--config ./examples/config.yml \
|
||||
--prompt generic.markdown_summary \
|
||||
--input transcript=./examples/fixtures/transcript.md \
|
||||
--input glossary=./examples/fixtures/glossary.yml
|
||||
```
|
||||
|
||||
`render` prepares a request without calling an LLM.
|
||||
Scriptorium uses CommandKit v0.7.0, ckconfig v0.9.0, and ckprompt v0.10.0.
|
||||
This document owns application invocation and delivery behavior. The pinned
|
||||
[upstream CLI contract][native-cli] owns standard family grammar and reports.
|
||||
[Configuration](config.md) owns discovery, settings, and source composition;
|
||||
the [HTTP API](api.md) owns the service contract.
|
||||
Existing callers should read the [CLI migration guide](consumers/upgrading-cli.md).
|
||||
|
||||
## Commands
|
||||
|
||||
- `scriptorium run`: prepare a prompt, call the configured LLM, and write the
|
||||
generated artifact.
|
||||
- `scriptorium render`: prepare a prompt and write prepared-run output.
|
||||
- `scriptorium serve`: start the HTTP server.
|
||||
- `scriptorium inspect prompt`: inspect one prompt definition without model execution.
|
||||
- `scriptorium inspect profile`: inspect one resolved profile without model execution.
|
||||
- `scriptorium inspect configuration`: validate or inspect Promptkit's captured framework configuration.
|
||||
- `scriptorium config validate`: validate application configuration without building an engine.
|
||||
- `scriptorium config show`: show the resolved application configuration.
|
||||
- `scriptorium config sources`: show the ordered configuration sources.
|
||||
- `scriptorium config explain`: explain one effective or historical configuration path.
|
||||
|
||||
All command families accept `--config <path>` and `--config-overlay <name>`;
|
||||
positional arguments are rejected. `--config-overlay` selects one application
|
||||
configuration overlay; it is separate from `--profile`, which selects a
|
||||
Promptkit execution profile. See [configuration composition](config.md#explicit-imports-and-selected-overlays)
|
||||
for name, root, and absent-main behavior. `run`, `render`, `serve`, `inspect prompt`,
|
||||
`inspect profile`, and `inspect configuration` accept repeated
|
||||
`--promptkit-source <path>` flags and `--schema-dir <dir>` where applicable.
|
||||
They replace the configured source sequence in flag order. `--prompt-dir` and
|
||||
`--profile-dir` are no longer supported; use `promptkit_sources` in application
|
||||
configuration or the repeated source flags. Application `config` commands
|
||||
remain independent of framework source loading. Explicit application flags,
|
||||
including empty values, override file settings. Configuration load diagnostics
|
||||
go to stderr and exit with status 1; successful load warnings are printed once
|
||||
before command work.
|
||||
|
||||
## `scriptorium run`
|
||||
|
||||
```text
|
||||
scriptorium run [flags]
|
||||
```
|
||||
|
||||
Required flags:
|
||||
|
||||
| Flag | Meaning |
|
||||
| --- | --- |
|
||||
| `--prompt <id>` | Prompt ID to execute. |
|
||||
|
||||
Optional flags:
|
||||
|
||||
| Flag | Meaning |
|
||||
| --- | --- |
|
||||
| `--config <path>` | Application configuration file. |
|
||||
| `--config-overlay <name>` | Selected application configuration overlay. |
|
||||
| `--promptkit-source <path>` | PromptKit source file or directory; repeat to select ordered sources. |
|
||||
| `--schema-dir <dir>` | Schema base-directory override. |
|
||||
| `--profile <id>` | Execution-profile override. |
|
||||
| `--session-id <id>` | Optional direct session identifier. |
|
||||
| `--input name=path` | Optional input file mapping; repeat or use comma-separated mappings. |
|
||||
| `--var name=value` | Template-variable mapping; repeat or use comma-separated mappings. |
|
||||
| `--out <path>` | Write generated content to this file instead of stdout. |
|
||||
| `--execution-report <path>` | Write an opt-in terminal execution report as newline-terminated JSON to a separate file. |
|
||||
| `--llm-base-url <url>` | Runtime endpoint override. |
|
||||
| `--model <name>` | Runtime model override. |
|
||||
| `--api-key-env <name>` | Runtime API-key environment-variable name override. |
|
||||
| `--temperature <float>` | Runtime temperature override. |
|
||||
| `--max-tokens <int>` | Runtime maximum-token override. |
|
||||
| `--top-p <float>` | Runtime top-p override. |
|
||||
| `--reasoning-effort <value>` | Runtime reasoning-effort override. |
|
||||
| `--timeout <duration>` | Runtime timeout override using Go duration syntax. |
|
||||
| `--run-timeout <duration>` | Optional whole-run engine deadline using Go duration syntax; zero or omission adds no deadline, negative values are invalid. |
|
||||
| `--transient-retries <integer>` | Nonnegative additional transient attempt count for this request; `0` disables additional attempts. |
|
||||
|
||||
Deprecated aliases: `--prompt-id` for `--prompt`, and `--profile-id` for
|
||||
`--profile`.
|
||||
|
||||
Omitted numeric runtime flags preserve the selected effective value; explicit
|
||||
zero values override it. `--timeout 0s` disables the per-attempt generation deadline
|
||||
only; the caller context and configured transport cap remain active. CLI
|
||||
durations are converted to whole seconds by truncation toward zero, so any
|
||||
duration whose absolute value is below one second becomes an explicit
|
||||
zero-second override. The timeout layers are defined in the
|
||||
[Promptkit outbound integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation).
|
||||
With the built-in client, each transient retry gets a fresh generation timeout;
|
||||
this flag does not limit the complete run.
|
||||
`--run-timeout` keeps subsecond precision and starts immediately before engine
|
||||
execution. It bounds preparation, capacity waits, retry waits, generation, and
|
||||
repairs where they honor context. Parsing, engine construction, and output
|
||||
writes are outside that interval. A failed run identified by PromptKit as an
|
||||
operation timeout exits 1 with a safe deadline diagnostic; a completed invalid
|
||||
output still exits 2. Synchronous work may not stop immediately.
|
||||
Omitting `--transient-retries` inherits the application setting or Promptkit's
|
||||
current default of two additional attempts. The flag overrides only this
|
||||
request; it does not alter the configured engine. Structural repair generations
|
||||
have separate transient retry budgets.
|
||||
|
||||
There is no raw API-key flag. Use `--api-key-env`.
|
||||
|
||||
Prompt and profile IDs are passed unchanged, including collection-qualified
|
||||
IDs. The removed `--prompt-version` flag is rejected. `--input` is optional
|
||||
at the CLI boundary: PromptKit decides whether the selected definition requires
|
||||
declared inputs or template-referenced values.
|
||||
|
||||
`--session-id` supplies a direct, non-secret session identifier. A nonblank
|
||||
value replaces a definition-rendered session ID; an omitted or blank value lets
|
||||
the definition supply one. Promptkit trims direct values and limits them to 256
|
||||
Unicode code points. Use stable, non-sensitive identifiers because effective
|
||||
session IDs may appear in prepared output, run metadata, and provider-facing
|
||||
requests.
|
||||
|
||||
`--reasoning-effort` is presence-aware: omitting it inherits the selected
|
||||
profile value, a nonblank value replaces that value, and
|
||||
`--reasoning-effort=` explicitly clears inherited reasoning. Promptkit treats
|
||||
nonblank values as provider-specific opaque strings.
|
||||
|
||||
### Execution report file
|
||||
|
||||
`--execution-report` requires a nonempty path. It is available only for `run`;
|
||||
`-` is an ordinary filename. Parent directories are not created. An existing
|
||||
file is replaced through ordinary file writing, without rollback or an atomic
|
||||
replacement guarantee. Generated content still goes to stdout or `--out`.
|
||||
Equal output/report paths, including existing paths that refer to the same
|
||||
file, are rejected before execution.
|
||||
|
||||
The file is written after engine execution when Promptkit supplies a terminal
|
||||
event, including for a failed run or invalid generated output. A failure before
|
||||
invocation leaves the report path untouched. If no terminal event is supplied,
|
||||
Scriptorium leaves the path untouched and emits a diagnostic; an existing file
|
||||
may therefore contain an older report. Artifact output is attempted first on a
|
||||
successful run, and report writing is attempted even if artifact writing fails.
|
||||
Any output or report write failure exits 1; already-written output is not
|
||||
undone. Without a write failure, the actual run keeps its usual exit status.
|
||||
|
||||
The [HTTP API reference](api.md#execution-report) defines the shared report
|
||||
fields and usage-presence semantics. The file contains that JSON object followed
|
||||
by a newline.
|
||||
|
||||
The report excludes content, credentials, URLs, headers, and raw errors, but
|
||||
its identifiers can still be sensitive. The caller owns file retention and
|
||||
access.
|
||||
|
||||
## `scriptorium render`
|
||||
|
||||
```text
|
||||
scriptorium render [flags]
|
||||
```
|
||||
|
||||
`--prompt <id>` is required. The following optional flags are supported:
|
||||
`--config`, `--config-overlay`, repeatable `--promptkit-source`, `--schema-dir`, `--profile`,
|
||||
`--input`, `--var`, `--out`, `--llm-base-url`,
|
||||
`--model`, `--api-key-env`, `--temperature`, `--max-tokens`, `--top-p`,
|
||||
`--reasoning-effort`, `--session-id`, `--timeout`, `--transient-retries`, and `--format text|json`. Their meanings match the corresponding
|
||||
`run` flags; `--format` selects prepared-run output and otherwise uses
|
||||
`defaults.render_format`.
|
||||
|
||||
The same deprecated aliases and numeric/timeout behavior as `run` apply.
|
||||
The same session and reasoning inheritance, replacement, and clearing behavior
|
||||
also applies.
|
||||
`render` validates the retry override but does not generate model output or
|
||||
include a retry field in prepared output.
|
||||
`render` resolves profiles and schemas as part of preparation but
|
||||
does not call an LLM.
|
||||
|
||||
To render from independently maintained collection checkouts:
|
||||
|
||||
```bash
|
||||
go run ./cmd/scriptorium render --config ./examples/config.discovery.yml \
|
||||
--prompt support/answer --profile support/fast \
|
||||
--input transcript=./examples/fixtures/transcript.md
|
||||
```
|
||||
|
||||
The [discovery example](../examples/discovery/framework.yml) also provides
|
||||
`review/answer`; see [configuration discovery](config.md#collection-checkout-discovery).
|
||||
|
||||
## `scriptorium serve`
|
||||
|
||||
```text
|
||||
scriptorium run PROMPT_ID [flags]
|
||||
scriptorium serve [flags]
|
||||
scriptorium config scopes
|
||||
scriptorium config validate|show|sources|explain|diff [flags]
|
||||
scriptorium promptkit list prompts|profiles|backends|namespaces|collections [flags]
|
||||
scriptorium promptkit show prompt|profile|backend ID [flags]
|
||||
scriptorium promptkit requirements show|validate PROMPT_ID [flags]
|
||||
scriptorium promptkit show prepared PROMPT_ID [flags]
|
||||
scriptorium promptkit test KIND [flags]
|
||||
scriptorium help [COMMAND ...]
|
||||
scriptorium version
|
||||
scriptorium completion bash|zsh|fish
|
||||
```
|
||||
|
||||
Optional flags:
|
||||
Native help is also available with `--help`. Help, version, scope discovery,
|
||||
and static completion do not load configuration or contact a provider.
|
||||
Version/revision metadata is supplied by the build; ordinary builds identify
|
||||
themselves as `dev` with no revision. Release build mechanics belong to the
|
||||
[release procedure](release.md).
|
||||
|
||||
Commands that consume configuration accept `--config PATH` and `--overlay NAME`.
|
||||
An explicitly empty config value remains explicit; overlay names follow
|
||||
[ConfigKit selection](config.md#explicit-imports-and-selected-overlays).
|
||||
There are no source/schema convenience flags or legacy command aliases.
|
||||
Native shared `--format`, `--quiet`, `--verbose`, `--debug`, and progress
|
||||
controls retain their upstream meanings. Diagnostics use stderr, not stdout.
|
||||
Verbose exposes emitted Info and Warning messages without changing result bytes.
|
||||
|
||||
## Generation
|
||||
|
||||
`run` requires exactly one positional prompt ID. It has no duplicate prompt
|
||||
flag or direct backend-selection flag; choose a profile for backend routing.
|
||||
It uses these native bindings, with the preferred aliases below. Canonical
|
||||
spellings prepend `llm-` (for example, `--llm-profile`).
|
||||
|
||||
| Preferred flags | Meaning |
|
||||
| --- | --- |
|
||||
| `--profile ID`, `--session-id ID` | Profile selection and optional non-secret session context. |
|
||||
| `--var KEY=VALUE` | Repeatable caller-variable mappings. |
|
||||
| `--input-text NAME=TEXT`, `--input NAME=TEXT` | Repeatable literal input mappings; `--llm-input` is also a literal-text alias. |
|
||||
| `--input-file NAME=PATH` | Repeatable file references. |
|
||||
| `--endpoint URL`, `--model NAME` | Native endpoint/model overrides. |
|
||||
| `--temperature N`, `--max-tokens N`, `--top-p N` | Presence-aware numeric overrides, including zero. |
|
||||
| `--timeout-seconds N` | Integer per-attempt generation timeout; zero disables that deadline, not caller cancellation or the transport cap. |
|
||||
| `--reasoning-effort VALUE`, `--service-tier VALUE` | Native provider controls; an explicit empty reasoning value is preserved. |
|
||||
| `--api-key-env NAME` | Credential environment-variable name, never raw key bytes. |
|
||||
| `--extra-params JSON` | Native JSON-object provider parameters. |
|
||||
| `--transient-retries N` | Request retry override; omission leaves the engine default. |
|
||||
| `--prompt-namespace NAME`, `--profile-namespace NAME`, `--backend-namespace NAME` | Independent native namespace views. Qualified resource IDs remain exact; stored references are not rewritten. |
|
||||
|
||||
Mappings split at the first `=`; commas and subsequent equals signs are literal.
|
||||
Repeat flags for multiple mappings. The last text/file occurrence for the same
|
||||
input wins in command-line order. PromptKit validates selected definitions,
|
||||
inputs, namespaces, provider settings, and credential requirements; Scriptorium
|
||||
does not add an execution-readiness preflight or configurable default namespace.
|
||||
Native string/pointer override semantics remain upstream-owned.
|
||||
|
||||
Application-owned generation controls:
|
||||
|
||||
| Flag | Meaning |
|
||||
| --- | --- |
|
||||
| `--config <path>` | Application configuration file. |
|
||||
| `--config-overlay <name>` | Selected application configuration overlay. |
|
||||
| `--addr <listen-address>` | HTTP listen-address override. |
|
||||
| `--promptkit-source <path>` | PromptKit source file or directory; repeat to select ordered sources. |
|
||||
| `--schema-dir <dir>` | Schema base-directory override. |
|
||||
| `--artifact-root <dir>` | Root for HTTP `file` input references. |
|
||||
| `--max-request-bytes <n>` | Maximum encoded HTTP request-body bytes; `0` disables the limit. |
|
||||
| `--max-artifact-bytes <n>` | Maximum HTTP file-input artifact bytes; `0` disables the limit. |
|
||||
| `--max-response-bytes <n>` | Maximum encoded HTTP response bytes; `0` disables the limit. |
|
||||
| `--run-timeout DURATION` | Go duration passed unchanged to PromptKit's operation budget. Positive values cover engine preparation/execution, including cooperative waits and repairs. Zero, omission, and negative values add no budget. Parsing, configuration/engine setup, and delivery are outside it. |
|
||||
| `--report PATH` | Additionally write the returned native result to a separate file. |
|
||||
| `--report-format text\|yaml\|json` | Explicit separate-report format; omission leaves native automatic rendering selected. |
|
||||
|
||||
`serve` accepts no runtime model override flags. HTTP request fields, response
|
||||
schemas, and error codes are defined in the [HTTP API reference](api.md).
|
||||
The operation budget is independent of the integer per-attempt timeout.
|
||||
Earlier parent cancellation/deadlines still apply. Cancellation is cooperative;
|
||||
synchronous work that ignores context cannot be forcibly interrupted.
|
||||
|
||||
## `scriptorium inspect prompt`
|
||||
### Results And Separate Reports
|
||||
|
||||
```text
|
||||
scriptorium inspect prompt --prompt ID
|
||||
[--config PATH] [--config-overlay NAME] [--promptkit-source PATH ...] [--schema-dir DIR] [--format text|json] [--out PATH]
|
||||
```
|
||||
The main report goes through the invocation reporter to stdout. Automatic/text
|
||||
output is exactly `Artifact.Body`, with no added newline, header, escaping, or
|
||||
summary. JSON/YAML output is the full native PromptKit `RunResult`, without a
|
||||
Scriptorium envelope. In native structured serialization, artifact bytes use
|
||||
the upstream representation (JSON base64), not an application text projection.
|
||||
|
||||
`--prompt` is required. Inspection uses normal configuration discovery and the
|
||||
selected Promptkit sources, defaults to text regardless of
|
||||
`defaults.render_format`, and writes to stdout unless `--out` is supplied.
|
||||
Save main output with shell redirection or the subprocess stdout destination.
|
||||
There is no `--output` or `--out` flag. Omit `--quiet` when capturing the main
|
||||
result: native quiet suppresses it even when stdout is redirected.
|
||||
|
||||
Both definition-inspection commands first construct the same engine used for
|
||||
execution from the complete selected source sequence. Construction resolves
|
||||
and validates all effective definitions, including unused ones, and captures
|
||||
referenced message-file contents and static template syntax. Invalid unused
|
||||
definitions or unreadable message resources can therefore prevent inspection.
|
||||
No prompt collection is mandatory, but selected prompts are not ignored.
|
||||
`--report` renders the same result through CommandKit without the artifact-only
|
||||
text template. Its format is independent of stdout's `--format` and the filename
|
||||
extension. Omission passes an unset format to the upstream renderer; it currently
|
||||
renders structured values as YAML in automatic/text mode. Choose an explicit
|
||||
format when required rather than relying on that upstream default.
|
||||
|
||||
Inspection does not prepare an execution request, load request-time schemas or
|
||||
artifacts, resolve credential values, reserve backend capacity, or call a model.
|
||||
Prompt inspection does not select an execution profile or render request-specific
|
||||
templates.
|
||||
Prompt output includes ID, hash, optional default profile and input metadata,
|
||||
and the output contract. Absent optional values are omitted; explicitly empty
|
||||
or zero values are retained. Captured message text is not projected.
|
||||
The requested file is written even in quiet mode. Omission creates no separate
|
||||
report. An explicitly empty path is a usage error before generation; `-` is an
|
||||
ordinary filename. New files use mode 0644 subject to umask, existing files use
|
||||
normal OS replacement behavior, and parent directories are not created.
|
||||
Render, write, and close failures are reported.
|
||||
|
||||
## `scriptorium inspect profile`
|
||||
Only a returned result is eligible for delivery. A resultless failure leaves an
|
||||
existing report untouched; it does not synthesize an invocation-error result.
|
||||
Main delivery is attempted first, then the requested report even if main
|
||||
delivery fails. Writes are nontransactional; bytes already written remain.
|
||||
Callers own redirected paths, retention, and keeping main and report destinations
|
||||
separate. A shell may truncate its redirected file before the process starts.
|
||||
|
||||
```text
|
||||
scriptorium inspect profile --profile ID
|
||||
[--config PATH] [--config-overlay NAME] [--promptkit-source PATH ...] [--schema-dir DIR] [--format text|json] [--out PATH]
|
||||
```
|
||||
## Application Configuration Inspection
|
||||
|
||||
`--profile` is required. After the [full-source engine construction described
|
||||
above](#scriptorium-inspect-prompt), inspection selects one resolved profile
|
||||
with inheritance. `profile_model_params` contains only fields present on that
|
||||
profile; it does not fill backend defaults. `api_key_required` is a separate
|
||||
optional field. Explicit zero and empty values remain visible. Use `render`
|
||||
for request-completed model settings.
|
||||
The native `config` family defaults to `app`; select `--scope promptkit` for
|
||||
captured framework configuration or use native scope discovery/all-scope modes.
|
||||
`app` uses the actual completed ConfigKit result and does not construct an engine.
|
||||
|
||||
## Application configuration inspection
|
||||
Native `--set POINTER=JSON` is enabled only for `app`. Records go directly to
|
||||
ConfigKit: duplicate and ancestor/descendant-overlapping paths are rejected,
|
||||
not resolved by flag order. No application-specific configuration flags or
|
||||
custom `--against-*` counterparts are installed.
|
||||
|
||||
```text
|
||||
scriptorium config validate [flags]
|
||||
scriptorium config show [flags]
|
||||
scriptorium config sources [flags]
|
||||
scriptorium config explain --path JSON_POINTER [flags]
|
||||
```
|
||||
Native diff uses independent `--against-config`, `--against-overlay`, and
|
||||
supported `--against-set` selections. Omitted right-side values do not inherit
|
||||
the left side. See the [upstream contract][native-cli] for focused paths,
|
||||
metadata discovery, source IDs, findings, explanations, and detailed comparisons.
|
||||
|
||||
Each accepts `--config`, `--config-overlay`, `--schema-dir`, `--addr`,
|
||||
`--artifact-root`, `--max-request-bytes`,
|
||||
`--max-artifact-bytes`, and `--max-response-bytes`. These are application
|
||||
configuration selectors and overrides; request, credential, backend-editing,
|
||||
output-format, and output-file flags are not accepted. Positional arguments
|
||||
are rejected.
|
||||
## Framework Configuration Inspection
|
||||
|
||||
`validate` writes no success output; status 0 means the application configuration
|
||||
loaded and passed its own validation. It does not establish that selected
|
||||
Promptkit sources can construct an engine, credentials are present, or a
|
||||
provider is available. `show` writes ConfigKit's resolved YAML snapshot. `sources`
|
||||
writes one newline-terminated JSON array of source records in load order. Each
|
||||
record has `id`, `label`, and `layer`, plus `path` when available. Application
|
||||
main-file and import records use the `main` layer; explicit CLI
|
||||
overrides appear as synthetic sources. Defaults-only input without overrides
|
||||
produces `[]` for `sources`.
|
||||
The `promptkit` config scope loads application settings selected by `--config`
|
||||
and `--overlay`, constructs an engine, and exposes its captured native view.
|
||||
It does not accept temporary overrides; native capability checks also apply
|
||||
when an all-scope operation requests them.
|
||||
|
||||
`explain` requires an explicitly supplied `--path` in JSON Pointer syntax.
|
||||
The empty string selects the root; `/server/addr` selects a field; `~1` and
|
||||
`~0` escape `/` and `~` inside mapping keys. Numeric tokens are interpreted
|
||||
according to the containing mapping or sequence. Dotted paths, file paths,
|
||||
and URL fragments are not accepted. ConfigKit writes a human-readable account
|
||||
of the effective value and its chronological default, file/import, overlay,
|
||||
CLI, normalization, and removed-value history. This is not a JSON schema or a
|
||||
byte-for-byte stable prose format. Unknown and malformed paths exit 1 without
|
||||
successful explanation output.
|
||||
Framework effective/explanation views retain native classified-field redaction,
|
||||
including history. Environment-reference names and ordinary values remain
|
||||
visible. This is not arbitrary secret detection and does not redact all prompt,
|
||||
prepared, application, or generated content. Protect reports accordingly.
|
||||
|
||||
Diagnostics and warnings go to stderr, never into successful stdout. Parse,
|
||||
load, output, and diagnostic-write failures exit 1. Ordinary output writes may
|
||||
leave partial data on failure. Application inspection can contain paths and
|
||||
configured values; protect its output accordingly. Raw API-key values are not
|
||||
accepted by the application configuration schema.
|
||||
## Discovery, Preview, And Explicit Smoke Testing
|
||||
|
||||
## Framework configuration inspection
|
||||
Inventories retain native defaults and `--namespace`/`--all-namespaces` filters.
|
||||
Named inspections expose native prompt messages and profile/backend values;
|
||||
prepared preview exposes rendered content, not a summary projection.
|
||||
|
||||
```text
|
||||
scriptorium inspect configuration validate [flags]
|
||||
scriptorium inspect configuration show [flags]
|
||||
scriptorium inspect configuration sources [flags]
|
||||
scriptorium inspect configuration explain --path JSON_POINTER [flags]
|
||||
```
|
||||
Requirements discovery works before input artifacts exist and without schema
|
||||
loading, credential resolution, message rendering, or provider access. It still
|
||||
loads configuration and captured message resources. Reports preserve exact names,
|
||||
metadata, variable presence (including empty values), completeness, and issue
|
||||
codes. Partial discovery may succeed with status zero; completeness is not
|
||||
binding satisfaction or execution readiness. Concrete validation and preview
|
||||
keep their native preparation-time prerequisites and make no generation call.
|
||||
|
||||
Each operation accepts `--config`, `--config-overlay`, repeatable
|
||||
`--promptkit-source`, and `--schema-dir`. These flags select the application
|
||||
settings and framework sources; positional arguments, `--format`, and `--out`
|
||||
are not accepted. Unlike `config validate`, framework `validate` constructs
|
||||
the Promptkit engine and validates all effective definitions, including
|
||||
unused ones. It writes nothing on success and does not prepare a request,
|
||||
resolve a credential, or contact a provider.
|
||||
Smoke-test kinds are `reachability`, `authentication`, `text_inference`,
|
||||
`structured_output`, or `all`, with native aliases as documented upstream.
|
||||
These explicit commands may contact providers and incur cost. Their presence
|
||||
does not add a startup/provider probe. Read the native findings: unsuccessful or
|
||||
unsupported checks are not automatically invocation failures.
|
||||
|
||||
`show` writes Promptkit's native effective YAML, an inspection snapshot rather
|
||||
than a promised reloadable file. `sources` writes a
|
||||
newline-terminated JSON array in captured source order. Each source record has
|
||||
`id`, `label`, `layer`, `kind`, and `underlay_index`, plus `path` when available
|
||||
and `imported_from` for imported sources. That nested object has `source_id`,
|
||||
`line`, and `column`. Values and output structure are a projection of the
|
||||
captured Promptkit view, not Scriptorium's application-source records.
|
||||
## Server And Statuses
|
||||
|
||||
`explain` requires an explicitly supplied `--path` in ConfigKit JSON Pointer
|
||||
syntax; `--path ''` selects the root. For example,
|
||||
`/collections/support/profiles/0/model` addresses the first support profile's
|
||||
model in the captured list. Escape `/` as `~1` and `~` as `~0`; dots in a key
|
||||
remain literal. Malformed and unknown pointers exit 1 without a successful
|
||||
report. Explanation prose is native and is not a stable machine-readable
|
||||
format.
|
||||
`serve` accepts configuration selection and presence-aware HTTP controls:
|
||||
`--addr`, `--artifact-root`, `--max-request-bytes`, `--max-artifact-bytes`,
|
||||
and `--max-response-bytes`. It has no generation request controls. Values and
|
||||
defaults belong to [configuration](config.md).
|
||||
|
||||
Framework `show` and `explain` use Promptkit's native redaction for its
|
||||
classified credential-shaped provider fields, including historical values.
|
||||
Environment-variable reference names and ordinary provider parameters remain
|
||||
visible. Arbitrary prompt or provider content is not classified as secret by
|
||||
name inspection, so treat these reports as sensitive. This redaction policy is
|
||||
limited to framework configuration reports; it does not add redaction to
|
||||
`inspect profile` or prepared-run output. Credentials are not resolved by any
|
||||
of these inspection operations. Promptkit owns detailed field and source
|
||||
semantics; see its tagged [format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md).
|
||||
|
||||
Warnings and errors go to stderr. Successful `validate` writes nothing to
|
||||
stdout; successful `show`, `sources`, and `explain` write their reports there.
|
||||
Parse, load, path, and output failures exit 1. A native writer error may leave
|
||||
partial output.
|
||||
|
||||
## Input And Variable Syntax
|
||||
|
||||
`--input name=path` maps an input name to a local file; `--var name=value`
|
||||
maps a template variable to a string. Both flags can be repeated or contain
|
||||
comma-separated mappings. Values may contain `=` after the first separator.
|
||||
Empty names and values are rejected.
|
||||
|
||||
CLI inputs are file references. HTTP inline inputs are defined by the
|
||||
[HTTP API reference](api.md).
|
||||
|
||||
## Output And Exit Behavior
|
||||
|
||||
- `run` writes generated content to stdout, or to `--out` when supplied, and
|
||||
writes a concise summary to stderr. The summary includes `backend=<id>` when
|
||||
Promptkit selected a backend; endpoint-only profiles omit it.
|
||||
- `render` writes prepared-run output to stdout, or to `--out` when supplied,
|
||||
without a success summary. Text output includes `selected_backend_id` after
|
||||
`selected_profile_id` when Promptkit selected one; endpoint-only profiles
|
||||
omit it.
|
||||
- `serve` writes startup and server errors to stderr.
|
||||
|
||||
Exit statuses:
|
||||
Interrupt/SIGTERM cancels the invocation context. The server closes its listener
|
||||
and active connections; canceled shutdown returns operational status, with no
|
||||
graceful-drain deadline or guarantee that context-ignoring work has finished.
|
||||
|
||||
| Status | Meaning |
|
||||
| --- | --- |
|
||||
| `0` | Success. |
|
||||
| `1` | Parse, configuration, loading, rendering, generation, output-write, or other runtime error. |
|
||||
| `2` | `run` generated and wrote output, but validation failed. |
|
||||
| 0 | Native success, subject to successful presentation/delivery. |
|
||||
| 1 | Operational failure, including lookup/preparation/generation/capacity, cancellation/timeouts, unclassified load errors, and delivery failure for an otherwise successful run. |
|
||||
| 2 | Native usage/declaration-input errors, or configuration errors classified as invalid input by native diagnostic evidence. |
|
||||
| 3 | Native `config diff --check` found differences. |
|
||||
| 4 | Completed generation returned `ValidationFailed`; artifact and native result remain deliverable. |
|
||||
|
||||
A backend admission rejection is a runtime error and prints `run error: model
|
||||
backend capacity is exhausted`. The HTTP capacity response is defined in the
|
||||
[HTTP API reference](api.md).
|
||||
Native finalization handles presentation errors: success/usage become operational;
|
||||
an already nonzero domain outcome retains its classification/status. A report-file
|
||||
failure preserves completed-validation status 4 while adding its explanation and
|
||||
cause. An operational failure to perform validation is status 1, not status 4.
|
||||
JSON selection does not turn failures into a separate JSON error envelope.
|
||||
|
||||
## Workflows And Examples
|
||||
|
||||
The [maintained render script](../examples/render-markdown-summary.sh) is a
|
||||
copyable render workflow. The [HTTP request example](../examples/http-run.json)
|
||||
is for a running `serve` process.
|
||||
[native-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md
|
||||
|
||||
382
docs/config.md
382
docs/config.md
@@ -1,87 +1,126 @@
|
||||
# Configuration Reference
|
||||
|
||||
This is the canonical reference for Scriptorium application settings. Prompt,
|
||||
profile, backend, schema, execution-setting, built-in profile, and framework
|
||||
credential semantics are defined by the
|
||||
[PromptKit v0.23.3 format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md).
|
||||
For command syntax, see the [CLI reference](cli.md); for HTTP request shapes and
|
||||
outcomes, see the [HTTP API reference](api.md). For migration examples, see
|
||||
[Upgrading Promptkit sources and definitions](consumers/upgrading-promptkit.md).
|
||||
This document owns Scriptorium's application settings, discovery, and source
|
||||
selection. [CLI syntax](cli.md) and the [HTTP API](api.md) have separate owners.
|
||||
Framework definitions and execution semantics belong to the pinned
|
||||
[PromptKit v0.23.3 formats][formats]; ConfigKit v1.2.1 owns
|
||||
[native composition and inspection][configkit].
|
||||
|
||||
## Discovery And Precedence
|
||||
|
||||
ConfigKit assembles the selected main source, imports, and overlay, resolves
|
||||
inheritance, and decodes the result with Scriptorium's typed defaults. It then
|
||||
applies explicitly supplied application CLI values, records application
|
||||
normalization, and validates the result. Source, composition, inheritance, and
|
||||
decoding failures happen before CLI assignment and cannot be repaired by it;
|
||||
an override can correct a decoded value before application validation.
|
||||
An explicit `--config` selects that file, including an explicitly empty value
|
||||
(which fails rather than falling back). With no selection, ConfigKit searches
|
||||
these native presets in order, selecting one main file:
|
||||
|
||||
When `--config` is omitted, Scriptorium searches
|
||||
`/usr/local/etc/scriptorium/config.yml` and then `/etc/scriptorium/config.yml`.
|
||||
ConfigKit performs this ordered search for each load. If neither exists, it
|
||||
uses built-in defaults; an error in a selected candidate does not cause a
|
||||
fallback. An explicit `--config` path must exist and decode successfully,
|
||||
including when an empty path is explicitly supplied.
|
||||
| Preset | Directories in order | Filename groups |
|
||||
| --- | --- | --- |
|
||||
| WorkingDirectory | Current working directory | Named only |
|
||||
| UserConfigDirectory | Go user-config directory / `scriptorium`, then the user-config directory | Named then Generic in the application directory; Named only in the base |
|
||||
| HomeDirectory | Go home directory / `.scriptorium`, then the home directory | Named then Generic in the application directory; Named only in the base |
|
||||
| UnixSystemDirectories | `/usr/local/etc/scriptorium`, `/etc/scriptorium`, then `/etc` | Named then Generic in application directories; Named only in `/etc` |
|
||||
|
||||
The maintained [minimal configuration](../examples/config.yml),
|
||||
[complete configuration](../examples/config.full.yml),
|
||||
[composed configuration](../examples/config.composed.yml),
|
||||
[collection configuration](../examples/config.collections.yml), and
|
||||
[framework inheritance configuration](../examples/config.inheritance.yml) are
|
||||
copyable examples.
|
||||
Named means `scriptorium.yml`, then `scriptorium.yaml`. Generic means
|
||||
`config.yml`, `config.yaml`, `main.yml`, then `main.yaml`.
|
||||
ConfigKit uses native Go directory resolution (including its user-config/home
|
||||
environment behavior) and checks every filename in one directory before the next.
|
||||
Candidates are not configuration layers. Optional exhaustion uses application
|
||||
defaults; a selected-file acquisition/decoding error is terminal.
|
||||
|
||||
## Application Configuration File
|
||||
ConfigKit assembles the main, enabled imports, and selected overlay, applies its
|
||||
inheritance/composition rules, creates typed defaults and strictly decodes, applies
|
||||
explicit override records, then runs application normalization and validation.
|
||||
An override can correct a decoded value before validation, but cannot repair
|
||||
source/composition/decoding errors. The completed result is authoritative:
|
||||
runtime settings conversion does not merge, default, or normalize again.
|
||||
|
||||
Application configuration is decoded by ConfigKit v1.2.1 as strict YAML.
|
||||
Unknown fields, empty files, multiple YAML documents, and YAML aliases/anchors
|
||||
are rejected.
|
||||
An explicit empty string is a value and may clear a file-provided optional
|
||||
string. A scalar `null` is not an empty string and is rejected for non-nullable
|
||||
fields; nullable fields such as `transient_retries` retain their documented
|
||||
meaning. Raw API-key fields and unknown application fields are rejected.
|
||||
## Application Settings
|
||||
|
||||
Only explicitly supplied application CLI flags override decoded settings. Paths
|
||||
in the application document remain relative to the process working directory, not to the file's
|
||||
directory. Load diagnostics are printed safely on stderr; invalid application
|
||||
configuration exits with status 1.
|
||||
|
||||
### Promptkit source selectors
|
||||
|
||||
`promptkit_sources` is an ordered sequence of explicit Promptkit source
|
||||
selectors. Each item must set exactly one of `file` or `directory`:
|
||||
Complete copyable configurations are maintained under
|
||||
[examples](../examples/config.yml), including [full settings](../examples/config.full.yml),
|
||||
[application imports](../examples/config.composed.yml),
|
||||
[framework fragment composition](../examples/config.collections.yml),
|
||||
[collection checkout discovery](../examples/config.discovery.yml), and
|
||||
[framework inheritance](../examples/config.inheritance.yml).
|
||||
|
||||
```yaml
|
||||
promptkit_sources:
|
||||
- directory: ./examples/prompts
|
||||
- directory: ./examples/profiles
|
||||
- file: ./examples/framework/backends.yml
|
||||
schema_dir: ./examples/schemas
|
||||
promptkit:
|
||||
configuration: ./examples/promptkit.yml
|
||||
schema_dir: ./examples/schemas
|
||||
```
|
||||
|
||||
An empty or null final resolved `promptkit_sources` list selects no
|
||||
application-supplied framework sources; PromptKit's bundled OpenRouter underlay
|
||||
still applies. A later sequence item overlays an earlier
|
||||
one. Files within a selected directory are composed together, so conflicting
|
||||
definitions in that group fail instead of using filename order as precedence.
|
||||
An explicit file may use ConfigKit imports. The complete framework format and
|
||||
source rules belong to the [PromptKit v0.23.3 format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md).
|
||||
The `promptkit` section contains acquisition settings, not embedded framework
|
||||
definitions. Profiles, prompts, backends, and collections belong in the separate
|
||||
framework document. The retired `promptkit_sources`, top-level `schema_dir`,
|
||||
and `defaults.render_format` fields have no compatibility conversion and are
|
||||
rejected by strict decoding, as are unknown/raw credential fields.
|
||||
|
||||
Selector paths are relative to the process working directory, not to the
|
||||
application configuration file. Application validation checks the selector
|
||||
shape but does not open or validate Promptkit sources. `config validate`
|
||||
therefore does not prove that selected sources can build an engine; use
|
||||
`inspect configuration validate` for that separate check. Repeated
|
||||
`--promptkit-source` flags replace the entire configured selector sequence
|
||||
and preserve flag order. Without an authored collection policy, a selected
|
||||
overlay replaces `promptkit_sources` as a whole; a declared sequence policy
|
||||
may instead combine the lists.
|
||||
| Field | Default | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `promptkit.configuration` | empty | One external framework file; omission/empty selects no external main. |
|
||||
| `promptkit.schema_dir` | `.` | Schema base directory passed to PromptKit. |
|
||||
| `transient_retries` | upstream default | Optional nonnegative engine retry count. Omitted/null delegates upstream; zero disables additional transient attempts. |
|
||||
| `server.addr` | `:8080` | HTTP listen address. |
|
||||
| `server.artifact_root` | empty | Root enabling HTTP file-artifact references. |
|
||||
| `server.max_request_bytes` | `16777216` | Encoded HTTP request limit; zero is unlimited. |
|
||||
| `server.max_artifact_bytes` | `16777216` | HTTP file-artifact limit; zero is unlimited. |
|
||||
| `server.max_response_bytes` | `16777216` | Encoded HTTP response limit; zero is unlimited. |
|
||||
|
||||
### Collection checkout discovery
|
||||
Size fields are nonnegative signed 64-bit values. [HTTP behavior](api.md) defines
|
||||
their enforcement; [operations](operations.md) covers safe deployment choices.
|
||||
|
||||
Select a framework discovery file using the existing file selector, as in
|
||||
[config.discovery.yml](../examples/config.discovery.yml). Its native imports
|
||||
select both supported collection-entry spellings:
|
||||
ConfigKit strictly decodes application YAML: empty files, unknown fields,
|
||||
multiple documents, aliases/anchors, and incompatible/null values fail under its
|
||||
schema rules. Explicit empty strings and numeric zeros remain values. The
|
||||
nullable retry field preserves null. Application paths are trimmed/cleaned and
|
||||
the server address is trimmed within ConfigKit's resolver, with native
|
||||
normalization evidence. Paths remain relative to process cwd, not the application
|
||||
file's directory. No general environment-variable override layer is installed.
|
||||
|
||||
## Explicit Imports And Selected Overlays
|
||||
|
||||
Application imports use native root `config.imports` and are enabled during
|
||||
loading. ConfigKit owns paths/directories/globs, requiredness, destination/item
|
||||
placement, inheritance, sequence policy, and source-root confinement; consult its
|
||||
[pinned contract][configkit]. Scriptorium does not widen the selected file's
|
||||
canonical source root or implement another traversal/merge policy.
|
||||
|
||||
`--overlay NAME` passes the name unchanged to ConfigKit. At the selected release,
|
||||
empty and exact lowercase `default` select none; other names use letters,
|
||||
digits, underscores, or hyphens and select `overlays/NAME.yml` beneath the main
|
||||
source root. A missing selected overlay fails. It is not a filesystem-path flag,
|
||||
inherited stack, or fallback-root mechanism. An active overlay after absent-main
|
||||
search exhaustion has no independent filesystem root in this application.
|
||||
|
||||
Only `serve` has named application override flags, for its HTTP settings.
|
||||
Native application-scope `--set` records are passed directly to ConfigKit.
|
||||
Nonconflicting records are supported; duplicate and ancestor/descendant paths
|
||||
are rejected rather than resolved by order. Configuration commands have no
|
||||
application-defined source/schema/HTTP selectors or comparison counterparts.
|
||||
Native comparison selections and supported overrides are independent on each side.
|
||||
|
||||
## Framework Source Mapping
|
||||
|
||||
A nonempty resolved `promptkit.configuration` becomes an import-enabled
|
||||
`configkit.File` main input to PromptKit. An empty value leaves its main absent.
|
||||
The native bundled OpenRouter underlay remains enabled; no application source
|
||||
list, directory expansion, or local precedence interpreter is installed.
|
||||
|
||||
Imports in that external document compose framework definitions using PromptKit's
|
||||
schema and ConfigKit's native rules. The [maintained entry file](../examples/promptkit.yml)
|
||||
imports the application's maintained prompt/profile fragments and backend
|
||||
definitions. Peer conflicts are errors, not filename-order precedence.
|
||||
Native whole-record replacement and inheritance remain framework-owned.
|
||||
Application settings do not embed or re-decode framework definitions.
|
||||
|
||||
PromptKit captures message-file resources with their defining source context
|
||||
when constructing the engine. Schema/artifact reads, credential resolution, and
|
||||
provider work retain native preparation/runtime lifecycles. The server keeps one
|
||||
engine until restarted; later CLI invocations perform fresh loads.
|
||||
|
||||
### Collection Checkout Discovery
|
||||
|
||||
The [discovery configuration](../examples/config.discovery.yml) selects
|
||||
[one framework entry](../examples/discovery/framework.yml) with two optional imports:
|
||||
|
||||
```yaml
|
||||
config:
|
||||
@@ -90,195 +129,30 @@ config:
|
||||
- glob: collections/*/collection.yaml
|
||||
```
|
||||
|
||||
Both globs are optional, so either spelling may have no matches. Paths are
|
||||
relative to the framework file; this example's `*` selects one checkout
|
||||
level and is not a general layout restriction. Each entry declares its own
|
||||
collection namespace and imports only its intended resource fragments. The
|
||||
checkout directory name does not determine the namespace. New checkouts are
|
||||
available on the next invocation without editing this file; a running server
|
||||
does not reload them. See the [maintained collection examples](../examples/discovery/collections/).
|
||||
Each independently maintained checkout declares its namespace and explicitly
|
||||
imports its own definitions relative to its entry file. Checkout names do not
|
||||
determine resource IDs. The [support example](../examples/discovery/collections/support-repo/collection.yml)
|
||||
imports multiple profiles/prompts and a source-relative message; the
|
||||
[review example](../examples/discovery/collections/review-repo/collection.yaml)
|
||||
uses the other spelling. Arbitrary checkout YAML is not loaded implicitly.
|
||||
|
||||
Entries imported by one discovery file are composed together as peers.
|
||||
Conflicting definitions of the same qualified resource ID fail to load;
|
||||
filename, checkout, and glob order do not set precedence. To override a
|
||||
discovered record, select a separate framework file later in
|
||||
`promptkit_sources` and supply the complete replacement record.
|
||||
Either glob may have no matches. New checkouts become visible on a later
|
||||
invocation, not through server hot reload. Entries in one discovery document are
|
||||
peers: conflicting qualified IDs fail instead of relying on glob order.
|
||||
|
||||
### Explicit imports and selected overlays
|
||||
## Inspection And Credentials
|
||||
|
||||
Application files declare imports under root `config.imports`. Native `path`,
|
||||
`dir`, and `glob` selectors, filters, recursion, destinations, and item
|
||||
placement are available as described in the [pinned ConfigKit contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/docs/config.md).
|
||||
Imports are optional by default; set `required: true` when absence must fail.
|
||||
The old `optional` field is not supported. Directory selection has no default
|
||||
filename filter; author a pattern when only YAML files are intended. ConfigKit
|
||||
composes peer sources strictly, rather than using filename order to resolve
|
||||
conflicts. Imports are resolved relative to their declaring file within the
|
||||
native source root. Scriptorium does not widen that root.
|
||||
The native `app` scope exposes the actual application result without acquiring
|
||||
framework definitions or credentials. The `promptkit` scope exposes the captured
|
||||
framework result selected by the application config/overlay. They are not merged
|
||||
into one synthetic document. See [CLI inspection](cli.md#application-configuration-inspection)
|
||||
for operations and independent comparison.
|
||||
|
||||
Root `config.sequences` can declare an identity key and merge mode for a
|
||||
collection. Scriptorium does not register or infer an identity for
|
||||
`promptkit_sources`: absent an authored policy, unkeyed lists replace across
|
||||
precedence boundaries. The [collection example](../examples/config.collections.yml)
|
||||
declares `file` identity with `upsert`, combines imported file selectors, and
|
||||
lets an overlay add another. CLI list overrides still replace the whole list.
|
||||
PromptKit owns profiles, namespaces, provider controls, repairs, retries, and
|
||||
credential resolution. Store credential environment-variable names, not raw
|
||||
values; supply the selected environment to the process. Native framework
|
||||
redaction is limited to classified fields and history, not arbitrary sensitive
|
||||
content. Protect application, prompt, prepared, and generated reports as data.
|
||||
|
||||
At application precedence boundaries, omission preserves lower-precedence
|
||||
selectors. Under ordinary list replacement, `[]` clears the selection and
|
||||
`null` resolves to no selectors. Under authored `append` or `upsert`, `[]`
|
||||
contributes no records and `null` is invalid. To clear a collection with an
|
||||
inherited policy, declare `mode: replace` at
|
||||
`destination: [promptkit_sources]` in the higher-precedence source and supply
|
||||
`promptkit_sources: []`. See
|
||||
[ConfigKit's collection policy contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/docs/config.md#yaml-declarations-and-policy-lifetime)
|
||||
for policy lifetime and combination rules.
|
||||
|
||||
These application root `config` controls do not change the separate
|
||||
PromptKit v0.23.3 framework format: its selected framework files use the
|
||||
[Promptkit contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
|
||||
and their own native ConfigKit `config` controls.
|
||||
|
||||
`--config-overlay NAME` selects one file at `overlays/NAME.yml` below that
|
||||
root. The name must use letters, digits, `_`, or `-`; it is not a path. Empty
|
||||
and exact lowercase `default` select no overlay. There is no fallback,
|
||||
case folding, inherited stack, or automatic selection; a missing selected
|
||||
overlay fails. Mappings merge; sequence contributions and nulls at collection
|
||||
destinations follow the effective collection policy described above. Other
|
||||
explicit nulls replace lower values subject to the application schema.
|
||||
Defaults-only loading can enable imports, but an absent main has no import
|
||||
declarations. This CLI supplies no independent overlay root, so an active
|
||||
overlay cannot be located without a selected main context. That is not a general
|
||||
ConfigKit restriction.
|
||||
|
||||
The [composed example](../examples/config.composed.yml) imports the application
|
||||
[source-selection fragment](../examples/config-fragments/sources.yml) and has
|
||||
a selectable [local overlay](../examples/overlays/local.yml). That fragment
|
||||
selects the [framework backend file](../examples/framework/backends.yml) through
|
||||
`promptkit_sources`; backend definitions are not imported into the application
|
||||
document. From the repository root:
|
||||
|
||||
```bash
|
||||
go run ./cmd/scriptorium render \
|
||||
--config ./examples/config.composed.yml --config-overlay local \
|
||||
--prompt generic.markdown_summary \
|
||||
--input transcript=./examples/fixtures/transcript.md \
|
||||
--input glossary=./examples/fixtures/glossary.yml
|
||||
```
|
||||
|
||||
Inspect the collection overlay and render without contacting a provider:
|
||||
|
||||
```bash
|
||||
go run ./cmd/scriptorium config show --config ./examples/config.collections.yml --config-overlay collection
|
||||
go run ./cmd/scriptorium render --config ./examples/config.collections.yml --config-overlay collection \
|
||||
--prompt generic.markdown_summary \
|
||||
--input transcript=./examples/fixtures/transcript.md \
|
||||
--input glossary=./examples/fixtures/glossary.yml
|
||||
```
|
||||
|
||||
Import and overlay file locations are constrained by ConfigKit; application
|
||||
path values such as `promptkit_sources`, `schema_dir`, and `server.artifact_root`
|
||||
remain relative to the process working directory even when authored in a
|
||||
fragment or overlay. These source constraints are separate from Promptkit
|
||||
message-resource paths and HTTP artifact containment.
|
||||
|
||||
| Field | Default | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `promptkit_sources` | empty sequence | Ordered file/directory sources for Promptkit backends, profiles, and prompts. |
|
||||
| `schema_dir` | `.` | Promptkit schema source directory for relative schema paths. |
|
||||
| `server.addr` | `:8080` | Address used by `serve`. |
|
||||
| `server.artifact_root` | unset | Root that enables HTTP `file` input references. |
|
||||
| `server.max_request_bytes` | `16777216` | Maximum encoded HTTP request-body bytes; `0` disables the limit. |
|
||||
| `server.max_artifact_bytes` | `16777216` | Maximum HTTP file-input artifact bytes; `0` disables the limit. |
|
||||
| `server.max_response_bytes` | `16777216` | Maximum encoded HTTP response bytes; `0` disables the limit. |
|
||||
| `defaults.render_format` | `text` | Default prepared-run output format: `text` or `json`. |
|
||||
| `transient_retries` | Promptkit default | Optional nonnegative count of additional built-in transient generation attempts. Omitted or `null` delegates to Promptkit; `0` disables additional attempts. |
|
||||
|
||||
The size fields must be zero or greater. The [HTTP API](api.md) defines how
|
||||
each limit is enforced and reported. `server.artifact_root` configures an HTTP
|
||||
deployment boundary; see [operations](operations.md) for deployment handling.
|
||||
|
||||
The `config validate`, `config show`, `config sources`, and `config explain`
|
||||
commands inspect this application configuration without creating a Promptkit
|
||||
engine. `show` is a resolved inspection snapshot, not necessarily a reloadable
|
||||
file. Application validation does not check framework sources, backend
|
||||
connectivity, or credential availability. Use `inspect configuration` for
|
||||
Promptkit's separately captured framework configuration; its four operations
|
||||
are documented in the [CLI reference](cli.md#framework-configuration-inspection).
|
||||
`config explain --path /server/addr` uses JSON Pointer syntax to show the
|
||||
selected field's current value and history from defaults, files, overlays,
|
||||
explicit CLI overrides, and normalization. `--path ''` selects the root.
|
||||
History includes replaced and removed values; `show` presents the final
|
||||
resolved snapshot. The application schema rejects raw credential fields, but
|
||||
do not treat inspection as a general-purpose filter for sensitive strings.
|
||||
|
||||
## Framework Source Mapping
|
||||
|
||||
Scriptorium assembles selected Promptkit source files and directories in the
|
||||
order described above, then constructs the Promptkit engine. Framework
|
||||
definitions and custom backends belong in those selected source files, not in
|
||||
the Scriptorium application configuration. Message `content_file` paths use
|
||||
the defining source's resource context and are captured when the engine is
|
||||
constructed; schema and request-artifact loading remain preparation-time
|
||||
operations. Scriptorium does not redefine or independently parse framework
|
||||
file formats.
|
||||
|
||||
- Prompt selection by ID, message templates, inputs, output contracts, and
|
||||
session IDs are Promptkit contracts.
|
||||
- Profile fields, numeric ranges, execution defaults, overlay precedence,
|
||||
built-in profiles, and credential rules are Promptkit contracts.
|
||||
- Schema path behavior and generated-content validation are Promptkit
|
||||
contracts.
|
||||
|
||||
See the
|
||||
[tagged Promptkit format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
|
||||
for all of those definitions. The files under
|
||||
[`examples/prompts`](../examples/prompts/),
|
||||
[`examples/profiles`](../examples/profiles/), and
|
||||
[`examples/schemas`](../examples/schemas/) are maintained Scriptorium
|
||||
application inputs using that tagged format.
|
||||
|
||||
PromptKit supplies a default-on OpenRouter bundle as the lowest-priority
|
||||
underlay. Choose an actual bundled profile such as `auto`, or a complete
|
||||
application-owned profile; old catalog IDs are not aliases. Caller definitions
|
||||
can replace bundled records by normal composition. Bundle availability is not
|
||||
a readiness check or a promise of a fixed provider model.
|
||||
|
||||
## Credentials And Outbound Behavior
|
||||
|
||||
Scriptorium maps `--api-key-env` and HTTP `model.api_key_env` into Promptkit
|
||||
request overrides. Keep secret values in environment variables and store only
|
||||
their names in configuration or framework source files. Do not place raw keys
|
||||
in configuration, prompts, profiles, CLI arguments, examples, or HTTP
|
||||
payloads.
|
||||
|
||||
An optional `api_key_env` whose environment value is absent or empty can result
|
||||
in an unauthenticated provider request. A profile that declares credentials
|
||||
required still fails as an invalid request when no credential source is
|
||||
selected, and fails with `ErrAPIKeyEnvMissing` when its selected environment
|
||||
source is absent or empty. Scriptorium never reads or emits the environment
|
||||
value itself.
|
||||
|
||||
Unset optional provider controls are omitted from compatible provider requests.
|
||||
A positive Promptkit `repair_attempts` budget can add provider calls, latency,
|
||||
token use, and cost; see the tagged format reference for its permitted values
|
||||
and validation-mode requirements.
|
||||
|
||||
Promptkit's built-in client makes up to two additional attempts for eligible
|
||||
transient HTTP statuses by default. The application `transient_retries` setting
|
||||
changes that budget for its constructed engine; an explicit `run` request
|
||||
override takes precedence. This can increase latency, request count, and cost.
|
||||
Each initial or repair generation has its own transient budget; an injected
|
||||
client retains its own retry behavior. The tagged integration contract owns
|
||||
eligibility and timing.
|
||||
|
||||
Promptkit's
|
||||
[OpenAI-compatible integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/integrations/openai-compatible-chat.md)
|
||||
defines outbound authentication, provider request mapping, transport limits,
|
||||
and timeout layering.
|
||||
|
||||
## Related References
|
||||
|
||||
- [CLI reference](cli.md)
|
||||
- [HTTP API reference](api.md)
|
||||
- [Operations guide](operations.md)
|
||||
- [Promptkit framework formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
|
||||
[formats]: https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md
|
||||
[configkit]: https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/docs/config.md
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
95
docs/consumers/upgrading-cli.md
Normal file
95
docs/consumers/upgrading-cli.md
Normal 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.
|
||||
@@ -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.
|
||||
|
||||
@@ -5,6 +5,8 @@ application that consumes the public
|
||||
[PromptKit v0.23.3 package](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md);
|
||||
framework implementation work belongs in Promptkit. Application configuration
|
||||
uses ConfigKit v1.2.1; keep Scriptorium's schema and source selection local.
|
||||
Operator interfaces use CommandKit v0.7.0, ckconfig v0.9.0, and ckprompt v0.10.0;
|
||||
standard command families and presentation remain upstream-owned.
|
||||
PromptKit uses the same ConfigKit release to load framework sources under its
|
||||
own separate schema and format contract.
|
||||
|
||||
@@ -46,8 +48,8 @@ Before recommending, planning, or implementing work:
|
||||
| CLI commands, flags, output, or exit behavior | [CLI contract](cli.md) and [adapter internals](internal/adapters.md) |
|
||||
| HTTP routes, DTOs, limits, status mapping, or artifact policy | [HTTP API contract](api.md), [adapter internals](internal/adapters.md), and [source internals](internal/sources.md) |
|
||||
| Application configuration or precedence | [Configuration contract](config.md), [adapter internals](internal/adapters.md), [source internals](internal/sources.md), and `internal/config` definition/load tests |
|
||||
| Prepared-run presentation | [CLI contract](cli.md), [adapter internals](internal/adapters.md), and `internal/format` |
|
||||
| Promptkit source selection or captured framework inspection | [Configuration contract](config.md#promptkit-source-selectors), [framework configuration CLI contract](cli.md#framework-configuration-inspection), and [source internals](internal/sources.md) |
|
||||
| Prepared-run presentation | [CLI contract](cli.md), [adapter internals](internal/adapters.md), and the [native CLI contract](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md) |
|
||||
| Promptkit source selection or captured framework inspection | [Configuration contract](config.md#framework-source-mapping), [framework configuration CLI contract](cli.md#framework-configuration-inspection), and [source internals](internal/sources.md) |
|
||||
| Prompt, profile, schema, generation, or validation semantics | [PromptKit v0.23.3 framework formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md) and the [Promptkit consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md) |
|
||||
| OpenAI-compatible outbound behavior or timeout layering | [PromptKit v0.23.3 integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/integrations/openai-compatible-chat.md) |
|
||||
| Subprocess behavior | [Subprocess integration](integrations/subprocess.md) and [CLI contract](cli.md) |
|
||||
|
||||
@@ -1,64 +1,67 @@
|
||||
# Subprocess Integration
|
||||
|
||||
This document covers process-boundary behavior for callers that invoke
|
||||
Scriptorium as a child process. Command syntax, flags, output, and exit codes
|
||||
are defined by the [CLI reference](../cli.md). Interface selection belongs in
|
||||
the [consumer integration overview](../consumers/api.md).
|
||||
Use the executable when a local process boundary is appropriate.
|
||||
The [CLI contract](../cli.md) owns exact command/flag/status syntax; the
|
||||
[consumer overview](../consumers/api.md) compares subprocess and HTTP use.
|
||||
|
||||
## Process Contract
|
||||
## Artifact-First Execution And Inspection
|
||||
|
||||
Use `scriptorium render` when the caller needs prepared output without a model
|
||||
call, and `scriptorium run` for generation. Pass an explicit `--config` or
|
||||
make the configuration search paths available to the child process; configuration
|
||||
discovery, fields, profile selection, and credential mechanisms are defined in
|
||||
the [configuration reference](../config.md).
|
||||
Select a stored prompt and capture its generated artifact from stdout. Use native
|
||||
requirements discovery before generated input files exist, concrete validation
|
||||
once bindings exist, and prepared preview to render without a model call.
|
||||
The [CLI migration guide](../consumers/upgrading-cli.md) explains replacements
|
||||
for older command and file-output conventions.
|
||||
|
||||
Pass required API-key environment variables through the child environment. Do
|
||||
not place raw API keys in arguments. Keep the environment limited to the values
|
||||
needed for the selected profile.
|
||||
Pass an explicit application configuration or deliberately arrange the child's
|
||||
[configuration discovery](../config.md). Supply only the environment needed for
|
||||
selected credentials; never put raw keys in arguments.
|
||||
|
||||
For application-only preflight, invoke `scriptorium config validate`; it exits
|
||||
0 with empty stdout when the application configuration loads, but does not
|
||||
prove that Promptkit sources or credentials are usable. `config show` emits
|
||||
resolved YAML and `config sources` emits newline-terminated JSON provenance.
|
||||
All three use the same source selection and explicit overrides as execution
|
||||
commands and require separate stderr capture for diagnostics. Their output can
|
||||
include source paths, identifiers, credential reference names, and ordinary
|
||||
backend parameters; treat it as potentially sensitive.
|
||||
Discovery completeness is distinct from binding satisfaction and execution
|
||||
readiness. Partial reports can succeed. Consumers own their binding graph and
|
||||
policy for incomplete findings; Scriptorium supplies no workflow state.
|
||||
|
||||
## Streams And Output Ownership
|
||||
## Streams, Reports, And Availability
|
||||
|
||||
Capture stdout and stderr separately. Stdout contains the requested artifact or
|
||||
prepared output unless the caller selects an output file; stderr contains
|
||||
summaries, diagnostics, and server messages. The exact destinations and status
|
||||
meanings are part of the [CLI reference](../cli.md), not a stable stderr data
|
||||
protocol.
|
||||
Capture stdout and stderr separately. Diagnostics are not a machine-readable
|
||||
error protocol, even when structured result output is selected. Prefer exit
|
||||
classification and native report fields; do not parse diagnostic prose.
|
||||
|
||||
When using `--out`, the caller owns the output path, its permissions, and
|
||||
cleanup. Treat rendered prompts, generated artifacts, stdout, and stderr as
|
||||
potentially sensitive.
|
||||
The default generated result is artifact content. Native structured results and
|
||||
optional separate reports carry the full returned result, including content and
|
||||
metadata. They are not the former metadata-only CLI observation report. Native
|
||||
prompt/prepared inspection also carries content. Treat all captured streams and
|
||||
reports as potentially sensitive.
|
||||
|
||||
For `run`, an optional [execution report file](../cli.md) contains terminal
|
||||
metadata separate from generated stdout or `--out`. The caller owns that
|
||||
path's permissions and retention. Output and report files are not a
|
||||
transaction: one may be written when the other fails, and a preexisting report
|
||||
may remain when the invocation has no terminal event. Check the exit status
|
||||
and diagnostics rather than assuming a report path contains this run's data.
|
||||
To save main output, supply a file as the subprocess stdout destination or use
|
||||
shell redirection. Omit quiet when that main result is needed: quiet suppresses
|
||||
it even for redirected stdout. A separately requested report remains an
|
||||
application file effect independent of quiet and main format selection.
|
||||
|
||||
A completed content-validation failure can still deliver an artifact/result;
|
||||
consumers decide whether it is usable. An operational failure with no result
|
||||
produces diagnostics and a nonzero status, not a synthesized result/error
|
||||
envelope. An existing separate report may then describe an older invocation.
|
||||
|
||||
## Partial Delivery And Caller Responsibility
|
||||
|
||||
Main output is attempted before a requested report, and report delivery is
|
||||
attempted even after main presentation failure. Either destination may contain
|
||||
partial data after an error. File delivery is not transactional and has no
|
||||
rollback or atomic-replacement promise.
|
||||
|
||||
Callers own redirected file creation/truncation, permissions, retention, and
|
||||
keeping destinations separate. A shell may truncate its file before the process
|
||||
starts, unlike a separate report that is opened only after a result exists.
|
||||
Check the finalized exit status and diagnostic stream; do not infer success or
|
||||
freshness from a file's existence.
|
||||
|
||||
## Cancellation And Recovery
|
||||
|
||||
A CLI invocation performs one synchronous request and creates no durable run
|
||||
state. A supervising process that needs cancellation must terminate the child
|
||||
process according to its own process-management policy. A later invocation is a
|
||||
new request and can make another model call; there is no resume or checkpoint
|
||||
protocol.
|
||||
Interrupt/SIGTERM cancels the child's invocation context. Engine cancellation is
|
||||
cooperative. The [whole-operation budget](../cli.md#generation) is separate from
|
||||
per-attempt provider timeouts and excludes process/configuration setup and
|
||||
delivery. Supervisors still own forced process termination when required.
|
||||
|
||||
For `run`, callers may set the [whole-run deadline](../cli.md) to bound the
|
||||
engine invocation. It is separate from the per-attempt generation timeout and
|
||||
does not include child startup or output writing. A typed operation deadline
|
||||
failure exits 1.
|
||||
Supervisors still own process termination when they need to stop the child
|
||||
outside that engine interval.
|
||||
|
||||
For deployment, filesystem permissions, and sensitive-artifact handling, see
|
||||
the [operations guide](../operations.md).
|
||||
A new invocation is a new request that may incur another provider call/cost.
|
||||
There is no checkpoint, archive, conversation, or resume protocol. Deployment and
|
||||
sensitive-data handling belong to [operations](../operations.md).
|
||||
|
||||
@@ -1,157 +1,89 @@
|
||||
# Adapter Internals
|
||||
|
||||
## Purpose
|
||||
Adapters map executable inputs and effects through public upstream values.
|
||||
The [CLI](../cli.md), [HTTP API](../api.md), and [architecture policy](../policy/architecture.md)
|
||||
own their external contracts and boundaries.
|
||||
|
||||
Scriptorium adapters translate executable inputs into Promptkit public requests
|
||||
and translate Promptkit results or errors back to CLI or HTTP behavior. They
|
||||
own IO and presentation mechanics, not framework decisions.
|
||||
## CLI Composition And Acquisition
|
||||
|
||||
External contracts are canonical in the [CLI reference](../cli.md) and
|
||||
[HTTP API reference](../api.md). Promptkit's public engine contract is
|
||||
described by its tagged
|
||||
[Go consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md).
|
||||
`app.go` composes application run/serve declarations with native configuration,
|
||||
PromptKit, completion, help, and version support. CommandKit owns parsing,
|
||||
declaration-input checks, reporting selection, presentation, and finalization.
|
||||
|
||||
## Components And Collaborators
|
||||
`selection.go` maps explicit native config/overlay choices and server-only HTTP
|
||||
bindings into `internal/config.Load`. It preserves supplied empty/zero values.
|
||||
Native application `--set` records remain upstream records with native conflict
|
||||
handling. No application selectors are installed under configuration commands.
|
||||
|
||||
- `cmd/scriptorium` passes process arguments and streams to
|
||||
`internal/adapter/cli`.
|
||||
- `internal/adapter/cli` resolves settings through `internal/config`,
|
||||
constructs `promptkit.Engine`, maps CLI values to `promptkit.RunRequest`,
|
||||
exposes application and captured framework configuration inspection, and
|
||||
owns output files, summaries, and exit codes.
|
||||
- `internal/config` delegates application YAML decoding, default resolution,
|
||||
overrides, and validation ordering to ConfigKit v1.2.1. The CLI supplies only
|
||||
explicitly visited application flags as overrides and renders safe structured
|
||||
load diagnostics on stderr. PromptKit uses the same ConfigKit release to
|
||||
load framework sources under its own definition and format contract. Both
|
||||
domains use ConfigKit's native diagnostic writer.
|
||||
- `internal/adapter/http` strictly decodes request DTOs, maps them to Promptkit
|
||||
public values, calls its adapter-owned `Runner` interface, and maps results
|
||||
and errors to HTTP DTOs.
|
||||
- `internal/format` renders `promptkit.PreparedRun` values as deterministic text
|
||||
or JSON.
|
||||
- `internal/report` maps Promptkit's terminal execution event to a small
|
||||
application-owned value without invoking the engine or writing output.
|
||||
`native_config.go` adapts the actual application result through
|
||||
`ckconfig.FromConfigKit` and framework inspection through `ckprompt.ConfigScope`.
|
||||
Native views own effective values, paths, metadata, sources, findings, explanations,
|
||||
redaction, and comparison. Application inspection does not construct an engine.
|
||||
Comparison loads each side from that side's selection; there is no config/engine
|
||||
cache or effective-document reconstruction.
|
||||
|
||||
## Wiring Flows
|
||||
`acquisitionState` contains application diagnostic evidence only, never loaded
|
||||
configuration or engines. Callback decorators forward it through native
|
||||
`Acquired` channels. An application LoadError is transported separately while
|
||||
the framework adapter runs, then its original typed cause is restored before
|
||||
native outcome classification. This prevents app findings from becoming
|
||||
framework findings. Native framework evidence remains unchanged; comparison
|
||||
application messages identify left/right context. Callback marks prevent replay
|
||||
when operations share invocation state.
|
||||
|
||||
### CLI
|
||||
`native_prompt.go` installs all twelve ckprompt callbacks, nil request builders,
|
||||
and empty-default native namespace views. Inventories, named resources,
|
||||
requirements, validation, preparation, and smoke testing retain their upstream
|
||||
lifecycles and reports.
|
||||
|
||||
`run` calls `promptkit.Engine.Run`; `render` calls
|
||||
`promptkit.Engine.Prepare`. Both share request mapping for exact prompt ID
|
||||
and profile selection, optional file inputs, variables, and presence-aware
|
||||
execution overrides. Omitted framework settings remain zero values so Promptkit
|
||||
resolves its own defaults and definition-required inputs.
|
||||
The application retry setting enters shared engine construction, while a
|
||||
run/render flag enters only the mapped request. The server uses the same engine
|
||||
setting and retains one backend admission state. Render prepares without
|
||||
generation.
|
||||
## Generation And Delivery
|
||||
|
||||
`inspect prompt` maps the selected ID to
|
||||
`promptkit.Engine.InspectPrompt`, then formats Scriptorium-owned inspection
|
||||
data. `inspect profile` maps an explicit profile ID to `Engine.InspectProfile`
|
||||
and formats Scriptorium-owned resolved profile data without backend completion.
|
||||
`native_run.go` binds the required operand and reusable resource/input/execution
|
||||
flags into a native RunRequest. Ordinary typed namespace flags feed
|
||||
`Engine.WithNamespaces`; stored references are not rewritten. One `Engine.Run`
|
||||
call receives the invocation context and unchanged operation duration. PromptKit
|
||||
owns preparation, credentials, admission, retries, repairs, and content validation.
|
||||
|
||||
Both paths construct the same full-source engine as execution before inspecting
|
||||
the chosen definition; selected prompts are not filtered out. They do not
|
||||
perform request preparation or generation. The [CLI definition-inspection
|
||||
contract](../cli.md#scriptorium-inspect-prompt) owns the loading and runtime
|
||||
boundaries, including the distinction between an optional prompt collection
|
||||
and validating any prompts that were selected.
|
||||
`outcomes.go` maps typed failures and native configuration evidence to native
|
||||
outcomes, preserving causes while keeping provider payloads out of terminal
|
||||
explanations. A returned completed validation failure remains a domain outcome;
|
||||
an unexpected nil successful result is an integration failure.
|
||||
|
||||
`inspect configuration` builds the same engine from the selected native
|
||||
Promptkit source sequence, reads its captured configuration view, and delegates
|
||||
effective output and explanation to Promptkit's native writers. The adapter
|
||||
projects captured source records into its small JSON DTO. Its validation
|
||||
operation constructs the engine without preparing a request. Framework source
|
||||
semantics and report redaction are owned by Promptkit; the [CLI
|
||||
contract](../cli.md#framework-configuration-inspection) documents the exposed
|
||||
operations and their deliberately limited redaction scope.
|
||||
`delivery.go` submits the actual RunResult to the invocation reporter with a
|
||||
reusable artifact-byte text template. The optional file renders that same value
|
||||
without the template through CommandKit's writer API, outside reporter callbacks
|
||||
to avoid reentrancy. File failures add explanations/causes while reporter
|
||||
presentation failures remain native. See [delivery semantics](../cli.md#results-and-separate-reports).
|
||||
|
||||
The `config` family loads the same application ConfigKit result once and uses
|
||||
its validation, effective-output, source, and explanation views directly. It
|
||||
does not construct a Promptkit engine. The CLI maps source records into a small
|
||||
JSON DTO for `sources`; `show` and `explain` use ConfigKit's own writers.
|
||||
## Server And HTTP
|
||||
|
||||
`serve` constructs Scriptorium's restricted HTTP artifact reader, injects it
|
||||
with `promptkit.WithArtifactReader`, passes the engine through the HTTP
|
||||
adapter's consumer-owned `Runner` interface, and starts the server.
|
||||
`server.go` loads application settings, injects the restricted artifact reader
|
||||
into one engine, installs the existing HTTP handler/limits, and opens a listener.
|
||||
It retains the header timeout and engine retry defaults. Context cancellation
|
||||
calls Server.Close; callback coordination finishes connection/listener closing
|
||||
before return, without waiting for arbitrary context-ignoring application work.
|
||||
|
||||
The command paths assemble the engine from application-selected framework
|
||||
source files and directories plus the schema directory and retry setting.
|
||||
Individual files become import-enabled ConfigKit inputs; directory selections
|
||||
are expanded through Promptkit's directory-input helper. Scriptorium supplies
|
||||
those ordered underlays through Promptkit's public configuration API rather
|
||||
than parsing or mapping framework definitions itself. The server constructs
|
||||
one engine, which retains the framework's backend registry and associated
|
||||
capacity state across requests.
|
||||
The HTTP handler strictly decodes DTOs and applies transport policy before
|
||||
mapping to PromptKit requests. Its Runner interface is a consumer-side external
|
||||
boundary using native values. Request controls do not mutate shared engine
|
||||
defaults; shared backend capacity accounting remains in that engine.
|
||||
|
||||
### HTTP
|
||||
|
||||
The handler enforces transport limits and strict JSON decoding before mapping
|
||||
DTOs into `promptkit.RunRequest`, `promptkit.ArtifactRef`, and
|
||||
`promptkit.ExecutionTargetOverride`. On success it reads Promptkit artifact,
|
||||
validation, model, usage, and metadata values directly.
|
||||
The optional HTTP retry count maps to `RunRequest.TransientRetries` without
|
||||
mutating the shared engine. Negative values are rejected before invocation;
|
||||
Promptkit controls retries and backend admission for concurrent requests.
|
||||
CLI and HTTP operation budgets map to PromptKit's `OperationTimeout`; HTTP
|
||||
passes the caller context through unchanged. The public sentinels determine
|
||||
timeout classification.
|
||||
|
||||
Failure mapping uses `errors.Is` against Promptkit's public sentinels and the
|
||||
HTTP reader's Scriptorium-owned containment and size errors. Wrapped reader
|
||||
errors preserve their identity through Promptkit's artifact-load boundary.
|
||||
|
||||
The report collector is per invocation. It ignores nonterminal events and
|
||||
copies terminal aggregates once, including usage presence and completeness.
|
||||
It retains no history or shared state; adapters decide whether to attach it and
|
||||
how to present its snapshot.
|
||||
CLI `run` attaches one only when a report path is selected, writes generated
|
||||
output first on success, and then writes the terminal snapshot when present.
|
||||
Its report path remains untouched for pre-invocation failures or absent
|
||||
terminal observations; report and artifact writes are independent.
|
||||
HTTP `POST /v1/runs` attaches a separate collector to each invocation only when
|
||||
`include_execution_report` is true. Its optional top-level `execution` field
|
||||
appears in success or error envelopes only when Promptkit emits a terminal
|
||||
event. Pre-invocation adapter errors and absent terminal events leave it out.
|
||||
The complete serialized success or report-bearing error response is subject to
|
||||
the configured response-size limit; overflow returns the compact 413 error
|
||||
without a report. Field meanings are owned by the [API contract](../api.md#execution-report).
|
||||
|
||||
## Package-Local Guarantees
|
||||
|
||||
- Adapters contain no copied framework types or orchestration.
|
||||
- Configuration is resolved before Promptkit engine construction.
|
||||
- Explicit numeric overrides preserve presence, including zero.
|
||||
- HTTP DTO and error mapping remains stable and transport-owned.
|
||||
- Resolved secrets are not serialized or printed.
|
||||
- No adapter creates durable run state.
|
||||
HTTP optional reports use one per-request `internal/report.Collector`, attached
|
||||
only for opted-in requests. It copies terminal aggregates, not event history,
|
||||
and is never the CLI result report. Success/error attachment and encoded-size
|
||||
handling retain the [HTTP contract](../api.md#execution-report). Reader sentinel
|
||||
identities survive PromptKit wrapping for status mapping.
|
||||
|
||||
## Verification
|
||||
|
||||
Inspect:
|
||||
Native composition/configuration/prompt/run/delivery/lifecycle tests protect the
|
||||
application's integration choices using real libraries and controlled local
|
||||
providers. Checkout-discovery tests cover fresh invocations and entry-file
|
||||
spellings. Entrypoint tests protect identity/status mapping; HTTP reader/DTO/
|
||||
report/capacity regressions and the architecture guard remain their own owners.
|
||||
Do not duplicate upstream parsers, analyzers, serializers, or exhaustive format
|
||||
matrices to change an adapter.
|
||||
|
||||
- `internal/adapter/cli/run_test.go`
|
||||
- `internal/adapter/http/handler_test.go`
|
||||
- `internal/adapter/http/artifact_reader_test.go`
|
||||
- `internal/format/prepared_run_test.go`
|
||||
- `internal/adapter/dependency_test.go`
|
||||
|
||||
The adapter tests protect parsing, configuration mapping, output, status
|
||||
mapping, restricted artifacts, and representative real Promptkit-engine
|
||||
workflows. The dependency test protects the repository boundary.
|
||||
|
||||
## Change Recipes
|
||||
|
||||
For a CLI or HTTP change:
|
||||
|
||||
1. identify the Scriptorium-owned external contract;
|
||||
2. map through Promptkit public values without copying framework semantics;
|
||||
3. add or update the narrow application-owned test;
|
||||
4. update the canonical Scriptorium contract; and
|
||||
5. coordinate and tag Promptkit first if a required public capability is
|
||||
genuinely absent.
|
||||
|
||||
Update [source internals](sources.md) when application source locations or HTTP
|
||||
artifact containment changes.
|
||||
When changing behavior, update its canonical external contract and focused
|
||||
integration protection. Required shared capabilities belong upstream before
|
||||
tagged adoption, not in a resurrected application framework facade.
|
||||
|
||||
@@ -1,19 +1,18 @@
|
||||
# Internal Component Overview
|
||||
|
||||
This is the complete inventory of Scriptorium's implemented Go components.
|
||||
The [architecture policy](../policy/architecture.md) owns normative boundaries;
|
||||
This inventory describes implemented Go components. The
|
||||
[architecture policy](../policy/architecture.md) owns normative boundaries;
|
||||
public behavior belongs in the linked contracts.
|
||||
|
||||
| Component | Implemented responsibility | References |
|
||||
| --- | --- | --- |
|
||||
| `cmd/scriptorium` | Process entrypoint that delegates arguments and streams to the CLI adapter. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
|
||||
| `internal/adapter/cli` | Parses execution, application-configuration, and captured framework-configuration inspection commands; resolves settings; constructs Promptkit engines for execution, definition inspection, and framework inspection; maps requests; and owns process output and exit behavior. | [CLI contract](../cli.md), [adapter internals](adapters.md), [source internals](sources.md) |
|
||||
| `internal/adapter/http` | Owns routes, DTOs, strict decoding, limits, Promptkit request/result mapping, public error mapping, and restricted HTTP artifact reading. | [HTTP API](../api.md), [adapter internals](adapters.md), [source internals](sources.md) |
|
||||
| `internal/config` | Selects application sources through ConfigKit v1.2.1, supplies the application definition and explicit overrides, and converts resolved settings for runtime use. | [configuration contract](../config.md), [adapter internals](adapters.md), [source internals](sources.md) |
|
||||
| `internal/defaults` | Holds Scriptorium-owned application and HTTP defaults. | [configuration contract](../config.md) |
|
||||
| `internal/format` | Formats Promptkit prepared-run and prompt/profile inspection values for CLI text or JSON output; framework-configuration output uses Promptkit's native captured view and writers. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
|
||||
| `internal/report` | Projects one terminal Promptkit observation into Scriptorium-owned execution metadata. | [adapter internals](adapters.md) |
|
||||
| `cmd/scriptorium` | Build identity, signal-aware context, native status-to-process exit. | [CLI](../cli.md), [adapters](adapters.md) |
|
||||
| `internal/adapter/cli` | CommandKit composition, ckconfig/ckprompt acquisition, application loading, native request mapping, run/report effects, and HTTP process lifecycle. | [CLI](../cli.md), [adapters](adapters.md), [sources](sources.md) |
|
||||
| `internal/adapter/http` | Routes, strict DTO decoding, transport limits, public request/result/error mapping, and restricted artifact reader. | [HTTP API](../api.md), [adapters](adapters.md), [sources](sources.md) |
|
||||
| `internal/config` | ConfigKit application schema, discovery/selection, defaults/resolution/validation callbacks, and completed-value conversion. | [Configuration](../config.md), [sources](sources.md) |
|
||||
| `internal/defaults` | Application and HTTP default constants. | [Configuration](../config.md) |
|
||||
| `internal/report` | HTTP terminal-observation metadata projection. It is not used for CLI native result reports. | [HTTP execution report](../api.md#execution-report), [adapters](adapters.md) |
|
||||
|
||||
Framework implementation packages are provided by
|
||||
[PromptKit v0.23.3](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md)
|
||||
and are not part of this repository.
|
||||
CommandKit, ckconfig, ckprompt, ConfigKit, and PromptKit are released upstream
|
||||
dependencies, not local framework packages. There is no custom CLI formatter
|
||||
package or compatibility dispatch surface.
|
||||
|
||||
@@ -1,117 +1,55 @@
|
||||
# Source Internals
|
||||
|
||||
## Purpose
|
||||
This document covers application acquisition and the restricted HTTP artifact
|
||||
reader. [Configuration](../config.md) owns field/discovery/composition contracts;
|
||||
the [PromptKit formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
|
||||
own framework resources and execution semantics.
|
||||
|
||||
This document covers Scriptorium-owned source locations and the restricted HTTP
|
||||
artifact reader. Prompt, profile, schema, and ordinary artifact semantics are
|
||||
owned by the tagged
|
||||
[PromptKit v0.23.3 format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md).
|
||||
## Application Boundary And Engine Construction
|
||||
|
||||
## Application Source Locations
|
||||
`internal/config.Load` selects an explicit File or the ordered native SearchConfig
|
||||
presets and performs one ConfigKit load with imports, overlay selection, and
|
||||
explicit overrides. It returns the actual Result with native inspection evidence.
|
||||
Definition callbacks supply application defaults, record actual path/address
|
||||
normalizations through ConfigKit, and validate retry/HTTP-size domains. Settings
|
||||
conversion consumes completed values without another merge or normalization pass.
|
||||
|
||||
`internal/config` resolves the ordered `promptkit_sources` sequence and
|
||||
`schema_dir` from application configuration and explicit CLI overrides. It
|
||||
owns selector-shape validation, not framework file parsing. During engine
|
||||
construction, `internal/adapter/cli` turns file selections into import-enabled
|
||||
ConfigKit inputs and expands directory selections with
|
||||
`promptkit.DirectoryInputs`, then passes the ordered groups as Promptkit
|
||||
configuration underlays, one per selector. Directory inputs retain the
|
||||
helper's strict-composition grouping; no selected source becomes an implicit
|
||||
framework main. The shared Promptkit engine receives the selected schema
|
||||
directory and retry setting, and the default OpenRouter bundle remains enabled.
|
||||
The typed application PromptKit section selects acquisition only. In
|
||||
`engine.go`, a nonempty resolved configuration path becomes an import-enabled
|
||||
main Input; an empty path leaves Main nil. The schema base and retry default are
|
||||
passed directly, retaining the bundled underlay. There is no source-list parser,
|
||||
directory classification/expansion, or one-underlay-per-selector algorithm.
|
||||
|
||||
Promptkit uses ConfigKit to load and compose those framework inputs according
|
||||
to Promptkit's own schema and format. Scriptorium does not parse or validate
|
||||
Promptkit definitions. Promptkit owns definition selection and validation,
|
||||
profile built-ins and overlays, schema resolution, ordinary file artifacts,
|
||||
captured framework configuration inspection, and related error identities.
|
||||
Framework imports resolve within the native source context. Message resources
|
||||
are captured from their defining contexts at engine construction. Schema and
|
||||
request-artifact acquisition retain their preparation-time behavior.
|
||||
Independent collection checkouts are discovered by native file import globs,
|
||||
not application traversal. New invocations reload normally; a server retains
|
||||
its single engine until restart.
|
||||
|
||||
The [configuration reference](../config.md) owns Scriptorium's source-location
|
||||
fields and precedence. Maintained files under `examples/` are application
|
||||
inputs that use Promptkit's tagged formats.
|
||||
|
||||
## Application Configuration Boundary
|
||||
|
||||
`internal/config` contains the application-owned ConfigKit-native `Document`
|
||||
definition. Its fresh defaults come from Scriptorium's existing default
|
||||
constants; its resolver records only actual leaf-level trimming, path cleaning, and
|
||||
render-format normalization. The validator reports selector-shape, retry,
|
||||
size-limit, and format errors without mutating the document or exposing
|
||||
rejected values. Application path values keep working-directory-relative
|
||||
meaning. ConfigKit v1.2.1 owns strict application YAML decoding and presence
|
||||
semantics. Framework configuration is separately loaded by PromptKit using
|
||||
the same ConfigKit release under PromptKit's own schema and source contract.
|
||||
|
||||
The `Load` boundary selects an explicit file or constructs a native ConfigKit
|
||||
search over the ordered implicit paths. Discovery exhaustion uses defaults;
|
||||
a selected-file error stops loading. One ConfigKit load enables imports,
|
||||
applies explicitly supplied application overrides after decoding and before
|
||||
resolution and validation, and returns the document and its frozen inspection
|
||||
records. `Settings` copies selectors in their resolved order into runtime
|
||||
settings; it does not read files or apply another merge. ConfigKit uses the selected file's
|
||||
canonical directory as the source root; the application does not widen it.
|
||||
Application path values retain process-working-directory-relative meaning.
|
||||
|
||||
Runtime conversion consumes the resolved application values through the
|
||||
existing `Settings` path. Promptkit receives selected framework sources only
|
||||
after application configuration has loaded and validated; its source merge,
|
||||
definition validation, and captured inspection view remain framework-owned.
|
||||
|
||||
Every configuration-loading command uses this boundary. The CLI maps only
|
||||
explicitly visited application flags to ConfigKit overrides and prints
|
||||
structured load diagnostics before engine construction. Application and
|
||||
framework load errors and warnings use their respective native writers. The old application
|
||||
YAML decoder and merge path have been removed.
|
||||
Application `config` inspection reuses the result's frozen effective,
|
||||
provenance, and history views without constructing an engine or reloading
|
||||
sources. It does not resolve credentials. `inspect configuration` separately
|
||||
constructs an engine and exposes Promptkit's captured framework view; only its
|
||||
framework `show` and `explain` reports receive Promptkit's native,
|
||||
credential-shaped redaction. Neither inspection family is a general-purpose
|
||||
filter for arbitrary sensitive values.
|
||||
Application-only inspection uses its completed result without framework
|
||||
acquisition. Framework inspection exposes the native captured view separately.
|
||||
Diagnostic decoration in the [CLI adapter](adapters.md) carries application
|
||||
messages without combining evidence trees or effective documents. There is no
|
||||
per-invocation engine/config cache or cross-invocation snapshot guarantee.
|
||||
|
||||
## Restricted HTTP Artifact Reader
|
||||
|
||||
`internal/adapter/http` implements `promptkit.ArtifactReader` for HTTP
|
||||
requests. The `serve` path injects it with
|
||||
`promptkit.WithArtifactReader`, replacing Promptkit's ordinary reader for
|
||||
inbound HTTP inputs.
|
||||
The HTTP adapter implements `promptkit.ArtifactReader`; server construction
|
||||
injects it through the public option. Ordinary CLI artifact loading remains
|
||||
upstream-owned.
|
||||
|
||||
The reader:
|
||||
The reader accepts inline content without a root. File references need a root;
|
||||
relative paths resolve below it and absolute paths must be lexically contained.
|
||||
Traversal outside is rejected and the configured file byte limit applies, with
|
||||
zero unlimited. Reads preserve native artifact metadata and honor cancellation.
|
||||
|
||||
- accepts inline references without an artifact root;
|
||||
- denies file references when no root is configured;
|
||||
- resolves relative paths below the configured root;
|
||||
- accepts absolute paths only when they are lexically within that root;
|
||||
- rejects lexical traversal outside the root;
|
||||
- applies the configured file byte limit, with zero meaning unlimited;
|
||||
- preserves content type, body, size, hash, name, and URI metadata; and
|
||||
- honors context cancellation.
|
||||
Containment does not resolve symlinks. The OS may follow a symlink inside the
|
||||
root to an outside target; this is not a filesystem sandbox or a defense against
|
||||
privileged concurrent filesystem modification. Reader errors retain identity
|
||||
through upstream artifact-load wrapping, enabling the existing HTTP mapping.
|
||||
|
||||
Containment is lexical and does not resolve symlinks. The operating system
|
||||
follows symlinks after the check. The [HTTP API](../api.md) owns observable
|
||||
request outcomes, and [operations](../operations.md) owns safe deployment
|
||||
permissions and root selection.
|
||||
|
||||
Reader errors remain identifiable after Promptkit wraps them as artifact-load
|
||||
failures, allowing the HTTP adapter to preserve Scriptorium status and error
|
||||
codes.
|
||||
|
||||
## Verification And Change Recipe
|
||||
|
||||
Inspect:
|
||||
|
||||
- `internal/config/document_test.go`
|
||||
- `internal/config/load_test.go`
|
||||
- `internal/adapter/cli/run_test.go`
|
||||
- `internal/adapter/http/artifact_reader_test.go`
|
||||
- `internal/adapter/http/handler_test.go`
|
||||
|
||||
When changing an application source location or HTTP artifact policy:
|
||||
|
||||
1. preserve strict configuration precedence and the Promptkit public boundary;
|
||||
2. keep containment and size policy in Scriptorium;
|
||||
3. update focused configuration, reader, and handler tests;
|
||||
4. update the [configuration](../config.md), [HTTP](../api.md), and
|
||||
[operations](../operations.md) contracts as applicable; and
|
||||
5. do not duplicate Promptkit loaders, formats, or ordinary artifact behavior.
|
||||
The [HTTP API](../api.md) owns outcomes and [operations](../operations.md) owns
|
||||
safe root/permission selection. Configuration, CLI acquisition/engine, and HTTP
|
||||
reader/handler tests own their respective boundaries; upstream owns exhaustive
|
||||
source traversal, format parsing, ordinary artifacts, and inspection semantics.
|
||||
|
||||
@@ -1,243 +1,120 @@
|
||||
# Operations Guide
|
||||
|
||||
## Scope And References
|
||||
This runbook covers deployment, normal operation, capacity, sensitive data, and
|
||||
recovery. Exact [CLI syntax/statuses](cli.md), [configuration](config.md), and
|
||||
[HTTP wire behavior](api.md) remain in their canonical references.
|
||||
See the [CLI migration guide](consumers/upgrading-cli.md) for changed jobs and
|
||||
the [framework upgrade guide](consumers/upgrading-promptkit.md) for definitions.
|
||||
|
||||
This runbook covers deployment, normal operation, capacity planning, and safe
|
||||
recovery for Scriptorium. It does not redefine invocation syntax, configuration
|
||||
fields, or HTTP wire behavior.
|
||||
## Deploy Sources And Process
|
||||
|
||||
- [CLI reference](cli.md): commands, output destinations, and exit codes.
|
||||
- [Configuration reference](config.md): application settings, source
|
||||
locations, defaults, and credential mapping.
|
||||
- [Promptkit source upgrade guide](consumers/upgrading-promptkit.md): concise
|
||||
source-selector and definition migration examples.
|
||||
- [PromptKit v0.23.3 framework formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md):
|
||||
prompt, profile, schema, execution-setting, and framework credential
|
||||
contracts.
|
||||
- [HTTP API reference](api.md): route, request/response schema, status codes,
|
||||
limits, and HTTP artifact access.
|
||||
- [Consumer integration overview](consumers/api.md): caller responsibilities.
|
||||
Provide readable application configuration, its selected framework entry file,
|
||||
and explicitly imported definitions/resources. Set cwd deliberately: application
|
||||
path values are cwd-relative, while framework imports and message resources keep
|
||||
their native source contexts. ConfigKit confines source imports/overlays to the
|
||||
selected main's canonical root; Scriptorium does not widen it.
|
||||
|
||||
## Operational Model And State
|
||||
Engine construction validates selected effective definitions and captures message
|
||||
resources/template syntax, including definitions not used by a particular request.
|
||||
Schema/artifact reads, credential resolution, and model work retain their native
|
||||
preparation/runtime lifecycles. A server constructs one engine at startup and
|
||||
does not hot-reload changed files; restart to capture updates. Separate CLI
|
||||
invocations load afresh rather than sharing an immutable snapshot.
|
||||
|
||||
Scriptorium handles one prompt request for each CLI invocation or HTTP request.
|
||||
It has no durable run store, archive, checkpoint, cache, or resume mechanism.
|
||||
A failed or interrupted request is recovered by correcting its inputs,
|
||||
configuration, or environment and submitting a new request.
|
||||
For independent collections, install checkouts beneath the layout selected by
|
||||
the [discovery entry](../examples/discovery/framework.yml). Each checkout declares
|
||||
its namespace and explicit fragment imports; arbitrary YAML is not a framework
|
||||
source. The maintained [discovery example](../examples/config.discovery.yml)
|
||||
supports both entry-file spellings and multiple definitions. New checkouts or
|
||||
updates become visible to later invocations or a restarted server.
|
||||
|
||||
Generated artifacts, rendered prompts, model output, and run metadata are
|
||||
caller-owned data. Retention, encryption, backup, and deletion are deployment
|
||||
responsibilities.
|
||||
Optional [CLI execution reports](cli.md) also belong to the caller. They can
|
||||
contain sensitive identifiers even though they omit prompt and response bodies.
|
||||
Keep report paths separate from generated output and apply the same access and
|
||||
retention controls. Output and report writes are not transactional; an older
|
||||
report may remain when no terminal observation was produced.
|
||||
HTTP callers may also request a [terminal execution report](api.md#execution-report).
|
||||
It shares the same identifier sensitivity and should receive response access
|
||||
and retention controls. An opted-in report increases the encoded response size;
|
||||
an oversized success or report-bearing error becomes the compact 413 response
|
||||
without a report.
|
||||
Supply only needed credential environment variables through a supervisor or
|
||||
secret-management mechanism. Confirm presence without printing their values.
|
||||
Raw keys do not belong in arguments or checked-in configuration.
|
||||
|
||||
## Deploy The Filesystem And Process
|
||||
## Normal Operator Workflow
|
||||
|
||||
Provide the process with readable selected Promptkit source files/directories
|
||||
and schema sources that follow the tagged framework formats. At engine
|
||||
construction, PromptKit v0.23.3 validates every selected effective definition,
|
||||
including unused definitions, and captures referenced message-file contents
|
||||
and static template syntax. `serve` constructs one engine at startup; it does
|
||||
not reload changed configuration or message content. Restart the process to
|
||||
validate and capture a new configuration. Schema and request-artifact reads,
|
||||
credential resolution, and provider work remain request-preparation or runtime
|
||||
concerns. For an HTTP deployment that accepts file artifacts, use a dedicated,
|
||||
narrow artifact directory rather than a general-purpose or sensitive filesystem
|
||||
tree.
|
||||
1. Validate application configuration through the native application scope.
|
||||
This does not acquire framework sources or prove provider readiness.
|
||||
2. Inspect framework configuration/resources and discover requirements for the
|
||||
selected prompt/profile/namespaces. Discovery can precede generated input
|
||||
artifacts; completeness does not establish satisfied bindings.
|
||||
3. Once artifacts exist, validate the concrete request or inspect prepared
|
||||
content. These are provider-free preparation checks with native prerequisites.
|
||||
4. Invoke a smoke test only when its provider effects are intended. Findings
|
||||
can be unsupported or unsuccessful while the command itself succeeds.
|
||||
Smoke tests are not an automatic startup or release prerequisite.
|
||||
5. Generate with the same selections and bindings, then inspect the finalized
|
||||
status and any returned validation result before accepting the output.
|
||||
|
||||
If application configuration uses explicit imports or a selected overlay,
|
||||
deploy those files beneath the selected configuration file's canonical
|
||||
directory. ConfigKit keeps imported and overlay files within that root;
|
||||
Scriptorium does not widen it. Application path values inside those files still
|
||||
resolve from the process working directory, so set that directory deliberately
|
||||
in the service manager. This configuration-source boundary is distinct from
|
||||
the HTTP artifact root and does not constrain prompt or schema directories.
|
||||
Use the [maintained preview script](../examples/render-markdown-summary.sh)
|
||||
for a provider-free example, and the [CLI contract](cli.md) for commands.
|
||||
A complete discovery report can still list required inputs that are not bound;
|
||||
a partial report can still be useful. Consumers own their policy for incomplete
|
||||
findings and changed resources between invocations.
|
||||
|
||||
For independently maintained collections, place checkouts beneath the
|
||||
directory selected by your framework discovery file. The maintained
|
||||
[discovery example](../examples/config.discovery.yml) selects optional
|
||||
`collection.yml` and `collection.yaml` entry files; each checkout owns its
|
||||
namespace and explicit fragment imports. Update a checkout independently and
|
||||
invoke the CLI again, or restart a running server to capture the update. Do
|
||||
not treat arbitrary YAML in a checkout as a framework source. When upgrading
|
||||
definitions, review exact profile IDs and replace retired catalog references
|
||||
as described in the [migration guide](consumers/upgrading-promptkit.md).
|
||||
## Sensitive Data And Retention
|
||||
|
||||
Run Scriptorium under an identity that can:
|
||||
Artifacts, prompt messages, prepared content, native run reports, metadata,
|
||||
diagnostics, and redirected streams are caller-owned potentially sensitive data.
|
||||
The separate CLI report contains the full returned result, not metadata alone.
|
||||
Control access, retention, encryption, backup, and deletion accordingly.
|
||||
Framework effective/explanation views apply native classified-field redaction,
|
||||
including history, but do not detect arbitrary secrets. Other content-bearing
|
||||
reports are not automatically made safe for publication.
|
||||
|
||||
- read only the prompt, profile, schema, and allowed input-artifact paths it
|
||||
needs;
|
||||
- read the required credential environment variables without writing them to
|
||||
files or logs; and
|
||||
- write only caller-selected output locations when CLI output files are used.
|
||||
Keep main output and report destinations separate. Delivery is nontransactional:
|
||||
one destination or partial bytes can remain after failure. An existing report
|
||||
can remain on a resultless error; check status and report identity, not just file
|
||||
existence. A shell can truncate a redirected destination before the child starts.
|
||||
Omit quiet if main stdout must be captured; the separate report effect remains
|
||||
independent. Exact delivery behavior belongs to [CLI results](cli.md#results-and-separate-reports).
|
||||
|
||||
Do not make the HTTP artifact directory writable by untrusted users. The HTTP
|
||||
artifact containment behavior is lexical and the operating system follows
|
||||
symlinks; account for that when choosing ownership and mount boundaries. See
|
||||
the [HTTP API reference](api.md) for the externally observable behavior.
|
||||
HTTP's optional [execution report](api.md#execution-report) remains a distinct
|
||||
terminal-observation projection. Protect its identifiers and any response data.
|
||||
It increases encoded response size and remains subject to the configured limit.
|
||||
|
||||
## Supply Credentials And Protect Runtime Data
|
||||
## HTTP Deployment And Shutdown
|
||||
|
||||
Set secret values in the process environment and configure only their
|
||||
environment-variable names. Do not put raw keys in configuration, prompt or
|
||||
profile files, process arguments, HTTP payloads, captured command lines, or
|
||||
debug dumps.
|
||||
The service has no built-in authentication/authorization. Deploy on a trusted
|
||||
network or behind appropriate authenticated proxy/gateway controls. Use a narrow,
|
||||
dedicated artifact root with controlled ownership and permissions when accepting
|
||||
file inputs; this is lexical containment, not a symlink sandbox.
|
||||
|
||||
Treat stdout, stderr, prepared-run output, generated artifacts, and HTTP
|
||||
responses as potentially sensitive. Send service logs to a controlled collector
|
||||
and apply the same retention and access rules as for model input and output.
|
||||
Use a supervisor for cwd, environment, restart policy, and stream capture.
|
||||
Startup information uses native Info reporting, not stdout banners.
|
||||
Interrupt/SIGTERM cancels the invocation and closes the listener and active
|
||||
connections. Canceled shutdown is nonzero operational termination. There is no
|
||||
graceful-drain deadline or promise that context-ignoring work has finished;
|
||||
supervisors own forced termination when necessary.
|
||||
|
||||
## Run A Normal Workflow
|
||||
## Capacity, Limits, And Recovery
|
||||
|
||||
Before changing production inputs, profiles, or schemas:
|
||||
One server engine shares backend admission/queue state across concurrent requests.
|
||||
That state is transient operational coordination, not a durable workflow or
|
||||
queue of resumable runs. HTTP capacity exhaustion retains its
|
||||
[API outcome](api.md); callers decide whether another model call is safe.
|
||||
|
||||
1. use `config validate`, `config show`, or `config sources` to check
|
||||
Scriptorium's application configuration; these do not open Promptkit sources
|
||||
or construct an engine;
|
||||
2. use `inspect configuration validate` to construct the engine and validate
|
||||
all selected framework definitions; this does not prepare a request, check
|
||||
credentials, load request-time schemas/artifacts, or contact a provider;
|
||||
3. confirm the deployed configuration selects the intended sources and
|
||||
environment-variable names;
|
||||
4. use [`render`](cli.md) with the same request inputs and variables to confirm
|
||||
preparation without a model call;
|
||||
5. use [`run`](cli.md) for generation; and
|
||||
6. retain or discard validation-failed output according to the caller's
|
||||
policy.
|
||||
Plan for input/output sizes, schema complexity, provider latency, retries, and
|
||||
repair costs. Native transient attempts and repair generations can add calls and
|
||||
waiting; engine defaults and per-request overrides belong to
|
||||
[configuration](config.md) and the [CLI](cli.md)/[HTTP](api.md) contracts.
|
||||
Whole-operation budgets are distinct from per-attempt generation timeouts.
|
||||
They remain cooperative and do not include configuration/setup or delivery.
|
||||
|
||||
Application configuration inspection can include paths and configured values.
|
||||
Framework `inspect configuration show` and `explain` use Promptkit's native
|
||||
redaction for classified credential-shaped provider fields, including
|
||||
historical values, while leaving environment-reference names and ordinary
|
||||
provider parameters visible. Neither report identifies arbitrary sensitive
|
||||
content by value or name. Protect inspection output accordingly; Scriptorium
|
||||
stores environment-variable names, not the resolved credential bytes.
|
||||
Before increasing HTTP byte limits, measure representative requests/artifacts/
|
||||
responses, confirm memory/network/provider capacity, retain authentication and
|
||||
upstream request controls, and test a representative workload. Do not widen the
|
||||
artifact root just to make an arbitrary host path accessible.
|
||||
|
||||
The [maintained render script](../examples/render-markdown-summary.sh) is a
|
||||
copyable preflight example. The CLI reference owns its complete invocation and
|
||||
exit semantics.
|
||||
For failures, capture diagnostics without publishing sensitive data. Verify
|
||||
selected configuration, resource identity, readable inputs, profile/credentials,
|
||||
and schema deployment. Use native prepared preview to isolate pre-generation
|
||||
problems. A completed content-validation failure is distinct from an operational
|
||||
failure to validate; consumers choose whether failed content is usable.
|
||||
Correct the cause, then issue a new request only when another provider call and
|
||||
its cost are acceptable.
|
||||
|
||||
## Expose The HTTP Service
|
||||
|
||||
The HTTP service has no built-in authentication or authorization. Place it on a
|
||||
trusted network or behind an authenticated reverse proxy, API gateway, or
|
||||
equivalent access control. Restrict who can reach it and who can read the
|
||||
artifact root.
|
||||
|
||||
Use a service manager or supervisor appropriate to the deployment to manage
|
||||
process lifetime, restart policy, log capture, and environment injection. The
|
||||
[HTTP API reference](api.md) owns client request shapes, status behavior, and
|
||||
artifact-access outcomes.
|
||||
|
||||
## Plan Capacity And Limits
|
||||
|
||||
Capacity is primarily determined by concurrent model calls, input and output
|
||||
sizes, schema complexity, provider latency, and network behavior. Size limits
|
||||
protect request bodies, HTTP file artifacts, and encoded responses; configure
|
||||
them through the [configuration reference](config.md) and rely on the
|
||||
[HTTP API reference](api.md) for their response effects.
|
||||
|
||||
Configured backend concurrency and queue capacity are enforced per constructed
|
||||
Promptkit engine. A `serve` process constructs one engine for its handler, so
|
||||
concurrent HTTP requests share that transient admission state. Scriptorium does
|
||||
not retain workflow state: capacity is neither durable nor a queue of resumable
|
||||
runs. When admission is exhausted, HTTP returns `503 capacity_exceeded` without
|
||||
retry timing; callers choose any retry policy that is safe for another model
|
||||
call.
|
||||
|
||||
Promptkit's built-in client now allows two additional attempts for eligible
|
||||
transient provider statuses by default. Account for added calls, latency, and
|
||||
cost when planning capacity. Each repair generation has its own transient
|
||||
budget, separate from the structural repair count. Configure the engine budget
|
||||
with [`transient_retries`](config.md); `run` and `render` accept a request
|
||||
override described in the [CLI contract](cli.md), and HTTP callers can select
|
||||
one through the [API contract](api.md). Omission inherits the engine
|
||||
setting and then Promptkit's default, while explicit zero disables additional
|
||||
attempts. Existing generation timeouts apply
|
||||
per attempt, while the caller context covers the complete operation. Provider
|
||||
`Retry-After` timing can exceed Promptkit's ordinary backoff cap; consult the
|
||||
[outbound integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/integrations/openai-compatible-chat.md)
|
||||
for details.
|
||||
|
||||
CLI `run` can set a [whole-run deadline](cli.md) when total execution time must
|
||||
be bounded. The existing generation timeout applies afresh to each attempt and
|
||||
does not cap retry waits or the complete invocation. The whole-run interval
|
||||
covers the engine call, including capacity waiting and repairs as supported by
|
||||
context cancellation; it excludes parsing, engine setup, and output writes.
|
||||
HTTP callers can use [`run_timeout_seconds`](api.md) to set the engine's
|
||||
operation budget for the same interval. The API distinguishes a typed expired
|
||||
execution deadline from caller cancellation and from a provider-attempt
|
||||
timeout. A canceled capacity waiter releases its Promptkit admission state.
|
||||
|
||||
Before increasing a limit:
|
||||
|
||||
1. measure representative input, generated-output, and optional raw-output
|
||||
sizes;
|
||||
2. confirm memory, network, and upstream-provider capacity;
|
||||
3. retain an upstream request-size and authentication boundary; and
|
||||
4. test the intended workload in a non-production environment.
|
||||
|
||||
For large local inputs, prefer a controlled file-artifact directory over
|
||||
placing arbitrary paths on the service host. Avoid disabling a limit unless an
|
||||
equivalent trusted control exists elsewhere.
|
||||
|
||||
## Diagnose And Recover
|
||||
|
||||
### Preparation Or Configuration Failure
|
||||
|
||||
Capture the CLI diagnostic or HTTP error response, then verify the selected
|
||||
configuration, prompt ID, profile selection, source readability, and input
|
||||
mapping. Use `render` with the same request when it is unclear whether failure
|
||||
occurs before model execution. Consult the [CLI reference](cli.md), the
|
||||
[configuration reference](config.md), and the [HTTP API reference](api.md) for
|
||||
the exact interface contract.
|
||||
|
||||
### Credential Or Provider Failure
|
||||
|
||||
Confirm that the process environment contains the configured credential name
|
||||
without printing the secret. Check endpoint reachability and provider health
|
||||
from the process network. If preparation succeeds but generation fails, inspect
|
||||
the selected model settings in prepared output and the service's controlled
|
||||
logs. Correct the deployment or provider issue, then submit a new request.
|
||||
|
||||
### Artifact Or Permission Failure
|
||||
|
||||
Verify that the process can read the intended local input. For HTTP file
|
||||
artifacts, verify the deployment's artifact root, ownership, path layout, and
|
||||
file size. Do not widen filesystem permissions or the allowed root merely to
|
||||
make an arbitrary path work; move or copy the required artifact into the
|
||||
controlled location instead.
|
||||
|
||||
### Validation Failure
|
||||
|
||||
A generated-content validation failure is distinct from a runtime failure.
|
||||
CLI `run` reports the validation result and error count in its success summary;
|
||||
it does not print the individual validation messages. For HTTP, inspect the
|
||||
validation object in the response according to the [HTTP API reference](api.md).
|
||||
|
||||
Use rendered input and generated output to determine whether prompt instructions,
|
||||
the selected model, or the schema needs correction. If schema loading or
|
||||
compilation itself fails, correct the source deployment or schema document
|
||||
before rerunning.
|
||||
|
||||
### HTTP Limit Or Request Failure
|
||||
|
||||
Compare the request, artifact, or expected response size with the deployed
|
||||
configuration, and validate the request against the [HTTP API reference](api.md).
|
||||
Reduce the payload, use an appropriate controlled artifact source, omit
|
||||
unneeded raw output, or adjust the deployment limit after capacity review.
|
||||
|
||||
## Cleanup And Reruns
|
||||
|
||||
Because no run state is retained, cleanup concerns caller-owned output files,
|
||||
logs, and artifacts only. Remove or rotate them using the deployment's normal
|
||||
retention policy. After a correction, rerun the request from the beginning;
|
||||
there is no safe resume point.
|
||||
There is no durable run store, archive, checkpoint, or resume mechanism.
|
||||
Cleanup concerns caller-owned files/logs only. Rotate/delete them under the
|
||||
deployment's normal retention policy; recovery starts from a new request.
|
||||
|
||||
@@ -39,8 +39,8 @@ Do not promote incidental implementation choices into architectural invariants.
|
||||
|
||||
## Scriptorium's Purpose And System Shape
|
||||
|
||||
Scriptorium is an executable application with CLI `run`, `render`,
|
||||
`inspect`, and `config` command families and an HTTP service started by
|
||||
Scriptorium is an executable application with CLI `run`, native `promptkit`
|
||||
and `config` families, and an HTTP service started by
|
||||
`serve`. It offers simple, request-independent execution of predefined
|
||||
prompts, not a reusable Scriptorium root Go API or a workflow framework.
|
||||
The [internal overview](../internal/overview.md) owns the concrete package
|
||||
@@ -71,9 +71,12 @@ externally observable application behavior; PromptKit owns framework formats.
|
||||
|
||||
As decided in [ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md),
|
||||
Scriptorium adopts CommandKit's native `ckconfig` and `ckprompt` interfaces to
|
||||
neutrally expose upstream features and semantics. The current CLI still uses
|
||||
custom presentation; the [adoption roadmap](../roadmap/commandkit-adoption.md)
|
||||
tracks its replacement. This decision complements ADRs 0004 and 0005.
|
||||
neutrally expose upstream features and semantics. CommandKit owns shared command,
|
||||
parsing, presentation, and outcome mechanics; application commands and effects
|
||||
remain local. Standard configuration inspection uses native adapters without
|
||||
custom effective documents or evidence reconciliation. This decision complements
|
||||
ADRs 0004 and 0005; the [adoption roadmap](../roadmap/commandkit-adoption.md)
|
||||
records the implementation work.
|
||||
|
||||
The CLI exposes Promptkit's captured framework configuration inspection. Its
|
||||
`show` and `explain` reports use Promptkit's native redaction for classified
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
**Base Policy Version:** 1.3
|
||||
|
||||
**Last Updated**: 2026-11-17
|
||||
**Last Updated**: 2026-11-19
|
||||
|
||||
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/testing.md
|
||||
|
||||
@@ -178,12 +178,15 @@ Give each layer its distinct responsibility and keep expectation updates localiz
|
||||
diagnostics. ConfigKit owns exhaustive YAML grammar, source traversal,
|
||||
import and overlay composition, provenance, and inspection renderers.
|
||||
- CLI tests own argument mapping, streams, output, exit behavior, and
|
||||
representative run, render, inspect, serve, and config workflows.
|
||||
representative native run, PromptKit resource/requirements/preview/smoke,
|
||||
serve, and configuration comparison workflows.
|
||||
- HTTP tests own DTO decoding, transport limits, status and error mapping,
|
||||
restricted artifact reading, and representative server workflows.
|
||||
- Formatting tests own prepared-run and definition-inspection text and JSON
|
||||
presentation. Architecture guards own dependency direction and removed
|
||||
framework-package boundaries.
|
||||
- CommandKit and its integrations own standard parsing and presentation.
|
||||
Scriptorium's integration tests protect native adoption, byte-preserving main
|
||||
output, separate report effects, outcomes, and acquisition boundaries without
|
||||
reproducing the upstream formatting matrix. Architecture guards own dependency
|
||||
direction and removed framework-package boundaries.
|
||||
- Promptkit owns framework parsing, orchestration, validation, profiles, and
|
||||
model-client behavior. Scriptorium's definition and execution fixtures
|
||||
protect adoption through its public adapter boundary without duplicating
|
||||
|
||||
@@ -643,6 +643,25 @@ version output. Test-local fallback deadlines prevent regressions from hanging.
|
||||
|
||||
## Stage 8: Retire Superseded Machinery And Update Canonical Documentation
|
||||
|
||||
**Status: Complete.** Removed legacy parsing/dispatch, custom inspection/source
|
||||
DTOs and writers, retired CLI tests, and the unused formatter package. Retained
|
||||
architecture boundaries, native integration protection, checkout-discovery
|
||||
coverage, and the unchanged HTTP/report implementation and regression suites.
|
||||
Maintained examples now select external framework entries with native imports;
|
||||
both collection-entry spellings and multi-definition discovery remain present.
|
||||
Canonical CLI/configuration/process/operations/internal/development/policy owners
|
||||
and navigation reflect the cutover, with a focused CLI migration guide distinct
|
||||
from the earlier framework-format guide. Accepted ADRs and release-note history
|
||||
are unchanged; deferred HTTP redesign and dynamic completion remain deferred.
|
||||
|
||||
Verified on Go 1.27.4: full tests and race suite, vet, ordinary build, module
|
||||
tidiness, formatting/diff checks, all maintained application configs in both
|
||||
native scopes, application overlays, maintained preview scripts, a structured
|
||||
schema preview, and local Markdown links/anchors (42 files). Added maintained
|
||||
example loading/preparation protection and adapted fresh-checkout discovery to
|
||||
native preview. Entrypoint package tests now run and pass. Linked identity,
|
||||
release-target builds, and the final assembled acceptance audit remain Stage 9.
|
||||
|
||||
**Primary files:** old CLI parser/dispatch/inspection files and tests,
|
||||
`internal/format`, documentation and maintained examples listed below.
|
||||
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
# Prompt input requirements for Narratio
|
||||
|
||||
Status: accepted direction, pending implementation through the CommandKit
|
||||
migration. This proposal records Narratio's consumer needs and their mapping
|
||||
to the native interface; it does not describe shipped Scriptorium behavior.
|
||||
Status: the native interface and focused consumer scenarios are implemented.
|
||||
The [implementation plan](implementation.md) tracks final assembled verification.
|
||||
This proposal records Narratio's consumer needs and their mapping to the native
|
||||
interface; the [CLI contract](../cli.md) owns current behavior.
|
||||
The [CommandKit notepad](commandkit-notepad.md) records the migration decisions.
|
||||
|
||||
## Consumer need
|
||||
@@ -27,8 +28,8 @@ Default and explicit text output use the native YAML presentation.
|
||||
The [upstream CLI contract][requirements-cli] owns syntax and report details.
|
||||
|
||||
Use the same application configuration and framework source selection as
|
||||
execution, including `--config`, `--overlay`, and applicable application
|
||||
selectors. The preferred native aliases `--profile`, `--var`, `--session-id`, and
|
||||
execution, including `--config` and `--overlay`. There are no application-defined
|
||||
source/schema selectors. The preferred native aliases `--profile`, `--var`, `--session-id`, and
|
||||
prompt/profile namespace flags supply the relevant discovery context.
|
||||
Preserve upstream selection semantics, including the prompt's default profile
|
||||
when an explicit profile is omitted. Qualified IDs identify installed resources;
|
||||
|
||||
Reference in New Issue
Block a user