# Documentation Map

This repository separates current operating guidance from immutable acceptance and
empirical history. Start with the README, then use the focused document that matches
the task.

## Current Guidance

| Document | Use it for |
|---|---|
| [`README.md`](../README.md) | Hugging Face-style overview, install, quick starts, model matrix, headline metrics |
| [`config.json`](../config.json) | Machine-readable project, schema, model, and evaluation manifest |
| [`ARCHITECTURE.md`](../ARCHITECTURE.md) | Current layers, modules, data flow, isolation, and evolution rules |
| [`CONFIGURATION.md`](CONFIGURATION.md) | Typed fields, defaults, invariants, CLI JSON, readiness catalogs |
| [`EVALUATION.md`](EVALUATION.md) | Compared configurations, metrics, results, limitations, artifacts |
| [`WORKFLOWS.md`](WORKFLOWS.md) | End-to-end annotation, benchmark, backend, and readiness flows |
| [`TESTING.md`](TESTING.md) | Quality commands, markers, coverage, and focused-test map |
| [`PROJECT_STATUS.md`](PROJECT_STATUS.md) | Accepted operational status and evidence boundary |
| [`W1_T_SEMANTIC_READINESS.md`](W1_T_SEMANTIC_READINESS.md) | Specialized offline semantic-boundary timing workflow |

## Contracts

| Document | Authority |
|---|---|
| [`ALIGNER_ENGINEERING_CONTRACT.md`](ALIGNER_ENGINEERING_CONTRACT.md) | Data columns, first/last semantics, reference-text and timestamp invariants |
| [`MODULAR_ARCHITECTURE_CONTRACT.md`](MODULAR_ARCHITECTURE_CONTRACT.md) | Mandatory layering, dependency direction, reuse, isolation, and coverage |
| [`AGENTS.md`](../AGENTS.md) | Repository execution and acceptance rules for coding agents |
| [`SKILLS.md`](../SKILLS.md) | Reusable implementation and verification patterns |

Contracts change only when the implementation/API changes intentionally. Update the
contract and its focused tests together.

## Decision and Empirical Evidence

| Document/artifact | Authority |
|---|---|
| [`FINAL_ALIGNER_SELECTION.md`](FINAL_ALIGNER_SELECTION.md) | Current operational selection and limitations |
| [`POSTFINAL_THREE_ALIGNER_COMPARISON.md`](POSTFINAL_THREE_ALIGNER_COMPARISON.md) | Symmetric three-backend full-36 comparison |
| `results/final/` | Canonical selection and MFA annotated output |
| `results/postfinal/` | Full-36 MFA extension and three-backend evidence |
| `results/w1t/` | Readiness timing, consensus, review, and receipt artifacts |

Evidence files are preserved as reviewed. Documentation may summarize and link them;
it must not rewrite hashes, source cells, timing, or historical conclusions.

## Historical Reports

| Document | Historical scope |
|---|---|
| [`STAGE_0_REPORT.md`](STAGE_0_REPORT.md) | Research, dependency selection, and original architecture freeze |
| [`STAGE_1_REPORT.md`](STAGE_1_REPORT.md) | Shared framework implementation and closure repairs |
| [`STAGE_2_REPORT.md`](STAGE_2_REPORT.md) | NeMo adapter implementation and original empirical boundary |
| [`STAGE_3_REPORT.md`](STAGE_3_REPORT.md) | MFA adapter and original five-row evidence |
| [`STAGE_4_REPORT.md`](STAGE_4_REPORT.md) | WhisperX adapter and original five-row/full-run evidence |
| [`STAGE_5_FINAL_ACCEPTANCE_REPORT.md`](STAGE_5_FINAL_ACCEPTANCE_REPORT.md) | Original software/architecture acceptance snapshot |
| [`POST_STAGE5_DOCS_LICENSE_REPORT.md`](POST_STAGE5_DOCS_LICENSE_REPORT.md) | Documentation, headers, and licensing audit |

Stage reports are provenance snapshots. Their counts, paths, and selection statements
may be superseded by later evidence. Current instructions live in the documents above.

## Maintenance Rules

When behavior or evidence changes:

1. Update the current focused guide first.
2. Update README/config only for user-facing identity, defaults, models, or headline
   metrics.
3. Add or update a result receipt/evidence artifact before citing a new empirical
   claim.
4. Keep historical reports unchanged unless correcting a factual link or marking a
   superseding record.
5. Validate all local Markdown links and repository paths.
6. Run every documented syntax/help/quality command before finalizing.
7. Update `.agents/plans`, `.agents/work_data`, and `.agents/logs` with decisions and
   observed results.
8. Review `AGENTS.md` and `SKILLS.md` at the end for durable process gaps.

## Terminology

- **Authoritative transcript**: the original `en_transcript` cell.
- **Forced alignment**: locating supplied text in audio; not ASR transcription.
- **Manual gold**: human reference timing/text fields.
- **Pairwise disagreement**: difference between two backend outputs; not accuracy.
- **Structural success**: valid complete word/timing output; not empirical accuracy.
- **Observed runtime**: one run's measured time under its stated hardware/cache state.
- **Current guidance**: maintained operating documentation.
- **Historical report**: preserved stage/acceptance snapshot.