Rewrite integration documentation and verify maintained examples

docs/integrations/audita.md

@@ -1,66 +1,60 @@
-# Integration: audita
+# Integration: Audita
 
 ## Purpose
-Define Narratio's adapter contract for transcript polishing via Audita CLI subprocess execution.
+Define the Audita adapter contract used by the `polish` stage.
 
-## Inputs and Outputs
-Inputs (`audita.PolishRequest`):
-- base transcript path
-- glossary path
-- output polished transcript path
-- optional report path (required when report enabled)
-- work dir
-- generated config path
-- stdout/stderr log paths
-- optional module/model/base URL and concurrency knobs
+## Adapter Boundary
+Interface:
+- `audita.Runner`
+- method: `Run(ctx, PolishRequest) (PolishResult, error)`
 
-Outputs (`audita.PolishResult`):
-- polished transcript path
-- optional report path
-- generated config path
-- stdout/stderr log paths
-- exit code, duration, invoked binary
-- adapter metadata
+Primary implementation:
+- `internal/adapters/audita/SubprocessRunner`
 
-## Boundaries
-Owns:
-- Deterministic CLI argument construction for `audita process`
-- Environment bridging for API credentials
-- Invocation config emission
-- Output validation for polished transcript and report
+Execution mode:
+- subprocess invocation of `audita process`
 
-Does not own:
-- Upstream/downstream stage orchestration
-- Credential sourcing policy beyond required env-var presence check
+## Request Contract
+`PolishRequest` carries:
+- required transcript/glossary/output/work-dir paths;
+- optional report path (required when report mode is enabled);
+- generated config and stdout/stderr log paths;
+- optional module/model/base-url/config/output-schema/concurrency settings.
 
-## Config Fields Used
-Via `pipeline.audita.*` mapped in app/stage wiring:
-- `binary`, `timeout`, `llm_api_key_env`, `modules`, `base_url`, `model`
-- `transcript_description`, `config_path`, `output_schema`, `work_dir_retention`
-- `total_llm_concurrency`, `proposal_llm_concurrency`, `validation_model`, `validation_llm_concurrency`, `report`
+## Result Contract
+`PolishResult` returns:
+- processed transcript path;
+- optional report path;
+- work dir and generated-config/log paths;
+- exit code, duration, binary provenance;
+- adapter metadata map.
 
-## External Adapters Used
-- Shared subprocess helper (`internal/adapters/subprocess`) to run CLI and capture logs.
+## Validation and Failure Semantics
+Construction fails for invalid static config values, including:
+- empty binary;
+- non-positive timeout;
+- invalid base URL;
+- invalid output schema;
+- invalid work-dir retention value;
+- invalid concurrency values.
 
-## State and Manifest Behavior
-- No direct manifest writes.
-- Stage-level metadata records adapter provenance and credential-present signal.
-- Generated invocation YAML is written when `GeneratedConfigPath` is provided.
+Run fails for:
+- missing required request paths;
+- missing required credential env var when configured (`llm_api_key_env`);
+- subprocess execution failure;
+- invalid processed transcript JSON (`segments` array required);
+- invalid report JSON when reporting is enabled.
 
-## Skip and Resume Behavior
-- Adapter has no skip/resume logic. Stage/runner controls this.
+Failure results still include output/log/config/exit metadata for diagnostics.
 
-## Failure Behavior
-- Constructor validation fails on invalid binary/timeout/schema/concurrency/URL values.
-- Run fails on missing required paths, missing required credential env var, subprocess errors, invalid polished JSON shape, or invalid report JSON.
-- Failures preserve stdout/stderr paths in returned result metadata.
+## Deterministic Behavior
+- CLI args are built from runner config + request in a fixed order.
+- Generated invocation YAML (`audita.generated.v1`) is emitted when requested.
+- Manifest writes are stage-owned; adapter itself is stateless.
 
-## Tests to Inspect Before Changing
-- `internal/adapters/audita/subprocess_test.go`
-- `internal/adapters/audita/fake_test.go`
-- `internal/stage/polish_test.go`
+## Config Mapping
+Config fields consumed through runner/stage wiring are under `pipeline.audita.*`.
 
-## Architectural Invariants
-- Polished output must be valid JSON with top-level `segments` array.
-- When report is enabled, report output must be valid JSON.
-- If `llm_api_key_env` is configured, credential must be present in environment.
+Maintained example with Audita config:
+- `examples/pipeline.full.annotated.yml`
+- `examples/pipeline.production.yml`