Move documentation for external integrations into the docs/integrations subfolder

docs/integrations/scriptorium.md

@@ -0,0 +1,64 @@
+# Integration: scriptorium
+
+## Purpose
+Define Narratio's adapter contract for Scriptorium artifact generation and render-debug subprocess invocations.
+
+## 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
+
+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
+
+## 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
+
+Does not own:
+- Artifact selection policy (`analyze` stage)
+- Bounds semantic validation (`trim` stage)
+
+## 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`
+
+## External Adapters Used
+- Shared subprocess helper (`internal/adapters/subprocess`).
+
+## State and Manifest Behavior
+- No direct manifest writes.
+- Stage metadata records adapter outputs and command mode.
+- Generated invocation YAML is written when requested.
+
+## Skip and Resume Behavior
+- Adapter has no skip/resume logic. Stage/runner controls execution.
+
+## 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.
+
+## 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`
+
+## 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.