Document that display-based capture is unavailable on headless

browsers/headless.mdx

@@ -53,5 +53,7 @@ func main() {
 </CodeGroup>
 
 <Info>
-    [Live View](/browsers/live-view) and [Replays](/browsers/replays) are not available in headless mode.
+    [Live View](/browsers/live-view) and [Replays](/browsers/replays) are not available in headless mode. Both capture the browser's display, which headless doesn't have. The same applies to the `screenshot` [telemetry category](/browsers/telemetry/categories) and to [computer controls](/browsers/computer-controls) screenshots.
+
+    To capture what a headless page looked like, take screenshots through your automation framework — Playwright's `page.screenshot()` renders in the page and works without a display. Every other telemetry category works headless.
 </Info>

browsers/replays.mdx

@@ -5,6 +5,10 @@ description: "Record and view browser sessions as mp4 videos"
 
 Replays capture browser sessions as video recordings that you can view or download later. You have full control over when replays start and stop, allowing you to capture specific interactions or workflows.
 
+<Note>
+Recording is opt-in per session. A browser doesn't record until you call `replays.start()`, so a session you never started a replay on produces no video.
+</Note>
+
 ## Starting and stopping recordings
 
 To start recording a browser session, use the replays API on an active browser:

browsers/telemetry/categories.mdx

@@ -107,12 +107,16 @@ These categories report what's happening in the page. Capturing any of them atta
 | `network` | Network requests, responses, and failures | `network_request`, `network_response`, `network_loading_failed`, `network_idle`, `proxy_error` |
 | `page` | Navigation and page lifecycle, including performance signals and renderer crashes | `page_navigation`, `page_dom_content_loaded`, `page_load`, `page_tab_opened`, `page_crashed`, `page_layout_shift`, `page_lcp`, `page_layout_settled`, `page_navigation_settled` |
 | `interaction` | Browser-native input in the page (clicks, keys, scroll) | `interaction_click`, `interaction_key`, `interaction_scroll_settled` |
-| `screenshot` | Periodic screenshots of the session | `monitor_screenshot` |
+| `screenshot` | Periodic screenshots of the session. Headful only | `monitor_screenshot` |
 
 <Note>
 `interaction` events are browser-native DOM events observed in the page, not calls to the [computer-control](/browsers/computer-controls) API (those are reported by the `control` category).
 </Note>
 
+<Warning>
+`screenshot` captures the browser's display, so it can't capture the page on a [headless](/browsers/headless) session. Enabling it there is accepted but won't give you usable frames. To capture frames headless, take them through your automation framework instead — Playwright's `page.screenshot()` renders in the page and needs no display.
+</Warning>
+
 ### The monitor category
 
 `monitor` reports the health of the CDP collector itself: `monitor_disconnected`, `monitor_reconnected`, `monitor_reconnect_failed`, and `monitor_init_failed`.

introduction/create.mdx

@@ -72,7 +72,7 @@ Most of what you'll tune at creation time falls into four buckets:
 
 <Columns cols={2}>
   <Card title="Headless vs headful" href="/browsers/headless">
-    headful (default) supports live view, replays, and better stealth — ideal for agent workflows on bot-detected sites. headless is lighter (1 gb vs 8 gb), good for simple scraping.
+    headful (default) supports live view, [replays](/browsers/replays) (opt-in per session), and better stealth — ideal for agent workflows on bot-detected sites. headless is lighter (1 gb vs 8 gb), good for simple scraping.
   </Card>
   <Card title="Stealth and proxies" href="/browsers/bot-detection/overview">
     Turn on stealth mode and route through residential, ISP, or datacenter proxies when you're hitting sites with bot detection.