# Scriptorium Integration

This document describes the external Scriptorium CLI contract used by
`weatherreporter`.

## Purpose

`weatherreporter` invokes Scriptorium as a subprocess to preflight prompt input
and generate report artifacts. This page documents the CLI surface the adapter
uses, not the full Scriptorium product.

## Commands Used

Render preflight:

```bash
scriptorium render \
  --prompt <prompt_id> \
  --input data_package=<path> \
  --format json
```

Report generation:

```bash
scriptorium run \
  --prompt <prompt_id> \
  --input data_package=<path> \
  --out <artifact_path>
```

Structured generated-text report generation uses the same command shape:

```bash
scriptorium run \
  --prompt <prompt_id> \
  --input data_package=<path> \
  --out <generated_text_raw_path>
```

`weatherreporter` always passes prompt input as
`--input data_package=<path>`. The data package is structured YAML created by
`internal/promptinput`; module snapshots remain separate JSON artifacts for
inspection and Recent Changes.

For generated-text reports, Scriptorium selects the structured output schema
from the prompt configuration associated with the prompt ID. `weatherreporter`
does not pass `--format`, schema path, or JSON Schema flags for structured
generation.

## Configured Arguments

The adapter can prepend configured flags before prompt-specific arguments:

- `--config <path>` from `scriptorium.config_path`
- `--profile <profile>` from `scriptorium.profile`

It appends `scriptorium.extra_args` after the built-in arguments. Extra
arguments are passed directly as argv items.

`scriptorium.binary` selects the executable name or path. If unset inside the
adapter, it falls back to `scriptorium`.

## Execution Behavior

The adapter runs Scriptorium without shell interpolation. Arguments are passed
through `exec.CommandContext`.

`scriptorium.timeout` limits each subprocess call when configured. Context
cancellation or timeout returns an execution error.

Stdout and stderr are captured separately. Each stream is capped at 1 MiB and
the result records whether truncation occurred.

## Results

Render results include:

- full argv recorded as `command`
- stdout
- stderr
- exit code
- truncation flags when applicable

Run results include the same fields plus the requested output path. Structured
generated-text run results use the same captured fields and output-path
recording, with the output path pointing at the raw generated-text JSON
artifact.

`weatherreporter` persists render preflight JSON when orchestration reaches the
preflight save point. For direct Markdown reports, Scriptorium writes the
managed Markdown artifact to the `--out` path. For generated-text-template
reports, Scriptorium writes raw JSON to the `--out` path; later
weatherreporter workflow steps validate those bytes and render Markdown from an
embedded template.

## Failure Behavior

The adapter validates required request fields before starting Scriptorium:

- prompt ID
- data package path
- output path for `run` and structured generated-text `run`

Nonzero exits return both the captured result and an error containing the exit
code and stderr. A `run` exit code such as `2` is still treated as an error by
the adapter, even if Scriptorium wrote output to the requested artifact path.

Subprocess start failures, context cancellation, and timeouts return errors
without fabricating a successful result.

## Security Notes

- The adapter does not invoke a shell.
- Generated artifacts, rendered prompt context, stdout, and stderr can contain
  operationally sensitive data.
- API keys should be provided through the Scriptorium environment or
  Scriptorium configuration, not through `weatherreporter` CLI arguments.