SpecificationsnormativeSheet 13 of 18

guided-narration@0.1

Explain the idea. Point to the passage. Keep the manuscript.

File: *.guided-narration.md
Unit: spoken beat
View: speech and source targets
Codes: MDTO1300–1399

Read agent skill · authoring and editorial guide

A guided explanation, authored as prose

Chapters organize the argument. Paragraphs say what to speak. A copied quote or existing anchor says where to look. The source can be Markdown or a webpage.

Fig. 1An authored guide and its manuscript review

article.guided-narration.md

---
markdownto: [email protected]
title: A guided explanation
source: https://example.com/article
---

## The idea

The workspace can outlive this machine. [target-quote:: Identity survives execution.]

## The architecture

Notice how storage is separate. [target:: #architecture] [align:: start]

Manuscript review · targets not yet resolved

A guided explanation

Source: https://example.com/article

Source article

Source issues

Open or paste the article that this narration refers to. Website addresses are not fetched automatically.

Source format Open source file

Or paste source

Review manuscript and targets

The idea

The workspace can outlive this machine.
Show: Identity survives execution.
Align: center

The architecture

Notice how storage is separate.
Show: #architecture
Align: start

An agent learns the format once

source:: The Markdown file or HTTPS page this narration accompanies.
## Chapter: A chapter label; it is not automatically spoken.
[target-quote:: …]: A copied passage identifies where the reader should look.
[target:: #anchor]: An existing source anchor identifies a figure or passage.

Read mdto spec guided-narration, write the manuscript, validate it, and resolve it against an explicit source capture. The playback manifest is derived; the Markdown remains canonical.

Resolve attention without guessing

Verb

Meaning

Source edit

resolve

Checks every target against a supplied capture and emits a playable manifest only when all targets resolve uniquely.

None.

The offline review renderer shows the manuscript and its directions. Synchronized playback belongs to a player adapter receiving the resolved capture; this view does not fetch the source or generate audio.

A missing target stays visible

broken.guided-narration.md

---
markdownto: [email protected]
source: ./article.md
---

Unanchored speech.

[target:: #intro]

Both references. [target:: #intro] [target-quote:: text]

mdto validate

MDTO1303 error line 6
Unanchored speech.
Supply exactly one target or target-quote field.
MDTO1302 error line 8
[target:: #intro]
A spoken beat needs 1 to 1200 characters.
MDTO1303 error line 10
Both references. [target:: #intro] [target-quote:: text]
Supply exactly one target or target-quote field.