scriptorium/docs/operations.md

Operations Guide

Scope

This guide covers operating the implemented CLI commands and HTTP service. It does not replace the CLI reference, Configuration reference, or HTTP API reference.

Operational Model

Scriptorium executes one prompt request per CLI invocation or HTTP request.

Important boundaries:

• No durable run state is stored.
• No manifest, archive, checkpoint, or built-in backup workflow is written.
• No built-in resume behavior exists.
• Recovery is rerun-based: correct inputs, config, or environment, then run again.

Filesystem Layout

Operational deployments usually provide:

• prompt_dir: prompt definition YAML files and adjacent content_file templates.
• profile_dir: optional custom profile YAML files.
• schema_dir: optional JSON Schema files.
• server.artifact_root: optional HTTP file-input root for serve.

Keep these directories readable by the Scriptorium process. Keep server.artifact_root narrow and not writable by untrusted users.

Normal CLI Workflow

Use render before run when changing prompt/profile/input wiring:

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 \
  --format json

Use run for generation after preflight:

go run ./cmd/scriptorium run \
  --config ./examples/config.yml \
  --prompt generic.markdown_summary \
  --input transcript=./examples/fixtures/transcript.md \
  --input glossary=./examples/fixtures/glossary.yml \
  --out ./summary.md

Before production runs, confirm:

• the effective config path is the intended one;
• prompt/profile/schema directories are readable;
• input file paths exist and match prompt input names;
• required API-key environment variables are set;
• the selected model endpoint is reachable from the process environment.

HTTP Service Operation

Start the service with:

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

The implemented HTTP route is POST /v1/runs; request and response fields are defined in the HTTP API reference.

The maintained HTTP request-shape example is examples/http-run.json.

HTTP service notes:

• Unknown JSON fields are rejected.
• inline input references work without an artifact root.
• file input references require server.artifact_root or serve --artifact-root.
• Request bodies, HTTP file input artifacts, and encoded JSON responses are size-limited.
• Validation content failures return 200 OK with validation.status: "failed".

Security boundary:

• serve has no built-in authentication or authorization.
• Put it behind trusted controls such as a private network, authenticated reverse proxy, or API gateway.
• Do not expose an artifact root containing unrelated sensitive files.
• Symlinks inside the artifact root are followed by the operating system.

Secrets Handling

Raw API keys are not accepted in app config, profiles, CLI flags, or HTTP request bodies.

Use this pattern:

1. Set an environment variable containing the secret value.
2. Store only the variable name in profile api_key_env or request override api_key_env.
3. Scope the process environment to the minimum required variables.

Output, Logs, And Exit Codes

run:

• stdout: generated artifact body unless --out is used.
• stderr: summary on success, errors on failure.
• exit 2: generation completed and output was written, but validation failed.

render:

• stdout: prepared-run output unless --out is used.
• stderr: errors.
• exit 0 on success, 1 on failure.

serve:

• stderr: startup and server errors.
• HTTP response body: JSON success or error envelope.

Validation Behavior

Prompt output.validation_mode controls validation:

• none: skipped.
• basic: output body must not be empty.
• json: output body must parse as JSON.
• json_schema: output body must parse as JSON and satisfy the configured schema.

Runtime/schema failures are hard failures (run exit 1, HTTP error). Generated-content validation failures are soft failures (run exit 2, HTTP 200 OK with failed validation status).

Size Limits

Defaults are documented in Configuration reference. Operationally:

• Keep default HTTP limits unless larger payloads are measured and expected.
• Prefer inline HTTP inputs for small payloads.
• Prefer file HTTP inputs for larger local artifacts under a controlled artifact root.
• Increase server.max_response_bytes when generated artifacts or requested raw output are expected to be large.
• Use 0 only when another trusted layer enforces size limits.

Maintained Examples

• examples/config.yml
• examples/config.full.yml
• examples/render-markdown-summary.sh
• examples/http-run.json

Safe Recovery

For failed CLI commands or HTTP requests:

1. Capture stderr or the HTTP error code and message.
2. Confirm config path and effective directory settings.
3. Verify prompt ID, profile ID, schema path, and input mappings.
4. Verify required API-key environment variables.
5. Reproduce with render --format json when pre-LLM resolution is uncertain.
6. Rerun after correction.

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