Add speaker notes viewer and how-it-works docs

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.

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.

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