Refresh cleanup-related documentation

docs/internal/scriptorium-adapter.md

@@ -6,8 +6,9 @@ This document describes the subprocess adapter in
 ## Purpose
 
 The adapter runs `scriptorium render` for prompt preflight and `scriptorium run`
-for Markdown report generation while isolating subprocess details from domain
-packages.
+for Markdown report generation. It isolates subprocess execution, argv
+construction, timeout handling, output capture, and exit-code interpretation
+from app and domain packages.
 
 ## Inputs And Outputs
 
@@ -17,19 +18,25 @@ Inputs:
 - prompt input data package path
 - report output path for `run`
 - configured binary, config path, profile, timeout, and extra arguments
+- context for cancellation
 
 Outputs:
 
 - argv used for execution
-- captured stdout and stderr with truncation flags
+- captured stdout and stderr
+- truncation flags for captured output
 - exit code
 - report output path for `run`
 
 ## Boundaries
 
-- 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.
+`internal/adapters/scriptorium` owns Scriptorium command construction and
+subprocess execution. It does not choose report types, build prompt input,
+fetch weather data, decide workflow order, or persist workflow metadata.
+
+The adapter exposes request and result structs for render and run operations.
+State persistence uses a state-owned preflight artifact shape; app
+orchestration converts render results before saving.
 
 ## Config Fields Used
 
@@ -39,29 +46,43 @@ Outputs:
 - `scriptorium.timeout`
 - `scriptorium.extra_args`
 
-## External Adapters Used
+## Commands
 
-- external `scriptorium` CLI
+Render preflight argv starts with:
 
-See [Scriptorium integration](../integrations/scriptorium.md) for the external
-CLI contract used by this project.
+```text
+scriptorium render --prompt <prompt_id> --input data_package=<path> --format json
+```
 
-## State Or Manifest Behavior
+Report generation argv starts with:
 
-None directly. The adapter returns render and run results; app orchestration and
-state own managed preflight paths and metadata links.
+```text
+scriptorium run --prompt <prompt_id> --input data_package=<path> --out <path>
+```
 
-## Skip And Resume Behavior
+Configured `--config` and `--profile` flags are inserted after the subcommand
+and before prompt-specific arguments. Extra arguments are appended after the
+built-in arguments.
 
-None. Context cancellation and configured timeout stop subprocess execution.
+## Execution Behavior
+
+The adapter runs commands without shell interpolation. The same private
+execution path is used by render and run after command-specific request
+validation and argv construction.
+
+When `scriptorium.timeout` is greater than zero, each subprocess call uses a
+context with that timeout. Stdout and stderr are captured separately, capped at
+1 MiB each, and marked as truncated when the cap is reached.
 
 ## Failure Behavior
 
-- 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.
+- Missing prompt ID or data package path returns an error before subprocess
+  execution.
+- Missing run output path returns an error before subprocess execution.
+- Subprocess start errors, context cancellation, and timeouts are wrapped with
+  operation context by the caller-facing method.
+- Nonzero render and run exits return the captured result plus an error
+  containing the exit code and stderr.
 
 ## Tests
 
@@ -75,4 +96,5 @@ Inspect:
 
 - No shell interpolation is used.
 - The Scriptorium input name is `data_package`.
+- Render and run preserve command-specific result structs.
 - Scriptorium-specific flags stay inside adapter and config boundaries.