SMD: Story Markdown

Agent-native presentation and storytelling format

SMD is a markdown-based format for writing structured stories, presentations, briefings, and argument-driven documents that are:

• Human-readable: Edit in any text editor
• Git-friendly: Clean diffs, durable source files
• Token-efficient: Designed for LLM and agent consumption
• Renderer-neutral: Web UIs can map semantic guidance into their own templates
• Argument-aware: Claims, evidence, asks, reveals, and takeaways are first-class

Quick Example

---type: story-deckversion: 0.1title: "ContextFit: Token-Native Agent Memory"audience: AI infrastructure founders and engineersrender:
template: investor-briefingaspect: "16:9"---# ContextFit changes how agents remember {#opening}
::scene id=intro role=hook
::layout mode=hero emphasis=title
::motion sequence=claim-then-proof pace=deliberate
:::claim id=contextfit-thesis source=whitepaper#token-native
Agents do not need bigger context windows as much as they need better memory retrieval.
::
:::beat id=old-way role=problem reveal=1
Most retrieval systems translate memory into vector space and lose source-level structure.
::
:::beat id=new-way role=reframe reveal=2
ContextFit stays token-native, making memory indexable, attributable, and agent-friendly.
::
:::takeaway id=opening-takeaway
The real product is not a slide; it is a structured argument graph.
::

CLI Usage

# Parse and inspect
smd parse examples/contextfit.smd
# Validate
smd validate examples/contextfit.smd
smd validate examples/contextfit.smd --strict
# Export for renderers or ContextFit ingest
smd export examples/contextfit.smd --format json

Integration Docs

• UI integration guide
• JSON contract
• Edit operations
• JSON schema

Python API

fromsmdimportparse_file, validatedoc=parse_file("examples/contextfit.smd")
issues=validate(doc, strict=True)
forsceneindoc.scenes:
print(scene.id, scene.title)

Core Idea

SMD separates three concerns:

1. Content: plain narrative, claims, quotes, evidence, examples, and notes
2. Structure: stable IDs, scenes, beats, roles, sources, and takeaways
3. Direction: semantic layout, motion, pacing, emphasis, and audience variants

Content must stand alone. Directives must enhance. Renderers must be replaceable.

See SPEC.md for the draft specification.