StreamnDad · JRemitz · Apr 2, 2026 · Apr 2, 2026
diff --git a/.gitignore b/.gitignore
@@ -37,6 +37,9 @@ docs/_build/
 CLAUDE.md
 AGENTS.md
 
+# Video demo notes — presenter-only, not published
+examples/_video-talking-points.md
+
 # IDE
 .idea/
 .vscode/

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.0.35] - 2026-04-02
+
+### Added
+- `examples/` directory with 10 step-by-step walkthrough pages covering install, OBS setup, game lifecycle, rendering, profiles, plugins, and smart zoom
+- Examples integrated into Read the Docs via `docs/examples/` section
+- Video demo talking points (gitignored, presenter-only)
+
+### Changed
+- README.md rewritten: prominent ffmpeg dependency callout, updated CLI reference (removed stale "coming soon" section), added examples link
+- Docs index updated with ffmpeg admonition, current feature list, and examples toctree entry
+
 ## [0.0.34] - 2026-04-02
 
 ### Added

diff --git a/README.md b/README.md
@@ -12,38 +12,81 @@
 
 reeln handles video manipulation, segment/highlight management, and media lifecycle — generic by default, sport-specific through configuration. Built by [Streamn Dad](https://streamn.dad).
 
-## Features
-
-- **Game lifecycle management** — init, segment, highlights, finish
-- **FFmpeg-powered video merging** — concat segments into highlight reels, no re-encoding
-- **Sport-agnostic segment model** — hockey periods, basketball quarters, soccer halves, and more
-- **Flexible configuration** — JSON config with XDG-compliant paths, env var overrides, named profiles
-- **Pipeline debugging** — `--debug` flag captures ffmpeg commands, filter chains, and metadata for troubleshooting
-- **Plugin-ready architecture** — lifecycle hooks, typed capability interfaces, and config schema declarations
-- **Cross-platform** — macOS, Linux, Windows
+## Requirements
 
-## Quick start
+- **Python 3.11+**
+- **ffmpeg 5.0+** with libx264, aac, and libass
+
+> **Important:** reeln requires ffmpeg installed on your system. It is used for
+> all video processing — merging, rendering, overlays, and encoding. Install it
+> before using reeln, then run `reeln doctor` to verify.
+>
+> ```bash
+> # macOS
+> brew install ffmpeg
+>
+> # Ubuntu / Debian
+> sudo apt install ffmpeg
+>
+> # Windows
+> winget install ffmpeg
+> ```
+
+## Install
 
 ```bash
-# Install
+# With pip
 pip install reeln
 
-# Verify it works
+# With uv (recommended)
+uv tool install reeln
+```
+
+Verify everything is working:
+
+```bash
 reeln --version
+reeln doctor          # checks ffmpeg, codecs, config, permissions, plugins
+```
 
-# View your configuration
-reeln config show
+## Features
+
+- **Game lifecycle management** — init, segment processing, highlights, events, finish
+- **Short-form rendering** — crop, scale, speed, LUT, overlays — landscape to vertical/square
+- **FFmpeg-powered merging** — concat segments into highlight reels with smart re-encoding
+- **Sport-agnostic segments** — hockey periods, basketball quarters, soccer halves, and more
+- **Render profiles** — save and reuse rendering settings, chain them with iterations
+- **Smart zoom** — AI-powered tracking that follows the action (via plugin)
+- **Player overlays** — roster-aware goal overlays with jersey number lookup
+- **Plugin architecture** — lifecycle hooks for YouTube, Instagram, cloud uploads, and more
+- **Flexible configuration** — JSON config, XDG paths, env var overrides, named profiles
+- **Cross-platform** — macOS, Linux, Windows
 
+## Quick start
+
+```bash
 # Initialize a hockey game
 reeln game init roseville mahtomedi --sport hockey
+
+# Process segments as the game progresses
+reeln game segment 1
+reeln game segment 2
+reeln game segment 3
+
+# Merge into a full-game highlight reel
+reeln game highlights
+
+# Render a vertical short for social media
+reeln render short clip.mkv --crop crop --speed 0.5
+
+# Finish the game
+reeln game finish
 ```
 
-More commands are being built — rendering and media management are on the roadmap. See the [CLI reference](#cli-reference) below for what's available and what's coming.
+See the [examples](examples/) for detailed walkthroughs of every workflow.
 
 ## Supported sports
 
-reeln adapts its directory structure and terminology to your sport:
-
 | Sport | Segment name | Count | Example directories |
 |---|---|---|---|
 | hockey | period | 3 | `period-1/`, `period-2/`, `period-3/` |
@@ -54,39 +97,56 @@ reeln adapts its directory structure and terminology to your sport:
 | lacrosse | quarter | 4 | `quarter-1/` through `quarter-4/` |
 | generic | segment | 1 | `segment-1/` |
 
-Custom sports can be registered in your config file.
-
 ## CLI reference
 
-**Available now:**
+### System
 
 | Command | Description |
 |---|---|
-| `reeln --version` | Show version |
-| `reeln --help` | Show help and available commands |
-| `reeln config show` | Display current configuration |
-| `reeln config doctor` | Validate config, warn on issues |
-| `reeln game init` | Set up game directory with sport-specific segments |
-
-| `reeln plugins search` | Search the plugin registry |
-| `reeln plugins info <name>` | Show detailed plugin information |
-| `reeln plugins install <name>` | Install a plugin from the registry |
-| `reeln plugins update [name]` | Update a plugin or all installed plugins |
-| `reeln plugins list` | List installed plugins with version info |
-| `reeln plugins enable <name>` | Enable a plugin |
-| `reeln plugins disable <name>` | Disable a plugin |
+| `reeln --version` | Show version and ffmpeg info |
+| `reeln doctor` | Health check: ffmpeg, codecs, config, permissions, plugins |
 
-**Coming soon** (command groups are registered, implementation in progress):
+### Game lifecycle
 
 | Command | Description |
 |---|---|
-| `reeln game segment <N>` | Move replays and merge segment highlights |
+| `reeln game init` | Set up game directory with sport-specific segments |
+| `reeln game segment <N>` | Collect replays and merge segment highlights |
 | `reeln game highlights` | Merge all segments into full-game highlight reel |
-| `reeln game finish` | Finalize game, cleanup temp files |
-| `reeln render short` | Render 9:16 short from clip |
+| `reeln game compile` | Compile event clips by type, segment, or player |
+| `reeln game finish` | Finalize game and show summary |
+| `reeln game prune` | Remove generated artifacts |
+| `reeln game event list` | List registered events |
+| `reeln game event tag` | Tag an event with type, player, metadata |
+
+### Rendering
+
+| Command | Description |
+|---|---|
+| `reeln render short` | Render 9:16 or 1:1 short from clip |
 | `reeln render preview` | Fast low-res preview render |
-| `reeln media prune` | Artifact cleanup (supports `--dry-run`) |
-| `reeln doctor` | Health check: ffmpeg, config, permissions |
+| `reeln render apply` | Apply a render profile (full-frame, no crop) |
+| `reeln render reel` | Assemble rendered shorts into a reel |
+
+### Configuration
+
+| Command | Description |
+|---|---|
+| `reeln config show` | Display resolved configuration |
+| `reeln config doctor` | Validate config and warn on issues |
+| `reeln config event-types` | Manage event types |
+
+### Plugins
+
+| Command | Description |
+|---|---|
+| `reeln plugins search` | Search the plugin registry |
+| `reeln plugins info <name>` | Show plugin details and config schema |
+| `reeln plugins install <name>` | Install a plugin from the registry |
+| `reeln plugins update [name]` | Update a plugin or all installed |
+| `reeln plugins list` | List installed plugins |
+| `reeln plugins enable <name>` | Enable a plugin |
+| `reeln plugins disable <name>` | Disable a plugin |
 
 ## Configuration
 
@@ -98,37 +158,13 @@ reeln uses a layered JSON config system:
 4. **Environment variables** — `REELN_<SECTION>_<KEY>`
 
 ```bash
-# Override any config value via env var
-export REELN_VIDEO_FFMPEG_PATH=/opt/ffmpeg/bin/ffmpeg
-export REELN_PATHS_OUTPUT_DIR=~/custom-output
-
-# View the resolved config
 reeln config show
 ```
 
-## Requirements
-
-- Python 3.11+
-- [ffmpeg 5.0+](https://ffmpeg.org/)
-
-## Installation
-
-```bash
-# With pip
-pip install reeln
-
-# With uv
-uv tool install reeln
-
-# Development
-git clone https://github.com/StreamnDad/reeln-cli.git
-cd reeln-cli
-make dev-install
-```
-
 ## Documentation
 
-Full documentation is available at [reeln-cli.readthedocs.io](https://reeln-cli.readthedocs.io).
+- [Full documentation](https://reeln-cli.readthedocs.io) — install, guides, CLI reference
+- [Examples](examples/) — step-by-step walkthroughs for common workflows
 
 ## License
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -50,6 +50,10 @@
 }
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+# Suppress warnings for relative links in included example files — these links
+# work on GitHub (primary consumption) but can't resolve in the Sphinx build.
+suppress_warnings = ["myst.xref_missing"]
+
 # -- Intersphinx mapping ----------------------------------------------------
 
 intersphinx_mapping = {

diff --git a/docs/examples/configuration.md b/docs/examples/configuration.md
@@ -0,0 +1,5 @@
+# Configuration & OBS Setup
+
+```{include} ../../examples/02-configuration.md
+:start-line: 2
+```
diff --git a/docs/examples/game-finish-and-cleanup.md b/docs/examples/game-finish-and-cleanup.md
@@ -0,0 +1,5 @@
+# Game Finish & Cleanup
+
+```{include} ../../examples/08-game-finish-and-cleanup.md
+:start-line: 2
+```
diff --git a/docs/examples/getting-started.md b/docs/examples/getting-started.md
@@ -0,0 +1,5 @@
+# Getting Started
+
+```{include} ../../examples/01-getting-started.md
+:start-line: 2
+```
diff --git a/docs/examples/highlights-and-reels.md b/docs/examples/highlights-and-reels.md
@@ -0,0 +1,5 @@
+# Highlights & Reels
+
+```{include} ../../examples/06-highlights-and-reels.md
+:start-line: 2
+```
diff --git a/docs/examples/index.md b/docs/examples/index.md
@@ -0,0 +1,19 @@
+# Examples
+
+Step-by-step walkthroughs for common reeln workflows. Each example is
+self-contained — start from the top or jump to whatever fits your use case.
+
+```{toctree}
+:maxdepth: 1
+
+getting-started
+configuration
+starting-a-game
+segments-and-events
+rendering-shorts
+highlights-and-reels
+profiles-and-iterations
+game-finish-and-cleanup
+plugins
+smart-zoom
+```
diff --git a/docs/examples/plugins.md b/docs/examples/plugins.md
@@ -0,0 +1,5 @@
+# Plugins
+
+```{include} ../../examples/09-plugins.md
+:start-line: 2
+```
diff --git a/docs/examples/profiles-and-iterations.md b/docs/examples/profiles-and-iterations.md
@@ -0,0 +1,5 @@
+# Profiles & Iterations
+
+```{include} ../../examples/07-profiles-and-iterations.md
+:start-line: 2
+```
diff --git a/docs/examples/rendering-shorts.md b/docs/examples/rendering-shorts.md
@@ -0,0 +1,5 @@
+# Rendering Shorts
+
+```{include} ../../examples/05-rendering-shorts.md
+:start-line: 2
+```
diff --git a/docs/examples/segments-and-events.md b/docs/examples/segments-and-events.md
@@ -0,0 +1,5 @@
+# Segments & Events
+
+```{include} ../../examples/04-segments-and-events.md
+:start-line: 2
+```
diff --git a/docs/examples/smart-zoom.md b/docs/examples/smart-zoom.md
@@ -0,0 +1,5 @@
+# Smart Zoom
+
+```{include} ../../examples/10-smart-zoom.md
+:start-line: 2
+```
diff --git a/docs/examples/starting-a-game.md b/docs/examples/starting-a-game.md
@@ -0,0 +1,5 @@
+# Starting a Game
+
+```{include} ../../examples/03-starting-a-game.md
+:start-line: 2
+```
diff --git a/docs/index.md b/docs/index.md
@@ -9,9 +9,18 @@ reeln handles video manipulation, segment/highlight management, and media lifecy
 - **FFmpeg foundation** — cross-platform ffmpeg discovery, version checking, probe helpers, deterministic command building
 - **Flexible configuration** — JSON config with XDG-compliant paths, env var overrides, named profiles
 - **Sport-agnostic segment model** — built-in support for 7 sports with custom sport registration
-- **Game lifecycle management** — initialize game directories, process segments, merge highlights, finalize *(in progress)*
-- **Short-form rendering** — crop, scale, and reframe clips into vertical/square formats with speed control, LUT grading, and subtitle overlays
-- **Plugin-ready architecture** — lifecycle hooks and capability interfaces for future extensions
+- **Game lifecycle management** — initialize game directories, process segments, merge highlights, tag events, finalize
+- **Short-form rendering** — crop, scale, speed, LUT, overlays — landscape to vertical/square
+- **Render profiles & iterations** — save and reuse render settings, chain them for multi-pass output
+- **Smart zoom** — AI-powered tracking that follows the action (via plugin)
+- **Player overlays** — roster-aware goal overlays with jersey number lookup
+- **Plugin architecture** — lifecycle hooks for YouTube, Instagram, cloud uploads, and more
+- **Cross-platform** — macOS, Linux, Windows
+
+:::{important}
+reeln requires **ffmpeg 5.0+** installed on your system for all video processing.
+See {doc}`install` for setup instructions, then run `reeln doctor` to verify.
+:::
 
 ## Getting started
 
@@ -46,6 +55,14 @@ cli/config
 cli/plugins
 ```
 
+## Examples
+
+```{toctree}
+:maxdepth: 1
+
+examples/index
+```
+
 ## Project
 
 ```{toctree}