From ee50864c9e29d28403c6434e4ae779bd6f1b0975 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 29 Aug 2026 11:00:35 +0200
Subject: [PATCH 1/5] docs(domain): document NativeFeed and entry_resolution
 for gem 0.28.0

Sync auto-source tiers and schema toggles with v0.27.2..HEAD (native RSS/Atom promotion + weak-entry tournament).
---
 .../docs/ruby-gem/reference/auto-source.mdx   | 34 +++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/src/content/docs/ruby-gem/reference/auto-source.mdx b/src/content/docs/ruby-gem/reference/auto-source.mdx
index 2007795c..213c8eef 100644
--- a/src/content/docs/ruby-gem/reference/auto-source.mdx
+++ b/src/content/docs/ruby-gem/reference/auto-source.mdx
@@ -22,6 +22,7 @@ To enable it, add `auto_source: {}` to your configuration:
 
 One fetch, then scrapers run in **tiers**. Within a tier, results merge. The pipeline stops when Cleanup has admitted enough articles (`limit`, default `25`).
 
+0. **Native syndication (tier 0):** `native_feed` — discovers same-origin RSS/Atom (`rel=alternate` plus common feed paths) and parses them before HTML heuristics. Direct feed entry URLs (Content-Type or body sniff) skip HTML AutoSource and parse immediately.
 1. **In-page structured:** `schema`, `microdata`, `microformats2`, `json_state`, `xhr_articles`
 2. **Follow-up IO:** `wordpress_api`, `sitemap`, `meta_oembed`
 3. **Heuristic:** `semantic_html`
@@ -29,6 +30,7 @@ One fetch, then scrapers run in **tiers**. Within a tier, results merge. The pip
 
 What each scraper does:
 
+- **`native_feed`:** Promotes native RSS/Atom when present so syndication wins before structured HTML scrapers. Tallies appear as `AutoSource::NativeFeed` under `--explain`.
 - **`schema`:** Parses `<script type="json/ld">` tags containing structured data (e.g., [Schema.org](https://schema.org/)), extracting authors and publishers.
 - **`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.
@@ -48,6 +50,20 @@ Drop reasons (counts) land on `Html2rss::Status#admission_drops`. Print them wit
 
 Ruby `limit:` and CLI `--limit` cap kept articles (default `25`).
 
+### Entry URL resolution
+
+Under `strategy: auto` with `auto_source` (no custom `selectors`), a weak homepage or hub extract can trigger an **entry URL tournament** before Botasaurus escalation. The pipeline probes same-origin listing and feed candidates, then sticky-rewrites the effective scrape URL only when a retry extract yields items.
+
+Resolution runs when enabled and the page is not a blocked surface, and any of:
+
+- fewer than 3 admitted articles, or
+- a weak surface (`high_entropy_surface`, `app_shell`, `unsupported_surface`), or
+- at least half of the articles came from `native_feed`
+
+Telemetry lands on `Html2rss::Status` as `entry_url` (pasted URL), `scrape_url` (effective fetch URL), and `entry_resolution` (`applied`, `probe_count`, `reason`, optional `winner_score`). `applied: true` means a tournament winner was picked; the sticky rewrite still requires a successful retry extract.
+
+Defaults: `entry_resolution.enabled: true`, `entry_resolution.max_probes: 5`. Disable with `enabled: false` when you want the pasted URL only.
+
 **`json_state` / `xhr_articles` Limitations:** both scrapers require discoverable arrays of hashes containing clear `title` and `url` fields. Minified or
 obfuscated payloads, heavily encoded values, or blobs that require executing embedded functions are ignored. `xhr_articles` only sees JSON bodies captured during the current Botasaurus browser scrape (capped by the scrape API).
 
@@ -67,6 +83,8 @@ Enable or disable specific scrapers and adjust their settings:
     url: https://example.com
   auto_source:
     scraper:
+      native_feed:
+        enabled: true # default: true; tier 0 RSS/Atom promotion
       wordpress_api:
         enabled: false # default: true
       sitemap:
@@ -97,6 +115,22 @@ Enable or disable specific scrapers and adjust their settings:
   lang="yaml"
 />
 
+### Entry Resolution Options
+
+Tune or disable the weak-entry tournament:
+
+<Code
+  code={`
+  channel:
+    url: https://example.com
+  auto_source:
+    entry_resolution:
+      enabled: true # default: true
+      max_probes: 5 # default: 5; exclusiveMinimum: 0
+  `}
+  lang="yaml"
+/>
+
 ### Cleanup Options
 
 Remove unwanted items from the results:

From dac4cc73e3aa78200b213b252ca9d1ca69e36fdf Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 29 Aug 2026 11:00:35 +0200
Subject: [PATCH 2/5] docs(infrastructure): document auto entry resolution and
 timeout_phase

Describe NativeFeed/entry-resolution steps in the auto chain, request-budget impact, and Botasaurus timeout_phase diagnostics.
---
 src/content/docs/ruby-gem/reference/strategy.mdx | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/src/content/docs/ruby-gem/reference/strategy.mdx b/src/content/docs/ruby-gem/reference/strategy.mdx
index af4fe810..4156335e 100644
--- a/src/content/docs/ruby-gem/reference/strategy.mdx
+++ b/src/content/docs/ruby-gem/reference/strategy.mdx
@@ -22,9 +22,16 @@ The default strategy chain is:
 
 `faraday` -> `botasaurus`
 
-Auto fallback shares one request budget across all strategy attempts. For pagination-heavy or dynamic pages, increase `request.max_requests` (or `--max-requests`) when retries exhaust the budget.
+Within each concrete strategy attempt that uses `auto_source` (no custom `selectors`), the extract path can:
 
-Under `auto`, `Html2rss.feed_result(...).status` exposes scrape telemetry: `selected_strategy`, `attempt_count`, and `strategy_attempts` (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`).
+1. Promote native RSS/Atom via the tier-0 `native_feed` scraper (or parse a direct feed URL).
+2. Run **entry URL resolution** on a weak homepage/hub extract — probe same-origin listing/feed candidates and sticky-rewrite the scrape URL only when the retry yields items — **before** escalating to Botasaurus.
+
+See [Auto Source](/ruby-gem/reference/auto-source/#entry-url-resolution) for gates, defaults (`entry_resolution.enabled: true`, `max_probes: 5`), and Status fields.
+
+Auto fallback shares one request budget across all strategy attempts. The baseline reserves slots for NativeFeed follow-up and entry-resolution probes (about **+7** requests when both defaults are on). For pagination-heavy or dynamic pages, increase `request.max_requests` (or `--max-requests`) when retries 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`).
 
 ## `faraday`
 
@@ -43,6 +50,8 @@ Requirements:
 
 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).
 
+When the scrape API reports a timed-out stage, `Html2rss::RequestService::RequestTimedOut` may carry `timeout_phase` as `queue`, `boot`, or `work` (also reflected in the exception message as `timeout_phase=<stage>`). Transport-hop timeouts leave `timeout_phase` unset.
+
 During the **browser** execution tier, the Botasaurus scrape API always captures JSON XHR/fetch response bodies (`xhr_responses`). html2rss forwards them as `Response#captured_responses` so AutoSource `xhr_articles` can extract articles without extra requests. The HTTP-request tier returns an empty capture list. Caps and filtering live in the scrape API (see its README); article-likeness filtering is a client concern.
 
 The client speaks OpenAPI 2.0 `ScrapeSuccess` / `ScrapeError` envelopes. Success requires an `html` string. Extra `request.botasaurus` keys fail YAML validation.

From a6a11364890dfb632b816cf3efa28e9884b71a69 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 29 Aug 2026 11:00:35 +0200
Subject: [PATCH 3/5] docs(adapters): sync MCP inspect payload and next_step
 for 0.28.0

Alternate feeds now route to scrape_url; document surface_category and nested sst fields for agents.
---
 .../docs/ruby-gem/guides/ai-agent-workflows.mdx        |  6 +++---
 src/content/docs/ruby-gem/reference/mcp-server.mdx     | 10 ++++++----
 2 files changed, 9 insertions(+), 7 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 c3064ce6..f280c1ba 100644
--- a/src/content/docs/ruby-gem/guides/ai-agent-workflows.mdx
+++ b/src/content/docs/ruby-gem/guides/ai-agent-workflows.mdx
@@ -84,16 +84,16 @@ Add `html2rss` to your Claude Desktop configuration (`~/Library/Application Supp
 
 When an agent needs articles immediately without saving a feed configuration:
 
-1. Call `scrape_url` with `strategy: "auto"`. Auto runs Faraday then Botasaurus when `BOTASAURUS_SCRAPER_URL` is set on the MCP process.
+1. Call `scrape_url` with `strategy: "auto"`. Auto runs Faraday then Botasaurus when `BOTASAURUS_SCRAPER_URL` is set on the MCP process, promotes native RSS/Atom when present, and may rewrite a weak homepage URL via entry resolution.
 2. An empty item list is still success for articles-now. Read `payload.items`. Follow `next_step` (including `read_runtime` / `html2rss://runtime` when Botasaurus is unset).
-3. Call `inspect_url` when the result is weak or you need recon (`final_url`, `status`, `scheme_downgrade`, native RSS/Atom).
+3. Call `inspect_url` when the result is weak or you need recon (`final_url`, `status`, `scheme_downgrade`, `alternate_feeds`, `surface_category`). If inspect reports alternate feeds, follow `next_step: scrape_url` — do not treat alternates as `done`.
 
 ### Pattern B: Iterative Feed Config Authoring
 
 When an agent is tasked with creating a durable YAML feed configuration:
 
 1. **Capture:** Call `capture_config`. YAML is `payload.yaml` (`items` + `enhance: true`). Check `payload.articles_count` and `has_selectors`.
-2. **Recon (optional):** Call `inspect_url` for `final_url`, `status`, `scheme_downgrade`, and `alternate_feeds` if the draft is weak.
+2. **Recon (optional):** Call `inspect_url` for `final_url`, `status`, `scheme_downgrade`, `alternate_feeds`, and `surface_category` if the draft is weak. Alternates mean call `scrape_url` next (native promotion), not stop.
 3. **Rewrite:** If the destination is html2rss-configs, add `directory.topics` and explicit channel `title`/`url`. Strive to keep `enhance: true` (set `false` only when chrome leaks into items).
 4. **Validate:** Pass `yaml` (or `config`) to `validate_config`. Exactly one of those arguments.
 5. **Apply:** Call `apply_config`. `isError` plus `payload.item_count: 0` means the config is not shippable — channel title in the XML is not success.
diff --git a/src/content/docs/ruby-gem/reference/mcp-server.mdx b/src/content/docs/ruby-gem/reference/mcp-server.mdx
index 193ec010..40c8a83d 100644
--- a/src/content/docs/ruby-gem/reference/mcp-server.mdx
+++ b/src/content/docs/ruby-gem/reference/mcp-server.mdx
@@ -38,9 +38,9 @@ The MCP server supports two transport mechanisms:
 
 ## Strategy Resolution in MCP
 
-`scrape_url` and `capture_config` with `strategy: "auto"` (the default) run Faraday → Botasaurus AutoFallback in one call.
+`scrape_url` and `capture_config` with `strategy: "auto"` (the default) run Faraday → Botasaurus AutoFallback in one call. That path also promotes native RSS/Atom when present and may run entry URL resolution on weak homepage/hub extracts (see [Auto Source](/ruby-gem/reference/auto-source/) and [Strategy](/ruby-gem/reference/strategy/#auto-default)).
 
-`inspect_url` with `auto` uses Faraday for a cheap diagnostic. Pin `strategy: "botasaurus"` when you need browser rendering for inspect.
+`inspect_url` with `auto` uses Faraday for a cheap diagnostic. Pin `strategy: "botasaurus"` when you need browser rendering for inspect. Inspect reports head `rel=alternate` feeds only — it does not path-guess `/feed`.
 
 Read `html2rss://runtime` for `botasaurus_configured` (boolean only). Set `BOTASAURUS_SCRAPER_URL` on the **MCP process** env (see [AI agent workflows](/ruby-gem/guides/ai-agent-workflows/)).
 
@@ -94,11 +94,13 @@ Diagnostic page analysis plus recon from the same fetch. `auto` uses Faraday; pi
   - `status`: HTTP status when the strategy reports one.
   - `scheme_downgrade`: `true` when the fetch went https → http.
   - `alternate_feeds`: `rel=alternate` RSS/Atom links from the document head (no `/feed` path guessing).
-  - `content_type` / `html_response` / `scraper_eligibility` / `sst_stats` / `sst.segment_stats`.
+  - `surface_category`: page surface class (for example listing vs weak/blocked surfaces).
+  - `content_type` / `html_response`.
+  - `sst`: nested `{ node_count, degraded, segment_stats }` when SST ran; `segment_stats` is also emitted at the top level when present.
   - `articles_count` and `admission_drops` when the response is HTML (Cleanup drop-reason counts).
   - `blocked_surface` when an interstitial signature is detected.
   - `xhr_capture` when the inspect strategy is `botasaurus` (`count`, redacted `sample_endpoints`, `candidate_articles`).
-- **next_step:** `done` when native alternate feeds exist, `capture_config` when articles were found, otherwise `scrape_url`.
+- **next_step:** `scrape_url` when head alternate feeds exist (runtime scrape consumes native alternates) or when no articles were found; `capture_config` when articles were found without alternates.
 
 ### `capture_config`
 

From 3464149826946a29debcbf41fed53d1b43a58c80 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 29 Aug 2026 11:00:35 +0200
Subject: [PATCH 4/5] docs(adapters): Status entry_resolution fields and 0.28.0
 upgrade notes

Document --explain / status.to_h entry_url scrape_url entry_resolution and additive migration bullets.
---
 .../ruby-gem/guides/backward-compatibility.mdx    | 15 ++++++++++++++-
 .../ruby-gem/guides/managing-feed-configs.mdx     |  2 +-
 .../docs/ruby-gem/reference/cli-reference.mdx     |  2 +-
 3 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/src/content/docs/ruby-gem/guides/backward-compatibility.mdx b/src/content/docs/ruby-gem/guides/backward-compatibility.mdx
index 1a69217b..ec807272 100644
--- a/src/content/docs/ruby-gem/guides/backward-compatibility.mdx
+++ b/src/content/docs/ruby-gem/guides/backward-compatibility.mdx
@@ -7,9 +7,22 @@ import { Code } from "@astrojs/starlight/components";
 
 This page outlines breaking changes, purged legacy aliases, and migration steps when upgrading the gem.
 
+## 0.28.0
+
+Upgrade notes for configs and integrators targeting gem **0.28.0** (current `master` after `0.27.2`):
+
+1. **`auto_source.scraper.native_feed`** — New tier-0 scraper (default `enabled: true`) promotes same-origin RSS/Atom before HTML heuristics. Direct feed URLs parse without HTML AutoSource. Disable with `enabled: false`.
+2. **`auto_source.entry_resolution`** — Weak homepage/hub extracts under `strategy: auto` may probe same-origin listing/feed candidates (defaults `enabled: true`, `max_probes: 5`) and sticky-rewrite the scrape URL only when the retry yields items. See [Auto Source](/ruby-gem/reference/auto-source/#entry-url-resolution).
+3. **`Status` / CLI `--explain`** — Optional `entry_url`, `scrape_url`, and `entry_resolution` (`applied`, `probe_count`, `reason`, optional `winner_score`). `applied: true` is a tournament win, not a guarantee the wire URL changed.
+4. **Request budget** — Default baseline reserves NativeFeed and entry-resolution slots (about +7 requests). Raise `request.max_requests` if builds hit the budget.
+5. **MCP `inspect_url`** — When `alternate_feeds` is present, `next_step` is `scrape_url` (was `done`). Payload adds `surface_category` and nests SST under `sst` (`node_count`, `degraded`, `segment_stats`); top-level `sst_stats` is gone.
+6. **`RequestTimedOut#timeout_phase`** — Optional `queue` / `boot` / `work` from Botasaurus scrape-API diagnostics (message may include `timeout_phase=<stage>`).
+
+Run `html2rss validate config.yml` after editing `auto_source` options.
+
 ## 0.27.0
 
-Upgrade notes for configs and integrators targeting gem **0.27.0** (current `master` after `0.26.0`):
+Upgrade notes for configs and integrators targeting gem **0.27.0** (after `0.26.0`):
 
 1. **MCP result envelope** — Every MCP tool returns `{ ok, next_step, guidance, payload }` in text and `structuredContent`. Read `payload.items`, `payload.yaml`, and `payload.rss`; scrape text is not a raw item array.
 2. **MCP AutoFallback** — `scrape_url` and `capture_config` with `strategy: "auto"` run Faraday → Botasaurus in one call. `inspect_url` with `auto` stays on Faraday (pin `botasaurus` when you need browser rendering for inspect).
diff --git a/src/content/docs/ruby-gem/guides/managing-feed-configs.mdx b/src/content/docs/ruby-gem/guides/managing-feed-configs.mdx
index e1a635f2..7853d538 100644
--- a/src/content/docs/ruby-gem/guides/managing-feed-configs.mdx
+++ b/src/content/docs/ruby-gem/guides/managing-feed-configs.mdx
@@ -76,7 +76,7 @@ Prefer `Html2rss.feed_result` when one scrape must render as both RSS and JSON F
 - `to_rss` / `to_json_feed(feed_url:)` — render formats
 - `status` — scrape telemetry (`Html2rss::Status`)
 
-`status.to_h` is the stable observability payload. Always includes `version` and `dedup_dropped`. When present, it may also include `scraper_tallies`, `selected_strategy`, `attempt_count`, `strategy_attempts` (auto-fallback attempts; empty outside `strategy: auto`), and `admission_drops` (Cleanup reason → count).
+`status.to_h` is the stable observability payload. Always includes `version` and `dedup_dropped`. When present, it may also include `scraper_tallies`, `selected_strategy`, `attempt_count`, `strategy_attempts` (auto-fallback attempts; empty outside `strategy: auto`), `admission_drops` (Cleanup reason → count), `entry_url` / `scrape_url` (pasted vs effective URL after entry resolution), and `entry_resolution` (`applied`, `probe_count`, `reason`, optional `winner_score`).
 
 For URL-only auto discovery, `Html2rss.auto_feed_result(url)` returns the same `FeedResult` (CLI `html2rss auto --explain` prints `status.to_h` on stderr).
 
diff --git a/src/content/docs/ruby-gem/reference/cli-reference.mdx b/src/content/docs/ruby-gem/reference/cli-reference.mdx
index c9f1675b..dae1b54b 100644
--- a/src/content/docs/ruby-gem/reference/cli-reference.mdx
+++ b/src/content/docs/ruby-gem/reference/cli-reference.mdx
@@ -44,7 +44,7 @@ Available options:
 - `--max-redirects`: Maximum redirects to follow per request.
 - `--max-requests`: Maximum requests to allow for this feed build (defaults to `4` for auto discovery).
 - `--input`: Local HTML file path to read input from without making network requests. When provided without a `URL`, `html2rss` attempts to detect the base URL from `<link rel="canonical">` or OpenGraph metadata in the HTML.
-- `--explain`: Print `Html2rss::Status` JSON to stderr (`version`, `dedup_dropped`, and when present `scraper_tallies`, `selected_strategy`, `attempt_count`, `strategy_attempts`, `admission_drops`). Stdout stays the RSS or JSON Feed.
+- `--explain`: Print `Html2rss::Status` JSON to stderr (`version`, `dedup_dropped`, and when present `scraper_tallies`, `selected_strategy`, `attempt_count`, `strategy_attempts`, `admission_drops`, `entry_url`, `scrape_url`, `entry_resolution`). Stdout stays the RSS or JSON Feed.
 
 #### URL Surface Guidance For `auto`
 

From ec2b3c29285c5af30ae7bdab8ba7d2d56e8e78bb Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 29 Aug 2026 11:09:43 +0200
Subject: [PATCH 5/5] docs(ruby-gem): proofread 0.28.0 sync without migration
 notes

Forward-facing rewrite of NativeFeed/entry-resolution/MCP Status docs; drop the temporary 0.28.0 backward-compat section and restore scraper_eligibility on inspect.
---
 .../ruby-gem/guides/ai-agent-workflows.mdx    |  6 +--
 .../guides/backward-compatibility.mdx         | 15 +-----
 .../ruby-gem/guides/managing-feed-configs.mdx |  7 ++-
 .../docs/ruby-gem/reference/auto-source.mdx   | 51 +++++++++----------
 .../docs/ruby-gem/reference/mcp-server.mdx    | 14 ++---
 .../docs/ruby-gem/reference/strategy.mdx      | 12 ++---
 6 files changed, 48 insertions(+), 57 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 f280c1ba..75926be7 100644
--- a/src/content/docs/ruby-gem/guides/ai-agent-workflows.mdx
+++ b/src/content/docs/ruby-gem/guides/ai-agent-workflows.mdx
@@ -84,16 +84,16 @@ Add `html2rss` to your Claude Desktop configuration (`~/Library/Application Supp
 
 When an agent needs articles immediately without saving a feed configuration:
 
-1. Call `scrape_url` with `strategy: "auto"`. Auto runs Faraday then Botasaurus when `BOTASAURUS_SCRAPER_URL` is set on the MCP process, promotes native RSS/Atom when present, and may rewrite a weak homepage URL via entry resolution.
+1. Call `scrape_url` with `strategy: "auto"`. Auto runs Faraday then Botasaurus when `BOTASAURUS_SCRAPER_URL` is set on the MCP process, prefers native RSS/Atom when present, and may rewrite a weak homepage URL via entry resolution.
 2. An empty item list is still success for articles-now. Read `payload.items`. Follow `next_step` (including `read_runtime` / `html2rss://runtime` when Botasaurus is unset).
-3. Call `inspect_url` when the result is weak or you need recon (`final_url`, `status`, `scheme_downgrade`, `alternate_feeds`, `surface_category`). If inspect reports alternate feeds, follow `next_step: scrape_url` — do not treat alternates as `done`.
+3. Call `inspect_url` when the result is weak or you need recon (`final_url`, `status`, `scheme_downgrade`, `alternate_feeds`, `surface_category`). Follow `next_step` — often `scrape_url` when `alternate_feeds` is present.
 
 ### Pattern B: Iterative Feed Config Authoring
 
 When an agent is tasked with creating a durable YAML feed configuration:
 
 1. **Capture:** Call `capture_config`. YAML is `payload.yaml` (`items` + `enhance: true`). Check `payload.articles_count` and `has_selectors`.
-2. **Recon (optional):** Call `inspect_url` for `final_url`, `status`, `scheme_downgrade`, `alternate_feeds`, and `surface_category` if the draft is weak. Alternates mean call `scrape_url` next (native promotion), not stop.
+2. **Recon (optional):** Call `inspect_url` for `final_url`, `status`, `scheme_downgrade`, `alternate_feeds`, and `surface_category` if the draft is weak. Follow `next_step` (often `scrape_url` when alternates are present).
 3. **Rewrite:** If the destination is html2rss-configs, add `directory.topics` and explicit channel `title`/`url`. Strive to keep `enhance: true` (set `false` only when chrome leaks into items).
 4. **Validate:** Pass `yaml` (or `config`) to `validate_config`. Exactly one of those arguments.
 5. **Apply:** Call `apply_config`. `isError` plus `payload.item_count: 0` means the config is not shippable — channel title in the XML is not success.
diff --git a/src/content/docs/ruby-gem/guides/backward-compatibility.mdx b/src/content/docs/ruby-gem/guides/backward-compatibility.mdx
index ec807272..1a69217b 100644
--- a/src/content/docs/ruby-gem/guides/backward-compatibility.mdx
+++ b/src/content/docs/ruby-gem/guides/backward-compatibility.mdx
@@ -7,22 +7,9 @@ import { Code } from "@astrojs/starlight/components";
 
 This page outlines breaking changes, purged legacy aliases, and migration steps when upgrading the gem.
 
-## 0.28.0
-
-Upgrade notes for configs and integrators targeting gem **0.28.0** (current `master` after `0.27.2`):
-
-1. **`auto_source.scraper.native_feed`** — New tier-0 scraper (default `enabled: true`) promotes same-origin RSS/Atom before HTML heuristics. Direct feed URLs parse without HTML AutoSource. Disable with `enabled: false`.
-2. **`auto_source.entry_resolution`** — Weak homepage/hub extracts under `strategy: auto` may probe same-origin listing/feed candidates (defaults `enabled: true`, `max_probes: 5`) and sticky-rewrite the scrape URL only when the retry yields items. See [Auto Source](/ruby-gem/reference/auto-source/#entry-url-resolution).
-3. **`Status` / CLI `--explain`** — Optional `entry_url`, `scrape_url`, and `entry_resolution` (`applied`, `probe_count`, `reason`, optional `winner_score`). `applied: true` is a tournament win, not a guarantee the wire URL changed.
-4. **Request budget** — Default baseline reserves NativeFeed and entry-resolution slots (about +7 requests). Raise `request.max_requests` if builds hit the budget.
-5. **MCP `inspect_url`** — When `alternate_feeds` is present, `next_step` is `scrape_url` (was `done`). Payload adds `surface_category` and nests SST under `sst` (`node_count`, `degraded`, `segment_stats`); top-level `sst_stats` is gone.
-6. **`RequestTimedOut#timeout_phase`** — Optional `queue` / `boot` / `work` from Botasaurus scrape-API diagnostics (message may include `timeout_phase=<stage>`).
-
-Run `html2rss validate config.yml` after editing `auto_source` options.
-
 ## 0.27.0
 
-Upgrade notes for configs and integrators targeting gem **0.27.0** (after `0.26.0`):
+Upgrade notes for configs and integrators targeting gem **0.27.0** (current `master` after `0.26.0`):
 
 1. **MCP result envelope** — Every MCP tool returns `{ ok, next_step, guidance, payload }` in text and `structuredContent`. Read `payload.items`, `payload.yaml`, and `payload.rss`; scrape text is not a raw item array.
 2. **MCP AutoFallback** — `scrape_url` and `capture_config` with `strategy: "auto"` run Faraday → Botasaurus in one call. `inspect_url` with `auto` stays on Faraday (pin `botasaurus` when you need browser rendering for inspect).
diff --git a/src/content/docs/ruby-gem/guides/managing-feed-configs.mdx b/src/content/docs/ruby-gem/guides/managing-feed-configs.mdx
index 7853d538..950aa938 100644
--- a/src/content/docs/ruby-gem/guides/managing-feed-configs.mdx
+++ b/src/content/docs/ruby-gem/guides/managing-feed-configs.mdx
@@ -76,7 +76,12 @@ Prefer `Html2rss.feed_result` when one scrape must render as both RSS and JSON F
 - `to_rss` / `to_json_feed(feed_url:)` — render formats
 - `status` — scrape telemetry (`Html2rss::Status`)
 
-`status.to_h` is the stable observability payload. Always includes `version` and `dedup_dropped`. When present, it may also include `scraper_tallies`, `selected_strategy`, `attempt_count`, `strategy_attempts` (auto-fallback attempts; empty outside `strategy: auto`), `admission_drops` (Cleanup reason → count), `entry_url` / `scrape_url` (pasted vs effective URL after entry resolution), and `entry_resolution` (`applied`, `probe_count`, `reason`, optional `winner_score`).
+`status.to_h` is the stable observability payload. Always includes `version` and `dedup_dropped`. When present, it may also include:
+
+- `scraper_tallies`, `selected_strategy`, `attempt_count`, `strategy_attempts` (auto-fallback attempts; empty outside `strategy: auto`)
+- `admission_drops` (Cleanup reason → count)
+- `entry_url` / `scrape_url` (pasted vs effective URL after entry resolution)
+- `entry_resolution` (`applied`, `probe_count`, `reason`, optional `winner_score`)
 
 For URL-only auto discovery, `Html2rss.auto_feed_result(url)` returns the same `FeedResult` (CLI `html2rss auto --explain` prints `status.to_h` on stderr).
 
diff --git a/src/content/docs/ruby-gem/reference/auto-source.mdx b/src/content/docs/ruby-gem/reference/auto-source.mdx
index 213c8eef..c09d39ae 100644
--- a/src/content/docs/ruby-gem/reference/auto-source.mdx
+++ b/src/content/docs/ruby-gem/reference/auto-source.mdx
@@ -22,15 +22,15 @@ To enable it, add `auto_source: {}` to your configuration:
 
 One fetch, then scrapers run in **tiers**. Within a tier, results merge. The pipeline stops when Cleanup has admitted enough articles (`limit`, default `25`).
 
-0. **Native syndication (tier 0):** `native_feed` — discovers same-origin RSS/Atom (`rel=alternate` plus common feed paths) and parses them before HTML heuristics. Direct feed entry URLs (Content-Type or body sniff) skip HTML AutoSource and parse immediately.
-1. **In-page structured:** `schema`, `microdata`, `microformats2`, `json_state`, `xhr_articles`
-2. **Follow-up IO:** `wordpress_api`, `sitemap`, `meta_oembed`
-3. **Heuristic:** `semantic_html`
-4. **Heuristic:** `html` — skipped when an earlier tier already admitted at least one clean article
+1. **Native syndication:** `native_feed` — discovers same-origin RSS/Atom (`rel=alternate` plus common feed paths) and parses them before HTML heuristics. Direct feed entry URLs (Content-Type or body sniff) skip HTML AutoSource and parse immediately.
+2. **In-page structured:** `schema`, `microdata`, `microformats2`, `json_state`, `xhr_articles`
+3. **Follow-up IO:** `wordpress_api`, `sitemap`, `meta_oembed`
+4. **Heuristic:** `semantic_html`
+5. **Heuristic:** `html` — skipped when an earlier tier already admitted at least one clean article
 
 What each scraper does:
 
-- **`native_feed`:** Promotes native RSS/Atom when present so syndication wins before structured HTML scrapers. Tallies appear as `AutoSource::NativeFeed` under `--explain`.
+- **`native_feed`:** Prefer native RSS/Atom when present. Tallies appear as `AutoSource::NativeFeed` under `--explain`.
 - **`schema`:** Parses `<script type="json/ld">` tags containing structured data (e.g., [Schema.org](https://schema.org/)), extracting authors and publishers.
 - **`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.
@@ -50,33 +50,36 @@ Drop reasons (counts) land on `Html2rss::Status#admission_drops`. Print them wit
 
 Ruby `limit:` and CLI `--limit` cap kept articles (default `25`).
 
-### Entry URL resolution
+**`json_state` / `xhr_articles`:** both need discoverable arrays of hashes with clear `title` and `url` fields. Minified or obfuscated payloads, heavily encoded values, or blobs that require executing embedded functions are ignored. `xhr_articles` only sees JSON bodies captured during the current Botasaurus browser scrape (capped by the scrape API).
 
-Under `strategy: auto` with `auto_source` (no custom `selectors`), a weak homepage or hub extract can trigger an **entry URL tournament** before Botasaurus escalation. The pipeline probes same-origin listing and feed candidates, then sticky-rewrites the effective scrape URL only when a retry extract yields items.
+**`wordpress_api`:** depends on a public WordPress REST API root. The scraper fetches post records directly; it does not resolve category names or featured media metadata.
 
-Resolution runs when enabled and the page is not a blocked surface, and any of:
+## Entry URL resolution
 
-- fewer than 3 admitted articles, or
-- a weak surface (`high_entropy_surface`, `app_shell`, `unsupported_surface`), or
+Under `strategy: auto` with `auto_source` and no custom `selectors`, a weak homepage or hub extract can trigger **entry URL resolution** before Botasaurus escalation. The pipeline probes same-origin listing and feed candidates, then sticky-rewrites the effective scrape URL only when a retry extract yields items.
+
+Resolution runs when enabled, the page is not a blocked surface, and any of:
+
+- fewer than 3 admitted articles
+- a weak surface (`high_entropy_surface`, `app_shell`, `unsupported_surface`)
 - at least half of the articles came from `native_feed`
 
-Telemetry lands on `Html2rss::Status` as `entry_url` (pasted URL), `scrape_url` (effective fetch URL), and `entry_resolution` (`applied`, `probe_count`, `reason`, optional `winner_score`). `applied: true` means a tournament winner was picked; the sticky rewrite still requires a successful retry extract.
+Inspect results with `html2rss auto URL --explain` or `Html2rss::Status#to_h`:
 
-Defaults: `entry_resolution.enabled: true`, `entry_resolution.max_probes: 5`. Disable with `enabled: false` when you want the pasted URL only.
+| Field              | Meaning                                                         |
+| ------------------ | --------------------------------------------------------------- |
+| `entry_url`        | Pasted / channel URL                                            |
+| `scrape_url`       | Effective fetch URL after resolution                            |
+| `entry_resolution` | `{ applied, probe_count, reason }` plus optional `winner_score` |
 
-**`json_state` / `xhr_articles` Limitations:** both scrapers require discoverable arrays of hashes containing clear `title` and `url` fields. Minified or
-obfuscated payloads, heavily encoded values, or blobs that require executing embedded functions are ignored. `xhr_articles` only sees JSON bodies captured during the current Botasaurus browser scrape (capped by the scrape API).
+`entry_resolution.applied: true` means a winner was selected. The sticky rewrite still requires a successful retry extract.
 
-**`wordpress_api` Limitations:** this scraper depends on the page exposing a public WordPress REST API root. The current implementation fetches post records directly, but it does not yet resolve category names or featured media metadata.
+Defaults: `enabled: true`, `max_probes: 5`. Set `enabled: false` to keep the pasted URL only.
 
 ## Fine-Tuning
 
-You can customize `auto_source` to improve its accuracy.
-
 ### Scraper Options
 
-Enable or disable specific scrapers and adjust their settings:
-
 <Code
   code={`
   channel:
@@ -84,7 +87,7 @@ Enable or disable specific scrapers and adjust their settings:
   auto_source:
     scraper:
       native_feed:
-        enabled: true # default: true; tier 0 RSS/Atom promotion
+        enabled: true # default: true
       wordpress_api:
         enabled: false # default: true
       sitemap:
@@ -117,8 +120,6 @@ Enable or disable specific scrapers and adjust their settings:
 
 ### Entry Resolution Options
 
-Tune or disable the weak-entry tournament:
-
 <Code
   code={`
   channel:
@@ -126,15 +127,13 @@ Tune or disable the weak-entry tournament:
   auto_source:
     entry_resolution:
       enabled: true # default: true
-      max_probes: 5 # default: 5; exclusiveMinimum: 0
+      max_probes: 5 # default: 5; must be > 0
   `}
   lang="yaml"
 />
 
 ### Cleanup Options
 
-Remove unwanted items from the results:
-
 <Code
   code={`
   channel:
diff --git a/src/content/docs/ruby-gem/reference/mcp-server.mdx b/src/content/docs/ruby-gem/reference/mcp-server.mdx
index 40c8a83d..4cc809fd 100644
--- a/src/content/docs/ruby-gem/reference/mcp-server.mdx
+++ b/src/content/docs/ruby-gem/reference/mcp-server.mdx
@@ -38,13 +38,13 @@ The MCP server supports two transport mechanisms:
 
 ## Strategy Resolution in MCP
 
-`scrape_url` and `capture_config` with `strategy: "auto"` (the default) run Faraday → Botasaurus AutoFallback in one call. That path also promotes native RSS/Atom when present and may run entry URL resolution on weak homepage/hub extracts (see [Auto Source](/ruby-gem/reference/auto-source/) and [Strategy](/ruby-gem/reference/strategy/#auto-default)).
+`scrape_url` and `capture_config` with `strategy: "auto"` (the default) run Faraday → Botasaurus AutoFallback in one call. That path prefers native RSS/Atom when present and may run entry URL resolution on weak homepage/hub extracts — see [Auto Source](/ruby-gem/reference/auto-source/) and [Strategy](/ruby-gem/reference/strategy/#auto-default).
 
-`inspect_url` with `auto` uses Faraday for a cheap diagnostic. Pin `strategy: "botasaurus"` when you need browser rendering for inspect. Inspect reports head `rel=alternate` feeds only — it does not path-guess `/feed`.
+`inspect_url` with `auto` uses Faraday for a cheap diagnostic. Pin `strategy: "botasaurus"` when you need browser rendering for inspect. Inspect reports head `rel=alternate` feeds only (no `/feed` path guessing).
 
 Read `html2rss://runtime` for `botasaurus_configured` (boolean only). Set `BOTASAURUS_SCRAPER_URL` on the **MCP process** env (see [AI agent workflows](/ruby-gem/guides/ai-agent-workflows/)).
 
-**Tool-call budget:** `scrape_url` = 1 call. Durable config = `capture_config` → `validate_config` → `apply_config`. Call `inspect_url` only when scrape/capture is weak or you need recon. Follow envelope `next_step` / `guidance` rather than guessing the next tool.
+**Tool-call budget:** `scrape_url` = 1 call. Durable config = `capture_config` → `validate_config` → `apply_config`. Call `inspect_url` only when scrape/capture is weak or you need recon. Follow envelope `next_step` / `guidance`.
 
 ## Result envelope
 
@@ -94,13 +94,13 @@ Diagnostic page analysis plus recon from the same fetch. `auto` uses Faraday; pi
   - `status`: HTTP status when the strategy reports one.
   - `scheme_downgrade`: `true` when the fetch went https → http.
   - `alternate_feeds`: `rel=alternate` RSS/Atom links from the document head (no `/feed` path guessing).
-  - `surface_category`: page surface class (for example listing vs weak/blocked surfaces).
-  - `content_type` / `html_response`.
-  - `sst`: nested `{ node_count, degraded, segment_stats }` when SST ran; `segment_stats` is also emitted at the top level when present.
+  - `surface_category`: page surface class (listing, weak, blocked, and related).
+  - `content_type` / `html_response` / `scraper_eligibility`.
+  - `sst`: `{ node_count, degraded, segment_stats }` when SST ran; `segment_stats` is also emitted at the top level when present.
   - `articles_count` and `admission_drops` when the response is HTML (Cleanup drop-reason counts).
   - `blocked_surface` when an interstitial signature is detected.
   - `xhr_capture` when the inspect strategy is `botasaurus` (`count`, redacted `sample_endpoints`, `candidate_articles`).
-- **next_step:** `scrape_url` when head alternate feeds exist (runtime scrape consumes native alternates) or when no articles were found; `capture_config` when articles were found without alternates.
+- **next_step:** Follow the envelope. Typical values: `scrape_url` when `alternate_feeds` is present or when no articles were found; `capture_config` when articles were found and there are no alternates.
 
 ### `capture_config`
 
diff --git a/src/content/docs/ruby-gem/reference/strategy.mdx b/src/content/docs/ruby-gem/reference/strategy.mdx
index 4156335e..4a58c9d0 100644
--- a/src/content/docs/ruby-gem/reference/strategy.mdx
+++ b/src/content/docs/ruby-gem/reference/strategy.mdx
@@ -22,14 +22,14 @@ The default strategy chain is:
 
 `faraday` -> `botasaurus`
 
-Within each concrete strategy attempt that uses `auto_source` (no custom `selectors`), the extract path can:
+When the config uses `auto_source` (no custom `selectors`), each strategy attempt:
 
-1. Promote native RSS/Atom via the tier-0 `native_feed` scraper (or parse a direct feed URL).
-2. Run **entry URL resolution** on a weak homepage/hub extract — probe same-origin listing/feed candidates and sticky-rewrite the scrape URL only when the retry yields items — **before** escalating to Botasaurus.
+1. Runs AutoSource scrapers, starting with `native_feed` for same-origin RSS/Atom (direct feed URLs parse without HTML AutoSource).
+2. May run **entry URL resolution** on a weak homepage/hub extract — probe same-origin listing/feed candidates and sticky-rewrite the scrape URL only when the retry yields items — **before** escalating to the next strategy.
 
-See [Auto Source](/ruby-gem/reference/auto-source/#entry-url-resolution) for gates, defaults (`entry_resolution.enabled: true`, `max_probes: 5`), and Status fields.
+Gates, defaults, and Status fields: [Auto Source — Entry URL resolution](/ruby-gem/reference/auto-source/#entry-url-resolution).
 
-Auto fallback shares one request budget across all strategy attempts. The baseline reserves slots for NativeFeed follow-up and entry-resolution probes (about **+7** requests when both defaults are on). For pagination-heavy or dynamic pages, increase `request.max_requests` (or `--max-requests`) when retries exhaust the budget.
+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`).
 
@@ -50,7 +50,7 @@ Requirements:
 
 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).
 
-When the scrape API reports a timed-out stage, `Html2rss::RequestService::RequestTimedOut` may carry `timeout_phase` as `queue`, `boot`, or `work` (also reflected in the exception message as `timeout_phase=<stage>`). Transport-hop timeouts leave `timeout_phase` unset.
+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.
 
 During the **browser** execution tier, the Botasaurus scrape API always captures JSON XHR/fetch response bodies (`xhr_responses`). html2rss forwards them as `Response#captured_responses` so AutoSource `xhr_articles` can extract articles without extra requests. The HTTP-request tier returns an empty capture list. Caps and filtering live in the scrape API (see its README); article-likeness filtering is a client concern.