ref(skills): replace sentry-create-alert with sentry-create-monitor

README.md

@@ -115,7 +115,7 @@ To build any target locally, run `src/plugins/<agent>/build.sh <output-dir>` (`c
 | Skill | What it does |
 | --- | --- |
 | `sentry-otel-exporter-setup` | Configure OTel Collector with the Sentry exporter for multi-project routing |
-| `sentry-create-alert` | Create alerts via the Sentry workflow engine API |
+| `sentry-create-monitor` | Create and edit monitors and the alerts that act on them, against the live API schema |
 | `sentry-snapshots-cocoa` | Set up Sentry Snapshots for Apple/Cocoa projects |
 
 ### Reference Library

scripts/build-skill-tree.sh

@@ -146,7 +146,7 @@ You are **Sentry's AI assistant**. You help developers set up Sentry, debug prod
 1. **Ask first.** Greet the user and ask what they'd like help with. Present these options:
    - **Set up Sentry** — Add error monitoring, performance tracing, session replay, or AI/LLM monitoring to a project
    - **Debug a production issue** — Investigate errors and exceptions using Sentry data
-   - **Configure a feature** — alerts, OpenTelemetry pipelines
+   - **Configure a feature** — monitors and alerts, OpenTelemetry pipelines
    - **Review code** — Resolve Sentry bot comments or check for predicted bugs
 
 2. **Wait for their answer.** Do not proceed until the user tells you what they want.

src/SKILL_TREE.md

@@ -9,7 +9,7 @@ You are **Sentry's AI assistant**. You help developers set up Sentry, debug prod
 1. **Ask first.** Greet the user and ask what they'd like help with. Present these options:
    - **Set up Sentry** — Add error monitoring, performance tracing, session replay, or AI/LLM monitoring to a project
    - **Debug a production issue** — Investigate errors and exceptions using Sentry data
-   - **Configure a feature** — alerts, OpenTelemetry pipelines
+   - **Configure a feature** — monitors and alerts, OpenTelemetry pipelines
    - **Review code** — Resolve Sentry bot comments or check for predicted bugs
 
 2. **Wait for their answer.** Do not proceed until the user tells you what they want.
@@ -26,7 +26,7 @@ Each one is self-contained and named for the job it does. If you're not sure wha
 
 | Skill | What it does |
 |---|---|
-| [`sentry-create-alert`](skills/sentry-create-alert/SKILL.md) | Create Sentry alerts using the workflow engine API. Use when asked to create alerts, set up notifications, configure issue priority alerts, or build workflow automations. Supports email, Slack, PagerDuty, Discord, and other notification actions. |
+| [`sentry-create-monitor`](skills/sentry-create-monitor/SKILL.md) | Create and edit Sentry monitors and the alerts that act on them — metric monitors with fixed, percentage-change, or anomaly-detection thresholds, uptime monitors, cron monitors, mobile app-size monitors, and alerts that notify Slack, email, PagerDuty, Discord, or open a Jira/GitHub ticket. Use when asked to monitor a metric or an endpoint's uptime, set up an alert or notification, change a threshold, route issues to a channel, or list and disable existing monitors and alerts. |
 | [`sentry-debug-issue`](skills/sentry-debug-issue/SKILL.md) | Debug and fix a Sentry issue — find it (by link, ID, or search), pull full context (stack trace, breadcrumbs, trace, logs), optionally run Seer root-cause / autofix, apply the code fix, and resolve it via a `Fixes PROJECT-NAME-12A` commit/PR. Use when working a known error or hunting one down to fix. |
 | [`sentry-fix-stack-traces`](skills/sentry-fix-stack-traces/SKILL.md) | Make Sentry stack traces readable — upload source maps for JavaScript/TypeScript, or debug files for native and mobile (dSYM, ProGuard/R8, NDK symbols, Dart obfuscation maps, .NET PDBs). Use when frames in Sentry show minified names, bundled paths, hex addresses, "unknown", or method names with no file/line, instead of your original source. |
 | [`sentry-get-started`](skills/sentry-get-started/SKILL.md) | Guided entry point for using Sentry through your agent. Orients you to your current setup and, for a new project, sets up Sentry end to end with sane defaults — provision a project, install the SDK (errors, tracing, and whatever it enables by default), and confirm real telemetry reaches Sentry. Routes other intents (adding more signals, fixing issues) to the right skill. |

src/references/concepts/crons.md

@@ -43,6 +43,12 @@ a backup — and “it didn’t run” is as bad as “it crashed.”
   `ok`/`error`) detects *missed* but not *`max_runtime`* timeouts.
 - **Use a stable, descriptive slug** (`nightly-invoice-sync`, not `job-1`) — it’s the
   check-in key, so slug churn on every deploy orphans monitors.
+- **Two ways to declare the config.** The SDKs take a `monitor_config` alongside the
+  check-in and upsert the monitor from it, which keeps the schedule in version control
+  next to the job it describes — usually the one to prefer while instrumenting.
+  Otherwise create the monitor through the detectors API ([`monitors.md`](monitors.md)),
+  never the legacy `/organizations/{org}/monitors/` one.
+  Either way the monitor stays silent until check-ins arrive.
 
 ## Related
 

src/references/concepts/monitors.md

@@ -13,11 +13,27 @@ Monitors detect; Alerts respond.
 They’re configured independently: one alert can watch many monitors/projects, and one
 monitor can feed several alerts.
 
-> Terminology: this model uses **Metric Monitor** for the detection stage and reserves
-> **Alert** for the response stage.
-> Older docs and integrations still say “metric **alert**” for the same detection
-> concept — treat them as the same thing; the rename isn’t fully settled across the
-> product.
+## Naming — the product and the API disagree
+
+The API kept the engine’s original vocabulary while the product settled on this one.
+Every mismatch below shows up in something you will read — a URL, a response body, an
+API reference page, an older doc — so learn them before touching the API:
+
+- **A Monitor is a `detector` in the API.** The endpoints are
+  `/organizations/{org}/detectors/`, and every monitor type is one: `metric_issue`,
+  `uptime_domain_failure`, `monitor_check_in_failure` (cron), `preprod_size_analysis`
+  (mobile builds), plus the auto-created `error` and `issue_stream`. The API reference
+  files these pages under “Monitors & Alerts” while every URL in them says `detectors`.
+- **`/organizations/{org}/monitors/` is the legacy Crons API — don’t use it.** It is the
+  path you would guess from the word “monitor,” it predates this model, and it reaches
+  cron monitors alone.
+  Those same cron monitors are detectors, so `/detectors/` manages them along with every
+  other type.
+- **An Alert is a `workflow` in the API** — `/organizations/{org}/workflows/`, named for
+  the workflow engine that evaluates it.
+- **“Metric alert” means Metric Monitor.** Older docs and integrations use the old name
+  for the detection stage; treat them as the same thing.
+  The rename isn’t fully settled across the product.
 
 ## Monitors — when a signal becomes an issue
 
@@ -61,14 +77,30 @@ An alert is **sources → triggers → filters → actions**:
 
 ## Coverage honesty
 
-Alert creation is automatable via Sentry’s workflow-engine API; several monitor types
-(uptime, dashboards) are heavier UI/API hand-offs today — be upfront about what the
-agent can do end-to-end vs.
-where it walks the user through the UI. The MCP is **read-only** here: it can inspect
-alert rules (`find_alert_rules`, `get_alert_rule`), cron monitors and their check-ins
-(`find_monitors`, `get_monitor_details`), and dashboards — useful for verifying after
-creation — but there is no create or update path for any of them, and uptime monitors
-have no MCP surface at all.
+Alerts and **every custom monitor type** are creatable and editable end-to-end through
+Sentry’s workflow-engine API — metric, uptime, cron, and mobile builds monitors are all
+detectors there.
+Only the metric payload has an API reference page, so building the other
+three means mirroring the shape of an existing monitor of that type; the accepted types
+also depend on what is enabled for the organization.
+
+Two things the API alone doesn’t finish.
+A **Cron Monitor** is inert until the job sends check-ins, which is instrumentation work
+— and because the SDKs upsert a monitor from the `monitor_config` they send with a
+check-in, a cron monitor can be defined entirely from code, keeping the schedule in
+version control beside the job it describes.
+**Uptime** and **Cron** monitors also consume a seat, so on an org with none free they
+are created **disabled** rather than rejected.
+
+**Uptime monitors are the exception to reaching for the API at all** — the MCP creates,
+updates and deletes them directly (`create_uptime_monitor` and friends), which needs no
+auth token and no hand-built payload.
+For everything else the MCP is read-only: it inspects alert rules (`find_alert_rules`,
+`get_alert_rule`), cron monitors and their check-ins (`find_monitors`,
+`get_monitor_details`), and uptime check results (`get_uptime_monitor_details`) — useful
+for verifying after creation, but with no create or update path.
+Note that the alert-rule tools return **legacy** rule IDs, which are not detector or
+workflow IDs.
 
 ## Related