scriptorium/docs/operations.md

Operations Guide

Scope And References

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.

• CLI reference: commands, output destinations, and exit codes.
• Configuration reference: configuration, prompt/profile/schema formats, defaults, and credentials.
• HTTP API reference: route, request/response schema, status codes, limits, and HTTP artifact access.
• Consumer integration overview: caller responsibilities.

Operational Model And State

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.

Generated artifacts, rendered prompts, model output, and run metadata are caller-owned data. Retention, encryption, backup, and deletion are deployment responsibilities.

Deploy The Filesystem And Process

Provide the process with readable prompt, profile, and schema sources. Keep prompt templates adjacent to the prompt definitions that reference them. For an HTTP deployment that accepts file artifacts, use a dedicated, narrow artifact directory rather than a general-purpose or sensitive filesystem tree.

Run Scriptorium under an identity that can:

• 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.

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 for the externally observable behavior.

Supply Credentials And Protect Runtime Data

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.

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.

Run A Normal Workflow

Before changing production inputs, profiles, or schemas:

1. confirm the deployed configuration selects the intended sources and model credentials;
2. use render with the same request inputs and variables to confirm preparation without a model call;
3. use run for generation; and
4. retain or discard validation-failed output according to the caller's policy.

The maintained render script is a copyable preflight example. The CLI reference owns its complete invocation and exit semantics.

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 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 and rely on the HTTP API reference for their response effects.

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, the configuration reference, and the HTTP API reference 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.

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. 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.