QEDScene
The atomic unit of story - one continuous stretch of narrative in a single Markdown file.
Scene
A scene is one continuous stretch of story - a conversation, a confrontation, a quiet moment - written
in a single .md file. It is the smallest unit the engine reads, and the anchor every thread,
presence record, and coherence finding hangs off.
How a scene gets written
What goes in a scene
A scene file has two parts: a frontmatter header with declared metadata, and a body written in the NVS Fountain dialect.
---
scene_id: harbour-s1
title: The Short Ledger
chapter: act-i
characters_present: [mara, delacroix]
---
The harbour office was already dark when Mara arrived.
MARA
You knew the shipment was short before it left.
DELACROIX (THINKING)
She's been counting this whole time.Frontmatter fields
| Field | Required | Description |
|---|---|---|
scene_id | yes | Stable unique identifier - never changes even if the file is renamed or moved |
title | yes | Human-readable scene title |
chapter | yes | The chapter or act this scene belongs to |
characters_present | no | Character IDs who appear in this scene |
The scene_id is the anchor everything else references. Set it once and leave it alone.
Where scenes live
content/
story/
001-act-i/
s001-harbour-office.md
s002-the-accountant.md
002-act-ii/
s001-the-trial.mdDirectories and files are sorted by their leading number (001-, s001-). Use zero-padded prefixes
so alphabetical order matches story order. The engine reads by content, not path - rename files and
folders freely without breaking analysis.
How the engine reads a scene
When you save, the engine parses the scene body into a sequence of beats, then:
- Records which characters spoke (presence)
- Advances or resolves threads referenced in the dialogue
- Checks declared character facts against what the scene shows (coherence)
- Logs any new information the reader learns (reveals)
This happens automatically. You write; the ledgers update.