# weatherreporter Subprocess Integration

## Purpose

This document defines the supported subprocess contract for weatherreporter invoking Scriptorium through the public CLI.

This is a CLI contract, not an internal Go package integration.

## Supported Commands

weatherreporter should invoke:

- `scriptorium run`
- `scriptorium render`

Use `run` for generation.

Use `render` for preflight/debug output without LLM execution.

## Recommended Invocation Shapes

Run:

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

Render:

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

weatherreporter may add:

- `--config <path>`
- `--profile <profile_id>`
- repeatable `--input name=path`
- repeatable `--var name=value`
- runtime overrides when explicitly needed (`--model`, `--llm-base-url`, `--timeout`, etc.)

## Config And Directory Behavior

weatherreporter can rely on resolved app config or pass explicit paths.

- default config search order:
  1. `/usr/local/etc/scriptorium/config.yml`
  2. `/etc/scriptorium/config.yml`
- explicit `--config` requires file existence and valid syntax
- CLI flags override config values

## Profile Selection

Profile selection follows runner behavior:

1. explicit `--profile`
2. prompt `default_profile`
3. error if neither is available

weatherreporter should treat prompt/profile IDs as deployment configuration, not hardcoded logic.

## Input And Variable Contract

- Inputs use repeated `--input name=path`.
- Input names must match prompt definition input names.
- Variables use repeated `--var name=value` for small metadata values.
- Prefer file inputs for large content.

## Environment Contract

- Pass through required API-key environment variables referenced by `api_key_env`.
- Never pass raw API keys via CLI arguments.
- Keep subprocess environment scoped to required variables.

## Output And Error Handling

`run`:

- stdout: artifact body unless `--out` is used
- `--out`: writes artifact to file
- stderr: success summary and errors

`render`:

- stdout: prepared-run output unless `--out` is used
- stderr: errors

weatherreporter should capture stdout and stderr separately.

## Exit Status Contract

- `0`: success
- `1`: parse/config/load/render/generation/IO/runtime error
- `2`: run completed but validation failed

A `run` exit code `2` can still produce output (stdout or `--out`).

## Security Notes

- Treat generated artifacts and stderr logs as potentially sensitive.
- Avoid logging full rendered prompts by default in production contexts.
- Use controlled output paths and access controls for persisted artifacts.

## Canonical References

- CLI behavior: [CLI reference](https://gitea.maximumdirect.net/eric/scriptorium/docs/cli.md)
- Config behavior: [Configuration reference](https://gitea.maximumdirect.net/eric/scriptorium/docs/config.md)
- Operations and failure handling: [Operations guide](https://gitea.maximumdirect.net/eric/scriptorium/docs/operations.md), [Troubleshooting](https://gitea.maximumdirect.net/eric/scriptorium/docs/troubleshooting.md)