diff --git a/README.md b/README.md
index daf6d49..6ec6189 100644
--- a/README.md
+++ b/README.md
@@ -296,6 +296,7 @@ Available options:
 - `-i, --idle-time-limit=<sec>` - Limit replayed terminal inactivity to max `<sec>` seconds
 - `-s, --speed=<factor>` - Playback speed (can be fractional)
 - `-l, --loop` - Play in a loop
+- `-b, --breakpoints` - Automatically pause on [breakpoints](#breakpoints)
 - `--stream=<stream>` - Select stream to play (see below)
 - `--out-fmt=<format>` - Select output format (see below)
 
@@ -361,6 +362,29 @@ happen in any order.
 > asciinema versions prior to 2.0 confusingly referred to install ID as "API
 > token".
 
+## Breakpoints
+
+Breakpoints are markers that you can set in a recording to pause the playback at
+a specific point.
+
+When a breakpoint is reached, the playback automatically pauses and can be
+resumed by pressing space bar key. The playback continues until next breakpoint
+is encountered.
+
+To enable auto-pause-on-breakpoint behaviour when replaying with `asciinema
+play` use `-b`/`--breakpoints` option. It's off by default.
+
+Breakpoints can be added to a recording in several ways:
+
+- during recording session, by pressing a configured hotkey, see
+  [add_breakpoint_key config option](#configuration-file)
+- for existing recording, by inserting breakpoint events (`"b"`) in the
+  asciicast file, see [breakpoint event](doc/asciicast-v2.md#b---breakpoint)
+
+Breakpoints can be useful in e.g. live demos: you can create a recording with
+breakpoints, then play it back during presentation, and have it stop wherever
+you want to explain terminal contents in more detail.
+
 ## Hosting the recordings on the web
 
 As mentioned in the `Usage > rec` section above, if the `filename` argument to
@@ -419,7 +443,7 @@ quiet = true
 ; default: C-\ (control + backslash)
 pause_key = C-p
 
-; Define hotkey for adding a breakpoint, default: None
+; Define hotkey for adding a breakpoint, default: none
 add_breakpoint_key = C-b
 
 ; Define hotkey prefix key - when defined other recording hotkeys must
diff --git a/doc/asciicast-v2.md b/doc/asciicast-v2.md
index 71cab9e..961c163 100644
--- a/doc/asciicast-v2.md
+++ b/doc/asciicast-v2.md
@@ -167,15 +167,14 @@ non-printable Unicode codepoints encoded as `\uXXXX`.
 
 #### "b" - breakpoint
 
-Event of type `"b"` represents a playback breakpoint.
+Event of type `"b"` represents a breakpoint.
 
 When breakpoint is encountered in the event stream and "pause on breakpoint"
 functionality of the player is enabled, the playback should pause, and wait for
 the user to resume.
 
 `event-data` can be used to annotate (comment) a breakpoint. Annotations may be
-used to show a list of "chapters" (players that load whole recording into
-memory only).
+used to e.g. show a list of "chapters".
 
 ## Notes on compatibility