devhelmhq · caballeto · Aug 23, 2026 · Aug 23, 2026 · Aug 23, 2026
diff --git a/docs/openapi/monitoring-api.json b/docs/openapi/monitoring-api.json
diff --git a/scripts/generate-skill-references.mjs b/scripts/generate-skill-references.mjs
@@ -51,6 +51,7 @@ const RESOURCES = {
  'status-pages': { singular: 'StatusPage' },
  'status-page-components': { singular: 'StatusPageComponent' },
  'status-page-incidents': { singular: 'StatusPageIncident' },
+ 'status-page-maintenance': { singular: 'StatusPageMaintenance' },
  'status-page-subscribers': { singular: 'StatusPageSubscriber' },
  'status-page-domains': { singular: 'StatusPageDomain' },
  },

diff --git a/skills/devhelm-communicate/SKILL.md b/skills/devhelm-communicate/SKILL.md
@@ -124,9 +124,12 @@ Ask which one if ambiguous.
 - **Existing auto-created incident** (from a monitor going down):
  list recent ones with `devhelm status-pages incidents list
  <page-id>` and ask the user which to post under.
-- **New manual incident**: create with `devhelm status-pages incidents
- create <page-id> ...` (planned maintenance, external provider
- outages, etc.).
+- **New incident**: create with `devhelm status-pages incidents
+ create <page-id> ...` for outages monitors can't detect
+ (external provider outages, etc.).
+- **Maintenance window**: schedule with
+ `devhelm status-pages maintenance create <page-id> ...`.
+ Do not use incident create for planned work.
 
 **Step 3 — Compose the update.**
 

diff --git a/skills/devhelm-communicate/references/_generated/status-page-components.fields.md b/skills/devhelm-communicate/references/_generated/status-page-components.fields.md
@@ -9,13 +9,14 @@
 |---|---|---|---|---|
 | `name` | string | ✓ | | Component display name |
 | `description` | string | | ✓ | Optional description shown on expand |
-| `type` | "MONITOR" \| "GROUP" \| "STATIC" | ✓ | | Component type: MONITOR, GROUP, or STATIC |
+| `type` | "MONITOR" \| "GROUP" \| "STATIC" \| "DEPENDENCY" | ✓ | | Component type: MONITOR, GROUP, STATIC, or DEPENDENCY |
 | `monitorId` | string (uuid) | | ✓ | Monitor ID (required when type=MONITOR) |
 | `resourceGroupId` | string (uuid) | | ✓ | Resource group ID (required when type=GROUP) |
+| `serviceSubscriptionId` | string (uuid) | | ✓ | Service subscription (Dependency) ID — required when type=DEPENDENCY. Bind an existing org subscription; catalog picks must create the subscription first, then pass its id |
 | `groupId` | string (uuid) | | ✓ | Component group ID for visual grouping |
-| `showUptime` | boolean | | ✓ | Whether to show the uptime bar (default: true) |
+| `showUptime` | boolean | | ✓ | Whether to show the uptime bar (default: true; false for DEPENDENCY) |
 | `displayOrder` | integer (int32) | | ✓ | Position in the component list |
-| `excludeFromOverall` | boolean | | ✓ | Exclude from overall status calculation (default: false, use true for third-party deps) |
+| `excludeFromOverall` | boolean | | ✓ | Exclude from overall status calculation (default: false; true for DEPENDENCY) |
 | `startDate` | string (date) | | ✓ | Date from which to start showing uptime; defaults to component creation. Set earlier to backdate (e.g. launch day); clamped at the monitor's createdAt for MONITOR-type components |
 
 ## `UpdateStatusPageComponentRequest`
@@ -43,7 +44,14 @@
 | `type` | string | ✓ | | |
 | `monitorId` | string (uuid) | | ✓ | |
 | `resourceGroupId` | string (uuid) | | ✓ | |
-| `currentStatus` | string | ✓ | | |
+| `serviceSubscriptionId` | string (uuid) | | ✓ | Service subscription (Dependency) id when type=DEPENDENCY |
+| `serviceSlug` | string | | ✓ | Slug of the subscribed catalog service (denormalized for display) |
+| `serviceName` | string | | ✓ | Display name of the subscribed catalog service (denormalized for display) |
+| `currentStatus` | string | ✓ | | Effective display status (incident > active override > binding) |
+| `overrideStatus` | string | | ✓ | Active timed override status; null when unset or expired |
+| `overrideReason` | string | | ✓ | Optional operator reason for the active override |
+| `overrideExpiresAt` | string (date-time) | | ✓ | When the active override expires; null when unset or expired |
+| `overrideActor` | integer (int32) | | ✓ | User id who set the override; null for API-key actors or when inactive |
 | `showUptime` | boolean | ✓ | | |
 | `displayOrder` | integer (int32) | ✓ | | |
 | `pageOrder` | integer (int32) | ✓ | | |

diff --git a/skills/devhelm-communicate/references/_generated/status-page-incidents.fields.md b/skills/devhelm-communicate/references/_generated/status-page-incidents.fields.md
@@ -12,11 +12,8 @@
 | `impact` | "NONE" \| "MINOR" \| "MAJOR" \| "CRITICAL" | ✓ | | Impact level: NONE, MINOR, MAJOR, or CRITICAL |
 | `body` | string | ✓ | | Initial update body in markdown |
 | `affectedComponents` | AffectedComponent[] | | ✓ | Component IDs affected by this incident |
-| `scheduled` | boolean | | ✓ | Whether this is a scheduled maintenance (default: false) |
-| `scheduledFor` | string (date-time) | | ✓ | Maintenance start time (required when scheduled=true) |
-| `scheduledUntil` | string (date-time) | | ✓ | Maintenance end time |
-| `autoResolve` | boolean | | ✓ | Auto-resolve at scheduledUntil (default: false) |
 | `notifySubscribers` | boolean | | ✓ | Whether to email confirmed subscribers about this incident (default: true) |
+| `monitoringIncidentId` | string (uuid) | | ✓ | Monitoring incident ID to link this status page incident to; null for standalone |
 
 ## `UpdateStatusPageIncidentRequest`
 
@@ -28,6 +25,10 @@
 | `affectedComponents` | AffectedComponent[] | | ✓ | Updated affected components; null preserves current |
 | `postmortemBody` | string | | ✓ | Postmortem body in markdown; empty string clears |
 | `postmortemUrl` | string | | ✓ | URL to an external postmortem document; empty string clears |
+| `published` | boolean | | ✓ | Whether the incident is published on the public page; null preserves current. true publishes (sets publishedAt); false unpublishes (clears publishedAt) |
+| `scheduledFor` | string (date-time) | | ✓ | New maintenance window start; null preserves current. Only for scheduled incidents |
+| `scheduledUntil` | string (date-time) | | ✓ | New maintenance window end; null preserves current. Only for scheduled incidents |
+| `autoResolve` | boolean | | ✓ | Whether the window auto-completes at scheduledUntil; null preserves current |
 
 ## `StatusPageIncidentDto` (response shape)
 

diff --git a/skills/devhelm-communicate/references/_generated/status-page-maintenance.fields.md b/skills/devhelm-communicate/references/_generated/status-page-maintenance.fields.md
@@ -0,0 +1,19 @@
+# status-page-maintenance — field reference
+
+> Auto-generated from the DevHelm OpenAPI spec. Do not edit by hand.
+> Regenerate with `node scripts/generate-skill-references.mjs`.
+
+## `CreateStatusPageMaintenanceRequest`
+
+| Field | Type | Required | Nullable | Description |
+|---|---|---|---|---|
+| `title` | string | ✓ | | Customer-facing maintenance title |
+| `status` | "INVESTIGATING" \| "IDENTIFIED" \| "MONITORING" \| "RESOLVED" | | ✓ | Initial status (default: INVESTIGATING) |
+| `impact` | "NONE" \| "MINOR" \| "MAJOR" \| "CRITICAL" | ✓ | | Impact level: NONE, MINOR, MAJOR, or CRITICAL |
+| `body` | string | ✓ | | Initial update body in markdown |
+| `affectedComponents` | AffectedComponent[] | | ✓ | Component IDs affected by this window |
+| `scheduledFor` | string (date-time) | ✓ | | Maintenance start time |
+| `scheduledUntil` | string (date-time) | | ✓ | Maintenance end time |
+| `autoResolve` | boolean | | ✓ | Auto-resolve at scheduledUntil (default: false) |
+| `notifySubscribers` | boolean | | ✓ | Whether to email confirmed subscribers about this window (default: true) |
+
diff --git a/skills/devhelm-communicate/references/_generated/status-page-subscribers.fields.md b/skills/devhelm-communicate/references/_generated/status-page-subscribers.fields.md
@@ -7,8 +7,12 @@
 
 | Field | Type | Required | Nullable | Description |
 |---|---|---|---|---|
-| `id` | string (uuid) | ✓ | | |
-| `email` | string | ✓ | | |
-| `confirmed` | boolean | ✓ | | |
-| `createdAt` | string (date-time) | ✓ | | |
+| `id` | string (uuid) | ✓ | | Subscriber id |
+| `email` | string | | ✓ | Email when channel is EMAIL; null for other channels |
+| `channel` | string | ✓ | | Delivery channel (EMAIL, SMS, WEBHOOK) |
+| `destination` | string | ✓ | | Channel destination (email, phone, or webhook URL) |
+| `componentIds` | string (uuid)[] | | ✓ | Scoped component IDs; null means whole page |
+| `confirmed` | boolean | ✓ | | Whether the subscriber has confirmed opt-in |
+| `confirmationSent` | boolean | | ✓ | True when this call sent a confirmation email; omitted on list reads |
+| `createdAt` | string (date-time) | ✓ | | When the subscriber was created |
 
diff --git a/skills/devhelm-communicate/references/_generated/status-pages.fields.md b/skills/devhelm-communicate/references/_generated/status-pages.fields.md
@@ -45,6 +45,7 @@
 | `componentCount` | integer (int32) | | ✓ | |
 | `subscriberCount` | integer (int64) | | ✓ | |
 | `overallStatus` | string | | ✓ | |
+| `openIncident` | any | | ✓ | |
 | `managedBy` | string | | ✓ | Source that created/owns this status page: DASHBOARD, CLI, TERRAFORM, MCP, or API. Null on pages created before this attribution column existed. |
 | `createdAt` | string (date-time) | ✓ | | |
 | `updatedAt` | string (date-time) | ✓ | | |

diff --git a/skills/devhelm-communicate/references/incidents.md b/skills/devhelm-communicate/references/incidents.md
@@ -10,8 +10,8 @@ Two flavors:
 - **Auto-created**: a monitor tied to a status page component went
  DOWN; DevHelm opened a public incident automatically. The user can
  edit/update it.
-- **Manual**: the user creates one for scheduled maintenance or
-vendor-side outages that monitors can't detect.
+- **Manual**: the user creates one for outages monitors can't detect.
+Planned work is a separate resource — see Maintenance below.
 
 ## List on a page
 
@@ -24,21 +24,36 @@ devhelm status-pages incidents get <incident-id>
 
 ```bash
 devhelm status-pages incidents create <page-id> \
- --title="Scheduled maintenance — DB upgrade" \
- --status=SCHEDULED \
- --scheduled-start=2026-05-01T02:00:00Z \
- --scheduled-end=2026-05-01T03:00:00Z \
- --affected-components=<comp_id1>,<comp_id2> \
- --body="Database upgrade. Expect 5-10m of read-only mode."
+ --title="API outage" \
+ --impact=MAJOR \
+ --status=INVESTIGATING \
+ --body="Investigating elevated 5xx on the public API."
 ```
 
-### Incident kinds
+`--scheduled` is rejected. Planned work goes on the maintenance resource.
 
-| Kind | Use | Required fields |
-|---|---|---|
-| `REAL_TIME` | Something is broken right now | `status=INVESTIGATING`, `body` |
-| `SCHEDULED` | Upcoming planned work | `scheduled_start`, `scheduled_end`, `body` |
-| `HISTORICAL` | Retrospective entry for an outage already over | `status=RESOLVED`, `body` with timeline |
+## Maintenance windows
+
+```bash
+devhelm status-pages maintenance create <page-id> \
+ --title="Database upgrade" \
+ --impact=MINOR \
+ --body="Read-only for 30 minutes." \
+ --scheduled-for=2026-05-01T02:00:00Z \
+ --scheduled-until=2026-05-01T03:00:00Z
+
+devhelm status-pages maintenance list <page-id>
+devhelm status-pages maintenance get <page-id> <window-id>
+devhelm status-pages maintenance update <page-id> <window-id> --status=MONITORING
+devhelm status-pages maintenance post-update <page-id> <window-id> \
+ --body="Halfway through." --status=MONITORING
+devhelm status-pages maintenance publish <page-id> <window-id>
+devhelm status-pages maintenance dismiss <page-id> <window-id>
+devhelm status-pages maintenance delete <page-id> <window-id>
+```
+
+`@_generated/status-page-maintenance.fields.md`. Runtime pull:
+`devhelm skills schema status-page-maintenance`.
 
 ## Update an incident (post an update)
 
@@ -51,12 +66,14 @@ devhelm status-pages incidents updates create <incident-id> \
 
 Valid status values:
 
-- `SCHEDULED` → upcoming maintenance
 - `INVESTIGATING` → just started, cause unknown
 - `IDENTIFIED` → cause known, fix in progress
 - `MONITORING` → fix applied, watching
 - `RESOLVED` → over
 
+Window timing belongs on the maintenance resource
+(`status-pages maintenance create` / `update`), not incident status.
+
 Each update is appended to the incident; the page shows the full
 timeline.
 

diff --git a/skills/devhelm-communicate/references/status-pages.md b/skills/devhelm-communicate/references/status-pages.md
@@ -97,11 +97,13 @@ Two sources:
 
 - **Auto-created** — from monitor failures.
 - **Manual** — `devhelm status-pages incidents create <page-id> ...`
- for maintenance windows, vendor-side outages, etc.
+ for outages monitors can't detect.
 
-Both are rendered in the same section. Manual incidents need an
-explicit resolve; auto-created ones resolve when the underlying
-monitor returns to UP.
+Do **not** use incident create for planned work. Schedule a window
+with `devhelm status-pages maintenance create <page-id> ...`.
+
+Manual incidents need an explicit resolve; auto-created ones resolve
+when the underlying monitor returns to UP.
 
 ## Complete field reference
 

diff --git a/skills/devhelm-configure/references/_generated/alert-channels.fields.md b/skills/devhelm-configure/references/_generated/alert-channels.fields.md
@@ -18,6 +18,7 @@
 | `name` | string | ✓ | | New channel name (full replacement, not partial update) |
 | `config` | any | ✓ | | |
 | `managedBy` | "DASHBOARD" \| "CLI" \| "TERRAFORM" \| "MCP" \| "API" | | ✓ | New attribution source: DASHBOARD, CLI, TERRAFORM, MCP, or API; null preserves current value. |
+| `enabled` | boolean | | ✓ | Whether this channel is enabled (default: true); null preserves current value |
 
 ## `AlertChannelDto` (response shape)
 
@@ -27,6 +28,7 @@
 | `name` | string | ✓ | | Human-readable channel name |
 | `channelType` | string | ✓ | | Channel integration type (e.g. SLACK, PAGERDUTY, EMAIL) |
 | `displayConfig` | any | | ✓ | |
+| `enabled` | boolean | ✓ | | Whether this channel is enabled and will receive alerts |
 | `createdAt` | string (date-time) | ✓ | | Timestamp when the channel was created |
 | `updatedAt` | string (date-time) | ✓ | | Timestamp when the channel was last updated |
 | `configHash` | string | | ✓ | SHA-256 hash of the channel config; use for change detection |

diff --git a/skills/devhelm-configure/references/_generated/monitors.fields.md b/skills/devhelm-configure/references/_generated/monitors.fields.md
@@ -8,7 +8,7 @@
 | Field | Type | Required | Nullable | Description |
 |---|---|---|---|---|
 | `name` | string | ✓ | | Human-readable name for this monitor |
-| `type` | "HTTP" \| "DNS" \| "MCP_SERVER" \| "TCP" \| "ICMP" \| "HEARTBEAT" | ✓ | | Monitor protocol type |
+| `type` | "HTTP" \| "DNS" \| "MCP_SERVER" \| "TCP" \| "ICMP" \| "HEARTBEAT" \| "BROWSER" \| "MULTI_STEP_API" | ✓ | | Monitor protocol type |
 | `config` | any | ✓ | | |
 | `frequencySeconds` | integer (int32) | | ✓ | Check frequency in seconds (10–86400); null defaults to plan minimum (60s on most paid plans) |
 | `enabled` | boolean | | ✓ | Whether the monitor is active (default: true) |

diff --git a/skills/devhelm-configure/references/_generated/notification-policies.fields.md b/skills/devhelm-configure/references/_generated/notification-policies.fields.md
@@ -8,6 +8,7 @@
 | Field | Type | Required | Nullable | Description |
 |---|---|---|---|---|
 | `name` | string | ✓ | | Human-readable name for this policy |
+| `description` | string | | ✓ | Optional note; omit or null when unused |
 | `matchRules` | MatchRule[] | | ✓ | Match rules to evaluate (all must pass; omit or empty for catch-all) |
 | `escalation` | EscalationChain | ✓ | | |
 | `enabled` | boolean | | ✓ | Whether this policy is enabled (default true) |
@@ -18,6 +19,7 @@
 | Field | Type | Required | Nullable | Description |
 |---|---|---|---|---|
 | `name` | string | | ✓ | Human-readable name for this policy; null preserves current |
+| `description` | string | | ✓ | New note; null preserves current, empty string clears |
 | `matchRules` | MatchRule[] | | ✓ | Match rules to evaluate (all must pass; omit or empty for catch-all) |
 | `escalation` | any | | ✓ | |
 | `enabled` | boolean | | ✓ | Whether this policy is enabled; null preserves current |
@@ -30,10 +32,15 @@
 | `id` | string (uuid) | ✓ | | Unique notification policy identifier |
 | `organizationId` | integer (int32) | ✓ | | Organization this policy belongs to |
 | `name` | string | ✓ | | Human-readable name for this policy |
+| `description` | string | | ✓ | Optional note; null when unset |
 | `matchRules` | MatchRule[] | ✓ | | Match rules (all must pass; empty = catch-all) |
 | `escalation` | EscalationChain | ✓ | | |
 | `enabled` | boolean | ✓ | | Whether this policy is active |
 | `priority` | integer (int32) | ✓ | | Evaluation order; higher value = evaluated first |
 | `createdAt` | string (date-time) | ✓ | | Timestamp when the policy was created |
 | `updatedAt` | string (date-time) | ✓ | | Timestamp when the policy was last updated |
+| `stats7d` | any | | ✓ | |
+| `stats30d` | any | | ✓ | |
+| `lastFiredAt` | string (date-time) | | ✓ | Created-at of the most recent dispatch for this policy; null if never fired |
+| `lastFiredIncidentId` | string (uuid) | | ✓ | Incident id of the most recent dispatch; null if never fired |
 
diff --git a/skills/devhelm-configure/references/_generated/resource-groups.fields.md b/skills/devhelm-configure/references/_generated/resource-groups.fields.md
@@ -8,7 +8,7 @@
 | Field | Type | Required | Nullable | Description |
 |---|---|---|---|---|
 | `name` | string | ✓ | | Human-readable name for this group |
-| `description` | string | | ✓ | Optional description |
+| `description` | string | | ✓ | Optional description (max 500) |
 | `alertPolicyId` | string (uuid) | | ✓ | Optional notification policy to apply for this group |
 | `defaultFrequency` | integer (int32) | | ✓ | Default check frequency in seconds applied to members (30–86400) |
 | `defaultRegions` | string[] | | ✓ | Default regions applied to member monitors |
@@ -27,7 +27,7 @@
 | Field | Type | Required | Nullable | Description |
 |---|---|---|---|---|
 | `name` | string | ✓ | | Human-readable name for this group |
-| `description` | string | | ✓ | Optional description; null clears the existing value |
+| `description` | string | | ✓ | Optional description (max 500); null clears the existing value |
 | `alertPolicyId` | string (uuid) | | ✓ | Optional notification policy to apply for this group; null clears the existing value |
 | `defaultFrequency` | integer (int32) | | ✓ | Default check frequency in seconds for members (30–86400); null clears |
 | `defaultRegions` | string[] | | ✓ | Default regions for member monitors; null clears |
@@ -63,6 +63,8 @@
 | `recoveryCooldownMinutes` | integer (int32) | | ✓ | Cooldown minutes after group incident resolves before a new one can open |
 | `health` | ResourceGroupHealthDto | ✓ | | |
 | `members` | ResourceGroupMemberDto[] | | ✓ | Member list with individual statuses; populated on detail GET only |
+| `deleteBlockedBy` | ResourceGroupDeleteBlockerDto[] | | ✓ | Status-page GROUP components that reference this group (delete blockers / public exposure); populated on detail GET only — omitted on list |
+| `openRegionIncident` | any | | ✓ | |
 | `managedBy` | string | | ✓ | Source that created/owns this group: DASHBOARD, CLI, TERRAFORM, MCP, or API. Null on groups created before this attribution column existed. |
 | `createdAt` | string (date-time) | ✓ | | Timestamp when the group was created |
 | `updatedAt` | string (date-time) | ✓ | | Timestamp when the group was last updated |