Retire the legacy CLI and document native operator workflows

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

View File

@@ -1,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).