# 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](cli.md). For file formats and defaults, see [Configuration reference](config.md).

## 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:

```bash
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 paths resolve inside that root and paths outside it 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.

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.