context.dev 2.5.0 → 2.6.0

data/lib/context_dev/models/monitor_create_params.rb

@@ -7,31 +7,23 @@ module ContextDev
       extend ContextDev::Internal::Type::RequestParameters::Converter
       include ContextDev::Internal::Type::RequestParameters
 
-      # @!attribute change_detection
-      #   Discriminated union describing how changes are detected.
-      #
-      #   @return [ContextDev::Models::MonitorCreateParams::ChangeDetection::Exact, ContextDev::Models::MonitorCreateParams::ChangeDetection::Semantic]
-      required :change_detection, union: -> { ContextDev::MonitorCreateParams::ChangeDetection }
-
       # @!attribute name
       #
       #   @return [String]
       required :name, String
 
-      # @!attribute schedule
-      #   Run the monitor on a fixed interval defined by a frequency and a unit, e.g.
-      #   every 6 hours or every 2 days. The total interval (frequency × unit) must be
-      #   between 10 minutes and 1 year.
-      #
-      #   @return [ContextDev::Models::MonitorCreateParams::Schedule]
-      required :schedule, -> { ContextDev::MonitorCreateParams::Schedule }
-
       # @!attribute target
       #   Discriminated union describing what the monitor watches.
       #
       #   @return [ContextDev::Models::MonitorCreateParams::Target::Page, ContextDev::Models::MonitorCreateParams::Target::Sitemap, ContextDev::Models::MonitorCreateParams::Target::Extract]
       required :target, union: -> { ContextDev::MonitorCreateParams::Target }
 
+      # @!attribute change_detection
+      #   Discriminated union describing how changes are detected.
+      #
+      #   @return [ContextDev::Models::MonitorCreateParams::ChangeDetection::Exact, ContextDev::Models::MonitorCreateParams::ChangeDetection::Semantic, nil]
+      optional :change_detection, union: -> { ContextDev::MonitorCreateParams::ChangeDetection }
+
       # @!attribute mode
       #   Top-level monitor category. Always `web` today; the concrete behavior is
       #   described by `target` and `change_detection`.
@@ -39,6 +31,14 @@ module ContextDev
       #   @return [Symbol, ContextDev::Models::MonitorCreateParams::Mode, nil]
       optional :mode, enum: -> { ContextDev::MonitorCreateParams::Mode }
 
+      # @!attribute schedule
+      #   Run the monitor on a fixed interval defined by a frequency and a unit, e.g.
+      #   every 6 hours or every 2 days. The total interval (frequency × unit) must be
+      #   between 10 minutes and 1 year.
+      #
+      #   @return [ContextDev::Models::MonitorCreateParams::Schedule, nil]
+      optional :schedule, -> { ContextDev::MonitorCreateParams::Schedule }
+
       # @!attribute tags
       #   User-defined tags for grouping and filtering monitors and their changes.
       #   Duplicates are removed.
@@ -51,138 +51,33 @@ module ContextDev
       #   @return [ContextDev::Models::MonitorCreateParams::Webhook, nil]
       optional :webhook, -> { ContextDev::MonitorCreateParams::Webhook }, nil?: true
 
-      # @!method initialize(change_detection:, name:, schedule:, target:, mode: nil, tags: nil, webhook: nil, request_options: {})
+      # @!method initialize(name:, target:, change_detection: nil, mode: nil, schedule: nil, tags: nil, webhook: nil, request_options: {})
       #   Some parameter documentations has been truncated, see
       #   {ContextDev::Models::MonitorCreateParams} for more details.
       #
-      #   @param change_detection [ContextDev::Models::MonitorCreateParams::ChangeDetection::Exact, ContextDev::Models::MonitorCreateParams::ChangeDetection::Semantic] Discriminated union describing how changes are detected.
-      #
       #   @param name [String]
       #
-      #   @param schedule [ContextDev::Models::MonitorCreateParams::Schedule] Run the monitor on a fixed interval defined by a frequency and a unit, e.g. ever
-      #
       #   @param target [ContextDev::Models::MonitorCreateParams::Target::Page, ContextDev::Models::MonitorCreateParams::Target::Sitemap, ContextDev::Models::MonitorCreateParams::Target::Extract] Discriminated union describing what the monitor watches.
       #
+      #   @param change_detection [ContextDev::Models::MonitorCreateParams::ChangeDetection::Exact, ContextDev::Models::MonitorCreateParams::ChangeDetection::Semantic] Discriminated union describing how changes are detected.
+      #
       #   @param mode [Symbol, ContextDev::Models::MonitorCreateParams::Mode] Top-level monitor category. Always `web` today; the concrete behavior is describ
       #
+      #   @param schedule [ContextDev::Models::MonitorCreateParams::Schedule] Run the monitor on a fixed interval defined by a frequency and a unit, e.g. ever
+      #
       #   @param tags [Array<String>] User-defined tags for grouping and filtering monitors and their changes. Duplica
       #
       #   @param webhook [ContextDev::Models::MonitorCreateParams::Webhook, nil]
       #
       #   @param request_options [ContextDev::RequestOptions, Hash{Symbol=>Object}]
 
-      # Discriminated union describing how changes are detected.
-      module ChangeDetection
-        extend ContextDev::Internal::Type::Union
-
-        discriminator :type
-
-        # Detect exact changes. For page targets, this means visible text diffs. For sitemap targets, this means URL additions and removals.
-        variant :exact, -> { ContextDev::MonitorCreateParams::ChangeDetection::Exact }
-
-        # 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::MonitorCreateParams::ChangeDetection::Semantic }
-
-        class Exact < ContextDev::Internal::Type::BaseModel
-          # @!attribute type
-          #
-          #   @return [Symbol, :exact]
-          required :type, const: :exact
-
-          # @!method initialize(type: :exact)
-          #   Detect exact changes. For page targets, this means visible text diffs. For
-          #   sitemap targets, this means URL additions and removals.
-          #
-          #   @param type [Symbol, :exact]
-        end
-
-        class Semantic < ContextDev::Internal::Type::BaseModel
-          # @!attribute type
-          #
-          #   @return [Symbol, :semantic]
-          required :type, const: :semantic
-
-          # @!attribute confidence_threshold
-          #
-          #   @return [Float, nil]
-          optional :confidence_threshold, Float
-
-          # @!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 confidence_threshold [Float]
-          #   @param type [Symbol, :semantic]
-        end
-
-        # @!method self.variants
-        #   @return [Array(ContextDev::Models::MonitorCreateParams::ChangeDetection::Exact, ContextDev::Models::MonitorCreateParams::ChangeDetection::Semantic)]
-      end
-
-      class Schedule < ContextDev::Internal::Type::BaseModel
-        # @!attribute frequency
-        #   Number of units between runs. The resulting interval (frequency × unit) must be
-        #   at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes;
-        #   maximum 365 when unit is days).
-        #
-        #   @return [Integer]
-        required :frequency, Integer
-
-        # @!attribute type
-        #
-        #   @return [Symbol, ContextDev::Models::MonitorCreateParams::Schedule::Type]
-        required :type, enum: -> { ContextDev::MonitorCreateParams::Schedule::Type }
-
-        # @!attribute unit
-        #
-        #   @return [Symbol, ContextDev::Models::MonitorCreateParams::Schedule::Unit]
-        required :unit, enum: -> { ContextDev::MonitorCreateParams::Schedule::Unit }
-
-        # @!method initialize(frequency:, type:, unit:)
-        #   Some parameter documentations has been truncated, see
-        #   {ContextDev::Models::MonitorCreateParams::Schedule} for more details.
-        #
-        #   Run the monitor on a fixed interval defined by a frequency and a unit, e.g.
-        #   every 6 hours or every 2 days. The total interval (frequency × unit) must be
-        #   between 10 minutes and 1 year.
-        #
-        #   @param frequency [Integer] Number of units between runs. The resulting interval (frequency × unit) must be
-        #
-        #   @param type [Symbol, ContextDev::Models::MonitorCreateParams::Schedule::Type]
-        #
-        #   @param unit [Symbol, ContextDev::Models::MonitorCreateParams::Schedule::Unit]
-
-        # @see ContextDev::Models::MonitorCreateParams::Schedule#type
-        module Type
-          extend ContextDev::Internal::Type::Enum
-
-          INTERVAL = :interval
-
-          # @!method self.values
-          #   @return [Array<Symbol>]
-        end
-
-        # @see ContextDev::Models::MonitorCreateParams::Schedule#unit
-        module Unit
-          extend ContextDev::Internal::Type::Enum
-
-          MINUTES = :minutes
-          HOURS = :hours
-          DAYS = :days
-
-          # @!method self.values
-          #   @return [Array<Symbol>]
-        end
-      end
-
       # Discriminated union describing what the monitor watches.
       module Target
         extend ContextDev::Internal::Type::Union
 
         discriminator :type
 
-        # Watch a single web page.
+        # Watch a single web page. Exact detection reports visible-text diffs; semantic detection judges confirmed stable diffs against `instructions`.
         variant :page, -> { ContextDev::MonitorCreateParams::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. 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.
@@ -202,17 +97,30 @@ module ContextDev
           #   @return [String]
           required :url, String
 
+          # @!attribute instructions
+          #   Plain-language goal describing which page changes matter. When provided without
+          #   change_detection, semantic detection is inferred.
+          #
+          #   @return [String, nil]
+          optional :instructions, String
+
           # @!attribute normalize_whitespace
           #   Normalize whitespace before comparing or analyzing text.
           #
           #   @return [Boolean, nil]
           optional :normalize_whitespace, ContextDev::Internal::Type::Boolean
 
-          # @!method initialize(url:, normalize_whitespace: nil, type: :page)
-          #   Watch a single web page.
+          # @!method initialize(url:, instructions: nil, normalize_whitespace: nil, type: :page)
+          #   Some parameter documentations has been truncated, see
+          #   {ContextDev::Models::MonitorCreateParams::Target::Page} for more details.
+          #
+          #   Watch a single web page. Exact detection reports visible-text diffs; semantic
+          #   detection judges confirmed stable diffs against `instructions`.
           #
           #   @param url [String]
           #
+          #   @param instructions [String] Plain-language goal describing which page changes matter. When provided without
+          #
           #   @param normalize_whitespace [Boolean] Normalize whitespace before comparing or analyzing text.
           #
           #   @param type [Symbol, :page]
@@ -344,6 +252,56 @@ module ContextDev
         #   @return [Array(ContextDev::Models::MonitorCreateParams::Target::Page, ContextDev::Models::MonitorCreateParams::Target::Sitemap, ContextDev::Models::MonitorCreateParams::Target::Extract)]
       end
 
+      # Discriminated union describing how changes are detected.
+      module ChangeDetection
+        extend ContextDev::Internal::Type::Union
+
+        discriminator :type
+
+        # Detect exact changes. For page targets, this means visible text diffs. For sitemap targets, this means URL additions and removals.
+        variant :exact, -> { ContextDev::MonitorCreateParams::ChangeDetection::Exact }
+
+        # Detect meaning-level changes to page content, ignoring cosmetic or instruction-irrelevant differences. Which changes are meaningful is judged against the page or extract target's `instructions` (and an extract target's `schema`, when provided).
+        variant :semantic, -> { ContextDev::MonitorCreateParams::ChangeDetection::Semantic }
+
+        class Exact < ContextDev::Internal::Type::BaseModel
+          # @!attribute type
+          #
+          #   @return [Symbol, :exact]
+          required :type, const: :exact
+
+          # @!method initialize(type: :exact)
+          #   Detect exact changes. For page targets, this means visible text diffs. For
+          #   sitemap targets, this means URL additions and removals.
+          #
+          #   @param type [Symbol, :exact]
+        end
+
+        class Semantic < ContextDev::Internal::Type::BaseModel
+          # @!attribute type
+          #
+          #   @return [Symbol, :semantic]
+          required :type, const: :semantic
+
+          # @!attribute confidence_threshold
+          #
+          #   @return [Float, nil]
+          optional :confidence_threshold, Float
+
+          # @!method initialize(confidence_threshold: nil, type: :semantic)
+          #   Detect meaning-level changes to page content, ignoring cosmetic or
+          #   instruction-irrelevant differences. Which changes are meaningful is judged
+          #   against the page or extract target's `instructions` (and an extract target's
+          #   `schema`, when provided).
+          #
+          #   @param confidence_threshold [Float]
+          #   @param type [Symbol, :semantic]
+        end
+
+        # @!method self.variants
+        #   @return [Array(ContextDev::Models::MonitorCreateParams::ChangeDetection::Exact, ContextDev::Models::MonitorCreateParams::ChangeDetection::Semantic)]
+      end
+
       # Top-level monitor category. Always `web` today; the concrete behavior is
       # described by `target` and `change_detection`.
       module Mode
@@ -355,6 +313,62 @@ module ContextDev
         #   @return [Array<Symbol>]
       end
 
+      class Schedule < ContextDev::Internal::Type::BaseModel
+        # @!attribute frequency
+        #   Number of units between runs. The resulting interval (frequency × unit) must be
+        #   at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes;
+        #   maximum 365 when unit is days).
+        #
+        #   @return [Integer]
+        required :frequency, Integer
+
+        # @!attribute type
+        #
+        #   @return [Symbol, ContextDev::Models::MonitorCreateParams::Schedule::Type]
+        required :type, enum: -> { ContextDev::MonitorCreateParams::Schedule::Type }
+
+        # @!attribute unit
+        #
+        #   @return [Symbol, ContextDev::Models::MonitorCreateParams::Schedule::Unit]
+        required :unit, enum: -> { ContextDev::MonitorCreateParams::Schedule::Unit }
+
+        # @!method initialize(frequency:, type:, unit:)
+        #   Some parameter documentations has been truncated, see
+        #   {ContextDev::Models::MonitorCreateParams::Schedule} for more details.
+        #
+        #   Run the monitor on a fixed interval defined by a frequency and a unit, e.g.
+        #   every 6 hours or every 2 days. The total interval (frequency × unit) must be
+        #   between 10 minutes and 1 year.
+        #
+        #   @param frequency [Integer] Number of units between runs. The resulting interval (frequency × unit) must be
+        #
+        #   @param type [Symbol, ContextDev::Models::MonitorCreateParams::Schedule::Type]
+        #
+        #   @param unit [Symbol, ContextDev::Models::MonitorCreateParams::Schedule::Unit]
+
+        # @see ContextDev::Models::MonitorCreateParams::Schedule#type
+        module Type
+          extend ContextDev::Internal::Type::Enum
+
+          INTERVAL = :interval
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+
+        # @see ContextDev::Models::MonitorCreateParams::Schedule#unit
+        module Unit
+          extend ContextDev::Internal::Type::Enum
+
+          MINUTES = :minutes
+          HOURS = :hours
+          DAYS = :days
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+      end
+
       class Webhook < ContextDev::Internal::Type::BaseModel
         # @!attribute url
         #   Webhook URL events are delivered to.

data/lib/context_dev/models/monitor_create_response.rb

@@ -20,6 +20,14 @@ module ContextDev
       #   @return [Time]
       required :created_at, Time
 
+      # @!attribute initial_run_id
+      #   The baseline run queued by this create call, or null if it could not be queued
+      #   immediately (in which case the baseline runs on the next scheduled tick). Poll
+      #   GET /monitors/{monitor_id}/runs/{run_id}.
+      #
+      #   @return [String, nil]
+      required :initial_run_id, String, nil?: true
+
       # @!attribute mode
       #   Top-level monitor category. Always `web` today; the concrete behavior is
       #   described by `target` and `change_detection`.
@@ -112,12 +120,12 @@ module ContextDev
       #   @return [ContextDev::Models::MonitorCreateResponse::WebhookFailure, nil]
       optional :webhook_failure, -> { ContextDev::Models::MonitorCreateResponse::WebhookFailure }, nil?: true
 
-      # @!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, webhook_failure: nil)
+      # @!method initialize(id:, change_detection:, created_at:, initial_run_id:, 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, webhook_failure: nil)
       #   Some parameter documentations has been truncated, see
       #   {ContextDev::Models::MonitorCreateResponse} for more details.
       #
-      #   A web monitor. `mode` is the constant `web`; behavior is described by `target`
-      #   (page/sitemap/extract) and `change_detection` (exact/semantic).
+      #   A newly created monitor plus `initial_run_id`, the id of the baseline run queued
+      #   at creation.
       #
       #   @param id [String]
       #
@@ -125,6 +133,8 @@ module ContextDev
       #
       #   @param created_at [Time]
       #
+      #   @param initial_run_id [String, nil] The baseline run queued by this create call, or null if it could not be queued i
+      #
       #   @param mode [Symbol, ContextDev::Models::MonitorCreateResponse::Mode] Top-level monitor category. Always `web` today; the concrete behavior is describ
       #
       #   @param name [String]
@@ -164,7 +174,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::MonitorCreateResponse::ChangeDetection::Exact }
 
-        # 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).
+        # Detect meaning-level changes to page content, ignoring cosmetic or instruction-irrelevant differences. Which changes are meaningful is judged against the page or extract target's `instructions` (and an extract target's `schema`, when provided).
         variant :semantic, -> { ContextDev::Models::MonitorCreateResponse::ChangeDetection::Semantic }
 
         class Exact < ContextDev::Internal::Type::BaseModel
@@ -192,9 +202,10 @@ module ContextDev
           optional :confidence_threshold, Float
 
           # @!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).
+          #   Detect meaning-level changes to page content, ignoring cosmetic or
+          #   instruction-irrelevant differences. Which changes are meaningful is judged
+          #   against the page or extract target's `instructions` (and an extract target's
+          #   `schema`, when provided).
           #
           #   @param confidence_threshold [Float]
           #   @param type [Symbol, :semantic]
@@ -300,7 +311,7 @@ module ContextDev
 
         discriminator :type
 
-        # Watch a single web page.
+        # Watch a single web page. Exact detection reports visible-text diffs; semantic detection judges confirmed stable diffs against `instructions`.
         variant :page, -> { ContextDev::Models::MonitorCreateResponse::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. 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.
@@ -320,17 +331,30 @@ module ContextDev
           #   @return [String]
           required :url, String
 
+          # @!attribute instructions
+          #   Plain-language goal describing which page changes matter. When provided without
+          #   change_detection, semantic detection is inferred.
+          #
+          #   @return [String, nil]
+          optional :instructions, String
+
           # @!attribute normalize_whitespace
           #   Normalize whitespace before comparing or analyzing text.
           #
           #   @return [Boolean, nil]
           optional :normalize_whitespace, ContextDev::Internal::Type::Boolean
 
-          # @!method initialize(url:, normalize_whitespace: nil, type: :page)
-          #   Watch a single web page.
+          # @!method initialize(url:, instructions: nil, normalize_whitespace: nil, type: :page)
+          #   Some parameter documentations has been truncated, see
+          #   {ContextDev::Models::MonitorCreateResponse::Target::Page} for more details.
+          #
+          #   Watch a single web page. Exact detection reports visible-text diffs; semantic
+          #   detection judges confirmed stable diffs against `instructions`.
           #
           #   @param url [String]
           #
+          #   @param instructions [String] Plain-language goal describing which page changes matter. When provided without
+          #
           #   @param normalize_whitespace [Boolean] Normalize whitespace before comparing or analyzing text.
           #
           #   @param type [Symbol, :page]

data/lib/context_dev/models/monitor_list_response.rb

@@ -187,7 +187,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::MonitorListResponse::Data::ChangeDetection::Exact }
 
-          # 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).
+          # Detect meaning-level changes to page content, ignoring cosmetic or instruction-irrelevant differences. Which changes are meaningful is judged against the page or extract target's `instructions` (and an extract target's `schema`, when provided).
           variant :semantic, -> { ContextDev::Models::MonitorListResponse::Data::ChangeDetection::Semantic }
 
           class Exact < ContextDev::Internal::Type::BaseModel
@@ -215,9 +215,10 @@ module ContextDev
             optional :confidence_threshold, Float
 
             # @!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).
+            #   Detect meaning-level changes to page content, ignoring cosmetic or
+            #   instruction-irrelevant differences. Which changes are meaningful is judged
+            #   against the page or extract target's `instructions` (and an extract target's
+            #   `schema`, when provided).
             #
             #   @param confidence_threshold [Float]
             #   @param type [Symbol, :semantic]
@@ -323,7 +324,7 @@ module ContextDev
 
           discriminator :type
 
-          # Watch a single web page.
+          # Watch a single web page. Exact detection reports visible-text diffs; semantic detection judges confirmed stable diffs against `instructions`.
           variant :page, -> { ContextDev::Models::MonitorListResponse::Data::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. 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.
@@ -343,17 +344,30 @@ module ContextDev
             #   @return [String]
             required :url, String
 
+            # @!attribute instructions
+            #   Plain-language goal describing which page changes matter. When provided without
+            #   change_detection, semantic detection is inferred.
+            #
+            #   @return [String, nil]
+            optional :instructions, String
+
             # @!attribute normalize_whitespace
             #   Normalize whitespace before comparing or analyzing text.
             #
             #   @return [Boolean, nil]
             optional :normalize_whitespace, ContextDev::Internal::Type::Boolean
 
-            # @!method initialize(url:, normalize_whitespace: nil, type: :page)
-            #   Watch a single web page.
+            # @!method initialize(url:, instructions: nil, normalize_whitespace: nil, type: :page)
+            #   Some parameter documentations has been truncated, see
+            #   {ContextDev::Models::MonitorListResponse::Data::Target::Page} for more details.
+            #
+            #   Watch a single web page. Exact detection reports visible-text diffs; semantic
+            #   detection judges confirmed stable diffs against `instructions`.
             #
             #   @param url [String]
             #
+            #   @param instructions [String] Plain-language goal describing which page changes matter. When provided without
+            #
             #   @param normalize_whitespace [Boolean] Normalize whitespace before comparing or analyzing text.
             #
             #   @param type [Symbol, :page]

data/lib/context_dev/models/monitor_retrieve_response.rb

@@ -164,7 +164,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::MonitorRetrieveResponse::ChangeDetection::Exact }
 
-        # 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).
+        # Detect meaning-level changes to page content, ignoring cosmetic or instruction-irrelevant differences. Which changes are meaningful is judged against the page or extract target's `instructions` (and an extract target's `schema`, when provided).
         variant :semantic, -> { ContextDev::Models::MonitorRetrieveResponse::ChangeDetection::Semantic }
 
         class Exact < ContextDev::Internal::Type::BaseModel
@@ -192,9 +192,10 @@ module ContextDev
           optional :confidence_threshold, Float
 
           # @!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).
+          #   Detect meaning-level changes to page content, ignoring cosmetic or
+          #   instruction-irrelevant differences. Which changes are meaningful is judged
+          #   against the page or extract target's `instructions` (and an extract target's
+          #   `schema`, when provided).
           #
           #   @param confidence_threshold [Float]
           #   @param type [Symbol, :semantic]
@@ -300,7 +301,7 @@ module ContextDev
 
         discriminator :type
 
-        # Watch a single web page.
+        # Watch a single web page. Exact detection reports visible-text diffs; semantic detection judges confirmed stable diffs against `instructions`.
         variant :page, -> { ContextDev::Models::MonitorRetrieveResponse::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. 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.
@@ -320,17 +321,30 @@ module ContextDev
           #   @return [String]
           required :url, String
 
+          # @!attribute instructions
+          #   Plain-language goal describing which page changes matter. When provided without
+          #   change_detection, semantic detection is inferred.
+          #
+          #   @return [String, nil]
+          optional :instructions, String
+
           # @!attribute normalize_whitespace
           #   Normalize whitespace before comparing or analyzing text.
           #
           #   @return [Boolean, nil]
           optional :normalize_whitespace, ContextDev::Internal::Type::Boolean
 
-          # @!method initialize(url:, normalize_whitespace: nil, type: :page)
-          #   Watch a single web page.
+          # @!method initialize(url:, instructions: nil, normalize_whitespace: nil, type: :page)
+          #   Some parameter documentations has been truncated, see
+          #   {ContextDev::Models::MonitorRetrieveResponse::Target::Page} for more details.
+          #
+          #   Watch a single web page. Exact detection reports visible-text diffs; semantic
+          #   detection judges confirmed stable diffs against `instructions`.
           #
           #   @param url [String]
           #
+          #   @param instructions [String] Plain-language goal describing which page changes matter. When provided without
+          #
           #   @param normalize_whitespace [Boolean] Normalize whitespace before comparing or analyzing text.
           #
           #   @param type [Symbol, :page]

data/lib/context_dev/models/monitor_update_params.rb

@@ -86,7 +86,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::MonitorUpdateParams::ChangeDetection::Exact }
 
-        # 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).
+        # Detect meaning-level changes to page content, ignoring cosmetic or instruction-irrelevant differences. Which changes are meaningful is judged against the page or extract target's `instructions` (and an extract target's `schema`, when provided).
         variant :semantic, -> { ContextDev::MonitorUpdateParams::ChangeDetection::Semantic }
 
         class Exact < ContextDev::Internal::Type::BaseModel
@@ -114,9 +114,10 @@ module ContextDev
           optional :confidence_threshold, Float
 
           # @!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).
+          #   Detect meaning-level changes to page content, ignoring cosmetic or
+          #   instruction-irrelevant differences. Which changes are meaningful is judged
+          #   against the page or extract target's `instructions` (and an extract target's
+          #   `schema`, when provided).
           #
           #   @param confidence_threshold [Float]
           #   @param type [Symbol, :semantic]
@@ -198,7 +199,7 @@ module ContextDev
 
         discriminator :type
 
-        # Watch a single web page.
+        # Watch a single web page. Exact detection reports visible-text diffs; semantic detection judges confirmed stable diffs against `instructions`.
         variant :page, -> { ContextDev::MonitorUpdateParams::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. 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.
@@ -218,17 +219,30 @@ module ContextDev
           #   @return [String]
           required :url, String
 
+          # @!attribute instructions
+          #   Plain-language goal describing which page changes matter. When provided without
+          #   change_detection, semantic detection is inferred.
+          #
+          #   @return [String, nil]
+          optional :instructions, String
+
           # @!attribute normalize_whitespace
           #   Normalize whitespace before comparing or analyzing text.
           #
           #   @return [Boolean, nil]
           optional :normalize_whitespace, ContextDev::Internal::Type::Boolean
 
-          # @!method initialize(url:, normalize_whitespace: nil, type: :page)
-          #   Watch a single web page.
+          # @!method initialize(url:, instructions: nil, normalize_whitespace: nil, type: :page)
+          #   Some parameter documentations has been truncated, see
+          #   {ContextDev::Models::MonitorUpdateParams::Target::Page} for more details.
+          #
+          #   Watch a single web page. Exact detection reports visible-text diffs; semantic
+          #   detection judges confirmed stable diffs against `instructions`.
           #
           #   @param url [String]
           #
+          #   @param instructions [String] Plain-language goal describing which page changes matter. When provided without
+          #
           #   @param normalize_whitespace [Boolean] Normalize whitespace before comparing or analyzing text.
           #
           #   @param type [Symbol, :page]