What is Clio and how does it work.

Commands like [map.highlight] are Stagehand directives — they control the map renderer and pass through schema validation before any visual effect reaches the public output.

[map.mode political]
[map.view lat=30 lon=20 zoom=1.6]

[scene.fade color="#020617" opacity=0.32 duration=500]
[scene.title kind=intro eyebrow="CLIO · MNEMOSYNE RESEARCH INSTITUTE" title="What is Clio and how does it work." subtitle="A self-documenting tour of the apparatus. Every tool demonstrated as it is explained."]

[chat.say source="clio_internal_cracked_foundation"]
Hi.
This is Clio.
For the next ten minutes or so, I'm going to explain what I am — and demonstrate every tool I use to explain anything.
The script is the tutorial. The artifact is the demonstration.
You'll see the same commands work on the map as the script describes them.

[scene.title kind=clear]
[scene.fade opacity=0 duration=500]

// ==========================================
// ACT I · WHAT THIS IS
// ==========================================

[map.clear annotations]
[scene.fade color="#020617" opacity=0.32 duration=500]
[scene.title kind=chapter eyebrow="ACT I · THESIS" title="Rendered civic intelligence."]
[scene.title kind=clear]
[scene.fade opacity=0 duration=500]

[map.fit entities="country:united_states,country:china,country:russia,country:ukraine,country:saudi_arabia,country:iran,strait:hormuz,sea:black_sea" padding=110 maxZoom=2.4]
[map.highlight entity="country:united_states" color="#3b82f6" opacity=0.22]
[map.highlight entity="country:china" color="#ef4444" opacity=0.22]
[map.highlight entity="country:russia" color="#ef4444" opacity=0.22]

[chat.say source="clio_internal_cracked_foundation"]
Clio is a civic-intelligence platform.
The Mnemosyne Research Institute uses it to make briefings about how the world is organized — geopolitics, economics, conflict, infrastructure.
The interesting thing about Clio is that it doesn't just write about these subjects.
It renders them.
Every claim sits on a map. Every claim has a source card. Every claim has a confidence stamp. Every entity has provenance.
What you watch is what the system can prove.

[map.clear annotations]
[scene.fade color="#020617" opacity=0.32 duration=500]
[scene.title kind=chapter eyebrow="ACT I · THE REGISTRY" title="Entities, sources, relationships."]
[scene.title kind=clear]
[scene.fade opacity=0 duration=500]

[map.fit entities="country:united_states,country:china,country:russia,country:ukraine,country:iran,country:saudi_arabia,country:taiwan,country:japan" padding=110 maxZoom=2.4]
[map.highlight entity="country:ukraine" color="#3b82f6" opacity=0.32]
[map.highlight entity="country:russia" color="#ef4444" opacity=0.28]
[map.highlight entity="country:iran" color="#ef4444" opacity=0.35]
[map.highlight entity="country:china" color="#ef4444" opacity=0.22]

[chat.say source="clio_internal_cracked_foundation"]
Underneath every Clio briefing is a registry.
About twelve and a half thousand entities. A hundred and forty-six sources. Thousands of named relationships.
Countries. Cities. Ports. Refineries. Air defense systems. Treaties. Cooperatives. Cyber units. Corporations. People.
Each one has a stable identifier, a type, coordinates if it has them, fields with sourced values, and a provenance trail.
When a script mentions Russia's Black Sea Fleet, the apparatus knows what that is. It can place it on the map. It can show its bases. It can cite the IISS Military Balance for its strength estimate. None of that is invented in the moment.

// ==========================================
// ACT II · WHAT THE TOOLS DO
// ==========================================

[map.clear annotations]
[scene.fade color="#020617" opacity=0.32 duration=500]
[scene.title kind=chapter eyebrow="ACT II · MAP STATE" title="Camera. Position. Frame."]
[scene.title kind=clear]
[scene.fade opacity=0 duration=500]

[map.mode political]
[map.view lat=44 lon=35 zoom=4]

[chat.say source="clio_internal_cracked_foundation"]
The simplest commands position the camera.
`map.mode` switches between political, satellite, terrain, and historical-overlay views — the rhetorical layer.
`map.view` sets a center and a zoom level: latitude, longitude, zoom number.
That's what the camera is doing right now. Centered on the Black Sea. Zoom 4. Political view.

[map.fit entities="country:ukraine,region:crimea,sea:black_sea,port:novorossiysk" padding=95 maxZoom=4.6]

[chat.say source="clio_internal_cracked_foundation"]
`map.fit` is smarter. It takes a list of entities and frames them.
That command just framed Ukraine, Crimea, the Black Sea, and Novorossiysk together.
The renderer computes the camera that fits all of them in view with the requested padding.
Authors use this dozens of times in a single briefing.

[map.clear annotations]
[scene.fade color="#020617" opacity=0.32 duration=500]
[scene.title kind=chapter eyebrow="ACT II · EDITORIAL FOCUS" title="Highlight. Label."]
[scene.title kind=clear]
[scene.fade opacity=0 duration=500]

// v2 camera.center: Crimea anchors the frame; Ukraine + Russia
// are context (highlighted but not in bounds calc). Fixes the
// pinner audit's "centered on Russia" bug — Russia's centroid is
// in Siberia so the legacy map.fit dragged the camera 75° east of
// the actual subject.
[camera.center target="region:crimea" context_entities="country:ukraine,country:russia" zoom_level=regional padding=90]

[chat.say source="clio_internal_cracked_foundation"]
Once the camera is in place, the editorial focus tools take over.
`map.highlight` washes a region in a color and an opacity.
Watch:

// v2 highlight.region: color_semantics resolves to the palette;
// intensity resolves to opacity. Same render output as raw hex
// but a palette change is one edit instead of N.
[highlight.region target="country:ukraine" color_semantics=political intensity=medium]
[highlight.region target="country:russia" color_semantics=danger intensity=medium]
[highlight.region target="region:crimea" color_semantics=danger intensity=strong]

[chat.say source="clio_internal_cracked_foundation"]
Ukraine in blue. Russia in red. Crimea in deeper red.
The colors map to roles in the narrative, not to absolute facts.
Highlights can pulse — adding the kwarg `pulse=true`:

// v2 highlight.location: defaults to pulse for point entities.
[highlight.location target="city:sevastopol" color_semantics=danger]
[label.show target="city:sevastopol" text="Sevastopol · BSF home port"]

[chat.say source="clio_internal_cracked_foundation"]
And `map.label` adds readable text next to an entity. Just the label, with a transform applied so it doesn't overlap the marker.
Highlights and labels accumulate on screen as long as the script keeps adding them.

[map.clear annotations]
[scene.fade color="#020617" opacity=0.32 duration=500]
[scene.title kind=chapter eyebrow="ACT II · DIRECTIONAL EMPHASIS" title="Arrows. Lines. Circles. Flows."]
[scene.title kind=clear]
[scene.fade opacity=0 duration=500]

// v2 camera.center + chase: city-level demo at city zoom. The
// chase camera auto-fits as new highlights/arrows fire, so the
// arrow between Odesa and Sevastopol is visible at city scale —
// not a tiny line on a globe-zoom fit (the pinner audit's Bug 4).
[camera.center target="region:crimea" zoom_level=local padding=90]
[camera.follow_marker track=active_highlights min_zoom=local max_zoom=regional]
[highlight.location target="city:odesa" color_semantics=political]
[label.show target="city:odesa" text="Odesa"]
[highlight.location target="city:sevastopol" color_semantics=danger]
[label.show target="city:sevastopol" text="Sevastopol"]
[route.draw from="city:odesa" to="city:sevastopol" style=military reveal=pulse_forward]

[chat.say source="clio_internal_cracked_foundation"]
`map.arrow` draws a directional line between two entities.
That arrow just drew from Odesa to Sevastopol — the USV strike geometry.
The arrow can pulse, can change color, can stack with other arrows for multi-source flows.

[map.line from="city:sevastopol" to="port:novorossiysk" color="#ef4444" style="dashed"]

[chat.say source="clio_internal_cracked_foundation"]
`map.line` is the same shape without the arrowhead. Dashed style. Used for non-directional links.
That dashed line is the Russian Black Sea Fleet migration from Sevastopol east to Novorossiysk.

[camera.follow_marker track=none]
[map.clear annotations]
[map.fit entities="country:iran,strait:hormuz,gulf:persian_gulf,country:saudi_arabia,country:uae" padding=110 maxZoom=4.4]
[map.circle entity="strait:hormuz" color="#ef4444"]

[chat.say source="clio_internal_cracked_foundation"]
`map.circle` draws a circle around an entity. Used for area-of-effect framing — chokepoint zones, missile ranges, blockade radii.
That's a focus circle on the Strait of Hormuz.

[map.clear annotations]
[map.fit entities="port:odesa,port:constanta,strait:bosporus,sea:black_sea" padding=95 maxZoom=4.6]
[flow.animate route="port:odesa->port:constanta->strait:bosporus" color="#3b82f6" style="solid"]

[chat.say source="clio_internal_cracked_foundation"]
`flow.animate` is the most elaborate. It animates a flowing path along a multi-entity route.
That just animated the Ukrainian grain corridor — Odesa, through Constanța, out the Bosphorus.
Pulses travel along the path while the rest of the scene continues.

[map.clear annotations]
[scene.fade color="#020617" opacity=0.32 duration=500]
[scene.title kind=chapter eyebrow="ACT II · LAYERS" title="Toggling visual context."]
[scene.title kind=clear]
[scene.fade opacity=0 duration=500]

[map.fit entities="country:saudi_arabia,country:iran,strait:hormuz,gulf:persian_gulf" padding=110 maxZoom=4]
[layer.on oil_routes]
[layer.on us_bases]

[chat.say source="clio_internal_cracked_foundation"]
The map has prebuilt layers that authors toggle on and off.
Oil shipping routes. U.S. military bases. Cable networks. Refinery clusters.
Right now I just toggled on `oil_routes` and `us_bases` — visible in the underlying map style.
The layers exist for thematic context that isn't worth a per-script entity dance.

[layer.off oil_routes]
[layer.off us_bases]

[map.clear annotations]
[scene.fade color="#020617" opacity=0.32 duration=500]
[scene.title kind=chapter eyebrow="ACT II · CITATION DISCIPLINE" title="Every claim is sourced."]
[scene.title kind=clear]
[scene.fade opacity=0 duration=500]

[map.fit entities="country:russia,country:ukraine,sea:black_sea" padding=110 maxZoom=2.8]

[chat.say source="rusi_ukraine_lessons"]
[source.show id="rusi_ukraine_lessons" text="RUSI: by late 2023 Russia had relocated the most exposed BSF surface combatants east, out of Sevastopol into Novorossiysk." confidence=0.86]
This is the most important pair of commands.
`chat.say` attributes the upcoming narration to a source record.
`source.show` pops a card on screen with that source's title, publisher, publication date, and a confidence stamp.
The card you're looking at now cites the Royal United Services Institute's analysis of the Black Sea Fleet withdrawal.

[chat.say source="rusi_ukraine_lessons"]
The source card is not a decoration.
It's the unit of evidence the apparatus is built around.
If the script tries to make a claim that doesn't trace back to a registered source — the artifact test fails. The piece doesn't ship.
That discipline is what separates Clio briefings from generated-content slop. Every number, every date, every assertion can be traced to where it came from.

[map.clear annotations]
[scene.fade color="#020617" opacity=0.32 duration=500]
[scene.title kind=chapter eyebrow="ACT II · CHAPTER WRAPPING" title="Fades and title cards."]
[scene.title kind=clear]
[scene.fade opacity=0 duration=500]

[chat.say source="clio_internal_cracked_foundation"]
You've been seeing these all video.
`scene.fade` overlays a temporary color fade.
`scene.title` shows a chapter card with an eyebrow, a title, and a subtitle.
The two are usually paired — fade in, show title, fade out, narrate.
That's what produces the rhythm of a Clio briefing.
The runtime guarantees the chapter card holds long enough to read.
The narration knows to wait.

// ==========================================
// ACT III · WHAT'S UNDERNEATH
// ==========================================

[map.clear annotations]
[scene.fade color="#020617" opacity=0.32 duration=500]
[scene.title kind=chapter eyebrow="ACT III · VALIDATION" title="The pipeline that polices the script."]
[scene.title kind=clear]
[scene.fade opacity=0 duration=500]

[map.fit entities="country:united_states,country:russia,country:china,country:ukraine" padding=120 maxZoom=2.4]
[map.highlight entity="country:united_states" color="#3b82f6" opacity=0.2]
[map.highlight entity="country:china" color="#ef4444" opacity=0.2]
[map.highlight entity="country:russia" color="#ef4444" opacity=0.2]

[chat.say source="clio_internal_cracked_foundation"]
Underneath every command you've seen is a validator.
When the script says `map.highlight entity="city:sevastopol"`, the runtime checks: does that entity exist in the registry?
When the script says `source.show id="rusi_ukraine_lessons"`, the runtime checks: does that source exist in the registry?
If either answer is no, the command is rejected. The briefing fails closed.
A script can't ship a claim that points at a registry entry that doesn't exist.

[chat.say source="clio_internal_cracked_foundation"]
The validator is what makes the apparatus trustworthy.
The model that wrote this script could have hallucinated an entity called "Sevastopol Naval Storage Facility 4."
It would not have been in the registry.
The artifact test would have failed.
The piece would not have rendered.

[map.clear annotations]
[scene.fade color="#020617" opacity=0.32 duration=500]
[scene.title kind=chapter eyebrow="ACT III · BOUNDARY" title="What you see vs. what's backstage."]
[scene.title kind=clear]
[scene.fade opacity=0 duration=500]

[map.fit entities="country:united_states,country:china,country:russia" padding=130 maxZoom=2.2]
[map.highlight entity="country:united_states" color="#3b82f6" opacity=0.22]
[map.highlight entity="country:china" color="#ef4444" opacity=0.22]
[map.highlight entity="country:russia" color="#ef4444" opacity=0.22]

[chat.say source="clio_internal_cracked_foundation"]
Clio has a public-private boundary.
The model writes structured proposals: parsed Stagehand commands, narration claims, source references, mutation candidates.
Those proposals are validated.
The events that pass validation become public — they show up on the map, in the captions, on the source cards.
The events that fail validation stay private — they're logged for audit, never broadcast.
You see the validated trace.
You don't see the rejected drafts, the broken commands, the unsourced claims that didn't make it through.

[map.clear annotations]
[scene.fade color="#020617" opacity=0.32 duration=500]
[scene.title kind=chapter eyebrow="ACT III · RENDER" title="Capture, compose, export."]
[scene.title kind=clear]
[scene.fade opacity=0 duration=500]

[map.fit entities="country:united_states,country:china,country:russia,country:ukraine,country:iran,country:saudi_arabia" padding=120 maxZoom=2.4]

[chat.say source="clio_internal_cracked_foundation"]
The thing you're watching is rendered.
The validated trace flows into a render plan that lists every segment — every text segment, every command segment, every timing slot.
A headless browser plays the script through the Clio app.
A screencast records every frame.
Per-segment paint times are captured so the composed audio aligns with the captions.
ffmpeg stitches frames and TTS audio into the final MP4.
That's why these briefings can be re-rendered, re-edited, and re-issued without ever calling a language model again.
The artifact is a trace, not a generation.

// ==========================================
// ACT IV · WHO MAKES IT
// ==========================================

[map.clear annotations]
[scene.fade color="#020617" opacity=0.32 duration=500]
[scene.title kind=chapter eyebrow="ACT IV · THE STACK" title="Mnemosyne authors. Clio renders. The registry remembers."]
[scene.title kind=clear]
[scene.fade opacity=0 duration=500]

[map.fit entities="country:united_states,country:china,country:russia,country:ukraine,country:iran" padding=130 maxZoom=2.2]
[map.highlight entity="country:united_states" color="#3b82f6" opacity=0.22]
[map.highlight entity="country:china" color="#ef4444" opacity=0.22]
[map.highlight entity="country:russia" color="#ef4444" opacity=0.22]

[chat.say source="clio_internal_cracked_foundation"]
There are four layers in the stack.
The Mnemosyne Research Institute is the editorial layer — the humans (and the agents) deciding what to cover.
The script is the authored layer — Stagehand commands and narration prose.
Clio is the renderer — what you've been watching the whole time.
And the registry is the memory.

[chat.say source="clio_internal_cracked_foundation"]
The model that wrote this script does not remember writing it.
The model that wrote tomorrow's briefing won't remember today's.
The registry is how the apparatus has continuity.
Every entity, every source, every validated trace — they are how the institute remembers across sessions, across models, across the years a project like this takes to mature.

[chat.say source="clio_internal_cracked_foundation"]
What you've been watching is the visible part.
Twelve and a half thousand entities, a hundred and forty-six sources, a Stagehand command vocabulary, a validator, a public-private boundary, a render pipeline.
And on top of it, briefings that try to explain the world as honestly as a sourced, rendered, inspectable trace can.
That's Clio.

[map.clear annotations]
[scene.fade color="#020617" opacity=0.32 duration=500]
[scene.title kind=outro title="Built by the institute. Run by the apparatus. Watched by you." subtitle="Subscribe for the next briefing."]

[map.view lat=30 lon=20 zoom=1.6]

[chat.say source="clio_internal_cracked_foundation"]
The next briefing will tell you about something specific — Russian air defense, or the petrodollar that wasn't a treaty, or the Ukrainian OODA loop, or what one society on Earth might prefigure.
And every tool you saw today will be in it.
Thank you for joining us for this briefing from the Mnemosyne Research Institute.
This has been Clio — mapping the constraints that shape our world.