# Donna integration contract

Donna remains responsible for collecting organizational information, deciding
priority, selecting a character, and writing the final canonical script. Local
Voice is an optional audio dependency responsible for rendering and validating
that script.

## Invocation

Donna supplies:

- voice profile ID;
- canonical Markdown or Ryan-labelled dialogue;
- absolute output path;
- pronunciation overrides when needed;
- optional delivery, role, signature-asset, and pause metadata.

Donna then asks Local Voice to:

1. run `doctor` if runtime health is unknown;
2. build or validate the render plan;
3. render with `--resume`;
4. return the final audio and QA-report paths.

## Required behavior

- Do not send Markdown headings, numbered section titles, speaker labels, or
  stage directions as spoken text.
- Keep greetings and closings as short standalone paragraphs so Local Voice can
  preserve native tempo.
- Keep substantive paragraphs to complete sentence groups of roughly 20–42
  words unless a profile specifies otherwise.
- Use canonical `text` for the written brief and `tts_text` only for local
  pronunciation corrections.
- Do not silently fall back to ElevenLabs. If Local Voice fails, Donna should
  report the failure and apply the caller's configured fallback policy.
- Attach or link the final audio alongside the full written organizational
  brief; the audio is a quick summary, not the sole record.

## Character mapping

| Donna character | Local Voice profile |
|---|---|
| Production Donna | `donna` |
| Chris Engineer | `chris-engineer` |
| Grandpa Bomber | `grandpa-bomber` |
| Pitch Meeting | `ryan-pitch-meeting` |
| Val Holiday | `val-holiday` |

## Example handoff

```json
{
  "voice": "val-holiday",
  "script": "/absolute/path/val-brief.md",
  "output": "/absolute/path/val-brief.mp3",
  "fallback": "report-and-return-text"
}
```

Local Voice returns the final audio path, QA report path, duration, and
segment-level completeness and cadence results.