scriptorium/docs/operations.md

Operations Guide

Scope

This document covers day-to-day operation of the CLI and HTTP service for currently implemented behavior.

For command syntax, see CLI reference. For file formats and defaults, see Configuration reference.

Operational Model

Scriptorium executes one request at a time per CLI invocation or HTTP request.

Important boundaries:

• No durable run state is stored.
• No built-in resume, checkpoint, archive, or backup workflow exists.
• Recovery is rerun-based: fix inputs/config, then rerun.

Filesystem Layout And Config

Scriptorium depends on:

• prompt definition files (prompt_dir)
• execution profile files (profile_dir)
• optional JSON schemas (schema_dir)

Config discovery order when --config is omitted:

1. /usr/local/etc/scriptorium/config.yml
2. /etc/scriptorium/config.yml

If neither exists, built-in defaults are used. If --config <path> is provided, that file must exist and parse successfully.

Built-in defaults relevant to operations:

• schema_dir: .
• server.addr: :8080
• server.artifact_root: unset; HTTP file input references are rejected until configured
• server.max_request_bytes: 16777216
• server.max_artifact_bytes: 16777216
• server.max_response_bytes: 16777216
• defaults.render_format: text

Normal CLI Workflow

Use render first when you need to verify prompt resolution and runtime settings without calling a model.

Use run for generation.

Typical sequence:

1. Confirm prompt/profile directories resolve through config or flags.
2. Confirm required input files exist and map to prompt input names.
3. Confirm required API-key environment variables are set.
4. Confirm the selected profile's model endpoint is reachable from the process environment.
5. Run render for preflight when changing prompt/profile/input wiring.
6. Run run for actual generation.

Secrets Handling

Raw API keys are not accepted in config files, profile files as api_key, CLI flags, or HTTP request bodies.

Operational pattern:

• Set environment variables that hold secret values.
• Set profile api_key_env (or runtime override api_key_env) to the environment variable name.
• Keep process environments scoped to only required variables.

HTTP Service Operation

Start service with:

go run ./cmd/scriptorium serve --config ./examples/config.yml

Current inbound API behavior:

• Route: POST /v1/runs
• JSON request parsing rejects unknown fields.
• Validation content failures still return 200 OK with validation.status: "failed".
• inline input references work without filesystem configuration.
• file input references require server.artifact_root or serve --artifact-root; relative traversal and absolute paths that are lexically outside that root are rejected.
• Request bodies, HTTP file input artifacts, and encoded JSON responses are limited by server.max_request_bytes, server.max_artifact_bytes, and server.max_response_bytes.

Security caveat:

• serve has no built-in authentication or authorization.
• Deploy only behind trusted controls (private network boundary, authenticated reverse proxy, API gateway, or equivalent).
• Keep the HTTP artifact root as narrow as practical and do not make it writable by untrusted users. Symlinks inside the root are followed by the operating system, including symlinks that point outside the root.

Sizing guidance:

• Keep limits at the defaults unless a deployment has a measured need for larger prompt inputs or outputs.
• Prefer inline inputs for small payloads and HTTP file inputs for larger local artifacts inside a controlled artifact root.
• Increase the response limit when prompts intentionally return large generated artifacts or when clients request include_raw_output.
• Set a limit to 0 only for trusted deployments where another layer enforces request and response size.

Output, Logs, And Exit Codes

run command:

• Generated artifact body goes to stdout by default.
• --out writes generated artifact to a file.
• Summary metadata line is written to stderr on success.
• Exit code 2 means generation completed but validation failed.

render command:

• Prepared-run output goes to stdout by default.
• --out writes prepared-run output to a file.
• Exit code is 0 on success and 1 on failure.

serve command:

• Startup and server errors are written to stderr.

Validation Behavior In Operations

Validation modes (none, basic, json, json_schema) are defined by prompt output contract.

Operational interpretation:

• Validation runtime errors are hard failures (run exit 1; HTTP error response).
• Validation content failures are soft failures (run exit 2; HTTP 200 with failed status).

A failed validation run can still produce output. Decide whether to keep or discard that output in your surrounding workflow.

Safe Recovery Steps

For failed runs or requests:

1. Capture stderr output or HTTP error code/message.
2. Confirm config path and directory settings.
3. Verify prompt/profile IDs and input mappings.
4. Verify API-key environment-variable presence when required.
5. Reproduce with render --format json when prompt/profile/input resolution is uncertain.
6. Rerun after correction.

Because Scriptorium does not persist run state, rerun is the canonical recovery path.