Move documentation for external integrations into the docs/integrations subfolder

docs/integrations/audita.md

@@ -0,0 +1,66 @@
+# Integration: audita
+
+## Purpose
+Define Narratio's adapter contract for transcript polishing via Audita CLI subprocess execution.
+
+## Inputs and Outputs
+Inputs (`audita.PolishRequest`):
+- merged transcript path
+- glossary path
+- output processed 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
+
+Outputs (`audita.PolishResult`):
+- processed transcript path
+- optional report path
+- generated config path
+- stdout/stderr log paths
+- exit code, duration, invoked binary
+- adapter metadata
+
+## Boundaries
+Owns:
+- Deterministic CLI argument construction for `audita process`
+- Environment bridging for API credentials
+- Invocation config emission
+- Output validation for processed transcript and report
+
+Does not own:
+- Upstream/downstream stage orchestration
+- Credential sourcing policy beyond required env-var presence check
+
+## 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`
+
+## External Adapters Used
+- Shared subprocess helper (`internal/adapters/subprocess`) to run CLI and capture logs.
+
+## 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.
+
+## Skip and Resume Behavior
+- Adapter has no skip/resume logic. Stage/runner controls this.
+
+## 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 processed JSON shape, or invalid report JSON.
+- Failures preserve stdout/stderr paths in returned result metadata.
+
+## Tests to Inspect Before Changing
+- `internal/adapters/audita/subprocess_test.go`
+- `internal/adapters/audita/fake_test.go`
+- `internal/stage/polish_test.go`
+
+## Architectural Invariants
+- Processed 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.