# MeditationML Authoring Contract

The live `get_meditation_authoring_kit` response is authoritative. Use this reference for structure and workflow, not as a substitute for the server's current limits, cue catalog, or safety policy.

MeditationML defines the production structure, not the creative genre. The
spoken experience may use any safe format or blend requested by the user. Keep
that semantic intent in `intent_contract.requested_format_label` and apply the
same structural validation below.

## Required Structure

A complete meditation uses exactly one ordered section of each type:

```xml
<intro>
Opening guidance.
<silence duration="3">Brief settling window after the opening cue.</silence>
</intro>
<main>
The central practice.
</main>
<outro>
Grounding and a gentle close.
<silence duration="10">Final integration window after the spoken close.</silence>
</outro>
```

- Keep all spoken content inside `intro`, `main`, or `outro`.
- Use well-formed XML-compatible markup.
- Use the live exact form
  `<silence duration="N">brief non-spoken description</silence>` for
  intentional pauses. In the current public contract, `N` is a whole integer
  from `1` through `30`, written with double quotes and no extra attributes.
  Confirm the limits from the live kit. The element body must contain a short
  non-spoken description of the listener action, intentional transition, or
  emotional landing; it is removed from narration.
- Do not use self-closing silence tags.
- Keep every silence directly inside one required section. Do not nest tags
  inside it or put listener-facing instructions in its description.
- Add an approved foreground sound effect with the exact self-closing form
  `<audio_cue id="approved_id"/>`. Replace `approved_id` with a `cue_id`
  returned by the live authoring kit, honor its allowed sections and
  `maximum_uses`, keep the whole document within
  `audio_cue_contract.maximum_total_uses`, and never invent an identifier.
  Audio cues are foreground
  bells, bowls, or gongs; they are not continuous background music.
- Stay within the live word, character, duration, and TTS limits.

## Action-Timed Silence Examples

Place silence after the cue, phrase, question, movement instruction, or
narrative beat it serves. If the action begins during narration, subtract only
the cue time that genuinely overlaps it. If the listener must hear the whole
instruction first, encode the full response or execution window after
narration. The detailed timing standard and additional examples are in
[guided-authoring.md](guided-authoring.md#use-silence-as-practice-time).

For a paced breath, cue each phase separately. A brief cue uses part of the
phase:

```xml
Breathe in.
<silence duration="3">Remaining time for the four-second inhale after the brief cue.</silence>
Breathe out.
<silence duration="5">Remaining time for the six-second exhale after the brief cue.</silence>
```

For repeat-after-me content, the spoken phrase stays outside the tag and the
response purpose goes inside it:

```xml
I can meet this moment with steadiness.
<silence duration="5">Response window for repeating the complete affirmation aloud or silently.</silence>
```

For one reflective prompt, give the listener a real response window before the
next instruction:

```xml
What is one choice that would support you tomorrow?
<silence duration="20">Reflection window for one specific and realistic choice.</silence>
```

If a practice genuinely requires more than 30 seconds, use additional
purposeful intervals that each remain within the live maximum. Add a light
spoken check-in between them only when it supports the researched method.
Never use a malformed over-limit tag, and never add identical pauses merely to
reach a total-silence target.

## Background Ambience

Continuous background music and nature sounds are saved as playback metadata,
not MeditationML. First call `list_ambience_options`, then pass one exact
returned `track_id` to `set_content_ambience` for an explicit owned content ID.
Use the same tool with `action: "remove"` to disable ambience. Never convert a
background track into an `<audio_cue>` tag or invent a track ID.

Changing ambience does not edit the script, advance its version, regenerate
narration, require `audio.generate`, or consume audio allowance. `get_content`
returns the current ambience setting.

## Writing Quality

Use [guided-authoring.md](guided-authoring.md) for the full craft standard.
In particular, research the requested method with the host's available tools,
then design an original structure from the evidence and the user's intent.
The live kit supplies research questions, craft principles, production limits,
and safety—not a prescribed modality flow. Write natural spoken language, give
the listener realistic practice time, create purposeful transitions, and match
the ending to the researched method and listening context. Keep research
queries generic, keep citations outside the spoken script, avoid repeatedly
stating private personalization details, and never copy source scripts or make
unsupported medical, therapeutic, or guaranteed-outcome claims.

## Production Gate

New direct creation and `edit_content` both validate the finished complete
document before persistence or production. The public plugin intentionally
exposes no standalone validator because validation is not storage and should
not become a separate drafting round trip. Fix every blocking error returned
by the write.

Changing saved text never changes existing audio in place. An edit that has
prior audio marks that narration as belonging to the previous script version.
Generate replacement audio only after the user explicitly asks for it, using
the stale-audio regeneration action returned by Manai. Drafting or editing text
alone does not imply approval to incur production usage.
