html2rss 0.28.0 → 0.29.1

data/lib/html2rss/feed_resolution.rb

@@ -33,13 +33,12 @@ module Html2rss
     # @param articles [Array<Html2rss::Article>]
     # @param surface_category [Symbol, nil]
     # @return [Result]
-    # rubocop:disable Metrics/ParameterLists -- tournament kwargs stay co-located
+    # rubocop:disable-next Metrics/ParameterLists -- tournament kwargs stay co-located
     def self.call(entry_url:, response:, session:, config:, articles:, surface_category: nil)
       Runner.new(
         entry_url:, response:, session:, config:, articles:, surface_category:
       ).call
     end
-    # rubocop:enable Metrics/ParameterLists
 
     ##
     # Outcome of {FeedResolution.try_apply!} for the auto-fallback chain.
@@ -60,7 +59,7 @@ module Html2rss
     # @param budget [Html2rss::RequestService::Budget]
     # @return [ApplyOutcome, nil] `:succeeded` sticky scrape target when retry extract yielded items;
     #   `nil` when no winner or retry was empty (entry scrape target kept; Diag.applied may still be true)
-    # rubocop:disable Metrics/ParameterLists -- orchestration kwargs stay co-located
+    # rubocop:disable-next Metrics/ParameterLists -- orchestration kwargs stay co-located
     def self.try_apply!(pipeline:, config:, response:, session:, strategy:, resources:, articles:,
                         scrape_target:, state:, budget:)
       Orchestrator.new(
@@ -68,7 +67,6 @@ module Html2rss
         scrape_target:, state:, budget:
       ).call
     end
-    # rubocop:enable Metrics/ParameterLists
 
     # Tournament + optional retry orchestration for {FeedPipeline::AutoFallback}.
     class Orchestrator
@@ -89,7 +87,7 @@ module Html2rss
       # @param scrape_target [Html2rss::ScrapeTarget]
       # @param state [Html2rss::FeedPipeline::AutoFallback::AttemptState]
       # @param budget [Html2rss::RequestService::Budget]
-      # rubocop:disable Metrics/ParameterLists -- orchestration context stays co-located
+      # rubocop:disable-next Metrics/ParameterLists -- orchestration context stays co-located
       def initialize(pipeline:, config:, response:, session:, strategy:, resources:, articles:,
                      scrape_target:, state:, budget:)
         @pipeline = pipeline
@@ -103,11 +101,10 @@ module Html2rss
         @state = state
         @budget = budget
       end
-      # rubocop:enable Metrics/ParameterLists
 
       ##
       # @return [ApplyOutcome, nil]
-      # rubocop:disable Metrics/MethodLength -- eligibility + tournament + retry path
+      # rubocop:disable-next Metrics/MethodLength -- eligibility + tournament + retry path
       def call
         return unless eligible?
 
@@ -131,7 +128,6 @@ module Html2rss
         Log.warn("FeedResolution: entry resolution retry failed (#{error.class})")
         nil
       end
-      # rubocop:enable Metrics/MethodLength
 
       private
 
@@ -192,7 +188,7 @@ module Html2rss
       # @param config [Html2rss::Config]
       # @param articles [Array<Html2rss::Article>]
       # @param surface_category [Symbol, nil]
-      # rubocop:disable Metrics/ParameterLists -- tournament context stays co-located
+      # rubocop:disable-next Metrics/ParameterLists -- tournament context stays co-located
       def initialize(entry_url:, response:, session:, config:, articles:, surface_category: nil)
         raise ArgumentError, 'articles must be an Array' unless articles.is_a?(Array)
 
@@ -203,11 +199,10 @@ module Html2rss
         @articles = articles
         @surface_category = surface_category
       end
-      # rubocop:enable Metrics/ParameterLists
 
       ##
       # @return [Result]
-      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- policy → candidates → probe → select
+      # rubocop:disable-next Metrics/AbcSize, Metrics/MethodLength -- policy → candidates → probe → select
       def call
         return skip(:policy_skip) unless Policy.resolve?(
           config:, articles:, surface_category:
@@ -226,7 +221,6 @@ module Html2rss
 
         apply(winner, probe_count: scored.size)
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
       private
 

data/lib/html2rss/html/article_extractor/heading_extractor.rb

@@ -19,26 +19,22 @@ module Html2rss
             tags = article_tag.css(HEADING_TAGS.join(','))
             if tags.any?
               select_best_heading(tags)
-            elsif fallback_anchorless && selected_anchor.nil?
-              fallback_heading(article_tag)
+            else
+              labeled = heading_from_aria_or_title(article_tag)
+              return labeled if labeled
+
+              fallback_heading(article_tag) if fallback_anchorless && selected_anchor.nil?
             end
           end
 
           private
 
           def select_best_heading(tags)
-            min_tag_name = tags.map(&:name).min
-            best_tag = nil
-            max_size = -1
-
-            tags.each do |tag|
-              next if tag.name != min_tag_name
-
-              size = Navigator::TextExtractor.call(tag)&.size.to_i
-              (best_tag = tag) && (max_size = size) if size > max_size
-            end
-
-            best_tag
+            tagged = tags.map { |tag| [Probe.tag(tag), tag] }
+            min_tag_name = tagged.map(&:first).min
+            tagged.select { |name, _tag| name == min_tag_name }
+                  .max_by { |_name, tag| Navigator::TextExtractor.call(tag)&.size.to_i }
+                  &.last
           end
 
           def fallback_heading(article_tag)
@@ -47,6 +43,20 @@ module Html2rss
             )
             fallback_tags.find { |t| !Navigator::TextExtractor.call(t).to_s.strip.empty? }
           end
+
+          def heading_from_aria_or_title(article_tag)
+            article_tag.css('[aria-label]').each do |node|
+              next if node['aria-label'].to_s.strip.empty?
+
+              return node
+            end
+            article_tag.css('[title]').each do |node|
+              next if node['title'].to_s.strip.empty?
+
+              return node
+            end
+            nil
+          end
         end
       end
     end

data/lib/html2rss/html/article_extractor.rb

@@ -5,7 +5,7 @@ module Html2rss
     ##
     # ArticleExtractor is responsible for extracting details (headline, url, images, etc.)
     # from an article_tag DOM node. DOM chrome helpers live on {Navigator}.
-    # rubocop:disable Metrics/ClassLength -- leftover re-extract stays with field extractors
+    # rubocop:disable-next Metrics/ClassLength -- leftover re-extract stays with field extractors
     class ArticleExtractor
       class << self
         ##
@@ -79,7 +79,7 @@ module Html2rss
         Url.from_relative("##{id}", base_url) if id
       end
 
-      # rubocop:disable Metrics/CyclomaticComplexity
+      # rubocop:disable-next Metrics/CyclomaticComplexity
       def extract_title
         source = heading || selected_anchor
         title_text = source ? Navigator.extract_visible_text(source) : fallback_anchorless_title
@@ -88,7 +88,6 @@ module Html2rss
         kicker = kicker_node ? Navigator.extract_visible_text(kicker_node).to_s.strip : nil
         kicker && !kicker.empty? && !title_text.include?(kicker) ? "#{kicker}: #{title_text}" : title_text
       end
-      # rubocop:enable Metrics/CyclomaticComplexity
 
       def fallback_anchorless_title
         return unless @fallback_anchorless && selected_anchor.nil?
@@ -130,11 +129,8 @@ module Html2rss
       end
 
       def heading_or_anchor_item?
-        heading_item? || article_tag.name.to_s == 'a'
-      end
-
-      def heading_item?
-        Navigator::HEADING_TAGS.include?(article_tag.name.to_s)
+        tag = Probe.tag(article_tag)
+        Navigator::HEADING_TAGS.include?(tag) || tag == 'a'
       end
 
       def heading_or_anchor_miss?(title, lines, published_at)
@@ -207,6 +203,5 @@ module Html2rss
 
       def extract_enclosures = EnclosureExtractor.call(article_tag, base_url)
     end
-    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/html2rss/html/feed_link.rb

@@ -25,8 +25,10 @@ module Html2rss
         end
 
         def feed_mime_type(type)
-          media_type = type.to_s.split(';', 2).first.strip.downcase
-          media_type if media_type in 'application/rss+xml' | 'application/atom+xml'
+          return Probe::APPLICATION_RSS_XML if Probe.mime_match?(type, Probe::APPLICATION_RSS_XML)
+          return Probe::APPLICATION_ATOM_XML if Probe.mime_match?(type, Probe::APPLICATION_ATOM_XML)
+
+          nil
         end
       end
     end

data/lib/html2rss/html/navigator.rb

@@ -11,9 +11,6 @@ module Html2rss
       # Element tags that indicate ignored DOM chrome when found in a container path.
       IGNORED_CONTAINER_TAGS = %w[nav footer header svg script style].to_set.freeze
 
-      # Layout roots and chrome tags excluded from class-clustering candidate nodes.
-      CLUSTER_EXCLUDED_TAGS = Set['html', 'body', 'nav', 'footer', 'header', 'svg', 'script', 'style'].freeze
-
       # Ancestor tags that usually indicate navigation/utility regions inside a content container.
       UTILITY_LANDMARK_TAGS = %w[nav aside footer menu].to_set.freeze
 
@@ -48,43 +45,11 @@ module Html2rss
         # @param article_tag [Nokogiri::XML::Node] article-like container to search within
         # @return [Nokogiri::XML::Node, nil] first eligible descendant anchor
         def main_anchor_for(article_tag)
-          return article_tag if article_tag.name == 'a' && article_tag.matches?(MAIN_ANCHOR_SELECTOR)
+          return article_tag if Probe.tag(article_tag) == 'a' && article_tag.matches?(MAIN_ANCHOR_SELECTOR)
 
           article_tag.at_css(MAIN_ANCHOR_SELECTOR)
         end
 
-        ##
-        # @param node [Nokogiri::XML::Node]
-        # @param cache [Hash, nil] identity cache used to store results (must use compare_by_identity)
-        # @return [Boolean] true when the node belongs to ignored DOM chrome
-        # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
-        def ignored_container_path?(node, cache = nil)
-          return cache[node] if cache&.key?(node)
-
-          curr = node
-          visited = []
-          is_ignored = false
-
-          while curr.respond_to?(:parent) && curr
-            if cache&.key?(curr)
-              is_ignored = cache[curr]
-              break
-            end
-
-            if IGNORED_CONTAINER_TAGS.include?(curr.name)
-              is_ignored = true
-              break
-            end
-
-            visited << curr
-            curr = curr.parent
-          end
-          visited.each { |n| cache[n] = is_ignored } if cache
-
-          is_ignored
-        end
-        # rubocop:enable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
-
         ##
         # Returns the first parent that satisfies the condition.
         # If the condition is met, it returns the node itself.
@@ -93,7 +58,7 @@ module Html2rss
         # @param condition [Proc] The condition to be met.
         # @return [Nokogiri::XML::Node, nil] The first parent that satisfies the condition.
         def parent_until_condition(node, condition)
-          while node && !node.document? && node.name != 'html'
+          while node && !node.document? && Probe.tag(node) != 'html'
             return node if condition.call(node)
 
             node = node.parent
@@ -109,7 +74,7 @@ module Html2rss
           return false unless node
           return false if node.respond_to?(:document?) && node.document?
 
-          !CARD_WALK_STOP_TAGS.include?(node.name.to_s)
+          !CARD_WALK_STOP_TAGS.include?(Probe.tag(node))
         end
 
         ##
@@ -137,7 +102,7 @@ module Html2rss
         # @param tag_name [String] tag name to find in ancestors
         # @return [Nokogiri::XML::Node, nil] matching ancestor node
         def find_tag_in_ancestors(current_tag, tag_name)
-          return current_tag if current_tag.name == tag_name
+          return current_tag if Probe.tag(current_tag) == Probe.fold(tag_name)
 
           current_tag.ancestors(tag_name).first
         end

data/lib/html2rss/html/probe.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Html2rss
+  module Html
+    ##
+    # Case-insensitive DOM wire matching for MIME types, tag names, and link relations.
+    module Probe
+      # Canonical MIME type strings for script and alternate link matching.
+      APPLICATION_LD_JSON = 'application/ld+json'
+      # @see #mime_match?
+      APPLICATION_JSON = 'application/json'
+      # @see #mime_match?
+      APPLICATION_JSON_OEMBED = 'application/json+oembed'
+      # @see #mime_match?
+      APPLICATION_RSS_XML = 'application/rss+xml'
+      # @see #mime_match?
+      APPLICATION_ATOM_XML = 'application/atom+xml'
+
+      module_function
+
+      ##
+      # @param string [String, Symbol, #to_s] wire value
+      # @return [String] folded comparison key
+      def fold(string)
+        string.to_s.downcase
+      end
+
+      ##
+      # @param node [Nokogiri::XML::Node]
+      # @return [String] folded element name
+      def tag(node)
+        name = node.name
+        return fold(name) unless name.is_a?(String)
+        return name if name.ascii_only? && !name.match?(/[A-Z]/)
+
+        fold(name)
+      end
+
+      ##
+      # @param type [String, Symbol, #to_s, nil] MIME type attribute value
+      # @return [String] media type without parameters, folded
+      def mime_base(type)
+        raw = type.to_s
+        return fold(raw) unless raw.include?(';') || raw.match?(/\A\s|\s\z/)
+
+        fold(raw.split(';', 2).first.to_s.strip)
+      end
+
+      ##
+      # @param actual [String, Symbol, #to_s, nil] observed MIME type
+      # @param expected [Array<String>] canonical MIME types to match
+      # @return [Boolean]
+      def mime_match?(actual, *expected)
+        base = mime_base(actual)
+        expected.any? { |candidate| base == candidate || base == mime_base(candidate) }
+      end
+
+      ##
+      # @param doc [Nokogiri::XML::Node]
+      # @param mime_types [Array<String>] optional MIME filters (folded once per call)
+      # @return [Array<Nokogiri::XML::Element>]
+      def scripts(doc, *mime_types)
+        return doc.css('script') if mime_types.empty?
+
+        allowed = mime_types.to_set { |mime| mime_base(mime) }
+        doc.css('script').select { |script| allowed.include?(mime_base(script['type'])) }
+      end
+
+      ##
+      # @param doc [Nokogiri::XML::Node]
+      # @param rel [String] link rel token
+      # @param mime [String, nil] optional MIME filter
+      # @return [Array<Nokogiri::XML::Element>]
+      def alternate_links(doc, rel:, mime: nil)
+        nodes = doc.css(%(link[rel~="#{rel}"][href]))
+        return nodes if mime.nil?
+
+        nodes.select { |node| mime_match?(node['type'], mime) }
+      end
+    end
+  end
+end

data/lib/html2rss/html/sst_article_extractor.rb

@@ -7,7 +7,7 @@ module Html2rss
     ##
     # Builds an {Html2rss::Article} from an SST segment / ranked segment.
     # Port of Html::ArticleExtractor field logic onto SST::Node.
-    # rubocop:disable Metrics/ClassLength -- SST field extractors colocated for parity with ArticleExtractor
+    # rubocop:disable-next Metrics/ClassLength -- SST field extractors colocated for parity with ArticleExtractor
     class SstArticleExtractor
       # CSS class tokens that mark kicker / eyebrow text (excluded from titles).
       KICKER_CLASS_PATTERN = /kicker|eyebrow|pre-title|pretitle|overline/i
@@ -390,6 +390,5 @@ module Html2rss
         end
       end
     end
-    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/html2rss/link_destination/noise_policy.rb

@@ -21,7 +21,7 @@ module Html2rss
       # @param heading_anchor [Boolean]
       # @param utility_landmark_ancestor [Boolean] pre-computed by Segmenter tree walk
       # @return [Boolean]
-      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/ParameterLists, Metrics/PerceivedComplexity, Lint/UnusedMethodArgument
+      # rubocop:disable-next Metrics/CyclomaticComplexity, Metrics/ParameterLists, Metrics/PerceivedComplexity, Lint/UnusedMethodArgument
       def noise_anchor?(text:, destination_facts:, anchor: nil, container: nil,
                         heading_anchor: false, utility_landmark_ancestor: false)
         return true unless destination_facts
@@ -35,7 +35,6 @@ module Html2rss
           icon_only_anchor?(anchor, text) ||
           utility_landmark_ancestor
       end
-      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/ParameterLists, Metrics/PerceivedComplexity, Lint/UnusedMethodArgument
 
       private
 

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).