Add integration documentation for subprocess, LLM, and input files

docs/integrations/transcript-glossary-files.md

@@ -0,0 +1,98 @@
+# Transcript and Glossary File Integration
+
+## Scope
+
+This document defines the input file contracts for:
+- transcript JSON;
+- glossary YAML.
+
+These files are loaded and validated before processing begins.
+
+## Transcript JSON Contract
+
+Audita accepts either top-level shape:
+- JSON array of segments; or
+- JSON object with a `segments` array.
+
+Segment fields:
+- `id` (optional integer in source form);
+- `speaker` (required non-empty string);
+- `start` (required finite non-negative number);
+- `end` (required finite non-negative number, `>= start`);
+- `text` (required non-empty string);
+- `categories` (optional string array; entries must be non-empty).
+
+Additional rules:
+- transcript must contain at least one segment;
+- duplicate segment IDs are rejected when IDs are present.
+
+Example (`examples/tiny-transcript.json`):
+
+```json
+[
+  {
+    "id": 1,
+    "speaker": "A",
+    "start": 0.0,
+    "end": 1.2,
+    "text": "hello world"
+  }
+]
+```
+
+## Glossary YAML Contract
+
+Audita expects top-level `glossary` list entries.
+
+Entry fields:
+- `name` (required non-empty string);
+- `category` (required non-empty string);
+- `summary` (required non-empty string);
+- `aliases` (optional list of strings; entries must be non-empty);
+- `plural` (optional string).
+
+Additional rules:
+- glossary must contain at least one entry.
+
+Example (`examples/tiny-glossary.yaml`):
+
+```yaml
+glossary:
+  - name: Audita
+    aliases:
+      - audita
+    category: product
+    summary: The Audita transcript correction CLI.
+```
+
+## Validation Failure Behavior
+
+Representative transcript validation failures:
+- invalid JSON;
+- unsupported top-level shape;
+- empty `speaker` or `text`;
+- invalid times (`NaN`, `Inf`, negative, or `end < start`);
+- duplicate IDs;
+- empty transcript array.
+
+Representative glossary validation failures:
+- invalid YAML;
+- empty or missing glossary entries;
+- missing required entry fields;
+- empty alias values.
+
+These failures surface as schema errors and the process exits nonzero.
+
+## CLI Usage
+
+Minimal invocation:
+
+```sh
+audita process ./transcript.json --glossary ./glossary.yaml --output ./corrected.json
+```
+
+See also:
+- [`docs/cli.md`](../cli.md)
+- [`docs/config.md`](../config.md)
+- [`examples/tiny-transcript.json`](../../examples/tiny-transcript.json)
+- [`examples/tiny-glossary.yaml`](../../examples/tiny-glossary.yaml)