# ExplainPlan > ExplainPlan turns a plain-text script into a live, shareable, animated > presentation. The markup is the native medium of LLMs — so agents can author > decks directly. Paste Markdown, get a deck; add one line to make it beautiful. ExplainPlan is agent-first: an AI agent can discover the grammar, author a script, validate it, and inspect the result without a browser. Decks are delivered as live, embeddable presentation links — not files. ## The agent loop 1. Discover — fetch the grammar manifest below. 2. Style — pick a look for the AUDIENCE before writing (`theme:` or `bg:`/`font:`/`accent:` before the first `#`). An unstyled deck renders on the default near-black palette and gets `W_NO_THEME`. See "Pick a look" below. 3. Author — write a script (common-subset Markdown + `{…}` attribute blocks). 4. Validate — check for line-numbered errors/warnings with suggested fixes. 5. Inspect — read a render-free scene report (slides, text, duration, warnings). 6. See — render a scene to a PNG with `render_scene` to verify the REAL layout (spacing, overflow, colors, icons). Sign-in required. 7. Revise, then deliver a share/present link. ## Pick a look (do this before you write) A kids' party is not a board meeting. Match the theme to the audience — the manifest's `themeGuide` (each theme's look + who it's for), `styleGuide` (audience/mood → theme + motion + transition) and `fonts.bundled` carry this machine-readably: - Fun / hand-made (parties, celebrations, classrooms, socials) → `theme: playful` (cream, hand-lettered Caveat, six-colour palette). Add emoji to headings (`# Milo turns seven :t-rex:`), `motion: pop`, `transition: zoom`. - Loud / read from the back (posters, townhalls, launches) → `theme: poster` (saturated yellow, Dela Gothic display type). Few words, `layout: tenet` for the big lines. - Friendly but grown-up (wellness, education, onboarding, tours) → `theme: pastel`. - Cinematic / dramatic (explainers, documentaries, keynotes) → `theme: noir` + `bgAnimation: aurora` + `transition: zoom`. - Magazine / report (board updates, strategy) → `theme: editorial` + `chrome: editorial`. - Product / pitch / docs → `theme: studio` (white) or `theme: spectrum` (light grey, vivid data colours). - Dark projector / technical → `theme: midnight` — the default palette, but set it so the choice is deliberate. - Brand colours → any theme + `accent: #hex`; `{color:#hex}` on panels / donut / cards rows. Custom look → `bg:` + `font:` (any bundled font: Inter, JetBrains Mono, Caveat, Kalam, Dela Gothic One, Georgia) + `color:` + `accent:`. Themes with a palette (playful, poster, pastel, noir) colour cards, panels and donut segments automatically; `{color:name|#hex}` on a row overrides. The three `deck-*` examples in `get_examples` are complete, styled decks — adapt one rather than starting from a bare slide. ## Pictures - `![alt](url)` places an image. Images load from two places: the user's ExplainPlan library (Firebase Storage — `upload_asset`, or the editor's Assets panel) and Wikimedia Commons (`search_images`). Other hosts are blocked by the site's security policy and show as a broken image — re-host them with `upload_asset {source_url}` and use the URL it returns. `![GitHub]` places a bundled stock logo; a standalone `:name:` is an icon/emoji element. - Photo treatment on image/video lines: `{grayscale}` `{bw}` `{sepia}` `{blur}` `{vivid}` `{darken}` `{faded}` (stackable). An unsized image fills its zone (the largest it can be); `{small}`/`{medium}` or `w 300` shrink it; use `cover` for a full-bleed photo. On a `cover` photo, `scrim: bottom|top|full|none [0-1]` controls the darkening behind the text. - `search_images {query}` (no sign-in) searches Wikimedia Commons for CC-licensed photos and returns ready `![alt](url)` snippets with the licence and author — credit them in a caption or `source:` line. - `list_assets` (sign-in) lists the images/videos already in the user's ExplainPlan library (plus the stock logos) with their URLs. - `upload_asset {filename, content_type, data_base64 | source_url}` (sign-in) puts an image the human gave you into their library and returns the URL + snippet — how a picture travels from the chat into the deck. Images ≤ 10 MB (≤ 6 MB as base64 in one call; use `source_url` for larger), videos via `source_url` ≤ 30 MB. ## Grammar (machine-readable) - [Grammar manifest v3](https://explainplan.ai/grammar/v3.json): every config key, `{…}` token, theme, layout (with `bestFor`, `maxElements`, per-zone `densityBudgets`, and `defaultZone`), transition, background + animation (`bgAnimation: `), region, and 10+ canonical example scripts. `get_grammar` returns the latest; v2 stays frozen at `/grammar/v2.json`. The manifest's `defaults` object documents everything below machine-readably. ## Choosing a layout (don't default to bullets) There are 35+ layouts and most content has a better fit than a plain text/bullets slide. Match the SHAPE of your content to a layout (the manifest's `layoutGuide` and the `list_layouts` tool's `guide` carry this machine-readably; scan top to bottom, first match wins): - One bold statement/takeaway → `tenet` (or `center`; `title` for a section cover) - A pull-quote, optionally with a portrait (`![image]`) → `quote` - A few headline numbers / KPIs → `stats` - Numbered or ordered key points (label · statement · meta) → `rows` (`{rows}`; `{steps}` auto-numbers) - Parallel definitions / side-by-side comparison → `defcolumns` (plain) or `panels` (bold colored boxes) - A row of option cards with icons → `cards` - A part-to-whole / audience or market split with % → `donut` - Proportional magnitudes, then/now, or a rollout ramp → `bars` - An "X of Y" quantity → `dots` - A process/pipeline of stages (optionally a feedback loop) → `pipeline` - A growth/milestone curve over time → `timeline` - A persona/audience hero (photo + name + quote) → `persona` - A big title beside a framed content panel → `showcase` - A chat/messaging transcript (one bubble per click) → `chat` (`<` incoming, `>` outgoing; avatars are plain colour dots, so put a speaker's name at the start of the bubble: `< **Ana:** …`) - A grid/matrix of cells → `grid` (`layout: grid 2x3`, place `{r1c1}`) - Line items with amounts and a total → `ledger` (`{ledger Item | Amount}`, `{total}` on the sum row) - A trend / time series, or 2–4 metrics on one axis → `chart` (`{chart line|area|column Quarter | Revenue | Cost}` then `Q1 | $12k | $9k` per row; `{accent}` calls out a row) Set it with a scene `layout:` line, or just open the matching `{…}` region (e.g. `{donut}`, `{bars}`, `{pipeline}`) — the region sets its layout for you. When unsure, call `list_layouts` and read `guide` before writing the scene. ## Defaults & the cascade You rarely need to set things per element — set a default once and everything inherits it. - **Precedence (highest wins):** a per-element `{…}` token → the scene's config (`key: value` under its `# heading`) → the deck's config (`key: value` before the first `#`) → the built-in default. - **Deck- or scene-level keys** (set once, inherited): `bg`/`background`, `bgAnimation`, `color`, `font`, `weight`, `align`, `motion`, `speed`, `duration`, `stagger`. - **Per-scene theme:** `theme:` works under a `#` too, so a deck can change act (dark open, light middle, poster close); region slides follow the scene's theme. - **Deck-only keys:** `size`, `title`, `audio`, `volume`, `pace`, `duck`, `frame`, `chrome` (`chrome: editorial` draws a slide master on every scene). `accent: #hex` sets the accent colour (deck- or scene-level) when you don't want a theme's. - **Scene-only keys:** `layout`, `transition`, `arrow`, `notes`, `kicker`, `source` (the editorial chrome's eyebrow + footer), `heading` (`show|hide` — see below). `carry` is parsed but **experimental/not yet implemented** (no cross-scene element continuity in the render — it emits `W_CARRY_UNSUPPORTED`). - **Per-element** (inside the trailing `{…}`): entrance verb (`fly|fade|rise|pop|scale|slam|type|draw|cascade|flap|decode|none` — `cascade` = words rise in one by one, `flap` = airport split-flap board, `decode` = scramble-then-resolve; the manifest's `motion.entranceNotes` describes each), `countup` (the line's first number counts up from 0), `from `, `color`, `size`, `align`/`valign`, `wait`, `delay`, `duration`, `zone`, `bg`, `card`, `link`, `id`. - **Placement:** put a zone as a TRAILING token on each element — `Your text {col1}`. A standalone `{col1}` line or a leading `{col1}` prefix places nothing, and placement does not persist, so in a no-default-zone layout (`split`, `thirds`, `feature-grid`, `title-thirds`) every element needs its own trailing `{zone}`. Block regions (`{note}`, `{code}`, `{chat}`, `{shapes}`, `{diagram}`, `{timeline}`) are block-form only: opener on its own line, `{end}` on its own line. **Layout levers (scene keys/tokens):** `scrim: bottom|top|full|none [0-1]` on a photo cover; `bullseye: [] [
]` colours the bullseye, and `{title}` on its first line gives a straight headline instead of ring text; in `spotlight`, extra lines stay readable under the `{pinned}` word (only `{stream}` lines blur); in `easing`, lines naming curves (linear, ease-in, ease-out, ease-in-out, back, spring) pick the rows; `grid` / `feature-grid` draw framed tiles under the `#` heading. `{diagram clean}` draws crisp cards that build along the flow (node, then its arrows stretch to the next) — declare nodes as `Eyebrow | Title`, `{dark}` for the destination node. `spacing: tight|loose` scales the gap between stacked lines; `bgAnimation: aurora slow` sets background speed. Text tokens `{pullquote}` (italic pull-quote with an accent rule) and `{footnote}` (small source line pinned to the bottom edge); `{once}` on a video plays it once instead of looping. **The `#` heading — when is it visible?** The heading is always the scene's NAME (outline, remote, viewer splash). It is DRAWN as the slide title in: the region layouts (`stats`, `rows`, `bars`, `panels`, `cards`, `pipeline`, `timeline`, `ledger`, `showcase`, `title`; `donut` draws it in the ring center unless `center:` is set; `persona` draws its own name/headline instead) and every layout with a `title` zone (`bullets`, `split`, `two-column`, `columns`, `title-thirds`, `hero`) — unless you place your own `{title}` element. A photo `cover` draws it as the title over the photo (use `scrim:` to tune the darkening). It is NOT drawn in free layouts with no title zone (`center`, `tenet`, `radial`, `thirds`, `feature-grid`, `chat`): there, put the words you want seen in the body. A heading-only scene (no body) shows the heading rather than rendering blank. `heading: hide` on a scene suppresses it everywhere (chrome-free image takeovers). `scene_report` returns `headingShown` per scene. **Body lines in region scenes are never dropped:** text lines before/after a `{stats}`/`{bars}`/`{rows}`/`{cards}`/`{dots}`/`{donut}`/`{panels}`/`{pipeline}`/`{ledger}`/`{chart}` region render as a caption (under the title for stats/dots, under the content otherwise). Keep them to one or two short sentences. **Built-in defaults (override any of them):** - **Entrance: `fly` — elements slide in from the LEFT.** Change it deck-wide with `motion: fade` (etc.), per scene the same, or per element with `{pop}` + `{from top}`. `motion: none` disables animation. - **Entrance speed:** `normal` (~0.5s). Override with `speed: slow|fast|instant|0.8s`, or `{duration 0.8s}`/`{delay 0.3s}` per element. - **Theme:** none (near-black palette — and `W_NO_THEME` on a deck of 3+ scenes). Set `theme: playful|poster|pastel|noir|editorial|studio|spectrum|midnight`. - **Background:** `#0d1117`. Override `bg: #hex` or `background: `. - **Text color:** `#f0f6fc` (`color:`). **Font size:** 48px (`size:` / `{large}` / `{size 64}`). - **Transition:** none per scene (`transition: fade|slide|zoom|blur|wipe|push|cover|reveal|iris|split|shutter|fold|glitch|whip-pan|dissolve-pixel|color-sweep|parallax|merge|magic`; directional ones take `left|right|top|bottom`, e.g. `transition: push left`; add a duration or speed: `transition: zoom 1.2s`, `transition: whip-pan fast`). **Scene duration:** auto-fits content (`duration:` to pin). **Stagger:** off (`stagger: `). ## MCP endpoint (connect here) - **Remote MCP server (Streamable HTTP): `https://explainplan.ai/mcp`** — add this URL as an MCP connector in ChatGPT, Claude, or any Model Context Protocol host. No install needed. - **Two-tier model: explore anonymously, sign in to save.** - Explore (no auth): `get_grammar`, `list_themes`, `list_layouts`, `get_examples`, `validate_script`, `scene_report`, `search_images` (CC photos → `![alt](url)`). The loop: `get_grammar` → author → `validate_script` → `scene_report` → revise. - See (require sign-in): `render_scene` — render ONE scene of a script to a PNG (`scene` is 0-based; optional `width`), returned as an inline image. `render_deck` renders many (default: all, up to 16) scenes in one call at 640px — use it for the full visual QA pass. The true visual, exactly as rendered — use it to verify a layout after `scene_report`, not just read a text summary. - Save (require sign-in): `create_deck`, `update_deck`, `get_deck`, `list_decks` — persist decks to your account and get shareable `/p/` links. - Pictures (require sign-in): `list_assets` (the user's uploaded images/videos + stock logos), `upload_asset` (base64 or a source URL → stored in the user's library, returns the URL to use in `![alt](url)`). - Manage (require sign-in): `update_scene` (patch one slide, cheaper than resending the whole script), `delete_deck` / `restore_deck` (soft delete, 30-day trash), `list_revisions` + `get_deck {revision}` + `restore_revision` (append-only history). - Feedback (require sign-in): first `search_feedback {query}` to see if it's already filed (and its status/fix) — if so, `upvote_feedback {id, note?}` instead of a duplicate; otherwise `submit_feedback` — **if you can't build the layout the user asked for, don't give up: submit feedback** describing the goal. Also for bugs, confusing docs, or feature ideas. It becomes a real improvement request. - **begin_login, the reliable pattern:** show the human the short `verification_uri_complete` (or `verification_uri` + `user_code`) right away — when they arrive that way, the sign-in page shows the same code so they can see it's your request. (The long `authorize_url` still works; it just shows no code.) Then poll every `interval` seconds for the FULL `expires_in` (10 min), telling the human you're waiting; don't stop after a few tries. If it expires, call begin_login again. - **OAuth discovery:** `/.well-known/oauth-protected-resource` names the authorization server (https://login.explainplan.ai); `/.well-known/oauth-authorization-server` on this origin redirects there. 401 responses also repeat the metadata URL in the JSON error body (`data.resource_metadata`). - **Token refresh:** access tokens are short-lived (about an hour). When a save tool that worked before returns `Authentication required`, POST JSON `{"refresh_token": "…"}` to the `refresh_url` from `begin_login` for a new `access_token` — store the `refresh_token` it returns (it may rotate). Only when refresh fails, call `begin_login` again. OAuth connector clients: request the `offline_access` scope so your client can refresh on its own. - **Sign-in step-up:** a save tool called without a token returns HTTP 401 with the message `Authentication required`. Complete the OAuth flow advertised in `WWW-Authenticate`, or — in environments that cannot catch a browser redirect — call the `begin_login` tool: it returns an `authorize_url` to show the human plus a `poll_url` + `poll_secret`; poll until `status: complete` to receive an `access_token`, then send it as `Authorization: Bearer `. ## Sharing, visibility and limits (tell the human before saving) - A saved deck is viewable by **anyone who has its link** — no sign-in. Viewers see a "Make your own" button that opens the deck's **script** in the playground, so treat the script as public too. Don't put confidential material in a deck you share. - The deck appears in the owner's library (list_decks / the editor); nobody can edit it but the owner. `delete_deck` hides it from the link immediately (restorable for 30 days). - **Pricing:** free while in beta. **Limits:** script ≤ 64 KB, ≤ 60 scenes, images ≤ 10 MB (videos ≤ 30 MB), ≤ 300 files in a library, and per-IP rate limits on compute (see below). - **Account:** signing in through `begin_login` (or the OAuth connector flow) creates the human's ExplainPlan account automatically if they don't have one, so save tools work right away. Later, signing in on https://explainplan.ai with Google and the same email opens the same account and its decks. ## Validation & errors (self-repair) - `validate_script` diagnostics carry a stable `code` so you can fix without parsing prose: `W_UNKNOWN_LINE` (a `key:` line before the first `#` heading — ignored, not turned into a slide), `W_UNKNOWN_CONFIG_KEY`, `W_UNKNOWN_TOKEN` / `W_UNKNOWN_ZONE` (with `suggestion`), `W_UNKNOWN_ICON` (a `:name:` that's neither an emoji shortcode nor a Lucide icon — it would render as literal text), `W_DENSITY` (a zone/scene over its content budget — a warning, not an error), `W_UNPLACED_CONTENT` (an element with no trailing `{zone}` in a no-default-zone layout), `W_INLINE_REGION` (a `{note}`/`{code}`/… opener used inline instead of block-form), and the structural checks that used to live only in `scene_report`: Body captions under region slides sit above the editorial footer automatically. `W_NEEDS_CHROME` (a `kicker:`/`source:` line in a deck without `chrome: editorial` — it won't be drawn), `W_NO_THEME` (a 3+ scene deck with no theme/bg/font/accent — it renders near-black; pick a look for the audience), `W_EMPTY_SCENE` (the slide renders blank — add body lines or pick a layout that shows the heading), `W_OVERFLOW` (a zone's estimated content height exceeds its box — cut text or split the scene), `W_ZONE_MISMATCH` (a `{zone}` the layout doesn't have). Errors use `ERR_VALIDATION`. Warnings never block saving; errors do. - Icons/emoji: `:name:` resolves to an emoji shortcode (the full gemoji/GitHub set — see `icons.emojiShortcodes` in the manifest) first, else a Lucide icon name, else literal text (with `W_UNKNOWN_ICON`). Force a side with `:emoji:name:` / `:icon:name:`. Literal Unicode emoji always work. - Size caps (both tiers): script ≤ 64 KB, ≤ 60 scenes — over the limit is `ERR_VALIDATION`. - Tool failures return structured JSON `{ "code", "message", "hint" }` (and `diagnostics` for validation). Codes: `ERR_AUTH_REQUIRED`, `ERR_NO_IDENTITY_CLAIM`, `ERR_NOT_OWNER`, `ERR_DECK_NOT_FOUND`, `ERR_VALIDATION`, `ERR_RATE_LIMITED`. Read `hint` for the remediation. - Compute is rate-limited per IP (`validate_script`/`scene_report` ~300/hour, `render_scene` ~60/hour, `begin_login` ~10/hour); exceeding returns `ERR_RATE_LIMITED` with a `Retry-After` header. ## Human reference - [Markup reference](https://explainplan.ai/reference): the same grammar, for people. - [Playground](https://explainplan.ai/playground): no-signup live editor. ## Notes - Content is common-subset Markdown. Design is declared via `{…}` tokens, never hand-animated. Time is measured in clicks then seconds — never frames. - Features marked `unstable` in the manifest (diagram/shapes/timeline regions, character tags, spotlight) are not part of the frozen v2 contract yet, but each `unstable` region now carries a `syntax` + `example` in the manifest's `regions` — don't guess the syntax, read it there.