Improved organization of the documentation

docs/architecture/output-schemas.md

@@ -0,0 +1,88 @@
+# Audita Output Schemas
+
+This document describes the built-in transcript output schema registry used by `audita process`.
+
+## Supported schema names
+
+### `bare-segments`
+
+Status:
+- implemented
+- default output schema
+
+Shape:
+- top-level JSON array of transcript segments
+
+Segment fields:
+- `id`
+- `speaker`
+- `start`
+- `end`
+- `text`
+- optional `categories`
+
+Compatibility:
+- this preserves the long-standing output shape used by existing consumers.
+
+### `audita-v1`
+
+Status:
+- implemented
+
+Shape:
+- top-level JSON object:
+  - `schema`: `"audita-v1"`
+  - `version`: `"v1"`
+  - `segments`: transcript segment array
+
+Segment fields inside `segments` match `bare-segments` segment fields.
+
+Compatibility:
+- this is the Audita-native object format with explicit schema/version metadata.
+
+### `seriatim-intermediate`
+
+Status:
+- deferred / not implemented
+
+Current behavior:
+- selecting `seriatim-intermediate` fails clearly as an unsupported output schema.
+
+Reason:
+- a concrete, repository-backed contract for this schema has not been finalized yet.
+
+## Selection
+
+Choose output schema with CLI:
+
+```sh
+audita process <transcript.json> --glossary <glossary.yaml> --output-schema audita-v1
+```
+
+Or in file config:
+
+```yaml
+version: 1
+output:
+  schema: audita-v1
+```
+
+Precedence remains:
+1. defaults
+2. file config
+3. environment overrides
+4. CLI overrides
+
+`--output-schema` overrides `output.schema` when both are supplied.
+
+## Output routing behavior
+
+- With `--output`, transcript JSON is written to file using the selected schema and stdout stays empty on success.
+- Without `--output`, stdout contains transcript JSON only, using the selected schema.
+- `--report-json` writes report JSON to file and does not write report payloads to stdout.
+
+## Backward-compatibility expectations
+
+- default schema stays `bare-segments` for compatibility unless explicitly changed in a future breaking release;
+- supported schema names are treated as stable public contract values;
+- unsupported schema names fail before output write.