Expand consumer integration documentation

docs/integrations/subprocess.md

@@ -1,59 +1,67 @@
 # Subprocess Integration
 
-## Purpose
+This document defines the supported subprocess contract for downstream
+applications invoking Scriptorium through the public CLI.
 
-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.
+This is a CLI contract. Go callers that want an in-process typed API should use
+the [package guide](../consumers/pkg-scriptorium.md).
 
 ## Supported Commands
 
 Downstream applications should invoke:
 
-- `scriptorium run`
-- `scriptorium render`
+- `scriptorium render` for preflight/debug output without LLM execution.
+- `scriptorium run` for generation.
 
-Use `run` for generation.
-
-Use `render` for preflight/debug output without LLM execution.
+`scriptorium serve` is an HTTP service command, not the recommended subprocess
+contract for per-request execution.
 
 ## Recommended Invocation Shapes
 
-Run:
-
-```bash
-scriptorium run \
-  --prompt <prompt_id> \
-  --input transcript=<path> \
-  --out <artifact_path>
-```
-
 Render:
 
 ```bash
 scriptorium render \
+  --config <config_path> \
   --prompt <prompt_id> \
   --input transcript=<path> \
   --format json
 ```
 
+Run:
+
+```bash
+scriptorium run \
+  --config <config_path> \
+  --prompt <prompt_id> \
+  --input transcript=<path> \
+  --out <artifact_path>
+```
+
 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.)
+- runtime overrides when explicitly needed, such as `--model`, `--llm-base-url`, `--api-key-env`, and `--timeout`
+
+Do not pass raw API keys as command arguments.
 
 ## 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
+Default config search order:
+
+1. `/usr/local/etc/scriptorium/config.yml`
+2. `/etc/scriptorium/config.yml`
+
+Rules:
+
+- Explicit `--config` requires file existence and valid syntax.
+- CLI flags override config values.
+- `run` and `render` require an effective `prompt_dir`.
+- `profile_dir` is optional because built-in profiles are available.
 
 ## Profile Selection
 
@@ -63,52 +71,60 @@ Profile selection follows runner behavior:
 2. prompt `default_profile`
 3. error if neither is available
 
-Callers should treat prompt/profile IDs as deployment configuration, not hardcoded logic.
+Treat prompt and profile IDs as deployment configuration, not hardcoded business
+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.
+- Variables use repeated `--var name=value`.
+- Both flags also accept comma-separated mappings.
 - Prefer file inputs for large content.
 
+CLI inputs are file references. HTTP-only `inline` references are documented in
+the [HTTP API reference](../api.md).
+
 ## 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.
+- Keep subprocess environments scoped to required variables.
+- Use `--api-key-env` only to name an environment variable.
+- Never pass raw API keys via argv.
 
-## Output And Error Handling
+## Stdout And Stderr
 
 `run`:
 
-- stdout: artifact body unless `--out` is used
-- `--out`: writes artifact to file
-- stderr: success summary and errors
+- stdout: generated artifact body unless `--out` is used.
+- stderr: success summary and errors.
 
 `render`:
 
-- stdout: prepared-run output unless `--out` is used
-- stderr: errors
+- stdout: prepared-run output unless `--out` is used.
+- stderr: errors.
 
-Callers should capture stdout and stderr separately.
+Capture stdout and stderr separately. Do not parse stderr as a stable data
+format beyond exit status handling.
 
 ## Exit Status Contract
 
-- `0`: success
-- `1`: parse/config/load/render/generation/IO/runtime error
-- `2`: run completed but validation failed
+- `0`: success.
+- `1`: parse, config, load, render, generation, IO, or runtime error.
+- `2`: `run` completed and output was written, but validation failed.
 
-A `run` exit code `2` can still produce output (stdout or `--out`).
+A `run` exit code `2` can still produce output on stdout or at `--out`.
+Consumers must decide whether to keep or discard that output.
 
 ## Security Notes
 
-- Treat generated artifacts and stderr logs as potentially sensitive.
-- Avoid logging full rendered prompts by default in production contexts.
+- Treat generated artifacts, rendered prompts, stdout, and stderr as potentially sensitive.
 - Use controlled output paths and access controls for persisted artifacts.
+- Avoid logging full rendered prompts or generated artifacts by default.
 
 ## 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)
+- Config and file formats: [Configuration reference](../config.md)
+- Operations: [Operations guide](../operations.md)
+- Troubleshooting: [Troubleshooting](../troubleshooting.md)