context.dev 2.0.0 → 2.2.0

data/lib/context_dev/models/monitor_update_response.rb

@@ -61,6 +61,15 @@ module ContextDev
       #   @return [Time]
       required :updated_at, Time
 
+      # @!attribute baseline
+      #   Current baseline: the last observed value the monitor compares new snapshots
+      #   against. Its shape follows `target.type` (page/sitemap/extract). Only populated
+      #   on GET /monitors/{monitor_id}; null until the first baseline run completes (and
+      #   after a target or change_detection update, which resets the baseline).
+      #
+      #   @return [ContextDev::Models::MonitorUpdateResponse::Baseline::MonitorsPageBaseline, ContextDev::Models::MonitorUpdateResponse::Baseline::MonitorsSitemapBaseline, ContextDev::Models::MonitorUpdateResponse::Baseline::MonitorsExtractBaseline, nil]
+      optional :baseline, union: -> { ContextDev::Models::MonitorUpdateResponse::Baseline }, nil?: true
+
       # @!attribute last_change_at
       #
       #   @return [Time, nil]
@@ -94,7 +103,7 @@ module ContextDev
       #   @return [ContextDev::Models::MonitorUpdateResponse::Webhook, nil]
       optional :webhook, -> { ContextDev::Models::MonitorUpdateResponse::Webhook }, nil?: true
 
-      # @!method initialize(id:, change_detection:, created_at:, mode:, name:, schedule:, status:, target:, updated_at:, last_change_at: nil, last_error: nil, last_run_at: nil, next_run_at: nil, tags: nil, webhook: nil)
+      # @!method initialize(id:, change_detection:, created_at:, mode:, name:, schedule:, status:, target:, updated_at:, baseline: nil, last_change_at: nil, last_error: nil, last_run_at: nil, next_run_at: nil, tags: nil, webhook: nil)
       #   Some parameter documentations has been truncated, see
       #   {ContextDev::Models::MonitorUpdateResponse} for more details.
       #
@@ -119,6 +128,8 @@ module ContextDev
       #
       #   @param updated_at [Time]
       #
+      #   @param baseline [ContextDev::Models::MonitorUpdateResponse::Baseline::MonitorsPageBaseline, ContextDev::Models::MonitorUpdateResponse::Baseline::MonitorsSitemapBaseline, ContextDev::Models::MonitorUpdateResponse::Baseline::MonitorsExtractBaseline, nil] Current baseline: the last observed value the monitor compares new snapshots aga
+      #
       #   @param last_change_at [Time, nil]
       #
       #   @param last_error [ContextDev::Models::MonitorUpdateResponse::LastError, nil] Error from the most recent failed run; null when the last run succeeded.
@@ -142,7 +153,7 @@ module ContextDev
         # Detect exact changes. For page targets, this means visible text diffs. For sitemap targets, this means URL additions and removals.
         variant :exact, -> { ContextDev::Models::MonitorUpdateResponse::ChangeDetection::Exact }
 
-        # Detect meaning-level changes that match a natural language query.
+        # Detect meaning-level changes to tracked page content, ignoring cosmetic or paraphrase-only differences. Which changes are meaningful is judged against the extract target's `instructions` (and `schema`, when provided).
         variant :semantic, -> { ContextDev::Models::MonitorUpdateResponse::ChangeDetection::Semantic }
 
         class Exact < ContextDev::Internal::Type::BaseModel
@@ -159,11 +170,6 @@ module ContextDev
         end
 
         class Semantic < ContextDev::Internal::Type::BaseModel
-          # @!attribute query
-          #
-          #   @return [String]
-          required :query, String
-
           # @!attribute type
           #
           #   @return [Symbol, :semantic]
@@ -174,10 +180,11 @@ module ContextDev
           #   @return [Float, nil]
           optional :confidence_threshold, Float
 
-          # @!method initialize(query:, confidence_threshold: nil, type: :semantic)
-          #   Detect meaning-level changes that match a natural language query.
+          # @!method initialize(confidence_threshold: nil, type: :semantic)
+          #   Detect meaning-level changes to tracked page content, ignoring cosmetic or
+          #   paraphrase-only differences. Which changes are meaningful is judged against the
+          #   extract target's `instructions` (and `schema`, when provided).
           #
-          #   @param query [String]
           #   @param confidence_threshold [Float]
           #   @param type [Symbol, :semantic]
         end
@@ -285,10 +292,10 @@ module ContextDev
         # Watch a single web page.
         variant :page, -> { ContextDev::Models::MonitorUpdateResponse::Target::Page }
 
-        # Watch a sitemap for URL additions and removals. Crawled URLs are normalized (lowercased host, no trailing slash/fragment) and scoped to the monitored site and its subdomains before comparison. A new URL set must be observed on two consecutive runs before a change is reported, suppressing one-run crawl flaps.
+        # Watch a sitemap for URL additions and removals. Crawled URLs are normalized (lowercased host, no trailing slash/fragment) and scoped to the monitored site and its subdomains before comparison. On a detected difference the sitemap is re-fetched within the same run and only URLs both observations agree on are reported, suppressing transient crawl flaps.
         variant :sitemap, -> { ContextDev::Models::MonitorUpdateResponse::Target::Sitemap }
 
-        # Watch a site's extracted structured data.
+        # Watch the monitor-relevant pages of a site for meaningful changes. A crawl guided by `schema`/`instructions` selects up to `max_pages` relevant pages to track; each run re-checks exactly those pages, and confirmed content changes are judged for relevance against the monitor's `instructions` (and `schema`, when provided). The tracked page set is refreshed by a periodic re-discovery crawl.
         variant :extract, -> { ContextDev::Models::MonitorUpdateResponse::Target::Extract }
 
         class Page < ContextDev::Internal::Type::BaseModel
@@ -351,8 +358,9 @@ module ContextDev
           # @!method initialize(url:, exclude: nil, include: nil, max_urls: nil, type: :sitemap)
           #   Watch a sitemap for URL additions and removals. Crawled URLs are normalized
           #   (lowercased host, no trailing slash/fragment) and scoped to the monitored site
-          #   and its subdomains before comparison. A new URL set must be observed on two
-          #   consecutive runs before a change is reported, suppressing one-run crawl flaps.
+          #   and its subdomains before comparison. On a detected difference the sitemap is
+          #   re-fetched within the same run and only URLs both observations agree on are
+          #   reported, suppressing transient crawl flaps.
           #
           #   @param url [String] Sitemap URL to monitor.
           #
@@ -366,6 +374,13 @@ module ContextDev
         end
 
         class Extract < ContextDev::Internal::Type::BaseModel
+          # @!attribute instructions
+          #   Natural-language instructions guiding which pages and facts to track and which
+          #   changes to report.
+          #
+          #   @return [String]
+          required :instructions, String
+
           # @!attribute type
           #
           #   @return [Symbol, :extract]
@@ -382,12 +397,6 @@ module ContextDev
           #   @return [Boolean, nil]
           optional :follow_subdomains, ContextDev::Internal::Type::Boolean
 
-          # @!attribute instructions
-          #   Optional natural-language instructions guiding what to extract.
-          #
-          #   @return [String, nil]
-          optional :instructions, String
-
           # @!attribute max_depth
           #   Optional maximum link depth from the starting URL (0 = only the starting page).
           #
@@ -395,35 +404,45 @@ module ContextDev
           optional :max_depth, Integer
 
           # @!attribute max_pages
-          #   Maximum number of pages to analyze during extraction.
+          #   Maximum number of pages to track.
           #
           #   @return [Integer, nil]
           optional :max_pages, Integer
 
           # @!attribute schema
-          #   JSON Schema describing the structured data to extract and watch for changes. If
-          #   omitted, a default summary + key-points schema is used.
+          #   JSON Schema describing the data you care about. It is used three ways: it guides
+          #   which pages are selected for tracking, it gives the change judge extra context
+          #   on which changes matter (alongside `instructions`), and it defines the shape of
+          #   the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most
+          #   about once a day). It is not a response format for changes: change events and
+          #   webhook payloads always contain diffs, summaries, and evidence excerpts — never
+          #   data in this schema's shape. If omitted, a default summary + key-points schema
+          #   is used.
           #
           #   @return [Hash{Symbol=>Object}, nil]
           optional :schema, ContextDev::Internal::Type::HashOf[ContextDev::Internal::Type::Unknown]
 
-          # @!method initialize(url:, follow_subdomains: nil, instructions: nil, max_depth: nil, max_pages: nil, schema: nil, type: :extract)
+          # @!method initialize(instructions:, url:, follow_subdomains: nil, max_depth: nil, max_pages: nil, schema: nil, type: :extract)
           #   Some parameter documentations has been truncated, see
           #   {ContextDev::Models::MonitorUpdateResponse::Target::Extract} for more details.
           #
-          #   Watch a site's extracted structured data.
+          #   Watch the monitor-relevant pages of a site for meaningful changes. A crawl
+          #   guided by `schema`/`instructions` selects up to `max_pages` relevant pages to
+          #   track; each run re-checks exactly those pages, and confirmed content changes are
+          #   judged for relevance against the monitor's `instructions` (and `schema`, when
+          #   provided). The tracked page set is refreshed by a periodic re-discovery crawl.
+          #
+          #   @param instructions [String] Natural-language instructions guiding which pages and facts to track and which c
           #
           #   @param url [String] Root URL to extract structured data from.
           #
           #   @param follow_subdomains [Boolean]
           #
-          #   @param instructions [String] Optional natural-language instructions guiding what to extract.
-          #
           #   @param max_depth [Integer] Optional maximum link depth from the starting URL (0 = only the starting page).
           #
-          #   @param max_pages [Integer] Maximum number of pages to analyze during extraction.
+          #   @param max_pages [Integer] Maximum number of pages to track.
           #
-          #   @param schema [Hash{Symbol=>Object}] JSON Schema describing the structured data to extract and watch for changes. If
+          #   @param schema [Hash{Symbol=>Object}] JSON Schema describing the data you care about. It is used three ways: it guides
           #
           #   @param type [Symbol, :extract]
         end
@@ -432,6 +451,116 @@ module ContextDev
         #   @return [Array(ContextDev::Models::MonitorUpdateResponse::Target::Page, ContextDev::Models::MonitorUpdateResponse::Target::Sitemap, ContextDev::Models::MonitorUpdateResponse::Target::Extract)]
       end
 
+      # Current baseline: the last observed value the monitor compares new snapshots
+      # against. Its shape follows `target.type` (page/sitemap/extract). Only populated
+      # on GET /monitors/{monitor_id}; null until the first baseline run completes (and
+      # after a target or change_detection update, which resets the baseline).
+      #
+      # @see ContextDev::Models::MonitorUpdateResponse#baseline
+      module Baseline
+        extend ContextDev::Internal::Type::Union
+
+        # Current baseline of a `page` monitor: the visible page text as last observed.
+        variant -> { ContextDev::Models::MonitorUpdateResponse::Baseline::MonitorsPageBaseline }
+
+        # Current baseline of a `sitemap` monitor: the normalized URL set as last observed.
+        variant -> { ContextDev::Models::MonitorUpdateResponse::Baseline::MonitorsSitemapBaseline }
+
+        # Current baseline of an `extract` monitor: the pages it tracks and the structured data as last extracted.
+        variant -> { ContextDev::Models::MonitorUpdateResponse::Baseline::MonitorsExtractBaseline }
+
+        class MonitorsPageBaseline < ContextDev::Internal::Type::BaseModel
+          # @!attribute captured_at
+          #   When this baseline was last captured or replaced.
+          #
+          #   @return [Time]
+          required :captured_at, Time
+
+          # @!attribute text
+          #   The page's visible text as last observed.
+          #
+          #   @return [String]
+          required :text, String
+
+          # @!method initialize(captured_at:, text:)
+          #   Current baseline of a `page` monitor: the visible page text as last observed.
+          #
+          #   @param captured_at [Time] When this baseline was last captured or replaced.
+          #
+          #   @param text [String] The page's visible text as last observed.
+        end
+
+        class MonitorsSitemapBaseline < ContextDev::Internal::Type::BaseModel
+          # @!attribute captured_at
+          #   When this baseline was last captured or replaced.
+          #
+          #   @return [Time]
+          required :captured_at, Time
+
+          # @!attribute url_count
+          #   Number of URLs in the baseline.
+          #
+          #   @return [Integer]
+          required :url_count, Integer
+
+          # @!attribute urls
+          #   The sitemap URLs as last observed (sorted, normalized).
+          #
+          #   @return [Array<String>]
+          required :urls, ContextDev::Internal::Type::ArrayOf[String]
+
+          # @!method initialize(captured_at:, url_count:, urls:)
+          #   Current baseline of a `sitemap` monitor: the normalized URL set as last
+          #   observed.
+          #
+          #   @param captured_at [Time] When this baseline was last captured or replaced.
+          #
+          #   @param url_count [Integer] Number of URLs in the baseline.
+          #
+          #   @param urls [Array<String>] The sitemap URLs as last observed (sorted, normalized).
+        end
+
+        class MonitorsExtractBaseline < ContextDev::Internal::Type::BaseModel
+          # @!attribute captured_at
+          #   When this baseline was last captured or replaced.
+          #
+          #   @return [Time]
+          required :captured_at, Time
+
+          # @!attribute data
+          #   The extracted structured data, matching the monitor's extraction schema (same
+          #   shape as the /web/extract endpoint's `data`). Refreshed when the monitor
+          #   re-discovers its page set (at most about once a day); `null` when no extraction
+          #   has been captured yet.
+          #
+          #   @return [Object]
+          required :data, ContextDev::Internal::Type::Unknown
+
+          # @!attribute urls_analyzed
+          #   The page URLs the monitor tracks and analyzes for changes.
+          #
+          #   @return [Array<String>]
+          required :urls_analyzed, ContextDev::Internal::Type::ArrayOf[String]
+
+          # @!method initialize(captured_at:, data:, urls_analyzed:)
+          #   Some parameter documentations has been truncated, see
+          #   {ContextDev::Models::MonitorUpdateResponse::Baseline::MonitorsExtractBaseline}
+          #   for more details.
+          #
+          #   Current baseline of an `extract` monitor: the pages it tracks and the structured
+          #   data as last extracted.
+          #
+          #   @param captured_at [Time] When this baseline was last captured or replaced.
+          #
+          #   @param data [Object] The extracted structured data, matching the monitor's extraction schema (same sh
+          #
+          #   @param urls_analyzed [Array<String>] The page URLs the monitor tracks and analyzes for changes.
+        end
+
+        # @!method self.variants
+        #   @return [Array(ContextDev::Models::MonitorUpdateResponse::Baseline::MonitorsPageBaseline, ContextDev::Models::MonitorUpdateResponse::Baseline::MonitorsSitemapBaseline, ContextDev::Models::MonitorUpdateResponse::Baseline::MonitorsExtractBaseline)]
+      end
+
       # @see ContextDev::Models::MonitorUpdateResponse#last_error
       class LastError < ContextDev::Internal::Type::BaseModel
         # @!attribute code

data/lib/context_dev/resources/brand.rb

@@ -5,11 +5,13 @@ module ContextDev
     class Brand
       # Retrieve logos, backdrops, colors, industry, description, and more. Provide
       # exactly one lookup identifier in the request body: a domain, company name, email
-      # address, stock ticker, or transaction descriptor.
+      # address, stock ticker, transaction descriptor, or direct URL. Note:
+      # `by_direct_url` fetches brand data only from the provided URL — not from the
+      # entire internet.
       #
       # @overload retrieve(body:, request_options: {})
       #
-      # @param body [ContextDev::Models::BrandRetrieveParams::Body::ByDomain, ContextDev::Models::BrandRetrieveParams::Body::ByName, ContextDev::Models::BrandRetrieveParams::Body::ByEmail, ContextDev::Models::BrandRetrieveParams::Body::ByTicker, ContextDev::Models::BrandRetrieveParams::Body::ByTransaction] Exactly one lookup type must be provided.
+      # @param body [ContextDev::Models::BrandRetrieveParams::Body::ByDomain, ContextDev::Models::BrandRetrieveParams::Body::ByName, ContextDev::Models::BrandRetrieveParams::Body::ByEmail, ContextDev::Models::BrandRetrieveParams::Body::ByTicker, ContextDev::Models::BrandRetrieveParams::Body::ByDirectURL, ContextDev::Models::BrandRetrieveParams::Body::ByTransaction] Exactly one lookup type must be provided.
       #
       # @param request_options [ContextDev::RequestOptions, Hash{Symbol=>Object}, nil]
       #

data/lib/context_dev/resources/monitors.rb

@@ -122,7 +122,7 @@ module ContextDev
       #
       # @param q [String] Free-text search term, matched against the fields named in `search_by`.
       #
-      # @param search_by [Array<Symbol, ContextDev::Models::MonitorListParams::SearchBy>] Comma-separated fields to search with `q`. Defaults to all of them. Note `query`
+      # @param search_by [Array<Symbol, ContextDev::Models::MonitorListParams::SearchBy>] Comma-separated fields to search with `q`. Defaults to all of them. Note `instru
       #
       # @param search_type [Symbol, ContextDev::Models::MonitorListParams::SearchType] `prefix` for as-you-type prefix matching (default), `exact` for full-token match
       #

data/lib/context_dev/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ContextDev
-  VERSION = "2.0.0"
+  VERSION = "2.2.0"
 end

data/rbi/context_dev/models/brand_retrieve_params.rbi

@@ -19,6 +19,7 @@ module ContextDev
             ContextDev::BrandRetrieveParams::Body::ByName,
             ContextDev::BrandRetrieveParams::Body::ByEmail,
             ContextDev::BrandRetrieveParams::Body::ByTicker,
+            ContextDev::BrandRetrieveParams::Body::ByDirectURL,
             ContextDev::BrandRetrieveParams::Body::ByTransaction
           )
         )
@@ -33,6 +34,7 @@ module ContextDev
               ContextDev::BrandRetrieveParams::Body::ByName::OrHash,
               ContextDev::BrandRetrieveParams::Body::ByEmail::OrHash,
               ContextDev::BrandRetrieveParams::Body::ByTicker::OrHash,
+              ContextDev::BrandRetrieveParams::Body::ByDirectURL::OrHash,
               ContextDev::BrandRetrieveParams::Body::ByTransaction::OrHash
             ),
           request_options: ContextDev::RequestOptions::OrHash
@@ -54,6 +56,7 @@ module ContextDev
                 ContextDev::BrandRetrieveParams::Body::ByName,
                 ContextDev::BrandRetrieveParams::Body::ByEmail,
                 ContextDev::BrandRetrieveParams::Body::ByTicker,
+                ContextDev::BrandRetrieveParams::Body::ByDirectURL,
                 ContextDev::BrandRetrieveParams::Body::ByTransaction
               ),
             request_options: ContextDev::RequestOptions
@@ -74,6 +77,7 @@ module ContextDev
               ContextDev::BrandRetrieveParams::Body::ByName,
               ContextDev::BrandRetrieveParams::Body::ByEmail,
               ContextDev::BrandRetrieveParams::Body::ByTicker,
+              ContextDev::BrandRetrieveParams::Body::ByDirectURL,
               ContextDev::BrandRetrieveParams::Body::ByTransaction
             )
           end
@@ -3054,6 +3058,69 @@ module ContextDev
           end
         end
 
+        class ByDirectURL < ContextDev::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                ContextDev::BrandRetrieveParams::Body::ByDirectURL,
+                ContextDev::Internal::AnyHash
+              )
+            end
+
+          # Full http(s) URL to fetch brand data from (e.g.,
+          # 'https://stripe.com/enterprise'). Only this URL is fetched — not the entire
+          # internet.
+          sig { returns(String) }
+          attr_accessor :direct_url
+
+          # Discriminator for direct-URL-based brand retrieval.
+          sig { returns(Symbol) }
+          attr_accessor :type
+
+          # Optional timeout in milliseconds for the request. If the request takes longer
+          # than this value, it will be aborted with a 408 status code. Maximum allowed
+          # value is 300000ms (5 minutes).
+          sig { returns(T.nilable(Integer)) }
+          attr_reader :timeout_ms
+
+          sig { params(timeout_ms: Integer).void }
+          attr_writer :timeout_ms
+
+          # Retrieve brand data by fetching the provided URL directly. Note: if you use
+          # this, brand data is fetched only from the provided URL — not from the entire
+          # internet — so results are limited to what that single page contains. No domain
+          # resolution, database lookup, or cross-source enrichment is performed. Cannot be
+          # combined with domain, name, email, or ticker.
+          sig do
+            params(
+              direct_url: String,
+              timeout_ms: Integer,
+              type: Symbol
+            ).returns(T.attached_class)
+          end
+          def self.new(
+            # Full http(s) URL to fetch brand data from (e.g.,
+            # 'https://stripe.com/enterprise'). Only this URL is fetched — not the entire
+            # internet.
+            direct_url:,
+            # Optional timeout in milliseconds for the request. If the request takes longer
+            # than this value, it will be aborted with a 408 status code. Maximum allowed
+            # value is 300000ms (5 minutes).
+            timeout_ms: nil,
+            # Discriminator for direct-URL-based brand retrieval.
+            type: :by_direct_url
+          )
+          end
+
+          sig do
+            override.returns(
+              { direct_url: String, type: Symbol, timeout_ms: Integer }
+            )
+          end
+          def to_hash
+          end
+        end
+
         class ByTransaction < ContextDev::Internal::Type::BaseModel
           OrHash =
             T.type_alias do

data/rbi/context_dev/models/monitor_create_params.rbi

@@ -186,9 +186,6 @@ module ContextDev
               )
             end
 
-          sig { returns(String) }
-          attr_accessor :query
-
           sig { returns(Symbol) }
           attr_accessor :type
 
@@ -198,21 +195,19 @@ module ContextDev
           sig { params(confidence_threshold: Float).void }
           attr_writer :confidence_threshold
 
-          # Detect meaning-level changes that match a natural language query.
+          # Detect meaning-level changes to tracked page content, ignoring cosmetic or
+          # paraphrase-only differences. Which changes are meaningful is judged against the
+          # extract target's `instructions` (and `schema`, when provided).
           sig do
-            params(
-              query: String,
-              confidence_threshold: Float,
-              type: Symbol
-            ).returns(T.attached_class)
+            params(confidence_threshold: Float, type: Symbol).returns(
+              T.attached_class
+            )
           end
-          def self.new(query:, confidence_threshold: nil, type: :semantic)
+          def self.new(confidence_threshold: nil, type: :semantic)
           end
 
           sig do
-            override.returns(
-              { query: String, type: Symbol, confidence_threshold: Float }
-            )
+            override.returns({ type: Symbol, confidence_threshold: Float })
           end
           def to_hash
           end
@@ -446,8 +441,9 @@ module ContextDev
 
           # Watch a sitemap for URL additions and removals. Crawled URLs are normalized
           # (lowercased host, no trailing slash/fragment) and scoped to the monitored site
-          # and its subdomains before comparison. A new URL set must be observed on two
-          # consecutive runs before a change is reported, suppressing one-run crawl flaps.
+          # and its subdomains before comparison. On a detected difference the sitemap is
+          # re-fetched within the same run and only URLs both observations agree on are
+          # reported, suppressing transient crawl flaps.
           sig do
             params(
               url: String,
@@ -494,6 +490,11 @@ module ContextDev
               )
             end
 
+          # Natural-language instructions guiding which pages and facts to track and which
+          # changes to report.
+          sig { returns(String) }
+          attr_accessor :instructions
+
           sig { returns(Symbol) }
           attr_accessor :type
 
@@ -507,13 +508,6 @@ module ContextDev
           sig { params(follow_subdomains: T::Boolean).void }
           attr_writer :follow_subdomains
 
-          # Optional natural-language instructions guiding what to extract.
-          sig { returns(T.nilable(String)) }
-          attr_reader :instructions
-
-          sig { params(instructions: String).void }
-          attr_writer :instructions
-
           # Optional maximum link depth from the starting URL (0 = only the starting page).
           sig { returns(T.nilable(Integer)) }
           attr_reader :max_depth
@@ -521,27 +515,37 @@ module ContextDev
           sig { params(max_depth: Integer).void }
           attr_writer :max_depth
 
-          # Maximum number of pages to analyze during extraction.
+          # Maximum number of pages to track.
           sig { returns(T.nilable(Integer)) }
           attr_reader :max_pages
 
           sig { params(max_pages: Integer).void }
           attr_writer :max_pages
 
-          # JSON Schema describing the structured data to extract and watch for changes. If
-          # omitted, a default summary + key-points schema is used.
+          # JSON Schema describing the data you care about. It is used three ways: it guides
+          # which pages are selected for tracking, it gives the change judge extra context
+          # on which changes matter (alongside `instructions`), and it defines the shape of
+          # the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most
+          # about once a day). It is not a response format for changes: change events and
+          # webhook payloads always contain diffs, summaries, and evidence excerpts — never
+          # data in this schema's shape. If omitted, a default summary + key-points schema
+          # is used.
           sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
           attr_reader :schema
 
           sig { params(schema: T::Hash[Symbol, T.anything]).void }
           attr_writer :schema
 
-          # Watch a site's extracted structured data.
+          # Watch the monitor-relevant pages of a site for meaningful changes. A crawl
+          # guided by `schema`/`instructions` selects up to `max_pages` relevant pages to
+          # track; each run re-checks exactly those pages, and confirmed content changes are
+          # judged for relevance against the monitor's `instructions` (and `schema`, when
+          # provided). The tracked page set is refreshed by a periodic re-discovery crawl.
           sig do
             params(
+              instructions: String,
               url: String,
               follow_subdomains: T::Boolean,
-              instructions: String,
               max_depth: Integer,
               max_pages: Integer,
               schema: T::Hash[Symbol, T.anything],
@@ -549,17 +553,24 @@ module ContextDev
             ).returns(T.attached_class)
           end
           def self.new(
+            # Natural-language instructions guiding which pages and facts to track and which
+            # changes to report.
+            instructions:,
             # Root URL to extract structured data from.
             url:,
             follow_subdomains: nil,
-            # Optional natural-language instructions guiding what to extract.
-            instructions: nil,
             # Optional maximum link depth from the starting URL (0 = only the starting page).
             max_depth: nil,
-            # Maximum number of pages to analyze during extraction.
+            # Maximum number of pages to track.
             max_pages: nil,
-            # JSON Schema describing the structured data to extract and watch for changes. If
-            # omitted, a default summary + key-points schema is used.
+            # JSON Schema describing the data you care about. It is used three ways: it guides
+            # which pages are selected for tracking, it gives the change judge extra context
+            # on which changes matter (alongside `instructions`), and it defines the shape of
+            # the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most
+            # about once a day). It is not a response format for changes: change events and
+            # webhook payloads always contain diffs, summaries, and evidence excerpts — never
+            # data in this schema's shape. If omitted, a default summary + key-points schema
+            # is used.
             schema: nil,
             type: :extract
           )
@@ -568,10 +579,10 @@ module ContextDev
           sig do
             override.returns(
               {
+                instructions: String,
                 type: Symbol,
                 url: String,
                 follow_subdomains: T::Boolean,
-                instructions: String,
                 max_depth: Integer,
                 max_pages: Integer,
                 schema: T::Hash[Symbol, T.anything]