The mental model (start here)

This is the whole picture on one page. Read it once and the rest of the concept docs slot into place. Five ideas, in order:

1. A Scenario is a graph of Scenes.
2. Every Scene is built on one shared Scene source: Markup, Bindings, Logic Blocks.
3. Logic is one rule shape: WHEN something happens, IF/WHILE a condition holds, DO some effects.
4. Every effect changes exactly one of three things: Memory, Content, or Context.
5. The Playthrough log is the single source of truth; Memory, Content, and Context are views rebuilt from it.

Reuse and the friendly authoring Modes sit on top of all of this — never underneath it.

---

1. A Scenario is a graph of Scenes

The Scenario is the whole work — a graph of nodes. The tool is named for it.

Each node is a Scene: the unit you actually build. A Scene is one screen the player is on. Scenes connect to other Scenes, and the connections are how a player moves through the story.

Scene = the unit you build. Scenario = the whole work.

That’s the top-level frame. Everything else is about what lives inside a Scene and how it behaves when someone plays it.

→ Detail: Scenario, Scenes, and the Scene source

---

2. Every Scene is built on the Scene source

Open any Scene all the way down and you find one markup-centric Scene source — the low-level floor every Scene is baked into. Markup is the material; Bindings and Logic are embossed from it — abstractions that rise out of the markup, not co-equal layers you tab between:

Layer	What it is	Plain job
Markup	Markdoc plus a safe, sandboxed HTML subset	content, structure, media
Bindings	the templating layer woven into the markup	dynamic bits that only read state — insert a value like {score}, show/hide a block by a condition
Logic Blocks	reusable WHEN/IF/DO rule packs you place and fill in	the rules that make a Scene do things

The load-bearing rule across these three: Bindings read, Logic writes. A Binding can pull a value in or hide a block, but it can never change anything. Only Logic changes state. That one-way wall is structural — there’s simply no “change something” affordance inside the markup.

The Custom surface is this Scene source, exposed directly. The code-like view of a Scene is the Source view (“Edit as code”) — a view of the same Scene, never “the code”, never “a script”, never an “eject”.

→ Detail: The three Scene source layers

---

3. Modes are abstractions over the same Scene source

You usually don’t author against the raw Scene source. You author through one of five opinionated Modes — Decision, Slides, Quiz, Video, or Custom — which fixes both how you author the Scene and which Scene rendering it uses (a friendlier, curated way to build).

A Mode is a higher-level projection on top of the Scene source. There is nothing underneath a Mode except the same one Scene source. That’s why ejecting a Mode to Custom is lossless: you’re not converting to something else, you’re just looking at the same Scene through the Source view.

A Mode also rides with the Scene rendering it targets — the process that draws and plays the Scene source — so you still make just one choice. “Slides” isn’t a separate document type or format; it’s the same Scene source run through the slides rendering process.

 Decision · Slides · Quiz · Video · Custom ← opinionated Modes (abstractions)
   ┌──────────────────────────────────┐
   │  Markup  ·  Bindings  ·  Logic    │   ← the Scene source (the floor)
   └──────────────────────────────────┘

Friendly Mode on top, the same Scene source underneath. Always.

---

4. Logic is WHEN / IF / DO

Logic is the layer of rules. Every rule has exactly one shape, written as fill-in-the-blank English:

WHEN <trigger> [IF/WHILE <condition>] DO <effects>.

Example: “WHEN you click [Isolate the host], IF [trust is at least 3], DO [add 5 to score] and [go to the Calm ending].”

Triggers — the five “when ___” kinds:

Trigger	Reads as
click	when you click this
arrive	when you arrive (entering the Scene)
leave	when you leave (exiting the Scene, whatever path is taken)
automatic	as soon as <condition> becomes true — badged automatic
gate	if / while <condition> — a gate, not a trigger: it allows or blocks, it never fires

As soon as is a discrete boundary check at the moment an interaction happens — never a live watcher running in the background.

Effects — the DO — are covered next. Operators are the plain-word building blocks for conditions and values: compare (is / is more than / at least…), combine (and / or / not), list (contains / is in / count / is empty), math (add / subtract / multiply / divide / min / max), range (between, inclusive). No iteration, no symbols required.

→ Detail: Logic — triggers, conditions, effects

---

5. Three effect families: Memory · Content · Context

Every effect changes exactly one of three things. These three families are the whole alphabet — there is nothing else an effect can touch.

Family	What it is	The verbs
Memory	facts the run remembers	remember… (set a fact, add to a number, add/remove a list item, flip a flag)
Content	what’s shown right now	show / style… (show or hide a block, mark an element, substitute a value)
Context	where you are in the scenario	go to…

Context means where you are — space/time-neutral. Picking an ending is just a “go to” into a terminal Scene. (Context replaces the older word “Location”; on the author surface we never say Location, Step, or Playhead.)

There is no second axis on top of these three — no “remembered vs shown”, no “saved vs this-moment-only”, no lifespan or read-only labels. Just Memory, Content, Context.

→ Detail: Logic — triggers, conditions, effects

---

6. The Playthrough log is the truth; Memory/Content/Context are views

Here is the one idea that makes undo, replay, and sharing all work.

The Playthrough log — the recorded sequence of what happened — is the single source of truth. Memory (facts), Content (what’s shown), and Context (where you are) are views: live state the engine keeps, but always rebuilds from Memory plus the log.

The bank line: Cynario saves your transactions (the log), not your balance — and totals them up on demand.

That’s the whole reason it all holds together: because the engine stores what happened rather than a snapshot of the screen, you can undo (drop the last transaction and re-total), replay (re-run the log to the same place), and share a run exactly. A recorded random roll replays identically, because the roll is in the log too.

Only Memory is stored. Content and Context are rebuilt every time — not because they’re “read-only” or “momentary”, but because, like a balance, they’re totaled on demand from the log.

→ Detail: The truth model (the bank line)

---

7. Reuse lives in the Workspace Library

When a rule pack or a piece of a Scene is worth reusing, it becomes a definition in the Workspace Library — a panel in the Explorer. Three reusable nouns:

Noun	What it is
Logic Block	a reusable WHEN/IF/DO rule pack
Component	a reusable content + logic bundle
Blueprint	a curated, fill-in-the-form preset (scored-gate, hotspot-triage, decision-table)

Each is authored once as a definition; every placement is a linked instance, never a copy. You fill in its inputs (the blanks), and the actions you can take on it are: Make · Place/Insert · Override · Detach · Push-to-definition · Swap · Find-usages · Rename. (Never “Extract”. Inputs are “inputs / blanks to fill in”, never parameters.)

A visual group is cosmetic — a precedence box. A Library object is real reuse. They are not the same thing.

→ Detail: Reuse and the Workspace Library

---

The picture, all at once

SCENARIO  ── a graph of ──►  SCENES
                                   │
                                   │  each Scene is built on …
                                   ▼
                         THE SUBSTRATE (the floor)
              Markup  ·  Bindings (read)  ·  Logic Blocks (write)
                                   ▲
                       opinionated MODES sit on top (lossless to eject)

LOGIC   =  WHEN <trigger> [IF/WHILE <condition>] DO <effects>
EFFECTS =  change one of:  MEMORY · CONTENT · CONTEXT

TRUTH   =  the PLAYTHROUGH LOG.
           Memory / Content / Context are VIEWS rebuilt from it.
           (Saves transactions, not the balance — totals on demand.)

REUSE   =  Logic Blocks · Components · Blueprints  →  WORKSPACE LIBRARY (in the Explorer)

---

Where to go next

• Scenario, Scenes, and the Scene source — the nesting and the lossless-eject frame
• Logic — triggers, conditions, effects — the WHEN/IF/DO shape, five triggers, three effect families, operators
• The truth model (the bank line) — why undo, replay, and share work
• Reuse and the Workspace Library — definitions, instances, and the library actions
• Glossary — every settled term, one plain line each