Rewrite integration documentation and verify maintained examples

docs/integrations/scriptorium.md

@@ -1,64 +1,66 @@
-# Integration: scriptorium
+# Integration: Scriptorium
 
 ## Purpose
-Define Narratio's adapter contract for Scriptorium artifact generation and render-debug subprocess invocations.
+Define the Scriptorium adapter contract used by `analyze` and trim-bounds generation in `trim`.
 
-## Inputs and Outputs
-Inputs:
-- `RunArtifactRequest`: binary, config path, prompt/profile IDs, input map, vars map, timeout, output path, logs/config paths, optional API env and working dir
-- `RenderArtifactRequest`: same core fields for render mode
+## Adapter Boundary
+Interface:
+- `scriptorium.Runner`
+- methods:
+  - `RunArtifact(ctx, RunArtifactRequest)`
+  - `RenderArtifact(ctx, RenderArtifactRequest)`
 
-Outputs (`ArtifactResult`):
-- output path
-- stdout/stderr log paths
-- generated config path
-- exit code and duration
-- command mode (`run` or `render`)
-- prompt/profile provenance
-- validation failure signal
-- adapter metadata
+Primary implementation:
+- `internal/adapters/scriptorium/SubprocessRunner`
 
-## Boundaries
-Owns:
-- Deterministic CLI arg construction for `scriptorium run` and `scriptorium render`
-- Common request validation
-- Invocation config emission
-- Output existence/non-empty checks
-- Validation-failure mapping for run exit code 2
+Execution modes:
+- `scriptorium run`
+- `scriptorium render`
 
-Does not own:
-- Artifact selection policy (`analyze` stage)
-- Bounds semantic validation (`trim` stage)
+## Request Contract
+Both request types carry:
+- binary/config/prompt/profile IDs;
+- input map and vars map;
+- output path;
+- timeout;
+- generated config + stdout/stderr log paths;
+- optional API-key env var name;
+- optional working directory.
 
-## Config Fields Used
-Via `pipeline.scriptorium.*` and stage-level artifact config:
-- `binary`, `config_path`, `timeout`, `render_debug`
-- artifact-level `prompt_id`, `profile_id`, `timeout`, `inputs`, `vars`, `output_path`
+## Result Contract
+`ArtifactResult` returns:
+- output/log/generated-config paths;
+- exit code and duration;
+- command mode (`run` or `render`);
+- prompt/profile provenance;
+- `ValidationFailed` marker;
+- metadata map.
 
-## External Adapters Used
-- Shared subprocess helper (`internal/adapters/subprocess`).
+## Validation and Failure Semantics
+Request validation fails for:
+- missing binary, prompt id, or output path;
+- non-positive timeout;
+- empty input/var names;
+- empty input path values;
+- missing required credential env var when `APIKeyEnv` is set.
 
-## State and Manifest Behavior
-- No direct manifest writes.
-- Stage metadata records adapter outputs and command mode.
-- Generated invocation YAML is written when requested.
+Run behavior:
+- subprocess errors propagate with context;
+- `run` exit code `2` is mapped to `ValidationFailed=true`;
+- successful subprocess still fails if output file is missing or empty.
 
-## Skip and Resume Behavior
-- Adapter has no skip/resume logic. Stage/runner controls execution.
+Render behavior:
+- subprocess errors propagate;
+- output file must exist and be non-empty.
 
-## Failure Behavior
-- Request validation fails for missing binary/prompt/output, invalid timeout, invalid input/var names, or missing required API env var.
-- Subprocess errors bubble with command context.
-- `run` exit code 2 is treated as `ValidationFailed=true` and surfaced as error by calling stage.
-- Successful subprocess still fails if output file is missing/empty.
+## Deterministic Behavior
+- input and var maps are sorted into deterministic `--input` and `--var` CLI args.
+- generated invocation YAML (`scriptorium.generated.v1`) is emitted when requested.
+- adapter is stateless and does not own artifact-selection policy.
 
-## Tests to Inspect Before Changing
-- `internal/adapters/scriptorium/subprocess_test.go`
-- `internal/adapters/scriptorium/fake_test.go`
-- `internal/stage/analyze_test.go`
-- `internal/stage/trim_test.go`
+## Config Mapping
+Config fields consumed through runner/stage wiring are under `pipeline.scriptorium.*` plus per-artifact settings under `pipeline.scriptorium.artifacts.*`.
 
-## Architectural Invariants
-- Both modes require explicit timeout > 0.
-- Input/var maps are sorted into deterministic CLI argument order.
-- Run-mode validation failures are represented explicitly, not silently skipped.
+Maintained examples with Scriptorium config:
+- `examples/pipeline.full.annotated.yml`
+- `examples/pipeline.production.yml`