Document internal component boundaries

docs/internal/scriptorium-adapter.md

@@ -1,59 +1,67 @@
 # Scriptorium Adapter Internals
 
-This document describes the implemented `scriptorium` subprocess adapter.
+This document describes the subprocess adapter in
+`internal/adapters/scriptorium`.
 
 ## Purpose
 
-`internal/adapters/scriptorium` runs `scriptorium render` to preflight prompt
-wiring and `scriptorium run` to generate report artifacts.
+The adapter runs `scriptorium render` for prompt preflight and `scriptorium run`
+for Markdown report generation while isolating subprocess details from domain
+packages.
 
-## Inputs and Outputs
+## Inputs And Outputs
 
-Input:
+Inputs:
 
 - prompt ID
 - prompt input data package path
 - report output path for `run`
 - configured binary, config path, profile, timeout, and extra arguments
 
-Output:
+Outputs:
 
-- captured stdout, with truncation tracking
-- captured stderr, with truncation tracking
+- argv used for execution
+- captured stdout and stderr with truncation flags
 - exit code
-- full argv used for inspection
+- report output path for `run`
 
 ## Boundaries
 
-- This adapter owns `scriptorium` CLI flag construction and subprocess
-  execution.
-- It does not choose report types, build prompt input, fetch weather data, or
-  decide workflow order.
+- This adapter owns Scriptorium argv construction and subprocess execution.
+- It does not choose report types, build prompt input, fetch weather data,
+  decide workflow order, or persist workflow metadata.
 
-## Behavior
+## Config Fields Used
 
-The render invocation shape is:
+- `scriptorium.binary`
+- `scriptorium.config_path`
+- `scriptorium.profile`
+- `scriptorium.timeout`
+- `scriptorium.extra_args`
 
-```text
-scriptorium render --prompt <prompt_id> --input data_package=<path> --format json
-```
+## External Adapters Used
 
-The run invocation shape is:
+- external `scriptorium` CLI
 
-```text
-scriptorium run --prompt <prompt_id> --input data_package=<path> --out <artifact_path>
-```
+See [Scriptorium integration](../integrations/scriptorium.md) for the external
+CLI contract used by this project.
 
-Configured `--config` and `--profile` values are added when present. Arguments
-are passed directly as argv, not through a shell. Stdout and stderr are captured
-separately. `SaveRenderResult` writes the captured result as JSON for inspection.
+## State Or Manifest Behavior
+
+`SaveRenderResult` can write render results atomically. The app and state store
+own managed preflight paths and metadata links.
+
+## Skip And Resume Behavior
+
+None. Context cancellation and configured timeout stop subprocess execution.
 
 ## Failure Behavior
 
-Nonzero render and run exits return both the captured result and an error
-containing the exit code and stderr. Run exit code `2` is treated as an error
-but may still produce a report artifact. Command execution respects context
-cancellation and the configured timeout.
+- Missing prompt ID, data package path, or run output path returns an error.
+- Subprocess start or context errors are wrapped with operation context.
+- Nonzero render and run exits return captured output plus an error containing
+  exit code and stderr.
+- Captured stdout and stderr are size-limited and marked when truncated.
 
 ## Tests
 
@@ -65,7 +73,6 @@ Inspect:
 
 ## Invariants
 
-- `scriptorium` details stay inside the adapter package.
-- The input name for prompt packages is always `data_package`.
-- Render preflight remains orchestration behavior; this adapter only exposes the
-  subprocess operations.
+- No shell interpolation is used.
+- The Scriptorium input name is `data_package`.
+- Scriptorium-specific flags stay inside adapter and config boundaries.