context.dev 2.21.0 → 2.22.0

data/rbi/context_dev/models/monitor_update_params.rbi

@@ -11,10 +11,12 @@ module ContextDev
           T.any(ContextDev::MonitorUpdateParams, ContextDev::Internal::AnyHash)
         end
 
+      # ID of the monitor.
       sig { returns(String) }
       attr_accessor :monitor_id
 
-      # Discriminated union describing how changes are detected.
+      # How changes are judged. Defaults to `semantic` for extract targets and page
+      # targets with `instructions`, otherwise `exact`.
       sig do
         returns(
           T.nilable(
@@ -38,6 +40,7 @@ module ContextDev
       end
       attr_writer :change_detection
 
+      # Display name for the monitor.
       sig { returns(T.nilable(String)) }
       attr_reader :name
 
@@ -55,6 +58,7 @@ module ContextDev
       end
       attr_writer :schedule
 
+      # Set `paused` to stop scheduled runs or `active` to resume them.
       sig do
         returns(T.nilable(ContextDev::MonitorUpdateParams::Status::OrSymbol))
       end
@@ -65,15 +69,14 @@ module ContextDev
       end
       attr_writer :status
 
-      # User-defined tags for grouping and filtering monitors and their changes.
-      # Duplicates are removed.
+      # Labels for filtering monitors, their changes, and their usage.
       sig { returns(T.nilable(T::Array[String])) }
       attr_reader :tags
 
       sig { params(tags: T::Array[String]).void }
       attr_writer :tags
 
-      # Discriminated union describing what the monitor watches.
+      # What to watch: a page, a sitemap, or data extracted from a site.
       sig do
         returns(
           T.nilable(
@@ -99,7 +102,7 @@ module ContextDev
       end
       attr_writer :target
 
-      # Set to null to remove the webhook.
+      # Set to null to remove the webhook. Changing `url` issues a new secret.
       sig { returns(T.nilable(ContextDev::MonitorUpdateParams::Webhook)) }
       attr_reader :webhook
 
@@ -133,21 +136,24 @@ module ContextDev
         ).returns(T.attached_class)
       end
       def self.new(
+        # ID of the monitor.
         monitor_id:,
-        # Discriminated union describing how changes are detected.
+        # How changes are judged. Defaults to `semantic` for extract targets and page
+        # targets with `instructions`, otherwise `exact`.
         change_detection: nil,
+        # Display name for the monitor.
         name: nil,
         # 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.
         schedule: nil,
+        # Set `paused` to stop scheduled runs or `active` to resume them.
         status: nil,
-        # User-defined tags for grouping and filtering monitors and their changes.
-        # Duplicates are removed.
+        # Labels for filtering monitors, their changes, and their usage.
         tags: nil,
-        # Discriminated union describing what the monitor watches.
+        # What to watch: a page, a sitemap, or data extracted from a site.
         target: nil,
-        # Set to null to remove the webhook.
+        # Set to null to remove the webhook. Changing `url` issues a new secret.
         webhook: nil,
         request_options: {}
       )
@@ -180,7 +186,8 @@ module ContextDev
       def to_hash
       end
 
-      # Discriminated union describing how changes are detected.
+      # How changes are judged. Defaults to `semantic` for extract targets and page
+      # targets with `instructions`, otherwise `exact`.
       module ChangeDetection
         extend ContextDev::Internal::Type::Union
 
@@ -201,13 +208,17 @@ module ContextDev
               )
             end
 
+          # Use `exact` to compare visible text or sitemap URLs.
           sig { returns(Symbol) }
           attr_accessor :type
 
           # Detect exact changes. For page targets, this means visible text diffs. For
           # sitemap targets, this means URL additions and removals.
           sig { params(type: Symbol).returns(T.attached_class) }
-          def self.new(type: :exact)
+          def self.new(
+            # Use `exact` to compare visible text or sitemap URLs.
+            type: :exact
+          )
           end
 
           sig { override.returns({ type: Symbol }) }
@@ -224,25 +235,30 @@ module ContextDev
               )
             end
 
+          # Use `semantic` to judge changes against the target instructions.
           sig { returns(Symbol) }
           attr_accessor :type
 
+          # Minimum confidence required to report a meaningful change, from 0 to 1.
           sig { returns(T.nilable(Float)) }
           attr_reader :confidence_threshold
 
           sig { params(confidence_threshold: Float).void }
           attr_writer :confidence_threshold
 
-          # 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).
+          # Detect meaningful content changes using the target’s instructions and optional
+          # schema.
           sig do
             params(confidence_threshold: Float, type: Symbol).returns(
               T.attached_class
             )
           end
-          def self.new(confidence_threshold: nil, type: :semantic)
+          def self.new(
+            # Minimum confidence required to report a meaningful change, from 0 to 1.
+            confidence_threshold: nil,
+            # Use `semantic` to judge changes against the target instructions.
+            type: :semantic
+          )
           end
 
           sig do
@@ -276,11 +292,13 @@ module ContextDev
         sig { returns(Integer) }
         attr_accessor :frequency
 
+        # Use `interval` to run on a repeating schedule.
         sig do
           returns(ContextDev::MonitorUpdateParams::Schedule::Type::OrSymbol)
         end
         attr_accessor :type
 
+        # Time unit used with `frequency` to set the run interval.
         sig do
           returns(ContextDev::MonitorUpdateParams::Schedule::Unit::OrSymbol)
         end
@@ -301,7 +319,9 @@ module ContextDev
           # at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes;
           # maximum 365 when unit is days).
           frequency:,
+          # Use `interval` to run on a repeating schedule.
           type:,
+          # Time unit used with `frequency` to set the run interval.
           unit:
         )
         end
@@ -318,6 +338,7 @@ module ContextDev
         def to_hash
         end
 
+        # Use `interval` to run on a repeating schedule.
         module Type
           extend ContextDev::Internal::Type::Enum
 
@@ -344,6 +365,7 @@ module ContextDev
           end
         end
 
+        # Time unit used with `frequency` to set the run interval.
         module Unit
           extend ContextDev::Internal::Type::Enum
 
@@ -381,6 +403,7 @@ module ContextDev
         end
       end
 
+      # Set `paused` to stop scheduled runs or `active` to resume them.
       module Status
         extend ContextDev::Internal::Type::Enum
 
@@ -404,7 +427,7 @@ module ContextDev
         end
       end
 
-      # Discriminated union describing what the monitor watches.
+      # What to watch: a page, a sitemap, or data extracted from a site.
       module Target
         extend ContextDev::Internal::Type::Union
 
@@ -426,27 +449,41 @@ module ContextDev
               )
             end
 
+          # Use `page` to watch one web page.
           sig { returns(Symbol) }
           attr_accessor :type
 
+          # Public HTTP(S) page URL to monitor.
           sig { returns(String) }
           attr_accessor :url
 
-          # CSS selectors for HTML regions to remove before text extraction. Applied after
-          # include_selectors; exclusion takes precedence when an element matches both. Omit
-          # or pass an empty array to apply no explicit exclusions. Changing these selectors
-          # creates a new baseline.
+          # Optional browser actions executed in array order after the page loads, before
+          # content is captured, on every run. Requires a paid plan. Maximum: 5 actions.
+          # Changes create a new baseline.
+          sig do
+            returns(
+              T.nilable(
+                T::Array[
+                  T.any(
+                    ContextDev::MonitorUpdateParams::Target::Page::Action::Wait,
+                    ContextDev::MonitorUpdateParams::Target::Page::Action::Perform,
+                    ContextDev::MonitorUpdateParams::Target::Page::Action::Scroll
+                  )
+                ]
+              )
+            )
+          end
+          attr_accessor :actions
+
+          # Remove matching regions after inclusions. Changes create a new baseline.
           sig { returns(T.nilable(T::Array[String])) }
           attr_reader :exclude_selectors
 
           sig { params(exclude_selectors: T::Array[String]).void }
           attr_writer :exclude_selectors
 
-          # CSS selectors defining the HTML regions to monitor. Matching subtrees are
-          # combined in document order before text extraction, instead of automatic
-          # main-content selection. Omit or pass an empty array to use automatic
-          # main-content extraction. If the filtered page has no usable text, the run fails
-          # without replacing the baseline. Changing these selectors creates a new baseline.
+          # Monitor these CSS-selected regions. Empty or omitted uses main content. Changes
+          # create a new baseline.
           sig { returns(T.nilable(T::Array[String])) }
           attr_reader :include_selectors
 
@@ -473,6 +510,16 @@ module ContextDev
           sig do
             params(
               url: String,
+              actions:
+                T.nilable(
+                  T::Array[
+                    T.any(
+                      ContextDev::MonitorUpdateParams::Target::Page::Action::Wait::OrHash,
+                      ContextDev::MonitorUpdateParams::Target::Page::Action::Perform::OrHash,
+                      ContextDev::MonitorUpdateParams::Target::Page::Action::Scroll::OrHash
+                    )
+                  ]
+                ),
               exclude_selectors: T::Array[String],
               include_selectors: T::Array[String],
               instructions: String,
@@ -481,23 +528,23 @@ module ContextDev
             ).returns(T.attached_class)
           end
           def self.new(
+            # Public HTTP(S) page URL to monitor.
             url:,
-            # CSS selectors for HTML regions to remove before text extraction. Applied after
-            # include_selectors; exclusion takes precedence when an element matches both. Omit
-            # or pass an empty array to apply no explicit exclusions. Changing these selectors
-            # creates a new baseline.
+            # Optional browser actions executed in array order after the page loads, before
+            # content is captured, on every run. Requires a paid plan. Maximum: 5 actions.
+            # Changes create a new baseline.
+            actions: nil,
+            # Remove matching regions after inclusions. Changes create a new baseline.
             exclude_selectors: nil,
-            # CSS selectors defining the HTML regions to monitor. Matching subtrees are
-            # combined in document order before text extraction, instead of automatic
-            # main-content selection. Omit or pass an empty array to use automatic
-            # main-content extraction. If the filtered page has no usable text, the run fails
-            # without replacing the baseline. Changing these selectors creates a new baseline.
+            # Monitor these CSS-selected regions. Empty or omitted uses main content. Changes
+            # create a new baseline.
             include_selectors: nil,
             # Plain-language goal describing which page changes matter. When provided without
             # change_detection, semantic detection is inferred.
             instructions: nil,
             # Normalize whitespace before comparing or analyzing text.
             normalize_whitespace: nil,
+            # Use `page` to watch one web page.
             type: :page
           )
           end
@@ -507,6 +554,16 @@ module ContextDev
               {
                 type: Symbol,
                 url: String,
+                actions:
+                  T.nilable(
+                    T::Array[
+                      T.any(
+                        ContextDev::MonitorUpdateParams::Target::Page::Action::Wait,
+                        ContextDev::MonitorUpdateParams::Target::Page::Action::Perform,
+                        ContextDev::MonitorUpdateParams::Target::Page::Action::Scroll
+                      )
+                    ]
+                  ),
                 exclude_selectors: T::Array[String],
                 include_selectors: T::Array[String],
                 instructions: String,
@@ -516,6 +573,311 @@ module ContextDev
           end
           def to_hash
           end
+
+          # Browser action discriminated by `do`. Each variant exposes only its applicable
+          # fields.
+          module Action
+            extend ContextDev::Internal::Type::Union
+
+            Variants =
+              T.type_alias do
+                T.any(
+                  ContextDev::MonitorUpdateParams::Target::Page::Action::Wait,
+                  ContextDev::MonitorUpdateParams::Target::Page::Action::Perform,
+                  ContextDev::MonitorUpdateParams::Target::Page::Action::Scroll
+                )
+              end
+
+            class Wait < ContextDev::Internal::Type::BaseModel
+              OrHash =
+                T.type_alias do
+                  T.any(
+                    ContextDev::MonitorUpdateParams::Target::Page::Action::Wait,
+                    ContextDev::Internal::AnyHash
+                  )
+                end
+
+              # Use `wait` to pause for a fixed duration.
+              sig { returns(Symbol) }
+              attr_accessor :do_
+
+              # Time to pause in milliseconds before the next action.
+              sig { returns(Integer) }
+              attr_accessor :time_ms
+
+              # Pause for a fixed number of milliseconds before continuing to the next action.
+              sig do
+                params(time_ms: Integer, do_: Symbol).returns(T.attached_class)
+              end
+              def self.new(
+                # Time to pause in milliseconds before the next action.
+                time_ms:,
+                # Use `wait` to pause for a fixed duration.
+                do_: :wait
+              )
+              end
+
+              sig { override.returns({ do_: Symbol, time_ms: Integer }) }
+              def to_hash
+              end
+            end
+
+            class Perform < ContextDev::Internal::Type::BaseModel
+              OrHash =
+                T.type_alias do
+                  T.any(
+                    ContextDev::MonitorUpdateParams::Target::Page::Action::Perform,
+                    ContextDev::Internal::AnyHash
+                  )
+                end
+
+              # One browser instruction, such as clicking a button or entering text.
+              sig { returns(String) }
+              attr_accessor :action
+
+              # Use `perform` for a plain-language browser instruction.
+              sig { returns(Symbol) }
+              attr_accessor :do_
+
+              # Resolve and perform one natural-language browser action.
+              sig do
+                params(action: String, do_: Symbol).returns(T.attached_class)
+              end
+              def self.new(
+                # One browser instruction, such as clicking a button or entering text.
+                action:,
+                # Use `perform` for a plain-language browser instruction.
+                do_: :perform
+              )
+              end
+
+              sig { override.returns({ action: String, do_: Symbol }) }
+              def to_hash
+              end
+            end
+
+            class Scroll < ContextDev::Internal::Type::BaseModel
+              OrHash =
+                T.type_alias do
+                  T.any(
+                    ContextDev::MonitorUpdateParams::Target::Page::Action::Scroll,
+                    ContextDev::Internal::AnyHash
+                  )
+                end
+
+              # Use `scroll` to move through the page or a container.
+              sig { returns(Symbol) }
+              attr_accessor :do_
+
+              # Pixels per scroll, one visible viewport, or the current scroll boundary.
+              # Defaults to viewport.
+              sig do
+                returns(
+                  T.nilable(
+                    T.any(
+                      Integer,
+                      ContextDev::MonitorUpdateParams::Target::Page::Action::Scroll::Amount::OrSymbol
+                    )
+                  )
+                )
+              end
+              attr_reader :amount
+
+              sig do
+                params(
+                  amount:
+                    T.any(
+                      Integer,
+                      ContextDev::MonitorUpdateParams::Target::Page::Action::Scroll::Amount::OrSymbol
+                    )
+                ).void
+              end
+              attr_writer :amount
+
+              # CSS selector for the first matching scroll container. Defaults to the page.
+              sig { returns(T.nilable(String)) }
+              attr_reader :container
+
+              sig { params(container: String).void }
+              attr_writer :container
+
+              # Direction to scroll. Defaults to down.
+              sig do
+                returns(
+                  T.nilable(
+                    ContextDev::MonitorUpdateParams::Target::Page::Action::Scroll::Direction::OrSymbol
+                  )
+                )
+              end
+              attr_reader :direction
+
+              sig do
+                params(
+                  direction:
+                    ContextDev::MonitorUpdateParams::Target::Page::Action::Scroll::Direction::OrSymbol
+                ).void
+              end
+              attr_writer :direction
+
+              # Maximum scroll iterations. Stops early when scrolling and scrollable extent stop
+              # changing. Defaults to 1.
+              sig { returns(T.nilable(Integer)) }
+              attr_reader :max_scrolls
+
+              sig { params(max_scrolls: Integer).void }
+              attr_writer :max_scrolls
+
+              # Scroll the page or a selected scrollable container, waiting adaptively for
+              # content and dimensions to settle after each iteration.
+              sig do
+                params(
+                  amount:
+                    T.any(
+                      Integer,
+                      ContextDev::MonitorUpdateParams::Target::Page::Action::Scroll::Amount::OrSymbol
+                    ),
+                  container: String,
+                  direction:
+                    ContextDev::MonitorUpdateParams::Target::Page::Action::Scroll::Direction::OrSymbol,
+                  max_scrolls: Integer,
+                  do_: Symbol
+                ).returns(T.attached_class)
+              end
+              def self.new(
+                # Pixels per scroll, one visible viewport, or the current scroll boundary.
+                # Defaults to viewport.
+                amount: nil,
+                # CSS selector for the first matching scroll container. Defaults to the page.
+                container: nil,
+                # Direction to scroll. Defaults to down.
+                direction: nil,
+                # Maximum scroll iterations. Stops early when scrolling and scrollable extent stop
+                # changing. Defaults to 1.
+                max_scrolls: nil,
+                # Use `scroll` to move through the page or a container.
+                do_: :scroll
+              )
+              end
+
+              sig do
+                override.returns(
+                  {
+                    do_: Symbol,
+                    amount:
+                      T.any(
+                        Integer,
+                        ContextDev::MonitorUpdateParams::Target::Page::Action::Scroll::Amount::OrSymbol
+                      ),
+                    container: String,
+                    direction:
+                      ContextDev::MonitorUpdateParams::Target::Page::Action::Scroll::Direction::OrSymbol,
+                    max_scrolls: Integer
+                  }
+                )
+              end
+              def to_hash
+              end
+
+              # Pixels per scroll, one visible viewport, or the current scroll boundary.
+              # Defaults to viewport.
+              module Amount
+                extend ContextDev::Internal::Type::Union
+
+                Variants =
+                  T.type_alias do
+                    T.any(
+                      Integer,
+                      ContextDev::MonitorUpdateParams::Target::Page::Action::Scroll::Amount::TaggedSymbol
+                    )
+                  end
+
+                sig do
+                  override.returns(
+                    T::Array[
+                      ContextDev::MonitorUpdateParams::Target::Page::Action::Scroll::Amount::Variants
+                    ]
+                  )
+                end
+                def self.variants
+                end
+
+                TaggedSymbol =
+                  T.type_alias do
+                    T.all(
+                      Symbol,
+                      ContextDev::MonitorUpdateParams::Target::Page::Action::Scroll::Amount
+                    )
+                  end
+                OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+                VIEWPORT =
+                  T.let(
+                    :viewport,
+                    ContextDev::MonitorUpdateParams::Target::Page::Action::Scroll::Amount::TaggedSymbol
+                  )
+                MAX =
+                  T.let(
+                    :max,
+                    ContextDev::MonitorUpdateParams::Target::Page::Action::Scroll::Amount::TaggedSymbol
+                  )
+              end
+
+              # Direction to scroll. Defaults to down.
+              module Direction
+                extend ContextDev::Internal::Type::Enum
+
+                TaggedSymbol =
+                  T.type_alias do
+                    T.all(
+                      Symbol,
+                      ContextDev::MonitorUpdateParams::Target::Page::Action::Scroll::Direction
+                    )
+                  end
+                OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+                UP =
+                  T.let(
+                    :up,
+                    ContextDev::MonitorUpdateParams::Target::Page::Action::Scroll::Direction::TaggedSymbol
+                  )
+                DOWN =
+                  T.let(
+                    :down,
+                    ContextDev::MonitorUpdateParams::Target::Page::Action::Scroll::Direction::TaggedSymbol
+                  )
+                LEFT =
+                  T.let(
+                    :left,
+                    ContextDev::MonitorUpdateParams::Target::Page::Action::Scroll::Direction::TaggedSymbol
+                  )
+                RIGHT =
+                  T.let(
+                    :right,
+                    ContextDev::MonitorUpdateParams::Target::Page::Action::Scroll::Direction::TaggedSymbol
+                  )
+
+                sig do
+                  override.returns(
+                    T::Array[
+                      ContextDev::MonitorUpdateParams::Target::Page::Action::Scroll::Direction::TaggedSymbol
+                    ]
+                  )
+                end
+                def self.values
+                end
+              end
+            end
+
+            sig do
+              override.returns(
+                T::Array[
+                  ContextDev::MonitorUpdateParams::Target::Page::Action::Variants
+                ]
+              )
+            end
+            def self.variants
+            end
+          end
         end
 
         class Sitemap < ContextDev::Internal::Type::BaseModel
@@ -527,6 +889,7 @@ module ContextDev
               )
             end
 
+          # Use `sitemap` to watch a site for added or removed URLs.
           sig { returns(Symbol) }
           attr_accessor :type
 
@@ -555,11 +918,7 @@ module ContextDev
           sig { params(max_urls: Integer).void }
           attr_writer :max_urls
 
-          # 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.
+          # Watch a site’s URL inventory for confirmed additions and removals.
           sig do
             params(
               url: String,
@@ -578,6 +937,7 @@ module ContextDev
             include: nil,
             # Maximum number of sitemap URLs to track (capped at 10,000).
             max_urls: nil,
+            # Use `sitemap` to watch a site for added or removed URLs.
             type: :sitemap
           )
           end
@@ -611,6 +971,7 @@ module ContextDev
           sig { returns(String) }
           attr_accessor :instructions
 
+          # Use `extract` to watch structured data across selected pages.
           sig { returns(Symbol) }
           attr_accessor :type
 
@@ -618,6 +979,7 @@ module ContextDev
           sig { returns(String) }
           attr_accessor :url
 
+          # Allow page discovery on subdomains of the target site.
           sig { returns(T.nilable(T::Boolean)) }
           attr_reader :follow_subdomains
 
@@ -638,25 +1000,16 @@ module ContextDev
           sig { params(max_pages: Integer).void }
           attr_writer :max_pages
 
-          # 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.
+          # JSON Schema for page selection and the baseline snapshot. Changes return diffs
+          # and evidence.
           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 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.
+          # Track relevant pages selected by `schema` and `instructions`; refresh the page
+          # set periodically.
           sig do
             params(
               instructions: String,
@@ -674,20 +1027,16 @@ module ContextDev
             instructions:,
             # Root URL to extract structured data from.
             url:,
+            # Allow page discovery on subdomains of the target site.
             follow_subdomains: nil,
             # Optional maximum link depth from the starting URL (0 = only the starting page).
             max_depth: nil,
             # Maximum number of pages to track.
             max_pages: nil,
-            # 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.
+            # JSON Schema for page selection and the baseline snapshot. Changes return diffs
+            # and evidence.
             schema: nil,
+            # Use `extract` to watch structured data across selected pages.
             type: :extract
           )
           end
@@ -727,15 +1076,13 @@ module ContextDev
             )
           end
 
-        # Webhook URL events are delivered to. Slack incoming webhook URLs are
-        # automatically formatted as Slack messages.
+        # Public HTTP(S) URL that receives events. Slack and GovSlack URLs get formatted
+        # messages.
         sig { returns(String) }
         attr_accessor :url
 
-        # Events delivered to this endpoint. `change.detected` fires only when a run
-        # detects a change; `run.completed` fires on every completed run — including runs
-        # that detected no change — and embeds the change when one was detected. Defaults
-        # to `["change.detected"]` when omitted.
+        # Events to deliver. Defaults to `change.detected`; `run.completed` also includes
+        # unchanged runs.
         sig do
           returns(
             T.nilable(
@@ -764,7 +1111,7 @@ module ContextDev
         sig { params(retry_: ContextDev::RetryConfig::OrHash).void }
         attr_writer :retry_
 
-        # Set to null to remove the webhook.
+        # Set to null to remove the webhook. Changing `url` issues a new secret.
         sig do
           params(
             url: String,
@@ -776,13 +1123,11 @@ module ContextDev
           ).returns(T.attached_class)
         end
         def self.new(
-          # Webhook URL events are delivered to. Slack incoming webhook URLs are
-          # automatically formatted as Slack messages.
+          # Public HTTP(S) URL that receives events. Slack and GovSlack URLs get formatted
+          # messages.
           url:,
-          # Events delivered to this endpoint. `change.detected` fires only when a run
-          # detects a change; `run.completed` fires on every completed run — including runs
-          # that detected no change — and embeds the change when one was detected. Defaults
-          # to `["change.detected"]` when omitted.
+          # Events to deliver. Defaults to `change.detected`; `run.completed` also includes
+          # unchanged runs.
           events: nil,
           # Webhook retry settings. Use {} for the default schedule.
           retry_: nil