html2rss 0.27.2 → 0.29.1

data/lib/html2rss/link_destination/path_classifier.rb

@@ -71,34 +71,35 @@ module Html2rss
       # @param segments [Array<String>] normalized URL path segments
       def initialize(segments)
         @segments = segments
+        @lexicon = segments.map { ::Html2rss::Html::Probe.fold(_1) }.freeze
       end
 
       # @return [Boolean] true when the route has article-like path evidence
       def content_path?
         @content_path ||= !leading_high_confidence_junk? &&
-                          (SEGMENT_SETS[:content].intersect?(segments) || yearish_content_context?)
+                          (SEGMENT_SETS[:content].intersect?(@lexicon) || yearish_content_context?)
       end
 
       # @return [Boolean] true when the route includes utility/navigation evidence
       def utility_path?
-        @utility_path ||= SEGMENT_SETS[:utility].intersect?(segments)
+        @utility_path ||= SEGMENT_SETS[:utility].intersect?(@lexicon)
       end
 
       # @return [Boolean] true when the route points at conversion or account chrome
       def vanity_path?
-        @vanity_path ||= SEGMENT_SETS[:vanity].intersect?(segments)
+        @vanity_path ||= SEGMENT_SETS[:vanity].intersect?(@lexicon)
       end
 
       # @return [Boolean] true when the route points at taxonomy/listing chrome
       def taxonomy_path?
-        @taxonomy_path ||= SEGMENT_SETS[:taxonomy].intersect?(segments)
+        @taxonomy_path ||= SEGMENT_SETS[:taxonomy].intersect?(@lexicon)
       end
 
       # @return [Boolean] true when the route is too shallow to strongly indicate an article
       def shallow?
         segment_count = segments.size
 
-        segment_count <= 1 || (segment_count == 2 && high_confidence_junk_segment?(segments.last))
+        segment_count <= 1 || (segment_count == 2 && high_confidence_junk_at?(segment_count - 1))
       end
 
       # @return [Boolean] true when the final path segment looks like a post slug
@@ -110,15 +111,15 @@ module Html2rss
 
       # @return [Boolean] true when every path segment is utility chrome
       def utility_only_route?
-        segments.all? { |segment| high_confidence_junk_segment?(segment) }
+        (0...segments.size).all? { |i| high_confidence_junk_at?(i) }
       end
 
       # @return [Boolean] true when the route is shallow and contains high-confidence noise
       def shallow_high_confidence_route?
         vanity_segments = SEGMENT_SETS.fetch(:vanity)
 
-        shallow? && segments.any? do |segment|
-          high_confidence_junk_segment?(segment) || vanity_segments.include?(segment)
+        shallow? && (0...segments.size).any? do |i|
+          high_confidence_junk_at?(i) || vanity_segments.include?(@lexicon[i])
         end
       end
 
@@ -148,11 +149,11 @@ module Html2rss
       private
 
       def leading_high_confidence_junk?
-        segments.any? && high_confidence_junk_segment?(segments.first)
+        segments.any? && high_confidence_junk_at?(0)
       end
 
       def any_high_confidence_junk_segment?
-        segments.any? { |segment| high_confidence_junk_segment?(segment) }
+        (0...segments.size).any? { |i| high_confidence_junk_at?(i) }
       end
 
       def yearish_content_context?
@@ -178,11 +179,12 @@ module Html2rss
       def all_junk?(limit)
         return false if limit <= 0
 
-        (0...limit).all? { |i| high_confidence_junk_segment?(segments[i]) }
+        (0...limit).all? { |i| high_confidence_junk_at?(i) }
       end
 
-      def high_confidence_junk_segment?(segment)
-        SEGMENT_SETS.fetch(:high_confidence_junk).include?(segment) || host_shaped_segment?(segment)
+      def high_confidence_junk_at?(index)
+        SEGMENT_SETS.fetch(:high_confidence_junk).include?(@lexicon[index]) ||
+          host_shaped_segment?(segments[index])
       end
 
       def host_shaped_segment?(segment)
@@ -197,10 +199,9 @@ module Html2rss
         context_segments = SEGMENT_SETS.fetch(:deep_post_context)
 
         (0...limit).any? do |i|
-          segment = segments[i]
-          content_segments.include?(segment) ||
-            segment.match?(PathClassifier::YEARISH_SEGMENT) ||
-            context_segments.include?(segment)
+          content_segments.include?(@lexicon[i]) ||
+            segments[i].match?(PathClassifier::YEARISH_SEGMENT) ||
+            context_segments.include?(@lexicon[i])
         end
       end
 
@@ -209,8 +210,8 @@ module Html2rss
       end
 
       def excluded_last_segment?
-        last = segments.last
-        high_confidence_junk_segment?(last) || SEGMENT_SETS[:vanity].include?(last)
+        last_i = segments.size - 1
+        high_confidence_junk_at?(last_i) || SEGMENT_SETS[:vanity].include?(@lexicon[last_i])
       end
 
       def slug_last_segment?

data/lib/html2rss/mcp/README.md

@@ -0,0 +1,80 @@
+# MCP — curation wire surface
+
+MCP exposes the same seven user-facing verbs as the CLI and gem facades. Full contract and ownership: `CONTEXT.md` § Frozen contract. Contributor law: `AGENTS.md` § Curation CLI / MCP.
+
+## Verb table
+
+| Verb     | MCP tool   | Job                                                  |
+| -------- | ---------- | ---------------------------------------------------- |
+| inspect  | `inspect`  | Diagnostics (final URL, status, alternates, surface) |
+| recon    | `recon`    | Verdict + native_feed preference                     |
+| capture  | `capture`  | YAML draft config                                    |
+| validate | `validate` | Schema only                                          |
+| test     | `test`     | Schema + live extraction                             |
+| apply    | `apply`    | Ship RSS from config                                 |
+| scrape   | `scrape`   | Articles now (one-shot)                              |
+
+Batch: `batch_inspect`, `batch_recon`, `batch_scrape`.
+
+**Golden path:** optional inspect → recon → capture → test → apply. Side door: validate. One-shot: scrape.
+
+## Decision tree
+
+1. **Articles now (no saved config)?** → `scrape` (or `batch_scrape` for multiple URLs). `strategy: "auto"` runs Faraday → Botasaurus; do not retry with explicit `faraday` after `auto`.
+2. **Reusable feed YAML?** → `capture` → `test` → `apply`. `capture` returns YAML in `payload.yaml`. Strive `enhance: true` (false only when chrome leaks). `test` runs schema + live extraction; optional `compare_enhance` compares enhance off vs on. `apply` is the ship gate (`isError` on zero items). Both `test` and `apply` may include `quality_report.enhance_gains` when `selectors.items.enhance` is true.
+3. **Weak scrape/capture or recon?** → `inspect` (or `batch_inspect`). When alternates warrant it, follow `next_step` to `recon`.
+4. **Config already in hand?** → `validate` (schema only) → `test` → `apply`.
+
+Prefer `capture` for durable configs; `scrape` / `batch_scrape` for one-shot extraction. Follow envelope `next_step` and `guidance`; do not parse scrape text as a raw item array.
+
+## Envelope
+
+Every tool result is one JSON object (text body and `structuredContent`):
+
+| Field       | Role                                                         |
+| ----------- | ------------------------------------------------------------ |
+| `ok`        | Success vs schema/ship failure                               |
+| `next_step` | Bare verb name or `done` / `read_runtime`                    |
+| `guidance`  | Agent instruction (from `Outcome::Playbook`)                 |
+| `payload`   | Tool-specific data (`yaml`, `rss`, `items`, recon fields, …) |
+
+`Contract.response` builds the wire body; `Outcome` owns `next_step` policy.
+
+## Ownership
+
+| Concern                                       | Owner                                            |
+| --------------------------------------------- | ------------------------------------------------ |
+| Tool schemas, titles, strategy enum           | `MCP::Contract`                                  |
+| Catalog fingerprint + `mcp_contract_version` | `MCP::Contract` (+ `Runtime.snapshot` wire)      |
+| Envelope factories, `next_step` routing       | `MCP::Outcome`                                   |
+| Runtime instructions, guidance, prompt bodies | `Outcome::Playbook` (SSOT — `Server` delegates)  |
+| Diagnostic fetch + assess                     | `PageRecon::Diagnostics`                         |
+| Curation verdict                              | `Recon`                                          |
+| Capture YAML product                          | `Capture::CaptureResult#yaml`                    |
+| Batch concurrency                             | `Batch.map` (Thread pool; preserves input order) |
+
+Do not duplicate playbook prose in `server.rb`.
+
+## Resources
+
+| URI                     | Description                                                |
+| ----------------------- | ---------------------------------------------------------- |
+| `html2rss://schema`     | Full JSON Schema for feed configurations                   |
+| `html2rss://extractors` | Registered extractor names                                 |
+| `html2rss://strategies` | Published MCP strategies (`auto`, `faraday`, `botasaurus`) |
+| `html2rss://runtime`    | `version`, `mcp_contract_version`, `catalog_fingerprint`, `tools`, `botasaurus_configured` (never the scraper URL). Fingerprint covers tool names, required keys, and `oneOf` branches; bump `mcp_contract_version` for envelope semantics. |
+
+## Prompts
+
+| Name                  | Description                                                  |
+| --------------------- | ------------------------------------------------------------ |
+| `scrape-webpage`      | One `scrape` call; `inspect` only if weak or recon needed    |
+| `capture-feed-config` | Capture YAML → test → apply; catalog rewrite; strive enhance |
+
+## Strategy note
+
+`scrape` / `capture` with `strategy: "auto"` run the full AutoFallback chain. `inspect` maps `auto` to Faraday for cheap diagnostics; pin `botasaurus` when you need browser rendering for inspect.
+
+## Inspect redirects
+
+`payload.final_url` is the post-redirect landing URL. When it differs from the URL you passed and `status` is 4xx, inspect still followed redirects — retry on `final_url` or pass the site's canonical hostname (often `www`). Cross-host redirects set `Host` per hop; html2rss does not pin the entry hostname. See [`page_recon/README.md`](../page_recon/README.md).

data/lib/html2rss/mcp/contract.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'digest'
+
 module Html2rss
   module MCP
     ##
@@ -9,6 +11,10 @@ module Html2rss
       # Published MCP request strategies (excludes +local_file+).
       STRATEGIES = %w[auto faraday botasaurus].freeze
 
+      # Bump when tool names, required inputs, or envelope semantics change (independent of gem +VERSION+).
+      MCP_CONTRACT_VERSION = 2
+      public_constant :MCP_CONTRACT_VERSION
+
       # Raised when apply/validate config uses an unpublished MCP request adapter.
       class UnpublishedRequestError < ArgumentError; end
 
@@ -51,14 +57,14 @@ module Html2rss
         }.freeze
       }.freeze
 
-      # Input schema for +validate_config+ (config XOR yaml).
+      # Input schema for +validate+ (config XOR yaml).
       CONFIG_XOR_SCHEMA = {
         type: 'object',
         properties: CONFIG_XOR_PROPERTIES,
         oneOf: XOR_ONE_OF
       }.freeze
 
-      # Input schema for +apply_config+ (required URL plus config XOR yaml).
+      # Input schema for +apply+ (required URL plus config XOR yaml).
       APPLY_INPUT_SCHEMA = {
         type: 'object',
         properties: { url: URL_PROPERTY, **CONFIG_XOR_PROPERTIES }.freeze,
@@ -66,7 +72,28 @@ module Html2rss
         oneOf: XOR_ONE_OF
       }.freeze
 
-      # Input schema for +scrape_url+.
+      # Input schema for +test+.
+      TEST_INPUT_SCHEMA = {
+        type: 'object',
+        properties: {
+          **CONFIG_XOR_PROPERTIES,
+          min_items: { type: 'integer', description: 'Minimum required items (default: 1)', default: 1 },
+          strict_quality: {
+            type: 'boolean',
+            description: 'Fail when ship-quality audit thresholds are exceeded (default: false)',
+            default: false
+          },
+          compare_enhance: {
+            type: 'boolean',
+            description: 'Diagnostic: compare extraction with enhance on vs off on cached HTML (default: false)',
+            default: false
+          },
+          strategy: STRATEGY_PROPERTY
+        }.freeze,
+        oneOf: XOR_ONE_OF
+      }.freeze
+
+      # Input schema for +scrape+.
       SCRAPE_INPUT_SCHEMA = {
         type: 'object',
         properties: {
@@ -78,24 +105,87 @@ module Html2rss
         required: %w[url]
       }.freeze
 
-      # Input schema for +inspect_url+.
+      # Input schema for +inspect+.
       INSPECT_INPUT_SCHEMA = {
         type: 'object',
         properties: { url: URL_PROPERTY, strategy: INSPECT_STRATEGY_PROPERTY }.freeze,
         required: %w[url]
       }.freeze
 
-      # Input schema for +capture_config+.
+      # Input schema for +recon+.
+      RECON_INPUT_SCHEMA = INSPECT_INPUT_SCHEMA
+
+      # Input schema for +capture+.
       CAPTURE_INPUT_SCHEMA = {
         type: 'object',
         properties: {
           url: URL_PROPERTY,
           strategy: STRATEGY_PROPERTY,
-          items_selector: { type: 'string', description: 'Optional CSS selector hint for items' }
+          items_selector: { type: 'string', description: 'Optional CSS selector hint for items' },
+          force: { type: 'boolean', description: 'Bypass native feed check', default: false },
+          topics: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Directory topics override'
+          }.freeze,
+          title: { type: 'string', description: 'Channel title override' },
+          summary: { type: 'string', description: 'Directory summary override' },
+          enhance: { type: 'boolean', description: 'Force enhance on or off' },
+          limit: { type: 'integer', description: 'Max articles to keep' },
+          max_redirects: { type: 'integer', description: 'Optional redirect limit override' },
+          max_requests: { type: 'integer', description: 'Optional request budget override' }
         }.freeze,
         required: %w[url]
       }.freeze
 
+      ##
+      # Shared JSON Schema for batch URL tools (+batch_scrape+, +batch_inspect+, +batch_recon+).
+      #
+      # @param urls_description [String] description for the +urls+ array property
+      # @param strategy_property [Hash] strategy JSON Schema property
+      # @param extra_properties [Hash] additional tool-specific properties (e.g. +limit+ on scrape)
+      # @return [Hash]
+      def self.batch_urls_input_schema(urls_description:, strategy_property:, extra_properties: {}) # rubocop:disable Metrics/MethodLength
+        {
+          type: 'object',
+          properties: {
+            urls: {
+              type: 'array',
+              items: URL_PROPERTY,
+              minItems: 1,
+              maxItems: 25,
+              description: urls_description
+            }.freeze,
+            strategy: strategy_property,
+            concurrency: {
+              type: 'integer',
+              description: 'Max parallel worker threads (1..10, default: 5)',
+              default: 5
+            },
+            **extra_properties
+          }.freeze,
+          required: %w[urls]
+        }
+      end
+
+      # Input schema for +batch_scrape+.
+      BATCH_SCRAPE_INPUT_SCHEMA = batch_urls_input_schema(
+        urls_description: 'List of page URLs to scrape (1..25)',
+        strategy_property: STRATEGY_PROPERTY,
+        extra_properties: {
+          limit: { type: 'integer', description: 'Max articles per URL to keep (default 10)', default: 10 }
+        }
+      ).freeze
+
+      # Input schema for +batch_inspect+.
+      BATCH_INSPECT_INPUT_SCHEMA = batch_urls_input_schema(
+        urls_description: 'List of page URLs to inspect (1..25)',
+        strategy_property: INSPECT_STRATEGY_PROPERTY
+      ).freeze
+
+      # Input schema for +batch_recon+.
+      BATCH_RECON_INPUT_SCHEMA = BATCH_INSPECT_INPUT_SCHEMA
+
       # Tool annotations for open-world read-only tools.
       ANNOTATIONS_OPEN_WORLD = {
         read_only_hint: true,
@@ -104,19 +194,51 @@ module Html2rss
         open_world_hint: true
       }.freeze
 
-      # Tool annotations for +validate_config+ (closed world).
+      # Tool annotations for +validate+ (closed world).
       ANNOTATIONS_VALIDATE = ANNOTATIONS_OPEN_WORLD.merge(open_world_hint: false).freeze
 
       # Human titles for +tools/list+.
       TITLES = {
-        scrape_url: 'Scrape URL',
-        inspect_url: 'Inspect URL',
-        capture_config: 'Capture feed config',
-        validate_config: 'Validate feed config',
-        apply_config: 'Apply feed config'
+        scrape: 'Scrape',
+        inspect: 'Inspect',
+        recon: 'Recon',
+        batch_scrape: 'Batch scrape',
+        batch_inspect: 'Batch inspect',
+        batch_recon: 'Batch recon',
+        capture: 'Capture',
+        validate: 'Validate',
+        apply: 'Apply',
+        test: 'Test'
       }.freeze
 
+      # @api private
+      CATALOG_ENTRY_LINE = lambda do |entry|
+        schema = entry.fetch(:input_schema)
+        required = Array(schema[:required]).sort.join(',')
+        one_of = Array(schema[:oneOf]).map { |branch| Array(branch[:required]).sort.join('+') }.sort.join('|')
+        [entry.fetch(:name), required, one_of].reject(&:empty?).join(':')
+      end.freeze
+
       class << self
+        ##
+        # Canonical MCP tool names in alphabetical order (same set as +tools/list+).
+        #
+        # @return [Array<String>]
+        def catalog_tools
+          Server::Tools::TOOLS.map { |entry| entry.fetch(:name) }.sort
+        end
+
+        ##
+        # Stable fingerprint of published tools, required keys, and +oneOf+ branches.
+        # Clients compare against a cached +tools/list+ to detect stale catalogs.
+        # Bump {MCP_CONTRACT_VERSION} for envelope or breaking wire semantics only.
+        #
+        # @return [String] 16-char hex digest prefix
+        def catalog_fingerprint
+          lines = Server::Tools::TOOLS.sort_by { |entry| entry.fetch(:name) }.map(&CATALOG_ENTRY_LINE)
+          Digest::SHA256.hexdigest(lines.join("\n")).slice(0, 16)
+        end
+
         ##
         # Envelope JSON Schema. Built lazily so Zeitwerk can load Contract before Outcome.
         #
@@ -151,7 +273,7 @@ module Html2rss
 
         ##
         # Rejects unpublished MCP request adapters so apply/validate cannot
-        # {File.read} arbitrary paths. CLI and Config still allow +local_file+.
+        # +File.read+ arbitrary paths. CLI and Config still allow +local_file+.
         #
         # @param config [Hash]
         # @return [void]

data/lib/html2rss/mcp/outcome/playbook.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Html2rss
+  module MCP
+    class Outcome
+      ##
+      # Single source of truth for MCP agent instructions, next-step guidance,
+      # and prompt bodies. {Server} delegates here — do not duplicate prose in
+      # +server.rb+.
+      class Playbook
+        # Default guidance copy keyed by {Outcome::NextStep::NAMES}.
+        GUIDANCE = {
+          done: 'Done. Read payload for the result.',
+          inspect: 'Call inspect next. Read payload for diagnostics (final_url, status, ' \
+                   'scheme_downgrade, alternate_feeds, likely_js_shell, redirect_summary).',
+          recon: 'Call recon next. Read payload for verdict and native_feed preference.',
+          validate: 'Call validate with payload.yaml or a config hash (XOR, not both).',
+          apply: 'Call apply next. Confirm payload.item_count before shipping.',
+          scrape: 'Call scrape for articles now. strategy auto already runs Faraday then Botasaurus ' \
+                  'and promotes native RSS/Atom when present.',
+          capture: 'Call capture for a reusable YAML draft, then follow next_step.',
+          read_runtime: 'Read html2rss://runtime. Compare mcp_contract_version and catalog_fingerprint ' \
+                        'to your cached tools/list before retrying unknown tools. ' \
+                        'Set BOTASAURUS_SCRAPER_URL on the MCP process if botasaurus_configured is false.',
+          test: 'Call test next (schema + live extraction). Confirm payload.item_count, ' \
+                'failure_kind, and payload.quality_report warnings before shipping.'
+        }.freeze
+
+        class << self
+          ##
+          # Published MCP server instructions (decision tree for agents).
+          #
+          # @return [String]
+          def instructions # rubocop:disable Metrics/MethodLength -- agent decision tree is the published contract
+            <<~TEXT.strip
+              html2rss MCP — decide which tool to call:
+
+              1. Need articles now (no saved config)? → scrape (or batch_scrape for multiple)
+                 - strategy "auto" runs Faraday → Botasaurus AutoFallback. Do not retry with explicit faraday after auto.
+                 - Empty scrape is still success (articles-now). Follow next_step / guidance (read_runtime if Botasaurus unset).
+              2. Need a reusable feed YAML? → capture → test → apply
+                 - capture returns YAML inside payload.yaml. Draft only: if destination is html2rss-configs, rewrite for directory.topics and explicit channel title/url. Default enhance follows capture evidence (false when admission_drops show chrome); override only when needed.
+                 - test runs schema + live extraction (min items). apply is the ship gate (isError on zero items). Confirm payload.item_count and payload.quality_report warnings (including enhance_gains when selectors.items.enhance is true). Use compare_enhance on test for enhance on/off diagnostics.
+                 - validate alone is for schema-only checks; on success next_step is test.
+              3. Weak scrape/capture or recon (final URL, status, https→http, rel=alternate feeds)? → inspect (or batch_inspect). Read likely_js_shell vs blocked_surface when articles_count is 0. When alternates warrant it, inspect next_step is recon.
+              4. Have a config already? → validate (must succeed) → test → apply
+              5. Schema / extractors / strategies / runtime → resources html2rss://schema|extractors|strategies|runtime
+                 - runtime publishes version, mcp_contract_version, catalog_fingerprint, tools, botasaurus_configured.
+                 - Refresh tools/list when catalog_fingerprint differs from your cache.
+
+              Prefer capture for durable config; scrape / batch_scrape for one-shot extraction.
+              Follow envelope next_step and guidance. Botasaurus needs BOTASAURUS_SCRAPER_URL in this process env (read html2rss://runtime; the URL is never returned).
+            TEXT
+          end
+
+          ##
+          # @param url [String]
+          # @return [String]
+          def scrape_webpage_prompt(url)
+            <<~MSG.strip
+              Scrape #{url} with scrape (strategy auto). One call is enough — auto already runs Faraday then Botasaurus.
+              Follow envelope next_step and guidance. Call inspect only if articles are empty/weak or you need diagnostics (final_url, status, scheme_downgrade, alternate_feeds). When inspect finds alternates, follow next_step to recon.
+              Do not retry scrape with explicit faraday after auto. Read html2rss://runtime if next_step is read_runtime.
+              Return payload.items (not a raw JSON array).
+            MSG
+          end
+
+          ##
+          # @param url [String]
+          # @return [String]
+          def capture_feed_config_prompt(url)
+            <<~MSG.strip
+              Build a reusable html2rss feed config for #{url}:
+              1) capture — YAML is payload.yaml. Check payload.articles_count, payload.has_selectors, and payload.suggested_channel_url. enhance defaults from admission evidence (false when chrome drops are high). When payload.native_feed is set, follow next_step (done — use the native feed).
+              2) Follow next_step. If weak or you need recon, inspect then recon when alternates warrant it. Auto already hops to Botasaurus; do not retry capture with botasaurus unless Faraday was blocked.
+              3) test with yaml (or config hash) — schema + live extraction. On :schema failure, validate; on :execution/:min_items, recapture. Read payload.quality_report.enhance_gains when enhance is on; optional compare_enhance compares enhance off vs on without changing shipped RSS.
+              4) apply — isError if zero items. Confirm payload.item_count and payload.quality_report (including enhance_gains) before shipping.
+              If the destination is html2rss-configs, rewrite the draft for directory.topics and explicit channel title/url. Return YAML.
+            MSG
+          end
+
+          ##
+          # @param report [PageRecon::Diagnostics::Report]
+          # @return [String]
+          def inspect_guidance(report)
+            return GUIDANCE.fetch(:inspect) unless report.articles_count.zero?
+
+            empty_extract_guidance(report.data)
+          end
+
+          ##
+          # @param data [Hash{Symbol => Object}]
+          # @return [String]
+          def empty_extract_guidance(data) # rubocop:disable Metrics/MethodLength
+            if data[:blocked_surface] || data[:surface_category].to_s == 'blocked_surface'
+              return 'Blocked or anti-bot interstitial likely. Retry scrape with strategy botasaurus once ' \
+                     '(or CLI inspect --deep when BOTASAURUS_SCRAPER_URL is set). ' \
+                     'Do not retry explicit faraday after auto.'
+            end
+            if data[:likely_js_shell]
+              return 'JS-rendered shell likely (html_present, zero articles). Use strategy auto or botasaurus; ' \
+                     'CLI inspect --deep for one Botasaurus diagnostic hop.'
+            end
+
+            'Empty extract on a static-looking page. Verify redirect_summary.final_url and surface; ' \
+              'capture may need selector hints.'
+          end
+
+          ##
+          # @param result [Html2rss::Recon::Result]
+          # @param next_step [Outcome::NextStep]
+          # @return [String]
+          def recon_guidance(result, next_step)
+            return next_step.guidance unless result.scheme_downgrade
+
+            "#{next_step.guidance} HTTPS→HTTP downgrade detected: try one Botasaurus scrape before DROP."
+          end
+        end
+      end
+    end
+  end
+end