Refresh documentation and policies and simplify releases

docs/integrations/transcript-glossary-files.md

@@ -1,98 +1,50 @@
-# Transcript and Glossary File Integration
+# Transcript and Glossary Input Files
 
-## Scope
-
-This document defines the input file contracts for:
-- transcript JSON;
-- glossary YAML.
-
-These files are loaded and validated before processing begins.
+This document owns accepted input formats. Use the [CLI reference](../cli.md) for
+invocation and error exit semantics, [operations](../operations.md) for artifact
+handling, and [output files](output-files.md) for corrected-transcript serialization.
 
 ## Transcript JSON Contract
 
-Audita accepts either top-level shape:
-- JSON array of segments; or
-- JSON object with a `segments` array.
+Accepted top-level shapes are an array of segments or an object containing a
+`segments` array. The array must contain at least one segment. Unknown object
+fields are ignored by the current parser; an input envelope does not require a
+schema/version marker.
 
-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).
+| Segment field | Type and validation |
+| --- | --- |
+| `id` | Optional integer (or null). Supplied IDs must be unique; missing IDs are accepted. |
+| `speaker` | Non-empty string |
+| `start`, `end` | Numeric seconds, finite and non-negative; end must be at least start |
+| `text` | Non-empty string |
+| `categories` | Optional array of non-empty strings |
 
-Additional rules:
-- transcript must contain at least one segment;
-- duplicate segment IDs are rejected when IDs are present.
+Supply explicit start and end times for meaningful timing. The current decoder
+uses zero for missing or null timestamps rather than enforcing their presence.
+String validation checks empty values, not whitespace trimming. Normalization can
+merge segments and reassign IDs, so source IDs need not match output IDs.
 
-Example (`examples/tiny-transcript.json`):
-
-```json
-[
-  {
-    "id": 1,
-    "speaker": "A",
-    "start": 0.0,
-    "end": 1.2,
-    "text": "hello world"
-  }
-]
-```
+The [tiny transcript](../../examples/tiny-transcript.json) is a complete copyable
+input. Invalid JSON, unsupported top-level shapes, empty transcripts, invalid field
+types, duplicate supplied IDs, and the validation failures above are rejected.
 
 ## Glossary YAML Contract
 
-Audita expects top-level `glossary` list entries.
+The top-level object contains a `glossary` list with at least one entry.
 
-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).
+| Entry field | Type and validation |
+| --- | --- |
+| `name` | Non-empty string |
+| `category` | Non-empty string |
+| `summary` | Non-empty string |
+| `aliases` | Optional list of non-empty strings |
+| `plural` | Optional string |
 
-Additional rules:
-- glossary must contain at least one entry.
+The parser checks empty strings without trimming them. Unknown YAML fields are
+ignored by the glossary parser, unlike the stricter
+[configuration-file schema](../config.md#file-schema).
 
-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)
+The [tiny glossary](../../examples/tiny-glossary.yaml) is a complete copyable input.
+Malformed YAML, an empty/missing glossary, invalid shapes, missing required text,
+and empty aliases are rejected. These formats describe input acceptance, not
+additional vocabulary restrictions.