diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3b5ea3a..11d834f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,4 +12,9 @@ All notable changes to this project are documented here. The format follows
 - Five layouts: `title`, `bullets`, `split`, `steps` and `table`.
 - Built-in `midnight` and `paper` themes. Custom themes are CSS files that set akceo's tokens.
 - PNG, JPEG and WebP images are shrunk and embedded; SVG is embedded as-is.
-- Build errors name the file, line and slide.
+- Deck errors name the file, line and slide; theme and image errors name the file.
+- `akceo viewer` writes `md-viewer.html`, a speaker-notes viewer for a second browser tab. In
+  Chrome and Edge it refreshes live when the notes file changes.
+- Example speaker notes for the demo deck.
+- Docs: the speaker-notes setup, and how Akceo works (plain terms, user experience, internals),
+  with Mermaid diagrams.
diff --git a/CLAUDE.md b/CLAUDE.md
index b74b366..7acacd8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -12,10 +12,14 @@ runtime dependency.
 - `src/akceo/files.py`: reads user-supplied text files, turning read failures into `DeckError`.
 - `src/akceo/cli.py`: the `akceo` command.
 - `src/akceo/assets/`: the page template, `base.css` (layout rules; all colors and fonts come from
-  theme tokens), and `deck.js` (navigation).
+  theme tokens), `deck.js` (navigation), and `md-viewer.html` (the standalone speaker-notes
+  viewer that `akceo viewer` writes out).
 - `src/akceo/themes/`: built-in themes, one CSS file each. The first-line comment is the
   description `akceo themes` prints.
-- `examples/demo/`: a deck that uses every layout. The end-to-end test builds it.
+- `examples/demo/`: a deck that uses every layout, and its speaker notes. The end-to-end test
+  builds the deck.
+- `docs/`: `syntax.md` (format reference), `speaker-notes.md` (notes setup), `how-it-works.md`
+  (design, with Mermaid diagrams), `branding.md`.
 
 ## Commands
 
@@ -33,4 +37,7 @@ uv run akceo build examples/demo/deck.md
 - `docs/syntax.md` is the format reference. Update it in the same change as any parser, renderer
   or token change.
 - A new theme token goes in `themes.TOKENS`, every built-in theme, and `docs/syntax.md`.
+- `docs/how-it-works.md` describes the modules and pipeline. Update it when either changes.
+- Keep JavaScript escapes such as `\u0000` as text in the assets. A raw control character breaks
+  the page, and a test checks for it.
 - Keep the `Unreleased` section of `CHANGELOG.md` current.
diff --git a/README.md b/README.md
index fcea46c..b1eef01 100644
--- a/README.md
+++ b/README.md
@@ -98,6 +98,26 @@ that sets akceo's color and font tokens. The simplest start is a copy of
 [`src/akceo/themes/midnight.css`](src/akceo/themes/midnight.css). The token list is in
 [docs/syntax.md](docs/syntax.md#themes).
 
+## Speaker notes
+
+Keep your notes in a Markdown file and read them in a second browser tab, while you share only
+the deck tab in your call.
+
+```sh
+akceo viewer    # writes md-viewer.html into the current folder
+```
+
+Open `md-viewer.html` next to your deck, for example with Chrome's split view, and open your
+notes file in it. In Chrome and Edge it refreshes by itself when you save the notes.
+`examples/demo/speaker-notes.md` goes with the demo deck. The setup is in
+[docs/speaker-notes.md](docs/speaker-notes.md).
+
+## How it works
+
+[docs/how-it-works.md](docs/how-it-works.md) explains Akceo at three levels: in plain terms,
+from the user's side, and under the hood. It has diagrams of the build pipeline, the data model
+and the notes viewer.
+
 ## Development
 
 ```sh
diff --git a/docs/how-it-works.md b/docs/how-it-works.md
new file mode 100644
index 0000000..91fceff
--- /dev/null
+++ b/docs/how-it-works.md
@@ -0,0 +1,393 @@
+# How Akceo works
+
+This document explains Akceo at three levels. Read as far as you need.
+
+1. [In plain terms](#in-plain-terms): what Akceo is and why you might use it.
+2. [The user's experience](#the-users-experience): what it's like to write, build and present a
+   deck.
+3. [Under the hood](#under-the-hood): how the code turns Markdown into a deck.
+
+The exact file format is in [syntax.md](syntax.md), and the notes setup is in
+[speaker-notes.md](speaker-notes.md).
+
+---
+
+## In plain terms
+
+Akceo turns a text outline into a slide deck.
+
+You write your slides as plain text, with a few simple marks for headings, lists and emphasis.
+Akceo reads that text and produces one file that is the whole presentation. Double-click the
+file and it opens in a web browser, ready to present.
+
+```mermaid
+flowchart LR
+    outline["Your outline<br/>(a text file)"] --> akceo(["Akceo"])
+    look["A look<br/>(a theme)"] --> akceo
+    pictures["Your pictures"] --> akceo
+    akceo --> deck["One presentation file<br/>(opens in any browser)"]
+```
+
+**Why work this way?**
+
+- **You write, Akceo designs.** There are no boxes to drag or fonts to match. Every slide
+  follows the same layout rules, so the deck looks consistent without effort.
+- **One file, no surprises.** Pictures are packed inside the file. It works offline and on any
+  computer, and nothing goes missing when you email it.
+- **Change the look in one step.** The same outline can be rebuilt in a dark or light theme, or
+  in your own brand colors.
+- **Text is easy to keep.** A plain-text deck can be versioned, compared, reused and reviewed
+  like any other document.
+- **Private notes.** Your speaker notes open in a separate tab that the audience never sees.
+
+**Who it's for:** people who present often and would rather write than lay out slides. Think
+engineers, founders, and anyone giving a design review or a pitch.
+
+**What it isn't:** a drawing tool. Akceo has five fixed layouts, and that restraint is the point.
+If a slide needs free-form design, make that one image in another tool and drop it into a
+`split` slide.
+
+---
+
+## The user's experience
+
+### The whole journey
+
+```mermaid
+journey
+    title Making and giving a talk with Akceo
+    section Write
+      Outline slides in deck.md: 5: Presenter
+      Add images and pick a theme: 4: Presenter
+      Write speaker notes: 4: Presenter
+    section Build
+      Run akceo build: 5: Presenter
+      Fix any error it names: 3: Presenter
+    section Rehearse
+      Open deck.html and click through: 5: Presenter
+      Edit, rebuild, refresh: 4: Presenter
+    section Present
+      Open notes beside the deck: 4: Presenter
+      Share the deck tab in the call: 5: Presenter, Audience
+```
+
+### Writing
+
+A deck is one Markdown file. A short config block at the top sets the title and theme. Then each
+slide follows a `---` line, and a few header lines choose its layout:
+
+```markdown
+title: Q3 Review
+theme: midnight
+
+---
+
+layout: title
+kicker: Q3 review
+
+# Shipping faster
+
+---
+
+kicker: The problem
+
+## Builds take too long
+
+- **Full rebuilds** on every change.
+- CI queues back up at ==peak hours==.
+```
+
+There are five layouts: `title`, `bullets`, `split` (image beside text), `steps` and `table`.
+The inline marks are small: bold, a strong color, an accent color, dimmed asides and code.
+
+### Building
+
+```sh
+akceo build deck.md
+```
+
+It prints the output file, its size and the slide count:
+
+```text
+wrote deck.html (12 KB, 7 slides)
+```
+
+If something is wrong, the build stops and says exactly where, instead of producing a broken
+deck:
+
+```text
+akceo: deck.md:14: slide 3: the steps layout needs a 1. list
+```
+
+The message gives the file, the line, the slide number and what to change. Typos in keys, a key
+on the wrong layout, a missing image and content a layout can't show are all caught this way.
+
+### The edit loop
+
+```mermaid
+flowchart LR
+    edit["Edit deck.md"] --> build["akceo build deck.md"]
+    build -->|"error at file:line"| edit
+    build -->|"wrote deck.html"| refresh["Refresh the browser tab"]
+    refresh --> edit
+```
+
+### Presenting
+
+Open `deck.html` in a browser.
+
+| Action | Keys |
+| --- | --- |
+| Next slide | `→`, `Space`, `PageDown`, or click the right half |
+| Previous slide | `←`, `PageUp`, or click the left half |
+| First or last slide | `Home`, `End` |
+| Full screen | `F` |
+
+A thin progress bar runs along the bottom, with a slide counter in the corner. Selecting text
+doesn't change slides, so you can copy from a slide mid-talk.
+
+### Presenting with private notes
+
+Your notes live in a Markdown file. You read them in `md-viewer.html`, a small page that
+`akceo viewer` writes out. Put the deck and the viewer side by side in one Chrome window, and
+share only the deck tab in your call. When you save the notes file, the viewer updates by itself.
+[speaker-notes.md](speaker-notes.md) walks through the setup.
+
+```mermaid
+sequenceDiagram
+    actor P as Presenter
+    participant D as Deck tab
+    participant V as Viewer tab
+    participant M as Meet or Zoom
+    actor A as Audience
+    P->>D: open deck.html
+    P->>V: open md-viewer.html, then the notes file
+    P->>M: share the deck tab only
+    M->>A: the slides, nothing else
+    loop during the talk
+        P->>D: arrow keys
+        P->>V: glance at notes, scroll
+    end
+```
+
+---
+
+## Under the hood
+
+### Design goals
+
+- **Self-contained output.** The built page references no external file or URL. CSS,
+  JavaScript and images are all inside it.
+- **One runtime dependency.** Pillow, for shrinking images. Everything else is the Python
+  standard library, and the page uses plain JavaScript with no framework.
+- **Fail loudly and precisely.** Input is checked before anything is written. Every error names
+  the file it's about, and errors in the deck also give the line and slide.
+- **Content and look are separate.** The deck says what's on each slide; the theme alone decides
+  colors and fonts.
+
+### Modules
+
+```mermaid
+flowchart TD
+    cli["cli.py<br/>akceo build / themes / viewer"] --> render["render.py<br/>build()"]
+    render --> parse["parse.py<br/>load(), validation"]
+    parse --> files["files.py<br/>read_text()"]
+    render --> themes["themes.py<br/>load(), token check"]
+    themes --> files
+    render --> images["images.py<br/>data_uri()"]
+    render --> assets[["assets/<br/>page.html · base.css · deck.js"]]
+    themes --> builtin[["themes/<br/>midnight.css · paper.css"]]
+    cli --> viewer[["assets/md-viewer.html"]]
+    parse -.->|raises| err["errors.py<br/>DeckError"]
+    themes -.->|raises| err
+    images -.->|raises| err
+    files -.->|raises| err
+```
+
+| Module | Job |
+| --- | --- |
+| `cli.py` | Parses arguments, runs a command, writes the output, turns `DeckError` into a message and exit code 1 |
+| `render.py` | Runs the build: loads the deck and theme, embeds images, renders each slide, fills the page template |
+| `parse.py` | Turns Markdown into a validated `Deck`. All input rules live here. |
+| `themes.py` | Finds a theme by name or path and checks that it sets every token |
+| `images.py` | Turns an image file into a `data:` URI, shrinking raster images |
+| `files.py` | Reads user files, turning read and decode failures into `DeckError` |
+| `errors.py` | `DeckError`, the one exception type the CLI reports to the user |
+
+### The build pipeline
+
+```mermaid
+sequenceDiagram
+    participant CLI as cli.py
+    participant R as render.build
+    participant P as parse.load
+    participant T as themes.load
+    participant I as images.data_uri
+    CLI->>R: deck path, optional --theme
+    R->>P: read and parse deck.md
+    P-->>R: Deck (config + slides)
+    R->>T: theme from --theme, else the deck's theme:, else midnight
+    T-->>R: theme CSS
+    loop each split slide
+        R->>I: image path, image-max
+        I-->>R: data URI
+    end
+    R->>R: render slides, fill page.html
+    R-->>CLI: HTML, slide count
+    CLI->>CLI: write deck.html, print summary
+```
+
+### Parsing
+
+Parsing runs in stages, each working on the output of the one before:
+
+```mermaid
+flowchart LR
+    text["deck.md text"] --> chunks["Split on --- lines<br/>(keeps line numbers)"]
+    chunks --> config["First chunk:<br/>config block"]
+    chunks --> slides["Each other chunk:<br/>a slide"]
+    slides --> header["Header lines<br/>key: value"]
+    slides --> body["Body lines"]
+    body --> logical["Join continuations<br/>(2-space indent, trailing \)"]
+    logical --> blocks["Group into blocks<br/>h1 h2 phase ul ol lead table note para"]
+    header --> check{"Validate against<br/>the layout's contract"}
+    blocks --> check
+    check -->|ok| slide["Slide"]
+    check -->|fail| error["DeckError<br/>file:line: slide N: …"]
+```
+
+Each layout has a contract, set in data at the top of `parse.py`:
+
+- the header keys it accepts (`LAYOUT_KEYS`)
+- the blocks it renders, and whether each may repeat (`LAYOUT_BLOCKS`)
+- what it requires (`REQUIRED_KEYS`, `REQUIRED_BLOCKS`)
+
+Anything outside the contract is an error rather than something silently dropped.
+
+The parsed result is a small, immutable data model:
+
+```mermaid
+classDiagram
+    class Deck {
+        path: Path
+        config: dict
+        slides: tuple~Slide~
+        title()
+        error(slide, message)
+    }
+    class Slide {
+        number: int
+        line: int
+        meta: dict
+        blocks: tuple~Block~
+        layout()
+        first(kind)
+        flag(key)
+    }
+    class Block {
+        kind: str
+        text: str
+        body: str
+        items: tuple
+        rows: tuple
+    }
+    Deck "1" --> "many" Slide
+    Slide "1" --> "many" Block
+```
+
+### Rendering
+
+`render_slide` writes one `<section class="slide">` per slide, choosing markup by layout. Inline
+text goes through `inline()` in a fixed order. This order is why markup inside backticks stays
+literal and why raw HTML is always escaped:
+
+1. Set aside `` `code` `` spans, so nothing else touches them.
+2. Escape HTML (`&`, `<`, `>`).
+3. Apply `***strong***`, `**bold**`, `==accent==` and `((dim))`.
+4. Put the code spans back, escaped.
+5. Turn hard line breaks into `<br>`.
+
+The page comes from `assets/page.html`, which has four placeholders filled in one pass: title,
+styles, slides and script. Filling them in one pass means slide text that happens to contain a
+placeholder name is never replaced.
+
+### Themes
+
+```mermaid
+flowchart LR
+    base["base.css<br/>layout rules,<br/>colors via var(--token)"] --> pagestyle["The page's style block"]
+    theme["theme CSS<br/>sets --bg, --accent, …<br/>may override rules"] --> pagestyle
+    pagestyle --> page["deck.html"]
+```
+
+`base.css` holds only layout. Every color and font in it comes from a CSS custom property, such
+as `var(--accent)`. A theme is a CSS file that sets those properties. It's added after
+`base.css`, so it can also override any layout rule. `themes.load` rejects a theme that leaves
+out a token, or that contains `</style`, which would end the style block early. The token list
+is in [syntax.md](syntax.md#themes).
+
+### Images
+
+```mermaid
+flowchart TD
+    start["image: file on a split slide"] --> exists{"File exists?"}
+    exists -->|no| e1["DeckError: image not found"]
+    exists -->|yes| svg{"SVG?"}
+    svg -->|yes| raw["Embed the bytes unchanged"]
+    svg -->|no| fmt{"PNG, JPEG or WebP?"}
+    fmt -->|no| e2["DeckError: unsupported format"]
+    fmt -->|yes| fix["Rotate upright from EXIF,<br/>shrink to image-max,<br/>never enlarge"]
+    fix --> save["Re-save in the same format<br/>(JPEG and WebP at quality 90)"]
+    raw --> uri["base64 data: URI in the img src"]
+    save --> uri
+```
+
+Images are processed on every build, so replacing an image file and rebuilding just works.
+
+### Errors
+
+Every problem the user can fix is a `DeckError`, with a message in one of these forms:
+
+```text
+deck.md:14: slide 3: the steps layout needs a 1. list
+deck.md:2: unknown config key 'diagrams' (expected one of: title, theme, images)
+theme brand.css doesn't set: --figure-bg
+```
+
+`cli.main` catches `DeckError`, prints `akceo: <message>` to stderr and exits with code 1.
+Anything else is a bug in Akceo, and it shows a normal Python traceback.
+
+### The page at runtime
+
+`deck.js` is small. It shows one slide at a time by toggling an `active` class,
+moves the progress bar and counter, and maps keys and clicks to next and previous. A click is
+ignored while text is selected.
+
+### The notes viewer
+
+`md-viewer.html` is a separate, self-contained page with its own small Markdown renderer. Live
+refresh uses Chrome's File System Access API. That API is available to pages opened from disk,
+so no server is needed.
+
+```mermaid
+sequenceDiagram
+    actor P as Presenter
+    participant V as md-viewer.html
+    participant C as Chrome file access
+    participant F as speaker-notes.md
+    P->>V: click Open .md (or drop the file)
+    V->>C: showOpenFilePicker()
+    C-->>V: file handle
+    V->>F: read, render, show "● watching"
+    loop every 1.5 seconds
+        V->>C: handle.getFile()
+        C-->>V: file with lastModified
+        alt lastModified changed
+            V->>F: read and re-render, keep scroll position
+        end
+    end
+    Note over V,F: If the read fails, show "file unavailable · open it again"
+```
+
+In browsers without that API, the viewer still opens files, but you drop the file again to
+refresh.
diff --git a/docs/speaker-notes.md b/docs/speaker-notes.md
new file mode 100644
index 0000000..d022f25
--- /dev/null
+++ b/docs/speaker-notes.md
@@ -0,0 +1,108 @@
+# Speaker notes
+
+An Akceo deck has no built-in presenter view. You keep your notes in a Markdown file and read
+them in a second browser tab with `md-viewer.html`. In a video call you share only the deck tab,
+so your notes stay private.
+
+```mermaid
+flowchart LR
+    subgraph window["Your Chrome window, in split view"]
+        deck["Tab 1: deck.html<br/>the slides"]
+        notes["Tab 2: md-viewer.html<br/>showing speaker-notes.md"]
+    end
+    deck -->|"shared tab"| meeting["Google Meet or Zoom"]
+    meeting --> audience["Audience sees<br/>only the slides"]
+    file[("speaker-notes.md<br/>on disk")] -.->|"refreshes when you save"| notes
+```
+
+## Set it up
+
+1. **Write your notes** in a Markdown file next to your deck, for example `speaker-notes.md`.
+   The [notes format](#notes-format) below has a suggested layout.
+2. **Get the viewer.** `akceo viewer` writes `md-viewer.html` into the current folder. Use
+   `-o` to put it somewhere else. You only need one copy; it can open any notes file.
+3. **Open the deck** (`deck.html`) in Chrome.
+4. **Open the viewer** (`md-viewer.html`) in a second tab. Click **Open .md** and pick your notes
+   file, or drag the file onto the page.
+5. **Put the tabs side by side** with Chrome's split view, so both sit in one window.
+6. **Present.** Share the deck tab in your meeting, and read your notes from the other half of
+   the window.
+
+### Try it with the demo
+
+```sh
+akceo build examples/demo/deck.md
+akceo viewer -o examples/demo
+```
+
+Open `examples/demo/deck.html` and `examples/demo/md-viewer.html` in two tabs. In the viewer,
+open `examples/demo/speaker-notes.md`. Its sections match the demo's seven slides.
+
+## Sharing in a meeting
+
+The idea is to share the one tab that holds the slides, not your whole screen.
+
+- **Google Meet** in Chrome can share a single tab. Choose to present a tab and pick the deck.
+- **Zoom's desktop app** shares a screen or a window rather than a tab. With split view, the
+  window includes your notes. Either share just the part of the screen that holds the deck, or
+  keep the deck in its own window and share that.
+
+## Live refresh
+
+In Chrome and Edge, the viewer watches the file you opened. When you save the notes, the page
+updates within about two seconds and keeps your scroll position. The header shows
+**● watching** while this is on. It works when the viewer is opened straight from disk, with no
+web server.
+
+- If the file is moved or deleted, the header shows **file unavailable · open it again**.
+- Reloading the viewer tab forgets the file. Open it again.
+- Other browsers can't watch files. Drop the file on the page again to refresh.
+
+**A−** and **A+** change the text size, and the viewer remembers the size for next time.
+
+## Notes format
+
+The viewer renders a common subset of Markdown, listed below. This layout reads well in it:
+
+```markdown
+# Speaker Notes · My talk
+
+---
+
+### 1 · Opening *(0:30)*
+What to say on the first slide.
+
+### 2 · The problem *(1:00)*
+- A point to hit
+- Another point
+```
+
+- One `###` heading per slide, numbered to match the deck, makes it easy to keep your place.
+- An italic part in a heading, like `*(0:30)*`, shows in small amber type. It's a good spot for
+  a time budget.
+
+The viewer renders:
+- headings
+- paragraphs
+- **bold**, *italic* and `code`
+- links
+- images
+- bulleted and numbered lists, nested by indenting
+- tables
+- quotes
+- fenced code blocks
+- horizontal rules
+
+Raw HTML shows as plain text, and other Markdown extensions, such as strikethrough, task lists
+and footnotes, aren't rendered.
+
+Only `http`, `https`, `mailto` and relative links become clickable. Links open in a new tab.
+
+Images use `![alt](path)`. A relative path resolves from the folder that holds `md-viewer.html`,
+not from the notes file, because the browser doesn't tell the viewer where the notes file lives.
+So keep the viewer next to your notes: `akceo viewer -o <notes folder>`. `http(s)` and
+`data:image/` sources work too. Any other source shows the alt text instead.
+
+## Limits
+
+- The notes don't follow the slides. Scroll the viewer as you go.
diff --git a/examples/demo/speaker-notes.md b/examples/demo/speaker-notes.md
new file mode 100644
index 0000000..1855102
--- /dev/null
+++ b/examples/demo/speaker-notes.md
@@ -0,0 +1,41 @@
+# Speaker Notes · Akceo demo
+
+Open this file in `md-viewer.html` in a second tab. Share only the deck tab.
+
+---
+
+### 1 · Decks at the speed of text *(0:20)*
+Open with the promise: a deck is a text file, and one command turns it into a presentation.
+
+### 2 · Slides are structured text *(0:45)*
+Three points, in order:
+
+1. **Markdown**: write in any editor, keep it in git, review changes in a diff.
+2. **One file**: images are embedded, so there's nothing to lose when you email it.
+3. **Anywhere**: it opens in any browser, even with no network.
+
+If asked: this slide is the `bullets` layout, the default when a slide doesn't name one.
+
+### 3 · A small set of marks *(0:40)*
+Walk the list top to bottom. Each item shows the syntax and the result side by side.
+
+- `==accent==` is the one to point out; it's how a lead line gets its color.
+- The last item shows that a long line can wrap in the source without breaking on the slide.
+
+### 4 · One command, one file *(0:40)*
+Point at the diagram: the deck and a theme go in, one HTML file comes out.
+
+The three phases on the right are the whole workflow. Mention that images are shrunk at build time, so a big screenshot doesn't make a big deck.
+
+### 5 · From zero to a deck *(0:30)*
+Read the four steps as a loop, not a one-time setup. After the first install it's write, build, present.
+
+### 6 · Five layouts *(0:30)*
+There are only five layouts, on purpose. Most slides are `bullets`; `split` is for a diagram with commentary.
+
+> The muted last column is `dim-last-column: yes` on this slide.
+
+### 7 · Same deck, any look *(0:20)*
+Close by rebuilding with `--theme paper` live, if time allows. The content doesn't change, only the look.
+
+---
diff --git a/src/akceo/assets/md-viewer.html b/src/akceo/assets/md-viewer.html
new file mode 100644
index 0000000..b08fe14
--- /dev/null
+++ b/src/akceo/assets/md-viewer.html
@@ -0,0 +1,257 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Markdown Viewer</title>
+<style>
+  :root{
+    --bg:#0b0f16; --panel:#111925; --line:#22314a; --text:#e8eef6; --muted:#93a4bd;
+    --accent:#5eead4; --accent2:#fbbf24; --warn:#f87171; --fs:18px;
+    --sans:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;
+    --mono:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;
+  }
+  *{box-sizing:border-box;margin:0;padding:0}
+  html,body{height:100%}
+  body{background:var(--bg);color:var(--text);font-family:var(--sans);display:flex;flex-direction:column}
+  header{display:flex;align-items:center;gap:14px;padding:10px 18px;border-bottom:1px solid var(--line);
+         background:var(--panel);position:sticky;top:0;z-index:5;flex:none}
+  header .name{color:var(--accent);font-family:var(--mono);font-size:13px;overflow:hidden;
+               text-overflow:ellipsis;white-space:nowrap;flex:1}
+  header .name .idle{color:var(--muted)}
+  button{font:inherit;font-size:13px;color:var(--text);background:#1b2740;border:1px solid var(--line);
+         border-radius:7px;padding:6px 12px;cursor:pointer}
+  button:hover{border-color:var(--accent);color:#fff}
+  button.accent{background:var(--accent);color:#06231d;border-color:var(--accent);font-weight:600}
+  .fsz{display:flex;gap:4px}
+  .fsz button{padding:6px 10px}
+  #status{color:var(--muted);font-size:12px;font-family:var(--mono)}
+  #status.on{color:var(--accent2)}
+  #status.warn{color:var(--warn)}
+  main{flex:1;overflow-y:auto}
+  #empty{height:100%;display:flex;flex-direction:column;align-items:center;justify-content:center;
+         gap:14px;color:var(--muted);text-align:center;padding:40px}
+  #empty .big{font-size:22px;color:var(--text)}
+  #content{max-width:80ch;margin:0 auto;padding:40px 48px 120px;font-size:var(--fs);line-height:1.62;display:none}
+  #content h1{font-size:1.9em;margin:.2em 0 .5em;letter-spacing:-.01em;border-bottom:1px solid var(--line);padding-bottom:.2em}
+  #content h2{font-size:1.5em;margin:1.4em 0 .5em;letter-spacing:-.01em}
+  #content h3{font-size:1.2em;margin:1.5em 0 .4em;color:#fff}
+  #content h3 em{color:var(--accent2);font-style:normal;font-size:.82em;font-family:var(--mono)}
+  #content h4{font-size:1.02em;margin:1.2em 0 .3em;color:var(--muted);text-transform:uppercase;letter-spacing:.06em}
+  #content p{margin:.7em 0}
+  #content ul,#content ol{margin:.6em 0 .6em 1.5em}
+  #content li{margin:.32em 0}
+  #content li>ul,#content li>ol{margin:.2em 0 .2em 1.3em}
+  #content img{max-width:100%;height:auto;border-radius:8px}
+  #content strong{color:#fff}
+  #content em{color:var(--text)}
+  #content a{color:var(--accent);text-decoration:none;border-bottom:1px solid rgba(94,234,212,.3)}
+  #content a:hover{border-bottom-color:var(--accent)}
+  #content code{font-family:var(--mono);font-size:.88em;background:#182338;color:var(--accent2);
+                padding:2px 6px;border-radius:5px}
+  #content pre{background:#0e1626;border:1px solid var(--line);border-radius:10px;padding:16px;
+               overflow-x:auto;margin:1em 0}
+  #content pre code{background:none;color:#cdd8e6;padding:0;font-size:.86em}
+  #content blockquote{border-left:3px solid var(--accent);background:#0e1626;margin:1em 0;padding:.6em 1.1em;
+                      color:var(--muted);border-radius:0 8px 8px 0}
+  #content hr{border:none;border-top:1px solid var(--line);margin:2em 0}
+  #content table{border-collapse:collapse;width:100%;margin:1em 0;font-size:.92em;display:block;overflow-x:auto}
+  #content th,#content td{border:1px solid var(--line);padding:9px 12px;text-align:left;vertical-align:top}
+  #content th{background:#0e1626;color:var(--accent);font-size:.85em;letter-spacing:.04em;text-transform:uppercase}
+  #drop{position:fixed;inset:0;background:rgba(11,15,22,.92);border:3px dashed var(--accent);
+        display:none;align-items:center;justify-content:center;font-size:26px;color:var(--accent);z-index:20}
+  #drop.show{display:flex}
+</style>
+</head>
+<body>
+<header>
+  <span class="name"><span class="idle">No file loaded</span></span>
+  <span id="status" role="status"></span>
+  <div class="fsz"><button id="minus" title="Smaller text">A&minus;</button><button id="plus" title="Larger text">A+</button></div>
+  <button id="open" class="accent">Open .md</button>
+  <input id="file" type="file" accept=".md,.markdown,.txt,text/markdown" hidden>
+</header>
+<main>
+  <div id="empty">
+    <div class="big">Open or drop a Markdown file</div>
+    <div id="hint"></div>
+  </div>
+  <article id="content"></article>
+</main>
+<div id="drop">Drop to open</div>
+
+<script>
+(function(){
+  var nameEl=document.querySelector('.name'), statusEl=document.getElementById('status'),
+      main=document.querySelector('main'), content=document.getElementById('content'),
+      empty=document.getElementById('empty'), drop=document.getElementById('drop'),
+      input=document.getElementById('file');
+  // File System Access API: Chrome and Edge, including pages opened from file://.
+  var canWatch=!!window.showOpenFilePicker;
+  document.getElementById('hint').textContent=canWatch
+    ?'It refreshes by itself whenever you save the file.'
+    :'This browser can\'t watch files, so drop the file again to refresh after edits.';
+
+  var fs=parseInt(localStorage.getItem('mdv_fs')||'18',10); applyFontSize();
+  function applyFontSize(){document.documentElement.style.setProperty('--fs',fs+'px');localStorage.setItem('mdv_fs',fs);}
+  document.getElementById('plus').onclick=function(){fs=Math.min(30,fs+1);applyFontSize();};
+  document.getElementById('minus').onclick=function(){fs=Math.max(12,fs-1);applyFontSize();};
+
+  var LIST_ITEM=/^([ \t]*)([-*+]|\d+\.)[ \t]+(.*)$/;
+  function esc(s){return s.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');}
+  function safeUrl(url,schemes){
+    // URL parsers drop control characters and spaces, so "java\tscript:" would still run as javascript:.
+    url=url.replace(/[\u0000-\u0020]/g,'');
+    var scheme=url.match(/^([a-z][a-z0-9+.-]*):/i);
+    return scheme&&!schemes.test(scheme[1])?null:url.replace(/"/g,'&quot;');
+  }
+  function link(text,url){
+    url=safeUrl(url,/^(https?|mailto)$/i);
+    return url===null?text:'<a href="'+url+'" target="_blank" rel="noopener">'+text+'</a>';
+  }
+  function image(alt,url){
+    url=safeUrl(url,/^(https?|data)$/i);
+    if(url===null||(/^data:/i.test(url)&&!/^data:image\//i.test(url)))return alt;
+    return '<img src="'+url+'" alt="'+alt.replace(/"/g,'&quot;')+'">';
+  }
+  // [text](url) and ![alt](src). Parentheses inside the URL are matched in pairs.
+  function links(s,hold){
+    var out='',i=0;
+    while(i<s.length){
+      var open=s.indexOf('[',i);
+      if(open<0)break;
+      var close=s.indexOf(']',open);
+      if(close<0)break;
+      var j=close+2,depth=1;
+      if(s.charAt(close+1)==='('){
+        while(j<s.length){if(s[j]==='(')depth++;else if(s[j]===')'&&--depth===0)break;j++;}
+      }
+      if(s.charAt(close+1)!=='('||depth){out+=s.slice(i,open+1);i=open+1;continue;}
+      var isImage=s.charAt(open-1)==='!',text=s.slice(open+1,close),url=s.slice(close+2,j);
+      out+=s.slice(i,isImage?open-1:open)+hold(isImage?image(text,url):link(text,url));
+      i=j+1;
+    }
+    return out+s.slice(i);
+  }
+  // Items indented deeper than the one before nest under it.
+  function listHtml(items){
+    var out='',open=[];
+    items.forEach(function(it){
+      while(open.length&&it.indent<open[open.length-1].indent)out+='</li></'+open.pop().tag+'>';
+      var top=open[open.length-1];
+      if(top&&it.indent===top.indent&&it.tag===top.tag){out+='</li><li>';}
+      else{
+        if(top&&it.indent===top.indent)out+='</li></'+open.pop().tag+'>';
+        open.push({indent:it.indent,tag:it.tag});out+='<'+it.tag+'><li>';
+      }
+      out+=inline(it.text);
+    });
+    while(open.length)out+='</li></'+open.pop().tag+'>';
+    return out;
+  }
+  function inline(s){
+    var held=[];
+    function hold(html){held.push(html);return '\uE000'+(held.length-1)+'\uE000';}
+    s=esc(s);
+    s=s.replace(/`([^`]+)`/g,function(m,c){return hold('<code>'+c+'</code>');});
+    s=links(s,hold);
+    s=s.replace(/\*\*([^*]+)\*\*/g,'<strong>$1</strong>');
+    s=s.replace(/(^|[^*])\*([^*\s][^*]*?)\*/g,'$1<em>$2</em>');
+    s=s.replace(/(^|[^\w])_([^_\s][^_]*?)_/g,'$1<em>$2</em>');
+    return s.replace(/\uE000(\d+)\uE000/g,function(m,i){return held[i];});
+  }
+  function splitRow(l){return l.trim().replace(/^\|/,'').replace(/\|$/,'').split('|').map(function(c){return c.trim();});}
+  function md(src){
+    var lines=src.replace(/\r\n?/g,'\n').split('\n'),out='',i=0,n=lines.length,para=[];
+    function flush(){if(para.length){out+='<p>'+inline(para.join(' '))+'</p>';para=[];}}
+    while(i<n){
+      var line=lines[i];
+      if(/^```/.test(line)){flush();i++;var code=[];while(i<n&&!/^```/.test(lines[i])){code.push(lines[i]);i++;}i++;out+='<pre><code>'+esc(code.join('\n'))+'</code></pre>';continue;}
+      if(/^\s*$/.test(line)){flush();i++;continue;}
+      var h=line.match(/^(#{1,6})\s+(.*)$/);
+      if(h){flush();out+='<h'+h[1].length+'>'+inline(h[2])+'</h'+h[1].length+'>';i++;continue;}
+      if(/^(-{3,}|\*{3,}|_{3,})\s*$/.test(line)){flush();out+='<hr>';i++;continue;}
+      if(/\|/.test(line)&&i+1<n&&/-/.test(lines[i+1])&&/^\s*\|?[\s:|-]+\|?\s*$/.test(lines[i+1])){
+        flush();var head=splitRow(line);i+=2;var rows=[];
+        while(i<n&&/\|/.test(lines[i])&&!/^\s*$/.test(lines[i])){rows.push(splitRow(lines[i]));i++;}
+        out+='<table><thead><tr>'+head.map(function(c){return '<th>'+inline(c)+'</th>';}).join('')+'</tr></thead><tbody>'+
+             rows.map(function(r){return '<tr>'+r.map(function(c){return '<td>'+inline(c)+'</td>';}).join('')+'</tr>';}).join('')+'</tbody></table>';continue;}
+      if(/^>\s?/.test(line)){flush();var bq=[];while(i<n&&/^>\s?/.test(lines[i])){bq.push(lines[i].replace(/^>\s?/,''));i++;}out+='<blockquote>'+md(bq.join('\n'))+'</blockquote>';continue;}
+      if(LIST_ITEM.test(line)){
+        flush();var items=[];
+        while(i<n){
+          var m=lines[i].match(LIST_ITEM);
+          if(m){items.push({indent:m[1].replace(/\t/g,'    ').length,tag:/\d/.test(m[2])?'ol':'ul',text:m[3]});i++;}
+          else if(/^[ \t]+\S/.test(lines[i])){items[items.length-1].text+=' '+lines[i].trim();i++;}
+          else if(/^\s*$/.test(lines[i])&&i+1<n&&LIST_ITEM.test(lines[i+1])){i++;}
+          else break;
+        }
+        out+=listHtml(items);continue;
+      }
+      para.push(line);i++;
+    }
+    flush();return out;
+  }
+
+  function setStatus(text,cls){statusEl.textContent=text;statusEl.className=cls||'';}
+  function render(text,name,keepScroll){
+    var top=main.scrollTop;
+    content.innerHTML=md(text);
+    content.style.display='block';empty.style.display='none';
+    nameEl.textContent=name||'document';document.title=(name||'Markdown')+' — Viewer';
+    main.scrollTop=keepScroll?top:0;
+  }
+
+  // Reads finish out of order. Each open bumps the generation, and a read only renders if its
+  // generation is still current, so the latest selection always wins.
+  var handle=null,lastMod=0,generation=0,polling=false;
+  function openHandle(h){
+    var gen=++generation;
+    return h.getFile().then(function(f){
+      return f.text().then(function(t){
+        if(gen!==generation)return;
+        handle=h;lastMod=f.lastModified;render(t,f.name,false);setStatus('● watching','on');
+      });
+    });
+  }
+  function openFile(f){
+    var gen=++generation;handle=null;
+    f.text().then(function(t){
+      if(gen!==generation)return;
+      render(t,f.name,false);setStatus(canWatch?'not watching · use Open to watch':'drop again to refresh');
+    });
+  }
+  setInterval(function(){
+    if(!handle||polling)return;
+    var h=handle,gen=generation;polling=true;
+    h.getFile().then(function(f){
+      if(gen!==generation||f.lastModified===lastMod)return;
+      return f.text().then(function(t){if(gen!==generation)return;lastMod=f.lastModified;render(t,f.name,true);});
+    }).catch(function(){if(gen===generation){handle=null;setStatus('file unavailable · open it again','warn');}})
+      .then(function(){polling=false;});
+  },1500);
+
+  document.getElementById('open').onclick=function(){
+    if(!canWatch){input.click();return;}
+    window.showOpenFilePicker({types:[{description:'Markdown',accept:{'text/markdown':['.md','.markdown','.txt']}}]})
+      .then(function(picks){return openHandle(picks[0]);})
+      .catch(function(err){if(err&&err.name!=='AbortError')input.click();});
+  };
+  input.addEventListener('change',function(e){var f=e.target.files[0];if(f)openFile(f);input.value='';});
+
+  window.addEventListener('dragover',function(e){e.preventDefault();drop.classList.add('show');});
+  window.addEventListener('dragleave',function(e){if(e.relatedTarget===null)drop.classList.remove('show');});
+  window.addEventListener('drop',function(e){
+    e.preventDefault();drop.classList.remove('show');
+    // The drop's data is only readable during this event, so take the file and ask for its handle now.
+    var file=e.dataTransfer.files[0],item=e.dataTransfer.items&&e.dataTransfer.items[0];
+    if(!file)return;
+    var pending=item&&item.getAsFileSystemHandle?item.getAsFileSystemHandle():null;
+    if(!pending){openFile(file);return;}
+    pending.then(function(h){return h&&h.kind==='file'?openHandle(h):openFile(file);})
+           .catch(function(){openFile(file);});
+  });
+})();
+</script>
+</body>
+</html>
diff --git a/src/akceo/cli.py b/src/akceo/cli.py
index 7b8b0da..6d42a05 100644
--- a/src/akceo/cli.py
+++ b/src/akceo/cli.py
@@ -9,6 +9,8 @@
 from akceo import render, themes
 from akceo.errors import DeckError
 
+VIEWER = "md-viewer.html"
+
 
 def _parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
@@ -23,6 +25,13 @@ def _parser() -> argparse.ArgumentParser:
     build.add_argument("-t", "--theme", help="built-in theme name or path to a .css file (overrides theme:)")
 
     commands.add_parser("themes", help="list the built-in themes")
+
+    viewer = commands.add_parser(
+        "viewer", help="write md-viewer.html, a live Markdown viewer for speaker notes"
+    )
+    viewer.add_argument(
+        "-o", "--out", type=Path, default=Path(VIEWER), help=f"output file or folder (default: ./{VIEWER})"
+    )
     return parser
 
 
@@ -31,6 +40,8 @@ def main(argv: Sequence[str] | None = None) -> int:
     try:
         if args.command == "build":
             _build(args.deck, args.out, args.theme)
+        elif args.command == "viewer":
+            _write_viewer(args.out)
         else:
             _list_themes()
     except DeckError as e:
@@ -42,12 +53,23 @@ def main(argv: Sequence[str] | None = None) -> int:
 def _build(deck: Path, out: Path | None, theme: str | None) -> None:
     page, count = render.build(deck, theme)
     out = out or deck.with_suffix(".html")
+    _write(out, page)
+    noun = "slide" if count == 1 else "slides"
+    print(f"wrote {out} ({out.stat().st_size / 1024:.0f} KB, {count} {noun})")
+
+
+def _write_viewer(out: Path) -> None:
+    if out.is_dir():
+        out = out / VIEWER
+    _write(out, (render.ASSETS / VIEWER).read_text(encoding="utf-8"))
+    print(f"wrote {out}")
+
+
+def _write(out: Path, text: str) -> None:
     try:
-        out.write_text(page, encoding="utf-8")
+        out.write_text(text, encoding="utf-8")
     except OSError as e:
         raise DeckError(f"{out}: {e.strerror}") from None
-    noun = "slide" if count == 1 else "slides"
-    print(f"wrote {out} ({out.stat().st_size / 1024:.0f} KB, {count} {noun})")
 
 
 def _list_themes() -> None:
diff --git a/tests/test_cli.py b/tests/test_cli.py
index 119fde3..e0a7412 100644
--- a/tests/test_cli.py
+++ b/tests/test_cli.py
@@ -7,7 +7,9 @@
 
 from akceo.cli import main
 
-DEMO = Path(__file__).parents[1] / "examples" / "demo"
+ROOT = Path(__file__).parents[1]
+DEMO = ROOT / "examples" / "demo"
+EXTERNAL_REF = re.compile(r"""(src|href)=["']?(https?:|//|\.{0,2}/)|<link|@import|url\(""")
 
 
 def test_builds_the_demo_deck_self_contained(tmp_path: Path, capsys: pytest.CaptureFixture[str]):
@@ -19,7 +21,7 @@ def test_builds_the_demo_deck_self_contained(tmp_path: Path, capsys: pytest.Capt
     assert page.count('<section class="slide') == 7
     assert "__SLIDES__" not in page
     assert "data:image/svg+xml;base64," in page
-    assert not re.search(r"""(src|href)=["']?(https?:|//|\.{0,2}/)|<link|@import|url\(""", page)
+    assert not EXTERNAL_REF.search(page)
 
 
 def test_default_output_sits_next_to_the_deck(tmp_path: Path):
@@ -37,9 +39,7 @@ def test_theme_flag_overrides_the_deck(tmp_path: Path):
 def test_deck_paths_resolve_against_the_deck_folder(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
     (tmp_path / "talk" / "img").mkdir(parents=True)
     Image.new("RGB", (20, 20)).save(tmp_path / "talk" / "img" / "fig.png")
-    shutil.copy(
-        Path(__file__).parents[1] / "src" / "akceo" / "themes" / "paper.css", tmp_path / "talk" / "brand.css"
-    )
+    shutil.copy(ROOT / "src" / "akceo" / "themes" / "paper.css", tmp_path / "talk" / "brand.css")
     (tmp_path / "talk" / "deck.md").write_text(
         "theme: brand.css\nimages: img\n---\nlayout: split\nimage: fig.png\n\n## Figure\n"
     )
@@ -74,3 +74,34 @@ def test_themes_command(capsys: pytest.CaptureFixture[str]):
     lines = capsys.readouterr().out.splitlines()
     assert lines[0].startswith("midnight  ") and lines[0].endswith("(default)")
     assert lines[1].startswith("paper     ")
+
+
+def test_viewer_is_written_to_the_working_directory(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+):
+    monkeypatch.chdir(tmp_path)
+    assert main(["viewer"]) == 0
+    assert capsys.readouterr().out == "wrote md-viewer.html\n"
+    page = (tmp_path / "md-viewer.html").read_text()
+    assert page == (ROOT / "src" / "akceo" / "assets" / "md-viewer.html").read_text()
+    assert "showOpenFilePicker" in page
+    assert not EXTERNAL_REF.search(page)
+
+
+def test_viewer_out_may_be_a_folder_or_a_file(tmp_path: Path):
+    assert main(["viewer", "-o", str(tmp_path)]) == 0
+    assert (tmp_path / "md-viewer.html").is_file()
+    assert main(["viewer", "-o", str(tmp_path / "notes.html")]) == 0
+    assert (tmp_path / "notes.html").is_file()
+
+
+def test_packaged_assets_contain_no_raw_control_characters():
+    # A raw NUL in a JavaScript regex is turned into U+FFFD by the HTML parser, which makes the whole
+    # viewer script a syntax error while every Python test still passes. Escapes must stay as text.
+    package = ROOT / "src" / "akceo"
+    paths = [*package.glob("assets/*"), *package.glob("themes/*.css")]
+    assert len(paths) >= 6
+    for path in paths:
+        text = path.read_text(encoding="utf-8")
+        bad = {hex(ord(c)) for c in text if (ord(c) < 32 and c not in "\n\t") or 0xE000 <= ord(c) <= 0xF8FF}
+        assert not bad, f"{path.name}: {sorted(bad)}"