From 72dc1d08d253ae42ab3df6282023c920f972f5ea Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 6 Sep 2026 02:49:59 +0200
Subject: [PATCH 1/6] docs(concepts): update server architecture and default
 http strategy

---
 src/content/docs/creating-custom-feeds.mdx    | 2 +-
 src/content/docs/web-application/concepts.mdx | 8 ++++++--
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/src/content/docs/creating-custom-feeds.mdx b/src/content/docs/creating-custom-feeds.mdx
index 31b098d2..18fac1a4 100644
--- a/src/content/docs/creating-custom-feeds.mdx
+++ b/src/content/docs/creating-custom-feeds.mdx
@@ -22,7 +22,7 @@ Prefer [Getting Started](/getting-started/) (URL paste) and the [Feed Directory]
 3. Validate: `html2rss validate your-config.yml`
 4. Live-check: `html2rss test your-config.yml`, then ship with `html2rss apply your-config.yml`
 5. Mount into `html2rss-web` or contribute to html2rss-configs
-6. Escalate to `strategy: botasaurus` (or `auto` with `BOTASAURUS_SCRAPER_URL`) only when Faraday is not enough
+6. Escalate to `strategy: botasaurus` (or `auto` with `BOTASAURUS_SCRAPER_URL`) only when default HTTP fetching is not enough
 
 `html2rss feed` is a Thor alias for `apply`. `html2rss auto` aliases `scrape` (one-shot, no YAML).
 
diff --git a/src/content/docs/web-application/concepts.mdx b/src/content/docs/web-application/concepts.mdx
index a0e36e4f..beefa085 100644
--- a/src/content/docs/web-application/concepts.mdx
+++ b/src/content/docs/web-application/concepts.mdx
@@ -13,7 +13,7 @@ Production Docker Compose defaults `AUTO_SOURCE_ENABLED` to `true`. Non-compose
 
 ## Botasaurus companion
 
-`html2rss-web` talks to `botasaurus-scrape-api` at `BOTASAURUS_SCRAPER_URL` (Compose sets `http://botasaurus:4010`). That service renders JavaScript-heavy pages when Faraday alone is not enough. Auto-source uses Faraday first, then Botasaurus when configured.
+`html2rss-web` talks to `botasaurus-scrape-api` at `BOTASAURUS_SCRAPER_URL` (Compose sets `http://botasaurus:4010`). That service renders JavaScript-heavy pages when default HTTP fetching alone is not enough. Auto-source uses the default HTTP strategy (HTTPX) first, then Botasaurus when configured.
 
 ## Three tokens (plain English)
 
@@ -27,9 +27,13 @@ Generate secrets with `openssl rand -hex 32`. Demo quickstart hard-codes `CHANGE
 
 Optional: `SENTRY_DSN` (web) and `BOTASAURUS_SENTRY_DSN` (scraper) for error reporting. They are separate projects; leave both unset until you want monitoring.
 
+## Server & async reactor
+
+`html2rss-web` runs on the Falcon application server, an asynchronous fiber-based server supporting HTTP/1.1 and HTTP/2. Falcon cooperates with HTTPX for non-blocking upstream I/O and coalesces concurrent feed requests in memory to prevent cache stampedes.
+
 ## HTTP vs HTTPS
 
-Plain HTTP works on localhost and LAN. The app sets HSTS and CSP `upgrade-insecure-requests` only when the request is HTTPS (including when a reverse proxy sends `X-Forwarded-Proto: https`). Put Caddy, Nginx, or Traefik in front for public TLS.
+Plain HTTP works on localhost and LAN. The app sets HSTS and CSP `upgrade-insecure-requests` only when the request is HTTPS (including when a reverse proxy sends `X-Forwarded-Proto: https`). For public TLS, put Caddy, Nginx, or Traefik in front, or configure direct in-process TLS with Falcon.
 
 ## Ecosystem map
 

From 55583d8540712c9ff9b650f31df310994797bb6c Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 6 Sep 2026 02:50:05 +0200
Subject: [PATCH 2/6] docs(guides): update strategy migration notes and direct
 tls deployment

---
 .../docs/ruby-gem/guides/ai-agent-workflows.mdx      |  2 +-
 .../docs/ruby-gem/guides/backward-compatibility.mdx  |  6 ++++++
 .../docs/ruby-gem/guides/capturing-feed-configs.mdx  |  2 +-
 .../ruby-gem/guides/handling-dynamic-content.mdx     |  4 ++--
 src/content/docs/web-application/deployment.mdx      | 12 ++++++++++++
 5 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/src/content/docs/ruby-gem/guides/ai-agent-workflows.mdx b/src/content/docs/ruby-gem/guides/ai-agent-workflows.mdx
index 7ead82f0..be9c85d2 100644
--- a/src/content/docs/ruby-gem/guides/ai-agent-workflows.mdx
+++ b/src/content/docs/ruby-gem/guides/ai-agent-workflows.mdx
@@ -50,7 +50,7 @@ Put `BOTASAURUS_SCRAPER_URL` in the MCP `env` block — a shell export does not
 
 ## Golden loops
 
-**Articles now:** `scrape` (or `batch_scrape`). `strategy: "auto"` already falls back to Botasaurus when configured — do not retry with explicit `faraday` after `auto`. Empty items can still be success; follow `next_step`.
+**Articles now:** `scrape` (or `batch_scrape`). `strategy: "auto"` already falls back to Botasaurus when configured — do not retry with explicit `default` after `auto`. Empty items can still be success; follow `next_step`.
 
 **Durable YAML:** optional `inspect` → `recon` → `capture` → `test` → `apply`.
 
diff --git a/src/content/docs/ruby-gem/guides/backward-compatibility.mdx b/src/content/docs/ruby-gem/guides/backward-compatibility.mdx
index 8de5059b..13bdeda0 100644
--- a/src/content/docs/ruby-gem/guides/backward-compatibility.mdx
+++ b/src/content/docs/ruby-gem/guides/backward-compatibility.mdx
@@ -7,6 +7,12 @@ import { Code } from "@astrojs/starlight/components";
 
 This page outlines breaking changes, purged legacy aliases, and migration steps when upgrading the gem.
 
+## 0.30.0 (Unreleased)
+
+1. **Default HTTP strategy (`:default`)** — Migrated from Faraday to HTTPX. The canonical strategy name across configs, CLI, Ruby API, and MCP is `:default`.
+2. **Deprecated strategy aliases** — `:faraday` and `:httpx` remain accepted as aliases for `:default` with deprecation warnings. Update configurations and scripts to `strategy: default` (or `strategy: auto`).
+3. **HTTP/2 & SSRF protection** — The default transport provides native HTTP/2 multiplexing via ALPN and enforced private-network IP filtering.
+
 ## 0.27.0
 
 Upgrade notes for configs and integrators targeting gem **0.27.0** (current `master` after `0.26.0`):
diff --git a/src/content/docs/ruby-gem/guides/capturing-feed-configs.mdx b/src/content/docs/ruby-gem/guides/capturing-feed-configs.mdx
index cad7f99c..bcd64832 100644
--- a/src/content/docs/ruby-gem/guides/capturing-feed-configs.mdx
+++ b/src/content/docs/ruby-gem/guides/capturing-feed-configs.mdx
@@ -46,7 +46,7 @@ Print YAML to stdout:
 
 Common options:
 
-- `--strategy` — `auto`, `faraday`, `botasaurus`, or `local_file` (default `auto`)
+- `--strategy` — `auto`, `default`, `botasaurus`, or `local_file` (default `auto`)
 - `--items_selector` — CSS selector hint for item cards
 - `--limit` — maximum articles kept while deriving selectors (default `25`)
 - `--max-redirects` / `--max-requests` — request budget overrides
diff --git a/src/content/docs/ruby-gem/guides/handling-dynamic-content.mdx b/src/content/docs/ruby-gem/guides/handling-dynamic-content.mdx
index 503c9d14..44c6ec3a 100644
--- a/src/content/docs/ruby-gem/guides/handling-dynamic-content.mdx
+++ b/src/content/docs/ruby-gem/guides/handling-dynamic-content.mdx
@@ -9,7 +9,7 @@ Some websites load their content dynamically using JavaScript. Static fetch path
 
 ## Solution
 
-Default `strategy: auto` automatically tries `faraday` first, then falls back to `botasaurus` when `BOTASAURUS_SCRAPER_URL` is configured. This handles many JS-rendered listing pages without needing custom configuration.
+Default `strategy: auto` automatically tries `default` first, then falls back to `botasaurus` when `BOTASAURUS_SCRAPER_URL` is configured. This handles many JS-rendered listing pages without needing custom configuration.
 
 When a site requires browser rendering or anti-bot bypass by default, you can explicitly set `strategy: botasaurus` and configure request controls under `request.botasaurus`:
 
@@ -102,7 +102,7 @@ Browser-based extraction uses more resources than static HTTP fetching because i
 - Executes JavaScript and handles DOM events
 - Manages browser pools and network emulation
 
-Use static HTTP fetching (`faraday`) for static content, and lean on `auto` or explicit `botasaurus` strategies when browser rendering is required. See the [Strategy Reference](/ruby-gem/reference/strategy/) for details.
+Use static HTTP fetching (`default`) for static content, and lean on `auto` or explicit `botasaurus` strategies when browser rendering is required. See the [Strategy Reference](/ruby-gem/reference/strategy/) for details.
 
 ## Related Topics
 
diff --git a/src/content/docs/web-application/deployment.mdx b/src/content/docs/web-application/deployment.mdx
index d32230dd..9b64a116 100644
--- a/src/content/docs/web-application/deployment.mdx
+++ b/src/content/docs/web-application/deployment.mdx
@@ -79,6 +79,18 @@ Example `.env` beside Compose:
 
 After `docker compose up -d`, check `docker compose logs caddy --tail 20` for certificate issuance.
 
+### Direct TLS termination (Falcon)
+
+Falcon also supports in-process TLS termination and HTTP/2 negotiation by pointing to your certificate and private key:
+
+<Code
+  code={`
+  TLS_CERTIFICATE_PATH=/path/to/fullchain.pem
+  TLS_KEY_PATH=/path/to/privkey.pem
+`}
+  lang="dotenv"
+/>
+
 ## Custom feeds mount
 
 Auto-source is the default. To add curated YAML feeds, bind-mount `feeds.yml` (see [Advanced Feeds](/creating-custom-feeds/)):

From d3d6945604417ec77850cc9258558bfd33c3a4f1 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 6 Sep 2026 02:50:15 +0200
Subject: [PATCH 3/6] docs(adapters): document default httpx strategy, cli
 flags, mcp schemas, and error handling

---
 .../docs/ruby-gem/reference/auto-source.mdx   |  2 +-
 .../docs/ruby-gem/reference/cli-reference.mdx |  6 ++--
 .../docs/ruby-gem/reference/configuration.mdx |  4 +--
 .../docs/ruby-gem/reference/mcp-server.mdx    |  8 ++---
 .../docs/ruby-gem/reference/strategy.mdx      | 30 ++++++++++++-------
 .../docs/troubleshooting/troubleshooting.mdx  | 10 +++----
 6 files changed, 34 insertions(+), 26 deletions(-)

diff --git a/src/content/docs/ruby-gem/reference/auto-source.mdx b/src/content/docs/ruby-gem/reference/auto-source.mdx
index 1ec09d9d..d8be1f06 100644
--- a/src/content/docs/ruby-gem/reference/auto-source.mdx
+++ b/src/content/docs/ruby-gem/reference/auto-source.mdx
@@ -35,7 +35,7 @@ What each scraper does:
 - **`microdata`:** Extracts HTML Microdata annotations (`itemscope itemtype`).
 - **`microformats2`:** Parses Microformats2 `h-entry` markup, extracting `p-name`, `e-content`, `u-url`, `dt-published`, `p-author`, `p-category`, and `u-photo` / `u-featured` media.
 - **`json_state`:** Walks in-page JSON (`<script type="application/json">`, `window.__NEXT_DATA__`, `window.__NUXT__`, `window.STATE`) for arrays with `title`/`url` pairs.
-- **`xhr_articles`:** Reuses JSON XHR/fetch bodies captured during a Botasaurus **browser** scrape (no extra HTTP). Empty for Faraday and Botasaurus HTTP-request tiers.
+- **`xhr_articles`:** Reuses JSON XHR/fetch bodies captured during a Botasaurus **browser** scrape (no extra HTTP). Empty for default HTTP and Botasaurus HTTP-request tiers.
 - **`wordpress_api`:** Detects `<link rel="https://api.w.org/">` and pulls posts from the REST API. See [WordPress API](/ruby-gem/reference/wordpress-api/).
 - **`sitemap`:** Locates XML sitemaps (`<link rel="sitemap">`, `/sitemap.xml`, or `/robots.txt`), filtering by priority and recency, with Google News tags (`<news:news>`).
 - **`meta_oembed`:** OpenGraph/Twitter meta tags plus JSON oEmbed (`<link rel="alternate" type="application/json+oembed">`).
diff --git a/src/content/docs/ruby-gem/reference/cli-reference.mdx b/src/content/docs/ruby-gem/reference/cli-reference.mdx
index 3554048f..ef513d34 100644
--- a/src/content/docs/ruby-gem/reference/cli-reference.mdx
+++ b/src/content/docs/ruby-gem/reference/cli-reference.mdx
@@ -37,7 +37,7 @@ Command: `html2rss scrape [URL]`
 
 Available options:
 
-- `--strategy`: Optional request strategy (`auto`, `faraday`, `botasaurus`, `local_file`). Defaults to `auto`, which tries `faraday` -> `botasaurus`.
+- `--strategy`: Optional request strategy (`auto`, `default`, `botasaurus`, `local_file`). Defaults to `auto`, which tries `default` -> `botasaurus`. Legacy names `faraday` and `httpx` are accepted as aliases with a deprecation warning.
 - `--format`: Output format for the auto-sourced feed (`rss` or `jsonfeed`). Defaults to `rss`.
 - `--limit`: Maximum number of articles to extract during discovery (defaults to `25`).
 - `--items_selector`: Optional CSS selector hint for item extraction.
@@ -123,7 +123,7 @@ Command: `html2rss apply YAML_FILE [feed_name]`
 
 Available options:
 
-- `--strategy`: Request strategy override (`auto`, `faraday`, `botasaurus`, `local_file`).
+- `--strategy`: Request strategy override (`auto`, `default`, `botasaurus`, `local_file`).
 - `--params`: Dynamic parameters passed as key-value pairs (e.g. `--params id:42 section:news`).
 - `--max-redirects`: Maximum redirects to follow per request.
 - `--max-requests`: Total request budget allowed for this feed build.
@@ -150,7 +150,7 @@ Command: `html2rss capture [URL]`
 
 Available options:
 
-- `--strategy`: Optional request strategy (`auto`, `faraday`, `botasaurus`, `local_file`). Defaults to `auto`.
+- `--strategy`: Optional request strategy (`auto`, `default`, `botasaurus`, `local_file`). Defaults to `auto`.
 - `--items_selector`: Optional CSS selector hint for item extraction.
 - `--limit`: Maximum number of articles to keep (defaults to `25`).
 - `--max-redirects`: Maximum redirects to follow per request.
diff --git a/src/content/docs/ruby-gem/reference/configuration.mdx b/src/content/docs/ruby-gem/reference/configuration.mdx
index 9dad7c29..ddb73feb 100644
--- a/src/content/docs/ruby-gem/reference/configuration.mdx
+++ b/src/content/docs/ruby-gem/reference/configuration.mdx
@@ -16,7 +16,7 @@ Global configuration is thread-safe and implements an RCU (Read-Copy-Update) mec
 Html2rss.configure do |config|
 config.log_level = :info
 config.min_ttl = 60
-config.default_strategy = :faraday
+config.default_strategy = :default
 config.headers = { 'User-Agent' => 'MyCustomUserAgent/1.0' }
 end
 `}
@@ -84,7 +84,7 @@ Sets the default scraper strategy name used when a feed configuration doesn't sp
 <Code
   code={`
   Html2rss.configure do |config|
-    config.default_strategy = :faraday
+    config.default_strategy = :default
   end
   `}
   lang="ruby"
diff --git a/src/content/docs/ruby-gem/reference/mcp-server.mdx b/src/content/docs/ruby-gem/reference/mcp-server.mdx
index 41540aa1..10d13d91 100644
--- a/src/content/docs/ruby-gem/reference/mcp-server.mdx
+++ b/src/content/docs/ruby-gem/reference/mcp-server.mdx
@@ -28,9 +28,9 @@ Daemon logs go to **stderr** (stdout is JSON-RPC). Default `LOG_LEVEL` for the M
 
 ## Strategy
 
-`scrape` and `capture` with `strategy: "auto"` run Faraday → Botasaurus AutoFallback in one call. Prefer native RSS/Atom when present; weak homepage URLs may be rewritten via entry resolution.
+`scrape` and `capture` with `strategy: "auto"` run default (HTTPX) → Botasaurus AutoFallback in one call. Prefer native RSS/Atom when present; weak homepage URLs may be rewritten via entry resolution.
 
-`inspect` with `auto` stays on Faraday. Pin `strategy: "botasaurus"` when inspect needs browser rendering.
+`inspect` with `auto` stays on the default HTTP strategy. Pin `strategy: "botasaurus"` when inspect needs browser rendering.
 
 Read `html2rss://runtime` for `botasaurus_configured` (boolean only). Set `BOTASAURUS_SCRAPER_URL` on the **MCP process** env.
 
@@ -62,7 +62,7 @@ Golden path for durable YAML: `inspect` (optional) → `recon` → `capture` →
 
 One-shot article extraction as JSON Feed items (no saved config).
 
-- **Parameters:** `url` (required); `strategy` (`auto` / `faraday` / `botasaurus`, default `auto`); `limit` (default `25`); optional `items_selector`
+- **Parameters:** `url` (required); `strategy` (`auto` / `default` / `botasaurus`, default `auto`); `limit` (default `25`); optional `items_selector`
 - **Payload:** `items`, plus totals / strategy fields when present
 - Empty items can still be `ok: true` — follow `next_step` / `guidance`
 
@@ -120,7 +120,7 @@ Ship gate: build RSS from a config. Required `url` plus exactly one of `config`
 | ----------------------- | ------------------------------------------------------------------------------------------------------------------ |
 | `html2rss://schema`     | Feed config JSON Schema                                                                                            |
 | `html2rss://extractors` | Extractor names                                                                                                    |
-| `html2rss://strategies` | `auto`, `faraday`, `botasaurus` (not `local_file`)                                                                 |
+| `html2rss://strategies` | `auto`, `default`, `botasaurus` (not `local_file`)                                                                 |
 | `html2rss://runtime`    | `version`, `mcp_contract_version`, `catalog_fingerprint`, `tools`, `botasaurus_configured` — never the scraper URL |
 
 `validate` / `apply` reject `strategy: local_file` and `request.local_file_path`. Use CLI `--input` for fixtures.
diff --git a/src/content/docs/ruby-gem/reference/strategy.mdx b/src/content/docs/ruby-gem/reference/strategy.mdx
index 52ed0072..c4f8ed69 100644
--- a/src/content/docs/ruby-gem/reference/strategy.mdx
+++ b/src/content/docs/ruby-gem/reference/strategy.mdx
@@ -1,26 +1,26 @@
 ---
 title: Strategy
-description: "Learn how html2rss chooses request strategies by default with auto fallback, and when to override with faraday, botasaurus, or local_file."
+description: "Learn how html2rss chooses request strategies by default with auto fallback, and when to override with default, botasaurus, or local_file."
 ---
 
 import { Code } from "@astrojs/starlight/components";
 
 The `strategy` key defines how `html2rss` fetches a website's content.
 
-- **`auto`** (default): Tries concrete strategies in order: `faraday` -> `botasaurus`.
-- **`faraday`**: Makes a direct HTTP request. It is fast but does not execute JavaScript.
+- **`auto`** (default): Tries concrete strategies in order: `default` -> `botasaurus`.
+- **`default`**: Makes a direct HTTP request (powered by HTTPX). Fast and non-blocking with native HTTP/2, connection pooling, and SSRF protection. Does not execute JavaScript.
 - **`botasaurus`**: Delegates fetching to a Botasaurus scrape API. Included in the `auto` chain; requires `BOTASAURUS_SCRAPER_URL` when that tier runs (or when you pin `strategy: botasaurus`).
 - **`local_file`**: Reads HTML content directly from a local file on disk without making network requests.
 
 `strategy` is a top-level config key. Request-specific controls live under `request`.
 
-`auto` falls back to `botasaurus` when `faraday` errors or extracts zero items. Pin a concrete strategy when you need a specific transport (for example, forcing `botasaurus` directly).
+`auto` falls back to `botasaurus` when `default` errors or extracts zero items. Pin a concrete strategy when you need a specific transport (for example, forcing `botasaurus` directly).
 
 ## `auto` (default)
 
 The default strategy chain is:
 
-`faraday` -> `botasaurus`
+`default` -> `botasaurus`
 
 When the config uses `auto_source` (no custom `selectors`), each strategy attempt:
 
@@ -33,11 +33,19 @@ Auto fallback shares one request budget across all strategy attempts. The baseli
 
 Under `auto`, `Html2rss.feed_result(...).status` exposes scrape telemetry: `selected_strategy`, `attempt_count`, `strategy_attempts`, and when resolution ran `entry_url`, `scrape_url`, and `entry_resolution` (see [Managing Feed Configs](/ruby-gem/guides/managing-feed-configs/#ruby-api-feedresult)). Auto fallback decisions are also visible at `LOG_LEVEL=info` (hidden at the default `LOG_LEVEL=warn`).
 
-## `faraday`
+## `default`
 
-`faraday` is the standard static HTTP transport. When no custom `User-Agent` header is supplied in `headers`, `html2rss` sends `html2rss/<VERSION>` by default.
+`default` is the standard static HTTP transport, powered by HTTPX. When no custom `User-Agent` header is supplied in `headers`, `html2rss` sends `html2rss/<VERSION>` by default.
 
-HTML is accepted when `Content-Type` includes `text/html`, or when the body sniffs as HTML (`<!DOCTYPE html` / `<html`) and the response is not JSON. Gzip, deflate, and brotli bodies are decoded even when `Content-Encoding` is missing; unlabeled brotli is tried for `octet-stream`.
+It features:
+
+- **HTTP/2 & HTTP/1.1**: Automatic ALPN negotiation and multiplexed connection pooling.
+- **SSRF protection**: Native private-network IP filtering and redirect validation.
+- **Resilient decoding**: HTML is accepted when `Content-Type` includes `text/html`, or when the body sniffs as HTML (`<!DOCTYPE html` / `<html`) and the response is not JSON. Gzip, deflate, and brotli streams are decoded automatically.
+
+:::note
+Legacy names `faraday` and `httpx` are accepted as aliases for `default` and emit a deprecation warning.
+:::
 
 ## `botasaurus`
 
@@ -46,9 +54,9 @@ HTML is accepted when `Content-Type` includes `text/html`, or when the body snif
 Requirements:
 
 - `BOTASAURUS_SCRAPER_URL` set to your Botasaurus scrape API base URL (for example `http://localhost:4010`)
-- pin `strategy: botasaurus` when you want to skip Faraday and force this transport directly
+- pin `strategy: botasaurus` when you want to skip the default HTTP tier and force browser rendering directly
 
-html2rss enforces local request policy preflight and a feed-build timeout budget. The Botasaurus scrape API splits **total** scrape time (queue, boot, navigate, wait) from **work** time (navigate, selector wait, and scroll after the browser is ready). Feed YAML `wait_timeout_seconds` is validated against the work cap (`1..30` by default); the gem forwards `request.botasaurus` options to the scrape API without shrinking retries or waits to fit a remaining feed budget. Faraday transport timeout for POST `/scrape` is the lesser of the remaining feed-build budget and `BOTASAURUS_SCRAPE_TIMEOUT_SECONDS` plus a small buffer (default **45s** scrape total, **47s** transport cap).
+html2rss enforces local request policy preflight and a feed-build timeout budget. The Botasaurus scrape API splits **total** scrape time (queue, boot, navigate, wait) from **work** time (navigate, selector wait, and scroll after the browser is ready). Feed YAML `wait_timeout_seconds` is validated against the work cap (`1..30` by default); the gem forwards `request.botasaurus` options to the scrape API without shrinking retries or waits to fit a remaining feed budget. Transport timeout for POST `/scrape` is the lesser of the remaining feed-build budget and `BOTASAURUS_SCRAPE_TIMEOUT_SECONDS` plus a small buffer (default **45s** scrape total, **47s** transport cap).
 
 When the scrape API reports a timed-out stage, `Html2rss::RequestService::RequestTimedOut` may include `timeout_phase` (`queue`, `boot`, or `work`) and the same value in the exception message (`timeout_phase=<stage>`). Transport-hop timeouts leave `timeout_phase` unset.
 
@@ -152,7 +160,7 @@ Because no remote network connection is established, `local_file` skips remote n
 
 Use this split consistently:
 
-- `strategy`: selects `auto`, `faraday`, `botasaurus`, or `local_file`
+- `strategy`: selects `auto`, `default`, `botasaurus`, or `local_file`
 - `headers`: top-level headers shared by remote strategies (defaults to `html2rss/<VERSION>` User-Agent)
 - `request.max_redirects`: redirect limit for the request session (default: `5`)
 - `request.max_requests`: total request budget for the whole feed build (default: `10`)
diff --git a/src/content/docs/troubleshooting/troubleshooting.mdx b/src/content/docs/troubleshooting/troubleshooting.mdx
index 6f30a58c..5f4cba7d 100644
--- a/src/content/docs/troubleshooting/troubleshooting.mdx
+++ b/src/content/docs/troubleshooting/troubleshooting.mdx
@@ -68,7 +68,7 @@ DataDome (and similar) challenge pages are classified as a blocked surface. Pref
 2. `strategy: botasaurus` with `BOTASAURUS_SCRAPER_URL` so the browser tier can complete navigation
 3. A session that already has resolved challenge cookies when the site still blocks automated browsers
 
-Do not expect Faraday-only fetches to succeed against active DataDome interstitials.
+Do not expect static HTTP fetches to succeed against active DataDome interstitials.
 
 ### Botasaurus Setup & Diagnostics
 
@@ -95,8 +95,8 @@ Then run with:
 
 Common configuration-related errors:
 
-- **`UnsupportedResponseContentType`:** The website returned content that html2rss can't parse (not HTML or JSON). Faraday still treats bodies that sniff as HTML (`<!DOCTYPE html` / `<html`) as HTML, and decodes gzip/brotli even when `Content-Encoding` is missing.
-- **`UnsupportedStrategy`:** The specified strategy is not available. Use `auto`, `faraday`, `botasaurus`, or `local_file`.
+- **`UnsupportedResponseContentType`:** The website returned content that html2rss can't parse (not HTML or JSON). The default HTTP strategy still treats bodies that sniff as HTML (`<!DOCTYPE html` / `<html`) as HTML, and decodes gzip/brotli even when `Content-Encoding` is missing.
+- **`UnsupportedStrategy`:** The specified strategy is not available. Use `auto`, `default`, `botasaurus`, or `local_file` (`faraday` and `httpx` are accepted as legacy aliases).
 - **`BOTASAURUS_SCRAPER_URL is required for strategy=botasaurus.`:** Set `BOTASAURUS_SCRAPER_URL` to your Botasaurus scrape API base URL when using `--strategy botasaurus`.
 - **`BOTASAURUS_SCRAPER_URL is invalid`:** Fix the URL format and retry.
 - **`Configuration must include at least 'selectors' or 'auto_source'`:** You need to specify either manual selectors or enable auto-source.
@@ -109,7 +109,7 @@ If parts of your items (e.g., title, link) are missing, check the following:
 
 - **Selector:** Ensure the selector for the missing part is correct and relative to the `items.selector`.
 - **Extractor:** Verify that you are using the correct `extractor` (e.g., `text`, `href`, `attribute`).
-- **Dynamic Content:** `faraday` does not render JavaScript. If content loads dynamically, configure `BOTASAURUS_SCRAPER_URL` or run with `--strategy botasaurus` so the page can be rendered before extraction.
+- **Dynamic Content:** `default` does not render JavaScript. If content loads dynamically, configure `BOTASAURUS_SCRAPER_URL` or run with `--strategy botasaurus` so the page can be rendered before extraction.
 
 ### Date/Time Parsing Errors
 
@@ -156,7 +156,7 @@ If you are getting a "command not found" error, try the following:
 ### Rate Limiting & Timeouts
 
 - **429 Too Many Requests:** The client IP has exceeded the rate limit. Check the `RATE_LIMIT_MAX_REQUESTS` and `RATE_LIMIT_WINDOW_SECONDS` settings. The response includes a `Retry-After` header indicating how many seconds to wait before retrying.
-- **503 Service Unavailable:** The server is busy or the request timed out at the rack/server layer (e.g. `RACK_TIMEOUT_SERVICE_TIMEOUT`). Returns a `Retry-After` header matching `RETRY_AFTER_TIMEOUT_SECONDS`.
+- **503 Service Unavailable:** The server is busy or the request timed out at the server layer (e.g. `REQUEST_TIMEOUT_SECONDS`). Returns a `Retry-After` header matching `RETRY_AFTER_TIMEOUT_SECONDS`.
 - **504 Gateway Timeout:** The target website or scraper took too long to respond (exceeding `HTML2RSS_TOTAL_TIMEOUT_SECONDS`).
 
 ### Feed Problems

From 1bfa95210ad22256d00e9d42ab811c371e479aa2 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 6 Sep 2026 02:50:19 +0200
Subject: [PATCH 4/6] docs(infrastructure): sync environment variables and
 timeout hierarchy with falcon

---
 .../web-application/reference/env-variables.mdx     | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/src/content/docs/web-application/reference/env-variables.mdx b/src/content/docs/web-application/reference/env-variables.mdx
index 70eaf8ef..8218226f 100644
--- a/src/content/docs/web-application/reference/env-variables.mdx
+++ b/src/content/docs/web-application/reference/env-variables.mdx
@@ -24,23 +24,26 @@ description: "Configuration reference for html2rss-web environment variables."
 | `RETRY_AFTER_TIMEOUT_SECONDS`            | optional integer `>= 1`; default `300`; Retry-After header backoff duration returned on timeouts                                                             |
 | `PORT`                                   | app listen port; compose uses `4000`                                                                                                                         |
 | `RACK_ENV`                               | Rack environment; quickstart uses `development`, production examples use `production`                                                                        |
-| `BOTASAURUS_SCRAPE_TIMEOUT_SECONDS`      | optional; Faraday client cap for POST `/scrape` in seconds; default `45`; mirrors `SCRAPE_TIMEOUT_SECONDS` on botasaurus-scrape-api                          |
+| `REQUEST_TIMEOUT_SECONDS`                | optional; total web-request timeout in seconds on the Falcon server; default `55`                                                                            |
+| `WEB_CONCURRENCY`                        | optional integer `>= 1`; default `2` in production (`1` in development); number of Falcon worker processes                                                   |
+| `TLS_CERTIFICATE_PATH`                   | optional; path to certificate file (e.g. `fullchain.pem`) for direct in-process Falcon TLS termination                                                       |
+| `TLS_KEY_PATH`                           | optional; path to private key file (e.g. `privkey.pem`) for direct in-process Falcon TLS termination                                                         |
+| `BOTASAURUS_SCRAPE_TIMEOUT_SECONDS`      | optional; HTTP client cap for POST `/scrape` in seconds; default `45`; mirrors `SCRAPE_TIMEOUT_SECONDS` on botasaurus-scrape-api                             |
 | `BOTASAURUS_SCRAPE_WORK_TIMEOUT_SECONDS` | optional; maximum `wait_timeout_seconds` in feed YAML; default `30`; mirrors `SCRAPE_WORK_TIMEOUT_SECONDS` on botasaurus-scrape-api                          |
 | `SCRAPE_WORK_TIMEOUT_SECONDS`            | optional on botasaurus-scrape-api; post-boot navigate, selector wait, and scroll budget in seconds; default `30`; set on the scraper service in compose      |
-| `RACK_TIMEOUT_SERVICE_TIMEOUT`           | optional; total web-request timeout in seconds; default `55`                                                                                                 |
 | `HTML2RSS_TOTAL_TIMEOUT_SECONDS`         | optional; internal gem feed-build timeout in seconds; default `50`                                                                                           |
 
 ## Timeout Chain
 
 When fetching feeds from complex websites, multiple components work together. Configure timeouts so outer layers wait longer than inner layers and the scraper exhausts its budget before the web tier aborts the request.
 
-Default compose aligns **scrape total (45) ≤ feed build (50) ≤ Rack (55)**. The **work** budget (**30s**) applies on botasaurus-scrape-api only after the browser is ready; browser boot and queue time count against the **total** scrape wall (**45s**), not against `wait_timeout_seconds`.
+Default compose aligns **scrape total (45) ≤ feed build (50) ≤ Falcon request timeout (55)**. The **work** budget (**30s**) applies on botasaurus-scrape-api only after the browser is ready; browser boot and queue time count against the **total** scrape wall (**45s**), not against `wait_timeout_seconds`.
 
 1. **botasaurus-scrape-api (`SCRAPE_TIMEOUT_SECONDS`)**: **45s** handler wall (queue, boot, navigate, wait).
 2. **botasaurus-scrape-api (`SCRAPE_WORK_TIMEOUT_SECONDS`)**: **30s** post-boot navigate, `wait_for_selector`, and scroll.
-3. **html2rss client (`BOTASAURUS_SCRAPE_TIMEOUT_SECONDS`)**: **45s** Faraday cap for POST `/scrape` (mirrors scrape total).
+3. **html2rss client (`BOTASAURUS_SCRAPE_TIMEOUT_SECONDS`)**: **45s** HTTPX cap for POST `/scrape` (mirrors scrape total).
 4. **Feed YAML (`wait_timeout_seconds`)**: **1..30**, capped by `BOTASAURUS_SCRAPE_WORK_TIMEOUT_SECONDS` (default **30**).
 5. **html2rss-web gem budget (`HTML2RSS_TOTAL_TIMEOUT_SECONDS`)**: **50s** for scrape plus extraction.
-6. **html2rss-web (`RACK_TIMEOUT_SERVICE_TIMEOUT`)**: **55s** Rack outer wall.
+6. **html2rss-web (`REQUEST_TIMEOUT_SECONDS`)**: **55s** Falcon outer wall.
 
 Set matching `SCRAPE_*` on botasaurus-scrape-api and `BOTASAURUS_SCRAPE_*` on html2rss-web when you override defaults. See the `Environment & Runtime Flags` table in [`docs/README.md`](https://github.com/html2rss/html2rss-web/blob/main/docs/README.md) for compose examples.

From 352d03c8cf9b6163ad29d8b89d149ee5ac4da9be Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 6 Sep 2026 09:52:19 +0200
Subject: [PATCH 5/6] docs: center scraping guidance on auto

Deepen the public strategy interface around auto and default while keeping HTTP and server adapters behind their implementation seams. Remove migration narration and incomplete deployment side paths so end users can act on scrape outcomes instead of transport internals.
---
 src/content/docs/creating-custom-feeds.mdx    |  2 +-
 .../ruby-gem/guides/ai-agent-workflows.mdx    |  2 +-
 .../guides/backward-compatibility.mdx         |  6 ----
 .../guides/capturing-feed-configs.mdx         | 16 ++++------
 .../guides/handling-dynamic-content.mdx       |  8 ++---
 .../docs/ruby-gem/reference/auto-source.mdx   |  2 +-
 .../docs/ruby-gem/reference/cli-reference.mdx |  8 ++---
 .../docs/ruby-gem/reference/configuration.mdx |  7 ++--
 .../docs/ruby-gem/reference/mcp-server.mdx    |  4 +--
 .../docs/ruby-gem/reference/strategy.mdx      | 32 ++++++-------------
 .../docs/troubleshooting/troubleshooting.mdx  | 10 +++---
 src/content/docs/web-application/concepts.mdx |  8 ++---
 .../docs/web-application/deployment.mdx       | 12 -------
 .../reference/env-variables.mdx               | 14 ++++----
 14 files changed, 45 insertions(+), 86 deletions(-)

diff --git a/src/content/docs/creating-custom-feeds.mdx b/src/content/docs/creating-custom-feeds.mdx
index 18fac1a4..6a0ffcea 100644
--- a/src/content/docs/creating-custom-feeds.mdx
+++ b/src/content/docs/creating-custom-feeds.mdx
@@ -22,7 +22,7 @@ Prefer [Getting Started](/getting-started/) (URL paste) and the [Feed Directory]
 3. Validate: `html2rss validate your-config.yml`
 4. Live-check: `html2rss test your-config.yml`, then ship with `html2rss apply your-config.yml`
 5. Mount into `html2rss-web` or contribute to html2rss-configs
-6. Escalate to `strategy: botasaurus` (or `auto` with `BOTASAURUS_SCRAPER_URL`) only when default HTTP fetching is not enough
+6. Keep `strategy: auto`; if results are incomplete, confirm the companion scraper is configured before adding site-specific controls
 
 `html2rss feed` is a Thor alias for `apply`. `html2rss auto` aliases `scrape` (one-shot, no YAML).
 
diff --git a/src/content/docs/ruby-gem/guides/ai-agent-workflows.mdx b/src/content/docs/ruby-gem/guides/ai-agent-workflows.mdx
index be9c85d2..d1e4cf7f 100644
--- a/src/content/docs/ruby-gem/guides/ai-agent-workflows.mdx
+++ b/src/content/docs/ruby-gem/guides/ai-agent-workflows.mdx
@@ -50,7 +50,7 @@ Put `BOTASAURUS_SCRAPER_URL` in the MCP `env` block — a shell export does not
 
 ## Golden loops
 
-**Articles now:** `scrape` (or `batch_scrape`). `strategy: "auto"` already falls back to Botasaurus when configured — do not retry with explicit `default` after `auto`. Empty items can still be success; follow `next_step`.
+**Articles now:** `scrape` (or `batch_scrape`). Keep `strategy: "auto"` so html2rss can choose the available fetch path. Empty items can still be success; follow `next_step` instead of retrying with another strategy.
 
 **Durable YAML:** optional `inspect` → `recon` → `capture` → `test` → `apply`.
 
diff --git a/src/content/docs/ruby-gem/guides/backward-compatibility.mdx b/src/content/docs/ruby-gem/guides/backward-compatibility.mdx
index 13bdeda0..8de5059b 100644
--- a/src/content/docs/ruby-gem/guides/backward-compatibility.mdx
+++ b/src/content/docs/ruby-gem/guides/backward-compatibility.mdx
@@ -7,12 +7,6 @@ import { Code } from "@astrojs/starlight/components";
 
 This page outlines breaking changes, purged legacy aliases, and migration steps when upgrading the gem.
 
-## 0.30.0 (Unreleased)
-
-1. **Default HTTP strategy (`:default`)** — Migrated from Faraday to HTTPX. The canonical strategy name across configs, CLI, Ruby API, and MCP is `:default`.
-2. **Deprecated strategy aliases** — `:faraday` and `:httpx` remain accepted as aliases for `:default` with deprecation warnings. Update configurations and scripts to `strategy: default` (or `strategy: auto`).
-3. **HTTP/2 & SSRF protection** — The default transport provides native HTTP/2 multiplexing via ALPN and enforced private-network IP filtering.
-
 ## 0.27.0
 
 Upgrade notes for configs and integrators targeting gem **0.27.0** (current `master` after `0.26.0`):
diff --git a/src/content/docs/ruby-gem/guides/capturing-feed-configs.mdx b/src/content/docs/ruby-gem/guides/capturing-feed-configs.mdx
index bcd64832..3f6ffb0a 100644
--- a/src/content/docs/ruby-gem/guides/capturing-feed-configs.mdx
+++ b/src/content/docs/ruby-gem/guides/capturing-feed-configs.mdx
@@ -29,9 +29,6 @@ Print YAML to stdout:
 <Code
   code={`
   html2rss capture https://example.com/articles
-  # Pin Botasaurus for JS-rendered listings
-  BOTASAURUS_SCRAPER_URL="http://localhost:4010" \\
-  html2rss capture https://example.com/articles --strategy botasaurus
   # Hint the item card when auto detection is weak
   html2rss capture https://example.com/articles --items_selector ".post-card"
   # Analyze a local HTML fixture
@@ -46,7 +43,7 @@ Print YAML to stdout:
 
 Common options:
 
-- `--strategy` — `auto`, `default`, `botasaurus`, or `local_file` (default `auto`)
+- `--strategy` — request strategy override; defaults to `auto` (see [Strategy](/ruby-gem/reference/strategy/))
 - `--items_selector` — CSS selector hint for item cards
 - `--limit` — maximum articles kept while deriving selectors (default `25`)
 - `--max-redirects` / `--max-requests` — request budget overrides
@@ -62,10 +59,9 @@ See the [CLI reference](/ruby-gem/reference/cli-reference/#capture) for the full
   require 'html2rss'
   # Derive a config hash (channel + items selector with enhance: true)
   config = Html2rss.capture('https://example.com/articles')
-  # Pin strategy or provide an items hint
+  # Provide an item-card hint when automatic detection is weak
   config = Html2rss.capture(
-    'https://spa-site.com',
-    strategy: :botasaurus,
+    'https://example.com/articles',
     items_selector: '.article-card'
   )
   File.write('my-feed.yml', Html2rss::Config.to_yaml(config))
@@ -76,11 +72,11 @@ See the [CLI reference](/ruby-gem/reference/cli-reference/#capture) for the full
 
 ## How It Works
 
-1. **Request** — `FeedPipeline` (AutoFallback when `:auto`)
+1. **Request** — fetch the page using the configured strategy (`auto` by default)
 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. When AutoFallback selects a concrete transport (or you pin one), Capture **stamps** `strategy:` into the YAML so later `html2rss apply` / `Html2rss.feed` replay the same transport.
+5. **Assemble** — `{ items: { selector:, enhance: true } }` plus channel. Capture records the selected strategy when the draft needs to reproduce that fetch behavior during `html2rss apply` / `Html2rss.feed`.
 
 When the quality gate fails, selectors are omitted (`has_selectors: false`) rather than inventing attribute selectors. Hint with `--items_selector` or refine by hand.
 
@@ -99,7 +95,7 @@ MCP `capture` returns that YAML in `payload.yaml`. `validate` / `apply` accept t
 
 1. Validate: `html2rss validate my-feed.yml`
 2. Render: `html2rss apply my-feed.yml`
-3. Tighten the items selector, strategy, or `request.botasaurus` options if needed
+3. Tighten the items selector if needed; keep `auto` unless diagnosis proves a fixed fetch mode is required
 4. For Feed Directory contributions, add `directory.topics` and keep `enhance: true` unless chrome leaks (see [Creating Custom Feeds](/creating-custom-feeds/#sharing-your-config))
 
 ## Related
diff --git a/src/content/docs/ruby-gem/guides/handling-dynamic-content.mdx b/src/content/docs/ruby-gem/guides/handling-dynamic-content.mdx
index 44c6ec3a..984f5348 100644
--- a/src/content/docs/ruby-gem/guides/handling-dynamic-content.mdx
+++ b/src/content/docs/ruby-gem/guides/handling-dynamic-content.mdx
@@ -9,9 +9,9 @@ Some websites load their content dynamically using JavaScript. Static fetch path
 
 ## Solution
 
-Default `strategy: auto` automatically tries `default` first, then falls back to `botasaurus` when `BOTASAURUS_SCRAPER_URL` is configured. This handles many JS-rendered listing pages without needing custom configuration.
+Keep the default `strategy: auto` and configure `BOTASAURUS_SCRAPER_URL`. html2rss can then choose an available fetch path based on the scrape result, which handles many JavaScript-rendered listing pages without per-feed strategy configuration.
 
-When a site requires browser rendering or anti-bot bypass by default, you can explicitly set `strategy: botasaurus` and configure request controls under `request.botasaurus`:
+If a site still needs browser-specific navigation, waits, or scrolling, pin `strategy: botasaurus` and configure those advanced controls under `request.botasaurus`:
 
 <Code
   code={`
@@ -92,7 +92,7 @@ Configure browser actions under `request.botasaurus`:
 
 ### JSON Loaded Over XHR
 
-When Botasaurus uses the browser tier, captured JSON XHR/fetch bodies feed AutoSource `xhr_articles` automatically (enabled by default). Prefer `strategy: botasaurus` (or `auto` with `BOTASAURUS_SCRAPER_URL`) for SPA listing pages that hydrate article lists over the network rather than embedding them in HTML. See [Auto Source](/ruby-gem/reference/auto-source/) and [Strategy](/ruby-gem/reference/strategy/#botasaurus).
+Browser-rendered fetches can pass captured JSON XHR/fetch bodies to AutoSource `xhr_articles` automatically (enabled by default). With the companion scraper configured, keep `auto` for SPA listing pages that hydrate article lists over the network; pin `botasaurus` only when you need its browser-specific controls. See [Auto Source](/ruby-gem/reference/auto-source/) and [Strategy](/ruby-gem/reference/strategy/#botasaurus).
 
 ## Performance Considerations
 
@@ -102,7 +102,7 @@ Browser-based extraction uses more resources than static HTTP fetching because i
 - Executes JavaScript and handles DOM events
 - Manages browser pools and network emulation
 
-Use static HTTP fetching (`default`) for static content, and lean on `auto` or explicit `botasaurus` strategies when browser rendering is required. See the [Strategy Reference](/ruby-gem/reference/strategy/) for details.
+Keep `auto` for normal use. Pin a concrete strategy only when diagnosing a site or configuring browser-specific behavior. See the [Strategy Reference](/ruby-gem/reference/strategy/) for details.
 
 ## Related Topics
 
diff --git a/src/content/docs/ruby-gem/reference/auto-source.mdx b/src/content/docs/ruby-gem/reference/auto-source.mdx
index d8be1f06..1712667f 100644
--- a/src/content/docs/ruby-gem/reference/auto-source.mdx
+++ b/src/content/docs/ruby-gem/reference/auto-source.mdx
@@ -35,7 +35,7 @@ What each scraper does:
 - **`microdata`:** Extracts HTML Microdata annotations (`itemscope itemtype`).
 - **`microformats2`:** Parses Microformats2 `h-entry` markup, extracting `p-name`, `e-content`, `u-url`, `dt-published`, `p-author`, `p-category`, and `u-photo` / `u-featured` media.
 - **`json_state`:** Walks in-page JSON (`<script type="application/json">`, `window.__NEXT_DATA__`, `window.__NUXT__`, `window.STATE`) for arrays with `title`/`url` pairs.
-- **`xhr_articles`:** Reuses JSON XHR/fetch bodies captured during a Botasaurus **browser** scrape (no extra HTTP). Empty for default HTTP and Botasaurus HTTP-request tiers.
+- **`xhr_articles`:** Reuses JSON XHR/fetch bodies captured during browser execution (no extra request). It is empty when the selected fetch path does not capture browser responses.
 - **`wordpress_api`:** Detects `<link rel="https://api.w.org/">` and pulls posts from the REST API. See [WordPress API](/ruby-gem/reference/wordpress-api/).
 - **`sitemap`:** Locates XML sitemaps (`<link rel="sitemap">`, `/sitemap.xml`, or `/robots.txt`), filtering by priority and recency, with Google News tags (`<news:news>`).
 - **`meta_oembed`:** OpenGraph/Twitter meta tags plus JSON oEmbed (`<link rel="alternate" type="application/json+oembed">`).
diff --git a/src/content/docs/ruby-gem/reference/cli-reference.mdx b/src/content/docs/ruby-gem/reference/cli-reference.mdx
index ef513d34..7d10e9f2 100644
--- a/src/content/docs/ruby-gem/reference/cli-reference.mdx
+++ b/src/content/docs/ruby-gem/reference/cli-reference.mdx
@@ -37,7 +37,7 @@ Command: `html2rss scrape [URL]`
 
 Available options:
 
-- `--strategy`: Optional request strategy (`auto`, `default`, `botasaurus`, `local_file`). Defaults to `auto`, which tries `default` -> `botasaurus`. Legacy names `faraday` and `httpx` are accepted as aliases with a deprecation warning.
+- `--strategy`: Optional request strategy (`auto`, `default`, `botasaurus`, `local_file`). Defaults to `auto`, which chooses an available fetch path based on scrape results. Use a concrete value only for diagnosis or strategy-specific controls.
 - `--format`: Output format for the auto-sourced feed (`rss` or `jsonfeed`). Defaults to `rss`.
 - `--limit`: Maximum number of articles to extract during discovery (defaults to `25`).
 - `--items_selector`: Optional CSS selector hint for item extraction.
@@ -76,11 +76,11 @@ When no extractable items are found, `scrape` classifies likely causes instead o
 
 Known anti-bot interstitial responses (for example Cloudflare challenge pages) are surfaced explicitly as blocked-surface errors.
 
-If all fallback tiers run but still extract zero items, html2rss raises:
+If `auto` exhausts the available fetch paths without items, html2rss raises:
 
 - `No RSS feed items extracted after auto fallback ...`
 
-If failures continue after URL/surface fixes, ensure `BOTASAURUS_SCRAPER_URL` is set so the `auto` Botasaurus tier can run.
+If failures continue after URL/surface fixes, ensure `BOTASAURUS_SCRAPER_URL` is set so `auto` can use the companion scraper.
 
 Start by changing the input URL to a direct listing/update page, then move to explicit selectors if needed.
 
@@ -158,7 +158,7 @@ Available options:
 - `--input`: Local HTML file path to read input from without making network requests.
 - `--explain`: Print capture quality JSON to stderr (`articles_count`, `channel_title`, `has_selectors`, `segment_strategy`, `selected_strategy`, `admission_drops`). Stdout stays YAML.
 
-When AutoFallback (or a pinned strategy) selects a concrete transport, the printed YAML includes a top-level `strategy:` so later `html2rss apply` uses the same hop.
+When capture needs a fixed fetch mode to reproduce its result, the printed YAML includes a top-level `strategy:` so later `html2rss apply` uses the same mode.
 
 ### MCP
 
diff --git a/src/content/docs/ruby-gem/reference/configuration.mdx b/src/content/docs/ruby-gem/reference/configuration.mdx
index ddb73feb..2ed14a38 100644
--- a/src/content/docs/ruby-gem/reference/configuration.mdx
+++ b/src/content/docs/ruby-gem/reference/configuration.mdx
@@ -16,7 +16,6 @@ Global configuration is thread-safe and implements an RCU (Read-Copy-Update) mec
 Html2rss.configure do |config|
 config.log_level = :info
 config.min_ttl = 60
-config.default_strategy = :default
 config.headers = { 'User-Agent' => 'MyCustomUserAgent/1.0' }
 end
 `}
@@ -76,15 +75,15 @@ Defines HTTP headers that are globally appended/prepended to all requests. You c
 
 ### `default_strategy`
 
-Sets the default scraper strategy name used when a feed configuration doesn't specify a `strategy`. The strategy name must correspond to a registered strategy.
+Overrides the strategy used when a feed configuration does not specify one. Keep the gem default (`auto`) unless every feed in the process requires a fixed fetch mode.
 
 - **Type**: `Symbol`, `String`, or `nil`
-- **Default**: `nil` (falls back to the gem default strategy, usually `auto`)
+- **Default**: `nil` (uses `auto`)
 
 <Code
   code={`
   Html2rss.configure do |config|
-    config.default_strategy = :default
+    config.default_strategy = :auto
   end
   `}
   lang="ruby"
diff --git a/src/content/docs/ruby-gem/reference/mcp-server.mdx b/src/content/docs/ruby-gem/reference/mcp-server.mdx
index 10d13d91..10efb059 100644
--- a/src/content/docs/ruby-gem/reference/mcp-server.mdx
+++ b/src/content/docs/ruby-gem/reference/mcp-server.mdx
@@ -28,9 +28,9 @@ Daemon logs go to **stderr** (stdout is JSON-RPC). Default `LOG_LEVEL` for the M
 
 ## Strategy
 
-`scrape` and `capture` with `strategy: "auto"` run default (HTTPX) → Botasaurus AutoFallback in one call. Prefer native RSS/Atom when present; weak homepage URLs may be rewritten via entry resolution.
+`scrape` and `capture` use `strategy: "auto"` by default so html2rss can choose an available fetch path from the scrape result. Prefer native RSS/Atom when present; weak homepage URLs may be rewritten via entry resolution.
 
-`inspect` with `auto` stays on the default HTTP strategy. Pin `strategy: "botasaurus"` when inspect needs browser rendering.
+Keep `auto` for normal use. Pin `strategy: "botasaurus"` only when a diagnostic requires browser rendering or browser-specific controls.
 
 Read `html2rss://runtime` for `botasaurus_configured` (boolean only). Set `BOTASAURUS_SCRAPER_URL` on the **MCP process** env.
 
diff --git a/src/content/docs/ruby-gem/reference/strategy.mdx b/src/content/docs/ruby-gem/reference/strategy.mdx
index c4f8ed69..a06b95d5 100644
--- a/src/content/docs/ruby-gem/reference/strategy.mdx
+++ b/src/content/docs/ruby-gem/reference/strategy.mdx
@@ -1,27 +1,23 @@
 ---
 title: Strategy
-description: "Learn how html2rss chooses request strategies by default with auto fallback, and when to override with default, botasaurus, or local_file."
+description: "Use auto for normal scraping, or choose a fixed request strategy for diagnosis, browser controls, and local fixtures."
 ---
 
 import { Code } from "@astrojs/starlight/components";
 
 The `strategy` key defines how `html2rss` fetches a website's content.
 
-- **`auto`** (default): Tries concrete strategies in order: `default` -> `botasaurus`.
-- **`default`**: Makes a direct HTTP request (powered by HTTPX). Fast and non-blocking with native HTTP/2, connection pooling, and SSRF protection. Does not execute JavaScript.
-- **`botasaurus`**: Delegates fetching to a Botasaurus scrape API. Included in the `auto` chain; requires `BOTASAURUS_SCRAPER_URL` when that tier runs (or when you pin `strategy: botasaurus`).
+- **`auto`** (default): Chooses from the available fetch paths based on scrape results. Use this for normal scraping.
+- **`default`**: Makes a direct request without executing JavaScript. Use it only when you need a fixed request mode.
+- **`botasaurus`**: Uses the companion scraper for browser rendering and browser-specific controls. Requires `BOTASAURUS_SCRAPER_URL`.
 - **`local_file`**: Reads HTML content directly from a local file on disk without making network requests.
 
 `strategy` is a top-level config key. Request-specific controls live under `request`.
 
-`auto` falls back to `botasaurus` when `default` errors or extracts zero items. Pin a concrete strategy when you need a specific transport (for example, forcing `botasaurus` directly).
+`auto` is the recommended interface: html2rss evaluates the scrape result and can use the configured companion scraper when needed. Pin a concrete strategy only for diagnosis, reproducibility, or strategy-specific controls.
 
 ## `auto` (default)
 
-The default strategy chain is:
-
-`default` -> `botasaurus`
-
 When the config uses `auto_source` (no custom `selectors`), each strategy attempt:
 
 1. Runs AutoSource scrapers, starting with `native_feed` for same-origin RSS/Atom (direct feed URLs parse without HTML AutoSource).
@@ -31,30 +27,22 @@ Gates, defaults, and Status fields: [Auto Source — Entry URL resolution](/ruby
 
 Auto fallback shares one request budget across all strategy attempts. The baseline reserves a NativeFeed follow-up slot and, when entry resolution is enabled, `max_probes` probe slots plus one retry GET. Raise `request.max_requests` (or `--max-requests`) when builds exhaust the budget.
 
-Under `auto`, `Html2rss.feed_result(...).status` exposes scrape telemetry: `selected_strategy`, `attempt_count`, `strategy_attempts`, and when resolution ran `entry_url`, `scrape_url`, and `entry_resolution` (see [Managing Feed Configs](/ruby-gem/guides/managing-feed-configs/#ruby-api-feedresult)). Auto fallback decisions are also visible at `LOG_LEVEL=info` (hidden at the default `LOG_LEVEL=warn`).
+Under `auto`, `Html2rss.feed_result(...).status` exposes scrape telemetry: `selected_strategy`, `attempt_count`, `strategy_attempts`, and when resolution ran `entry_url`, `scrape_url`, and `entry_resolution` (see [Managing Feed Configs](/ruby-gem/guides/managing-feed-configs/#ruby-api-feedresult)). Strategy selection is also visible at `LOG_LEVEL=info` (hidden at the default `LOG_LEVEL=warn`).
 
 ## `default`
 
-`default` is the standard static HTTP transport, powered by HTTPX. When no custom `User-Agent` header is supplied in `headers`, `html2rss` sends `html2rss/<VERSION>` by default.
-
-It features:
-
-- **HTTP/2 & HTTP/1.1**: Automatic ALPN negotiation and multiplexed connection pooling.
-- **SSRF protection**: Native private-network IP filtering and redirect validation.
-- **Resilient decoding**: HTML is accepted when `Content-Type` includes `text/html`, or when the body sniffs as HTML (`<!DOCTYPE html` / `<html`) and the response is not JSON. Gzip, deflate, and brotli streams are decoded automatically.
+`default` is the fixed direct-request mode. It does not execute JavaScript. Keep `auto` unless you are diagnosing fetch behavior or must prevent browser rendering.
 
-:::note
-Legacy names `faraday` and `httpx` are accepted as aliases for `default` and emit a deprecation warning.
-:::
+When no custom `User-Agent` header is supplied in `headers`, html2rss sends `html2rss/<VERSION>`. The shared request policy enforces redirect, request, timeout, and private-network safeguards and accepts supported compressed HTML responses.
 
 ## `botasaurus`
 
-`botasaurus` delegates page fetching to a Botasaurus scrape API endpoint. It runs as the second tier of `auto`, or when you pin `strategy: botasaurus`.
+`botasaurus` delegates page fetching to the companion scrape API. `auto` can use it when configured; pin `strategy: botasaurus` only when you need browser-specific behavior.
 
 Requirements:
 
 - `BOTASAURUS_SCRAPER_URL` set to your Botasaurus scrape API base URL (for example `http://localhost:4010`)
-- pin `strategy: botasaurus` when you want to skip the default HTTP tier and force browser rendering directly
+- pin `strategy: botasaurus` only when you need to force browser rendering or configure the controls below
 
 html2rss enforces local request policy preflight and a feed-build timeout budget. The Botasaurus scrape API splits **total** scrape time (queue, boot, navigate, wait) from **work** time (navigate, selector wait, and scroll after the browser is ready). Feed YAML `wait_timeout_seconds` is validated against the work cap (`1..30` by default); the gem forwards `request.botasaurus` options to the scrape API without shrinking retries or waits to fit a remaining feed budget. Transport timeout for POST `/scrape` is the lesser of the remaining feed-build budget and `BOTASAURUS_SCRAPE_TIMEOUT_SECONDS` plus a small buffer (default **45s** scrape total, **47s** transport cap).
 
diff --git a/src/content/docs/troubleshooting/troubleshooting.mdx b/src/content/docs/troubleshooting/troubleshooting.mdx
index 5f4cba7d..64b31c3b 100644
--- a/src/content/docs/troubleshooting/troubleshooting.mdx
+++ b/src/content/docs/troubleshooting/troubleshooting.mdx
@@ -56,9 +56,9 @@ If your feed is empty, check the following:
 
 Known anti-bot interstitial patterns (for example Cloudflare or DataDome challenge pages) are surfaced as blocked-surface errors instead of silent empty extraction results.
 
-When all auto fallback tiers complete but still extract zero items, html2rss raises `No RSS feed items extracted after auto fallback ...`.
+When `auto` exhausts the available fetch paths without items, html2rss raises `No RSS feed items extracted after auto fallback ...`.
 
-If failures continue after URL/surface fixes, configure `BOTASAURUS_SCRAPER_URL` or use `--strategy botasaurus` for browser rendering.
+If failures continue after URL/surface fixes, configure `BOTASAURUS_SCRAPER_URL` so `auto` can use the companion scraper. Pin `--strategy botasaurus` only for browser-specific diagnosis or controls.
 
 ### DataDome And Similar Challenges
 
@@ -95,8 +95,8 @@ Then run with:
 
 Common configuration-related errors:
 
-- **`UnsupportedResponseContentType`:** The website returned content that html2rss can't parse (not HTML or JSON). The default HTTP strategy still treats bodies that sniff as HTML (`<!DOCTYPE html` / `<html`) as HTML, and decodes gzip/brotli even when `Content-Encoding` is missing.
-- **`UnsupportedStrategy`:** The specified strategy is not available. Use `auto`, `default`, `botasaurus`, or `local_file` (`faraday` and `httpx` are accepted as legacy aliases).
+- **`UnsupportedResponseContentType`:** The website returned content that html2rss cannot parse (not HTML or JSON). Supported compressed HTML and bodies that clearly identify themselves as HTML are accepted even when response headers are incomplete.
+- **`UnsupportedStrategy`:** The specified strategy is not available. Use `auto`, `default`, `botasaurus`, or `local_file`. Prefer `auto` unless you need a fixed mode.
 - **`BOTASAURUS_SCRAPER_URL is required for strategy=botasaurus.`:** Set `BOTASAURUS_SCRAPER_URL` to your Botasaurus scrape API base URL when using `--strategy botasaurus`.
 - **`BOTASAURUS_SCRAPER_URL is invalid`:** Fix the URL format and retry.
 - **`Configuration must include at least 'selectors' or 'auto_source'`:** You need to specify either manual selectors or enable auto-source.
@@ -109,7 +109,7 @@ If parts of your items (e.g., title, link) are missing, check the following:
 
 - **Selector:** Ensure the selector for the missing part is correct and relative to the `items.selector`.
 - **Extractor:** Verify that you are using the correct `extractor` (e.g., `text`, `href`, `attribute`).
-- **Dynamic Content:** `default` does not render JavaScript. If content loads dynamically, configure `BOTASAURUS_SCRAPER_URL` or run with `--strategy botasaurus` so the page can be rendered before extraction.
+- **Dynamic Content:** Configure `BOTASAURUS_SCRAPER_URL` and keep `auto` so html2rss can render the page when needed. Pin `--strategy botasaurus` only for browser-specific diagnosis or controls.
 
 ### Date/Time Parsing Errors
 
diff --git a/src/content/docs/web-application/concepts.mdx b/src/content/docs/web-application/concepts.mdx
index beefa085..18e8d282 100644
--- a/src/content/docs/web-application/concepts.mdx
+++ b/src/content/docs/web-application/concepts.mdx
@@ -13,7 +13,7 @@ Production Docker Compose defaults `AUTO_SOURCE_ENABLED` to `true`. Non-compose
 
 ## Botasaurus companion
 
-`html2rss-web` talks to `botasaurus-scrape-api` at `BOTASAURUS_SCRAPER_URL` (Compose sets `http://botasaurus:4010`). That service renders JavaScript-heavy pages when default HTTP fetching alone is not enough. Auto-source uses the default HTTP strategy (HTTPX) first, then Botasaurus when configured.
+`html2rss-web` talks to the companion scraper at `BOTASAURUS_SCRAPER_URL` (Compose sets `http://botasaurus:4010`). With that service configured, auto-source can choose browser rendering for JavaScript-heavy pages when the scrape result requires it.
 
 ## Three tokens (plain English)
 
@@ -27,13 +27,9 @@ Generate secrets with `openssl rand -hex 32`. Demo quickstart hard-codes `CHANGE
 
 Optional: `SENTRY_DSN` (web) and `BOTASAURUS_SENTRY_DSN` (scraper) for error reporting. They are separate projects; leave both unset until you want monitoring.
 
-## Server & async reactor
-
-`html2rss-web` runs on the Falcon application server, an asynchronous fiber-based server supporting HTTP/1.1 and HTTP/2. Falcon cooperates with HTTPX for non-blocking upstream I/O and coalesces concurrent feed requests in memory to prevent cache stampedes.
-
 ## HTTP vs HTTPS
 
-Plain HTTP works on localhost and LAN. The app sets HSTS and CSP `upgrade-insecure-requests` only when the request is HTTPS (including when a reverse proxy sends `X-Forwarded-Proto: https`). For public TLS, put Caddy, Nginx, or Traefik in front, or configure direct in-process TLS with Falcon.
+Plain HTTP works on localhost and LAN. The app sets HSTS and CSP `upgrade-insecure-requests` only when the request is HTTPS (including when a reverse proxy sends `X-Forwarded-Proto: https`). For public TLS, put Caddy, Nginx, or Traefik in front.
 
 ## Ecosystem map
 
diff --git a/src/content/docs/web-application/deployment.mdx b/src/content/docs/web-application/deployment.mdx
index 9b64a116..d32230dd 100644
--- a/src/content/docs/web-application/deployment.mdx
+++ b/src/content/docs/web-application/deployment.mdx
@@ -79,18 +79,6 @@ Example `.env` beside Compose:
 
 After `docker compose up -d`, check `docker compose logs caddy --tail 20` for certificate issuance.
 
-### Direct TLS termination (Falcon)
-
-Falcon also supports in-process TLS termination and HTTP/2 negotiation by pointing to your certificate and private key:
-
-<Code
-  code={`
-  TLS_CERTIFICATE_PATH=/path/to/fullchain.pem
-  TLS_KEY_PATH=/path/to/privkey.pem
-`}
-  lang="dotenv"
-/>
-
 ## Custom feeds mount
 
 Auto-source is the default. To add curated YAML feeds, bind-mount `feeds.yml` (see [Advanced Feeds](/creating-custom-feeds/)):
diff --git a/src/content/docs/web-application/reference/env-variables.mdx b/src/content/docs/web-application/reference/env-variables.mdx
index 8218226f..82c9712d 100644
--- a/src/content/docs/web-application/reference/env-variables.mdx
+++ b/src/content/docs/web-application/reference/env-variables.mdx
@@ -24,10 +24,8 @@ description: "Configuration reference for html2rss-web environment variables."
 | `RETRY_AFTER_TIMEOUT_SECONDS`            | optional integer `>= 1`; default `300`; Retry-After header backoff duration returned on timeouts                                                             |
 | `PORT`                                   | app listen port; compose uses `4000`                                                                                                                         |
 | `RACK_ENV`                               | Rack environment; quickstart uses `development`, production examples use `production`                                                                        |
-| `REQUEST_TIMEOUT_SECONDS`                | optional; total web-request timeout in seconds on the Falcon server; default `55`                                                                            |
-| `WEB_CONCURRENCY`                        | optional integer `>= 1`; default `2` in production (`1` in development); number of Falcon worker processes                                                   |
-| `TLS_CERTIFICATE_PATH`                   | optional; path to certificate file (e.g. `fullchain.pem`) for direct in-process Falcon TLS termination                                                       |
-| `TLS_KEY_PATH`                           | optional; path to private key file (e.g. `privkey.pem`) for direct in-process Falcon TLS termination                                                         |
+| `REQUEST_TIMEOUT_SECONDS`                | optional; total web-request timeout in seconds; default `55`                                                                                                 |
+| `WEB_CONCURRENCY`                        | optional integer `>= 1`; default `2` in production (`1` in development); number of web worker processes                                                      |
 | `BOTASAURUS_SCRAPE_TIMEOUT_SECONDS`      | optional; HTTP client cap for POST `/scrape` in seconds; default `45`; mirrors `SCRAPE_TIMEOUT_SECONDS` on botasaurus-scrape-api                             |
 | `BOTASAURUS_SCRAPE_WORK_TIMEOUT_SECONDS` | optional; maximum `wait_timeout_seconds` in feed YAML; default `30`; mirrors `SCRAPE_WORK_TIMEOUT_SECONDS` on botasaurus-scrape-api                          |
 | `SCRAPE_WORK_TIMEOUT_SECONDS`            | optional on botasaurus-scrape-api; post-boot navigate, selector wait, and scroll budget in seconds; default `30`; set on the scraper service in compose      |
@@ -37,13 +35,13 @@ description: "Configuration reference for html2rss-web environment variables."
 
 When fetching feeds from complex websites, multiple components work together. Configure timeouts so outer layers wait longer than inner layers and the scraper exhausts its budget before the web tier aborts the request.
 
-Default compose aligns **scrape total (45) ≤ feed build (50) ≤ Falcon request timeout (55)**. The **work** budget (**30s**) applies on botasaurus-scrape-api only after the browser is ready; browser boot and queue time count against the **total** scrape wall (**45s**), not against `wait_timeout_seconds`.
+Runtime defaults align **scrape total (45) ≤ feed build (50) ≤ web request timeout (55)**. The **work** budget (**30s**) applies on botasaurus-scrape-api only after the browser is ready; browser boot and queue time count against the **total** scrape wall (**45s**), not against `wait_timeout_seconds`.
 
 1. **botasaurus-scrape-api (`SCRAPE_TIMEOUT_SECONDS`)**: **45s** handler wall (queue, boot, navigate, wait).
 2. **botasaurus-scrape-api (`SCRAPE_WORK_TIMEOUT_SECONDS`)**: **30s** post-boot navigate, `wait_for_selector`, and scroll.
-3. **html2rss client (`BOTASAURUS_SCRAPE_TIMEOUT_SECONDS`)**: **45s** HTTPX cap for POST `/scrape` (mirrors scrape total).
+3. **html2rss client (`BOTASAURUS_SCRAPE_TIMEOUT_SECONDS`)**: **45s** client cap for POST `/scrape` (mirrors scrape total).
 4. **Feed YAML (`wait_timeout_seconds`)**: **1..30**, capped by `BOTASAURUS_SCRAPE_WORK_TIMEOUT_SECONDS` (default **30**).
 5. **html2rss-web gem budget (`HTML2RSS_TOTAL_TIMEOUT_SECONDS`)**: **50s** for scrape plus extraction.
-6. **html2rss-web (`REQUEST_TIMEOUT_SECONDS`)**: **55s** Falcon outer wall.
+6. **html2rss-web (`REQUEST_TIMEOUT_SECONDS`)**: **55s** outer web-request wall.
 
-Set matching `SCRAPE_*` on botasaurus-scrape-api and `BOTASAURUS_SCRAPE_*` on html2rss-web when you override defaults. See the `Environment & Runtime Flags` table in [`docs/README.md`](https://github.com/html2rss/html2rss-web/blob/main/docs/README.md) for compose examples.
+Set matching `SCRAPE_*` on botasaurus-scrape-api and `BOTASAURUS_SCRAPE_*` on html2rss-web when you override defaults. Set `REQUEST_TIMEOUT_SECONDS` explicitly when changing the outer web-request wall. See the `Environment & Runtime Flags` table in [`docs/README.md`](https://github.com/html2rss/html2rss-web/blob/main/docs/README.md) for compose examples.

From 6cb6a5e6e774cc8fd2a3573baf03495e89ef9dca Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 6 Sep 2026 09:56:25 +0200
Subject: [PATCH 6/6] docs: correct strategy contract details

State capture persistence and MCP discovery behavior exactly as implemented while keeping compatibility aliases out of recommended user guidance. Use the runtime UnknownStrategy name in troubleshooting.
---
 src/content/docs/ruby-gem/guides/capturing-feed-configs.mdx | 2 +-
 src/content/docs/ruby-gem/reference/cli-reference.mdx       | 2 +-
 src/content/docs/ruby-gem/reference/mcp-server.mdx          | 2 +-
 src/content/docs/troubleshooting/troubleshooting.mdx        | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/content/docs/ruby-gem/guides/capturing-feed-configs.mdx b/src/content/docs/ruby-gem/guides/capturing-feed-configs.mdx
index 3f6ffb0a..3242e10d 100644
--- a/src/content/docs/ruby-gem/guides/capturing-feed-configs.mdx
+++ b/src/content/docs/ruby-gem/guides/capturing-feed-configs.mdx
@@ -76,7 +76,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. Capture records the selected strategy when the draft needs to reproduce that fetch behavior during `html2rss apply` / `Html2rss.feed`.
+5. **Assemble** — `{ items: { selector:, enhance: true } }` plus channel. Capture records the concrete strategy that produced the draft so `html2rss apply` / `Html2rss.feed` can reproduce that fetch path.
 
 When the quality gate fails, selectors are omitted (`has_selectors: false`) rather than inventing attribute selectors. Hint with `--items_selector` or refine by hand.
 
diff --git a/src/content/docs/ruby-gem/reference/cli-reference.mdx b/src/content/docs/ruby-gem/reference/cli-reference.mdx
index 7d10e9f2..9115faaa 100644
--- a/src/content/docs/ruby-gem/reference/cli-reference.mdx
+++ b/src/content/docs/ruby-gem/reference/cli-reference.mdx
@@ -158,7 +158,7 @@ Available options:
 - `--input`: Local HTML file path to read input from without making network requests.
 - `--explain`: Print capture quality JSON to stderr (`articles_count`, `channel_title`, `has_selectors`, `segment_strategy`, `selected_strategy`, `admission_drops`). Stdout stays YAML.
 
-When capture needs a fixed fetch mode to reproduce its result, the printed YAML includes a top-level `strategy:` so later `html2rss apply` uses the same mode.
+Capture records the concrete strategy that produced the draft as a top-level `strategy:` so later `html2rss apply` can reproduce that fetch path.
 
 ### MCP
 
diff --git a/src/content/docs/ruby-gem/reference/mcp-server.mdx b/src/content/docs/ruby-gem/reference/mcp-server.mdx
index 10efb059..7fa76123 100644
--- a/src/content/docs/ruby-gem/reference/mcp-server.mdx
+++ b/src/content/docs/ruby-gem/reference/mcp-server.mdx
@@ -120,7 +120,7 @@ Ship gate: build RSS from a config. Required `url` plus exactly one of `config`
 | ----------------------- | ------------------------------------------------------------------------------------------------------------------ |
 | `html2rss://schema`     | Feed config JSON Schema                                                                                            |
 | `html2rss://extractors` | Extractor names                                                                                                    |
-| `html2rss://strategies` | `auto`, `default`, `botasaurus` (not `local_file`)                                                                 |
+| `html2rss://strategies` | Runtime strategy names for client discovery; prefer `auto`, `default`, or `botasaurus`                             |
 | `html2rss://runtime`    | `version`, `mcp_contract_version`, `catalog_fingerprint`, `tools`, `botasaurus_configured` — never the scraper URL |
 
 `validate` / `apply` reject `strategy: local_file` and `request.local_file_path`. Use CLI `--input` for fixtures.
diff --git a/src/content/docs/troubleshooting/troubleshooting.mdx b/src/content/docs/troubleshooting/troubleshooting.mdx
index 64b31c3b..f2cc4b23 100644
--- a/src/content/docs/troubleshooting/troubleshooting.mdx
+++ b/src/content/docs/troubleshooting/troubleshooting.mdx
@@ -96,7 +96,7 @@ Then run with:
 Common configuration-related errors:
 
 - **`UnsupportedResponseContentType`:** The website returned content that html2rss cannot parse (not HTML or JSON). Supported compressed HTML and bodies that clearly identify themselves as HTML are accepted even when response headers are incomplete.
-- **`UnsupportedStrategy`:** The specified strategy is not available. Use `auto`, `default`, `botasaurus`, or `local_file`. Prefer `auto` unless you need a fixed mode.
+- **`UnknownStrategy`:** The specified strategy is not available. Use `auto`, `default`, `botasaurus`, or `local_file`. Prefer `auto` unless you need a fixed mode.
 - **`BOTASAURUS_SCRAPER_URL is required for strategy=botasaurus.`:** Set `BOTASAURUS_SCRAPER_URL` to your Botasaurus scrape API base URL when using `--strategy botasaurus`.
 - **`BOTASAURUS_SCRAPER_URL is invalid`:** Fix the URL format and retry.
 - **`Configuration must include at least 'selectors' or 'auto_source'`:** You need to specify either manual selectors or enable auto-source.