html2rss 0.30.0 → 0.32.0

data/lib/html2rss/auto_source/scraper/microdata.rb

@@ -17,6 +17,11 @@ module Html2rss
         # @return [Symbol] scraper config key
         def self.options_key = :microdata
 
+        ##
+        # @param _opts [Hash] unused options
+        # @return [Integer]
+        def self.request_slots(_opts = {}) = 0
+
         class << self
           # @param parsed_body [Nokogiri::HTML::Document, nil] parsed HTML document
           def articles?(parsed_body)
@@ -81,6 +86,9 @@ module Html2rss
           @url = url
         end
 
+        # @return [Boolean]
+        def extractable? = self.class.articles?(parsed_body)
+
         ##
         # Iterates over normalized article hashes extracted from supported Microdata roots.
         #

data/lib/html2rss/auto_source/scraper/microformats2.rb

@@ -18,6 +18,11 @@ module Html2rss
         # @return [Symbol] scraper config key
         def self.options_key = :microformats2
 
+        ##
+        # @param _opts [Hash] unused options
+        # @return [Integer]
+        def self.request_slots(_opts = {}) = 0
+
         class << self
           # @param parsed_body [Nokogiri::HTML::Document, nil] parsed HTML document
           # @return [Boolean] whether Microformats2 h-entry elements exist
@@ -38,6 +43,9 @@ module Html2rss
           @url = Html2rss::Url.from_absolute(url)
         end
 
+        # @return [Boolean]
+        def extractable? = self.class.articles?(parsed_body)
+
         ##
         # Yields normalized article hashes extracted from h-entry elements.
         #

data/lib/html2rss/auto_source/scraper/native_feed.rb

@@ -51,6 +51,9 @@ module Html2rss
           @request_session = request_session
         end
 
+        # @return [Boolean]
+        def extractable? = self.class.articles?(parsed_body)
+
         ##
         # @yieldparam article [Hash{Symbol => Object}]
         # @return [Enumerator, void]

data/lib/html2rss/auto_source/scraper/schema/thing.rb

@@ -19,9 +19,6 @@ module Html2rss
             ReviewNewsArticle SatiricalArticle ScholarlyArticle SocialMediaPosting TechArticle
           ].to_set.freeze
 
-          # Attributes exposed by `#call` in generated article hashes.
-          DEFAULT_ATTRIBUTES = %i[id title description author url image published_at categories].freeze
-
           # @param schema_object [Hash{Symbol => Object}] parsed schema.org object
           # @param url [String, Html2rss::Url, nil] base URL used for relative normalization
           def initialize(schema_object, url:)
@@ -29,8 +26,10 @@ module Html2rss
             @base_url = normalized_base_url(url)
           end
 
-          # @return [Hash] the scraped article hash with DEFAULT_ATTRIBUTES
-          def call = DEFAULT_ATTRIBUTES.to_h { [_1, public_send(_1)] }
+          # @return [Hash{Symbol => Object}] scraped article attributes
+          def call
+            { id:, title:, description:, author:, url:, image:, published_at:, categories: }
+          end
 
           # @return [String, nil] stable schema object identifier
           def id

data/lib/html2rss/auto_source/scraper/schema.rb

@@ -46,6 +46,11 @@ module Html2rss
         # @return [Symbol] scraper config key
         def self.options_key = :schema
 
+        ##
+        # @param _opts [Hash] unused options
+        # @return [Integer]
+        def self.request_slots(_opts = {}) = 0
+
         class << self
           # @param parsed_body [Nokogiri::HTML::Document] parsed HTML document
           # @return [Boolean] whether the page includes supported schema types
@@ -166,6 +171,9 @@ module Html2rss
           @opts = opts
         end
 
+        # @return [Boolean]
+        def extractable? = self.class.articles?(parsed_body)
+
         ##
         # @yield [Hash] Each scraped article_hash
         # @return [Array<Hash>] the scraped article_hashes

data/lib/html2rss/auto_source/scraper/semantic_html.rb

@@ -15,6 +15,11 @@ module Html2rss
         # @return [Symbol] config key used to enable or configure this scraper
         def self.options_key = :semantic_html
 
+        ##
+        # @param _opts [Hash] unused options
+        # @return [Integer]
+        def self.request_slots(_opts = {}) = 0
+
         # @param parsed_body [Nokogiri::HTML::Document] parsed HTML document
         # @return [Boolean] true when at least one semantic container has an eligible anchor
         def self.articles?(parsed_body)

data/lib/html2rss/auto_source/scraper/sitemap.rb

@@ -54,6 +54,9 @@ module Html2rss
           @max_age_days = opts.fetch(:max_age_days, Scraper::Sitemap::Parser::DEFAULT_MAX_AGE_DAYS)
         end
 
+        # @return [Boolean]
+        def extractable? = self.class.articles?(parsed_body)
+
         ##
         # Yields article hashes from the sitemap.
         #

data/lib/html2rss/auto_source/scraper/wordpress_api.rb

@@ -56,6 +56,9 @@ module Html2rss
           @page_scope = PageScope.from(parsed_body:, url: @url)
         end
 
+        # @return [Boolean]
+        def extractable? = self.class.articles?(parsed_body)
+
         ##
         # Yields article hashes from the WordPress posts API.
         #

data/lib/html2rss/auto_source/scraper.rb

@@ -32,15 +32,18 @@ module Html2rss
         [Html].freeze
       ].freeze
 
+      # JSON response body scrapers (routed by AutoSource before SCRAPER_TIERS).
+      DOCUMENT_SCRAPERS = [JsonDocument].freeze
+
       # Flat ordered list (request slot accounting, detection helpers).
-      SCRAPERS = SCRAPER_TIERS.flatten.freeze
+      SCRAPERS = (DOCUMENT_SCRAPERS + SCRAPER_TIERS.flatten).freeze
 
       # Heuristic scrapers that share one memoized SST::Document per page.
-      HEURISTIC_SCRAPERS = [SemanticHtml, Html].freeze
+      HEURISTIC_SCRAPERS = Set[SemanticHtml, Html].freeze
       # Scrapers that accept a shared follow-up +request_session+.
-      REQUEST_SESSION_SCRAPERS = [NativeFeed, WordpressApi, Sitemap, MetaOembed].freeze
+      REQUEST_SESSION_SCRAPERS = Set[NativeFeed, WordpressApi, Sitemap, MetaOembed].freeze
       # Scrapers that consume browser-captured XHR/fetch JSON bodies.
-      CAPTURED_RESPONSE_SCRAPERS = [XhrArticles].freeze
+      CAPTURED_RESPONSE_SCRAPERS = Set[XhrArticles].freeze
 
       ##
       # Error raised when no suitable scraper is found.
@@ -51,8 +54,8 @@ module Html2rss
                            'Target a direct listing URL, configure BOTASAURUS_SCRAPER_URL, ' \
                            'or run from an environment that can complete anti-bot checks.',
           app_shell: 'app-shell surface detected (client-rendered page with little or no ' \
-                     'server-rendered article HTML). Configure BOTASAURUS_SCRAPER_URL or target a direct ' \
-                     'listing/update URL instead of a homepage or shell entrypoint.',
+                     'server-rendered article HTML). Target a direct listing/update URL instead of a ' \
+                     'homepage or shell entrypoint; a browser strategy does not add extractable markup here.',
           high_entropy_surface: 'high-entropy surface (e.g. news homepage) with few or no durable ' \
                                 'article destinations after admission. Target a section, topic, or ' \
                                 'listing/update URL instead of the site homepage.',
@@ -91,6 +94,7 @@ module Html2rss
       # @option opts [Hash] :microdata scraper toggle and configuration
       # @option opts [Hash] :microformats2 scraper toggle and configuration
       # @option opts [Hash] :json_state scraper toggle and configuration
+      # @option opts [Hash] :json_document scraper toggle and configuration
       # @option opts [Hash] :xhr_articles scraper toggle and configuration
       # @option opts [Hash] :meta_oembed scraper toggle and configuration
       # @option opts [Hash] :semantic_html scraper toggle and configuration
@@ -110,7 +114,7 @@ module Html2rss
       # @param tier [Array<Class>]
       # @return [Boolean]
       def self.heuristic_tier?(tier)
-        tier.intersect?(HEURISTIC_SCRAPERS)
+        HEURISTIC_SCRAPERS.intersect?(tier)
       end
 
       ##
@@ -139,6 +143,7 @@ module Html2rss
       # @option opts [Hash] :microdata scraper toggle and configuration
       # @option opts [Hash] :microformats2 scraper toggle and configuration
       # @option opts [Hash] :json_state scraper toggle and configuration
+      # @option opts [Hash] :json_document scraper toggle and configuration
       # @option opts [Hash] :xhr_articles scraper toggle and configuration
       # @option opts [Hash] :meta_oembed scraper toggle and configuration
       # @option opts [Hash] :semantic_html scraper toggle and configuration
@@ -163,16 +168,6 @@ module Html2rss
         scraper.new(parsed_body, url:, **kwargs, **scraper_opts)
       end
 
-      ##
-      # @param instance [Object]
-      # @param parsed_body [Nokogiri::HTML::Document]
-      # @return [Boolean]
-      def self.extractable_instance?(instance, parsed_body)
-        return instance.extractable? if instance.respond_to?(:extractable?)
-
-        instance.class.articles?(parsed_body)
-      end
-
       ##
       # @param parsed_body [Nokogiri::HTML::Document]
       # @param body [String, nil] raw response body (preferred for blocked-surface checks)

data/lib/html2rss/auto_source/segment.rb

@@ -2,9 +2,14 @@
 
 module Html2rss
   class AutoSource
+    Segment = Data.define(:root_node, :primary_link, :strategy, :position)
+
     ##
     # One candidate content block discovered by {Segmenter}.
-    Segment = Data.define(:root_node, :primary_link, :strategy, :position) do
+    class Segment
+      # Allowed Segmenter strategies.
+      STRATEGIES = Set[:semantic, :list, :cluster].freeze
+
       ##
       # @param root_node [SST::Node]
       # @param primary_link [SST::Node, nil]
@@ -17,13 +22,11 @@ module Html2rss
         unless primary_link.nil? || primary_link.is_a?(SST::Node)
           raise ArgumentError, 'primary_link must be SST::Node or nil'
         end
-        raise ArgumentError, "unknown strategy: #{strategy.inspect}" unless Segment::STRATEGIES.include?(strategy)
+        raise ArgumentError, "unknown strategy: #{strategy.inspect}" unless STRATEGIES.include?(strategy)
         raise ArgumentError, 'position must be Integer' unless position.is_a?(Integer)
 
         new(root_node:, primary_link:, strategy:, position:)
       end
     end
-    # Allowed Segmenter strategies.
-    Segment::STRATEGIES = %i[semantic list cluster].to_set.freeze
   end
 end

data/lib/html2rss/auto_source/segmenter/cluster.rb

@@ -13,15 +13,18 @@ module Html2rss
         # @param segmenter [Segmenter]
         # @return [Array<Segment>]
         def call(segmenter)
+          primary = PrimaryLink.new(segmenter)
           nodes = best_group_nodes(segmenter)
-          nodes.each_with_index.map do |node, position|
-            Segment.build(root_node: node, primary_link: nil, strategy: :cluster, position:)
+          nodes.each_with_index.filter_map do |node, position|
+            link = primary.select(node)
+            next unless link || segmenter.permit_unanchored
+
+            Segment.build(root_node: node, primary_link: link, strategy: :cluster, position:)
           end
         end
 
         def best_group_nodes(segmenter)
-          class_groups = collect_class_groups(segmenter)
-          groups = class_groups.empty? ? collect_structure_groups(segmenter) : class_groups
+          groups = collect_groups(segmenter)
           return [] if groups.empty?
 
           resolver = OverlapResolver.new(index: segmenter.index)
@@ -33,33 +36,29 @@ module Html2rss
         module_function :best_group_nodes
         private_class_method :best_group_nodes
 
-        def collect_class_groups(segmenter) # rubocop:disable Metrics/AbcSize
-          groups = Hash.new { |h, k| h[k] = [] }
+        def collect_groups(segmenter) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+          class_groups = Hash.new { |hash, key| hash[key] = [] }
+          structure_groups = Hash.new { |hash, key| hash[key] = [] }
+          min = segmenter.minimum_selector_frequency
+
           segmenter.index.each_node do |node|
             next if SST::Tags::CLUSTER_EXCLUDED_NAMES.include?(node.name)
             next if segmenter.index.ignored_chrome?(node)
 
             cls = normalize_class(node.attrs.class_names)
-            groups[cls] << node unless cls.empty?
-          end
-          groups.select { |_, nodes| nodes.size >= segmenter.minimum_selector_frequency }
-        end
-        module_function :collect_class_groups
-        private_class_method :collect_class_groups
-
-        def collect_structure_groups(segmenter) # rubocop:disable Metrics/AbcSize
-          groups = Hash.new { |h, k| h[k] = [] }
-          segmenter.index.each_node do |node|
-            next if SST::Tags::CLUSTER_EXCLUDED_NAMES.include?(node.name)
-            next if segmenter.index.ignored_chrome?(node)
+            class_groups[cls] << node unless cls.empty?
 
             sig = structure_signature(node)
-            groups[sig] << node unless sig.empty?
+            structure_groups[sig] << node unless sig.empty?
           end
-          groups.select { |_, nodes| nodes.size >= segmenter.minimum_selector_frequency }
+
+          frequent_class = class_groups.select { |_, nodes| nodes.size >= min }
+          return frequent_class unless frequent_class.empty?
+
+          structure_groups.select { |_, nodes| nodes.size >= min }
         end
-        module_function :collect_structure_groups
-        private_class_method :collect_structure_groups
+        module_function :collect_groups
+        private_class_method :collect_groups
 
         def normalize_class(class_names)
           return '' if class_names.empty?
@@ -73,7 +72,7 @@ module Html2rss
           kids = node.children
           return '' if kids.empty?
 
-          kids.map { |c| c.name.to_s }.join('>')
+          kids.map { |child| child.name.to_s }.join('>')
         end
         module_function :structure_signature
         private_class_method :structure_signature

data/lib/html2rss/auto_source/segmenter/list.rb

@@ -4,8 +4,8 @@ module Html2rss
   class AutoSource
     class Segmenter
       ##
-      # Builds repeated-list article segments from tag_path frequency
-      # (port of Discovery::ListCandidates using tag_path instead of xpath).
+      # Builds repeated-list article segments by grouping cards under a shared parent.
+      # When the document has a +main+ or +[role=main]+, anchors outside it are dropped.
       module List
         module_function
 
@@ -30,40 +30,55 @@ module Html2rss
         end
 
         def article_pairs(segmenter)
-          by_path = relevant_links_by_path(segmenter)
-          top_paths(segmenter, by_path).flat_map do |path|
-            by_path.fetch(path, []).filter_map do |node|
-              article_tag = parent_until_boundary(segmenter, node)
-              next unless article_tag
-
-              [article_tag, node]
-            end
-          end
+          top_groups(segmenter).flatten(1)
         end
         module_function :article_pairs
         private_class_method :article_pairs
 
-        def relevant_links_by_path(segmenter)
-          by_path = Hash.new { |hash, path| hash[path] = [] }
-          segmenter.index.each_node do |node|
+        def top_groups(segmenter)
+          cards_by_parent(segmenter)
+            .select { |_parent, cards| cards.size >= segmenter.minimum_selector_frequency }
+            .max_by(segmenter.use_top_selectors) { |_parent, cards| cards.size }
+            .map(&:last)
+        end
+        module_function :top_groups
+        private_class_method :top_groups
+
+        def cards_by_parent(segmenter) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+          index = segmenter.index
+          main = main_landmark(index)
+          groups = {}.compare_by_identity
+
+          index.each_node do |node|
             next unless node.link?
-            next if segmenter.index.ignored_chrome?(node)
+            next if index.ignored_chrome?(node)
             next unless relevant_anchor?(segmenter, node)
+            next if main && !inside_main?(index, node, main)
+
+            card = parent_until_boundary(segmenter, node)
+            next unless card
 
-            by_path[node.tag_path] << node
+            parent = index.parent_of(card)
+            next unless parent
+
+            (groups[parent] ||= []) << [card, node]
           end
-          by_path
+          groups
+        end
+        module_function :cards_by_parent
+        private_class_method :cards_by_parent
+
+        def main_landmark(index)
+          index.each_node.find { |node| node.name == :main || node.attrs.raw['role'] == 'main' }
         end
-        module_function :relevant_links_by_path
-        private_class_method :relevant_links_by_path
+        module_function :main_landmark
+        private_class_method :main_landmark
 
-        def top_paths(segmenter, by_path)
-          by_path.select { |_path, nodes| nodes.size >= segmenter.minimum_selector_frequency }
-                 .max_by(segmenter.use_top_selectors) { |_path, nodes| nodes.size }
-                 .map(&:first)
+        def inside_main?(index, node, main)
+          node.equal?(main) || index.descendant_of?(node, main)
         end
-        module_function :top_paths
-        private_class_method :top_paths
+        module_function :inside_main?
+        private_class_method :inside_main?
 
         def relevant_anchor?(segmenter, node)
           facts = segmenter.link_resolver.destination_facts(node)
@@ -77,12 +92,15 @@ module Html2rss
         module_function :relevant_anchor?
         private_class_method :relevant_anchor?
 
+        BOUNDARY_TAGS = Set[:body, :html].freeze
+        private_constant :BOUNDARY_TAGS
+
         def parent_until_boundary(segmenter, node)
           index = segmenter.index
-          link_counts = Hash.new { |hash, curr| hash[curr] = count_links(curr) }
+          link_counts = Hash.new { |hash, curr| hash[curr] = count_relevant_links(segmenter, curr) }
 
           index.parent_until(node, lambda { |curr|
-            return true if %i[body html].include?(curr.name)
+            return true if BOUNDARY_TAGS.include?(curr.name)
             return false if index.ignored_chrome?(curr)
 
             parent = index.parent_of(curr)
@@ -92,11 +110,16 @@ module Html2rss
         module_function :parent_until_boundary
         private_class_method :parent_until_boundary
 
-        def count_links(node)
-          node.link? ? 1 : node.descendants.count(&:link?)
+        def count_relevant_links(segmenter, node)
+          # Chrome inside a card must not stop the walk before the shared list parent.
+          if node.link?
+            relevant_anchor?(segmenter, node) ? 1 : 0
+          else
+            node.count_descendants { |child| child.link? && relevant_anchor?(segmenter, child) }
+          end
         end
-        module_function :count_links
-        private_class_method :count_links
+        module_function :count_relevant_links
+        private_class_method :count_relevant_links
       end
     end
   end

data/lib/html2rss/auto_source/segmenter.rb

@@ -7,7 +7,7 @@ module Html2rss
     #
     # Strategies:
     # - +:semantic+ — leaf article/section/li/tr/div containers with a primary link
-    # - +:list+ — repeated tag_path anchors walked to a shared container boundary
+    # - +:list+ — repeated cards grouped by parent (`main` is a filter when present)
     # - +:cluster+ — class / structure clustering for anchorless card grids
     class Segmenter
       # @param document [SST::Document]
@@ -68,11 +68,11 @@ module Html2rss
       # @param container [SST::Node]
       # @return [Boolean]
       def landmark_ancestor?(anchor, container)
-        cache = (@landmark_cache ||= {})
-        key = [anchor.object_id, container.object_id]
-        return cache[key] if cache.key?(key)
+        cache = (@landmark_cache ||= {}.compare_by_identity)
+        anchor_cache = (cache[anchor] ||= {}.compare_by_identity)
+        return anchor_cache[container] if anchor_cache.key?(container)
 
-        cache[key] = compute_landmark_ancestor?(anchor:, container:)
+        anchor_cache[container] = compute_landmark_ancestor?(anchor:, container:)
       end
 
       private

data/lib/html2rss/auto_source.rb

@@ -61,6 +61,9 @@ module Html2rss
         json_state: {
           enabled: true
         },
+        json_document: {
+          enabled: true
+        },
         xhr_articles: {
           enabled: true
         },
@@ -93,7 +96,7 @@ module Html2rss
         Scraper::SCRAPERS.sum do |scraper|
           if config.dig(:scraper, scraper.options_key, :enabled)
             opts = config.dig(:scraper, scraper.options_key)
-            scraper.respond_to?(:request_slots) ? scraper.request_slots(opts) : 0
+            scraper.request_slots(opts)
           else
             0
           end
@@ -113,6 +116,7 @@ module Html2rss
       @parsed_body = response.parsed_body
       @body = response.body
       @url = response.url
+      @json_response = response.json_response?
       @captured_responses = response.captured_responses
       @opts = opts
       @request_session = request_session
@@ -131,7 +135,12 @@ module Html2rss
     def articles
       @articles ||= extract_articles
     rescue Html2rss::AutoSource::Scraper::NoScraperFound => error
-      Log.warn "#{self.class}: no scraper matched #{url} (#{error.message})"
+      Log.warn({
+        event_name: 'auto_source.no_scraper',
+        host: url.host,
+        category: error.category,
+        message: "#{self.class}: no scraper matched #{url} (#{error.message})"
+      }.to_json)
       @admission_drops = {}.freeze
       []
     end
@@ -150,6 +159,8 @@ module Html2rss
 
     # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
     def extract_articles
+      return extract_json_document_articles if json_response?
+
       articles = []
       matched = false
       document = nil
@@ -180,7 +191,7 @@ module Html2rss
             captured_responses:
           )
           next unless instance
-          next unless Scraper.extractable_instance?(instance, parsed_body)
+          next unless instance.extractable?
 
           matched = true
           articles.concat(run_scraper(instance))
@@ -189,11 +200,55 @@ module Html2rss
 
       raise Scraper.no_scraper_found_for(parsed_body, body:) unless matched
 
+      finish_articles(articles)
+    end
+
+    def json_response?
+      @json_response
+    end
+
+    def extract_json_document_articles
+      instance = json_document_instance
+      raise Scraper::NoScraperFound.new(category: :unsupported_surface) unless instance&.extractable?
+
+      articles = run_scraper(instance)
+      raise Scraper::NoScraperFound.new(category: :unsupported_surface) if articles.empty?
+
+      finish_articles(articles)
+    end
+
+    def json_document_instance
+      Scraper.build_instance(
+        Scraper::JsonDocument,
+        parsed_body,
+        opts: @opts.fetch(:scraper, {}),
+        url:,
+        request_session:,
+        body:,
+        captured_responses:
+      )
+    end
+
+    def finish_articles(articles)
+      captured_count = articles.size
       result = Cleanup.call(articles, url:, **cleanup_options)
       @admission_drops = result.drop_tallies
+      log_admission_emptied(captured_count, result) if captured_count.positive? && result.articles.empty?
       result.articles.first(article_limit)
     end
 
+    def log_admission_emptied(captured_count, result)
+      payload = {
+        event_name: 'auto_source.admission_emptied',
+        host: url.host,
+        captured_count:,
+        drop_tallies: result.drop_tallies
+      }
+      hint = Cleanup.admission_hint(result.drop_tallies)
+      payload[:hint] = hint if hint
+      Log.warn(payload.to_json)
+    end
+
     def enough_articles?(articles)
       return false if articles.size < article_limit
 

data/lib/html2rss/batch.rb

@@ -10,8 +10,10 @@ module Html2rss
     # Default worker threads for batch operations.
     DEFAULT_CONCURRENCY = 5
 
+    BatchResult = Data.define(:total, :successful, :results)
+
     # Value object representing the outcome of a batch operation.
-    BatchResult = Data.define(:total, :successful, :results) do
+    class BatchResult
       ##
       # @return [Hash{Symbol => Object}]
       def to_h

data/lib/html2rss/capture/README.md

@@ -27,7 +27,9 @@ File.write('my-feed.yml', result.yaml)
 rss = Html2rss.apply(result.config)
 ```
 
-`Html2rss.capture` and `Capture.build` both return a `CaptureResult` with YAML (`#yaml`, includes the schema modeline) and quality meta (`has_selectors`, `segment_strategy`, `admission_drops`, `selected_strategy`, `native_feed`).
+`Html2rss.capture` and `Capture.build` both return a `CaptureResult` with YAML (`#yaml`, includes the schema modeline) and quality meta (`has_selectors`, `segment_strategy`, `admission_drops`, `selected_strategy`, `native_feed`, `candidates`).
+
+`#candidates` is ranked discovery evidence: `{ items:, title:, link:, published: }` arrays (best-first, deduplicated). Items entries are `{ selector:, enhance:, sample: }`; field entries are `{ selector:, sample: }`. `sample` stays on `#candidates` only — emitted YAML is still `items` + `enhance`. Buckets may be empty when evidence is missing. The default `a[href]` YAML fallback is not listed as discovered evidence.
 
 **Wire vs internal:** user-facing **`Html2rss.apply`** ships RSS from a config Hash. Pipeline internals **`Html2rss.feed` / `feed_result`** stay unchanged — use `apply` in CLI/MCP/docs examples, not `feed`.
 
@@ -58,13 +60,13 @@ html2rss capture https://example.com --explain   # quality JSON on stderr; YAML
 1. **Request** — `FeedPipeline` (AutoFallback when `:auto`)
 2. **Discover** — AutoSource extracts admitted articles
 3. **Segment** — try SST Segmenter strategies `:list` → `:cluster` → `:semantic`
-4. **Gate** — emit items selector only when ≥ `MIN_SELECTOR_MATCHES` (2) articles match
-5. **Assemble** — `{ items: { selector:, enhance: true } }` plus channel
+4. **Gate** — keep a derived items selector when ≥ `MIN_SELECTOR_MATCHES` (2) articles match
+5. **Assemble** — `{ items: { selector:, enhance: } }` plus channel. HTML derivation misses fall back to `Selectors::DEFAULT_ITEMS_SELECTOR` (`segment_strategy: :default`) instead of omitting selectors.
 
 ## Constraints
 
 - Selector quality depends on page structure; treat output as a first draft.
-- When the quality gate fails, selectors are omitted (`has_selectors: false`) rather than inventing attribute selectors.
+- When HTML derivation misses (no articles, no SST document, fewer than `MIN_SELECTOR_MATCHES` pairs, or a rescued `ArgumentError`), Capture emits the default items selector with `segment_strategy: :default`. `enhance` still follows admission evidence (false when chrome drops are high). Non-HTML responses still omit selectors.
 - Botasaurus hops need `BOTASAURUS_SCRAPER_URL`.
 
 See also {Html2rss::AutoSource} for article discovery and {Html2rss::FeedPipeline} for the `:auto` request chain.