Establish canonical documentation links

docs/integrations/subprocess.md

@@ -0,0 +1,114 @@
+# Subprocess Integration
+
+## Purpose
+
+This document defines the supported subprocess contract for downstream applications invoking Scriptorium through the public CLI.
+
+This is a CLI contract, not an internal Go package integration.
+
+## Supported Commands
+
+Downstream applications 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 transcript=<path> \
+  --out <artifact_path>
+```
+
+Render:
+
+```bash
+scriptorium render \
+  --prompt <prompt_id> \
+  --input transcript=<path> \
+  --format json
+```
+
+Callers 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
+
+Callers 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
+
+Callers 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
+
+Callers 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](../cli.md)
+- Config behavior: [Configuration reference](../config.md)
+- Operations and failure handling: [Operations guide](../operations.md), [Troubleshooting](../troubleshooting.md)