# Scriptorium Integration

`weatherreporter` invokes the Scriptorium executable as a subprocess to
preflight prompt input and produce report artifacts. This is the limited CLI
contract Weatherreporter uses, not general Scriptorium documentation.

## Invocation

The configured `scriptorium.binary` is the executable name or path. When it is
empty, the adapter invokes `scriptorium`. Arguments are passed directly to the
process, without a shell.

For every command, arguments occur in this order:

1. The subcommand.
2. `--config <path>` when `scriptorium.config_path` is set.
3. `--profile <profile>` when `scriptorium.profile` is set.
4. The command-specific arguments below.
5. Each configured `scriptorium.extra_args` item.

The adapter uses these exact command shapes:

```text
scriptorium render [--config <path>] [--profile <profile>] \
  --prompt <prompt_id> --input data_package=<data_package_path> --format json \
  [<extra_arg> ...]

scriptorium run [--config <path>] [--profile <profile>] \
  --prompt <prompt_id> --input data_package=<data_package_path> --out <output_path> \
  [<extra_arg> ...]
```

`render` is the preflight command. `run` writes a structured generated-text
artifact to the supplied `--out` path. It does not add `--format`, `--schema`,
`--schema-path`, or `--json-schema` flags. Prompt configuration selected by
`<prompt_id>` controls that output.

## Inputs and Outputs

Weatherreporter always supplies exactly one prompt input:
`--input data_package=<data_package_path>`. The path identifies the YAML data
package produced by the [prompt-input builder](../internal/prompt-input.md).
Its schema and the separate JSON module snapshots are internal artifacts, not
part of this CLI contract.

The application supplies an already-managed output path to every `run` call.
For direct reports it is the Markdown artifact path. For generated-text
reports it is the raw JSON artifact path; subsequent validation and Markdown
rendering are owned by [generated-text processing](../internal/generatedtext.md).

`render` has no output-path argument. Its JSON-formatted stdout remains
captured output: the adapter records it and does not parse it into a separate
CLI result type. Likewise, the adapter records `run` output metadata without
decoding the artifact written at `--out`.

## Execution and Results

`scriptorium.timeout`, when greater than zero, creates a timeout for each
subprocess invocation. Parent-context cancellation and that timeout stop the
command through the process context.

Stdout and stderr are captured independently, each up to 1 MiB. Every returned
result records the complete argv as `command`, the captured `stdout` and
`stderr`, `exitCode`, and `stdoutTruncated` and `stderrTruncated` when a stream
was capped. Results from both forms of `run` also record `outputPath`, the
requested `--out` value.

The [Scriptorium adapter](../internal/scriptorium-adapter.md) owns process
execution and result capture. [Application orchestration](../internal/app-orchestration.md)
owns when preflight output, report artifacts, and generated-text artifacts are
persisted.

## Failure Behavior

Before starting Scriptorium, the adapter requires a prompt ID and data-package
path for every command, plus an output path for `run`. Missing fields fail
without executing a subprocess.

A nonzero process exit returns the captured result and an error that includes
the exit code and stderr. An output file written before such an exit does not
make the request successful. Failures to start the command, context
cancellation, and timeout return an error rather than a successful result.

## Operational Notes

- Extra arguments are argv items; they are not shell-interpreted.
- Prompt input, generated artifacts, stdout, and stderr can contain
  operationally sensitive weather data.
- Provide API keys through the Scriptorium environment or its configuration,
  not through Weatherreporter CLI arguments.