# Output conventions

**Authority:** For the formal output contract (layout, manifests, speaker exclusion), see **[docs/contracts/output-contract-v1.md](contracts/output-contract-v1.md)**.

This document remains a short reference. Implementation lives in `src/transcriptx/core/utils/output_standards.py` and `src/transcriptx/core/utils/_path_core.py` (path helpers and naming).

## Directory layout

- **Run root:** Outputs live under `outputs/<slug>/<run_id>/` where `slug` is the human-friendly folder name (from the slug manager) and `run_id` is `YYYYMMDD_HHMMSS_<hash>`. The run root contains module subdirs, `manifest.json`, `run_results.json`, and report projections (`report.json` / `report.md` / `report.txt`) when enabled by the run profile. See [output-contract-v1.md](contracts/output-contract-v1.md) for the full contract.
- **Per-module:** Each analysis module writes under `<run_root>/<module_name>/` unless it uses a versioned namespace (see below).
- **Standard subdirs (per module):** `data/`, `charts/`, `global/`, `speakers/` as created by `create_standard_output_structure()` in `output_standards.py`.

## Versioned namespaces

Modules that need a stable, versioned contract write under `<run_root>/<namespace>/<version>/`. Example: voice artifacts use `voice/v1/` so that future changes can introduce `voice/v2/` without breaking consumers. See `ModuleInfo.output_namespace` and `output_version` in `module_registry.py`.

## Artifact naming

- **Canonical base name:** From `_path_core.get_canonical_base_name(transcript_path)` (used for run dir and file prefixes). See contract for naming rules.
- **Manifest and run summary:** `manifest.json` and `run_results.json` at run root. Built by `manifest_builder.py`; schema validated in tests (see `run_schema.py` and `tests/contracts/test_run_results_and_manifest_contracts.py`).
- **Module data/charts:** Use `create_standard_output_structure()` and the helpers in `output_standards.py` (e.g. `save_global_data`, `save_speaker_data`) so paths stay consistent.
- **LLM list/prose modules:** `llm_summary`, `narrative_summary`, `llm_speaker_summary`, and `llm_action_items` write JSON+Markdown under `<module>/data/global/` (and speakers for per-speaker summaries). See [runtime/llm.md](../runtime/llm.md).
- **Group LLM synthesis:** group runs additionally publish generation-scoped rollups under `{group_run}/.group_llm_synthesis/generations/{id}/` with `ACTIVE.json` / `COMMIT.json` (not under `data/global/`). Explicit manifest entries list those paths; do not rely on directory scans of the dot-directory. See [groups/group_llm_synthesis_contract.md](../groups/group_llm_synthesis_contract.md).
- **Lexical diversity:** `lexical_diversity` writes JSON+CSV under `data/global/` and chart PNGs via `OutputService.save_chart`. See [runtime/lexical_diversity.md](../runtime/lexical_diversity.md).
- **Overview ZIP presentation:** Export builds selection-scoped `index.html` and optional `index.epub` from copied artifacts (not a separate pipeline module). See [runtime/export.md](../runtime/export.md).

## Single canonical path source

New code should use `_path_core` / `_path_resolution` (as appropriate) and `output_standards` only. Do not build output paths manually; use `get_transcript_dir()`, `get_module_output_dir()`, and `create_standard_output_structure()` so there is one canonical way.

## Stability (v0.41+)

- Do not rename output folders or top-level layout without versioning (prefer versioned namespaces for new layouts).
- Do not change `manifest.json` or run results schema without bumping version or documenting migration.