docs(use-cases): sync capture, MCP logs, and Botasaurus request schema

Capture stamps strategy and supports --explain; MCP daemons log to stderr at info. Replace scroll_to_bottom with scroll and document the OpenAPI 2.0 window_size object.

Author: gildesmarais

src/content/docs/ruby-gem/guides/ai-agent-workflows.mdx

@@ -110,3 +110,7 @@ For dynamic JavaScript single-page applications or sites protected by anti-bot m
 />
 
 Put `BOTASAURUS_SCRAPER_URL` (typically `http://127.0.0.1:4010`) in the MCP server `env` block above — a shell export does not reach the Cursor/Claude MCP process. Confirm with `html2rss://runtime` (`botasaurus_configured: true`). AutoFallback then hops without a second tool call.
+
+## Daemon logs (stderr)
+
+`html2rss mcp` uses stdout for JSON-RPC, so the daemon logs to **stderr**. Unless you set `LOG_LEVEL`, the MCP process uses `info` (the gem library default stays `warn`). A foreground watcher sees the start banner, each tool call, and pipeline fallbacks. Use `LOG_LEVEL=debug` for more detail or `LOG_LEVEL=warn` to quiet it.

src/content/docs/ruby-gem/guides/backward-compatibility.mdx

@@ -7,6 +7,17 @@ import { Code } from "@astrojs/starlight/components";
 
 This page outlines recent breaking changes, purged legacy aliases, and migration steps for older feed configurations.
 
+## Current Botasaurus request schema
+
+`request.botasaurus` matches the scrape-API OpenAPI 2.0 `ScrapeRequest` (unknown keys rejected):
+
+1. **`scroll`** — boolean. There is no `scroll_to_bottom` key; use `scroll: true` for infinite lists.
+2. **`window_size`** — object `{ width: 1920, height: 1080 }`, not a two-item array.
+3. **`wait_timeout_seconds`** — integer `1..20` (omit to use the scrape-API default of `15`).
+4. **`max_retries`** — integer `0..3` (omit to use the scrape-API default of `2`).
+
+Run `html2rss validate config.yml` after editing Botasaurus options.
+
 ## 0.26.0
 
 Upgrade notes for configs and integrators targeting gem **0.26.0**:
@@ -97,4 +108,5 @@ When upgrading to modern `html2rss` releases:
 4. **Move channel-level transport keys**: Ensure `strategy` and `headers` are defined at the top level of the YAML file.
 5. **Use `enclosure` for RSS media**: Do not rely on `image` becoming an RSS `<enclosure>`; select podcast/media URLs with `enclosure`.
 6. **Prefer `feed_result` for dual-format / cache**: Integrators that need RSS + JSON Feed from one scrape (or Marshal caching) should use `Html2rss.feed_result` and `status.to_h`.
-7. **Validate configurations**: Run `html2rss validate config.yml` to ensure your YAML conforms to the current schema.
+7. **Align `request.botasaurus` with OpenAPI 2.0**: Replace `scroll_to_bottom` with `scroll`, use `{ width, height }` for `window_size`, and keep `wait_timeout_seconds` in `1..20`.
+8. **Validate configurations**: Run `html2rss validate config.yml` to ensure your YAML conforms to the current schema.

src/content/docs/ruby-gem/guides/capturing-feed-configs.mdx

@@ -36,6 +36,8 @@ Print YAML to stdout:
   html2rss capture https://example.com/articles --items_selector ".post-card"
   # Analyze a local HTML fixture
   html2rss capture https://example.com/articles --input ./page.html
+  # Quality JSON on stderr; YAML stays on stdout
+  html2rss capture https://example.com/articles --explain
   # Save the draft
   html2rss capture https://example.com/articles > my-feed.yml
 `}
@@ -46,9 +48,10 @@ Common options:
 
 - `--strategy` — `auto`, `faraday`, `botasaurus`, or `local_file` (default `auto`)
 - `--items_selector` — CSS selector hint for item cards
-- `--limit` — maximum articles kept while deriving selectors
+- `--limit` — maximum articles kept while deriving selectors (default `25`)
 - `--max-redirects` / `--max-requests` — request budget overrides
 - `--input` — local HTML file (sets `local_file` strategy)
+- `--explain` — print capture quality JSON on stderr (`articles_count`, `channel_title`, `has_selectors`, `segment_strategy`, `selected_strategy`, `admission_drops`); YAML stays on stdout
 
 See the [CLI reference](/ruby-gem/reference/cli-reference/#capture) for the full flag list.
 
@@ -77,7 +80,7 @@ See the [CLI reference](/ruby-gem/reference/cli-reference/#capture) for the full
 2. **Discover** — AutoSource extracts admitted articles
 3. **Segment** — SST Segmenter strategies `:list` → `:cluster` → `:semantic`
 4. **Gate** — emit an items selector only when enough articles match
-5. **Assemble** — `{ items: { selector:, enhance: true } }` plus channel
+5. **Assemble** — `{ items: { selector:, enhance: true } }` plus channel. When AutoFallback selects a concrete transport (or you pin one), Capture **stamps** `strategy:` into the YAML so later `html2rss feed` / `Html2rss.feed` replay the same transport.
 
 When the quality gate fails, selectors are omitted (`has_selectors: false`) rather than inventing attribute selectors. Hint with `--items_selector` or refine by hand.
 

src/content/docs/ruby-gem/guides/custom-http-requests.mdx

@@ -73,7 +73,7 @@ Request budgets are configured under `request`, not as top-level keys:
 
 - `request.max_redirects` limits redirect hops
 - `request.max_requests` limits the total request budget for the feed build
-- `request.botasaurus.*` is reserved for Botasaurus-only behavior such as navigation mode, retries, header/cookie forwarding, and scroll options
+- `request.botasaurus.*` is reserved for Botasaurus-only behavior such as navigation mode, retries, header/cookie forwarding, and `scroll`
 
 ## Common Use Cases
 

src/content/docs/ruby-gem/guides/handling-dynamic-content.mdx

@@ -22,7 +22,7 @@ When a site requires browser rendering or anti-bot bypass by default, you can ex
     botasaurus:
       navigation_mode: google_get_bypass
       wait_for_selector: ".article-card"
-      scroll_to_bottom: true
+      scroll: true
   channel:
     url: https://example.com/app
   selectors:
@@ -44,7 +44,7 @@ Botasaurus extraction is ideal when:
 - **Content loads after page load** - JavaScript fetches data dynamically
 - **Single Page Applications (SPAs)** - React, Vue, Angular apps
 - **Anti-bot interstitials** - Cloudflare, Google search referrers, or challenge pages
-- **Scroll-triggered content** - Infinite scroll lists (`scroll_to_bottom: true`)
+- **Scroll-triggered content** - Infinite scroll lists (`scroll: true`)
 
 ## Botasaurus Request Controls
 
@@ -70,7 +70,7 @@ Configure browser actions under `request.botasaurus`:
   strategy: botasaurus
   request:
     botasaurus:
-      scroll_to_bottom: true
+      scroll: true
   `}
   lang="yaml"
 />