html2rss 0.28.0 → 0.30.0

data/lib/html2rss/mcp/contract.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'digest'
+
 module Html2rss
   module MCP
     ##
@@ -7,7 +9,15 @@ module Html2rss
     # annotations, and the single compact JSON envelope response.
     module Contract # rubocop:disable Metrics/ModuleLength -- published listing constants stay co-located
       # Published MCP request strategies (excludes +local_file+).
-      STRATEGIES = %w[auto faraday botasaurus].freeze
+      STRATEGIES = %w[auto default httpx botasaurus].freeze
+      # Accepted migration strategies retained for backwards compatibility.
+      MIGRATION_STRATEGIES = %w[faraday].freeze
+      # Complete set of strategies accepted by {.assert_published_request!}.
+      ALL_ACCEPTED_STRATEGIES = (STRATEGIES + MIGRATION_STRATEGIES).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
@@ -24,12 +34,12 @@ module Html2rss
         type: 'string',
         enum: STRATEGIES,
         default: 'auto',
-        description: 'Request strategy (auto runs faraday → botasaurus fallback chain)'
+        description: 'Request strategy (auto runs default → botasaurus fallback chain)'
       }.freeze
 
-      # JSON Schema property for inspect +strategy+ (auto stays on Faraday).
+      # JSON Schema property for inspect +strategy+ (auto stays on default).
       INSPECT_STRATEGY_PROPERTY = STRATEGY_PROPERTY.merge(
-        description: 'Request strategy (auto uses Faraday for cheap diagnostics; pin botasaurus when needed)'
+        description: 'Request strategy (auto uses default for cheap diagnostics; pin botasaurus when needed)'
       ).freeze
 
       # JSON Schema +oneOf+ requiring exactly one of +config+ or +yaml+.
@@ -51,14 +61,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 +76,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 +109,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 +198,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 +277,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]
@@ -159,7 +285,7 @@ module Html2rss
         #   or +request.local_file_path+ is present
         def assert_published_request!(config)
           strategy = config[:strategy]
-          unless strategy.nil? || STRATEGIES.include?(strategy.to_s)
+          unless strategy.nil? || ALL_ACCEPTED_STRATEGIES.include?(strategy.to_s)
             raise UnpublishedRequestError,
                   "MCP does not accept strategy #{strategy} (published: #{STRATEGIES.join(', ')})"
           end

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 default (HTTPX) → Botasaurus AutoFallback. Do not retry with explicit default 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 default 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 default 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 default 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 default 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

data/lib/html2rss/mcp/outcome.rb

@@ -5,10 +5,10 @@ module Html2rss
     Outcome = Data.define(:ok, :next_step, :guidance, :payload)
 
     ##
-    # Typed MCP tool result. Owns next-step policy and guidance copy so the
-    # protocol adapter does not branch on quality heuristics.
-    class Outcome
-      # Matches {ConfigArgument} XOR {ArgumentError} messages.
+    # Typed MCP tool result. Owns next-step policy; guidance copy lives in
+    # {Playbook}.
+    class Outcome # rubocop:disable Metrics/ClassLength -- next-step policy + factories stay co-located
+      # Matches {ConfigArgument} XOR +ArgumentError+ messages.
       XOR_ERROR = /exactly one of config or yaml/
       NextStep = Data.define(:name, :guidance)
 
@@ -16,20 +16,7 @@ module Html2rss
       # Closed set of agent next actions. Invalid names cannot be constructed.
       class NextStep
         # Wire names for +next_step+.
-        NAMES = %i[done inspect_url validate_config apply_config scrape_url capture_config read_runtime].freeze
-        # Default guidance copy keyed by {NAMES}.
-        GUIDANCE = {
-          done: 'Done. Read payload for the result.',
-          inspect_url: 'Call inspect_url next. Read payload for recon (final_url, status, ' \
-                       'scheme_downgrade, alternate_feeds).',
-          validate_config: 'Call validate_config with payload.yaml or a config hash (XOR, not both).',
-          apply_config: 'Call apply_config next. Confirm payload.item_count before shipping.',
-          scrape_url: 'Call scrape_url for articles now. strategy auto already runs Faraday then Botasaurus ' \
-                      'and promotes native RSS/Atom when present.',
-          capture_config: 'Call capture_config for a reusable YAML draft, then follow next_step.',
-          read_runtime: 'Read html2rss://runtime. Set BOTASAURUS_SCRAPER_URL on the MCP process ' \
-                        'if botasaurus_configured is false.'
-        }.freeze
+        NAMES = %i[done inspect recon validate apply scrape capture read_runtime test].freeze
 
         ##
         # @param name [Symbol, String]
@@ -38,7 +25,7 @@ module Html2rss
           step = name.to_sym
           raise ArgumentError, "unknown next_step: #{name.inspect}" unless NAMES.include?(step)
 
-          super(name: step, guidance: (guidance || GUIDANCE.fetch(step)).freeze)
+          super(name: step, guidance: (guidance || Playbook::GUIDANCE.fetch(step)).freeze)
         end
 
         class << self
@@ -79,11 +66,21 @@ module Html2rss
         end
 
         ##
-        # @param payload [Hash] inspect recon Hash
+        # @param report [PageRecon::Diagnostics::Report]
         # @return [Outcome]
-        def inspect(payload:)
-          next_step = inspect_next_step(payload)
-          new(ok: true, next_step:, guidance: next_step.guidance, payload:)
+        def inspect(report:)
+          next_step = inspect_next_step(report)
+          guidance = Playbook.inspect_guidance(report)
+          new(ok: true, next_step:, guidance:, payload: report.to_wire_h)
+        end
+
+        ##
+        # @param result [Html2rss::Recon::Result]
+        # @return [Outcome]
+        def recon(result:)
+          next_step = recon_next_step(result)
+          guidance = Playbook.recon_guidance(result, next_step)
+          new(ok: true, next_step:, guidance:, payload: result.to_h)
         end
 
         ##
@@ -95,13 +92,17 @@ module Html2rss
         # @param segment_strategy [Symbol, String, nil]
         # @param selected_strategy [Symbol, String, nil]
         # @param admission_drops [Hash]
+        # @param native_feed [String, nil]
+        # @param suggested_channel_url [String, nil]
         # @return [Outcome]
         def capture(yaml:, articles_count:, has_selectors:, channel_title:, requested_strategy:, # rubocop:disable Metrics/ParameterLists
-                    segment_strategy: nil, selected_strategy: nil, admission_drops: {})
-          next_step = capture_next_step(articles_count:, has_selectors:)
+                    segment_strategy: nil, selected_strategy: nil, admission_drops: {}, native_feed: nil,
+                    suggested_channel_url: nil)
+          next_step = capture_next_step(articles_count:, has_selectors:, native_feed:)
           new(ok: true, next_step:, guidance: next_step.guidance, payload: capture_payload(
             yaml:, articles_count:, has_selectors:, channel_title:, requested_strategy:,
-            segment_strategy:, selected_strategy:, admission_drops:
+            segment_strategy:, selected_strategy:, admission_drops:, native_feed:,
+            suggested_channel_url:
           ))
         end
 
@@ -110,19 +111,50 @@ module Html2rss
         # @return [Outcome]
         def validate(errors:)
           ok = errors.nil?
-          next_step = ok ? NextStep.apply_config : NextStep.validate_config
+          next_step = ok ? NextStep.test : NextStep.validate
           new(ok:, next_step:, guidance: next_step.guidance, payload: ok ? {} : { errors: })
         end
 
+        ##
+        # @param test_result [Html2rss::Test::Result]
+        # @return [Outcome]
+        def test(test_result)
+          next_step = test_next_step(test_result)
+          new(
+            ok: test_result.success,
+            next_step:,
+            guidance: test_guidance(test_result, next_step),
+            payload: test_result.to_h
+          )
+        end
+
+        ##
+        # @param batch_result [Html2rss::Batch::BatchResult]
+        # @return [Outcome]
+        def batch_scrape(batch_result) = batch(batch_result, NextStep.scrape)
+
+        ##
+        # @param batch_result [Html2rss::Batch::BatchResult]
+        # @return [Outcome]
+        def batch_inspect(batch_result) = batch(batch_result, NextStep.inspect)
+
+        ##
+        # @param batch_result [Html2rss::Batch::BatchResult]
+        # @return [Outcome]
+        def batch_recon(batch_result) = batch(batch_result, NextStep.recon)
+
         ##
         # @param rss [String]
         # @param item_count [Integer]
         # @param empty [Boolean] {FeedResult#empty?} (ship gate); defaults to zero items
+        # @param quality_report [Hash, nil] optional ship-quality audit summary
         # @return [Outcome]
-        def apply(rss:, item_count:, empty: item_count.zero?)
+        def apply(rss:, item_count:, empty: item_count.zero?, quality_report: nil)
           ok = !empty
-          next_step = ok ? NextStep.done : NextStep.inspect_url
-          new(ok:, next_step:, guidance: next_step.guidance, payload: { rss:, item_count: })
+          next_step = ok ? NextStep.done : NextStep.inspect
+          payload = { rss:, item_count: }
+          payload[:quality_report] = quality_report if quality_report
+          new(ok:, next_step:, guidance: next_step.guidance, payload:)
         end
 
         ##
@@ -136,11 +168,16 @@ module Html2rss
 
         private
 
+        def batch(batch_result, failure_step)
+          step = batch_result.successful.positive? ? NextStep.done : failure_step
+          new(ok: true, next_step: step, guidance: step.guidance, payload: batch_result.to_h)
+        end
+
         def scrape_next_step(empty, botasaurus_configured:)
           return NextStep.done unless empty
           return NextStep.read_runtime unless botasaurus_configured
 
-          NextStep.inspect_url
+          NextStep.inspect
         end
 
         def scrape_payload(items:, requested_strategy:, channel_title:, admission_drops:)
@@ -150,22 +187,55 @@ module Html2rss
           }
         end
 
-        def inspect_next_step(payload)
-          # Runtime scrape_url now consumes native alternates (NativeFeed / direct feed parse).
-          return NextStep.scrape_url if Array(payload[:alternate_feeds]).any?
-          return NextStep.capture_config if payload[:articles_count].to_i.positive?
+        def inspect_next_step(report)
+          return NextStep.recon if report.alternate_feeds?
+          return NextStep.capture if report.articles_count.positive?
 
-          NextStep.scrape_url
+          NextStep.scrape
         end
 
-        def capture_next_step(articles_count:, has_selectors:)
-          articles_count.positive? && has_selectors ? NextStep.validate_config : NextStep.inspect_url
+        def recon_next_step(result)
+          return NextStep.done if result.defer?
+          return NextStep.capture if result.build?
+
+          NextStep.scrape
+        end
+
+        def capture_next_step(articles_count:, has_selectors:, native_feed: nil)
+          return NextStep.done if native_feed
+
+          articles_count.positive? && has_selectors ? NextStep.test : NextStep.inspect
+        end
+
+        def test_next_step(test_result)
+          return NextStep.apply if test_result.success
+
+          kind = test_result.failure_kind
+          return NextStep.validate if kind&.schema?
+          return NextStep.capture if kind&.execution? || kind&.min_items? || kind&.quality?
+
+          NextStep.capture
+        end
+
+        def test_guidance(test_result, next_step)
+          base = if test_result.success
+                   next_step.guidance
+                 else
+                   test_result.error_message || next_step.guidance
+                 end
+          warnings = test_result.quality_report&.warnings
+          return base if warnings.nil? || warnings.empty?
+
+          "#{base} Review payload.quality_report warnings: #{warnings.join(', ')}."
         end
 
         def capture_payload(yaml:, articles_count:, has_selectors:, channel_title:, requested_strategy:, # rubocop:disable Metrics/ParameterLists
-                            segment_strategy:, selected_strategy:, admission_drops:)
+                            segment_strategy:, selected_strategy:, admission_drops:, native_feed: nil,
+                            suggested_channel_url: nil)
           {
             yaml:, articles_count:, has_selectors:, channel_title:, requested_strategy: requested_strategy.to_s,
+            **(native_feed ? { native_feed: native_feed.to_s } : {}),
+            **(suggested_channel_url ? { suggested_channel_url: suggested_channel_url.to_s } : {}),
             **(segment_strategy ? { segment_strategy: segment_strategy.to_s } : {}),
             **(selected_strategy ? { selected_strategy: selected_strategy.to_s } : {}),
             **(admission_drops.any? ? { admission_drops: } : {})
@@ -175,14 +245,14 @@ module Html2rss
         def next_step_for_error(error)
           case error
           when RequestService::BotasaurusConfigurationError then NextStep.read_runtime
-          when Contract::UnpublishedRequestError then NextStep.validate_config
+          when Contract::UnpublishedRequestError then NextStep.validate
           when ArgumentError then argument_error_next_step(error)
-          else NextStep.inspect_url
+          else NextStep.inspect
           end
         end
 
         def argument_error_next_step(error)
-          XOR_ERROR.match?(error.message) ? NextStep.validate_config : NextStep.inspect_url
+          XOR_ERROR.match?(error.message) ? NextStep.validate : NextStep.inspect
         end
       end
     end

data/lib/html2rss/mcp/runtime.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Html2rss
+  module MCP
+    ##
+    # Runtime facts for the MCP process (env configuration, wire coercion).
+    module Runtime
+      # Published +html2rss://runtime+ resource (never leaks secrets).
+      Snapshot = Data.define(
+        :version,
+        :mcp_contract_version,
+        :catalog_fingerprint,
+        :tools,
+        :botasaurus_configured
+      )
+
+      module_function
+
+      ##
+      # @return [Boolean] whether Botasaurus transport is configured in this process
+      def botasaurus_configured?
+        !ENV['BOTASAURUS_SCRAPER_URL'].to_s.strip.empty?
+      end
+
+      ##
+      # @return [Snapshot] runtime capabilities and catalog identity for MCP clients
+      def snapshot
+        Snapshot.new(
+          version: Html2rss::VERSION,
+          mcp_contract_version: Contract::MCP_CONTRACT_VERSION,
+          catalog_fingerprint: Contract.catalog_fingerprint,
+          tools: Contract.catalog_tools,
+          botasaurus_configured: botasaurus_configured?
+        )
+      end
+
+      ##
+      # @param strategy [String, Symbol, nil]
+      # @return [Symbol]
+      def coerce_strategy(strategy)
+        (strategy || :auto).to_sym
+      end
+    end
+  end
+end