diff --git a/Rendering.md b/Rendering.md
new file mode 100644
index 0000000..7ea7a64
--- /dev/null
+++ b/Rendering.md
@@ -0,0 +1,147 @@
+# Rendering
+
+go-session provides two rendering backends: a self-contained HTML timeline and an MP4 video via charmbracelet's VHS.
+
+## RenderHTML
+
+```go
+func RenderHTML(sess *Session, outputPath string) error
+```
+
+Generates a single `.html` file with no external dependencies. The output is a dark-themed interactive timeline suitable for sharing, archiving, or embedding.
+
+### Usage
+
+```go
+sess, _ := session.ParseTranscript("session.jsonl")
+err := session.RenderHTML(sess, "timeline.html")
+```
+
+### Features
+
+**Header bar** (sticky, top of page):
+- Session ID (first 8 characters)
+- Start timestamp (`2006-01-02 15:04:05` format)
+- Total duration (formatted as `Xh Ym`, `Xm Ys`, `X.Xs`, or `Xms`)
+- Tool call count
+- Error count (shown in red, only if > 0)
+
+**Search and filtering:**
+- Text search input — filters events by input and output content
+- Dropdown filter with options: All events, Tool calls only, Errors only, Bash only, User messages
+- Keyboard shortcut: press `/` to focus the search box
+
+**Event cards** — each event renders as a collapsible card:
+- Click to expand/collapse (toggle arrow indicator)
+- Timestamp (`HH:MM:SS`)
+- Tool name with colour coding:
+  - Green for Bash commands
+  - Blue (accent) for other tools
+  - Red for errors
+  - Yellow for user messages
+  - Grey for assistant messages
+- Truncated input (120 characters max)
+- Duration display
+- Success/failure icon (checkmark or cross)
+
+**Expanded view** shows:
+- Full input with contextual label (Command, Message, Response, Target, or File)
+- Full output (red-highlighted if error)
+- Output capped at 400px height with scroll
+
+### Theme
+
+The HTML uses CSS custom properties with a GitHub Dark colour scheme:
+
+| Variable | Colour | Use |
+|----------|--------|-----|
+| `--bg` | `#0d1117` | Page background |
+| `--bg2` | `#161b22` | Header, event headers |
+| `--accent` | `#58a6ff` | Tool names, links |
+| `--green` | `#3fb950` | Bash tools, success |
+| `--red` | `#f85149` | Errors |
+| `--yellow` | `#d29922` | User messages |
+
+Font stack: SF Mono, Cascadia Code, JetBrains Mono, monospace.
+
+## RenderMP4
+
+```go
+func RenderMP4(sess *Session, outputPath string) error
+```
+
+Generates an MP4 video by creating a VHS tape script and executing it. Requires [VHS](https://github.com/charmbracelet/vhs) to be installed.
+
+### Prerequisites
+
+```bash
+go install github.com/charmbracelet/vhs@latest
+```
+
+If VHS is not found in PATH, the function returns an error with installation instructions.
+
+### Usage
+
+```go
+sess, _ := session.ParseTranscript("session.jsonl")
+err := session.RenderMP4(sess, "session.mp4")
+```
+
+### How It Works
+
+1. Generates a VHS `.tape` script from session events
+2. Writes the tape to a temporary file
+3. Executes `vhs <tape-file>` which renders to the specified output path
+4. Cleans up the temporary tape file
+
+### Tape Configuration
+
+The generated tape uses these settings:
+
+| Setting | Value |
+|---------|-------|
+| Font Size | 16 |
+| Width | 1400px |
+| Height | 800px |
+| Typing Speed | 30ms |
+| Theme | Catppuccin Mocha |
+| Shell | bash |
+
+### Event Rendering in Video
+
+The video renders different event types with different treatments:
+
+**Title frame** — shown for 2 seconds:
+```
+# Session abc12345 | 2026-02-19 10:30
+```
+
+**Bash commands** — typed out with output:
+- Command prefixed with `$ `
+- Output truncated to 200 characters
+- Status indicator: `# ✓ OK` or `# ✗ FAILED`
+- 1 second pause after each command
+
+**Read/Edit/Write** — shown as comments:
+```
+# Read: /src/main.go
+# Edit: /src/config.go (edit)
+```
+- 500ms pause after each
+
+**Task (sub-agent)** — shown as comments:
+```
+# Agent: [code] Refactor the auth module
+```
+- 1 second pause after each
+
+**Closing** — 3 second hold on final frame.
+
+### Command Extraction
+
+For Bash events, the `extractCommand` helper strips the description suffix (everything after ` # `) from the input before rendering, so the video shows clean commands.
+
+## Related
+
+- [[Home]] — Package overview and installation
+- [[Session-Format]] — JSONL structure and event types